Deprecated: This field will be removed in a future API version. Use count to specify a number of payments instead.
Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
| | `app_fee` | string / integer | No | 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). | | `metadata` | object | No | 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. | | `retry_if_possible` | boolean | No | On failure, automatically retry payments using [intelligent retries](/success-plus/overview). 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).
| | `links` | object | No | | ### Responses | Status | Description | | --- | --- | | 201 | Resource created successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## List subscriptions `GET /subscriptions` Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your subscriptions. Please note if the subscriptions are related to customers who have been removed, they will not be shown in the response. ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Get a single subscription `GET /subscriptions/{subscription_id}` Retrieves the details of a single subscription. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `subscription_id` | path | string | Yes | The subscription id | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Update a subscription `PUT /subscriptions/{subscription_id}` Updates a subscription object. This fails with: - `validation_failed` if invalid data is provided when attempting to update a subscription. - `subscription_not_active` if the subscription is no longer active. - `subscription_already_ended` if the subscription has taken all payments. - `mandate_payments_require_approval` if the amount is being changed and the mandate requires approval. - `number_of_subscription_amendments_exceeded` error if the subscription amount has already been changed 10 times. - `forbidden` if the amount is being changed, and 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 - `resource_created_by_another_app` if the app fee is being changed, and the subscription was created by an app other than the app you are authenticated as ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `subscription_id` | path | string | Yes | The subscription id | ### Request body Wrap request body attributes in a `subscriptions` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | No | Optional name for the subscription. This will be set as the description on each payment created. Must not exceed 255 characters. | | `metadata` | object | No | 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. | | `payment_reference` | string | No | 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](#payments-create-a-payment) for more details.Restricted: You need your own Service User Number to specify a payment reference for Bacs payments.
| | `amount` | string / integer | No | Amount in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). | | `app_fee` | string / integer | No | 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). | | `retry_if_possible` | boolean | No | On failure, automatically retry payments using [intelligent retries](/success-plus/overview). 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).
| ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Pause a subscription `POST /subscriptions/{subscription_id}/actions/pause` 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](#subscriptions-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. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `subscription_id` | path | string | Yes | The subscription id | ### Request body Wrap request body attributes in a `subscriptions` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `pause_cycles` | integer | No | 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](#subscriptions-resume-a-subscription). For NZD subscriptions with `interval_unit: weekly` the minimum value is `2` because of the [mandatory minimum waiting period](#subscriptions-resume-a-subscription). | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Resume a subscription `POST /subscriptions/{subscription_id}/actions/resume` Resume a subscription object. Payments will start to be created again based on the subscriptions recurrence rules. The `charge_date` on the next payment will be the same as the subscriptions `earliest_charge_date_after_resume` 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 resume a subscription. - `subscription_not_paused` if the subscription is not paused. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `subscription_id` | path | string | Yes | The subscription id | ### Request body Wrap request body attributes in a `subscriptions` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Cancel a subscription `POST /subscriptions/{subscription_id}/actions/cancel` Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes. This will fail with a cancellation_failed error if the subscription is already cancelled or finished. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `subscription_id` | path | string | Yes | The subscription id | ### Request body Wrap request body attributes in a `subscriptions` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `metadata` | object | No | 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. | ### Responses | Status | Description | | --- | --- | | 200 | Action completed successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error |