# Ads & attribution

Every order records where it came from:

| `order.source` | When |
|---|---|
| `whatsapp` | The customer messaged the shop directly. |
| `ad` | They tapped a Click-to-WhatsApp ad (Facebook or Instagram) within the last 7 days. |
| `website` | They came from a [checkout session](https://kibanda.africa/docs/checkout-sessions) your site created, or the button. |
| `link` | The shop's public page (`/s/<shop-slug>`), e.g. a link in bio. |
| `agent` | An AI assistant built the cart. |
| `api` | A checkout session created by your server with no other source. |

`order.attribution` holds the details: for ads, the ad id (`sourceId`), `headline` and Meta's click id (`ctwaClid`); for sessions, your UTM tags and the `checkoutSession` id. Filter with `GET /v1/orders?source=ad`.

## Click-to-WhatsApp ads

Nothing to set up. When someone taps an ad, WhatsApp tells us which ad it was; if they order within 7 days, the order is credited to it. Tip: set the ad's prefilled message to include a product's share code — *"Hi! I'd like the Sunday special (P-7K2Q)"* — and the customer lands on that product.

### Reporting sales back to Meta

For ad-attributed orders, Kibanda reports `OrderCreated`, `Purchase` (when paid), `OrderDelivered` and `OrderCanceled` to Meta's Conversions API for Business Messaging, with the click id. That lets Meta optimise your ads for people who actually buy, not just people who message. Each event is sent once.

This uses your WhatsApp Business Account's dataset (created automatically). Meta requires advanced access to the `whatsapp_business_manage_events` permission for the app sending them.

## Landing pages and UTM tags

Point an ad at your shop page with UTM tags — `https://api.kibanda.africa/s/<shop-slug>?utm_source=facebook&utm_campaign=october` — and they're saved on the order. The same works with the website button.