Store APIsSubscriptions
Change subscription plan
Upgrades, downgrades, or re-prices a subscription (product, variant, interval, or quantity). Upgrades charge a prorated difference immediately; downgrades and end-of-period changes apply at the next renewal. Requires the SUBSCRIPTIONS_WRITE scope.
AuthorizationBearer <token>
Bearer token authentication. Pass the secret directly in the Authorization header. Token secrets start with sk_.
In: header
Path Parameters
storeId*string
Length
12 <= length <= 48subscriptionId*string
Length
12 <= length <= 48Header Parameters
idempotency-key?string
Length
8 <= length <= 32Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/stores/stringstring/subscriptions/stringstring/change" \ -H "Content-Type: application/json" \ -d '{}'{ "ok": true, "data": { "id": "sub_h7n4tr3bcfp2v8q1mzj0kxw5", "status": "ACTIVE", "billingInterval": "MONTHLY", "amount": 2900, "currency": "USD", "currentPeriodStart": "2026-05-14T12:34:56.000Z", "currentPeriodEnd": "2026-06-14T12:34:56.000Z", "nextChargeAt": "2026-06-14T12:34:56.000Z", "trialEnd": null, "cancelledAt": null, "pausedAt": null, "endsAt": null, "retryCount": 0, "product": { "id": "prd_8h4t6sqzy3x9w5n2k1m0vqbf", "title": "Pro Plan", "price": 2900 }, "customer": { "id": "cus_j8h0r1n4tzcbfp2v8q1mzwx5", "email": "buyer@example.com" }, "paymentMethod": { "id": "pmm_n4tr3bcfp2v8q1mzj0kxw5h7", "brand": "visa", "lastFour": "4242", "expMonth": 12, "expYear": 2030 }, "createdAt": "2026-05-14T12:34:56.000Z" }}