Subscription Plan
List Contracts
Retrieve a paginated list of subscription contracts with filtering by status, date, subscriber, and payment details.
List Contracts
Version: 3.0.0
Generate an API Key for the Subscription channel before making requests.
Use this endpoint to retrieve a paginated list of all subscription contracts associated with your merchant account. You can filter by subscription status, date ranges, subscriber information, payment status, and billing details.
Endpoint
| Method | URL |
|---|---|
| GET | https://api.payorc.com/subscriptions/v1/contract/list |
Please use the test credentials for sandbox testing.
Authentication
Include the following headers in every request:
| Header | Type | Description |
|---|---|---|
merchant-key | String | Your merchant key |
merchant-secret | String | Your merchant secret |
All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
perpage | Integer | Yes | Number of records per page |
page | Integer | Yes | Page number (starting from 1) |
contract_id | Integer | No | Filter by plain display contract ID |
subscriber_id | Integer | No | Filter by plain display subscriber ID |
subscriber_email_or_mobile | String | No | Filter by subscriber email or mobile number |
subscription_from_date | String | No | Filter subscriptions from this date (YYYY-MM-DD) |
subscription_to_date | String | No | Filter subscriptions up to this date (YYYY-MM-DD) |
payment_from_date | String | No | Filter payments from this date (YYYY-MM-DD) |
payment_to_date | String | No | Filter payments up to this date (YYYY-MM-DD) |
last_payment_status | String | No | Filter by last payment status (PAID, FAILED) |
currency | String | No | Filter by currency code (3-letter) |
status | String | No | Filter by subscription status (Active, Deactivated) |
billing_interval | Integer | No | Filter by billing interval |
billing_frequency | String | No | Filter by billing frequency (yearly, monthly, weekly, daily) |
installment_amount | Number | No | Filter by installment amount |
total_terms | Integer | No | Filter by total terms |
Pagination is required for accounts with many contracts. Use perpage and page to navigate through results.
Response (200 OK)
| Field | Type | Description |
|---|---|---|
data | Array | List of contract objects |
data[].contract_details | Object | Contract details |
data[].contract_details.subscription_id | String | Encrypted subscription ID — use this for Contract Details and Cancel Subscription |
data[].contract_details.contract_id | String | Plain display contract ID |
data[].contract_details.de_submerchant_id | String | Sub-merchant ID |
data[].contract_details.submerchant_name | String | Sub-merchant name |
data[].contract_details.status | String | Status (Active, Deactivated) |
data[].contract_details.subscription_date | String | Subscription date (DD-MM-YYYY HH:mm:ss) |
data[].contract_details.order_no | String | Order number |
data[].contract_details.last_payment_status | String | Last payment status |
data[].contract_details.terms_collected | Integer | Terms collected so far |
data[].contract_details.subscription_start_date | String | Subscription start date |
data[].contract_details.next_payment_date | String | Next payment date |
data[].contract_details.last_payment_date | String | Last payment date |
data[].contract_details.card_no | String | Masked card number |
data[].contract_details.card_nw | String | Card network |
data[].contract_details.due_amount | String | Due amount |
data[].plan_details | Object | Plan details |
data[].plan_details.plan_id | String | Plan ID |
data[].plan_details.plan_name | String | Plan name |
data[].plan_details.billing_frequency | String | Billing frequency |
data[].plan_details.total_terms | String | Total terms (or Unlimited) |
data[].plan_details.billing_interval | Integer | Billing interval |
data[].plan_details.currency | String | Currency |
data[].plan_details.installment_amount | String | Installment amount |
data[].plan_details.shipping_fee | Number | Shipping fee |
data[].plan_details.convenience_fee | Number | Convenience fee |
data[].plan_details.start_date | String | Plan start date |
data[].subscriber_details | Object | Subscriber details |
data[].subscriber_details.subscribers_id | String | Subscriber ID |
data[].subscriber_details.name | String | Subscriber name |
data[].subscriber_details.mobile_no | String | Subscriber mobile number |
data[].subscriber_details.email | String | Subscriber email |
message | String | Human-readable status message |
status | String | success or error |
code | String | Status code (00 for success) |
total_records | Integer | Total number of matching records |
Code Examples
curl -X GET "https://api.payorc.com/subscriptions/v1/contract/list?perpage=10&page=1" \
-H "merchant-key: YOUR_MERCHANT_KEY" \
-H "merchant-secret: YOUR_MERCHANT_SECRET"Example Response
{
"data": [
{
"contract_details": {
"subscription_id": "WnIzN0tFTGQxZ2a3ZLdXpQRTQydz09",
"contract_id": "1000010002",
"de_submerchant_id": "0000001181",
"submerchant_name": "DEMOACCOUNT",
"status": "Active",
"subscription_date": "23-01-2025 16:06:26",
"order_no": "1000012004",
"last_payment_status": "PAID",
"terms_collected": 1,
"subscription_start_date": "23-01-2025",
"next_payment_date": "24-01-2025",
"last_payment_date": "23-01-2025 04:08:00",
"card_no": "xxxx xxxx xxxx 1111",
"card_nw": "VISA",
"due_amount": "90.00"
},
"plan_details": {
"plan_id": "10000002",
"plan_name": "TEST",
"billing_frequency": "daily",
"total_terms": 2,
"billing_interval": 1,
"currency": "AED",
"installment_amount": "50.00",
"shipping_fee": "25.00",
"convenience_fee": "15.00",
"start_date": "23-01-2025 11:08:00"
},
"subscriber_details": {
"subscribers_id": "0000000248",
"name": "Rahul S",
"mobile_no": "9238328673",
"email": "[email protected]"
}
}
],
"message": "Contract list fetched successfully.",
"status": "success",
"code": "00",
"total_records": 1
}Use the encrypted contract_details.subscription_id from this response for Contract Details and Cancel Subscription. The plain contract_id is the display identifier only. Request date filters use YYYY-MM-DD; response dates use DD-MM-YYYY.