Skip to main content

Subscription pauses

You can temporarily pause a subscription. Pausing stops renewals from running while keeping the subscription, the customer, and the payment instrument intact. Resuming the pause picks up where the subscription left off.

A pause is a separate resource — it has its own ID and its own properties — and the same subscription can have multiple historical pauses over time.

Creating a pause​

curl -i -X POST \
  'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/subscription-pauses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: ApiKey <keyValue>' \
  -d '{
    "subscriptionId": "ord_xxx",
    "pausedBy":       "customer",
    "description":    "Going on holiday for the summer"
  }'

Once created, the pause moves through its own status: pending → ongoing → revoked or finished (see below).

Pause statuses​

StatusMeaning
pendingPause is created but has not yet taken effect (for example, a pause scheduled for the end of the current cycle).
ongoingPause is in effect — the subscription is currently paused.
revokedPause was resumed before its scheduled end.
finishedPause reached its scheduled end naturally.

Who paused it​

The pausedBy field records the actor: customer or merchant.

Resuming a pause​

To resume the subscription immediately, delete the pause:

curl -i -X DELETE \
  'https://staging-api.payments.ai/v1/public-api/organizations/:organizationId/subscription-pauses/{pauseId}' \
  -H 'Authorization: ApiKey <keyValue>'

The pause transitions to revoked and the subscription returns to active.

What happens during a pause​

Renewals do not run while the pause is ongoing. Confirm the resulting renewal schedule on the subscription after resuming.

Available operations​

MethodPath
POST/.../subscription-pauses (create)
GET/.../subscription-pauses (list) and /.../subscription-pauses/{id} (one)
PUT/.../subscription-pauses/{id} (update — for example, change the scheduled end)
DELETE/.../subscription-pauses/{id} (resume the subscription)

Pause rules​

A few constraints apply (see Subscription flow):

  • Only an active subscription can be paused.
  • A paused subscription cannot be canceled directly — resume the pause first.
  • Deleting the pause returns the subscription to active.