Buy an add-on, or move between tiers of one. Buying and moving to a pricier tier apply now; a cheaper tier waits for the period end.

POST

/billing/addons

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

• Production

Authorizations

• bearer_auth

Request Body ^required

Media type application/json

object

pack_id

required

string format: uuid

billing_interval

required

"month" or "year".

string

idempotency_key

required

Client-generated, stable across retries of ONE confirm attempt.

This is what makes a double-click safe: the same value twice is one Stripe mutation. A client that omits it gets no protection, which is why it is required rather than optional here (unlike change-plan, which has to keep accepting bodies from already-cached bundles).

string format: uuid

Example ^generated

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

Responses

200

Add-on bought or upgraded (now), cheaper tier scheduled for period end, or payment required

Media type application/json

object

success

required

Retained for symmetry with change-plan, whose older clients read it.

boolean

status

required

The same statuses as change-plan: "updated" when the change is live, "requires_payment" when the customer must confirm a payment first, "scheduled" for a cheaper tier (applied at effective_at), and "scheduled_change_cancelled" when re-picking the current tier cancelled a scheduled change.

string

client_secret

string | null

stripe_subscription_id

string | null

effective_at

For scheduled: when the change takes effect.

string | null format: date-time

Example ^generated

{
  "success": true,
  "status": "example",
  "client_secret": "example",
  "stripe_subscription_id": "example",
  "effective_at": "2026-04-15T12:00:00Z"
}

400

Invalid interval, unknown pack, pack is not an add-on, or already on that tier

401

Missing or invalid authentication

403

Caller is not a super admin

409

Account has no Stripe customer

500

Internal server error