Logo

Smarty Docs

Subscriptions

Use the API described below to integrate subscriptions into your app or e-commerce system. To learn more about subscriptions, visit this section.

To create a subscription via API one should follow these steps:

  1. Get active subscription plans.
  2. Create a new subscription in a Draft state, and get a future contract address.
  3. Broadcast a particular approve spending transaction into the blockchain, for the corresponding token and contract as a spender.
  4. Activate subscription.

Preparing your account

Before you can create subscription, make sure you've checked everything on the merchant account setup checklist:

GET/integration/subscription-plans

Get subscription plans

This endpoint allows you to get subscription plans created via Merchant Dashboard.

Learn about authentication

Query Parameters

  • Name
    statusIn
    Type
    string[]
    Description

    Array of enum values: "Draft", "Active", "Archived"

  • Name
    limit
    Type
    integer
    Description

    Result limit

  • Name
    offset
    Type
    integer
    Description

    Result offset

Request

GET
/integration/subscription-plans
curl 'https://api.smartypay.io/integration/subscription-plans' \
  --user API_KEY:SECRET

Response

{
  "plans": [
    {
      "id": "CjGSkDdmSNCslurvtgu2Vw",
      "description": "10GB Data plan for SkyX Mobile",
      "amount": "1.33 bUSDT",
      "periodSeconds": 300,
      "createdAt": "2022-12-14T12:57:07.455558Z",
      "tags": [],
      "status": "Active"
    }
  ]
}
POST/integration/subscriptions

Create a subscription

Creates a new subscription in a Draft state, you should activate it by giving allowance for the subscription contract.

Required attributes

  • Name
    planId
    Type
    string
    Description

    ID of a subscription plan.

  • Name
    customerId
    Type
    string
    Description

    Customer correlation ID.

  • Name
    payer
    Type
    string
    Description

    Blockchain address of a payer.

  • Name
    startFrom
    Type
    string
    Description

    ISO8601 Timestamp of when the subscription is expected to start.

Optional attributes

  • Name
    metadata
    Type
    string
    Description

    Additional data to be passed with webhooks.

  • Name
    maxPeriods
    Type
    integer
    Description

    A limit for the maximum allowed charges, default is 24 periods.

Request

POST
/integration/subscriptions
curl --request POST \
  --url https://api.smartypay.io/integration/subscriptions \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "planId": "CjGSkDdmSNCslurvtgu2Vw",
    "customerId": "stage-user-001",
    "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
    "startFrom": "2024-07-29T13:51:34.755Z"
}'

Response

{
  "contractAddress": "0xd90537f50e6273f904ac5d2cadc68b5dc679e36e",
  "planId": "CjGSkDdmSNCslurvtgu2Vw",
  "asset": "bUSDT",
  "blockchain": "BinanceTestNet",
  "customerId": "stage-user-001",
  "nextChargeAt": "2022-12-14T13:12:05Z",
  "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
  "createdAt": "2025-07-29T13:51:34.755Z",
  "startFrom": "2025-07-29T13:51:34.755Z",
  "status": "Draft"
}
GET/integration/subscriptions

Returns subscriptions by filter

Use this method to get a collection of subscriptions based on a filter.

Query Parameters

  • Name
    customerId
    Type
    string
    Description

    External customer Id

  • Name
    payer
    Type
    string
    Description

    Address of the payer

  • Name
    statusIn
    Type
    string[]
    Description

    Comma-separated statuses

  • Name
    limit
    Type
    integer
    Description

    Result limit

  • Name
    offset
    Type
    integer
    Description

    Result offset

Request

GET
/integration/subscriptions
curl 'https://api.smartypay.io/integration/subscriptions' \
  --user API_KEY:SECRET

Response

{
  "subscriptions": [
    {
      "contractAddress": "0xd90537f50e6273f904ac5d2cadc68b5dc679e36e",
      "planId": "CjGSkDdmSNCslurvtgu2Vw",
      "asset": "bUSDT",
      "blockchain": "BinanceTestNet",
      "customerId": "stage-user-001",
      "nextChargeAt": "2022-12-14T13:12:05Z",
      "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
      "createdAt": "2025-07-29T13:51:34.755Z",
      "startFrom": "2025-07-29T13:51:34.755Z",
      "status": "Draft"
    }
  ],
  "page": {
    "limit": 100,
    "offset": 0
  }
}
POST/integration/create-customer-token

Create access token for external widget

Use this widget to allow payers to create a new instance of subscription (or a recurring payment).

Required attributes

  • Name
    customerId
    Type
    string
    Description

    Customer correlation ID.

Request

POST
/integration/subscriptions/create-customer-token
curl --request POST \
  --url https://api.smartypay.io/integration/subscriptions/create-customer-token \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "customerId": "stage-user-001"
}'

Response

{
  "token": "...",
}