Skip to main content
PUT
Update Subscription

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Path Parameters

provider_subscription_id
string
required

Provider subscription ID (e.g. test_subscription_id).

Body

application/json
discounts
object[]

Replaces the subscription-level discounts with the ones you send. An empty array removes all of them. Discounts on individual items are not affected; use items[].discounts for those. To keep a discount while changing the others, resend it as { "discount": "<its provider_discount_id>" }. Each entry must specify exactly one of coupon, promotion_code or discount. A blank or non-string member is ignored rather than rejected, so {"coupon": "", "promotion_code": "test_promotion_code_id"} is accepted as a promotion-code discount. Ids are trimmed before use. Changed: an empty array used to change nothing; it now removes every subscription-level discount, so omit the field to leave the discounts alone.

default_payment_method
string

Provider payment-method id (e.g. pm_...). Non-empty.

items
object[]

Non-empty. Each entry needs at least one of provider_item_id or provider_price_id; optional quantity (non-negative integer), deleted (boolean, used with provider_item_id to remove the item) and discounts (this item's discounts). After the change the subscription may hold at most one item: the count is the current items, minus entries with provider_item_id and deleted: true, plus entries without provider_item_id and without deleted: true. quantity: 0 does not remove an item. Checked only when items is sent, so a subscription that already holds several items can still change its other fields.

metadata
object

Free-form string key/value pairs. Merged, not replaced — keys you omit are preserved; send a key with an empty-string value to unset just that key. An empty {} clears nothing and does not count as an update, so metadata: {} on its own is a 400.

trial_end
integer

Unix timestamp in seconds; must be an integer in the future. Starts a trial ending at that instant and moves the subscription's billing anchor to it, so the next charge lands on that date instead of the original schedule — the way to push out a renewal when, say, a shipment was delayed. Valid on its own. Three consequences to know before calling it: (1) nothing is charged, though the provider does record a $0 invoice with a single “Trial period” line that will appear in GET /subscriptions/{provider_subscription_id}/invoices. (2) The subscription reports status: "trialing" until the date passes, so GET /subscriptions?status=active will not return it during that window — query status=trialing or status=all. (3) The anchor move is permanent: every later cycle bills on the new date, the original schedule does not resume. Combining it with items or discounts is allowed.

cancel_at

Moves or removes a scheduled cancel. A future unix timestamp in integer seconds, no later than the end of the current billing period, cancels at that instant (cancel_at_period_end: false); "period_end" cancels at the end of the current period (cancel_at_period_end: true); null removes any scheduled cancel, and is safe to send when nothing is scheduled. null counts as an update. Moving or removing a cancel creates no invoice and charges nothing. A timestamp after the current billing period ends is a 400: a cancel date in a later period would renew the subscription into a partial final period, which the payment provider always bills prorated. A date exactly at the period end is accepted and bills like "period_end", but reports cancel_at_period_end: false. A timestamp sent to a subscription with no upcoming renewal is a 400. When the same request changes the billing interval, a timestamp is checked against the end of the new period. A timestamp cannot be combined with trial_end (send trial_end first, then cancel_at in a separate request); "period_end" and null can. "now" is a 400: use DELETE /subscriptions/{provider_subscription_id} to cancel immediately. Needs the payment-subscriptions:update permission, not :cancel.

Response

Success.

data
object
required