---
title: "Get a single subscription"
method: GET
path: "/subscriptions/{subscription_id}"
tags: ["Subscription"]
---

# Get a single subscription

`GET /subscriptions/{subscription_id}`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/subscriptions/{subscription_id}`
- Auth: HTTP bearer

Retrieves the details of a single subscription.

## Path parameters

- `subscription_id` string, required

## Headers

- `GoCardless-Version` string, required

## Response `200`

Successful response

- 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. <br /> If this field is blank and `count` is not specified, the subscription will continue forever. <br /> <p class="deprecated-notice"><strong>Deprecated</strong>: This field will be removed in a future API version. Use <code>count</code> to specify a number of payments instead.</p>
    - `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. <br /> <p class="restricted-notice"><strong>Restricted</strong>: You need your own Service User Number to specify a payment reference for Bacs payments.</p>
    - `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`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p>
    - `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)