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.

Registered prices vs price_data

You can pass price_data directly to a checkout without registering the product on Byl, but in that case subscriptions and product-scoped promotion codes won’t work. For products you sell regularly, we recommend registering them and referencing them by lookup key. See Checkout — Specifying items for details.

Creating a product

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.

Prices

Each price has the following settings:

Field	Description
Amount	Unit price, in tögrög.
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).

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

Prices linked to subscriptions can’t be deleted

A price that has active or past subscriptions attached to it can’t be deleted — this preserves the integrity of historical records. To stop using such a price, add a new price and stop referencing the old one in your checkouts.

Lookup key

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 }
          ]
      }'

Recurring prices and subscriptions

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.

Grace period

Instead of cancelling a subscription immediately when it becomes overdue, you can configure a per-product grace period that keeps it in the past_due state for a set number of days. Set it to 0–30 days under Subscription settings → Grace period on the product form (shown only for products with a recurring price). With 0, the subscription skips past_due and is canceled directly. Overdue subscriptions are checked once a day at 02:30 (Ulaanbaatar time), so cancellation happens at the first check after the period ends.

client_reference_id

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].

Next steps

• Checkout — create purchases with your registered prices
• Subscriptions — run subscriptions on recurring prices
• Promotion codes — set up discounts on products