Subscription

Lydian supports recurring billing through subscription plans. Create plans with defined billing intervals, subscribe customers, and manage the subscription lifecycle.

Subscription Plans

Create Subscription Plan

POST /subscriptionplans

POST

/subscriptionplans

curl --location '{API_BASE_URL}/subscriptionplans' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "accountId": "{ACCOUNT_ID}",
    "merchantId": "{MERCHANT_ID}", // OPTIONAL
    "planName": "{PLAN_NAME}", // OPTIONAL
    "description": "{DESCRIPTION}", // OPTIONAL
    "amount": "{AMOUNT}",
    "billingInterval": "{BILLING_INTERVAL}"
}'

billingInterval must be one of: MONTHLY, YEARLY.

Create Subscription Plan Response

Name
id
Type
string
Description
Unique identifier for the subscription plan.
Name
accountId
Type
string
Description
Account ID the plan belongs to.
Name
merchantId
Type
string
Description
Merchant ID the plan belongs to.
Name
planName
Type
string
Description
Name of the subscription plan.
Name
description
Type
string
Description
Description of the subscription plan.
Name
billingInterval
Type
string
Description
Billing interval for the plan. Either MONTHLY or YEARLY.
Name
amount
Type
string
Description
Amount to charge per billing interval.

example response

{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "planName": "Pro Monthly",
    "description": "Pro plan billed monthly",
    "billingInterval": "MONTHLY",
    "amount": "29.99"
}

List Subscription Plans

GET /subscriptionplans

GET

/subscriptionplans

curl --location '{API_BASE_URL}/subscriptionplans?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

Optional query parameters: accountId, merchantId.

List Subscription Plans Response

Name
plans
Type
array
Description
List of subscription plans.
Name
metadata
Type
object
Description
Pagination metadata.
Name
totalCount
Type
number
Description
Total number of items available.
Name
count
Type
number
Description
Number of items in the current page.
Name
page
Type
number
Description
Current page number.
Name
pageSize
Type
number
Description
Maximum items per page.

example response

{
    "plans": [
        {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "planName": "Pro Monthly",
            "description": "Pro plan billed monthly",
            "billingInterval": "MONTHLY",
            "amount": "29.99"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}

Get Subscription Plan

GET /subscriptionplans/{planId}

GET

/subscriptionplans/{planId}

curl --location '{API_BASE_URL}/subscriptionplans/{planId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

The response is the same structure as the Create Subscription Plan Response.

Subscriptions

Create Subscription

POST /subscriptions

POST

/subscriptions

curl --location '{API_BASE_URL}/subscriptions' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "planId": "{PLAN_ID}",
    "customerEmail": "{CUSTOMER_EMAIL}",
    "walletAddress": "{WALLET_ADDRESS}",
    "billingInterval": "{BILLING_INTERVAL}"
}'

Create Subscription Response

Name
id
Type
string
Description
Unique identifier for the subscription.
Name
accountId
Type
string
Description
Account ID the subscription belongs to.
Name
merchantId
Type
string
Description
Merchant ID the subscription belongs to.
Name
planId
Type
string
Description
Plan ID the subscription is based on.
Name
planName
Type
string
Description
Name of the associated plan.
Name
customerEmail
Type
string
Description
Email address of the subscribed customer.
Name
walletAddress
Type
string
Description
Crypto wallet address of the customer.
Name
status
Type
string
Description
Current status of the subscription. One of ACTIVE, PAUSED, PAYMENT_FAILED, or CANCELED.
Name
billingInterval
Type
string
Description
Billing interval. Either MONTHLY or YEARLY.
Name
lastBillingAt
Type
string
Description
Timestamp of the last billing event.
Name
nextBillingAt
Type
string
Description
Timestamp of the next scheduled billing.

example response

{
    "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "planName": "Pro Monthly",
    "customerEmail": "customer@example.com",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "status": "ACTIVE",
    "billingInterval": "MONTHLY",
    "lastBillingAt": "2025-09-01T00:00:00.000Z",
    "nextBillingAt": "2025-10-01T00:00:00.000Z"
}

List Subscriptions

GET /subscriptions

GET

/subscriptions

curl --location '{API_BASE_URL}/subscriptions?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

Optional query parameters: accountId, merchantId, planId, customerEmail, walletAddress.

List Subscriptions Response

Name
subscriptions
Type
array
Description
List of subscriptions.
Name
metadata
Type
object
Description
Pagination metadata with totalCount, count, page, and pageSize.

example response

{
    "subscriptions": [
        {
            "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "planName": "Pro Monthly",
            "customerEmail": "customer@example.com",
            "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
            "status": "ACTIVE",
            "billingInterval": "MONTHLY",
            "lastBillingAt": "2025-09-01T00:00:00.000Z",
            "nextBillingAt": "2025-10-01T00:00:00.000Z"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}

Get Subscription

GET /subscriptions/{subscriptionId}

GET

/subscriptions/{subscriptionId}

curl --location '{API_BASE_URL}/subscriptions/{subscriptionId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

The response is the same structure as the Create Subscription Response.

Pause Subscription

PUT /subscriptions/{subscriptionId}/pause

PUT

/subscriptions/{subscriptionId}/pause

curl --location --request PUT '{API_BASE_URL}/subscriptions/{subscriptionId}/pause' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'

Pause/Resume/Cancel Response

Name
id
Type
string
Description
Unique identifier for the subscription.
Name
status
Type
string
Description
Updated status of the subscription.

example response

{
    "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "status": "PAUSED"
}

Resume Subscription

PUT /subscriptions/{subscriptionId}/resume

PUT

/subscriptions/{subscriptionId}/resume

curl --location --request PUT '{API_BASE_URL}/subscriptions/{subscriptionId}/resume' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'

The response is the same structure as the Pause/Resume/Cancel Response.

Cancel Subscription

DELETE /subscriptions/{subscriptionId}

DELETE

/subscriptions/{subscriptionId}

curl --location --request DELETE '{API_BASE_URL}/subscriptions/{subscriptionId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'

The response is the same structure as the Pause/Resume/Cancel Response.

List Subscription Events

GET /subscriptions/{subscriptionId}/events

GET

/subscriptions/{subscriptionId}/events

curl --location '{API_BASE_URL}/subscriptions/{subscriptionId}/events' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

List Subscription Events Response

Name
events
Type
array
Description
List of events for this subscription.
Event Object
Name
timestamp
Type
string
Description
Timestamp of the event.
Name
type
Type
string
Description
Event type. One of CREATED, PAUSED, RESUMED, CANCELED, or PAYMENT_FAILED.
Name
data
Type
object
Description
Event data containing an optional reason string.
Name
metadata
Type
object
Description
Pagination metadata with totalCount, count, page, and pageSize.

example response

{
    "events": [
        {
            "timestamp": "2025-09-01T00:00:00.000Z",
            "type": "CREATED",
            "data": {
                "reason": ""
            }
        },
        {
            "timestamp": "2025-09-15T12:00:00.000Z",
            "type": "PAUSED",
            "data": {
                "reason": "Customer requested pause"
            }
        }
    ],
    "metadata": {
        "totalCount": 2,
        "count": 2,
        "page": 1,
        "pageSize": 10
    }
}

Subscription Payments

Create Subscription Payment

POST /subscriptionpayments

POST

/subscriptionpayments

curl --location '{API_BASE_URL}/subscriptionpayments' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "subscriptionId": "{SUBSCRIPTION_ID}"
}'

Create Subscription Payment Response

Name
id
Type
string
Description
Unique identifier for the subscription payment.
Name
subscriptionId
Type
string
Description
Subscription this payment belongs to.
Name
planId
Type
string
Description
Plan associated with the payment.
Name
accountId
Type
string
Description
Account ID for the payment.
Name
merchantId
Type
string
Description
Merchant ID for the payment.
Name
items
Type
array
Description
Line items for the payment, each with id, type, and amount.
Name
payments
Type
array
Description
Payment attempts, each with id, result, network, assetSymbol, address, txnHash, amount, startedAt, completedAt, and failureReason.
Name
total
Type
string
Description
Total amount for the payment.
Name
status
Type
string
Description
Payment status. One of PAID, PENDING, PARTIALLY_PAID, or FAILED.

example response

{
    "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "subscriptionId": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "items": [
        {
            "id": "item-001",
            "type": "subscription",
            "amount": "29.99"
        }
    ],
    "payments": [],
    "total": "29.99",
    "status": "PENDING"
}

List Subscription Payments

GET /subscriptionpayments

GET

/subscriptionpayments

curl --location '{API_BASE_URL}/subscriptionpayments?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

Optional query parameters: accountId, merchantId, planId, subscriptionId, customerEmail, status, from, to.

The status filter accepts: PAID, PENDING, PARTIALLY_PAID, FAILED. The from and to parameters are unix timestamps for filtering by creation date range.

List Subscription Payments Response

Name
payments
Type
array
Description
List of subscription payments.
Name
metadata
Type
object
Description
Pagination metadata with totalCount, count, page, and pageSize.

example response

{
    "payments": [
        {
            "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "subscriptionId": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
            "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "total": "29.99",
            "status": "PAID"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}

Get Subscription Payment

GET /subscriptionpayments/{paymentId}

GET

/subscriptionpayments/{paymentId}

curl --location '{API_BASE_URL}/subscriptionpayments/{paymentId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

The response is the same structure as the Create Subscription Payment Response.

Retry Subscription Payment

PUT /subscriptionpayments/{subscriptionId}/retry

PUT

/subscriptionpayments/{subscriptionId}/retry

curl --location --request PUT '{API_BASE_URL}/subscriptionpayments/{subscriptionId}/retry' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

Returns 204 No Content on success.