Put a promotion on a subscription
Puts one of the operator's coupons on the subscription, by id or by code in any case. The coupon must be redeemable now and apply to the subscription's site and unit type; a staff-only coupon and a free period are allowed. From the next invoice, its discount comes off the licence fee of each invoice until its periods are used; a free period that covers a whole invoice raises no invoice for that period. A subscription carries one promotion at a time. Each use counts as one of the coupon's redemptions.
Puts one of the operator's coupons on the subscription, by id or by code in any case. The coupon must be redeemable now and apply to the subscription's site and unit type; a staff-only coupon and a free period are allowed. From the next invoice, its discount comes off the licence fee of each invoice until its periods are used; a free period that covers a whole invoice raises no invoice for that period. A subscription carries one promotion at a time. Each use counts as one of the coupon's redemptions.
Present an API key (sb_live_… / sb_test_…), an OAuth2 access token, or a static token as a Bearer credential. The operator is implied by the credential; it is never in the path. Only a SHA-256 hash of an API key is stored server-side.
In: header
Path Parameters
UUIDv7 identifier of the resource.
uuidHeader Parameters
A unique key that makes this mutation safe to retry. Repeats replay the stored response; reuse with a different body returns 409 idempotency_conflict.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Exactly one of coupon_id or code.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/promotion" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "object": "subscription", "agreement_id": "67dd069b-637c-4b8e-8d92-17a313d06fb8", "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598", "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811", "status": "pending", "billing_interval": "week", "interval_count": 0, "currency": "str", "amount_minor": 0, "current_period_start": "2019-08-24", "current_period_end": "2019-08-24", "next_billing_date": "2019-08-24", "anchor_day": 0, "payment_method_id": "ec18d2d7-d2e0-41e4-98e4-847f14422d8a", "mandate_id": "e98a8906-c5df-4f83-89a8-e8197c5fddcb", "default_rail": "bacs_dd", "auto_collect": true, "collection_waived": true, "customer_reference": "string", "started_at": "2019-08-24T14:15:22Z", "paused_at": "2019-08-24T14:15:22Z", "cancelled_at": "2019-08-24T14:15:22Z", "ended_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "pending_renewal_change": { "bridge_start": "2019-08-24", "bridge_end": "2019-08-24", "new_period_start": "2019-08-24", "new_anchor_day": 0, "bridge_days": 0, "bridge_amount_minor": 0 }, "promotion": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "coupon_id": "97ffaabb-eb3d-43ed-8769-a889d53b9a3d", "code": "string", "name": "string", "discount_kind": "percent", "discount_value": 0, "periods_total": 0, "periods_applied": 0, "source": "checkout", "created_at": "2019-08-24T14:15:22Z" } }}{ "error": { "code": "unauthorized", "message": "Missing or invalid credential." }}{ "error": { "code": "insufficient_scope", "message": "The credential lacks a scope required by this endpoint." }}{ "error": { "code": "not_found", "message": "Resource not found." }}{ "error": { "code": "validation_error", "message": "string", "details": [ { "field": "string", "issue": "string" } ] }}{ "error": { "code": "validation_error", "message": "One or more fields are invalid.", "details": [ { "field": "email", "issue": "must be a valid email address" } ] }}{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry after 7s." }}{ "error": { "code": "validation_error", "message": "string", "details": [ { "field": "string", "issue": "string" } ] }}