Skip to main content
POST
Change a subscription's recurring amount

Authorizations

Authorization
string
header
required

Bearer credential for the public API: a live COPE API key (ck_live_*; keys issued earlier as cope_sk_live_* keep working). Dashboard sign-in tokens are not accepted.

Headers

Idempotency-Key
string
required

Required. At most 255 characters of valid UTF-8 with no NUL byte. The change attempt is recorded against this key for this subscription, and a retry that carries the same key and the same body does not change the subscription twice: it returns the subscription as it stands now. The exception is an attempt that failed at the payment provider or stopped responding: it is re-checked and then re-attempted. COPE also re-attempts, on its own, an attempt the payment provider did not confirm or that stopped responding, under the same re-check: usually within minutes, for up to 24 hours after it was recorded. The re-check asks whether subscription changes through the API are still enabled for the business and whether another change is still processing (change_in_flight: repeat under the same key once it settles); a price or plan change is also refused as not_active (final) once the subscription has ended and as superseded (final) when another price or plan change has been applied since it was recorded, and a pause, resume or cancel when the subscription has left the status it needs. A refusal of the first request under a key, change_in_flight included, is recorded against that key: once it settles, send the request again under a new key. The same key with a different body is refused with 409 idempotency_conflict.

Maximum string length: 255

Path Parameters

id
string
required

id public identifier.

Pattern: ^ps_[A-Za-z0-9]{8,32}$
Example:

"ps_A1b2C3d4E5f6"

Body

application/json
amount_cents
integer
required

The new recurring amount per unit in minor units, net or gross of tax as has_net_price says. What it bills, the tax included, must be at least 200 (2.00), and at most 99999900 (999,999.00) once multiplied by the quantity. Outside those bounds the change is refused with 422 subscription_not_eligible, errors[0].code invalid_recurring_amount. It bills from the next cycle, with no proration.

Required range: 200 <= x <= 99999900
currency
string

Optional. Checked against the subscription's billing currency, never applied: a different currency is refused with 422 subscription_not_eligible, errors[0].code currency_mismatch.

Pattern: ^[A-Za-z]{3}$
has_net_price
boolean

Optional. Whether amount_cents is net of tax (true: the tax is added on top) or includes it (false: the tax is taken out of it). Omit it to use the basis the subscription's terms are set in, its has_net_price. The tax is worked out at the rate the subscription was sold at. A value other than true or false is refused with 422 validation_failed.

reason
string

Optional. Recorded on the change attempt; longer than 500 characters is truncated.

Response

Successful response

data
object
required