Create an offer

Creates a sellable offer with one or more pricing options and returns its checkoutUrl. This is a single call — there is no separate plan or paylink to create first. idempotencyKey is optional; a retried request with the same key returns the original offer with 200 instead of creating a duplicate.

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.

name*string

What you are selling, shown as the heading at checkout. This is also what a subscription snapshots as its display name, so it survives the offer being renamed later.

Length1 <= length <= 200

description?string

Shown at checkout beneath the name. Plain text — no markdown or HTML rendering.

Lengthlength <= 1000

imageUrl?string

Cover image shown at checkout. Must be a publicly reachable HTTPS URL — Tidepay does not host or proxy it.

Formaturi

identifier?string

Your own stable slug for this offer, so you can address it without storing Tidepay's opaque id: GET /v1/offers?identifier=pro. Unique per merchant — reusing one returns 409. Lowercase letters, numbers, underscores and hyphens only.

Match^[a-z0-9_-]+$

Length1 <= length <= 100

productRef?string

Free-text reference to this product in your own catalog. Purely informational — never validated for uniqueness or format, and never interpreted by Tidepay. Use identifier if you need to look the offer up.

Lengthlength <= 200

features?array<>

Descriptive bullet points listed at checkout (e.g. "2 classes per week"). Display and entitlement metadata only — these NEVER affect what is billed. Max 20 entries.

Itemsitems <= 20

collectFields?

Personal details the checkout collects from the payer before they connect a wallet. Every field is opt-in: omit a key (or the whole object) and it is not asked for. Only request what you actually need — each field is one more step between the buyer and paying.

allowedPaymentMethods?

Which checkout methods this offer accepts. Omit for both. Enabling walletTransfer on an offer with recurring pricing is rejected: a recurring charge needs a standing on-chain authorization, which only walletConnect grants.

availableQuantity?integer

Total successful checkouts this offer allows, ever — not a remaining count (track that via redeemedCount in the response). Once reached, the offer deactivates itself and its checkout URL returns 404. Omit for unlimited.

Range0 < value <= 1000000

expiresAt?string

ISO-8601 timestamp after which checkout returns 404, exactly as a deactivated offer does. Existing subscriptions keep billing — this closes the offer to NEW buyers, it does not end what was already sold.

afterCompletion?|

Where the buyer lands once payment settles: a hosted success page (optionally with your own message), or a redirect to a URL you own. Defaults to the hosted page.

metadata?

Arbitrary key-value data echoed back on every response and webhook for this offer. Never read or interpreted by Tidepay — it exists so you can correlate an offer with your own systems.

reference?string

Short external reference string, e.g. your own order id. Not required to be unique, and not usable to look the offer up — see identifier for that.

Lengthlength <= 200

pricing*array<>

One or more pricing options. The customer picks one at checkout.

Items1 <= items <= 20

idempotencyKey?string

Your own key for this logical operation. Retrying with the same key returns the ORIGINAL offer with 200 instead of creating a second one — and, critically, without re-creating its pricing options or re-publishing their on-chain objects. Scoped per merchant and per live/test mode.

Length1 <= length <= 200

Response Body

`application/json`

curl -X POST "https://example.com/offers" \  -H "Content-Type: application/json" \  -d '{    "name": "Pro",    "pricing": [      {        "amount": "30",        "acceptedTokens": [          "usdc-base"        ],        "billing": {          "type": "one_time"        }      }    ]  }'

{  "id": "offer_01j8x2q3r4s5t6u7v8w9x0y1z2",  "name": "Pro",  "description": "string",  "imageUrl": "string",  "identifier": "pro",  "productRef": "SKU-1234",  "checkoutUrl": "https://tidepay.cc/pay/a8f3k2",  "pricing": [    {      "id": "price_01j8x2q3r4s5t6u7v8w9x0y1z3",      "label": "Monthly",      "amount": "30",      "currency": "USDC",      "billing": {        "type": "recurring",        "interval": "month"      },      "acceptedTokens": [        {          "tokenKey": "usdc-polygon",          "chainId": 8453,          "amountBaseUnits": "30000000"        }      ],      "trialDays": 7,      "maxCycles": 12,      "maxFailedCycles": 3,      "active": true    }  ],  "active": true,  "availableQuantity": 100,  "redeemedCount": 12,  "expiresAt": "2026-08-19T14:32:00.000Z",  "afterCompletion": {    "property1": null,    "property2": null  },  "features": [    {      "property1": null,      "property2": null    }  ],  "collectFields": {    "property1": null,    "property2": null  },  "allowedPaymentMethods": {    "property1": null,    "property2": null  },  "metadata": {    "orderId": "12345"  },  "reference": "ORDER-2024-001",  "isSandbox": true,  "createdAt": "2026-08-19T14:32:00.000Z",  "updatedAt": "2026-08-19T14:32:00.000Z"}

Create an offer

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

409application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`