Бүтээгдэхүүн ба үнэ

Бүтээгдэхүүн (product) нь таны зарж буй бараа, үйлчилгээг Byl дээр төлөөлөх объект юм. Үнэ (price) нь тухайн бүтээгдэхүүний нэг худалдаалах хувилбар — нэг бүтээгдэхүүн олон үнэтэй байж болно (жишээ нь сарын болон жилийн үнэ).

Бүтээгдэхүүн, үнэ хоёр нь дараах боломжуудын суурь болдог:

Checkout — price (lookup key) эсвэл price_id-гаар бүртгэлтэй үнийг зааж худалдан авалт үүсгэнэ.
Багц (subscription) — давтагдах (recurring) үнэтэй checkout төлөгдөхөд багц автоматаар үүснэ.
Хөнгөлөлтийн код — “Сонгосон бүтээгдэхүүн” хүрээтэй хөнгөлөлт нь бүртгэлтэй бүтээгдэхүүнтэй холбогдож ажиллана.
Төлбөрийн линк — бүртгэлтэй үнээ кодгүйгээр, хуваалцах линкээр зарна.
Барааны үлдэгдэл — бүтээгдэхүүнд зарах тоо тохируулж, борлуулалтыг үлдэгдэлтэй уялдуулна.

Бүтээгдэхүүн үүсгэх

Удирдлагын буланд төслийнхөө Бүтээгдэхүүн цэсээр орно.
Шинэ бүтээгдэхүүн товчийг дарна.
Дараах мэдээллийг бөглөнө:
- Нэр (заавал) — 255 тэмдэгт хүртэл. Checkout хуудсан дээр харилцагчид харагдана.
- Тайлбар (сонголттой) — 1024 тэмдэгт хүртэл.
- Зураг (сонголттой) — JPEG эсвэл PNG, 12MB хүртэл.
- Зарах тоо (сонголттой) — хоосон үлдээвэл хязгааргүй. Дэлгэрэнгүйг Барааны үлдэгдэл хуудаснаас уншина уу.
Хамгийн багадаа нэг үнэ нэмнэ (доорх хэсгийг үзнэ үү).
Хадгалснаар бүтээгдэхүүн үүснэ.

Үнэ

Үнэ бүр дараах тохиргоотой:

Талбар	Тайлбар
Дүн	Нэгж үнэ, төгрөгөөр.
Төрөл	`Нэг удаагийн` (өгөгдмөл) эсвэл `Давтагдах` (recurring).
Мөчлөг	Зөвхөн давтагдах үнэд: `сар` эсвэл `жил`, 1–12 мөчлөгийн тоотой (жишээ нь “3 сар тутам”).
Lookup key	Үнийг кодоос дуудах, санахад хялбар нэр (сонголттой, доорх хэсгийг үзнэ үү).

Бүтээгдэхүүний эхний үнэ автоматаар үндсэн үнэ болно. Үндсэн үнэ нь удирдлагын булангийн жагсаалтад харагдах үнэ юм.

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

Дүнг нь өөрчилж болно. Гэхдээ одоогийн бүх идэвхтэй багцын дараагийн сунгалт шинэ дүнгээр тооцогдоно. Засах хуудас нөлөөлөх багцын тоог хадгалахаас өмнө харуулна.

Үнийг архивлах

Үнээр шинээр зарахаа болих бол засах хуудасны үнийн мөр дээрх Архивлах товчийг дарна:

Архивласан үнээр шинэ checkout үүсгэх боломжгүй. API-аас price_id эсвэл lookup key-гээр дуудвал validation алдаа буцна.
Энэ үнийг агуулсан төлбөрийн линк идэвхгүй болж, 404 буцаана.
Billing portal-ын “Багц солих” сонголтод харагдахгүй.
Энэ үнэтэй одоогийн багцууд хэвээрээ сунгагдсаар байна. Захиалагчид анх бүртгүүлсэн дүн, мөчлөгөөрөө үргэлжилнэ.
Үндсэн үнийг архивлавал үндсэн үнэ идэвхтэй байгаа хамгийн эртний үнэ рүү шилжинэ.

Үнийн дүн эсвэл төрлийг өөрчлөхдөө одоогийн захиалагчдын нөхцлийг хэвээр үлдээх бол хуучин үнийг архивлаад шинэ үнэ нэмээрэй. Архивласан үнийг Сэргээх товчоор буцааж идэвхжүүлж болно.

Lookup key

Lookup key нь үнэд өгөх, төсөл дотроо давтагдашгүй нэр юм (200 тэмдэгт хүртэл). Жишээ нь: starter_monthly, growth_yearly, tshirt.

Lookup key ашигласнаар:

Кодод үнийн ID (price_id) хатуу бичих шаардлагагүй болно — items[0][price] талбарт lookup key-гээ дамжуулна.
Test болон Live төслүүдэд ижил lookup key өгвөл орчин солиход кодоо өөрчлөх шаардлагагүй.
Үнийг дараа нь өөрчлөхөд (шинэ үнэ үүсгэж lookup key-г шилжүүлэхэд) кодод өөрчлөлт хийхгүй.

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

Давтагдах үнэ ба багц

Багцын (subscription) үйлчилгээ ажиллуулахын тулд бүтээгдэхүүндээ давтагдах төрөлтэй үнэ үүсгэнэ:

Үнэ нэмэхдээ төрлийг Давтагдах болгоно.
Мөчлөгөө сонгоно — сар эсвэл жил, шаардлагатай бол мөчлөгийн тоог заана (жишээ нь 3 сар тутам).
Lookup key өгөхийг зөвлөж байна (жишээ нь starter_monthly).

Энэ үнэтэй checkout төлөгдмөгц багц автоматаар үүсч, сунгалтын сануулга, статусын шилжилт, webhook мэдэгдлийг Byl зохицуулна.

Нэг бүтээгдэхүүнд хэд хэдэн давтагдах үнэ байж болно (сарын/жилийн гэх мэт) — billing portal-ын “Багц солих” хэсэгт төслийн архивлаагүй бүх давтагдах үнэ автоматаар харагдана.

Багцын хугацаа хэтэрсэн үед шууд цуцлахгүй, тодорхой хоногийн турш past_due төлөвт байлгах grace period-ийг бүтээгдэхүүн тус бүрээр тохируулах боломжтой. Бүтээгдэхүүнийг засах хуудасны Багцын тохиргоо хэсэгт Grace period-ийг 0–30 хоногоор тохируулна (давтагдах үнэтэй бүтээгдэхүүн дээр л харагдана). 0 бол past_due төлөвт орохгүйгээр шууд цуцлагдана. Хугацаа хэтэрсэн багцыг өдөр бүр 02:30-д (Улаанбаатарын цагаар) шалгадаг тул цуцлалт хугацаа дууссаны дараах шалгалтаар хийгдэнэ.

client_reference_id

Өөрийн систем дэх бүтээгдэхүүний ID-г Byl-ийн бүтээгдэхүүнтэй холбохыг хүсвэл client_reference_id талбарыг ашиглана — webhook болон API-ийн хариун дахь product объектод энэ талбар буцаж ирдэг. price_data-гаар checkout үүсгэх үед мөн product_data[client_reference_id]-аар дамжуулж болно.

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

Checkout — бүртгэлсэн үнээрээ худалдан авалт үүсгэх
Subscriptions — давтагдах үнэ дээр багц ажиллуулах
Хөнгөлөлтийн код — бүтээгдэхүүнд хөнгөлөлт тохируулах