Products and payment links

A product is an item in your catalogue. It has one of two pricing modes, chosen at create and fixed for life:

Either kind can be sold two ways:

• through checkout sessions, which know which of your users is paying (checkout-sessions); or
• through its payment link, https://thru.la/pay/<slug>, which anyone can open and pay, anonymously.

Every product is a one-off charge. Each purchase is a separate payment.

Create a fixed-price product

curl -X POST https://api.thru.la/v1/products \
  -H "x-api-key: $THRU_API_KEY" -H "content-type: application/json" \
  -d '{"name":"Pro plan, 30 days","kind":"one_off","chain":"bnb","network":"mainnet","token":"USDC","price":"20","networks":[{"chain":"bnb","token":"USDC","price":"20"},{"chain":"sui","token":"USDC","price":"20"}],"successUrl":"https://example.com/billing/done","cancelUrl":"https://example.com/billing"}'

The response is the product. Its slug is generated by the server from the name plus 6 random hex characters (for example pro-plan-30-days-4f1c2a). You cannot choose it, so read it from the response or the console.

Create a custom-amount product

One product sells every amount. Use it for credit, top-ups and anything else where the buyer, or your server, decides the number.

curl -X POST https://api.thru.la/v1/products \
  -H "x-api-key: $THRU_API_KEY" -H "content-type: application/json" \
  -d '{"name":"Account credit","kind":"one_off","pricingMode":"custom_amount","chain":"bnb","network":"mainnet","token":"USDC","minAmount":"1","maxAmount":"500","networks":[{"chain":"bnb","token":"USDC"},{"chain":"sui","token":"USDC"}],"successUrl":"https://example.com/credit/done","cancelUrl":"https://example.com/credit"}'

The differences from a fixed-price product:

The amount maps 1:1 to token units on the rail the buyer picks. A custom-amount product charges its amount as that many tokens of the chosen rail, with no conversion: a $37 session on a USDC rail asks for 37 USDC, and on a BNB rail it asks for 37 BNB. Native coins in the registry (BNB, SUI, ETH) pass the create check, so the API will not stop you from listing one. For USD credit, list USD stablecoins only (USDC, USDT, USDG, …), and only where supported-chains marks the pair live: USDT on bnb testnet is refused because no such token is registered there, and USDC on base is registered but not watched. A fixed-price product has none of these restrictions: a plan may still be priced in ETH.

The effective minimum is the larger of your minAmount and thru's own floor of 0.01. There is no thru-wide or per-chain minimum above that. Whatever the effective minimum is, the API reports it in the 400 for an amount that is too small, and GET /v1/public/products/:slug reports it to the page, so a buyer never learns about a limit after sending funds.

Precision. Every amount on a custom-amount product (minAmount, maxAmount, a session's amount, a buyer's amount) is a decimal string matching ^\d{1,20}(\.\d{1,2})?$: at most two decimal places, no sign, no exponent, no whitespace, and at least 0.01. "37", "37.5" and "37.50" are all accepted and all mean the same amount.

The product object

Every product response is the row: id, merchantId, slug, name, description, imageUrl, kind, chain, network, token, price, pricingMode, minAmount, maxAmount, enabledChains, successUrl, cancelUrl, status, createdAt, updatedAt. Only GET /v1/products and GET /v1/products/:id add networks (rows of { chain, token, price } in display order); the create and update responses return the row without it, so read the product back when you need the rails. Of note:

Manage products

The payment link: /pay/:slug

Share https://thru.la/pay/<slug> anywhere. The buyer picks a chain from the ones you enabled and pays the product's price for that chain, or, on a custom-amount product, types an amount within your bounds and pays that. The page is backed by two public endpoints:

• GET /v1/public/products/:slug returns the product as the page sees it, including pricingMode and, on a custom-amount product, the effective bounds:

  json

  {
  "pricingMode": "custom_amount",
  "minAmount": "1",
  "maxAmount": "500",
  "currency": "USD"
  

}

On a fixed-price product these three bound fields are `null`. `networks[].price` is `null` on a custom-amount product.
- `POST /v1/public/products/:slug/checkout` with body `{ idempotencyKey?, chain?, amount? }` returns `{ kind, payment }`. `amount` is **required** on a custom-amount product and **refused** on a fixed-price one (`400 amount is not accepted for a fixed-price product.`). It is checked by the same rule as a session's amount, so an amount outside the bounds returns the same `400` with the bounds as fields:

```json
{
"statusCode": 400,
"error": "Bad Request",
"message": "amount 0.5 is below the minimum of 1 USD.",
"minAmount": "1",
"maxAmount": "500",
"currency": "USD"
}

On a custom-amount product the idempotencyKey is scoped by chain and amount, so a page that resubmits the same key with a different amount gets a new payment for the new amount, not the earlier quote.

The payment a link creates has expectedAmount equal to the price or the chosen amount, token set to the chosen rail's token, and currency equal to that token symbol.

A payment link is anonymous. The payment it creates has no reference and no metadata, only productId. You receive payment.* webhooks, but nothing in them says who the buyer is. Use it for things that need no account, such as tips or a public buy button. To know who paid, use a checkout session.

The slug is not secret: the hosted checkout-session page reads the product by its slug, so anyone who has a session link can find the product's payment link. If a product must only be bought by known users, check for payments on it that did not come through a session: their metadata has no thru.sessionId, and GET /v1/payments/:id returns checkoutSession: null for them.

Lifecycle

active → archived. An archived product disappears from /pay/:slug, and new checkout sessions for it are refused with 409.