---
title: "Create subscription"
method: POST
path: "/processing-terminals/{processingTerminalId}/subscriptions"
tags: ["Subscriptions"]
---

# Create subscription

`POST /processing-terminals/{processingTerminalId}/subscriptions`

Use this method to assign a customer to a payment plan.  

**Note:** This method is part of our Repeat Payments feature. To help you understand how this method works with our Payment plans endpoints, go to [Repeat Payments](https://docs.payroc.com/guides/take-payments/repeat-payments).  

When you create a subscription you need to provide a unique subscriptionId that you use to run follow-on actions:  

- [Retrieve Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/retrieve) - View the details of the subscription.
- [Update Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/partially-update) - Update the details of the subscription.
- [Deactivate Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/deactivate) - Stop taking payments for the subscription.
- [Re-activate Subscription](https://docs.payroc.com/api/schema/payments/subscriptions/reactivate) - Start taking payments again for the subscription.
- [Pay Manual Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/pay) - Manually collect a payment for the subscription.

The request includes the following settings:
- **paymentPlanId** - Unique identifier of the payment plan that the merchant wants to use. If you don't have the paymentPlanId, use our [List Payment Plans](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/list) method to search for the payment plan.
- **paymentMethod** - Object that contains information about the secure token, which represents the customer's card details or bank account details.
- **startDate** - Date that you want to start to take payments.

You can also update the settings that the subscription inherited from the payment plan, for example, you can change the amount for each payment. If you change the settings for the subscription, it doesn't change the settings in the payment plan that it's linked to.

## Path parameters

- `processingTerminalId` string, required

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, uuid, required

## Request body

- SubscriptionRequest
  - `subscriptionId` string, required — Unique identifier that the merchant assigns to the subscription.
  - `paymentPlanId` string, required — Unique identifier that the merchant assigned to the payment plan.
  - `paymentMethod` SubscriptionRequestPaymentMethod, required — Object that contains information about the secure token that represents the customer’s payment details.
    - `type` 'secureToken', required — Discriminator value: secureToken
    - `accountType` 'checking' | 'savings' — Indicates the customer’s account type. **Note:** Send a value for accountType only if the secure token represents bank account details.
    - `token` string, required — Unique token that the gateway assigned to the payment details.
    - `secCode` 'web' | 'tel' | 'ccd' | 'ppd' — Indicates how the customer authorized the ACH transaction. Send one of the following values: - `web` – Online transaction. - `tel` – Telephone transaction. - `ccd` – Corporate credit or debit entry for a business bank account. - `ppd` – Pre-arranged transaction. **Note:** This field is mandatory when the secure token represents ACH bank account details.
  - `name` string — Name of the subscription. This value replaces the name inherited from the payment plan.
  - `description` string — Description of the subscription. This value replaces the description inherited from the payment plan.
  - `setupOrder` SubscriptionPaymentOrderRequest — 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` SubscriptionOrderBreakdownRequest — Object that contains information about the taxes to 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.
      - `taxes` TaxRate[] — Array of tax objects.
        - `rate` number, double, required — Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data).
        - `name` string, required — Name of the tax. A tax validation on the stored rate for the tax name is performed.
  - `recurringOrder` SubscriptionRecurringOrderRequest — Object that contains information about the cost of each payment. **Note:** Send this object only if the value for **type** is `automatic`.
    - `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` SubscriptionOrderBreakdownRequest — Object that contains information about the taxes to 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.
      - `taxes` TaxRate[] — Array of tax objects.
        - `rate` number, double, required — Tax percentage for the transaction. Required for [Level 3 and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data).
        - `name` string, required — Name of the tax. A tax validation on the stored rate for the tax name is performed.
  - `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.
  - `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.

## Response `201`

Successful request. We created the 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` — Validation error
- `401` — Identity could not be verified
- `403` — Do not have permissions to perform this action
- `406` — Not acceptable
- `409` — Conflict
- `415` — Unsupported media type
- `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)