Data Integration: Orders & Webhooks

This guide provides instructions and best practices for connecting external Business Intelligence (BI) systems, data warehouses, and operational tools to the AiFi platform.

We currently support two primary methods for data integration: real-time events and historical analysis: Orders API (Pull): Best for scheduled reporting and reconciliation. Push Checkout Webhook (Real-Time): Best for immediate event triggers (e.g., sending a receipt immediately upon exit).

1. Orders API (Transactional)

The Orders API provides granular access to individual shopping receipts. This is the standard "pull" method for retrieving financial data, synchronizing with ERPs, or generating daily reports.

Base URL: https://api.aifi.com/api/admin/v2
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Rate Limiting

To ensure system stability, our API enforces a rate limit on incoming requests.

• Limit: 20 requests per second (RPS).
• Behavior: If you exceed this limit, the API will respond with a 503 Service Unavailable error.
• Recommendation: We recommend implementing exponential backoff retry logic in your integration. If you receive a 503 error, pause your requests briefly before retrying.

---

1.1 Orders List

Use this endpoint to synchronize sales data to your ERP or BI tool. We recommend polling this endpoint periodically (e.g., every 15 minutes) using time-based filters.

Endpoint: GET /orders

Key Query Parameters

Parameter	Type	Description
minDraftCreatedAt	string (ISO8601)	Filter by start date of draft order creation.
maxDraftCreatedAt	string (ISO8601)	Filter by end date of draft order creation.
storeId	integer	Filter by specific store location.
status	string	Filter by order state (e.g., paid, contested).
includeProducts	Boolean	Include product lines and details in the response. Default: false.
customerRole	string	Filter by customer role to get receipts only for specific registered customer types.
pageSize	integer	Items per page (Max: 200).
orderBy	string	Sorting attribute: "id", "storeId", "totalPrice", "draftCreatedAt".
direction	string	Direction of sorting (asc / desc).

Example Request

Get all paid customer orders created after 2025-11-01.

curl -X GET "https://api.aifi.com/api/admin/v2/orders?minDraftCreatedAt=2025-11-01T00:00:00Z&status=paid&customerRole=customer" \
  -H "Authorization: Bearer <TOKEN>"

Best Practices for Syncing

To sync data to your data warehouse without missing records:

1. Filter by minDraftCreatedAt using the timestamp of the last order you successfully processed.
2. Set pageSize to 100 or 200.
3. Loop through page incrementing by 1 until the returned data array is empty.

---

1.2 Order Details

Retrieves the full details of a single order, including line items, tax rates, and session metadata.

Endpoint: GET /orders/{orderId}

Key Response Fields

Order

• version: Default is 1. A newer version of the order will be created when an order gets contested.
• isLatest: Indicates whether this is the latest version of the order.

Financial Values

• totalPrice: The final amount charged to the customer.
• totalTax: The tax component of the total price.
• subtotalPrice: Price before tax.

Line Items (lineItems) The array containing purchased products.

• productSnapshot: Contains the immutable details of the product at the time of sale (Name, Barcode, Price).
• quantity: Number of units purchased.
• status: Indicates if the item was ORIGINAL, ADDED, or REMOVED (relevant for reviewed/contested orders).
• isExternallyAdded: Indicates whether the item was added via Cart Mutator logic.

Session (session) Links the transaction to the physical store visit.

• customerFirstEnteredAt: Timestamp when the customer entered.
• customerLastExitedAt: Timestamp when the customer left.
• sessionId: The unique trace ID for the customer shopping session.
• visitors: Actual group size associated with the shopping session.

---

2. Push Checkout Webhook (Real-Time)

For use cases requiring immediate action—such as sending a digital receipt the moment a customer leaves the store, or updating real-time inventory dashboards—use the Push Checkout Webhook.

AiFi pushes a JSON payload to your configured URL immediately when a customer exits and the system generates a draft or completed order.

Configuration

• Trigger: Fires when a customer checks out (Status: draft, completed) or when a contested order is resolved (reviewed).
• Endpoint: You must provide an exact URL (e.g., https://api.retailer.com/aifi-webhook).

The Payload

The webhook delivers the full context of the shopping session. Below are the critical fields you should parse:

• Session & Store: sessionId, storeId, customerFirstEnteredAt, customerLastExitedAt.
• Financials: totalPrice, totalTax, subtotalPrice.
• Cart Items: The cart array contains the items purchased.
  • Note: Use the productSnapshot object inside the cart item for the most accurate product data (Name, Price, Barcode) at the time of purchase.
• Payment: The payment object details the status (success, failure, processing) and the paymentProvider.

Handling Payments via Webhook

If you handle payments externally (not using AiFi's native payment integration), your server can respond to this webhook with payment confirmation details. AiFi will update the order status based on your response.

Example Webhook Response (Retailer to AiFi):

{
  "paymentStatus": "success",
  "paymentTransactionIds": ["tx_123456789"],
  "externalId": "my_erp_order_99"
}

---

Summary: Which method should I use?

Feature	Orders API	Push Webhook
Integration Type	REST Pull	REST Push
Latency	Near Real-time (Polling)	Real-time (Event Driven)
Best Use Case	Daily Reporting, Reconciliation	Instant Receipts, Live Inventory
Complexity	Low	Medium (Requires listening server)