Create a subscription

Requires an existing customerId. Returns a subscribeUrl where the subscriber connects a wallet and authorizes the recurring pulls on-chain — an ERC-20 allowance on EVM, or a subscription against the audited @solana/subscriptions program on Solana. See Core concepts → Subscriptions.

Authorization

apiKey

X-API-Key<token>

Your merchant API key, shown once at creation in the dashboard (Settings → API key).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

offerId*string

The offer the customer is subscribing to.

Length1 <= length

priceId?string

Which pricing option on that offer to bill. Required when the offer has more than one active option — the choice is the customer's and is never guessed. Omit only when there is exactly one.

Length1 <= length

customerId*string

The payer. Create them first with POST /v1/customers — billing only starts once they hold a wallet matching the chosen chain family.

Length1 <= length

billingCycleAnchor?string

Explicit Unix timestamp or ISO-8601 string for the billing cycle anchor date.

billingCycleAnchorConfig?

Configuration object to automatically align monthly or annual renewal dates.

prorationBehavior?string

Proration behavior for period alignment ('none' | 'create_prorations').

Value in

"none"
"create_prorations"

customVariables?

Arbitrary key-value data echoed back untouched on every response and webhook for this subscription. Never interpreted by Tidepay. The only field editable after creation.

idempotencyKey?string

Your own key for this logical operation. Retrying with the same key returns the ORIGINAL subscription with 200 instead of creating a second one — which makes it safe to retry after a timeout without knowing whether the first attempt landed. Scoped per merchant and per live/test mode.

Length1 <= length <= 200

Response Body

`application/json`

curl -X POST "https://example.com/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "offerId": "offer_01j8x2q3r4s5t6u7v8w9x0y1z2",    "customerId": "cust_01j8x2q3r4s5t6u7v8w9x0y1z2"  }'

{  "id": "sub_01j8x2q3r4s5t6u7v8w9x0y1z2",  "status": "pending",  "subscribeUrl": "https://tidepay.cc/subscribe/sub_01j8x2q3r4s5t6u7v8w9x0y1z2",  "requiredAllowance": "string",  "operatorWallet": "0x71c7656ec7ab88b098defb751b7401b5f6d8976",  "tokenAddress": "string",  "mint": "string",  "chainId": 137}

Create a subscription

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

404application/json

409application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`