Apply a base-plan subscription change
POST/subscriptions/:subscription_id/change
Applies the same planner used by preview. Immediate positive proration must be committed by the provider before its authoritative subscription snapshot can replace the effective base plan. Immediate decreases create no refund or credit. Provider facts, not this mutation response, drive local grant projection. Idempotency-Key deduplicates the same request and supplies a stable provider operation identity. The service does not serialize different idempotency keys with a local command aggregate. An ambiguous provider result returns BILLING.PAYMENT_PROVIDER_OUTCOME_UNKNOWN; retrying the same key is delegated to a replay-safe provider adapter that uses native idempotency or inspect-before-retry reconciliation.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
- 503
Provider mutation accepted, scheduled, or committed.
Bad Request
Unauthorized
Forbidden (realm/account mismatch, billing account not derived from your session/principal, or insufficient role)
Not Found
Conflict (idempotency body mismatch, duplicate adjustment, or an unsupported provider capability). Unsupported mutations return BILLING.PAYMENT_PROVIDER_CAPABILITY_UNSUPPORTED before Customer creation, provider I/O, or local state mutation. Concurrent use of the same Idempotency-Key returns WRITE.IDEMPOTENCY_IN_PROGRESS; different keys are independent requests whose final ordering is owned by the PSP. A subscription Checkout with mixed group, currency, or recurrence facts is rejected before Customer lookup or provider I/O. Missing or inconsistent selected Customer bindings return BILLING.PAYMENT_PROVIDER_CUSTOMER_REQUIRED or BILLING.PAYMENT_PROVIDER_CUSTOMER_CONFLICT without silently replacing the binding.
Unprocessable Entity (validation, visibility, or binding/meter unresolved)
Rate limited
Response Headers
Seconds to wait before retry.
Internal Server Error
Provider unavailable, transient failure, or an ambiguous provider mutation reported as BILLING.PAYMENT_PROVIDER_OUTCOME_UNKNOWN.