Customer — Харилцагч

Customer нь таны үйлчилгээний хэрэглэгчийг Byl систем дээр төлөөлөх объект юм. Худалдан авалтын түүх, нэхэмжлэх, багц (subscription) зэрэг бүгд customer-т холбогдоно.

Харилцагч багцаа billing portal дээр өөрөө удирддаг бөгөөд portal session нь customer-т үүсдэг.

client_reference_id-г үргэлж дамжуулаарай

Өөрийн систем дэх хэрэглэгчийн ID-г client_reference_id талбарт дамжуулбал хоёр системийн хэрэглэгчийг хооронд нь map хийхэд хялбар болно — webhook болон API-ийн хариу бүрт энэ талбар буцаж ирдэг. Мөн энэ ID-гаар шууд лавлах боломжтой тул Byl-ийн customer ID-г өөр талдаа хадгалах шаардлагагүй.

Customer объект

Талбар	Төрөл	Тайлбар
id	Number	Customer ID.
name	String	Нэр.
email	String	И-мэйл хаяг.
phone	String	Утасны дугаар.
client_reference_id	String	Таны систем дэх хэрэглэгчийн ID.
subscriptions	Array	Эрхтэй багцууд. Зөвхөн лавлах хүсэлтийн хариунд ирнэ.
created_at	Date	Анх үүссэн огноо.
updated_at	Date	Өөрчлөлт орсон огноо.

Customer үүсгэх

POST /v1/projects/:project_id/customers

Параметер	Төрөл	Заавал эсэх	Тайлбар
email	String	true	И-мэйл хаяг.
name	String	false	Нэр. 255 тэмдэгт хүртэл.
phone	String	false	Утасны дугаар.
client_reference_id	String	false	Таны систем дэх хэрэглэгчийн ID. 48 тэмдэгт хүртэл.

Давхардал үүсгэхгүй (upsert)

client_reference_id дамжуулсан үед энэ endpoint давхардал үүсгэдэггүй — тухайн ID-тай customer аль хэдийн байвал мэдээллийг нь шинэчлээд буцаана.

Тиймээс checkout үүсгэхийнхээ өмнө бүр удаа дуудаж, хариунд ирэх id-г шууд customer_id болгон ашиглаж болно. client_reference_id-гүй дуудвал шинэ customer үүсэх тул давхардал үүсэж болзошгүй.

Жишээ хүсэлт

BYL_PROJECT_ID="таны төслийн ID"
BYL_TOKEN="таны 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"
      }'

Жишээ гаралт

{
  "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"
  }
}

Customer лавлах

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

Хариунд харилцагчийн эрхтэй багцууд (subscriptions) хамт ирдэг тул "энэ хэрэглэгч subscribed юу?" гэсэн шалгалтыг нэг хүсэлтээр хийж болно.

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

client_reference_id-ээр лавлах

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

Byl-ийн customer ID-г өөр талдаа хадгалаагүй бол өөрийн хэрэглэгчийн ID-гаар шууд лавлана. Хариу нь дээрхтэй ижил.

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'

Тухайн ID-тай харилцагч байхгүй бол 404 буцна.

Жишээ гаралт

{
  "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"
  }
}

subscriptions массивт зөвхөн эрхтэй (trialing, active, past_due) багцууд багтана. Хоосон массив бол хэрэглэгчид одоогоор эрх байхгүй гэсэн үг.

Дараагийн алхам

• Subscriptions — давтагдах төлбөр, багцын мөчлөг
• Billing portal — харилцагч багцаа өөрөө удирдах хуудас
• Checkout — харилцагчтай холбосон худалдан авалт үүсгэх