Customers

A Customer is the object that represents a user of your service in the Byl system. Purchase history, invoices, and subscriptions are all linked to a customer.

Customers manage their subscriptions themselves in the billing portal, and portal sessions are created for a customer.

Always pass client_reference_id

Passing your own system's user ID in the client_reference_id field makes it easy to map users between the two systems — this field is returned in every webhook and API response. You can also retrieve customers directly by this ID, so there is no need to store Byl's customer ID on your side.

The customer object

Field	Type	Description
id	Number	The customer ID.
name	String	Name.
email	String	Email address.
phone	String	Phone number.
client_reference_id	String	The user's ID in your system.
subscriptions	Array	Entitled subscriptions. Only included in retrieve responses.
created_at	Date	Creation date.
updated_at	Date	Last updated date.

Create a customer

POST /v1/projects/:project_id/customers

Parameter	Type	Required	Description
email	String	true	Email address.
name	String	false	Name. Up to 255 characters.
phone	String	false	Phone number.
client_reference_id	String	false	The user's ID in your system.

No duplicates (upsert)

When client_reference_id is passed, this endpoint never creates duplicates — if a customer with that ID already exists, their details are updated and returned.

This means you can safely call it every time before creating a checkout, and use the id in the response directly as customer_id. Calling it without client_reference_id creates a new customer, so duplicates may occur.

Example request

BYL_PROJECT_ID="your project ID"
BYL_TOKEN="your API token"

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/customers \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "email": "[email protected]",
          "name": "Бат-Эрдэнэ",
          "client_reference_id": "user_842"
      }'

Example response

{
  "data": {
    "id": 12,
    "name": "Бат-Эрдэнэ",
    "email": "[email protected]",
    "phone": null,
    "client_reference_id": "user_842",
    "created_at": "2026-07-23T04:10:00.000000Z",
    "updated_at": "2026-07-23T04:10:00.000000Z"
  }
}

Retrieve a customer

GET /v1/projects/:project_id/customers/:customer_id

The response includes the customer's entitled subscriptions (subscriptions), so you can answer "is this user subscribed?" with a single request.

curl -X GET https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/customers/12 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Retrieve by client_reference_id

GET /v1/projects/:project_id/customers/by-client-reference-id/:client_reference_id

If you have not stored Byl's customer ID on your side, retrieve the customer directly by your own user ID. The response is identical to the one above.

curl -X GET https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/customers/by-client-reference-id/user_842 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

If no customer with that ID exists, the API returns 404.

Example response

{
  "data": {
    "id": 12,
    "name": "Бат-Эрдэнэ",
    "email": "[email protected]",
    "phone": null,
    "client_reference_id": "user_842",
    "subscriptions": [
      {
        "id": 4,
        "status": "active",
        "product_id": 7,
        "price_id": 3,
        "current_period_start": "2026-07-23T04:10:00.000000Z",
        "current_period_end": "2026-08-23T15:59:59.000000Z",
        "trial_ends_at": null,
        "canceled_at": null,
        "is_test": false
      }
    ],
    "created_at": "2026-07-23T04:10:00.000000Z",
    "updated_at": "2026-07-23T04:10:00.000000Z"
  }
}

The subscriptions array only includes entitled subscriptions (trialing, active, past_due). An empty array means the user currently has no entitlement.

Next steps

• Subscriptions — recurring payments and billing cycles
• Billing portal — a page where customers manage their own subscriptions
• Checkout — create a purchase linked to a customer