---
title: "Retrieve subscription"
method: GET
path: "/processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}"
tags: ["Subscriptions"]
---

# Retrieve subscription

`GET /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}`

Use this method to retrieve information about a subscription.  

To retrieve a subscription, you need its subscriptionId. You sent the subscriptionId in the request of the [Create subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) method.  

**Note:** If you don't have the subscriptionId, use our [List subscriptions](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/list) method to search for the subscription.  

Our gateway returns information about the following for the subscription:  

-	Payment plan the subscription is linked to.  
-	Secure token that represents cardholder’s payment details.  
-	Current state of the subscription, including its status, next due date, and invoices.  
-	Fees for setup and the cost of the recurring order.  
-	Subscription length, end date, and frequency.  

We also return the paymentPlanId and the secureTokenId, which you can use to perform follow-on actions.

## Path parameters

- `processingTerminalId` string, required
- `subscriptionId` string, required

## Headers

- `Authorization` string, required

## Response `200`

Successful request. Returns the requested subscription.

- Subscription
  - `subscriptionId` string, required — Unique identifier that the merchant assigned to the subscription.
  - `processingTerminalId` string, required — Unique identifier of the terminal that the subscription is linked to.
  - `paymentPlan` PaymentPlanSummary, required
    - `paymentPlanId` string, required — Unique identifier that the merchant assigns to the payment plan.
    - `name` string, required — Name of the payment plan.
    - `link` Link — Object that contains HATEOAS links for the resource.
      - `rel` string, required — Indicates the relationship between the current resource and the target resource.
      - `method` string, required — HTTP method that you need to use with the target resource.
      - `href` string, required — URL of the target resource.
  - `secureToken` SecureTokenSummary, required — Object that contains information about the secure token.
    - `secureTokenId` string, required — Unique identifier that the merchant assigned to the secure token.
    - `customerName` string, required — Customer's name.
    - `token` string, required — Token that the merchant can use in future transactions to represent the customer's payment details. The token: - Begins with the six-digit identification number **296753**. - Contains up to 12 digits. - Contains a single check digit that we calculate using the Luhn algorithm.
    - `status` 'notValidated' | 'cvvValidated' | 'validationFailed' | 'issueNumberValidated' | 'cardNumberValidated' | 'bankAccountValidated', required — Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. **Note:** Depending on the merchant's account settings, this feature may be unavailable.
    - `link` Link — Object that contains HATEOAS links for the resource.
      - `rel` string, required — Indicates the relationship between the current resource and the target resource.
      - `method` string, required — HTTP method that you need to use with the target resource.
      - `href` string, required — URL of the target resource.
  - `name` string, required — Name of the subscription.
  - `description` string — Description of the subscription.
  - `currency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'USS' | 'UYI' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL', required — Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.
  - `setupOrder` SubscriptionPaymentOrder — Object that contains information about the initial cost that a customer pays to set up the subscription.
    - `orderId` string — Unique identifier that the merchant assigns to the transaction.
    - `amount` integer — Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    - `description` string — Description of the transaction.
    - `breakdown` SubscriptionOrderBreakdown — Object that contains information about the surcharge and taxes that apply to the transaction.
      - `subtotal` integer, required — Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      - `convenienceFee` ConvenienceFee — Object that contains information about the convenience fee for the transaction.
        - `amount` integer, required — If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents.
      - `surcharge` Surcharge — Object that contains information about the surcharge.
        - `bypass` boolean — Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction.
        - `amount` integer — If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents.
        - `percentage` number, double — If the merchant added a surcharge fee, this value indicates the surcharge percentage.
      - `taxes` RetrievedTax[] — Array of tax objects.
        - `name` string, required — Name of the tax.
        - `rate` number, double, required — Tax percentage for the transaction.
        - `amount` integer — Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
  - `recurringOrder` SubscriptionRecurringOrder — Object that contains information about the cost of each payment.
    - `amount` integer — Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>**Important:** Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    - `description` string — Description of the transaction.
    - `breakdown` SubscriptionOrderBreakdown — Object that contains information about the surcharge and taxes that apply to the transaction.
      - `subtotal` integer, required — Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      - `convenienceFee` ConvenienceFee — Object that contains information about the convenience fee for the transaction.
        - `amount` integer, required — If the merchant added a convenience fee, this value indicates the amount of the convenience fee in the currency’s lowest denomination, for example, cents.
      - `surcharge` Surcharge — Object that contains information about the surcharge.
        - `bypass` boolean — Indicates if the merchant wants to remove the surcharge fee from the transaction. - `true` - Gateway removes the surcharge fee from the transaction. - `false` - Gateway adds the fee to the transaction.
        - `amount` integer — If the merchant added a surcharge fee, this value indicates the amount of the surcharge fee in the currency’s lowest denomination, for example, cents.
        - `percentage` number, double — If the merchant added a surcharge fee, this value indicates the surcharge percentage.
      - `taxes` RetrievedTax[] — Array of tax objects.
        - `name` string, required — Name of the tax.
        - `rate` number, double, required — Tax percentage for the transaction.
        - `amount` integer — Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
  - `currentState` SubscriptionState, required — A snapshot of the subscription's current state.
    - `status` 'active' | 'completed' | 'suspended' | 'cancelled', required — Status of the Subscription. - 'active' - Subscription is active. - 'completed' - Subscription has reached the end date or the total number of billing cycles. - 'cancelled' - Merchant deactivated the subscription. - 'suspended' - Subscription is suspended. For example, if the customer misses payments.
    - `nextDueDate` string, date — Date that the merchant collects the next payment.
    - `paidInvoices` integer, required — Number of payments that the merchant has collected.
    - `outstandingInvoices` integer — Number of payments until the end of the subscription. Our gateway returns a value for **outstandingInvoices** only if the subscription has an end date or a fixed number of billing cycles.
  - `startDate` string, date, required — Format: **YYYY-MM-DD** Subscription's start date.
  - `endDate` string, date — Format: **YYYY-MM-DD** Subscription's end date. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end.
  - `length` integer — Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of `0`. This value replaces the **length** inherited from the payment plan. **Note:** If you provide values for both **length** and **endDate**, our gateway uses the value for **endDate** to determine when the subscription should end.
  - `type` 'manual' | 'automatic', required — How the merchant takes the payment from the customer’s account. - `manual` – The merchant manually collects payments from the customer. - `automatic` – The terminal automatically collects payments from the customer.
  - `frequency` 'weekly' | 'fortnightly' | 'monthly' | 'quarterly' | 'yearly', required — Indicates how often the merchant or the terminal collects a payment from the customer.
  - `pauseCollectionFor` integer — Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.
  - `customFields` CustomField[] — Array of customField objects.
    - `name` string, required — Name of the custom field.
    - `value` string, required — Value for the custom field.

## Other responses

- `400` — Invalid request
- `401` — Identity could not be verified
- `403` — Do not have permissions to perform this action
- `404` — Resource not found
- `406` — Not acceptable
- `500` — An error has occured

---

[API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)