Core concepts
Products and prices
Your catalog holds products, prices, coupons, and promotion codes. Every transaction line refers to a catalog price, so the catalog decides what a line costs.
On this page
What the catalog holds#
| Item | What it is | ID |
|---|---|---|
| Product | Something that you sell, with a name and an optional description. | prod_… |
| Price | An amount and a currency for a product, and whether the amount includes tax. A price does not change after you create it. | price_… |
| Coupon | A discount rule. | |
| Promotion code | A code that a buyer enters to apply a coupon. |
You manage the catalog in the dashboard. The API has no catalog endpoints.
Why lines refer to prices#
A transaction line names a price, not an amount. Merxian takes the product name, the description, the unit amount, and the tax code from the catalog. You cannot send your own line description or unit amount.
This keeps the amount of each sale tied to a price that you defined, and it gives the tax calculation the product details that it needs.
Where the API refers to the catalog#
| Field | Where | Meaning |
|---|---|---|
lines[].catalogPriceId |
Create or update a transaction | The price of the line. |
lines[].productId |
Create or update a transaction | A product of your account, instead of a price. |
transactionDraft.lineItems[].priceId |
Create a checkout session | The price of the line. |
amountSource.lineItems[].priceId |
Create a payment link | The price of the line. |
promotionCode |
Create or update a transaction | A promotion code of your account. It needs lines. |
allowPromotionCodes |
Create a checkout session | Lets the buyer enter a promotion code on the hosted page. |
The resulting lines show productId, priceId, name, unitAmount, and taxBehavior. taxBehavior is inclusive when the unit amount includes tax, and exclusive when Merxian adds the tax.
Prices in sandbox and live#
Sandbox and live have separate catalogs. In the dashboard, you can copy products and prices from sandbox to live. The copies get new IDs in live. The copy includes products and prices only.
What to build#
- Keep a mapping from your own product or plan to the Merxian price ID, for each environment.
- To change a price, create a new price and update your mapping. A price does not change after you create it.