Skip to content

Merchant API - Subscriptions ​

Overview ​

The Subscriptions API lets you create on-chain recurring billing plans, enroll subscribers, and manage subscription links, payments, and invitations for recurring cryptocurrency payments. Billing terms (amount, interval, trial period, grace period) are anchored on-chain via a signed plan digest; a subscription link represents an individual subscriber's enrollment and on-chain approval to be billed.

Base URL: https://sandboxapi.bitxpay.com/api/v1

The API is split into two route groups with different authentication requirements:

GroupPath PrefixesAuthentication
Authenticated (Merchant) Routes/merchant/subscription_plans, /merchant/subscribers, /merchant/subscribers/invitations, /merchant/subscription_linksMerchant API Key + Ed25519 (EdDSA) signature — same scheme as the Payments API
Public Routes/public/subscriptions/plans, /public/subscriber, /public/subscriptions/link, /public/subscriptions/nftNo merchant signature — called directly from the customer-facing wallet/checkout flow

Plan Billing Models ​

The merchant create-plan service currently registers token-based plans using token and amount (a string in token base units). Although the shared request DTO also contains currency, value, period, currency_id, and kind, the merchant service does not use those fields to register a value-based plan. A request without token is rejected.


Subscription Plan Statuses ​

StatusDescription
activePlan is live and can accept new subscribers
inactivePlan is inactive

Deprecation is represented separately by is_deprecated and deprecated_at. The Merchant API does not mount a DELETE/deprecate route.

Subscriber Statuses ​

StatusDescription
invitation_sentSubscriber created, awaiting on-chain confirmation
subscribedSubscriber accepted the invitation
rejectedSubscriber rejected the invitation
expiredInvitation expired
cancelledSubscription cancelled

This is the canonical subscriber status set referenced by every subscriber endpoint on this page.

Billing Intervals ​

interval and trial_period are durations in seconds. max_arrears and auto_cancel_after_missed are counts, and subscribe_deadline is an integer enrollment deadline. Common interval values:

NameSeconds
Daily86400
Weekly604800
Monthly2592000
Quarterly7776000
Yearly31536000

Authenticated (Merchant) Routes ​

All endpoints in this section require Merchant API Key authentication with an Ed25519 (EdDSA) request signature (RSA-PSS accepted for legacy keys):

X-API-Key: btxm_9b451fa04a2e
X-API-Signature: <base64_encoded_ed25519_signature>
X-API-Timestamp: 2026-01-31T12:00:00Z
Content-Type: application/json

Success responses in this section wrap the documented response object in {"message": "...", "data": ...}. Creation returns HTTP 201; reads and updates return 200. Paths are relative to /api/v1; sign the full actual path, including any trailing slash.

Subscription Plans — /merchant/subscription_plans ​

1. Create Subscription Plan ​

POST /merchant/subscription_plans/

Request Body:

FieldTypeRequiredDescription
network_idstring (UUID)NoBlockchain network ID
currency_idstring (UUID)NoPresent in the shared DTO; not persisted by the merchant create service
merchantstringYesMerchant on-chain address
destinationstringYesDestination address for collected funds
tokenstringYesToken contract address
amountstringYesBilling amount in token base units
currencystringNoNot used by the merchant create service
valuestringNoNot used by the merchant create service
periodintegerNoPresent in the shared DTO; use interval for merchant plans
intervalintegerYesBilling interval (seconds)
trial_periodintegerNoTrial period (seconds)
max_arrearsintegerYesMaximum arrears count, 1–255
auto_cancel_after_missedintegerNoNumber of missed payments before auto-cancellation
subscribe_deadlineintegerNoDeadline for the subscriber to complete on-chain enrollment (seconds)
plan_nonceintegerYesNon-zero on-chain plan nonce; unique per merchant
merchant_sigstringYesMerchant's on-chain signature over the plan digest
metadata_uristringNoURI to off-chain plan metadata
namestringYesPlan name
descriptionstringNoPlan description
kindstring (SubscriptionPlanType)NoPresent in the shared DTO; not persisted by the merchant create service

Use token + amount for this merchant endpoint. Include the required signed plan fields even when a client SDK has older plan types.

Response data (SubscriptionPlanResponse): Optional fields such as network, token, currency_id, plan_id, digest, source, and deprecated_at are omitted when unavailable. The merchant service does not populate on-chain identifiers merely by registering the plan.

json
{
  "id": "uuid",
  "merchant_id": "uuid",
  "network_id": "uuid",
  "chain_id": 0,
  "network": { "id": "uuid", "name": "string", "chain_id": 0, "symbol": "string", "is_active": true, "created_at": "", "updated_at": "" },
  "merchant_address": "string",
  "destination_address": "string",
  "token": "string",
  "currency_id": "uuid",
  "currency": "string",
  "currency_symbol": "string",
  "amount": "string",
  "formatted_amount": "string",
  "interval": 0,
  "trial_period": 0,
  "max_arrears": 0,
  "auto_cancel_after_missed": 0,
  "subscribe_deadline": 0,
  "plan_nonce": 0,
  "plan_id": "string",
  "digest": "string",
  "revoked": false,
  "source": "string",
  "metadata_uri": "string",
  "name": "string",
  "description": "string",
  "is_deprecated": false,
  "deprecated_at": "",
  "status": "active",
  "total_subscribers": 0,
  "active_subscribers": 0,
  "trial_subscribers": 0,
  "failed_subscribers": 0,
  "subscribers": [],
  "created_at": "",
  "updated_at": ""
}

Error Responses:

StatusErrorDescription
400Bad RequestInvalid request payload, missing token, or duplicate merchant plan nonce
401UnauthorizedMissing or invalid API key/signature
500Internal Server ErrorServer error

2. List Subscription Plans ​

GET /merchant/subscription_plans/

Query Parameters:

ParameterTypeDescription
pageintegerPage number
page_sizeintegerResults per page
searchstringSearch by plan name
deprecatedbooleanFilter by deprecated status
start_datedatetimeFilter by creation date range start
end_datedatetimeFilter by creation date range end

Response (SubscriptionPlanListResponse):

json
{
  "plans": [ { "...": "SubscriptionPlanResponse, see #1" } ],
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0
}

3. Get Subscription Plan ​

GET /merchant/subscription_plans/:id

Path Parameters: id (UUID)

Response: SubscriptionPlanResponse (same shape as #1)

Error Responses:

StatusErrorDescription
401UnauthorizedMissing or invalid API key/signature
404Not FoundPlan not found
500Internal Server ErrorServer error

4. Update Subscription Plan ​

PUT /merchant/subscription_plans/:id

Path Parameters: id (UUID)

Request Body:

FieldTypeRequiredDescription
namestringNoUpdated plan name
metadata_uristringNoUpdated metadata URI
statusstring (SubscriptionPlanStatus)Noactive or inactive

Response: SubscriptionPlanResponse (same shape as #1)

Error Responses:

StatusErrorDescription
400Bad RequestInvalid request payload
401UnauthorizedMissing or invalid API key/signature
404Not FoundPlan not found
500Internal Server ErrorServer error

5. Plan Deprecation ​

The Merchant API mounts POST, GET, and PUT for plans. Deprecation through DELETE /subscriptions/plans/:id belongs to the dashboard session API and is not available with merchant API-key authentication.


Subscribers — /merchant/subscribers ​

6. Create Subscriber ​

POST /merchant/subscribers/

Request Body:

FieldTypeRequiredDescription
subscription_plan_idstring (UUID)YesPlan to subscribe to
customer_idstringNoYour internal customer identifier
customer_namestringNoCustomer's full name
customer_emailstringNoCustomer's email address
webhook_metadataobjectNoCopied to subscription creation/invitation events; not automatically included in renewal event DTOs
failure_return_urlstringNoURL to redirect to on failed enrollment
success_return_urlstringNoURL to redirect to on successful enrollment

Create response (201): data contains subscriber (the stored subscriber model) and subscription_link (the customer enrollment URL). The raw model uses capitalized Status and WebhookMetadata; customer fields, return URLs, and timestamps use snake_case. Single-subscriber get/update endpoints also return this raw model. List endpoints use the SubscriberResponse DTO shown below.

json
{
  "message": "Subscriber created successfully",
  "data": {
    "subscriber": {
      "id": "5d17b0c4-b32c-40dd-a2e2-8ace612251c7",
      "subscription_plan_id": "6f03697c-eb8d-49f2-9ac1-bca1cbe58a4c",
      "merchant_user_id": "11111111-1111-1111-1111-111111111111",
      "customer_name": "John Doe",
      "customer_email": "customer@example.com",
      "Status": "invitation_sent"
    },
    "subscription_link": "https://pay.bitxpay.com/subscriptions/subscription_link?subscription_id=5d17b0c4-b32c-40dd-a2e2-8ace612251c7"
  }
}

The example omits other stored model fields. Include customer_name and customer_email for merchant creation: the notification service currently reads both values without a nil check, despite their being optional in the shared DTO.

List item data (SubscriberResponse):

json
{
  "id": "uuid",
  "subscription_plan_id": "uuid",
  "merchant_user_id": "uuid",
  "customer_id": "string",
  "customer_name": "string",
  "customer_email": "string",
  "subscription_link_url": "string",
  "status": "invitation_sent",
  "subscription_plan": { "...": "SubscriptionPlan model" },
  "subscription_link": { "...": "SubscriptionLink model" },
  "webhook_metadata": {},
  "created_at": "",
  "updated_at": ""
}

Error Responses:

StatusErrorDescription
400Bad RequestInvalid request payload or missing required fields
401UnauthorizedMissing or invalid API key/signature
404Not FoundSubscription plan ID not found
500Internal Server ErrorServer error

7. Get Subscribers By Merchant ​

GET /merchant/subscribers/

Query Parameters:

ParameterTypeDescription
plan_idstring (UUID)Filter by subscription plan
searchstringSearch by customer name/email
start_datedatetimeFilter by creation date range start
end_datedatetimeFilter by creation date range end
pageintegerPage number (default 1)
page_sizeintegerResults per page (default 10)

Response (SubscriberListResponse):

json
{
  "subscribers": [ { "...": "SubscriberResponse, see #6" } ],
  "data": null,
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0
}

8. Get Subscribers By Plan ID ​

GET /merchant/subscribers/plan/:plan_id

Path Parameters: plan_id (UUID)

Response: data is a SubscriberListResponse object with subscribers and total. It returns all matches; page, page_size, and total_pages are zero, and the unused legacy data field is null.


9. Update Subscriber ​

PUT /merchant/subscribers/:id

Path Parameters: id (UUID)

Request Body:

FieldTypeRequiredDescription
customer_namestringNoUpdated customer name
customer_emailstringNoUpdated customer email
statusstring (SubscriberStatus)NoNew subscriber status

Response: The stored subscriber model described in #6, including capitalized Status and WebhookMetadata. Merchant responses wrap it in data; public responses return it directly.

Error Responses:

StatusErrorDescription
400Bad RequestInvalid request payload
401UnauthorizedMissing or invalid API key/signature
404Not FoundSubscriber not found
500Internal Server ErrorServer error

10. Get Subscriber By ID ​

GET /merchant/subscribers/:id

Path Parameters: id (UUID)

Response: The stored subscriber model described in #6, including capitalized Status and WebhookMetadata. Merchant responses wrap it in data; public responses return it directly.

Error Responses:

StatusErrorDescription
401UnauthorizedMissing or invalid API key/signature
404Not FoundSubscriber not found
500Internal Server ErrorServer error

Invitations — /merchant/subscribers/invitations ​

11. Get Invitations ​

GET /merchant/subscribers/invitations

Query Parameters: page, page_size, search, plan_id, start_date, end_date, sort_order (same list-filter DTO as subscribers).

Response (InvitationListResponse):

json
{
  "invitations": [ { "...": "SubscriberResponse, see #6" } ],
  "data": null,
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0
}

GET /merchant/subscription_links/

Query Parameters:

ParameterTypeDescription
pageintegerPage number
page_sizeintegerResults per page
searchstringSearch term
is_activebooleanFilter by active status
plan_idstring (UUID)Filter by subscription plan
start_datedatetimeFilter by creation date range start
end_datedatetimeFilter by creation date range end

Response (SubscriptionLinkListResponse):

json
{
  "links": [ { "...": "SubscriptionLinkResponse, see #13" } ],
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0
}

GET /merchant/subscription_links/:id

Path Parameters: id (UUID)

Response (SubscriptionLinkResponse):

json
{
  "id": "uuid",
  "merchant_user_id": "uuid",
  "subscription_plan_id": "uuid",
  "subscribed_at": "",
  "trial_ends_at": "",
  "wallet_address": "string",
  "subscribe_hash": "string",
  "approvals": [ { "...": "ApprovalDetail" } ],
  "owed": "string",
  "paid_periods": 0,
  "locked": false,
  "customer_id": "string",
  "customer_email": "string",
  "customer_name": "string",
  "expires_at": "",
  "is_active": true,
  "subscription_transactions": [ { "...": "SubscriptionResponse; see Request and Response Fields" } ],
  "plan": { "...": "SubscriptionPlanSummary" },
  "created_at": "",
  "updated_at": ""
}

Public Routes ​

Public controllers return their response data directly, without the merchant message/data wrapper, except where explicitly documented below. The endpoints in this section are called directly from the customer-facing wallet/checkout flow and do not require X-API-Key/X-API-Signature headers. Record Subscription Payment additionally requires a merchant_key reference in the body; this is separate from request-signature authentication.

Subscription Plans — /public/subscriptions/plans ​

14. List Public Subscription Plans ​

GET /public/subscriptions/plans/

Query parameters: page, page_size, search, deprecated, start_date, end_date (same filters as the merchant plan list).

Response: SubscriptionPlanListResponse (same shape as #2)


15. Get Public Subscription Plan ​

GET /public/subscriptions/plans/:id

Path Parameters: id (UUID)

Response: SubscriptionPlanResponse (same shape as #1)


Subscribers — /public/subscriber ​

16. Prepare Subscription ​

GET /public/subscriber/prepare

Query parameters: subscriber_id (required UUID) and wallet_address (customer wallet address).

Returns an unwrapped object with subscriber_id, plan_id, wallet_address, currency, value, and networks. Each network contains chain_id and tokens; tokens include address, symbol, decimals, quotable, and optional price, amount, or error. Use this treasury-supported selection when preparing enrollment. Invalid subscriber IDs return 400; missing subscribers/plans return 404.


17. Get Subscriber By ID ​

GET /public/subscriber/:id

Path Parameters: id (UUID)

Response: The stored subscriber model described in #6, including capitalized Status and WebhookMetadata. Merchant responses wrap it in data; public responses return it directly.


18. Update Subscriber ​

PUT /public/subscriber/:id

Path Parameters: id (UUID)

Request Body: UpdateSubscriberRequest (same fields as #9)

Response: The stored subscriber model described in #6, including capitalized Status and WebhookMetadata. Merchant responses wrap it in data; public responses return it directly.


POST /public/subscriptions/link/

Request Body:

FieldTypeRequiredDescription
subscription_plan_idstring (UUID)YesPlan being subscribed to
subscriber_idstring (UUID)NoAssociated subscriber ID
subscription_onchain_idintegerNoOn-chain subscription ID
subscribed_attimestampNoSubscription start time
trial_ends_attimestampNoTrial end time
wallet_addressstringYesCustomer's wallet address
subscribe_hashstringYesOn-chain subscription transaction hash
owedstringNoAmount currently owed
paid_periodsintegerNoNumber of billing periods paid
lockedbooleanNoWhether the link is locked from further updates
approvalsarrayYesOn-chain token approval details (at least 1 required)
customer_idstringNoYour internal customer identifier
customer_emailstringNoCustomer's email address
customer_namestringNoCustomer's full name
expires_attimestampNoLink expiration time

approvals[] fields:

FieldTypeRequiredDescription
approval_hashstringNoOn-chain approval transaction hash
token_addressstringYesApproved token contract address
amount_approvedstringYesApproved amount (raw units)
network_namestringYesBlockchain network name
chain_idintegerYesNon-zero chain ID
decimalsintegerYesNon-zero token decimals

Response: SubscriptionLinkResponse (same shape as #13)


GET /public/subscriptions/link/:walletAddress

Path Parameters: walletAddress (string)

Response: { "data": [...], "total": 0 }, where data holds stored subscription link models. This wallet lookup is not the paginated merchant link DTO. No matches return 404.


21. Record Subscription Payment ​

POST /public/subscriptions/link/payment

Request Body:

FieldTypeRequiredDescription
sub_link_idstring (UUID)YesSubscription link ID
merchant_keystringYesMerchant reference stored with the payment record
tx_hashstringYesBlockchain transaction hash
block_numberintegerNoBlock number the transaction was included in
block_hashstringNoBlock hash
network_idstring (UUID)YesBlockchain network ID
currency_idstring (UUID)YesCurrency ID
amount_paidstringYesAmount paid
wallet_usedstringYesWallet address the payment was made from

Response (200):

json
{
  "message": "Payment recorded successfully"
}

This endpoint returns an acknowledgement rather than a subscription payment DTO.


PUT /public/subscriptions/link/:id

Path Parameters: id (UUID)

Request Body:

FieldTypeRequiredDescription
trial_ends_attimestampNoUpdated trial end time
customer_emailstringNoUpdated customer email
customer_namestringNoUpdated customer name
expires_attimestampNoUpdated expiration time
is_activebooleanNoUpdated active status
lockedbooleanNoUpdated locked status
owedstringNoUpdated amount owed

Response: SubscriptionLinkResponse (same shape as #13)


NFT Metadata — /public/subscriptions/nft ​

23. Get Subscription NFT Metadata ​

GET /public/subscriptions/nft/:plan_id

Path Parameters: plan_id (UUID)

Response (SubscriptionMetaResponse):

json
{
  "name": "string",
  "description": "string",
  "image": "string",
  "external_url": "string",
  "attributes": [
    { "trait_type": "string", "value": "string" }
  ]
}

Rate Limiting ​

The mounted subscription routes use payment/default rate limiters, both configured to 100 requests per minute in this checkout. Limiter identity falls back to client IP when no recognized user/API-key context is available. Handle HTTP 429 and honor Retry-After when present; deployment settings may differ.


Common Use Cases ​

Create a Subscription Plan ​

bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/merchant/subscription_plans/ \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <base64_encoded_ed25519_signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3",
    "destination": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3",
    "token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
    "amount": "100000",
    "interval": 2592000,
    "max_arrears": 1,
    "plan_nonce": 1,
    "merchant_sig": "<merchant_onchain_signature>",
    "name": "Pro Plan Monthly"
  }'

Create a Subscriber ​

bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/merchant/subscribers/ \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <base64_encoded_ed25519_signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_plan_id": "6f03697c-eb8d-49f2-9ac1-bca1cbe58a4c",
    "customer_id": "cust-001",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe"
  }'
bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/public/subscriptions/link/ \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_plan_id": "6f03697c-eb8d-49f2-9ac1-bca1cbe58a4c",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3",
    "subscribe_hash": "0xa1b2c3d4e5f60789a1b2c3d4e5f60789a1b2c3d4e5f60789a1b2c3d4e5f60781",
    "approvals": [
      {
        "token_address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
        "amount_approved": "100000",
        "network_name": "arbitrum",
        "chain_id": 42161,
        "decimals": 6
      }
    ]
  }'

Record a Subscription Payment (Public) ​

bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/public/subscriptions/link/payment \
  -H "Content-Type: application/json" \
  -d '{
    "sub_link_id": "5d17b0c4-b32c-40dd-a2e2-8ace612251c7",
    "merchant_key": "btxm_9b451fa04a2e",
    "tx_hash": "0xa1b2c3d4e5f60789a1b2c3d4e5f60789a1b2c3d4e5f60789a1b2c3d4e5f60785",
    "network_id": "0b4f3bab-4354-4373-9821-c8665fffbca3",
    "currency_id": "d4e5f6a7-8b9c-4d1e-9f2a-3b4c5d6e7f80",
    "amount_paid": "49.99",
    "wallet_used": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3"
  }'

Webhooks ​

Configure active subscriptions in the dashboard. Subscription event codes defined by the backend are subscription_plan.created, subscription_invitation.created, subscription.created, subscription.renewed, and subscription.renewal_failed. Availability depends on the operation and enabled catalog entries.

See the event data reference for exact fields and emission behavior. Merchant subscriber creation emits subscription.created before on-chain enrollment; dashboard subscriber creation emits subscription_invitation.created. The plan-created and renewal event DTOs exist, but this checkout has no automatic producers for those three event types. Use the test-notification API to exercise them. See the Webhooks Guide for signature verification.


Support ​

For questions or issues: