Skip to main content

Custom-price Links

A custom-price link is a shareable checkout link that sells one product at an amount you choose. A link can stop selling after a number of purchases, at a set moment, or both, and can be archived to stop it at once.

Path {productId} is the product the link sells. Each link keeps its own usage count and status, and its checkout_url is the link to share.

Overview​

List and create are nested under the product. Get, update, and archive use the flat /custom-price-links/{id} path. There is no draft twin — links always sell the live product.

A custom-price link fixes the price of one product. The buyer opens the link and pays amount — there is nothing to type at checkout.

A promotion code is a string the buyer enters at checkout. It applies a discount, and can cover several products or the whole store.

Amount and currency​

amount is the price charged through the link, in minor units (e.g. cents) of the product's currency. currency is always the product's currency and is read-only. amount can be 0.

is_net: true means amount is a net price and tax is added at checkout. Omit it on create for a gross price.

amount, is_net, and variant_id cannot change after create. For a different price, create a new link and archive the old one.

Checkout URL​

checkout_url is the signed link to share. It opens checkout at amount and is returned on every read and write. Changing any of its query parameters invalidates the signature — share it exactly as returned.

The link only sells while the product is published. A link can be created for an unpublished product.

Variant​

variant_id pins the link to one variant of the product. null means checkout uses the product's default one-time variant.

A pinned variant must be a published one-time variant of this product that is currently on sale — inside its active_from / active_until window. Hidden variants (is_hidden: true) are allowed, so a hidden variant can act as the price a link sells. Recurring and archived variants cannot be pinned. See Product Variants.

Limits​

  • max_purchases stops the link after that many purchases. null means no cap. 1–1,000,000.
  • expires_at stops the link at that moment. null means no expiry. It must be in the future when you send it.

The link stops selling at whichever limit is reached first. Update changes either limit, and null removes it. Raising the cap on a used_up link, or moving the expiry of an expired link into the future, makes it sell again.

Send expires_at as an RFC 3339 timestamp with an offset, e.g. 2026-12-31T23:59:00-05:00. Responses can express the same instant with a different offset.

Purchases count​

purchases_count counts orders placed through the link, one per order:

  • refunded orders still count;
  • checkouts started in the last 30 minutes that are still awaiting payment also count, so the number can briefly include a purchase that is later abandoned.

A link with a cap therefore reports used_up while the last few checkouts are still in progress.

Status​

status is derived from the limits and archive state. It is also a list filter.

StatusMeaning
activeThe link sells today.
used_uppurchases_count has reached max_purchases.
expiredexpires_at has passed.
archivedThe link was archived. Irreversible.

When more than one applies, archived wins over expired, which wins over used_up. An archived link with a past expiry reports archived.

Archive​

Archive stops the link selling at once and sets archived_at. There is no unarchive. An archived link stays in the list and can be read by id, but it cannot be updated — PATCH returns 422.

Test-mode products​

List and create return 422 for a product in test mode. Custom-price links for test-mode products are managed in the dashboard.

FieldTypeNullableDescription
idstringNoLink UUID.
product_idstringNoUUID of the product the link sells.
variant_idstringYesPinned one-time variant UUID. null uses the product's default one-time variant. See Variant.
amountintegerNoPrice charged through the link, in minor units (e.g. cents). Minimum 0.
currencystringNoThe product's currency, lowercase ISO 4217. Read-only.
is_netbooleanNoWhether amount is net, with tax added at checkout.
max_purchasesintegerYesPurchase cap. null means no cap.
purchases_countintegerNoOrders placed through the link. See Purchases count.
expires_atstringYesWhen the link stops selling (ISO 8601). null means no expiry.
archived_atstringYesWhen the link was archived (ISO 8601). null until archived.
statusstringNoactive, used_up, expired, or archived. See Status.
checkout_urlstringNoSigned checkout link to share. See Checkout URL.
created_atstringNoCreation timestamp (ISO 8601).