Use this method to return a paginated list of subscriptions.
Note: If you want to view the details of a specific subscription and you have its subscriptionId, use our Retrieve subscription method.
Use query parameters to filter the list of results that we return, for example, to search for subscriptions for a customer, a payment plan, or frequency.
Our gateway returns information about the following for each subscription in the list:
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.
For each subscription, we also return the subscriptionId, the paymentPlanId, and the secureTokenId, which you can use to perform follow-actions.
Parameters
Name
In
Type
Description
processingTerminalIdRequired
path
string
Unique identifier that we assigned to the terminal.
customerName
query
string
Filter by the customer's name.
last4
query
string
Filter by the last four digits of the card or account number.
paymentPlan
query
string
Filter by the name of the payment plan.
frequency
query
string
Filter by the frequency of subscription payments.
status
query
string
Filter by the current status of the subscription.
endDate
query
string
Format: YYYY-MM-DD Filter subscriptions that end on a specific date.
nextDueDate
query
string
Format: YYYY-MM-DD Filter subscriptions by the date that the next payment is collected.
before
query
string
Return the previous page of results before the value that you specify.
You can’t send the before parameter in the same request as the after parameter.
after
query
string
Return the next page of results after the value that you specify.
You can’t send the after parameter in the same request as the before parameter.
limit
query
integer
Limit the maximum number of results that we return for each page.
Responses
Successful request. Returns a paginated list of subscriptions.
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMorebooleanrequired
Indicates whether there is another page of results available.
limitintegerrequired
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
hrefstringrequired
URL of the target resource.
methodstringrequired
HTTP method that you need to use with the target resource.
relstringrequired
Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of subscriptions.
currencystringrequired
Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
currentStateobjectrequired
A snapshot of the subscription's current state.
nextDueDatestringdate
Date that the merchant collects the next payment.
outstandingInvoicesintegerint32
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.≥ 0
paidInvoicesintegerint32required
Number of payments that the merchant has collected.≥ 0
statusstringrequired
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.activecompletedsuspendedcancelled
customFieldsobject[]
Array of customField objects.
namestringrequired
Name of the custom field.1–56 chars
valuestringrequired
Value for the custom field.1–100 chars
descriptionstring
Description of the subscription.1–128 chars
endDatestringdate
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.
frequencystringrequired
Indicates how often the merchant or the terminal collects a payment from the customer.weeklyfortnightlymonthlyquarterlyyearly
lengthintegerint32
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.≥ 0
namestringrequired
Name of the subscription.5–128 chars
pauseCollectionForintegerint32
Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.≥ 0
paymentPlanobjectrequired
linkobject
Object that contains HATEOAS links for the resource.
hrefstringrequired
URL of the target resource.
methodstringrequired
HTTP method that you need to use with the target resource.
relstringrequired
Indicates the relationship between the current resource and the target resource.
namestringrequired
Name of the payment plan.5–128 chars
paymentPlanIdstringrequired
Unique identifier that the merchant assigns to the payment plan.1–48 chars
processingTerminalIdstringrequired
Unique identifier of the terminal that the subscription is linked to.4–50 chars
recurringOrderobject
Object that contains information about the cost of each payment.
amountintegerint64
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.
descriptionstring
Description of the transaction.1–1024 chars
breakdownobject
Object that contains information about the surcharge and taxes that apply to the transaction.
convenienceFeeobject
Object that contains information about the convenience fee for the transaction.
amountintegerint64required
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.
subtotalintegerint64required
Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
surchargeobject
Object that contains information about the surcharge that we applied to the transaction.
amountintegerint64
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.
bypassboolean
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.
percentagenumberdouble
If the merchant added a surcharge fee, this value indicates the surcharge percentage.≤ 100
taxesobject[]
Array of tax objects.
amountintegerint64
Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
namestringrequired
Name of the tax.1–64 chars
ratenumberdoublerequired
Tax percentage for the transaction.0–99.99999
secureTokenobjectrequired
Object that contains information about the secure token.
customerNamestringrequired
Customer's name.1–50 chars
linkobject
Object that contains HATEOAS links for the resource.
hrefstringrequired
URL of the target resource.
methodstringrequired
HTTP method that you need to use with the target resource.
relstringrequired
Indicates the relationship between the current resource and the target resource.
secureTokenIdstringrequired
Unique identifier that the merchant assigned to the secure token.1–200 chars
statusstringrequired
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.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
tokenstringrequired
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.12–19 chars
setupOrderobject
Object that contains information about the initial cost that a customer pays to set up the subscription.
amountintegerint64
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.≤ 999999999999
descriptionstring
Description of the transaction.1–1024 chars
orderIdstring
Unique identifier that the merchant assigns to the transaction.1–24 chars
breakdownobject
Object that contains information about the surcharge and taxes that apply to the transaction.
convenienceFeeobject
Object that contains information about the convenience fee for the transaction.
amountintegerint64required
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.
subtotalintegerint64required
Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
surchargeobject
Object that contains information about the surcharge that we applied to the transaction.
amountintegerint64
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.
bypassboolean
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.
percentagenumberdouble
If the merchant added a surcharge fee, this value indicates the surcharge percentage.≤ 100
taxesobject[]
Array of tax objects.
amountintegerint64
Amount of tax that was applied to the transaction. The value is in the currency's lowest denomination, for example, cents.
namestringrequired
Name of the tax.1–64 chars
ratenumberdoublerequired
Tax percentage for the transaction.0–99.99999
startDatestringdaterequired
Format: YYYY-MM-DD Subscription's start date.
subscriptionIdstringrequired
Unique identifier that the merchant assigned to the subscription.1–48 chars
typestringrequired
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.manualautomatic
Invalid request
400 Bad Request · application/problem+json
{"detail":"One or more validation errors occurred, see error section for more info","errors":[{"detail":"invalid date","message":"Expected time, got '' for start_time","parameter":"start_time"}],"status":400,"title":"Bad request","type":"https://docs.payroc.com/api/errors#bad-request"}
Response schema · 8 fields
detailstringrequired
Explanation of the problem
errorsobject[]
detailstring
Short detail of the validation errors
messagestring
Error message
parameterstring
The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Identity could not be verified
401 Unauthorized · application/problem+json
{"detail":"Your identity could not be verified","status":401,"title":"Not Authorized","type":"https://docs.payroc.com/api/errors#not-authorized"}
Response schema · 4 fields
detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Do not have permissions to perform this action
403 Forbidden · application/problem+json
{"detail":"You do not have the required permissions to perform this action","instance":"https://api.payroc.com/v1/exampleResource/3","resource":"exampleResource","status":403,"title":"Forbidden","type":"https://docs.payroc.com/api/errors#forbidden"}
Response schema · 6 fields
detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
Not acceptable
406 Not Acceptable · application/problem+json
{"detail":"Resource does not support the representation requested","status":406,"title":"Not acceptable","type":"https://docs.payroc.com/api/errors#not-acceptable"}
Response schema · 4 fields
detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type
An error has occured
500 Internal Server Error · application/problem+json
{"detail":"We are unable to process your request at this time","errors":[{"message":"Service offline"}],"status":500,"title":"Api error","type":"https://docs.payroc.com/api/errors#api-error"}