API Documentation

Furniture, appliances and bulky goods

Add a goods manifest to a booking: each line with its weight and size per item. Areye works out the real and volumetric weight, picks the smallest vehicle whose door, load bay, payload and equipment actually fit every item (turning items where they may be turned), decides the crew, and prices every line in the market's currency. The same body sent to POST /business/bulky/quote returns exactly what the booking will freeze. Totals you send are ignored. A booking without goods is exactly as before.

• Service levels: curbside, doorstep, room_of_choice. Assembly, installation and removal only where Areye has authorised your business; otherwise the order is held for review. An ordinary driver is never assumed to install anything.
• Access: for room of choice give the floor, and on an upper floor whether there is a working lift. Missing access is never guessed: the order is held for review.
• Outcomes: 201 booked; 202 booked and held for review; 422 bulky_refused with the evidence, nothing created.
• Proof: what the driver must capture is frozen on the order: condition photos, serials, the items checked against your order, who handed over, where they were placed, the recipient's first names, surname and signature. The driver cannot leave or finish without it. Read it back on GET /business/trips/{trip} under bulky.
• Problems: trip.exception reports one of 14 structured problems. Before collection, an unsafe or wrong load goes back to operations, not to another driver blind.
• Returns: a return to your store is charged at the percentage shown in the quote's terms, of the route fare, once.
• Delivery window: send delivery_window and, for estates or offices, access.restricted_hours (e.g. 08:00-17:00). The order is not offered before it can arrive on time, cannot be taken once the window can no longer be met, and a window that cannot be met is refused at booking.
• Several items: Areye approves a multi-item load automatically only when it can show how the items stand together in the vehicle (fit.packing_confidence: "proven"). Otherwise the order is held for a person to check, never approved on volume alone.
• When it does not go to plan: the driver records each line as delivered, damaged, refused or short (trip.delivery_outcome); what was not delivered comes back with proof. You can then authorise disposal of damaged or refused lines, or order one redelivery. Waiting, cancelling after a driver is committed, redelivery and disposal are charged as frozen in the order's rules, once each.
• Shop connectors: GET /business/bulky/schema is the versioned contract. A WooCommerce, Shopify or OpenCart connector maps each product's packed weight and size onto a goods line and sends the order; it never picks a vehicle or computes a price. A product with no weight or size is sent without guessing and the order is held for review.

The figures below are from Areye's automated test market (BWP), shown so you can see the shape and the decisions. Your market's vehicles and prices apply to your orders.

1. A fridge

An upright fridge needs a tall door, a closed body and two people.

POST /business/book
{ ...route and recipient...,
  "goods": [{"description": "Fridge", "category": "refrigerator", "weight_kg": 85,
             "length_cm": 70, "width_cm": 75, "height_cm": 185, "upright": true, "serial": "FR-2026-0001"}],
  "needs": {"body": "closed"} }

201  "bulky": { "status": "ok", "fit": {"vehicle_name": "One-ton closed with tail lift"},
                "crew": {"required": 2},
                "quote": {"lines": [{"code": "route_fare", "amount": 287}, {"code": "bulky_surcharge", "amount": 60},
                                    {"code": "crew", "label": "1 additional crew", "amount": 150}],
                          "merchant_total": 497, "currency": "BWP"} }

2. A king bed to the bedroom

Base and mattress are 183 cm wide: they do not pass a small van's door, so a larger vehicle is chosen; room of choice is priced as its own line.

"goods": [{"description": "King bed base", "category": "bed", "weight_kg": 55, "length_cm": 200, "width_cm": 183, "height_cm": 40},
          {"description": "King mattress", "category": "mattress", "weight_kg": 45, "length_cm": 200, "width_cm": 183, "height_cm": 30}],
"service_level": "room_of_choice", "access": {"floor": 0}

201  status "ok" · vehicle "One-ton closed with tail lift" · crew 2
     evidence for "Cargo Van": "line 1 (King bed base) does not fit through the door or in the bay"
     lines: route fare 287 · handling 60 · 1 additional crew 150 · room-of-choice 80 · total 577

3. A sofa for two people

Any item of 40 kg or more is a two-person lift; the smallest vehicle that takes it is used.

"goods": [{"description": "3-seater sofa", "category": "sofa", "weight_kg": 60, "length_cm": 210, "width_cm": 90, "height_cm": 85}]

201  status "ok" · vehicle "Cargo Van" · crew 2 · total 469

4. An appliance batch

Three stops, each a fridge and a washer, one driver. The vehicle is chosen for the combined load (465 kg aboard at once); the crew is charged once, on the first stop.

POST /business/batches
{ "stops": [ {...route..., "goods": [fridge, washer]}, {...}, {...} ] }

201  "bulky": { "status": "ok", "run": { "vehicle": "One-ton closed with tail lift", "crew": 2,
                 "totals": {"actual_weight_kg": 465}, "load_order": [3, 2, 1], "unload_order": [1, 2, 3] } },
     "stop_quotes": [ {"merchant_total": 497}, {"merchant_total": 347}, {"merchant_total": 347} ]

5. Too large for any vehicle

Refused with the reason and the evidence for every vehicle. Nothing is created and nothing is charged; for a batch, no stop is created.

"goods": [{"description": "Generator", "weight_kg": 3500, "length_cm": 200, "width_cm": 120, "height_cm": 150}]

422  { "code": "bulky_refused",
       "message": "No vehicle in this market can carry this load safely. Line 1 weighs 3500 kg; ...",
       "bulky": { "status": "refused", "fit": {"evidence": { "...": {"qualifies": false, "why_not": ["payload 3000 kg < 3500 kg"]} } } } }

6. Room of choice on an upper floor, lift unknown

The order is booked and held: no driver is sent until operations has checked it. If the checked price is higher you get trip.quote_changed and accept or decline it.

"goods": [washer], "service_level": "room_of_choice", "access": {"floor": 3}

202  "review_state": "manual_review_required",
     "bulky": { "status": "manual_review_required",
                "review": {"reasons": ["An upper floor needs to say whether there is a working lift."]} }
→ webhook trip.review_required, then trip.review_approved (or trip.quote_changed → POST .../bulky/accept-quote)

Integrating a merchant platform

If you run a marketplace, restaurant group, grocery chain or online store and want Areye drivers to deliver your orders, you do not need a separate product. You use the same /business/book endpoint with extra fields. Your customers stay in your app; Areye handles dispatch, the driver relationship and proof of delivery.

What the driver actually sees

When you send order_payload, the driver gets a full order card — your store, your item list with photos, and the money to handle — instead of a bare pickup/drop-off pair. Every field below maps to something on that screen, so send what you want the driver to know.

The flow

1. Customer orders and pays in your app, however you already collect payment.
2. Your backend calls POST /business/book with pickup (your store), drop-off (your customer) and the order payload.
3. Areye dispatches a nearby driver and starts firing webhooks.
4. You call POST /business/trip/{reference}/ready when the order is packed.
5. Your customer follows the live map at the booking's tracking_url (or your own map, polling it; see Live tracking) and can message the driver.
6. Driver hands over against a delivery code, plus a proof-of-delivery photo if your account requires one. Delivery fees are debited from your Areye wallet.

Creating a merchant order

POST /api/business/book
X-Business-API-Key: your_api_key_here
Content-Type: application/json

{
  "type": "parcel",
  "pickup_address": "Choppies Riverwalk, Gaborone",
  "pickup_lat": -24.6541, "pickup_lng": 25.9237,
  "dest_address": "Plot 22, Phakalane",
  "dest_lat": -24.5821, "dest_lng": 25.9412,
  "passenger_name": "Kagiso M.",
  "passenger_phone": "+26771234567",

  "prep_minutes": 15,
  "handover_required": false,
  "age_verification_required": false,
  "cod_amount": 348.50,
  "bring_change_amount": 500.00,

  "order_payload": {
    "store_name": "Choppies Riverwalk",
    "store_phone": "+2673901234",
    "external_reference": "CHP-88421",
    "module_type": "grocery",
    "order_amount": 348.50,
    "order_note": "Leave at the gate if no answer",
    "items": [
      { "name": "Milk 2L", "qty": 2, "price": 24.00,
        "image": "https://cdn.example.com/milk.jpg" },
      { "name": "Brown bread", "qty": 1, "price": 12.50,
        "options": "Sliced" }
    ]
  }
}

Choosing how money moves

Age-restricted orders (alcohol, tobacco)

Send age_verification_required: true on any order containing alcohol, tobacco or anything else with a minimum age. The driver is then blocked from completing the delivery until they have checked the buyer's photo ID and recorded the outcome. The proof-of-delivery photo and signature captured at that moment are the evidence.

Read the result back from any trip response — age_verification_required and age_verification_outcome — and use it to decide whether to refund. A return leg is exempt from the check, since nothing is being handed to a buyer.

Webhooks you will receive

Set your endpoint on PATCH /business/profile. Every payload carries reference — match it to the external_reference you sent. Each request also carries X-Areye-Event and X-Areye-Signature (sha256=HMAC-SHA256(raw_body, your_webhook_secret)) — your webhook_secret and Webhook URL are on the portal Settings & API page (separate from your API key) — verify it with a constant-time comparison before trusting the payload.

Cash on delivery: the money terms

• Fee: Areye keeps your account's COD fee (cod_fee_pct, a percentage of the cash collected), booked as a fee line when the settlement is made.
• Cycle: collected cash is gathered into a settlement on your settlement_cycle (for example weekly), one settlement per currency.
• Netting: when cod_netting_enabled is true, what your account owes Areye is taken from the settlement before it is paid out.
• Endpoints: GET /business/cod/ledger returns cod_enabled, cod_fee_pct, settlement_cycle, cod_netting_enabled, unsettled_amount and the last 200 entries; GET /business/cod/settlements lists settlements.
• cod.settlement_ready and cod.settled payload (data): id, reference, period_start, period_end, gross, fee, net, currency, status, paid_at, orders. net = gross − fee (less any netting); paid_at is null until cod.settled.

Before you go live

• Fund your wallet, or ask us to enable invoiced billing — delivery fees are debited per order, and a flat wallet stops dispatch.
• Send us your store list and service areas so we can confirm driver coverage around each branch.
• Ask us to enable proof-of-delivery photos if you need them for disputes.
• Selling alcohol or tobacco? Flag those orders with age_verification_required, keep delivery windows inside your licensed trading hours, and handle refunds for refused handovers.
• Serve item images over HTTPS from a public URL — signed or expiring links will show as placeholders.
• Store our reference against your order. It is the key for tracking, chat, webhooks and support.
• Dedicated driver pools, default prep times and shop-and-deliver access are configured per account — tell us your volumes and we will set them.

Courier platform

For courier companies running their own operation on Areye, and for the marketplaces and accounting systems that connect to them: instant prices and booking on versioned rate cards, client billing (prepaid, credit or your own accounting system), signed billing events and exports, long-running shipments with milestones, health and alerts, network runs across borders with customs and laboratory samples, and what a courier's drivers may receive.

Read the courier platform integrator guide →

In-store shopping fulfilment

Version: shopping fulfilment v1 · Last changed: 11 October 2026 (creation vs arrival order clarified; 410 Gone refusal and replay; outcome set and field meanings stated). Policy: within v1 changes are additive only (new optional fields, events or values you can ignore; no field is ever repurposed). A breaking change comes as a new version, announced to your technical contact, with the old version kept running at least 90 days alongside it — and, because these events carry money (refunds and amounts collected), never switched off until every integrator using it has demonstrably moved.

Send one order that a single Areye shopper buys across several stores (for example the shops in a shopping centre) and delivers in one trip. You send a pick list per store; the shopper marks each line found, substituted or unavailable under the customer's substitution preference, photographs each store's till receipt, and Areye tells your platform what happened through signed webhooks to your URL, signed with your secret. It is an ordinary shop & deliver merchant order underneath: the shopper is fronted the shelf money and the float reconciles on the till receipts. The full integrator guide is also available as docs/SHOPPING_FULFILMENT.md on request.

1. Switching it on

The capability is off by default for every account. While it is off, nothing about your other bookings changes, the endpoints below answer 403 SHOPPING_FULFILMENT_OFF, and nothing is ever sent. Ask Areye support to enable it for your account. Then set your webhook URL and issue your secret:

# where your events go (public HTTPS only; no private networks, no credentials in the URL; redirects are never followed)
curl -s -X PUT $AREYE/business/shopping-fulfilment -H "X-Business-API-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"webhook_url":"https://partner.example/webhooks/areye-shopping"}'

# issue (or rotate) your signing secret -- shown ONCE in the response
curl -s -X POST $AREYE/business/shopping-fulfilment/secret/rotate -H "X-Business-API-Key: $KEY"

# check your setup: enabled, webhook_url, webhook_secret_set, sending ("ok" or the reason nothing can be sent)
curl -s $AREYE/business/shopping-fulfilment -H "X-Business-API-Key: $KEY"

Rotating takes effect at once, including for retries of earlier events. Each integrator has its own URL and secret; no other account's orders or events are ever visible to you.

2. Authentication

Every call uses your Business API key in X-Business-API-Key, or a scoped partner key (see Partner keys), exactly like the rest of the Business API.

3. Creating a shopping order

POST /business/shopping-orders. It takes the same pickup and drop-off fields as POST /business/book (pickup_address, pickup_lat, pickup_lng, dest_address, dest_lat, dest_lng, optional scheduled_at, notes, delivery_code, payment_method, test), the recipient as first names and surname, and a shopping block. Retries are safe on external_reference (defaults to your external_order_id), as for every booking.

curl -s -X POST $AREYE/business/shopping-orders -H "X-Business-API-Key: $KEY" -H "Content-Type: application/json" -d '{
  "recipient_first_names": "Kagiso Thabo",
  "recipient_surname": "Molefe",
  "recipient_phone": "+26771234567",
  "pickup_address": "Riverwalk Mall, Gaborone", "pickup_lat": -24.6639, "pickup_lng": 25.9318,
  "dest_address": "Plot 1234, Block 8", "dest_lat": -24.6280, "dest_lng": 25.9030,
  "purchase_amount": 120.00,
  "shopping": {
    "external_order_id": 123456,
    "external_location_id": 3,
    "substitution_preference": "ask",
    "stores": [
      { "external_fulfilment_id": 9001, "external_store_id": 2, "store_name": "Fresh Grocer", "sequence": 1,
        "estimated_amount": 56.00,
        "items": [ { "external_item_id": 7001, "name": "Full cream milk 2L", "qty": 2, "unit_price": 28.00,
                     "barcode": "6001234567890", "image": "https://cdn.partner.example/milk.jpg" } ] },
      { "external_fulfilment_id": 9002, "external_store_id": 5, "store_name": "City Pharmacy", "sequence": 2,
        "estimated_amount": 64.00,
        "items": [ { "external_item_id": 7002, "name": "Paracetamol 500mg x24", "qty": 1, "unit_price": 64.00 } ] }
    ]
  }
}'

The response is the same as /business/book (201 with the trip reference). Read the order's live state at any time with GET /business/shopping-orders/{reference}, and your outbound events with GET /business/shopping-fulfilment/deliveries.

4. Substitution preferences and the decision window

The preference is one of exactly refund, match or ask. Omitted means refund; any other value is refused with 422 before anything is booked. It is fixed on the order when it is created: a retry of the same order with a different preference is refused with 409 external_reference_conflict, and the preference travels with the shopper's pick list.

• refund (default): a missing line is marked unavailable; the shopper may not buy a substitute. You refund the customer for it.
• "match" — shown to customers as “Allow a suitable substitute”. Send the exact literal match; no other spelling is accepted. The shopper may buy a like-for-like substitute without asking (decided_by: "preference") only within limits frozen on the order when it is created: no more pieces than ordered; a unit price no higher than the line's unit_price plus the margin (default 10% for new orders, read it from match_price_tolerance_pct in GET /business/shopping-fulfilment); a line total no higher than the line's max_line_amount; and the basket staying within max_basket_amount (your purchase_amount), counting what is already bought and the original value of lines still to shop. The order keeps its own match_margin_pct, currency and ceilings: a later change to the default never reinterprets an order already placed. Outside any limit, or when the line has no listed price, the substitute becomes a proposal and you receive shopping.substitution_requested with reason: "outside_substitution_limits", exactly as under ask.
• ask: a substitute is only a proposal. You receive shopping.substitution_requested, ask your customer, and answer within the decision window (default 5 minutes; the current value is ask_timeout_minutes in GET /business/shopping-fulfilment). No answer in time falls back to refund (unavailable, decided_by: "preference").

curl -s -X POST $AREYE/business/shopping-orders/T8F3A21QZ/items/7001/decision -H "X-Business-API-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"decision":"accept"}'     # or "reject"
# 200 -> the line's outcome; 409 "The decision window closed; the item was refunded." when too late

decided_by is one of shopper (found, or unavailable on the shelf), customer (your accept/reject) or preference (match, or the window closing).

5. Events you will receive

POST to your webhook URL, Content-Type: application/json. Store status is collected or unavailable (the whole store could not be shopped); line outcome is found, substituted or unavailable — the complete set; there is no other value (an unavailable line is the one you refund).

Creation order, not arrival order. Every store — collected or unavailable — gets its own shopping.store_collected event, and all of them are created before the order's single shopping.basket_collected. Delivery is at-least-once: a store event that failed and is being retried can arrive after the basket event, and any event can arrive more than once. So: dedupe on event_id (= X-Areye-Delivery), never rely on arrival order, and use basket_collected.stores[] as the authoritative summary of every store's final status and amount. If an event seems to be missing, fetch the order's current state with GET /business/shopping-orders/{trip_reference}; your delivery history is at GET /business/shopping-fulfilment/deliveries.

"proposed_substitute" vs "substitute": deliberately different names. item.proposed_substitute in shopping.substitution_requested is a proposal awaiting the customer's decision; items[].substitute in shopping.store_collected is what was actually bought (present only when outcome is substituted).

shopping.substitution_requested (preference "ask" only)

{"event":"shopping.substitution_requested","event_id":"areye-shop-41-ask-310","external_order_id":123456,"trip_reference":"T8F3A21QZ",
 "store":{"external_fulfilment_id":9001,"external_store_id":2},
 "item":{"external_item_id":7001,"qty_requested":2,"proposed_substitute":{"name":"Store-brand 2L","barcode":"600xxxx","unit_price":27.25},"qty_found":2},
 "expires_at":"2026-10-10T09:05:00+02:00","at":"2026-10-10T09:00:00+02:00"}

shopping.store_collected (once per store)

{"event":"shopping.store_collected","event_id":"areye-shop-41-store-87","external_order_id":123456,"trip_reference":"T8F3A21QZ",
 "store":{"external_fulfilment_id":9001,"external_store_id":2,"status":"collected","estimated_amount":56.0,"collected_amount":54.5,
          "currency":"BWP","receipt_photo_url":"https://api.areye.app/api/shopping/receipts/87?expires=...&signature=..."},
 "items":[{"external_item_id":7001,"outcome":"substituted","qty_requested":2,"qty_found":2,"unit_price_paid":27.25,
           "substitute":{"name":"Store-brand 2L","barcode":"600xxxx","unit_price":27.25},"decided_by":"customer"}],
 "at":"2026-10-10T09:00:00+02:00"}

shopping.basket_collected (exactly once per order)

{"event":"shopping.basket_collected","event_id":"areye-shop-41-basket","external_order_id":123456,"trip_reference":"T8F3A21QZ",
 "stores":[{"external_fulfilment_id":9001,"external_store_id":2,"status":"collected","estimated_amount":56.0,"collected_amount":54.5},
           {"external_fulfilment_id":9002,"external_store_id":5,"status":"unavailable","estimated_amount":64.0,"collected_amount":0.0}],
 "collected_total":54.5,"currency":"BWP","at":"2026-10-10T09:40:00+02:00"}

shopping.basket_collected is emitted exactly once, when every store is collected or unavailable; then the shopper heads to the customer and the ordinary trip webhooks (see Webhooks) continue. Those trip.* events go to your business webhook URL (the one for all your trips), not to the shopping webhook URL — a shopping receiver receives only shopping.* events. Amounts are in currency, which is the order's billing currency fixed when you booked it; it never changes during the order, and you need not validate it beyond that.

6. Signature (HMAC-V2)

Each request carries:

X-Areye-Timestamp: 1791621174                 # unix seconds at the moment of sending
X-Areye-Delivery: areye-shop-41-store-87      # the event_id; identical on every retry
X-Areye-Event: shopping.store_collected
X-Areye-Signature-V2: t=1791621174,sha256=<hex>

signing string = <timestamp> + "." + <raw body bytes>
hex            = lowercase hex of HMAC-SHA256(your secret, signing string)

Worked example. Secret TEST_ONLY_example_secret, timestamp 1791621174, body exactly the shopping.store_collected example above written on one line with no spaces and "receipt_photo_url":"https://signed.example/receipt.jpg", gives 4bb3c00dcf528d4f53795e87c5e1d958175d9d33b7496e3bbc8f2f9fc78d7e47. The exact bytes are in the integrator guide.

// PHP -- verify BEFORE parsing; use the raw body exactly as received
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_AREYE_TIMESTAMP'] ?? '';
$hdr = $_SERVER['HTTP_X_AREYE_SIGNATURE_V2'] ?? '';
$ok  = ctype_digit($ts) && abs(time() - (int) $ts) <= 300
    && hash_equals("t={$ts},sha256=" . hash_hmac('sha256', $ts . '.' . $raw, getenv('AREYE_SHOPPING_SECRET')), $hdr);
if (! $ok) { http_response_code(401); exit; }

// Node (Express: app.use(express.raw({ type: 'application/json' })))
const ts = req.get('X-Areye-Timestamp') || '';
const want = `t=${ts},sha256=` + crypto.createHmac('sha256', process.env.AREYE_SHOPPING_SECRET)
  .update(ts + '.').update(req.body).digest('hex');
const got = req.get('X-Areye-Signature-V2') || '';
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const ok = fresh && got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));

Reject a timestamp more than 5 minutes from your clock. The timestamp is fresh on every attempt, so a retry hours later still verifies; the body bytes never change.

7. Idempotency and retries

• Any 2xx is success. Anything else, a timeout, or a redirect is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours (6 attempts by default).
• Versioning on every event: the body carries api_version (v1), event_type (same as event), event_id and occurred_at; headers carry X-Areye-Api-Version: v1 and X-Areye-Attempt-Id (new on every attempt — dedupe on event_id, not on the attempt id). In v2 the event-specific fields will move under payload; v1 keeps its current shape.
• Signature V3 (recommended): X-Areye-Signature-V3: t={timestamp},sha256={hex}, hex = HMAC-SHA256 with your secret of this canonical string — five lines joined by \n, in this order: api_version, X-Areye-Delivery-Timestamp, event_id, X-Areye-Attempt-Id, and base64 of the SHA-256 digest of the exact raw body. Also check that X-Areye-Event-Id and X-Areye-Api-Version equal the body's event_id and api_version. X-Areye-Key-Id names the secret that signed it: when you rotate your secret, keep the old one until events arrive under the new key id. Reject a delivery timestamp more than 5 minutes from your clock; a replay is a fresh delivery (new timestamp and attempt id, same event_id and body), so it always verifies. V2 (timestamp + "." + body) is still sent unchanged; move to V3 when you can.
• To refuse an event for good (for example it names an order you do not have), answer 410 Gone, optionally with a short reason in the body. Areye records that event as refused (never as delivered), with your reason, endpoint and time, alerts its operations team, and stops retrying that event only — every other event to your endpoint carries on. Once you have corrected your side, replay it with POST /business/shopping-fulfilment/deliveries/{event_id}/replay (the same event_id and body; a reason is required and recorded; at most 10 replays a minute; it always goes to your configured webhook URL, never to one in the request). Do not use 2xx for an event you did not process; dead-letter it on your side or answer 410.
• Every retry sends the same body bytes and the same X-Areye-Delivery (= event_id). Dedupe on it and answer 2xx for anything you have already processed.
• Events are sent only after Areye has saved the change they report. Order between events is not guaranteed across retries; use status and outcome, never arrival order.
• While your account has no secret or no valid URL, events are held (not dropped and not counted as attempts) and go out once both are set. GET /business/shopping-fulfilment says why nothing is sending.

8. Receipt photos

receipt_photo_url is a signed link to the photographed till receipt, valid for at least 10 minutes (currently receipt_url_ttl_minutes in GET /business/shopping-fulfilment, 24 hours by default). Copy the image to your own storage when you receive the event; an expired or altered link answers 403.

9. Errors

10. Testing

Test your signature check against the worked example above before anything else. To run a shopping order end to end, ask Areye support for a sandbox session: real shopping orders are only ever handled by real shoppers, so test runs are arranged with the operations team rather than fired at the live network. Point your webhook URL at a public HTTPS endpoint you control and watch GET /business/shopping-fulfilment/deliveries for each event's state, attempts and last error.

Rewards & Gift Cards

Areye is the parent registry for coupons and gift cards across the whole suite. One code is minted once, and every platform that accepts it — Areye itself and any merchant integrated with these endpoints — validates and redeems it against the same ledger. That means a customer cannot spend the same code twice on two different platforms, and you get one reconciliation trail instead of several.

Two instruments, two very different money models

Read this before you issue anything. The difference is not cosmetic — it decides when your wallet is debited and what happens to value the customer does not use.

Three ways a gift card is redeemed

All three are live at the same time, and all three move the same balance on the same card. You do not choose one at issuance — the holder chooses at spend time.

Settlement: who bears the discount, who gets paid back

How a code is consumed

Every code also carries a redemption mode, which decides what happens the first time it is used. You rarely set this yourself — it is derived from the instrument type — but it is returned on every code and is worth understanding.

Batches minted through POST /business/coupons/issue are issuer-funded reward coupons, or prepaid gift_card stored value when instrument_type says so. Reversing a redemption claws back both sides: the reimbursement is debited off the merchant who no longer gave anything up, and a wallet-funded issuer gets their money back. A gift card gets its drawn-down value returned to the balance. That is why /reverse is not optional.

Redemption lifecycle

Three calls, in this order. /validate is a dry run you make while the customer is still on the checkout screen; /redeem is the committing call and the only place a usage counter or a stored balance ever moves; /reverse puts the value back if the order later fails.

/validate returns valid, reason (a message safe to show the customer when invalid), discount_amount, discount_type, coupon_id, currency, instrument_type, stackable, and for gift cards remaining_value plus remaining_after so you can show the customer what will be left on the card. /redeem answers 200 with redemption_id and idempotent, or 422 with a reason (expired, already used, below min_spend, wrong currency, out of scope, bad PIN, issuer wallet short). Treat any non-200 as “no discount applied” and charge the full amount.

POST /api/business/coupons/redeem
X-Business-API-Key: your_api_key_here
Content-Type: application/json

{
  "code": "AREYE-7K2MQX",
  "currency": "BWP",
  "order_amount": 120.00,
  "external_order_ref": "SHOP-88421",
  "user_key": "+26771234567",
  "merchant_ref": "riverwalk",
  "pin": "4821"
}

Issuing a batch

POST /business/coupons/issue mints up to 1,000 codes at once and returns them, along with one-time PINs when the batch is gift cards. Set instrument_type to discount (default) or gift_card. Codes are generated from an unambiguous character set with no 0/O/1/I/L, so they survive being printed and read over the phone.

POST /api/business/coupons/issue
X-Business-API-Key: your_api_key_here
Content-Type: application/json

{
  "instrument_type": "gift_card",
  "quantity": 50,
  "currency": "BWP",
  "value": 200.00,
  "prefix": "STAFF",
  "batch_label": "Q3 staff rewards",
  "activate": true,
  "activation_channel": "admin",
  "expires_at": "2027-12-31T23:59:59+02:00"
}

201 Created
{
  "success": true,
  "data": {
    "batch_id": "BATCH-XXXXXXXXXX",
    "issued": 50,
    "coupons": [
      { "id": 9001, "code": "STAFF-4H8P2Q", "pin": "8140", "value": 200 }
    ],
    "note": "PINs are shown once and cannot be retrieved later ..."
  }
}

Managing batches and cards

Public gift-card storefront

Consumers buy Areye-issued cards on the storefront at areye.app/gift-cards, which uses the unauthenticated, rate-limited /api/gift-cards/* family. You can drive the same flow from your own site. Nothing spendable is minted until the gateway confirms the money — never from the browser.

Legacy promos and the unified code box

Areye had its own promotions system before the suite-wide registry existed. The two now resolve through one path: a passenger types a code into a single box, and Areye checks the suite registry first and the legacy promo table second. The customer never has to know which system their code lives in, and the booking screen and the Promotions screen can never disagree about what a code is worth.

Note the shapes: POST /business/coupons is the legacy single-promo create, while POST /business/coupons/issue mints a suite-wide batch. New integrations should use the /coupons/* family throughout.