Usual Docs
APIMCPOpenAPIllms.txt
View as Markdown

Quickstart

Make your first call in three minutes: create a key, read the store, then preview and make a change.

1. Create a key

In Shopify admin, open Usual → Developers → Create key. Give it a name, choose API key (for your code) or Agent (for an AI agent), and pick only the permissions it needs. Copy the key: it's shown once.

bash
export USUAL_KEY="usk_..."

Keys look like usk_ followed by two random parts. We store only a hash of them. Revoke a key any time from the same page.

2. Read something

Start with the overview: whether everything is working, active subscribers, monthly recurring revenue and what's due this week.

bash
curl https://regular-subs.fly.dev/api/v1/overview \
  -H "Authorization: Bearer $USUAL_KEY"

Then find subscriptions. Filters combine:

bash
curl "https://regular-subs.fly.dev/api/v1/subscriptions?status=ACTIVE&nextBillingTo=2026-12-31T00:00:00Z&limit=10" \
  -H "Authorization: Bearer $USUAL_KEY"
json
{
  "subscriptions": [
    {
      "id": "cmw5ttqtk000axbrkeltlbrm5",
      "status": "ACTIVE",
      "nextBillingDate": "2026-12-15T14:00:00.000Z",
      "billing": { "every": 1, "interval": "MONTH" },
      "lines": [{ "title": "House Blend Coffee", "quantity": 2, "unitPrice": { "amount": "18.50", "currency": "USD" } }],
      "recurringTotal": { "amount": "41.99", "currency": "USD" }
    }
  ],
  "total": 1,
  "nextCursor": null
}

3. Preview a change

Add ?preview=true to any change to see exactly what it would do, without doing it:

bash
curl -X POST "https://regular-subs.fly.dev/api/v1/subscriptions/cmw5ttqtk000axbrkeltlbrm5/skip?preview=true" \
  -H "Authorization: Bearer $USUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
json
{
  "status": "planned",
  "plan": {
    "id": "cmw5u2...",
    "command": "subscriptions.skip_next",
    "diff": { "summary": "Skip the delivery on 2026-12-15; next one 2027-01-15.", "changes": [...] },
    "affected": 1,
    "status": "pending",
    "policy": { "outcome": "allow", "reasons": [] },
    "expiresAt": "2026-11-07T15:15:00.000Z",
    "nextStep": "Review the diff, then apply this plan by its id. It expires at expiresAt."
  }
}

4. Make it

Apply the plan exactly as previewed. If anything changed in the meantime, it's refused instead of doing something you didn't see:

bash
curl -X POST https://regular-subs.fly.dev/api/v1/plans/cmw5u2.../apply \
  -H "Authorization: Bearer $USUAL_KEY" \
  -H "Idempotency-Key: skip-cmw5ttqtk-2026-12"

Or skip the preview and make the change directly: the same request without ?preview=true. Either way it's recorded in the activity log with your key's name, and it can be undone.

Next