Offers & order bumps

Offers & order bumps endpoints of the Zanfia Workspace API, with schemas and code samples.

10 min readLast updated Jul 26, 2026

An offer is a checkout of a product; one product can have several. Order bumps are add-on offers shown at checkout. Amounts are minor units (1999 = 19.99). All routes require a Authorization: Bearer header — see Authentication.

List offers

GET/checkouts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

productId?string

Response Body

`application/json`

curl -X GET "https://example.com/checkouts"

{  "count": 0,  "checkouts": [    {      "id": "string",      "productId": "string",      "name": "string",      "slug": "string",      "title": "string",      "active": true,      "archived": true,      "isFree": true,      "priceCount": 0,      "createdAt": "string"    }  ]}

{  "error": "string"}

Create an offer

POST/checkouts

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

productId*string

isFree?boolean

Free offers cannot carry prices. Defaults to false (paid).

name?string

Response Body

`application/json`

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

{  "id": "string",  "productId": "string",  "name": "string",  "slug": "string",  "title": "string",  "active": true,  "archived": true,  "isFree": true,  "priceCount": 0,  "createdAt": "string"}

{  "error": "string"}

Offer detail

GET/checkouts/{checkoutId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Response Body

`application/json`

curl -X GET "https://example.com/checkouts/string"

{  "id": "string",  "productId": "string",  "name": "string",  "slug": "string",  "title": "string",  "active": true,  "archived": true,  "isFree": true,  "priceCount": 0,  "createdAt": "string",  "description": "string",  "language": "string",  "successUrl": "string",  "prices": [    {      "id": "string",      "productId": "string",      "amountCents": 0,      "currency": "string",      "type": "one_time",      "active": true,      "status": "available",      "gateways": [        "string"      ],      "label": "string",      "hidden": true,      "interval": "string",      "intervalCount": 0,      "trialPeriodDays": 0,      "installments": {        "numberOfCycles": 0,        "allowCancellation": true      },      "saleEndsAt": "string",      "quantityLimit": 0,      "compareAtAmountCents": 0,      "customInvoiceName": "string",      "planId": "string"    }  ],  "orderBumps": [    {      "orderBumpId": "string",      "visibleForPriceIds": [        "string"      ]    }  ]}

{  "error": "string"}

Update offer settings

PATCH/checkouts/{checkoutId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial update of an offer — the full checkout-builder settings surface. Omitted fields are unchanged.

Derived from the internal editor DTO with the composition/lifecycle fields removed: active/archived (publish + delete routes), orderBumps (attach/detach routes), and the republishHiddenProducts activation control flag. oto (the checkout's one-time-offer chain attachment) IS included — offer ids for its steps[].otoOfferId come from the /oto-offers routes; the shared Joi validator enforces the chain shape.

description is a public alias for checkoutDescription (kept from the original 5-field surface); when both are present checkoutDescription wins.

description?string

name?string

slug?string

title?string

checkoutDescription?string

checkoutImages?never

checkoutImagesMedia?never

checkoutMedia?never

checkoutMediaWidth?|

Max display width (px) of the media gallery on the checkout page. null/absent = full column width. Creator-set in the builder's Media section; the renderer applies it as a max-width, so the gallery never exceeds the layout column regardless of the value.

showTestimonials?boolean

Show a gallery of the product's approved testimonials (the wall-of-love data, product-filtered) on the checkout page. Absent = off, so existing checkouts are unchanged until the creator enables it in the builder.

language?string|null

successUrl?string|null

Deprecated

afterPurchase?|null

deadline?|null

theme?|null

invoiceAsOption?boolean

hideCountryField?boolean

showPhoneField?||

showAdditionalInfo?||

collectFirstName?boolean

Free-checkout contact fields. Email is always collected; each name field is rendered (and required) only when enabled. Absent (pre-feature docs) = both ON — readers resolve via ?? true, preserving the pre-feature form, so no migration is needed. New checkouts get explicit values from CreateCheckoutUseCase (first name on, last name off). Paid checkouts ignore these (their form always collects both names).

collectLastName?boolean

freeAccessPeriod?|

Free-offer access length. Absent/null = lifetime (pre-feature docs and the default). See FreeCheckoutAccessPeriod. Paid checkouts ignore this.

allowPromotionCode?||

forceB2B?boolean

promoteNetPrices?boolean

promoteNetPriceRate?number|null

priceVariantsPlacement?

stripeTaxBehavior?||null

paymentMethodsDisplay?array<PaymentMethodDisplayEntry> & object|

DISPLAY config — visibility + tile order of payment methods on this checkout (one-time prices only; subscriptions/installments stay card-only). null/absent = inherit default behavior (workspace defaults + implicit server order). Applied as a filter/reorder over the already-gated method list, so it can hide but never force-show a method. See applyPaymentMethodsDisplay in services/applyPaymentMethodsDisplay.ts.

showExpressCheckout?boolean

Shows the express "Quick payment" wallet section (Apple Pay / Google Pay buttons leading the form). Absent/false = hidden — legacy checkouts (which never carry the field) get no wallet section; new checkouts are created with true. Display-only: complements paymentMethodsDisplay without touching routing. Read through resolveShowExpressCheckout, which also honors the deprecated inverse field below.

allowUpgradeSubscriptionPlan?boolean

allowDowngradeSubscriptionPlan?boolean

enableClientToBuyMultipleTimes?boolean

clientMultiplePurchaseLimit?number|null

multiplePurchaseType?||null

termsUrl?string|null

privacyPolicyUrl?string|null

termsContent?string|null

privacyPolicyContent?string|null

claim?string|null

customInvoicesClient?|null

disableInvoiceIssuing?boolean

Explicit per-checkout opt-out from invoice issuance. Resolution order: customInvoicesClient set → use it; else this flag true → never issue; else fall back to WorkspaceDefaultsDocument.defaultInvoicesClient. Needed because customInvoicesClient: null means "unconfigured" (and thus inherits the workspace default once one is set), not "intentionally none".

issueReceiptWhenInvoiceIsOptIn?boolean

dontSendInvoiceToClient?boolean

customInvoiceEmailSubject?string|null

customInvoiceEmailMessage?string|null

disableEmailNotificationAboutPurchase?boolean

disableEmailNotificationAboutPurchaseToOwner?boolean

disableEmailsAboutFailedPayment?boolean

disableEmailNotificationAboutFailedPaymentClient?boolean

disableEmailsAboutCancelSubscription?boolean

disableEmailsAboutEndSubscription?boolean

disableEmailNotificationsRemindersAboutEndingAccessToClient?boolean

ownerEmailNotifications?|null

oto?|null

facebookPixelId?string|null

Deprecated

googleAnalyticsId?string|null

Deprecated

googleAnalyticsGtmId?string|null

Deprecated

metaConversionIntegrationId?string|null

Deprecated

conversionTrackingIntegrationIds?array<string> & object|

Workspace-level conversion-tracking integrations assigned to this checkout. Each ID resolves against IntegrationDocument.conversionTracking across all platform arrays (manual Meta CAPI entries, OAuth Meta sources, GA4, GTM, TikTok). Replaces the four legacy per-checkout fields below; readers fall back to them while this is absent.

conversionTrackingInheritDefaults?|

Whether this checkout inherits the workspace-default tracking integrations (IntegrationDocument.defaultConversionTrackingIntegrationIds). When unset, it's inferred: a checkout with no own assignment (and no legacy fields) inherits; an already-configured checkout does not — so existing offers keep their explicit tracking. Set explicitly when the creator toggles "use workspace defaults" vs "custom" on the offer's Tracking tab. false + an empty conversionTrackingIntegrationIds means "intentionally no tracking".

Response Body

`application/json`

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

{  "checkoutId": "string"}

{  "error": "string"}

Delete an offer

DELETE/checkouts/{checkoutId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Response Body

`application/json`

curl -X DELETE "https://example.com/checkouts/string"

{  "checkoutId": "string",  "deleted": true}

{  "error": "string"}

Activate or pause an offer

POST/checkouts/{checkoutId}/publish

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

active*boolean

true = publish (buyable); false = pause. Paid offers need a connected gateway to publish.

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/publish" \  -H "Content-Type: application/json" \  -d '{    "active": true  }'

{  "checkoutId": "string",  "active": true}

{  "error": "string"}

Duplicate an offer

POST/checkouts/{checkoutId}/duplicate

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

includePrices?boolean

Copy the price variants too (fresh gateway prices are registered).

name?string

Response Body

`application/json`

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

{  "id": "string",  "productId": "string",  "name": "string",  "slug": "string",  "title": "string",  "active": true,  "archived": true,  "isFree": true,  "priceCount": 0,  "createdAt": "string"}

{  "error": "string"}

Make this the product's default checkout

POST/checkouts/{checkoutId}/set-default

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/set-default"

{  "checkoutId": "string",  "productId": "string"}

{  "error": "string"}

Add a price variant

POST/checkouts/{checkoutId}/prices

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

installments = recurring with a fixed number of cycles (Stripe-only). recurring_payment = a fresh payment link each cycle (any gateway) — stored as a one_time price whose access window IS the billing cycle (interval/intervalCount), re-offered per endAccessStrategy (default: same price).

Value in

"one_time"
"recurring"
"recurring_payment"
"installments"

amountCents*number

Unit price in minor units. For installments: EACH payment, not the total.

currency*string

'pln' | 'usd' | 'eur' | 'gbp' (lowercase).

interval?string

Required for recurring; defaults to 'month' for installments/recurring_payment.

Value in

"day"
"week"
"month"
"year"

intervalCount?number

numberOfCycles?number

Required for installments (total number of payments, >= 2).

installmentsAllowCancellation?boolean

trialPeriodDays?number

Recurring only: free-trial days before the first charge.

label?string

customInvoiceName?string

hidden?boolean

Hidden from the public price list; buyable via direct link.

description?string

Markdown description rendered under the price.

additionalInfo?string

Short one-liner note under the price (VAT, refund policy, …).

hidePaymentMethods?boolean

Hide the small payment-method icons under the price card.

enableQuantityBuy?boolean

Let the buyer purchase multiple seats of this price in one order.

saleEndsAt?string

Time-limited sale deadline (ISO 8601 with timezone); must be in the future.

quantityLimit?number

showQuantityAvailable?boolean

compareAtAmountCents?number

Promo strike-through "was" price in minor units; must exceed amountCents.

hidePromoBadge?boolean

With compareAtAmountCents: suppress the "-X%" promo badge next to the price.

treatAsRenewalPriceOnly?boolean

One-time only: hide the price from public listings and use it exclusively as the follow-up charge when another price's access period ends.

accessInterval?string

One-time only: limited access window instead of lifetime.

Value in

"day"
"week"
"month"
"year"

accessIntervalCount?number

endAccessStrategy?ApiEndAccessStrategy

With an access window (or type recurring_payment): what happens when it ends. Defaults: cancel for one_time, same_price for recurring_payment.

Value in

"cancel"
"same_price"
"chosen_price"
"current_prices"

endAccessStrategyPriceId?string

chosen_price strategy: the id of the renewal price to offer.

endAccessConditionType?ApiEndAccessConditionType

How long a non-cancel end-access follow-up offer stays open.

Value in

"active_clients"
"unlimited"
"days_after_access_end"
"until_date"

endAccessConditionDays?number

Required with endAccessConditionType 'days_after_access_end'.

endAccessConditionDate?string

ISO date; required with endAccessConditionType 'until_date'.

renewalPriceInline?

chosen_price strategy: mint a renewal-only companion price inline.

enabledGateways?array<>

Restrict the price to these connected gateways; omit = every connected gateway. Installments/subscriptions are pinned to Stripe regardless.

stripePaymentMethods?array<>

Stripe buyer-method whitelist; listed methods stay enabled, unlisted ones are disabled for this price. Omit = all Stripe methods.

planId?string

upgradeFromPlanId?string

Marks the price as an eligibility-gated UPGRADE OFFER from the named plan (only customers currently on it can buy; hidden from the public checkout). planId then names the plan being upgraded TO.

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/prices" \  -H "Content-Type: application/json" \  -d '{    "type": "one_time",    "amountCents": 0,    "currency": "string"  }'

{  "id": "string",  "productId": "string",  "amountCents": 0,  "currency": "string",  "type": "one_time",  "active": true,  "status": "available",  "gateways": [    "string"  ],  "label": "string",  "hidden": true,  "interval": "string",  "intervalCount": 0,  "trialPeriodDays": 0,  "installments": {    "numberOfCycles": 0,    "allowCancellation": true  },  "saleEndsAt": "string",  "quantityLimit": 0,  "compareAtAmountCents": 0,  "customInvoiceName": "string",  "planId": "string"}

{  "error": "string"}

Reorder prices

PUT/checkouts/{checkoutId}/prices/order

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

priceIds*array<string>

All price ids in the new display order.

Response Body

`application/json`

curl -X PUT "https://example.com/checkouts/string/prices/order" \  -H "Content-Type: application/json" \  -d '{    "priceIds": [      "string"    ]  }'

{  "checkoutId": "string"}

{  "error": "string"}

Mutate a price

PATCH/checkouts/{checkoutId}/prices/{priceId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

priceId*string

Price id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Point mutation of an existing price. change-amount re-prices in place (fresh gateway price under the same id) keeping label/limits/promo/plan. edit-details changes label/description only; set-plan re-links the price to a product plan; edit applies the partial overrides in edit over the stored price (limits/promo/access/gateways/trial).

operation*string

Value in

"activate"
"deactivate"
"hide"
"unhide"
"change-amount"
"edit-details"
"set-plan"
"edit"

newAmountCents?number

Required for change-amount; minor units, same currency.

newLabel?string

edit-details: new display label (omit to keep).

newDescription?|

edit-details: new description; empty string or null clears it.

planId?|

set-plan: plan id on the parent product; null unlinks the plan.

edit?

edit: the partial overrides to apply.

Response Body

`application/json`

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

{  "checkoutId": "string",  "priceId": "string"}

{  "error": "string"}

Archive or remove a price

DELETE/checkouts/{checkoutId}/prices/{priceId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

priceId*string

Price id

Query Parameters

mode?string

Default"archive"

Value in

"archive"
"remove"

Response Body

`application/json`

curl -X DELETE "https://example.com/checkouts/string/prices/string"

{  "checkoutId": "string",  "priceId": "string",  "mode": "archive"}

{  "error": "string"}

Preview a cart-recovery email

POST/checkouts/{checkoutId}/sessions/{sessionId}/recovery-email/preview

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

sessionId*string

Checkout session id

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/sessions/string/recovery-email/preview"

{  "status": "ok",  "recipientEmail": "string",  "customerName": "string",  "productName": "string",  "checkoutUrl": "string",  "language": "pl"}

{  "error": "string"}

Send a cart-recovery email

POST/checkouts/{checkoutId}/sessions/{sessionId}/recovery-email

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

sessionId*string

Checkout session id

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/sessions/string/recovery-email"

{  "status": "ok",  "sentAtMs": 0,  "sentCount": 0}

{  "error": "string"}

Attach a bump to an offer

POST/checkouts/{checkoutId}/order-bumps

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orderBumpId*string

visibleForPriceIds?array<string>|

Restrict to these price variants of the offer; omit/null = all prices.

Response Body

`application/json`

curl -X POST "https://example.com/checkouts/string/order-bumps" \  -H "Content-Type: application/json" \  -d '{    "orderBumpId": "string"  }'

{  "checkoutId": "string",  "orderBumpId": "string",  "alreadyAttached": true}

{  "error": "string"}

Detach a bump from an offer

DELETE/checkouts/{checkoutId}/order-bumps/{orderBumpId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

checkoutId*string

Offer (checkout) id

orderBumpId*string

Order bump id

Response Body

`application/json`

curl -X DELETE "https://example.com/checkouts/string/order-bumps/string"

{  "checkoutId": "string",  "orderBumpId": "string"}

{  "error": "string"}

List order bumps

GET/order-bumps

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/order-bumps"

{  "count": 0,  "orderBumps": [    {      "id": "string",      "name": "string",      "description": "string",      "ctaText": "string",      "productId": "string",      "productName": "string",      "priceId": "string",      "price": {        "amountCents": 0,        "currency": "string",        "type": "one_time"      },      "createdAt": "string"    }  ]}

{  "error": "string"}

Create an order bump

POST/order-bumps

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

productId*string

priceId*string

name*string

description?string

ctaText?string

appearance?

Appearance/styling of the bump box on the checkout page. All fields optional — absent fields keep the dashboard defaults (create) or the current values (update). media: null clears the media slot.

Response Body

`application/json`

curl -X POST "https://example.com/order-bumps" \  -H "Content-Type: application/json" \  -d '{    "productId": "string",    "priceId": "string",    "name": "string"  }'

{  "orderBumpId": "string"}

{  "error": "string"}

Update an order bump

PATCH/order-bumps/{orderBumpId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

orderBumpId*string

Order bump id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

description?string

ctaText?string

productId?string

priceId?string

appearance?

Response Body

`application/json`

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

{  "orderBumpId": "string"}

{  "error": "string"}

Delete an order bump

DELETE/order-bumps/{orderBumpId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

orderBumpId*string

Order bump id

Response Body

`application/json`

curl -X DELETE "https://example.com/order-bumps/string"

{  "orderBumpId": "string"}

{  "error": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

List offers

200application/json

4XXapplication/json

Create an offer

200application/json

4XXapplication/json

Offer detail

200application/json

4XXapplication/json

Update offer settings

200application/json

4XXapplication/json

Delete an offer

200application/json

4XXapplication/json

Activate or pause an offer

200application/json

4XXapplication/json

Duplicate an offer

200application/json

4XXapplication/json

Make this the product's default checkout

200application/json

4XXapplication/json

Add a price variant

200application/json

4XXapplication/json

Reorder prices

200application/json

4XXapplication/json

Mutate a price

200application/json

4XXapplication/json

Archive or remove a price

200application/json

4XXapplication/json

Preview a cart-recovery email

200application/json

4XXapplication/json

Send a cart-recovery email

200application/json

4XXapplication/json

Attach a bump to an offer

200application/json

4XXapplication/json

Detach a bump from an offer

200application/json

4XXapplication/json

List order bumps

200application/json

4XXapplication/json

Create an order bump

200application/json

4XXapplication/json

Update an order bump

200application/json

4XXapplication/json

Delete an order bump

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`