Process a transaction

POST /v1/transactions/process commits a transaction for the selected card. Three things can happen, individually or together:

Campaign collection

Applicable campaigns on the card run; balances update and reward coupons are granted when thresholds are reached.

Coupon redemption

Any reward (coupon instance id) on a line item or at the order level is redeemed.

Point spend

pointsToSpend is deducted from the card’s point balance.

POST $BASE_URL/v1/transactions/process

Discount amounts (discountAmount / discountedAmount, per-line and order-level) are calculated by your system and stored as-is. Product, user, and branch IDs are opaque IDs. user and branch default to the authenticated user and its branch.

Request headers

string

required

Your active Bearer token: Bearer <accessToken>.

string

required

Always application/json.

Request body

string

required

Customer id (from GET /v1/customers/find).

string

required

Selected card (customerpass id). The campaigns run come from this card.

string

Cashier user opaque id.

string

Branch opaque id.

array

Basket lines.

Show item fields

string

required

Product opaque id.

number

Line quantity.

number

Unit price.

string

Product name.

number

Discount applied to the line.

number

Final line amount after discounts.

string

Coupon instance id applied to this line. It will be redeemed.

number

Total amount before discounts.

number

Total discount applied to the order.

number

Final amount after discounts.

string[]

Coupon instance ids applied to the order total. They will be redeemed.

number

Loyalty points the customer spends on the order total. They will be deducted.

Response fields (200 OK)

string

Human-readable summary of what happened.

array

Campaign actions executed in this transaction.

Show executed action fields

string

Name of the campaign action.

string

Transaction category the action belongs to.

number

Amount collected by this action in the current transaction.

number

Collectable value before the action ran.

object

Updated collectable state: value (current spendable balance) and total (lifetime total).

string[]

Coupon instance ids granted when a threshold was reached.

curl --request POST \
  --url "$BASE_URL/v1/transactions/process" \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer": "3d8ec956-de2a-4d43-9c1e-74475b153362",
    "card": "41dd8263-288e-4b55-bf2e-6a82995a0441",
    "items": [
      { "id": "8f26e6c7-...", "quantity": 4, "price": 140, "name": "Americano" }
    ],
    "amount": 560,
    "pointsToSpend": 120
  }'

{
  "message": "You collected 4 stamps, earned a Free Coffee coupon",
  "executedActions": [
    {
      "actionName": "collect-stamps",
      "transactionCategory": "collect-stamps",
      "netCollected": 4,
      "previousCollectableValue": 3,
      "result": { "value": 2, "total": 12 },
      "rewards": ["2f19b6ba-e7f8-4dd5-b328-cbfabc08e412"]
    }
  ]
}

{
  "statuscode": 400,
  "errorcode": 400,
  "message": "_insufficient_collectable_balance",
  "description": "",
  "timestamp": 1754040000000,
  "path": "/v1/transactions/process",
  "method": "POST"
}

Preview the discount a point spend would produce with POST /v1/transactions/validate before committing.

Getting started

Endpoints

Reference

Process a transaction

Request headers

Request body

Response fields (200 OK)

​Request headers

​Request body

​Response fields (200 OK)

Request headers

Request body

Response fields (200 OK)