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/${ORGANIZATION_ID}/subscription-pauses" \
  -H 'Content-Type: application/json' \
  -H "Authorization: ApiKey ${API_KEY}" \
  -d '{
    "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 canceled before it finished (subscription resumed early).
finishedPause ended 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/${ORGANIZATION_ID}/subscription-pauses/{pauseId}' \
  -H 'Authorization: ApiKey ${API_KEY}'

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

What happens during a pause​

While a subscription is paused, renewals do not run and no charges are issued. The subscription, customer, and payment instrument remain intact. The next charge date is recalculated when the pause ends.

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.