Skip to main content
POST
Update Usage Cap
The cap is the most your app may charge the merchant for usage in one billing period. It starts at pricing.usage.cappedAmount and changes like Shopify’s capped-amount update:
  • Lowering it (or setting a first cap on an uncapped install) applies at once. It cannot go below the usage already accrued this period.
  • Raising it needs the merchant’s approval. The request is stored as pending and the response carries a confirmationUrl — a page in the merchant’s admin that shows the current and requested limit. The cap only changes when the merchant approves there. A new raise request replaces a pending one.
Scope: write_billing.

Request

number
required
The new cap in major units of the pricing currency (e.g. 40.25 = $40.25), rounded to two decimals. 0 stops further usage charges until the cap is raised again.
string
Where to send the merchant after they approve or decline. Used only when it is an https URL on your App URL’s origin or on the origin of one of your registered redirect URLs; otherwise the merchant stays in their admin.

Response — applied (lowering)

Response — approval required (raising)

Open confirmationUrl in the top-level window (from an embedded app, use the App Bridge Redirect action to the remote URL). While the request waits, GET /api/v1/billing/usage reports it as pendingCapAmountCents.

After the merchant decides

  • They are returned to returnUrl (when it passed the check above).
  • Your app receives an app_subscriptions/update webhook with reason: "usage_cap_approved" or "usage_cap_declined" and the resulting capAmountCents.
  • An approved cap applies to the next POST /api/v1/billing/usage call.

Errors

Errors use { "errors": { "base": ["…"] } }.