Subscription — Багц

Subscription боломжоор сар эсвэл жилээр давтагдан төлөгддөг үйлчилгээгээ (SaaS багц, гишүүнчлэл, контентын эрх гэх мэт) Byl дээр бүрэн зохицуулна.

Монголын төлбөрийн системүүдэд автомат суутгал (auto-charge) байдаггүй тул Byl-ийн subscription нь request-to-pay зарчмаар ажиллана: мөчлөг бүрийн төгсгөлд хэрэглэгч рүү сануулга илгээгдэж, хэрэглэгч өөрөө төлбөрөө төлж эрхээ сунгана. Сануулга, дуусах хугацааны хяналт, статусын шилжилт, webhook мэдэгдэл зэргийг Byl автоматаар зохицуулна.

Хэрэглэгч багцаа billing portal дээр өөрөө удирдана — Byl данс, нууц үг шаардлагагүй, түр хугацааны session линкээр ордог тэр хуудсаар сунгах, багц солих, цуцлах, төлбөрийн түүхээ харах боломжтой.

Хэрхэн ажилладаг вэ

Удирдлагын буланд бүтээгдэхүүндээ давтагдах (recurring) үнэ үүсгэнэ (сар эсвэл жилийн мөчлөгтэй).
Хэрэглэгч тань худалдан авахад та recurring үнэтэй checkout үүсгэнэ.
Checkout төлөгдмөгц subscription автоматаар үүсч, subscription.created webhook илгээгдэнэ.
Мөчлөг дуусахын өмнө Byl хэрэглэгч рүү имэйл сануулга (portal линктэй) илгээж, танд subscription.renewal_due webhook явуулна.
Хэрэглэгч portal дээрээ төлбөл мөчлөг сунгагдана (subscription.renewed); төлөхгүй бол хугацаа дуусмагц цуцлагдана (subscription.canceled).

Статусууд

Статус	Тайлбар
`trialing`	Туршилтын хугацаа. Туршилт дуусахад төлбөл `active` болно.
`active`	Идэвхтэй. Мөчлөг дуустал эрх нээлттэй.
`past_due`	Хугацаа хэтэрсэн (зөвхөн grace period тохируулсан бүтээгдэхүүн дээр).
`canceled`	Цуцлагдсан. Хэрэглэгчийн эрхийг хаах ёстой төлөв.

Эрхийг хэзээ хаах вэ

Хэрэглэгчийн эрхийг subscription.canceled event ирэх хүртэл нээлттэй байлгана — trialing, active, past_due статусууд бүгд эрхтэйд тооцогдоно.

Сануулгын хуваарь

Мөчлөгөөс хамаарч дараах хуваариар хэрэглэгч рүү имэйл сануулга илгээгдэж, танд subscription.renewal_due webhook явуулна:

Сарын багц — дуусахаас 7 хоног, 1 хоногийн өмнө
Жилийн багц — дуусахаас 30 хоног, 7 хоног, 1 хоногийн өмнө

Цуцлалт хүссэн хэрэглэгч рүү сануулга илгээгдэхгүй.

Багц эхлүүлэх

Subscription нь recurring үнэтэй checkout төлөгдөхөд автоматаар үүснэ. Ердийн checkout-оос хоёр нэмэлт шаардлагатай:

customer_id заавал — багц тодорхой харилцагчид бүртгэгдэнэ
Ганц item — recurring үнэтэй checkout-д өөр item нэмж болохгүй

customer_id-г Customer үүсгэх endpoint-оор авна — client_reference_id дамжуулбал upsert байдлаар ажилладаг тул checkout бүрийн өмнө дуудсан ч давхардал үүсэхгүй.

Жишээ хүсэлт

shell

BYL_PROJECT_ID="таны төслийн ID"
BYL_TOKEN="таны API token"

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 '{
          "customer_id": 12,
          "success_url": "https://example.mn/subscribe/success",
          "items": [
              { "price": "starter_monthly", "quantity": 1 }
          ]
      }'

Checkout төлөгдмөгц subscription үүсч subscription.created webhook илгээгдэнэ. Хэрэглэгч рүү portal линктэй имэйл очно.

Нэг бүтээгдэхүүн — нэг багц

Нэг харилцагч нэг бүтээгдэхүүн дээр зөвхөн нэг идэвхтэй subscription-тэй байна.

Идэвхтэй subscription-тэй харилцагчийн ижил бүтээгдэхүүний ижил үнэтэй checkout нь шинэ subscription үүсгэхгүй, одоогийнхыг нь сунгана.
Өөр үнэтэй checkout үүсгэх бол subscription_id-г заавал дамжуулна — эс бөгөөс хүсэлт алдаа буцаана (үлдсэн хоногийн кредит алдагдахаас сэргийлнэ).

Багцын хязгаар

Идэвхтэй subscription-ий нийт тоо таны Byl багцаас хамаарна — Starter багцад 30, Growth багцад хязгааргүй. Хязгаарт хүрсэн үед шинэ subscription эхлүүлэх хүсэлт алдаа буцаана; одоо байгаа subscription-ий сунгалт, багц солилтод хязгаар үйлчлэхгүй. Test горимд хязгаар шалгагдахгүй.

Сунгалт

Хэрэглэгч portal дээрээ "Сунгах" даран төлдөг тул ихэнх тохиолдолд танаас нэмэлт ажиллагаа шаардлагагүй. Хэрэв өөрийн системээс сунгалтын checkout үүсгэхийг хүсвэл subscription_id параметрийг дамжуулна:

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 '{
          "customer_id": 12,
          "subscription_id": 4,
          "items": [
              { "price": "starter_monthly", "quantity": 3 }
          ]
      }'

Сунгалт одоогийн дуусах хугацаан дээр нэмэгдэнэ — үлдсэн хоног алдагдахгүй.
quantity нь хэдэн мөчлөгөөр сунгахыг заана (жишээн дээр 3 сар).

Багц солих

subscription_id-тай checkout-д өөр recurring үнэ өгвөл багц солилт болно — subscription шинэ багц руу шилжиж, шинэ мөчлөг төлсөн өдрөөс эхэлнэ. Өөр бүтээгдэхүүний үнэ рүү ч (жишээ нь Starter → Growth) солих боломжтой.

Одоогийн мөчлөгийн үлдсэн хоногийн үнэ кредит болж шинэ checkout-ийн дүнгээс автоматаар хасагдана. Кредит нь шинэ багцын үнээс их эсвэл тэнцүү бол (жишээ нь жилийн багцаас сарын багц руу буух) мөчлөг дундуур солих боломжгүй — мөчлөг дуусахад л солино.

WARNING

Кредит нь checkout үүсэх мөчид тооцогддог тул багц солих checkout 24 цагийн дотор төлөгдөх ёстой. Хугацаа хэтэрвэл шинэ checkout үүсгэнэ.

Portal дээр "Багц солих" хэсэгт төслийн бусад recurring үнэнүүд автоматаар харагддаг тул энэ урсгалыг та өөрөө хийх шаардлагагүй.

Туршилт (Trial)

Туршилтын багц төлбөргүй эхэлдэг тул checkout-оор биш, API-аар шууд үүсгэнэ. Энэ нь API-аар subscription үүсгэх цорын нэг арга — төлбөртэй багц үргэлж checkout-оос үүснэ.

POST /v1/projects/:project_id/subscriptions

Параметер	Төрөл	Заавал эсэх	Тайлбар
`customer_id`	Number	true	Харилцагчийн ID.
`price`	String	true*	Recurring үнийн `lookup_key`.
`price_id`	Number	true*	Recurring үнийн ID — `price`-ийн оронд дамжуулж болно.
`trial_days`	Number	true	Туршилтын хоног (1–365).

* price эсвэл price_id-ийн аль нэгийг заавал дамжуулна. Хоёуланг өгвөл price_id хүчинтэй. Үнэ нь давтагдах (recurring) байх ёстой.

shell

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/subscriptions \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
          "customer_id": 12,
          "price": "starter_monthly",
          "trial_days": 14
      }'

Туршилт дуусахын өмнө хэрэглэгч рүү ердийн сануулга очих ба portal дээрээ төлснөөр active болно, төлөхгүй бол цуцлагдана.

WARNING

Нэг харилцагч нэг бүтээгдэхүүн дээр нэг л удаа туршилт авч болно. Өмнө нь туршилт авсан, эсвэл тухайн бүтээгдэхүүн дээр аль хэдийн эрхтэй бол хүсэлт алдаа буцаана.

Цуцлалт

Цуцлалт нь анхдагчаар мөчлөгийн төгсгөлд хэрэгжинэ:

Цуцлах үед статус active хэвээр үлдэж, subscription.updated webhook илгээгдэнэ (canceled_at талбар бөглөгдсөн байна).
Хэрэглэгчийн эрх мөчлөг дуустал хүчинтэй, харин сануулга дахиж илгээгдэхгүй.
Мөчлөг дуусмагц статус canceled болж subscription.canceled webhook илгээгдэнэ — энэ үед л эрхийг хаана.
Мөчлөг дуусахаас өмнө цуцлалтыг буцаах (resume) боломжтой.

mode: immediately дамжуулбал шууд цуцлагдана: статус тэр даруй canceled болж, subscription.canceled webhook илгээгдэнэ. Цуцлалт хүсэгдсэн (canceled_at бөглөгдсөн) идэвхтэй багц дээр ч ажиллана. Шууд цуцлалтыг буцаах боломжгүй.

Хэрэглэгч portal дээрээсээ өөрөө цуцлах ба та мөн API-аар цуцалж болно:

POST /v1/projects/:project_id/subscriptions/:subscription_id/cancel
POST /v1/projects/:project_id/subscriptions/:subscription_id/resume

Параметер	Төрөл	Тайлбар
`mode`	String	`at_period_end` (анхдагч) — мөчлөгийн төгсгөлд; `immediately` — шууд цуцалж эрх хаана.

shell

# Мөчлөгийн төгсгөлд цуцлах
curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/subscriptions/4/cancel \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

# Шууд цуцлах (эрх тэр даруй хаагдана)
curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/subscriptions/4/cancel \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"mode": "immediately"}'

# Цуцлалт буцаах
curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/subscriptions/4/resume \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Аль хэдийн бүрэн цуцлагдсан subscription дээр эдгээр хүсэлт 409 Conflict буцаана.

Portal

Хэрэглэгч багцаа billing portal дээр өөрөө удирдана: сунгах, багц солих, цуцлах/буцаах, дахин авах, төлбөрийн түүхээ харах. Багц үүсэх, сануулга очих, цуцлагдах бүрд Byl хэрэглэгч рүү portal линктэй, таны брэндтэй имэйл автоматаар илгээдэг тул ихэнх тохиолдолд танаас нэмэлт ажиллагаа шаардлагагүй.

Өөрийн аппликэйшн дотроос ("Миний багц" цэс гэх мэт) хандалт өгөхийг хүсвэл POST /billing-portal/sessions-ээр түр хугацааны session линк үүсгэж чиглүүлнэ.

Subscription объект

Талбар	Төрөл	Тайлбар
`id`	Number	Subscription ID.
`status`	String	Төлөв: `trialing`, `active`, `past_due`, `canceled`.
`customer_id`	Number	Харилцагчийн ID.
`product_id`	Number	Бүтээгдэхүүний ID.
`price_id`	Number	Үнийн ID (багц солиход өөрчлөгдөнө).
`current_period_start`	Date	Одоогийн мөчлөгийн эхлэл.
`current_period_end`	Date	Одоогийн мөчлөгийн төгсгөл (эрхийн дуусах хугацаа).
`trial_ends_at`	Date	Туршилтын дуусах хугацаа (туршилтгүй бол `null`).
`canceled_at`	Date	Цуцлалт хүссэн огноо (цуцлаагүй бол `null`).
`is_test`	Boolean	Test горимд үүссэн эсэх.
`customer`	Object	Харилцагчийн мэдээлэл (лавлах хүсэлтэд ирнэ).
`price`	Object	Үнэ болон бүтээгдэхүүний мэдээлэл (лавлах хүсэлтэд ирнэ).

Багцын жагсаалт

GET /v1/projects/:project_id/subscriptions

Нэг хуудсанд 25 бичлэг буцах бөгөөд дараагийн хуудсыг ?page=2-оор авна. Дараах параметрүүдээр шүүнэ:

Параметер	Тайлбар
`customer_id`	Тухайн харилцагчийн багцууд.
`price_id`	Тухайн үнийн багцууд.
`price`	Тухайн үнийн `lookup_key`-ээр шүүх.
`status`	`trialing`, `active`, `past_due`, `canceled`.

shell

curl -X GET "https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/subscriptions?customer_id=12&status=active" \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Багц лавлах

GET /v1/projects/:project_id/subscriptions/:subscription_id

Жишээ гаралт

json

{
  "data": {
    "id": 4,
    "status": "active",
    "project_id": 1,
    "customer_id": 12,
    "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,
    "customer": {
      "id": 12,
      "name": "Бат-Эрдэнэ",
      "email": "[email protected]",
      "phone": "99999999",
      "client_reference_id": "user_842"
    },
    "price": {
      "id": 3,
      "type": "recurring",
      "unit_amount": 30000,
      "recurring_interval": "month",
      "recurring_interval_count": 1,
      "lookup_key": "starter_monthly",
      "product": {
        "id": 7,
        "name": "Starter багц",
        "client_reference_id": null
      }
    },
    "created_at": "2026-06-23T04:10:00.000000Z",
    "updated_at": "2026-07-23T04:10:00.000000Z"
  }
}

Харилцагч эрхтэй эсэхийг шалгах

"Энэ хэрэглэгч subscribed юу?" гэсэн шалгалтын хамгийн хялбар зам — харилцагч лавлахад эрхтэй багцууд нь хамт ирнэ:

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

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

Webhook event-үүд

Event	Хэзээ илгээгдэх вэ
`subscription.created`	Шинэ subscription үүссэн (checkout төлөгдсөн эсвэл trial эхэлсэн).
`subscription.renewed`	Мөчлөг амжилттай сунгагдсан.
`subscription.updated`	Багц солигдсон, цуцлалт хүссэн эсвэл цуцлалт буцсан.
`subscription.renewal_due`	Сунгалтын сануулга илгээгдсэн.
`subscription.past_due`	Хугацаа хэтэрсэн (зөвхөн grace period тохируулсан бүтээгдэхүүн дээр).
`subscription.canceled`	Subscription бүрэн цуцлагдсан — хэрэглэгчийн эрхийг энэ үед хаана.

Event бүрийн data.object-т subscription объект (customer, product, price мэдээллийн хамт) очно. Webhook тохиргоо болон гарын үсгийн шалгалтын талаар Webhook хуудаснаас уншина уу.

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

Billing portal — харилцагч багцаа өөрөө удирдах хуудас
Checkout — багц эхлүүлэх checkout үүсгэх
Webhook — багцын event-үүдийг өөрийн системд хүлээн авах

Subscription — Багц ​

Хэрхэн ажилладаг вэ ​

Статусууд ​

Сануулгын хуваарь ​

Багц эхлүүлэх ​

Сунгалт ​

Багц солих ​

Туршилт (Trial) ​

Цуцлалт ​

Portal ​

Subscription объект ​

Багцын жагсаалт ​

Багц лавлах ​

Харилцагч эрхтэй эсэхийг шалгах ​

Webhook event-үүд ​

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

Subscription — Багц

Хэрхэн ажилладаг вэ

Статусууд

Сануулгын хуваарь

Багц эхлүүлэх

Сунгалт

Багц солих

Туршилт (Trial)

Цуцлалт

Portal

Subscription объект

Багцын жагсаалт

Багц лавлах

Харилцагч эрхтэй эсэхийг шалгах

Webhook event-үүд

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