Purchases

Create a purchase

POST /b2b/purchases

Every request requires a client-generated Idempotency-Key. Reusing it with the same payload returns the original purchase; reusing it with a different payload returns 409 conflict.

curl -X POST "$REWARDOS_API_BASE/b2b/purchases" \
  -H "x-api-key: $REWARDOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "6af64816-a9ff-46d3-a211-5919422a19ca",
    "quantity": 1,
    "faceAmount": 950
  }'

faceAmount is in major currency units. Select it from the current catalog response. For a portal offer, it must exactly equal fixedUnitPriceMinor / 100 and quantity must be 1.

The response contains purchase.orderId, lifecycle status, line snapshot, wallet-fund reference, vendor status, and fulfillment credentials or a portal coupon when available. Preserve the full response securely: credentials and coupon codes can be sensitive.

Read a purchase

GET /b2b/purchases/{orderId} returns the same purchase view.

curl "$REWARDOS_API_BASE/b2b/purchases/$ORDER_ID" \
  -H "x-api-key: $REWARDOS_API_KEY"

Purchase statuses are pending_funds, reserved, routing, fulfilled, failed, or unknown. Treat unknown as requiring reconciliation rather than assuming failure or issuing a second purchase.

Recovery rules

• Retry an uncertain create with the same idempotency key and identical body.
• Refresh the catalog for validation_error responses.
• Do not retry a 409 with a different payload under the same key.
• Retrieve the existing order before taking any manual fulfillment action.