Subscription API Reference

This page documents the API endpoints for recurring products and subscriptions. Before using these APIs, create and confirm a saved payment method in Saved Payment Methods.

Prerequisite: Saved customer and token

Create and manage the customer_id and token_id in Saved Payment Methods. A confirmed customer_id and token_id are required before you create a subscription.

1. Create Product

POST /product/v1/create Creates a recurring billing product.

Request Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Product name
`type`	String	Yes	Must be `recurring`
`description`	String	No	Product description
`txamt`	Int	Yes	Amount in cents (100 = $1)
`txcurrcd`	String	Yes	Currency (e.g. HKD)
`interval`	String	Yes	Billing cycle: `weekly`, `monthly`, `yearly`
`interval_count`	Int	Yes	NO. of interval units (e.g. 1 month = 1) Weekly: weekly + 1 Monthly: monthly + 1 Quarterly: monthly + 3 Semi-annually: monthly + 6 Annually: yearly + 1 (or monthly + 12)
`usage_type`	String	Yes	Must be `licensed`

In the sandbox environment, minutes and hours can be used in the interval field for testing purposes.

Response

Returns generated product_id.

6. Update Product

POST /product/v1/update Updates product metadata.

Request Parameters

Parameter	Type	Required	Description
`product_id`	String	Yes	Product ID to update
`name`	String	No	New name
`description`	String	No	New description

Response

Returns number of affected rows.

7. Query Products

POST /product/v1/query Search for products.

Request Parameters

Parameter	Type	Required	Description
`product_id`	String	No	Product ID
`name`	String	No	Product name
`description`	String	No	Description
`txcurrcd`	String	No	Currency
`interval`	String	No	`monthly` / `yearly`
`page`	Int	No	Default = 1
`page_size`	Int	No	Default = 10, max = 100

Response

List of matching products.

8. Delete Product

POST /product/v1/delete Deletes a product (must not be linked to active subscriptions).

Request Parameters

Parameter	Type	Required	Description
`product_id`	String	Yes	Product ID to delete

Response

Returns deleted product ID and row count.

9. Create Subscription

You must create customer_id, product_id, and token_id before calling the subscription API.

POST /subscription/v1/create Creates a recurring subscription.

Request Parameters

Parameter	Type	Required	Description
`customer_id`	String	Yes	Linked customer ID
`token_id`	String	Yes	Linked payment token
`products`	List	Yes	Product ID and quantity
`total_billing_cycles`	Int	No	Total billing periods (null = indefinite)
`start_time`	String	No	ISO timestamp to start subscription

Products Object

Attribute	Type	Required	Description
`product_id`	String	Yes	Unique product identifier
`quantity`	Int	No	Default = 1

Example Request

{
  "products": [
    {
      "product_id": "prod_54c3772d******9a54b236e09ec74f",
      "quantity": 1
    }
  ],
  "customer_id": "cust_aaf6aae94******982c54c9cae5ba32",
  "token_id": "tk_a99892fd*********d3417d168a18bb",
  "total_billing_cycles": 2,
  "start_time": "2020-05-14 12:32:56"
}

Response (data field)

Attribute	Type	Description
`subscription_id`	String	Unique subscription identifier
`state`	String	`ACTIVE`, `INCOMPLETE`, `COMPLETED`

10. Update Subscription

POST /subscription/v1/update

Request Parameters

Attribute	Type	Required	Description
`subscription_id`	String	Yes	Unique subscription ID
`total_billing_cycles`	Int	No	Null = indefinite
`start_time`	String	No	First billing time
`token_id`	String	No	Payment token
`products`	Object	No	List of product objects

Response (data field)

Attribute	Type	Description
`subscription_id`	String	Subscription ID
`rowAffected`	Int	Number of records updated

11. Query Subscription

POST /subscription/v1/query

Request Parameters

Attribute	Type	Required	Description
`page`	Int	No	Default = 1
`page_size`	Int	No	Default = 10, max = 100
`subscription_id`	String	No	Subscription ID
`customer_id`	String	No	Customer ID
`state`	String	No	e.g. `INCOMPLETE`, `ACTIVE`

Sample Response

{
  "resperr": "success",
  "respcd": "0000",
  "respmsg": "success",
  "data": [
    {
      "subscription_id": "sub_e120378de*******da066f690da75",
      "customer_id": "cust_5ba1539f*******c9bda11d12c854e36",
      "token_id": "tk_9ac510017*******69b614e8f7ee",
      "state": "ACTIVE",
      "total_billing_cycles": 3,
      "completed_iteration": 1,
      "last_billing_time": "2024-11-21T11:12:06Z",
      "next_billing_time": "2024-11-21T11:13:06Z",
      "products": [
        { "product_id": "prod_8efecd0bd******b9aa1ec5ec01", "quantity": 1 }
      ]
    }
  ]
}

12. Cancel Subscription

POST /subscription/v1/cancel

Request Parameters

Attribute	Type	Required	Description
`subscription_id`	String	Yes	Subscription ID

13. Query Subscription Orders

POST /subscription/billing_order/v1/list

Request Parameters

Attribute	Type	Required	Description
`subscription_id`	String	Yes	Subscription ID
`page`	Int	No	Default = 1
`page_size`	Int	No	Default = 10, max = 100

Response (data field)

Attribute	Type	Description
`subscription_order_id`	String	Format: `sub_ord_{subscription_id}_{0001}`
`subscription_id`	String	Parent subscription
`trigger_by`	String	`auto` or `manual`
`sequence_no`	Int	Billing iteration number

14. Manual Charge Subscription

POST /subscription/v1/charge

Request Parameters

Attribute	Type	Required	Description
`subscription_id`	String	Yes	Subscription ID
`subscription_order_id`	String	No	Specific order to retry

This API is only valid for subscriptions with failed billing and state UNPAID, INCOMPLETE, or PAST_DUE.

If manual charge occurs before next billing time → subscription remains ACTIVE
If manual charge occurs after next billing time → subscription will be cancelled
If manual charge fails → subscription state remains unchanged

Query a saved payment token

POST /token/v1/query Query token details, including the token expiry date. Use customer_id and token_id when you need a specific saved payment method. For the saved-payment-method flow and notification handling, see Customer & Token Setup.

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

Prerequisite: Saved customer and token

1. Create Product

Request Parameters

Response

6. Update Product

Request Parameters

Response

7. Query Products

Request Parameters

Response

8. Delete Product

Request Parameters

Response

9. Create Subscription

Request Parameters

Products Object

Example Request

Response (data field)

10. Update Subscription

Request Parameters

Response (data field)

11. Query Subscription

Request Parameters

Sample Response

12. Cancel Subscription

Request Parameters

13. Query Subscription Orders

Request Parameters

Response (data field)

14. Manual Charge Subscription

Request Parameters

Query a saved payment token

​Prerequisite: Saved customer and token

​1. Create Product

​Request Parameters

​Response

​6. Update Product

​Request Parameters

​Response

​7. Query Products

​Request Parameters

​Response

​8. Delete Product

​Request Parameters

​Response

​9. Create Subscription

​Request Parameters

​Products Object

​Example Request

​Response (data field)

​10. Update Subscription

​Request Parameters

​Response (data field)

​11. Query Subscription

​Request Parameters

​Sample Response

​12. Cancel Subscription

​Request Parameters

​13. Query Subscription Orders

​Request Parameters

​Response (data field)

​14. Manual Charge Subscription

​Request Parameters

​Query a saved payment token

Prerequisite: Saved customer and token

1. Create Product

Request Parameters

Response

6. Update Product

Request Parameters

Response

7. Query Products

Request Parameters

Response

8. Delete Product

Request Parameters

Response

9. Create Subscription

Request Parameters

Products Object

Example Request

Response (data field)

10. Update Subscription

Request Parameters

Response (data field)

11. Query Subscription

Request Parameters

Sample Response

12. Cancel Subscription

Request Parameters

13. Query Subscription Orders

Request Parameters

Response (data field)

14. Manual Charge Subscription

Request Parameters

Query a saved payment token