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 custom-price links
- Retrieve a custom-price link
- Create a custom-price link
- Update a custom-price link
- Archive a custom-price link
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.
Custom-price links and promotion codes
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_purchasesstops the link after that many purchases.nullmeans no cap. 1–1,000,000.expires_atstops the link at that moment.nullmeans 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.
| Status | Meaning |
|---|---|
active | The link sells today. |
used_up | purchases_count has reached max_purchases. |
expired | expires_at has passed. |
archived | The 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.
Custom-price Link Object
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Link UUID. |
product_id | string | No | UUID of the product the link sells. |
variant_id | string | Yes | Pinned one-time variant UUID. null uses the product's default one-time variant. See Variant. |
amount | integer | No | Price charged through the link, in minor units (e.g. cents). Minimum 0. |
currency | string | No | The product's currency, lowercase ISO 4217. Read-only. |
is_net | boolean | No | Whether amount is net, with tax added at checkout. |
max_purchases | integer | Yes | Purchase cap. null means no cap. |
purchases_count | integer | No | Orders placed through the link. See Purchases count. |
expires_at | string | Yes | When the link stops selling (ISO 8601). null means no expiry. |
archived_at | string | Yes | When the link was archived (ISO 8601). null until archived. |
status | string | No | active, used_up, expired, or archived. See Status. |
checkout_url | string | No | Signed checkout link to share. See Checkout URL. |
created_at | string | No | Creation timestamp (ISO 8601). |