Send WhatsApp receipts and purchase orders

POST /api/v1/whatsapp/send sends a receipt or purchase_order template over WhatsApp through AskBiz’s Meta Business API connection. It requires an account-mode key, costs 2 cents per successful send, and is billed only after Meta confirms the message actually went out — a failed or rejected call never touches your wallet.

1. 1

   Confirm your key is account-mode

   POST /api/v1/whatsapp/send requires an account-mode key — a generic-mode key gets a 403. Generic keys have no tie to a real AskBiz business, so this endpoint deliberately can’t be used as an open message-blasting gateway. Check a key’s mode on the Keys page in the developer dashboard before you build against this endpoint.

2. 2

   Choose receipt or purchase_order as the template

   The template field accepts exactly two values: receipt or purchase_order. There is no third option — otp is reserved for AskBiz’s own login flow and is never available through this endpoint. The template just tells AskBiz which category the message belongs to; the actual wording comes from the text field you send, up to 1024 characters.

3. 3

   Format the phone number in international form

   phone must be in international format with a leading +, for example +254712345678. An invalid format returns a 400 before anything is attempted, so it never gets billed.

4. 4

   Send the request with an Idempotency-Key header

   Generate a fresh client-side ID — a UUID works — and send it as the Idempotency-Key header. If your request times out and you don’t know whether it landed, retry with the exact same key and you get back the original result instead of a second real WhatsApp message going out. You’re only charged 2 cents once Meta confirms the send succeeded; a retry that hits the same key on an already-successful send is never billed twice.

   cURLJavaScriptPython

   curl -X POST https://askbiz.co/api/v1/whatsapp/send \
     -H "x-api-key: abz_live_your_key_here" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7c4f1a2e-9d3b-4e6a-8f21-1b5c9a0d3e7f" \
     -d '{
       "phone": "+254712345678",
       "template": "receipt",
       "text": "Receipt #1042 — Coca-Cola 500ml x2, Total KES 160. Thank you for your purchase."
     }'

5. 5

   Handle a 502 by retrying with the same key

   A 502 means Meta’s WhatsApp API failed to actually send the message — nothing is charged. It’s safe to retry immediately, as long as you reuse the same Idempotency-Key from the first attempt. Generating a new key on retry defeats the protection: it would be treated as an unrelated send, and if the first attempt had actually succeeded on Meta’s side after your client gave up on it, you’d end up paying for and delivering the message twice.

   JavaScriptPython

   async function sendReceipt(payload, idempotencyKey) {
     const res = await fetch('https://askbiz.co/api/v1/whatsapp/send', {
       method: 'POST',
       headers: {
         'x-api-key': process.env.ASKBIZ_API_KEY,
         'Content-Type': 'application/json',
         'Idempotency-Key': idempotencyKey, // same key on every attempt for this send
       },
       body: JSON.stringify(payload),
     })
   
     if (res.status === 502) {
       // Meta failed to send — nothing was charged. Retry with the SAME key,
       // not a new one, so a message that actually did land isn't sent twice.
       return sendReceipt(payload, idempotencyKey)
     }
   
     return res.json()
   }

What’s next

For the full parameter and error reference, see POST /api/v1/whatsapp/send. For the complete idempotency contract shared with /api/v1/scan, see Errors and retries. Check GET /api/v1/pricing any time for current per-endpoint prices — it’s public, no key required.