> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bilt.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Order reporting overview

> Tell Bilt what a linked member bought and how they paid, so Bilt can reward them

## What it is

When a linked Bilt member buys from you, you tell Bilt what they bought and how they paid. Bilt rewards the member from the payments. Points are awarded once the order is fully captured, and reversed in proportion when money is refunded.

You send one stream of signed events. All traffic goes from you to Bilt, and Bilt never calls you.

> [!NOTE]
>
> This contract is a proposal under design review and is not live yet.

## How it works

Every change to an order is a new `POST` of a new event. There is no `PATCH` or `PUT`, and Bilt never edits an event you sent. Bilt answers `202` right away and checks the event a few seconds later.

```mermaid theme={null}
sequenceDiagram
    participant You as Your server
    participant Bilt as Bilt order reporting
    You->>Bilt: PURCHASE, card AUTHORIZED
    Bilt-->>You: 202 Accepted
    Note over Bilt: Checks the event: ACCEPTED, HELD, or REJECTED
    You->>Bilt: FULFILLMENT_UPDATED, card CAPTURED
    Bilt-->>You: 202 Accepted
    Note over Bilt: Captures equal the order total, so points are awarded
```

A `202` is a receipt, not a verdict. Every rule about the content of an event is applied after it.

## Key concepts

### Event types

Each event has an `order` part and, when money moved, a `payments` part.

| `order.type` | Send it when |
| - | - |
| `PURCHASE` | The order is placed. Send the full order once, first. |
| `FULFILLMENT_UPDATED` | Lines ship, are picked up, or are canceled. Repeat as needed. |
| `PAYMENT_UPDATED` | Only money moved: a later capture, a void, or a refund without a return. |
| `ORDER_CANCELED` | Nothing more will ship. |
| `RETURN` | Goods come back. |

Events after the purchase carry only what changed. They point at the order by `orderId`, at its lines by `lineItemId`, and at a tender by `paymentId`. Never resend line details, the location, or the totals.

Do not send carts, drafts, orders awaiting payment, or picking and packing steps that leave a line's status unchanged.

### Your IDs

Bilt does not give you IDs. `orderId` names an order, `lineItemId` names one of its lines, and `paymentId` names one tender. Every event has an `idempotencyKey` you generate once. `orderId`, `partnerMemberId`, `currency`, and each `paymentId` never change across an order's events.

### Payment lifecycle

Each tender has its own sequence, sent inside `payments` of whichever order event you are sending.

* A card goes `AUTHORIZED`, then `CAPTURED`, then `REFUNDED`. You can capture several times as you ship, up to the authorized amount. You can refund several times, each with its own `refundId`. A hold released without a capture is `VOIDED`, which ends the sequence.
* Every other tender goes `CAPTURED`, then `REFUNDED`. It is captured once.

### Amounts

Within the purchase:

```text theme={null}
lineItems[].grossSales   = basePrice × quantity
lineItems[].total        = grossSales − discount + tax
netAmounts.subtotal      = Σ lineItems[].grossSales
netAmounts.discount      = Σ lineItems[].discount + Σ discounts[].applied
netAmounts.tax           = Σ lineItems[].tax      + Σ taxes[].applied
netAmounts.serviceCharge = Σ serviceCharges[].applied
netAmounts.total         = subtotal − discount + tax + serviceCharge + tip
```

Across the order's events:

```text theme={null}
Σ CAPTURED.amount for a card paymentId   ≤  its AUTHORIZED.amount   (CAPTURE_EXCEEDS_AUTHORIZATION)
Σ CAPTURED.amount over all tenders       ≤  netAmounts.total        (CAPTURE_EXCEEDS_ORDER)
                                         == netAmounts.total        → points awarded
Σ REFUNDED.amount for a paymentId        ≤  its captured amount     (REFUND_EXCEEDS_CAPTURE)
```

### When points move

* Points are earned on `CASH`, and on `CARD` with `cardType` `CREDIT` or `DEBIT`.
* The award is the sum of those tenders' captures. Bilt makes it once captures across all tenders equal `netAmounts.total`.
* A card capture needs its `AUTHORIZED` first, with the same `paymentId` and the same card.
* Prepaid cards, gift cards, store credit, and other tenders are recorded so the totals reconcile. They earn nothing.
* A refund reverses points in proportion to its amount.

### Versioning

A breaking change ships as `/v2/partners/order-reports` next to `/v1`. Within `/v1`, Bilt may add enum values, so accept values you do not know.

## Next steps

> **[Send order events](/partners/order-reporting/send-order-events.md)**
>
> Build, sign, and post an event.

> **[Sign your requests](/partners/order-reporting/sign-your-requests.md)**
>
> Set up your key and sign each request.

> **[Handle rejections and resends](/partners/order-reporting/handle-rejections-and-resends.md)**
>
> Fix a rejected event and retry safely.

> **[Report an order event](/api-reference/order-reports/report-an-order-event.md)**
>
> Every field, with eight worked examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.