Update a subscription

Only the fields supplied are changed. On an active or past-due subscription, next_billing_date and anchor_day are refused with 409 subscription_renewal_date_endpoint, even when they carry the value the subscription already has: the renewal date moves through POST /subscriptions/{id}/renewal-date, which bills the days between the old and new dates. On a pending subscription, a next_billing_date on or before the end of a period already invoiced is refused with 409 conflict, and so is a new next_billing_date while cover or a repeating charge starts on the current next_billing_date or on the agreement's move_in_date: move the agreement's move_in_date instead, which moves them. While a renewal date change is pending (pending_renewal_change is set), a change to billing_interval or interval_count is refused with 409 conflict until the change is cancelled, because the pending change was worked out for the current cadence. On a subscription with no licence fee (one with no agreement, which bills only its repeating charges) a change to amount_minor is refused with 409 conflict: its price is the sum of those charges. A new billing_interval or interval_count re-prices every repeating charge and every cover the subscription bills from its next invoice, each converted afresh from the price it was converted from (a charge's own price, a cover's premium) and never from its old amount per period; amount_minor moves by what the next invoice then bills. The licence fee is not re-priced: an amount_minor sent with the new period moves it by the difference from the current amount_minor, and the re-pricing lands on top. A charge with no price of its own on a subscription billed every two or more intervals, or one that can't be priced for the new period, refuses the whole change with 409 conflict, and nothing is written. An amount_minor equal to the current one is no change. With expected_amount_minor, a change is refused with 409 conflict when the subscription's amount_minor is no longer that figure.

Authorization

AuthorizationBearer <token>

Present an API key (sb_live_… / sb_test_…), an OAuth2 access token, or a static token as a Bearer credential. The operator is implied by the credential; it is never in the path. Only a SHA-256 hash of an API key is stored server-side.

In: header

Path Parameters

id*string

UUIDv7 identifier of the resource.

Formatuuid

Header Parameters

Idempotency-Key?string

A unique key that makes this mutation safe to retry. Repeats replay the stored response; reuse with a different body returns 409 idempotency_conflict.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

All fields optional; only supplied fields are changed.

billing_interval?string

Value in

"week"
"month"
"4week"
"quarter"
"6month"
"year"

interval_count?integer

NOT NULL in the database (defaults to 1). Refused with 409 while a renewal date change is pending, like billing_interval.

amount_minor?integer

Recurring amount per interval, minor units. NOT NULL in the database.

Formatint64

expected_amount_minor?integer

The amount_minor this change was worked out against. amount_minor moves the licence fee by its difference from the subscription's amount as it stands when the request lands, so a charge or cover added meanwhile would land on the licence fee. When the amount is no longer this figure the change is refused with 409 conflict and nothing is written. Only with amount_minor (422 otherwise). Optional; send it whenever the subscription was read first.

Formatint64

Range0 <= value

anchor_day?|

Refused with 409 subscription_renewal_date_endpoint on an active or past-due subscription, whatever the value: use POST /subscriptions/{id}/renewal-date.

payment_method_id?|

The stored card this subscription's future invoices are collected from. It must belong to this subscription's own contact, be an active CARD carrying a provider token, and satisfy that provider's precondition for unattended collection (a Stripe card needs the contact's customer reference; a Global Payments card needs the scheme reference its first verification mints). Anything else is a 422 naming payment_method_id, with the reason as the field issue — binding an instrument that cannot be charged off-session produces a subscription that skips collection silently, writing no payment row and opening no dunning case. Send null to clear it.

Formatuuid

mandate_id?|

Formatuuid

default_rail?string

Value in

"bacs_dd"
"card"

next_billing_date?string

Driven by the billing timer. Refused with 409 subscription_renewal_date_endpoint on an active or past-due subscription, whatever the value: use POST /subscriptions/{id}/renewal-date, which bills the days between the old and new dates. There is no product reason to clear it independently of a status transition (pause and cancel have their own actions).

Formatdate

collection_waived?boolean

The occupier pays the operator some other way (bank transfer, standing order, cash): invoices are still raised, but StoreBay never attempts to collect them. Distinct from auto_collect, which is the CUSTOMER's own autopay preference. Setting it to false makes every already-open invoice on this subscription eligible for collection on the next sweep, which for a card subscription is an immediate charge of the accumulated balance.

customer_reference?|

The customer's PO/account number for future invoices. Trimmed; at most 60 characters; a blank string is refused — send null to clear it. Invoices already issued keep the reference they were stamped with (correct those through PATCH /invoices/{id}).

Lengthlength <= 60

Response Body

`application/json`

curl -X PATCH "https://example.com/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "object": "subscription",    "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8",    "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598",    "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",    "status": "pending",    "billing_interval": "week",    "interval_count": 0,    "currency": "str",    "amount_minor": 0,    "current_period_start": "2019-08-24",    "current_period_end": "2019-08-24",    "next_billing_date": "2019-08-24",    "anchor_day": 0,    "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a",    "mandate_id": "e98a8906-c5df-4f83-89a8-e8197c5fddcb",    "default_rail": "bacs_dd",    "auto_collect": true,    "collection_waived": true,    "customer_reference": "string",    "started_at": "2019-08-24T14:15:22Z",    "paused_at": "2019-08-24T14:15:22Z",    "cancelled_at": "2019-08-24T14:15:22Z",    "ended_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "pending_renewal_change": {      "bridge_start": "2019-08-24",      "bridge_end": "2019-08-24",      "new_period_start": "2019-08-24",      "new_anchor_day": 0,      "bridge_days": 0,      "bridge_amount_minor": 0    },    "promotion": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d",      "code": "string",      "name": "string",      "discount_kind": "percent",      "discount_value": 0,      "periods_total": 0,      "periods_applied": 0,      "source": "checkout",      "created_at": "2019-08-24T14:15:22Z"    }  }}

{  "error": {    "code": "unauthorized",    "message": "Missing or invalid credential."  }}

{  "error": {    "code": "insufficient_scope",    "message": "The credential lacks a scope required by this endpoint."  }}

{  "error": {    "code": "not_found",    "message": "Resource not found."  }}

{  "error": {    "code": "conflict",    "message": "The request conflicts with current resource state."  }}

{  "error": {    "code": "validation_error",    "message": "One or more fields are invalid.",    "details": [      {        "field": "email",        "issue": "must be a valid email address"      }    ]  }}

{  "error": {    "code": "rate_limited",    "message": "Rate limit exceeded. Retry after 7s."  }}

{  "error": {    "code": "validation_error",    "message": "string",    "details": [      {        "field": "string",        "issue": "string"      }    ]  }}

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`