Retrieve subscription | Payroc

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.

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

processingTerminalIdstringRequired4-50 characters

Unique identifier that we assigned to the terminal.

subscriptionIdstringRequired1-48 characters

Unique identifier that the merchant assigned to the subscription.

Response

Successful request. Returns the requested subscription.

subscriptionIdstring1-48 characters

Unique identifier that the merchant assigned to the subscription.

processingTerminalIdstring4-50 characters

Unique identifier of the terminal that the subscription is linked to.

paymentPlanobject

secureTokenobject

Object that contains information about the secure token.

namestring5-128 characters

Name of the subscription.

currencyenum

Currency of the transaction. The value for the currency follows the ISO 4217 standard.

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.

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:

descriptionstring1-128 characters

Description of the subscription.

setupOrderobject

recurringOrderobject

Object that contains information about the cost of each payment.

endDatedate

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

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>=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

Array of customField objects.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

406

Not Acceptable Error

500

Internal Server Error

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.

1	using Payroc;
2	using System.Threading.Tasks;
3	using Payroc.RepeatPayments.Subscriptions;
4
5	namespace Usage;
6
7	public class Example
8	{
9	public async Task Do() {
10	var client = new PayrocClient();
11
12	await client.RepeatPayments.Subscriptions.RetrieveAsync(
13	new RetrieveSubscriptionsRequest {
14	ProcessingTerminalId = "1234001",
15	SubscriptionId = "SubRef7654"
16	}
17	);
18	}
19
20	}

1	{
2	"subscriptionId": "SubRef7654",
3	"processingTerminalId": "1234001",
4	"paymentPlan": {
5	"paymentPlanId": "PlanRef8765",
6	"name": "Monthly Premium Club subscription",
7	"link": {
8	"rel": "self",
9	"method": "GET",
10	"href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
11	}
12	},
13	"secureToken": {
14	"secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
15	"customerName": "Sarah Hazel Hopper",
16	"token": "296753123456",
17	"status": "notValidated",
18	"link": {
19	"rel": "self",
20	"method": "GET",
21	"href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
22	}
23	},
24	"name": "Premium Club",
25	"currency": "USD",
26	"currentState": {
27	"status": "active",
28	"paidInvoices": 0,
29	"nextDueDate": "2024-08-02",
30	"outstandingInvoices": 3
31	},
32	"startDate": "2024-07-02",
33	"type": "automatic",
34	"frequency": "monthly",
35	"description": "Premium Club subscription",
36	"setupOrder": {
37	"amount": 4999,
38	"breakdown": {
39	"subtotal": 4347,
40	"surcharge": {
41	"amount": 217,
42	"percentage": 5
43	},
44	"taxes": [
45	{
46	"name": "Sales Tax",
47	"rate": 5
48	}
49	]
50	},
51	"description": "Initial setup fee for Premium Club subscription",
52	"orderId": "OrderRef6543"
53	},
54	"recurringOrder": {
55	"amount": 4999,
56	"breakdown": {
57	"subtotal": 4347,
58	"surcharge": {
59	"amount": 217,
60	"percentage": 5
61	},
62	"taxes": [
63	{
64	"name": "Sales Tax",
65	"rate": 5
66	}
67	]
68	},
69	"description": "Premium Club subscription"
70	},
71	"endDate": "2025-07-01",
72	"length": 12,
73	"pauseCollectionFor": 0,
74	"customFields": [
75	{
76	"name": "yourCustomField",
77	"value": "abc123"
78	}
79	]
80	}