Create subscription

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/integrate/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/payments/subscriptions/retrieve) - View the details of the subscription. - [Update Subscription](https://docs.payroc.com/api/schema/payments/subscriptions/partially-update) - Update the details of the subscription. - [Deactivate Subscription](https://docs.payroc.com/api/schema/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/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/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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

processingTerminalIdstringRequired>=4 characters<=50 characters
Unique identifier that we assigned to the terminal.

Headers

Idempotency-KeystringRequiredformat: "uuid"
Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency).

Request

This endpoint expects an object.
subscriptionIdstringRequired>=1 character<=48 characters
Unique identifier that the merchant assigned to the subscription.
paymentPlanIdstringRequired>=1 character<=48 characters
Unique identifier that the merchant assigned to the payment plan.
paymentMethodobjectRequired
Object that contains information about the customer's payment details.
startDatedateRequired

Format: YYYY-MM-DD
Subscription’s start date.

namestringOptional>=5 characters<=128 characters
Name of the subscription. This value replaces the name inherited from the payment plan.
descriptionstringOptional>=1 character<=128 characters
Description of the subscription. This value replaces the description inherited from the payment plan.
setupOrderobjectOptional
recurringOrderobjectOptional

Object that contains information about the cost of each payment.
Note: Send this object only if the value for type is automatic.

endDatedateOptional
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.
lengthintegerOptional>=0
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.
pauseCollectionForintegerOptional
Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.
customFieldslist of objectsOptional
Array of customField objects.

Response

Successful request. We created the subscription.
subscriptionIdstring>=1 character<=48 characters
Unique identifier that the merchant assigned to the subscription.
processingTerminalIdstring>=4 characters<=50 characters
Unique identifier of the terminal that the subscription is linked to.
paymentPlanobject
secureTokenobject
Object that contains information about the secure token.
namestring>=5 characters<=128 characters
Name of the subscription.
currencyenum
Currency of the transaction. The value for the currency follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.
currentStateobject
A snapshot of the subscription's current state.
startDatedate

Format: YYYY-MM-DD
Subscription’s start date.

typeenum
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.
Allowed values:
frequencyenum
Indicates how often the merchant or the terminal collects a payment from the customer.
Allowed values:
descriptionstring or null>=1 character<=128 characters
Description of the subscription.
setupOrderobject or null
recurringOrderobject or null
Object that contains information about the cost of each payment.
endDatedate or null

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.

lengthinteger or null>=0
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.
pauseCollectionForinteger or null>=0
Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.
customFieldslist of objects or null
Array of customField objects.

Errors