Skip to main content
Send Bilt one event each time a linked member’s order changes.

​
Before you begin

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

​
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.
3

Post it

Send one event to Report an order event:
To send up to 100 events in one request, wrap them as {"events": [...]} and post to Report a batch. 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.
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.
  • order.status is not allowed for the order.type. Bilt rejects it with STATUS_MISMATCH.
  • The customer has not linked yet. Bilt holds the event with CONSUMER_NOT_LINKED.
  • An event arrives before its PURCHASE. Bilt holds it with ORIGINAL_ORDER_NOT_FOUND.
  • A signing header is missing or too long. Bilt answers 400.

​
Next steps