Subscription — Багц

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

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

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

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

1. Удирдлагын буланд бүтээгдэхүүндээ давтагдах (recurring) үнэ үүсгэнэ (сар эсвэл жилийн мөчлөгтэй).
2. Хэрэглэгч тань худалдан авахад та recurring үнэтэй checkout үүсгэнэ.
3. Checkout төлөгдмөгц subscription автоматаар үүсч, subscription.created webhook илгээгдэнэ.
4. Мөчлөг дуусахын өмнө Byl хэрэглэгч рүү имэйл сануулга (portal линктэй) илгээж, танд subscription.renewal_due webhook явуулна.
5. Хэрэглэгч 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 бүрийн өмнө дуудсан ч давхардал үүсэхгүй.

Жишээ хүсэлт

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 параметрийг дамжуулна:

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-ийн дүнгээс автоматаар хасагдана. Кредит нь шинэ багцын үнээс их эсвэл тэнцүү бол (жишээ нь жилийн багцаас сарын багц руу буух) мөчлөг дундуур солих боломжгүй — мөчлөг дуусахад л солино.

Анхааруулга

Кредит нь 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) байх ёстой.

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 болно, төлөхгүй бол цуцлагдана.

Анхааруулга

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

Цуцлалт

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

• Цуцлах үед статус 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 — шууд цуцалж эрх хаана.

# Мөчлөгийн төгсгөлд цуцлах
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.

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

Жишээ гаралт

{
  "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-үүдийг өөрийн системд хүлээн авах