> ## 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.

# Send order events

> Build, sign, and post an order event for a linked member, alone or in a batch

Send Bilt one event each time a linked member's order changes.

## Before you begin

* Link the customer first. Use the same `partnerMemberId` you used when they linked. See [Account linking](/partners/account-linking/overview.md).
* Register a signing key and get your key ID. See [Sign your requests](/partners/order-reporting/sign-your-requests.md).
* Use the base URL for your environment. See [Environments and credentials](/partners/environments-and-credentials.md).

## How it works

You build the event as JSON, sign the exact bytes, and post them. Bilt answers `202` and checks the event a few seconds later. Field rules and eight worked examples are on [Report an order event](/api-reference/order-reports/report-an-order-event.md).

## Steps

**1. Build the event**

Set `orderId`, `partnerMemberId`, `currency`, `createdAt`, and a new `idempotencyKey`. Pick the `order.type` for what happened and set `order.status` to the order status after it.

Add `payments` only when money moved: an authorization, a capture, a void, or a refund. Add one entry per tender that changed.

Every listed field is required unless the reference says optional. Send empty arrays as `[]`. Send money as strings with two decimals, such as `"12.50"`. An unknown key rejects the whole event.

**2. Sign it**

Serialize the JSON once and sign those bytes. Add the `webhook-id`, `webhook-timestamp`, `webhook-signature`, and `X-Bilt-Key-Id` headers. See [Sign your requests](/partners/order-reporting/sign-your-requests.md).

**3. Post it**

Send one event to [Report an order event](/api-reference/order-reports/report-an-order-event.md):

```bash theme={null}
curl https://webhooks.staging.bilt.dev/v1/partners/order-reports \
  -H "Content-Type: application/json" \
  -H "webhook-id: $WEBHOOK_ID" \
  -H "webhook-timestamp: $WEBHOOK_TIMESTAMP" \
  -H "webhook-signature: $WEBHOOK_SIGNATURE" \
  -H "X-Bilt-Key-Id: $BILT_KEY_ID" \
  --data-binary @event.json
```

To send up to 100 events in one request, wrap them as `{"events": [...]}` and post to [Report a batch](/api-reference/order-reports/report-a-batch.md). The batch has one `webhook-id`, one signature, and a 1 MiB limit.

**4. Handle the response**

A `202` means Bilt stored the request. It does not mean Bilt accepted the event. On a `400` or `413`, fix the request, because Bilt stored nothing. On a timeout or a `500`, retry with the same `webhook-id` and body, signed again.

**5. Send the next change**

Send each later event when it happens, with the same `orderId` and a new `idempotencyKey`. If Bilt rejects an event, see [Handle rejections and resends](/partners/order-reporting/handle-rejections-and-resends.md).

> [!WARNING]
>
> **Never send a full card number.** `bin` and `last4` in `cardDetails` are the only card digits Bilt accepts.

Send only your own identifiers. Keep customer email addresses and phone numbers out of every event. Put card data only in `cardDetails`, never in a line item or a `reason`. Bilt stores every event as you sent it.

## What can go wrong

* The amounts do not add up. Bilt rejects the event with [`SUM_MISMATCH`](/partners/errors-and-retries#order-report-reasons).
* `order.status` is not allowed for the `order.type`. Bilt rejects it with [`STATUS_MISMATCH`](/partners/errors-and-retries#order-report-reasons).
* The customer has not linked yet. Bilt holds the event with [`CONSUMER_NOT_LINKED`](/partners/errors-and-retries#order-report-reasons).
* An event arrives before its `PURCHASE`. Bilt holds it with [`ORIGINAL_ORDER_NOT_FOUND`](/partners/errors-and-retries#order-report-reasons).
* A signing header is missing or too long. Bilt answers [`400`](/api-reference/order-reports/report-an-order-event).

## Next steps

* [Handle rejections and resends](/partners/order-reporting/handle-rejections-and-resends.md)
* [Test and go live](/partners/test-and-go-live.md)


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