> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/chat/broadcast/check-or-reserve-template-message-balance.md).

# Check or reserve template-message balance

Returns the billing details for sending one template message to a phone number and, on prepaid credit-line inboxes, reserves the estimated cost against `message_id`.

`POST /templates/send` and campaigns already do this for you, so you only need this endpoint if you send templates through your own WhatsApp integration and bill through Cekat. Calling it with the same `message_id` again returns the existing reservation.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Broadcast","description":"Use these endpoints to manage WhatsApp message templates, upload recipient lists, and run broadcast campaigns.\n\n## Typical flow\n1. **Create a template** with `POST /templates`. Meta reviews it; its `status` starts as `PENDING`.\n2. **Check approval** with `GET /api/templates`. Only templates with `status: APPROVED` can be sent. If you created or edited templates directly in Meta, call `POST /templates/sync` first to copy them into Cekat.\n3. **Send to one contact** with `POST /templates/send`, or continue below to send to many.\n4. **Upload a recipient list** with `POST /api/recipients`. Contacts are imported in the background; poll `GET /api/recipients` until the list's `total_contacts` matches the number returned by the upload.\n5. **Create a campaign** with `POST /api/campaigns`, using the template's `wa_template_id` as `template_id`. Leave out `schedule_at` to send right away.\n6. **Track results** with `GET /api/campaigns` for totals and `GET /api/v2/campaigns/{id}/messages` for each recipient's delivery status and replies.\n\nEvery step needs the `inbox_id` of a connected WhatsApp inbox. Get it from `GET /api/inboxes` (the `id` of an inbox whose `type` is `whatsapp`).\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"schemas":{"TemplateBilling":{"type":"object","additionalProperties":true,"properties":{"billing_mode":{"type":"string","description":"How the message is billed, for example `credit_card` or `credit_line_prepaid`."},"is_balance_locked":{"type":"boolean","description":"True when balance was reserved for this message."},"estimated_price":{"type":"number"},"currency_code":{"type":"string"},"to_country_code":{"type":"string","nullable":true},"template_id":{"type":"string"},"template_category":{"type":"string"},"inbox_id":{"type":"string","format":"uuid"},"wa_business_id":{"type":"string","nullable":true},"billing_settlement_status":{"type":"string","nullable":true},"billing_lock_reference_type":{"type":"string","nullable":true},"billing_lock_reference_id":{"type":"string","nullable":true}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/templates/lock-balance":{"post":{"tags":["Broadcast"],"operationId":"ReserveTemplateMessageBalance","summary":"Check or reserve template-message balance","description":"Returns the billing details for sending one template message to a phone number and, on prepaid credit-line inboxes, reserves the estimated cost against `message_id`.\n\n`POST /templates/send` and campaigns already do this for you, so you only need this endpoint if you send templates through your own WhatsApp integration and bill through Cekat. Calling it with the same `message_id` again returns the existing reservation.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message_id","phone_number","inbox_id","wa_template_id"],"properties":{"message_id":{"type":"string","description":"Your unique ID for the message. The reservation is tied to it."},"phone_number":{"type":"string","description":"Recipient's number, digits only with country code. Used to price the message."},"inbox_id":{"type":"string","format":"uuid"},"wa_template_id":{"type":"string"},"conversation_id":{"type":"string","format":"uuid","description":"Optional conversation to bill against. Found from the phone number if left out."}}}}}},"responses":{"200":{"description":"Billing details for the message.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/TemplateBilling"}}}}}},"400":{"description":"A required field is missing or invalid, or there is not enough balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"404":{"description":"The template or inbox was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```