Usual Docs
APIMCPOpenAPIllms.txt
View as Markdown

Pause everyone on a product

A product is out of stock for a month, or recalled. Pause every active subscription that includes it, then resume them when it's back.

1. Find them

bash
curl "https://regular-subs.fly.dev/api/v1/subscriptions?status=ACTIVE&productId=gid://shopify/Product/123&limit=100" \
  -H "Authorization: Bearer $USUAL_KEY"

Page through with nextCursor until it's null. total tells you how many there are before you start.

2. Preview one

bash
curl -X POST "https://regular-subs.fly.dev/api/v1/subscriptions/sub_123/pause?preview=true" \
  -H "Authorization: Bearer $USUAL_KEY" \
  -H "Content-Type: application/json" -d '{}'

A subscription with a payment going through right now, or one that's failing, can't be paused until that settles; the error says so.

3. Pause each one

bash
for id in $(cat subscription-ids.txt); do
  curl -s -X POST "https://regular-subs.fly.dev/api/v1/subscriptions/$id/pause" \
    -H "Authorization: Bearer $USUAL_KEY" \
    -H "Idempotency-Key: recall-2026-11-$id" \
    -H "X-Change-Reason: Cold Brew Pack recall" \
    -H "Content-Type: application/json" -d '{}'
done

The Idempotency-Key makes the loop safe to run again if it stops halfway. The X-Change-Reason shows up in the activity log, so anyone looking later knows why.

4. Resume when it's back

POST /subscriptions/{id}/resume for each. If a subscription's charge date passed while it was paused, its next delivery is tomorrow rather than a date in the past. Or undo each pause from the activity log.

With an AI agent

"Pause every active subscription for the Cold Brew Pack until the new batch arrives." Pausing is medium risk, so with an agent key each pause waits for someone at the store to approve it in Usual → Activity.