Starts an unpaid or past-due plan over: ends it now and voids its outstanding invoices, then buys the same items from today. A payment that needs the customer comes back as `requires_payment`, like any first purchase.

POST

/billing/subscription/restart

curl --request POST \
  --url https://api.siteqwality.com/billing/subscription/restart \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "idempotency_key": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "stripe_subscription_id": "example" }'

• Production

Authorizations

• bearer_auth

Request Body ^required

Media type application/json

object

idempotency_key

required

Client-generated, stable across retries of one restart.

string format: uuid

stripe_subscription_id

required

The plan the preview showed.

string

Example ^generated

{
  "idempotency_key": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "stripe_subscription_id": "example"
}

Responses

200

Old plan ended; the new one is live or awaits payment

Media type application/json

object

status

required

updated (the new plan is live) or requires_payment (confirm client_secret).

string

stripe_subscription_id

string | null

client_secret

string | null

customer_session_client_secret

Lets the payment sheet offer the saved cards.

string | null

invoices_voided

required

integer format: int64

Example ^generated

{
  "status": "example",
  "stripe_subscription_id": "example",
  "client_secret": "example",
  "customer_session_client_secret": "example",
  "invoices_voided": 1
}

400

Malformed subscription id

401

Missing or invalid authentication

403

Caller has no billing role

409

The plan is not restartable, or another plan is live

500

Internal server error

503

An old invoice is still outstanding; retry with the same key