Developer API

WhatsApp Commerce, Orders, Finance & Usage API

Export WhatsApp Commerce orders, normalized SKU line items, paid GMV & fulfilment SLA analytics, metered WhatsApp message usage, Auth OTP challenges, and loyalty balances.

Connect your ERP, OMS, or finance warehouse directly to WhatsApp Commerce orders, revenue analytics, and messaging telemetry.

1. List WhatsApp Orders (GET /api/v1/whatsapp/orders)

Endpoint: GET https://profilepilotapp.com/api/v1/whatsapp/orders Required Scope: whatsapp:read or reports:read Required Product Subscription: WhatsApp Commerce + Developer API Access

Query Parameters:

startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC)
status ("prep_queue" | "verification" | "dispatched" | "completed" | "cancelled", optional — returns 400 if an unknown status is passed)
paymentStatus or payment_status ("pending" | "paid" | "unpaid_cod" | "payshap_review", optional)
fulfillmentType or fulfillment_type ("delivery" | "collection", optional)
limit (1–500, default 100) & offset (default 0)

Performance Metrics & Response Fields (`orders[]`):

id (UUID), org_id (UUID), wa_id (string customer WhatsApp E.164 digits), customer_name (string | null).
order_status, payment_status, payment_gateway, fulfillment_type, fulfillment_date.
total_amount (number), delivery_fee (number), food_amount (number net goods amount excluding delivery fee).
dropoff_address (object | null), delivery_km (number | null).
cart_items (array raw cart snapshot) & lines[] (normalized OMS export lines: { line_number, product_id, sku, name, qty, unit_price, line_total, is_reward }).
ready_at, dispatched_at, completed_at, created_at, updated_at (string | null ISO-8601 timestamps).

curl -sS -X GET "https://profilepilotapp.com/api/v1/whatsapp/orders?status=completed&paymentStatus=paid&limit=50" \
  -H "Authorization: Bearer ppapi_your_secret_key"

{
  "ok": true,
  "period": { "startDate": "2026-10-01", "endDate": "2026-10-20" },
  "currency": "ZAR",
  "total": 148,
  "limit": 50,
  "offset": 0,
  "orders": [
    {
      "id": "fb29c810-4411-4a88-9a21-001122334455",
      "org_id": "00000000-0000-0000-0000-000000000000",
      "wa_id": "27821234567",
      "customer_name": "Thabo Nkosi",
      "cart_items": [],
      "lines": [
        {
          "line_number": 1,
          "product_id": "prod_01",
          "sku": "BV-5KG",
          "name": "Bulk Beef Viennas 5kg",
          "qty": 5,
          "unit_price": 250.00,
          "line_total": 1250.00,
          "is_reward": false
        }
      ],
      "total_amount": 1315.00,
      "delivery_fee": 65.00,
      "food_amount": 1250.00,
      "order_status": "completed",
      "payment_status": "paid",
      "payment_gateway": "payfast",
      "fulfillment_type": "delivery",
      "fulfillment_date": "2026-10-19",
      "dropoff_address": { "address": "14 Bree Street, Cape Town" },
      "delivery_km": 6.4,
      "ready_at": "2026-10-19T08:42:00Z",
      "dispatched_at": "2026-10-19T08:55:00Z",
      "completed_at": "2026-10-19T09:30:00Z",
      "created_at": "2026-10-19T08:14:00Z",
      "updated_at": "2026-10-19T09:30:00Z"
    }
  ]
}

2. Single WhatsApp Order Detail (GET /api/v1/whatsapp/orders/{id})

Endpoint: GET https://profilepilotapp.com/api/v1/whatsapp/orders/{id} Required Scope: whatsapp:read or reports:read Required Product Subscription: WhatsApp Commerce + Developer API Access Path Parameter: id (UUID of the WhatsApp order). Returns 404 Not Found if the order does not belong to your organisation.

Response Fields (`order`):

Includes all fields from orders[] above, plus courier dispatch telemetry (delivery_provider, uber_delivery_id, uber_tracking_url, uber_delivery_status) and fulfillment_timeline: { created_at, verified_at, ready_at, dispatched_at, customer_arrived_at, completed_at }.

curl -sS -X GET "https://profilepilotapp.com/api/v1/whatsapp/orders/fb29c810-4411-4a88-9a21-001122334455" \
  -H "Authorization: Bearer ppapi_your_secret_key"

{
  "ok": true,
  "currency": "ZAR",
  "order": {
    "id": "fb29c810-4411-4a88-9a21-001122334455",
    "org_id": "00000000-0000-0000-0000-000000000000",
    "wa_id": "27821234567",
    "customer_name": "Thabo Nkosi",
    "cart_items": [],
    "lines": [
      {
        "line_number": 1,
        "product_id": "prod_01",
        "sku": "BV-5KG",
        "name": "Bulk Beef Viennas 5kg",
        "qty": 5,
        "unit_price": 250.00,
        "line_total": 1250.00,
        "is_reward": false
      }
    ],
    "total_amount": 1315.00,
    "delivery_fee": 65.00,
    "food_amount": 1250.00,
    "order_status": "completed",
    "payment_status": "paid",
    "payment_gateway": "payfast",
    "fulfillment_type": "delivery",
    "fulfillment_date": "2026-10-19",
    "dropoff_address": { "address": "14 Bree Street, Cape Town" },
    "delivery_km": 6.4,
    "delivery_provider": "uber_direct",
    "uber_delivery_id": "del_998877",
    "uber_tracking_url": "https://ters.uber.com/track/del_998877",
    "uber_delivery_status": "delivered",
    "ready_at": "2026-10-19T08:42:00Z",
    "dispatched_at": "2026-10-19T08:55:00Z",
    "completed_at": "2026-10-19T09:30:00Z",
    "created_at": "2026-10-19T08:14:00Z",
    "updated_at": "2026-10-19T09:30:00Z",
    "fulfillment_timeline": {
      "created_at": "2026-10-19T08:14:00Z",
      "verified_at": "2026-10-19T08:16:00Z",
      "ready_at": "2026-10-19T08:42:00Z",
      "dispatched_at": "2026-10-19T08:55:00Z",
      "customer_arrived_at": null,
      "completed_at": "2026-10-19T09:30:00Z"
    }
  }
}

3. WhatsApp Commerce Finance, Queue SLA & Top Products Report (GET /api/v1/whatsapp/reports/finance)

Endpoint: GET https://profilepilotapp.com/api/v1/whatsapp/reports/finance Required Scope: whatsapp:read or reports:read Required Product Subscription: WhatsApp Commerce + Developer API Access

Query Parameters:

startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC; automatically computes the equal-length prior period for comparison).

Performance Metrics & Response Fields:

summary: { revenue, grossProductSales, deliveryFees, netOfVat, completedOrders, cancelledOrders, fulfillmentRate, count, food_total, delivery_total, grand_total, averageOrderValue, totalOrdersInPeriod }.
finance.current & finance.previous: Full current vs prior period financial breakdown.
finance.changePct (deltas): Period-over-period % change for { revenue, completedOrders, cancelledOrders, fulfillmentRate }.
finance.metaBillable: Metered WhatsApp spend during the period ({ totalUsd, byCategory }).
queue: Live operations snapshot ({ activeToday, queueValue, avgFulfillMinutes, filters: { allActive, prepQueue, readyForDispatch, distanceUnset } }).
catalog: Product catalog health ({ total, active, specials, soldOut, avgLeadHours }).
paymentGatewayBreakdown[]: { gateway, orders, revenue }.
fulfillmentBreakdown[]: { fulfillment_type, orders, revenue, delivery_fees }.
topProducts[]: Top 25 SKUs by paid revenue ({ sku, product_id, name, qty_sold, order_count, revenue }).

curl -sS -X GET "https://profilepilotapp.com/api/v1/whatsapp/reports/finance?startDate=2026-10-01&endDate=2026-10-20" \
  -H "Authorization: Bearer ppapi_your_secret_key"

{
  "ok": true,
  "period": {
    "startDate": "2026-10-01",
    "endDate": "2026-10-20",
    "previousPeriodLabel": "2026-09-11…2026-09-30"
  },
  "currency": "ZAR",
  "summary": {
    "revenue": 194620.00,
    "grossProductSales": 185000.00,
    "deliveryFees": 9620.00,
    "netOfVat": 160869.57,
    "completedOrders": 144,
    "cancelledOrders": 14,
    "fulfillmentRate": 91.1,
    "count": 148,
    "food_total": 185000.00,
    "delivery_total": 9620.00,
    "grand_total": 194620.00,
    "averageOrderValue": 1315.00,
    "totalOrdersInPeriod": 162
  },
  "finance": {
    "current": {
      "revenue": 194620.00,
      "grossProductSales": 185000.00,
      "deliveryFees": 9620.00,
      "netOfVat": 160869.57,
      "completedOrders": 144,
      "cancelledOrders": 14,
      "fulfillmentRate": 91.1,
      "count": 148,
      "food_total": 185000.00,
      "delivery_total": 9620.00,
      "grand_total": 194620.00
    },
    "previous": {
      "revenue": 172400.00,
      "grossProductSales": 164100.00,
      "deliveryFees": 8300.00,
      "netOfVat": 142695.65,
      "completedOrders": 129,
      "cancelledOrders": 15,
      "fulfillmentRate": 89.6,
      "count": 131,
      "food_total": 164100.00,
      "delivery_total": 8300.00,
      "grand_total": 172400.00
    },
    "changePct": {
      "revenue": 12.9,
      "completedOrders": 11.6,
      "cancelledOrders": -6.7,
      "fulfillmentRate": 1.5
    },
    "metaBillable": {
      "totalUsd": 412.85,
      "byCategory": {}
    }
  },
  "queue": {
    "activeToday": 6,
    "queueValue": 7890.00,
    "avgFulfillMinutes": 38.4,
    "filters": {
      "allActive": 6,
      "prepQueue": 6,
      "readyForDispatch": 2,
      "distanceUnset": 1
    }
  },
  "catalog": {
    "total": 84,
    "active": 78,
    "specials": 9,
    "soldOut": 6,
    "avgLeadHours": 2.5
  },
  "paymentGatewayBreakdown": [
    { "gateway": "payfast", "orders": 112, "revenue": 149800.00 },
    { "gateway": "payshap", "orders": 36, "revenue": 44820.00 }
  ],
  "fulfillmentBreakdown": [
    { "fulfillment_type": "delivery", "orders": 104, "revenue": 142100.00, "delivery_fees": 9620.00 },
    { "fulfillment_type": "collection", "orders": 44, "revenue": 52520.00, "delivery_fees": 0 }
  ],
  "topProducts": [
    {
      "sku": "BV-5KG",
      "product_id": "prod_01",
      "name": "Bulk Beef Viennas 5kg",
      "qty_sold": 210,
      "order_count": 68,
      "revenue": 52500.00
    }
  ]
}

4. WhatsApp Messaging Usage, Auth OTP & Loyalty Report (GET /api/v1/whatsapp/reports/usage)

Endpoint: GET https://profilepilotapp.com/api/v1/whatsapp/reports/usage Required Scope: whatsapp:read or reports:read Required Product Subscription: WhatsApp Commerce or WhatsApp Authentication + Developer API Access

Query Parameters:

startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC).

Performance Metrics & Response Fields:

messages: total, inbound, outbound, billable_units, estimated_total_usd.
messages.by_category: { marketing, marketing_lite, utility, authentication, service } — each with { count, billable_count, total_usd }.
messages.delivery_status: { sent, delivered, read, failed }.
auth_otp_challenges: { total, pending, verified, failed, expired, exhausted }.
loyalty: Omnichannel loyalty summary from loyalty_org_summary (enrolled_members, active_points_balance, lifetime_points_issued, lifetime_points_redeemed).

curl -sS -X GET "https://profilepilotapp.com/api/v1/whatsapp/reports/usage?startDate=2026-10-01&endDate=2026-10-20" \
  -H "Authorization: Bearer ppapi_your_secret_key"

{
  "ok": true,
  "period": { "startDate": "2026-10-01", "endDate": "2026-10-20" },
  "messages": {
    "total": 18420,
    "inbound": 4120,
    "outbound": 14300,
    "billable_units": 12940,
    "estimated_total_usd": 412.85,
    "by_category": {
      "marketing": { "count": 8200, "billable_count": 8200, "total_usd": 319.80 },
      "marketing_lite": { "count": 1400, "billable_count": 1400, "total_usd": 44.80 },
      "utility": { "count": 2600, "billable_count": 2600, "total_usd": 36.40 },
      "authentication": { "count": 740, "billable_count": 740, "total_usd": 11.85 },
      "service": { "count": 1360, "billable_count": 0, "total_usd": 0 }
    },
    "delivery_status": {
      "sent": 14300,
      "delivered": 13980,
      "read": 10840,
      "failed": 320
    }
  },
  "auth_otp_challenges": {
    "total": 740,
    "pending": 12,
    "verified": 698,
    "failed": 9,
    "expired": 18,
    "exhausted": 3
  },
  "loyalty": {
    "enrolled_members": 3420,
    "active_points_balance": 184500,
    "lifetime_points_issued": 420000,
    "lifetime_points_redeemed": 235500
  }
}

5. Troubleshooting & Common Scenarios

Which orders count toward `summary.revenue` (paid GMV)? Only non-cancelled orders with payment_status equal to "paid" or "unpaid_cod" are included in paid GMV, paymentGatewayBreakdown, fulfillmentBreakdown, and topProducts. Cancelled or unpaid pending orders are counted in totalOrdersInPeriod and cancelledOrders.
Auth-only tenants (`whatsapp_auth` without `whatsapp_commerce`): Tenants subscribed only to WhatsApp Authentication OTP can call GET /api/v1/whatsapp/reports/usage for OTP and message metering; calling /api/v1/whatsapp/orders or /api/v1/whatsapp/reports/finance requires an active WhatsApp Commerce subscription.

Typical Tasks

Grant whatsapp:read scope to your API key
Sync orders and SKU line items via GET /api/v1/whatsapp/orders and /api/v1/whatsapp/orders/{id}
Pull GMV, period deltas, and queue SLA via GET /api/v1/whatsapp/reports/finance
Track billable message categories and OTP verification rates via GET /api/v1/whatsapp/reports/usage

Developer API Reference

All Developer & Reporting API Modules

Manage API Keys →

Store Sync

locations:readlocations:write

Enterprise Store Locations API

Push and query your canonical store master records (up to 100 stores per batch) by store_code.

POST/api/v1/locations

GET/api/v1/locations

GET/api/v1/locations/{store_code}

DELETE/api/v1/locations/{store_code}

Local Presence & SEO

reports:readlocations:read

Locations Metrics & Local SEO Geo-Grid API

Pull Google Business Profile impressions, website clicks, phone calls, direction requests, peak footfall days, Meta store metrics, and Geo-Grid Share of Voice.

GET/api/v1/reports/locations/metrics

GET/api/v1/reports/seo-grid

Reputation & CX

reputation:readreports:read

Reputation, Reviews, Red Flags & CSAT API

Export star ratings, customer reviews, reply rates, business-hours response times, Red Flag alerts, and Customer Satisfaction cases.

GET/api/v1/reports/reputation/summary

GET/api/v1/reputation/reviews

GET/api/v1/reputation/red-flags

GET/api/v1/reputation/csat

WhatsApp Commerce

whatsapp:readreports:read

WhatsApp Commerce, Orders, Finance & Usage API

Export WhatsApp orders with normalized line items, fulfilment SLAs, paid GMV analytics, metered message volume, Auth OTP challenges, and loyalty balances.

GET/api/v1/whatsapp/orders

GET/api/v1/whatsapp/orders/{id}

GET/api/v1/whatsapp/reports/finance

GET/api/v1/whatsapp/reports/usage

Email & Marketing

email:readmarketing:readreports:read