Retrieve subscription

Browse API reference

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

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 method.

Note: If you don't have the subscriptionId, use our List subscriptions 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.

Parameters

Name	In	Type	Description
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.
`subscriptionId`Required	path	`string`	Unique identifier that the merchant assigned to the subscription.

Responses

Successful request. Returns the requested subscription.

200 OK · application/json

{
  "currency": "USD",
  "currentState": {
    "nextDueDate": "2024-08-02",
    "outstandingInvoices": 3,
    "paidInvoices": 0,
    "status": "active"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ],
  "description": "Premium Club subscription",
  "endDate": "2025-07-01",
  "frequency": "monthly",
  "length": 12,
  "name": "Premium Club",
  "pauseCollectionFor": 0,
  "paymentPlan": {
    "link": {
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765",
      "method": "GET",
      "rel": "self"
    },
    "name": "Monthly Premium Club subscription",
    "paymentPlanId": "PlanRef8765"
  },
  "processingTerminalId": "1234001",
  "recurringOrder": {
    "amount": 4999,
    "breakdown": {
      "convenienceFee": {
        "amount": 217
      },
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Premium Club subscription"
  },
  "secureToken": {
    "customerName": "Sarah Hazel Hopper",
    "link": {
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "method": "GET",
      "rel": "self"
    },
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "status": "notValidated",
    "token": "296753123456"
  },
  "setupOrder": {
    "amount": 4999,
    "breakdown": {
      "convenienceFee": {
        "amount": 217
      },
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Initial setup fee for Premium Club subscription",
    "orderId": "OrderRef6543"
  },
  "startDate": "2024-07-02",
  "subscriptionId": "SubRef7654",
  "type": "automatic"
}

Response schema · 52 of 66 fields

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.+1 more fields at deeper levels — see the full spec
  - 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.+3 more fields at deeper levels — see the full spec
  - taxesobject[]
    Array of tax objects.+3 more fields at deeper levels — see the full spec
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.+1 more fields at deeper levels — see the full spec
  - 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.+3 more fields at deeper levels — see the full spec
  - taxesobject[]
    Array of tax objects.+3 more fields at deeper levels — see the full spec
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

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
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"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

manage-subscriptions