Subscriptions

Pause a subscription by Id

Changed on Oct 29, 2026

Used to schedule a pause for a Subscription. Only 'Active' subscriptions can be paused, though the details for already 'Paused' subscriptions can also be edited. The subscription will remain in 'Active' and will be moved to 'Paused' when it was next due to be billed. The reason or duration of the pause can be edited by calling this endpoint again, even after it has moved to 'Paused'. After a pause is scheduled but whilst still in 'Active', the pause can be unscheduled via the 'unschedule' flag.

patch/subscriptions/{subscriptionId}/pause

Request

Base URL
https://sandbox-api.ryftpay.com/v1
URL
https://sandbox-api.ryftpay.com/v1/subscriptions/{subscriptionId}/pause
Auth
API key in header Authorization

Path parameters

subscriptionIdstring required

Example:sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to pause

Request body

reasonstring nullable

Optional field describing why the subscription is being paused.

resumeAtTimestampnumber nullable

The epoch timestamp (seconds) when the subscription should resume collecting payments. If not specified, the subscription will remain paused indefinitely until a /resume API call is made.

unscheduleboolean nullable

A flag used to unschedule an already scheduled pause, resulting in the customer being billed as normal (as they were before). This can only be 'true' if the subscription is still 'Active', a pause has been scheduled and no other fields are provided. To resume an already 'Paused' subscription then either update the 'resumeAtTimestamp' or call /resume.

Example request

{
  "reason": "Offering service for free to customer",
  "resumeAtTimestamp": 1470989538
}

Response

The subscription was paused successfully

idstring

The ID of the subscription

descriptionstring nullable

(optional) description helps you personalise/identify the specific subscription

metadataobject nullable

use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata.

createdTimestampinteger

The epoch timestamp (seconds) when the subscription was created

Example response

{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": {
      "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
      "requiredAction": {
        "type": "Redirect",
        "url": "https://ryftpay.com/3ds-auth"
      }
    },
    "latest": {
      "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
      "requiredAction": {
        "type": "Redirect",
        "url": "https://ryftpay.com/3ds-auth"
      }
    }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": {
      "unit": "Months",
      "count": 1,
      "times": 12
    }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": {
      "paymentAttempts": 2,
      "lastPaymentError": "insufficient_funds"
    }
  },
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": {
      "descriptor": "Ryft Ltd",
      "city": "London"
    }
  },
  "createdTimestamp": 1470989538
}

Changes

Oct 29, 2026d73b6f121d8a Revision changes
- warning
  added the new 3ds_authentication_not_supported enum value to the // response property for the response status
- warning
  added the new authorisation_denied enum value to the // response property for the response status
- warning
  added the new in_person_terminal_action_cancelled enum value to the // response property for the response status
- warning
  added the new in_person_terminal_action_timeout enum value to the // response property for the response status
- warning
  added the new in_person_terminal_busy enum value to the // response property for the response status
- warning
  added the new in_person_terminal_not_available enum value to the // response property for the response status
- warning
  added the new payment_cancelled enum value to the // response property for the response status
- warning
  added the new recurring_series_terminated enum value to the // response property for the response status

Operation history