Subscription Status Endpoint

This documentation details the endpoint used to retrieve the current status and information of existing subscriptions in our system.

Overview

The Subscription Status API allows merchants to retrieve comprehensive information about a subscription, including its current status, billing details, dates, and configuration.

Endpoint

GET https://api-stg.onekeypayments.com/v3/subscriptions/{subscription_id}

Where {subscription_id} is the unique numeric identifier of the subscription you wish to retrieve.

Get subscription details

get

This endpoint retrieves the details of a specific subscription by ID.

Path parameters

subscription_idinteger · int64Required

Unique numeric identifier of the subscription to retrieve.

Example: 219

Header parameters

Content-TypestringRequired

Media type of the body sent to the API.

Default: application/json

X-Datestring · date-timeRequired

ISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ)

X-LoginstringRequired

Merchant X-Login API Key.

AuthorizationstringRequired

Authorization control hash.

X-Idempotency-KeystringOptional

Unique idempotency key for ensuring that the same request is not processed more than once.

Responses

get

HTTPcURLJavaScriptPython

GET /v3/subscriptions/{subscription_id} HTTP/1.1
Host: api-stg.onekeypayments.com
Content-Type: text
X-Date: 2025-04-27T08:56:58.276Z
X-Login: text
Authorization: text
Accept: */*

{
  "subscription_id": 219,
  "status": "PENDING",
  "start_date": "2020-10-10",
  "end_date": "2020-10-17",
  "creation_date": "2025-02-18T17:18:21.67708163",
  "subscription_plan": "WEEKLY",
  "amount": 10.9,
  "auto_renewal": true,
  "last_modified_date": "2025-02-18T13:49:16"
}

Request Parameters

This endpoint uses only a path parameter to identify the subscription:

Parameter	Type	Required	Description
id	integer	Yes	Unique numeric identifier of the subscription to retrieve.

Response

Success Response

A successful request returns an HTTP 200 status code with the subscription details:

{
  "id": 219,
  "status": "PENDING",
  "start_date": "2020-10-10",
  "end_date": "2020-10-17",
  "creation_date": "2025-02-18T17:18:21.67708163",
  "subscription_plan": "WEEKLY",
  "amount": 10.90,
  "auto_renewal": true,
  "last_modified_date": "2025-02-18T13:49:16"
}

Response Fields

Field	Type	Description
id	integer	Unique identifier of the subscription
status	string	Current status of the subscription (PENDING, ACTIVE, CANCELLED, TERMINATED)
start_date	string	Date when the subscription started or will start (YYYY-MM-DD)
end_date	string	Date when the subscription will end if not renewed (YYYY-MM-DD)
creation_date	string	Timestamp when the subscription was created
subscription_plan	string	Frequency of the subscription (DAILY, WEEKLY, MONTHLY, ANNUALLY)
amount	number	Amount charged for each billing cycle
auto_renewal	boolean	Whether the subscription will automatically renew
last_modified_date	string	Timestamp when the subscription was last modified

Error Responses

The API may return the following errors:

Subscription Not Found

Returned when the specified subscription ID does not exist:

{
  "code": 420,
  "description": "Subscription does not exist.",
  "type": "SUBSCRIPTION_NOT_FOUND"
}

Generic Error

Returned when an unexpected error occurs:

{
  "code": 500,
  "description": "Subscription not found id 218 for merchantId 127,885",
  "type": "GENERIC_ERROR"
}

Subscription Statuses

A subscription can have one of the following statuses:

Status	Description
PENDING	Subscription has been created but payment has not been confirmed
ACTIVE	Subscription is active and billing cycles are in progress.
CANCELLED	Subscription was cancelled before completion.
TERMINATED	Subscription was terminated successfully, and all payments were charged accordingly.

Webhook Notifications and Payment Flow

When a payment related to a subscription is processed, our system will send notification updates to your configured notification URL. This notification includes a deposit_id which is crucial for tracking the payment status.

It is important that you integrate the Deposit Status Endpoint.

Complete Notification Flow

1. Payment Processing: The system processes a payment (initial or recurring)

2. Webhook Notification: A notification is sent to your configured URL with a deposit_id

3. Deposit Status Endpoint: Query GET v3/deposits/{deposit_id} to get payment details. You can find details of the endpoint here.
4. Subscription Identification: The deposit response includes the related subscription_id

5. Subscription Status Check: Query GET v3/subscriptions/{subscription_id} to verify current status

Example Flow

Payment processed
    ↓
Notification received with deposit_id=12345
    ↓
GET v3/deposits/12345
    ↓
Response contains subscription_id=219
    ↓
GET v3/subscriptions/219
    ↓
Verify and update subscription records

This complete flow ensures that you have full visibility into both payment status and subscription details.