--- title: "Pause a subscription" method: POST path: "/subscriptions/{subscription_id}/actions/pause" tags: ["Subscription"] --- # Pause a subscription `POST /subscriptions/{subscription_id}/actions/pause` ## Request - Base URL: `https://api.gocardless.com` - URL: `https://api.gocardless.com/subscriptions/{subscription_id}/actions/pause` - Auth: HTTP bearer Pause a subscription object. No payments will be created until it is resumed. This can only be used when a subscription is collecting a fixed number of payments (created using `count`), when they continue forever (created without `count` or `end_date`) or the subscription is already paused for a number of cycles. When `pause_cycles` is omitted the subscription is paused until the [resume endpoint](https://docs.gocardless.com/docs/api-reference/subscription#resume-a-subscription) is called. If the subscription is collecting a fixed number of payments, `end_date` will be set to `null`. When paused indefinitely, `upcoming_payments` will be empty. When `pause_cycles` is provided the subscription will be paused for the number of cycles requested. If the subscription is collecting a fixed number of payments, `end_date` will be set to a new value. When paused for a number of cycles, `upcoming_payments` will still contain the upcoming charge dates. This fails with: - `forbidden` if the subscription was created by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app - `validation_failed` if invalid data is provided when attempting to pause a subscription. - `subscription_paused_cannot_update_cycles` if the subscription is already paused for a number of cycles and the request provides a value for `pause_cycle`. - `subscription_cannot_be_paused` if the subscription cannot be paused. - `subscription_already_ended` if the subscription has taken all payments. - `pause_cycles_must_be_greater_than_or_equal_to` if the provided value for `pause_cycles` cannot be satisfied.

Warning: Please note that any payments that have already been created from this subscription will still be collected unless you manually cancel them.

## Path parameters - `subscription_id` string, required ## Headers - `GoCardless-Version` string, required ## Request body - object - `subscriptions` object - `pause_cycles` integer, nullable: The number of cycles to pause a subscription for. A cycle is one duration of `interval` and `interval_unit`. This should be a non zero positive value. For AUD subscriptions with `interval_unit: weekly` the minimum value varies between `3` & `4` because of the [mandatory minimum waiting period](https://docs.gocardless.com/docs/api-reference/subscription#resume-a-subscription). For NZD subscriptions with `interval_unit: weekly` the minimum value is `2` because of the [mandatory minimum waiting period](https://docs.gocardless.com/docs/api-reference/subscription#resume-a-subscription). - `metadata` CustomerMetadata: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. ## Response `200` Action completed successfully - SubscriptionSingleResourceResponse - `subscriptions` Subscription: Subscriptions create [payments](https://docs.gocardless.com/docs/api-reference/payment) according to a schedule. ### Recurrence Rules The following rules apply when specifying recurrence: - If `day_of_month` and `start_date` are not provided `start_date` will be the [mandate](https://docs.gocardless.com/docs/api-reference/mandate)'s `next_possible_charge_date` and the subscription will then recur based on the `interval` & `interval_unit` - If `month` or `day_of_month` are present the following validations apply: | __interval_unit__ | __month__ | __day_of_month__ | | :---------------- | :--------------------------------------------- | :----------------------------------------- | | yearly | optional (required if `day_of_month` provided) | optional (invalid if `month` not provided) | | monthly | invalid | optional | | weekly | invalid | invalid | Examples: | __interval_unit__ | __interval__ | __month__ | __day_of_month__ | valid? | | :---------------- | :----------- | :-------- | :--------------- | :------------------------------------------------- | | yearly | 1 | january | -1 | valid | | monthly | 6 | | | valid | | monthly | 6 | | 12 | valid | | weekly | 2 | | | valid | | yearly | 1 | march | | invalid - missing `day_of_month` | | yearly | 1 | | 2 | invalid - missing `month` | | monthly | 6 | august | 12 | invalid - `month` must be blank | | weekly | 2 | october | 10 | invalid - `month` and `day_of_month` must be blank | ### Rolling dates When a charge date falls on a non-business day, one of two things will happen: - if the recurrence rule specified `-1` as the `day_of_month`, the charge date will be rolled __backwards__ to the previous business day (i.e., the last working day of the month). - otherwise the charge date will be rolled __forwards__ to the next business day. - `id` string: Unique identifier, beginning with "SB". - `created_at` string, date-time: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created. - `amount` integer: Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). - `name` string, nullable: Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters. - `start_date` string, date, nullable: The date on which the first payment should be charged. Must be on or after the [mandate](https://docs.gocardless.com/docs/api-reference/mandate)'s `next_possible_charge_date`. When left blank and `month` or `day_of_month` are provided, this will be set to the date of the first payment. If created without `month` or `day_of_month` this will be set as the mandate's `next_possible_charge_date` - `end_date` string, date, nullable: Date on or after which no further payments should be created.
If this field is blank and `count` is not specified, the subscription will continue forever.

Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.

- `interval` integer: Number of `interval_units` between customer charge dates. Must be greater than or equal to `1`. Must result in at least one charge date per year. Defaults to `1`. - `interval_unit` 'weekly' | 'monthly' | 'yearly': The unit of time between customer charge dates. One of `weekly`, `monthly` or `yearly`. - `day_of_month` integer, nullable: As per RFC 2445. The day of the month to charge customers on. `1`-`31` or `-1` to indicate the last day of the month. If the chosen day does not exist in a given month (e.g. `31` in April), the charge is made on the last day of that month. - `currency` string: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. - `month` 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december', nullable: Name of the month on which to charge a customer. Must be lowercase. Only applies when the interval_unit is `yearly`. - `count` integer, nullable: The total number of payments that should be taken by this subscription. - `payment_reference` string, nullable: An optional payment reference. This will be set as the reference on each payment created and will appear on your customer's bank statement. See the documentation for the [create payment endpoint](https://docs.gocardless.com/docs/api-reference/payment#create-a-payment) for more details.

Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.

- `metadata` CustomerMetadata: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. - `status` 'pending_customer_approval' | 'customer_approval_denied' | 'active' | 'finished' | 'cancelled' | 'paused': One of: - `pending_customer_approval`: the subscription is waiting for customer approval before becoming active - `customer_approval_denied`: the customer did not approve the subscription - `active`: the subscription is currently active and will continue to create payments - `finished`: all of the payments scheduled for creation under this subscription have been created - `cancelled`: the subscription has been cancelled and will no longer create payments - `paused`: the subscription has been paused and will not create payments - `upcoming_payments` object[]: Up to 10 upcoming payments with their amounts and charge dates. - `charge_date` string, date: The date on which this payment will be charged. - `amount` integer: The amount of this payment, in minor unit (e.g. pence in GBP, cents in EUR). - `app_fee` integer, nullable: The amount to be deducted from each payment as an app fee, to be paid to the partner integration which created the subscription, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). - `links` SubscriptionLinks - `mandate` string: ID of the associated [mandate](https://docs.gocardless.com/docs/api-reference/mandate) which the subscription will create payments against. - `retry_if_possible` boolean: On failure, automatically retry payments using [intelligent retries](https://docs.gocardless.com/docs/optimise/reduced-failed-payments-with-success-plus). Default is `false`.

Important: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus).

- `earliest_charge_date_after_resume` string, date, nullable: The earliest date that will be used as a `charge_date` on payments created for this subscription if it is resumed. Only present for `paused` subscriptions. This value will change over time. - `parent_plan_paused` boolean: Whether the parent plan of this subscription is paused. ## Other responses - `400`: Bad Request - `401`: Unauthorised - `404`: Not found - `422`: Validation Error - `500`: Internal Error --- [API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)