Change the renewal date
Moves the day the customer renews on, from now on. Nothing already invoiced changes. By default the next renewal bills a shortened period, from next_billing_date up to the day before the new renewal date, pro-rated by day against the full period it replaces; full periods then run from the new date. That change is pending until the next renewal invoice is raised, is shown in pending_renewal_change, and can be cancelled with DELETE until then. A second change replaces a pending one. With waive true, the days are not charged: the current invoice's period is extended to cover them and the new schedule applies at once, so nothing is pending. Send day for monthly, quarterly, six-monthly and yearly subscriptions, and date for weekly and 4-weekly ones. No email is sent to the customer; the renewal invoice describes the change. Fires subscription.renewal_date_changed.
Moves the day the customer renews on, from now on. Nothing already invoiced changes. By default the next renewal bills a shortened period, from next_billing_date up to the day before the new renewal date, pro-rated by day against the full period it replaces; full periods then run from the new date. That change is pending until the next renewal invoice is raised, is shown in pending_renewal_change, and can be cancelled with DELETE until then. A second change replaces a pending one. With waive true, the days are not charged: the current invoice's period is extended to cover them and the new schedule applies at once, so nothing is pending. Send day for monthly, quarterly, six-monthly and yearly subscriptions, and date for weekly and 4-weekly ones. No email is sent to the customer; the renewal invoice describes the change. Fires subscription.renewal_date_changed.
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 day or date. Which one the subscription needs depends on its cadence; sending the other is a 422 naming the field it needs.
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/renewal-date" \ -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" } ] }}Cancel a pending renewal date change DELETE
Withdraws a renewal date change that has not been billed yet. The subscription carries on renewing on its current day. Once the renewal invoice has been raised the change has already happened, and this returns 409. What can be withdrawn is decided by the waiting change itself, not by the subscription's status: a change parked before the agreement was paused or fell past due can still be taken back. Fires subscription.renewal_date_change_cancelled.
Create an agreement POST
Books the customer into the units named, as a `draft` agreement. Each unit is checked, under a lock, by the same rule every hold, booking and transfer uses: a unit that is archived, not in service (occupied, under maintenance, overlocked or unavailable), already booked, or held for someone else is refused with a 409 that says which, and nothing is created. A unit reserved for this same customer is not refused: the booking takes that reservation up, whether or not `reservation_id` names it. One agreement takes up at most one reservation, so a booking of two reserved units is refused (422) — book each on its own. Refusing held, archived and out-of-service units is a tightening made on 27 September 2026; such units were booked before.