> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Payload

> Construct a single JSON payload for BrandWallet transactions: campaigns, coupon redemptions, and point spend in one call.

The BrandWallet API uses a single standard payload structure for all transactions. Whether a customer has a stamp card, a point card, or a multi-tier program, the same body shape on [POST /v1/transactions/process](/api/process-transaction) handles them all.

## What the payload handles

A single transaction payload can do any combination of the following in one call:

* **Campaign collection** — Applicable campaigns on the selected `card` run; balances update and reward coupons are granted when thresholds are reached.
* **Coupon redemption** — Coupon instance ids passed as `reward` on a line item or at the order level are redeemed.
* **Point spend** — `pointsToSpend` is deducted from the card's point balance.

## Key concepts

A transaction payload represents a single basket. You construct and submit one payload per customer interaction.

Product, user, and branch IDs in the payload are **opaque IDs**, your external system identifiers. BrandWallet resolves them to internal references. `user` and `branch` default to the authenticated API user and its branch when omitted.

Discount amounts (`discountAmount` / `discountedAmount`, per-line and order-level) are calculated by your system and stored as-is. To preview the discount a point spend would produce before committing, call [POST /v1/transactions/validate](/api/validate-transaction) with the same body.

## Required fields

Every transaction payload must include:

* `customer` — Customer id from [GET /v1/customers/find](/api/find-customer).
* `card` — Selected card (customerpass id). The campaigns run come from this card.

See the full field reference on [POST /v1/transactions/process](/api/process-transaction).

## Payload flow

<Steps>
  <Step title="Identify the customer">
    Call [GET /v1/customers/find](/api/find-customer) with the customer's phone, email, or card barcode. Save the returned `id` (customer id) and the `cards[].id` (customerpass id).
  </Step>

  <Step title="(Optional) Preview the discount">
    Call [POST /v1/transactions/validate](/api/validate-transaction) with the basket and `pointsToSpend` to preview the discount before committing.
  </Step>

  <Step title="Commit the basket">
    Call [POST /v1/transactions/process](/api/process-transaction) with the same body to commit. BrandWallet returns the updated loyalty state in `executedActions`, including new balances and any coupons granted.
  </Step>
</Steps>

<RequestExample>
  ```json Example payload theme={null}
  {
    "customer": "3d8ec956-de2a-4d43-9c1e-74475b153362",
    "card": "41dd8263-288e-4b55-bf2e-6a82995a0441",
    "items": [
      {
        "id": "8f26e6c7-...",
        "quantity": 4,
        "price": 140,
        "name": "Americano",
        "reward": "906550fd-dcf5-4aed-a80e-03e8939fc2b4"
      }
    ],
    "amount": 560,
    "pointsToSpend": 120
  }
  ```
</RequestExample>

<Tip>
  Use BrandWallet as the single source of truth for all loyalty data. Do not cache points, stamps, or coupon balances locally. Fetch fresh state before each transaction.
</Tip>