Test and go live - Bilt Rewards Support

Run the staging test plans for each product you build, then go live with Bilt.

Onboarding

Finish the exchange on Environments and credentials first. Your integration stays disabled until then.

Run this plan against staging, in order. Bilt runs an equivalent suite, so raise mismatches early.

Test	Scenario	Expected
1	Link with a valid, fresh token	`200`, `LINKED`
2	Get the same `partnerUserId`	`200`, `LINKED`, with `linkedAt`
3	Resend the identical link request	`200`, the same link
4	Reuse the token with a different `partnerUserId`	`409 ID_TOKEN_REPLAYED`
5	Link a second account of yours to the same member, with a fresh token	`409 ALREADY_LINKED`
6	Link the same account to a second member, with that member’s fresh token	`409 IDENTITY_ALREADY_LINKED`
7	Link with an expired token	`401 ID_TOKEN_EXPIRED`
8	Link with a token minted for another client	`401 ID_TOKEN_AUDIENCE_MISMATCH`
9	Call any endpoint with no credential, then a wrong one	`401` both times
10	Call any endpoint with an invalid token and a valid `x-api-key`	`401`, with no fallback to the key
11	Send a blank or 257-character `partnerUserId`	`400`
12	Send `x-request-id` on a failing call	`requestId` is the trace ID, not your value
13	Return to your callback with a mismatched `state`	Your callback rejects it before reading `code`
14	Exchange a code twice	`invalid_grant` on the second try
15	End the link	`204`
16	End it again	`204`
17	Get the link after ending it	`200`, `LINK_REVOKED`
18	End a link with a well-formed `linkId` that is not yours	`404 LINK_NOT_FOUND`
19	End a link with no `linkId`	`400`
20	Link again with a fresh token	`200`, `LINKED`, a new link

Validate the bearer token on every endpoint, and keep it out of logs.
Run every link account check, including contact.isVerified.
Make retries safe, and refuse a retry after unlink.
Match accounts exactly, and never create one from link account.
Answer an existing account on create and link with 409 account_exists, and write nothing.
Rate-limit contact lookup, and answer a miss with exists: false.
Make unlink account idempotent.
Agree normalization rules, base URLs, credentials, and contacts with Bilt.

Send each of these to staging, signed, and ask Bilt for the result of each webhook-id. The examples on the reference page cover the happy paths.

Test	Scenario	Expected
1	`PURCHASE` with a card `AUTHORIZED`, for a linked customer	`202`, then `ACCEPTED`
2	`FULFILLMENT_UPDATED` with a card `CAPTURED` for the full total	`ACCEPTED`, points awarded
3	`RETURN` with a card `REFUNDED`	`ACCEPTED`, points reversed in proportion
4	`ORDER_CANCELED` with a card `VOIDED`	`ACCEPTED`
5	Split tender: gift card `CAPTURED` and card `AUTHORIZED`, then `PAYMENT_UPDATED` with the card `CAPTURED`	`ACCEPTED`, points on the card share only
6	Resend test 1 with the same `webhook-id` and body	Ignored as a duplicate
7	Resend test 1 with the same `webhook-id` and a different body	`REJECTED`, `IDEMPOTENCY_KEY_REUSED`
8	A `PURCHASE` whose amounts do not add up	`REJECTED`, `SUM_MISMATCH`
9	A `FULFILLMENT_UPDATED` before its `PURCHASE`	`HELD`, `ORIGINAL_ORDER_NOT_FOUND`
10	A `PURCHASE` for a customer who has not linked	`HELD`, `CONSUMER_NOT_LINKED`
11	A request with a timestamp 10 minutes old	`202`, then `stale_timestamp`
12	A request signed over different bytes than you sent	`202`, then `bad_signature`
13	A request with no `webhook-signature`	`400`
14	A batch over 1 MiB	`413`

Finish the checklists. Complete onboarding and pass the staging tests.
Get production credentials. Bilt issues separate credentials for production. Never reuse staging credentials.
Confirm together. You and Bilt confirm the launch. Bilt enables your integration with a configuration change, effective in about 30 seconds.

Contact your Bilt technical contact or your shared Slack channel. Include:

The requestId from an account links error, or the webhook-id of an order report
The time in UTC
The environment
The endpoint and the HTTP status
The partnerUserId or orderId

Never include tokens, keys, secrets, or personal data.