Customer - Харилцагч

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

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

Харилцагч захиалгаа billing portal дээр өөрөө удирддаг — portal session нь customer-т үүсдэг тул удирдлагын панелийн харилцагчийн хуудаснаас ч portal линк үүсгэж болно.

Customer объект

Параметер	Төрөл	Тайлбар
id	Number	Customer ID.
name	String	Нэр.
email	String	И-мэйл хаяг.
phone	String	Утасны дугаар.
client_reference_id	String	Таны систем дэх хэрэглэгчийн ID.
subscriptions	Array	Идэвхтэй захиалгууд (лавлах хүсэлтэд ирнэ).

Customer үүсгэх

• HTTP Method: POST
• Content Type: application/json
• URL: https://byl.mn/api/v1/projects/1/customers

Параметер

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

Upsert семантик: client_reference_id дамжуулсан үед энэ endpoint нь давхардал үүсгэдэггүй — тухайн client_reference_id-тай customer аль хэдийн байвал мэдээллийг нь шинэчлээд буцаана. Тиймээс checkout үүсгэхийнхээ өмнө бүр удаа дуудсан ч болно: хариунд ирэх id-г шууд customer_id болгон ашиглана.

Жишээ хүсэлт

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 лавлах

• HTTP Method: GET
• URL: https://byl.mn/api/v1/projects/1/customers/12

Хариунд харилцагчийн идэвхтэй захиалгууд (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-ээр лавлах

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

• HTTP Method: GET
• URL: https://byl.mn/api/v1/projects/1/customers/by-client-reference-id/user_842

$ 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'

Олдохгүй бол 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"
  }
}