SchemaPaymentsSubscriptions

Retrieve subscription

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/payments/subscriptions/create) method. **Note:** If you don't have the subscriptionId, use our [List subscriptions](https://docs.payroc.com/api/schema/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.

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.
subscriptionIdstringRequired>=1 character<=48 characters
Unique identifier that the merchant assigned to the subscription.

Response

Successful request. Returns the requested 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