Update an offer

Presentation, addressing, distribution limits and lifecycle only. pricing is NOT patchable: an existing option's terms are immutable, because a subscriber's on-chain authorization is sized against the amount in force when they subscribed. Add an option with POST /offers/{offerId}/pricing, retire one with DELETE /offers/{offerId}/pricing/{priceId}, and move an existing subscriber with POST /subscriptions/{subscriptionId}/migrate.

Authorization

apiKey

X-API-Key<token>

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

In: header

Path Parameters

offerId*string

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

active?boolean

Deactivating hides the offer from new checkouts; existing subscriptions keep billing.

Response Body

`application/json`

curl -X PATCH "https://example.com/offers/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "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"}

Update an offer

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`