Skip to main content

​
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.
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. 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. 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:
Across the order’s events:

​
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

Build, sign, and post an event.

Sign your requests

Set up your key and sign each request.

Handle rejections and resends

Fix a rejected event and retry safely.

Report an order event

Every field, with eight worked examples.