English

Монгол

English

Монгол

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.

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.
  4. Add at least one price (see the section below).
  5. Save to create the product.

Prices ​

Each price has the following settings:

FieldDescription
AmountUnit price, in tögrög.
TypeOne-time (default) or Recurring.
IntervalRecurring prices only: month or year, with an interval count of 1–12 (e.g. "every 3 months").
Lookup keyA 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.
shell
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. Contact us if you'd like this enabled.

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 ​