Skip to content

Products and prices

A product represents the goods or services you sell on Byl. A price is a specific way to sell that product — a single product can have multiple prices (for example, a monthly price and a yearly price).

Products and prices are the foundation for the following features:

  • Checkout — create a purchase by referencing a registered price via price (lookup key) or price_id.
  • Subscriptions — when a checkout with a recurring price is paid, a subscription is created automatically.
  • Promotion codes — coupons scoped to “Specific products” work against registered products.
  • Checkout links — sell registered prices through a shareable link, no code required.
  • Product stock — set a stock limit and tie sales to your inventory.
  1. In the dashboard, open your project’s Products (Бүтээгдэхүүн) menu.
  2. Click New product (Шинэ бүтээгдэхүүн).
  3. Fill in the following:
    • Name (required) — up to 255 characters. Shown to customers on the checkout page.
    • Description (optional) — up to 1024 characters.
    • Image (optional) — JPEG or PNG, up to 12MB.
    • Stock (optional) — leave empty for unlimited. See Product stock for details.
  4. Add at least one price (see the section below).
  5. Save to create the product.

Each price has the following settings:

Field Description
Amount Unit price, in tögrög.
Label A short name customers see, up to 64 characters (optional, e.g. “Large”, “1 kg”). Catalogs, carts and the payment page show “Shirt — Large”; without one the price shows as its amount. Not in the API yet.
Type One-time (default) or Recurring.
Interval Recurring prices only: month or year, with an interval count of 1–12 (e.g. “every 3 months”).
Lookup key A memorable name for referencing the price from code (optional, see the section below).
Metadata Your own key–value pairs, such as the price’s entitlements and limits (optional, see Metadata).

The first price of a product automatically becomes the default price. The default price is the one shown in the dashboard list.

A product marked «Hide from catalog» does not show in catalog links with the All products scope. A Selected products catalog shows what you picked regardless of the mark. The mark is not in the API yet.

A lookup key is a name you assign to a price that is unique within your project (up to 200 characters). For example: starter_monthly, growth_yearly, tshirt.

Using a lookup key means:

  • You don’t have to hardcode price IDs (price_id) in your code — pass the lookup key in the items[0][price] field.
  • If you give the same lookup key to prices in your Test and Live projects, you don’t need to change your code when switching environments.
  • When you change the price later (by creating a new price and moving the lookup key to it), no code changes are needed.
Терминал
curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/checkouts \
-H "Authorization: Bearer $BYL_TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"success_url": "https://example.mn/purchase/success",
"items": [
{ "price": "starter_monthly", "quantity": 1 }
]
}'

To run a subscription service, create a recurring price on your product:

  1. When adding the price, set the type to Recurring (Давтагдах).
  2. Choose the interval — month or year, and set the interval count if needed (e.g. every 3 months).
  3. We recommend assigning a lookup key (e.g. starter_monthly).

Once a checkout with this price is paid, a subscription is created automatically — Byl handles renewal reminders, status transitions, and webhook notifications.

A product can have multiple recurring prices (monthly/yearly, etc.) — all of the project’s recurring prices automatically appear in the “Change plan” section of the billing portal.

Products and prices can each hold key–value pairs for your own system — for example a plan’s entitlements and limits: max_projects = 3, tier = pro. Add them in the Metadata section of the product form, for the product and for each price.

  • Up to 50 keys. Keys are up to 40 characters of Latin letters, digits, _ and -. Values are up to 500 characters.
  • Values are always strings — read 3 as a number in your own code.
  • They come back as price.metadata and product.metadata in the subscription API and in the subscription.* and checkout.completed webhooks. Empty metadata is {}.

Keeping a plan’s entitlements in its price’s metadata instead of hardcoding them means adding a plan or changing a limit needs no code change: read the customer’s price.metadata and check against it.

To link a product ID from your own system to a Byl product, use the client_reference_id field — it is returned on the product object in webhooks and API responses. When creating a checkout with price_data, you can also pass it via product_data[client_reference_id].