Subscription Plans

The API is designed for creating subscription plans. Subscription plans essentially act as templates specifying the amount, frequency, and other attributes (for example, "Standard plan 10 AED/month"), based on which specific subscription instances are created for each payer.

Guide: Subscriptions

The Plan object

The SubscriptionPlan object includes all relevant details about a subscription plan. You should create it before any subscription instances can be created.

Properties

Name
id
Type
string
Description
Unique identifier for the plan.
Name
merchantId
Type
string
Description
The identifier of the merchant this plan is related to.
Name
name
Type
string
Description
Name of the plan.
Name
description
Type
string
Description
A short text explaining the plan details.
Name
amount
Type
money
Description
The price of the plan.
Name
periodSeconds
Type
number
Description
Duration of the plan in seconds.
Name
gracePeriodSeconds
Type
number
Description
The timeframe during which automatic renewal is possible (the subscription for this plan will remain active).
Name
createdAt
Type
string
Description
ISO8601 Timestamp of when the plan was created.
Name
status
Type
string
Description
Status of the plan, the possible values are the following:
1. Draft
2. Active
3. Archived

POST/v1/subscription-plans

Create a plan

This endpoint allows you to create a new plan.

Required attributes

Name
merchantId
Type
string
Description
The identifier of the merchant this plan is related to.
Name
name
Type
string
Description
Name of the plan.
Name
description
Type
string
Description
A short text explaining the plan details.
Name
amount
Type
money
Description
The cost or price of the plan.
Name
periodSeconds
Type
number
Description
Duration of the plan in seconds.
Name
gracePeriodSeconds
Type
number
Description
The automatic renewal timeframe.

Optional attributes

None

Error codes

If something goes wrong during the processing of this request the error code in standard format is returned.

See error codes

Request

POST

/v1/subscription-plans

curl --request POST \
  --url https://partner-api.smartypay.io/v1/subscription-plans \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "name": "Premium One",
    "description": "Enjoy the premium access to our music streaming",
    "periodSeconds": 2592000,
    "gracePeriodSeconds": 86400,
    "amount": {
        "value": "15",
        "currency": "btUSDTv2"
    },
    "merchantId": "9xBoSUdGWeiAzMn5VHBvMB"
}'

Response

{
    "id": "pIBJda_dS_C2KWUb6MzJ7Q",
    "merchantId": "9xBoSUdGWeiAzMn5VHBvMB",
    "name": "Premium One",
    "description": "Enjoy the premium access to our music streaming",
    "amount": {
        "value": "15",
        "currency": "btUSDTv2"
    },
    "periodSeconds": 2592000,
    "gracePeriodSeconds": 86400,
    "createdAt": "2024-02-19T16:25:30.811174Z",
    "status": "Draft"
}

POST/v1/subscription-plans/search

Search for plans

This endpoint allows you to retrieve a paginated list of subscription plans that optionally can be filtered based on the predicates defined below.

Predicates are combined with AND semantics.

Required attributes

Name
merchantId
Type
string
Description
The identifier of the merchant.

Optional attributes

Name
page
Type
object
Description
Defines pagination and sorting options.
Name
predicates.network
Type
string
Description
Type of blockchain network MainNet or TestNet.

Request

POST

/v1/subscription-plans/search

curl --request POST \
  --url https://partner-api.smartypay.io/v1/subscription-plans/search \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "predicates": {
        "network": "TestNet"
    },
    "page": {
        "limit": 5
    }
}'

Response

{
    "list": [
        {
            "id": "pIBJda_dS_C2KWUb6MzJ7Q",
            "merchantId": "9xBoSUdGWeiAzMn5VHBvMB",
            "name": "Premium One",
            "description": "Enjoy the premium access to our music streaming",
            "amount": {
                "value": "15",
                "currency": "btUSDTv2"
            },
            "periodSeconds": 2592000,
            "gracePeriodSeconds": 86400,
            "createdAt": "2024-02-19T16:25:30.811174Z",
            "status": "Draft"
        },
        {
            "id": "rFI995vUhSIhXBhNe8Xv7x"
            // ...
        }
    ],
    "page": {
        "limit": 5,
        "offset": 0
    },
}

GET/v1/subscription-plans/{planId}

Retrieve a plan

This endpoint allows you to retrieve a subscription plan by providing their unique id.

Refer to the list at the top of this page to see which properties are included with plan objects.

Request

GET

/v1/subscription-plans/{planId}

curl https://partner-api.smartypay.io/v1/subscription-plans/pIBJda_dS_C2KWUb6MzJ7Q \
  --user API_KEY:SECRET

Response

{
    "id": "pIBJda_dS_C2KWUb6MzJ7Q",
    "merchantId": "9xBoSUdGWeiAzMn5VHBvMB",
    "name": "Premium One",
    "description": "Enjoy the premium access to our music streaming",
    "amount": {
        "value": "15",
        "currency": "btUSDTv2"
    },
    "periodSeconds": 2592000,
    "gracePeriodSeconds": 86400,
    "createdAt": "2024-02-19T16:25:30.811174Z",
    "status": "Draft"
}

PUT/v1/subscription-plans/{planId}/status

Update plan status

This endpoint allows you to update the plan's status.

Request

PUT

/v1/subscription-plans/{planId}/status

curl --request PUT \
  --url https://partner-api.smartypay.io/v1/subscription-plans/pIBJda_dS_C2KWUb6MzJ7Q/status \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "status": "Active"
}'

Response

{
    "id": "pIBJda_dS_C2KWUb6MzJ7Q",
    "merchantId": "9xBoSUdGWeiAzMn5VHBvMB",
    "name": "Premium One",
    "description": "Enjoy the premium access to our music streaming",
    "amount": {
    "value": "15",
    "currency": "btUSDTv2"
},
    "periodSeconds": 2592000,
    "gracePeriodSeconds": 86400,
    "createdAt": "2024-02-19T16:25:30.811174Z",
    "status": "Active"
}

DELETE/v1/subscription-plans/{planId}

Delete a plan

This endpoint allows you to delete the plan by its identifer.

Request

DELETE

/v1/subscription-plans/{planId}

curl --request DELETE \
  --url https://partner-api.smartypay.io/v1/subscription-plans/pIBJda_dS_C2KWUb6MzJ7Q \
  --user API_KEY:SECRET

Response

{
    // ... an empty object
}

Error codes

In case of error, you will receive the standard error object as a response with the following possible error codes. Use this code to handle them in an appropriate way.

The error codes listed below are only related to subscription plans; some generic errors might be also returned.

Code	HTTP Code	Description
MerchantNotFound	404	The merchant that provided in `merchantId` attribute is not found.
SubscriptionPlanNotFound	404	Subscription plan is not found.
SubscriptionPlanAssetNotActive	400	Currency/Asset of the plan amount you have provided is not enabled for the merchant or invalid.
SubscriptionPlanInvalidStatus	400	Plan you're trying to update or delete has invalid status.

SMARTy Docs

SMARTy Docs

Subscription Plans

The Plan object

Properties

Create a plan

Required attributes

Optional attributes

Error codes

Request

Response

Search for plans

Required attributes

Optional attributes

Request

Response

Retrieve a plan

Request

Response

Update plan status

Request

Response

Delete a plan

Request

Response

Error codes