Receipts

Submit an uploaded receipt reference, view past submissions, and read their processing-status counts. Upload the image first, then submit its reference.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

Add user receipt

Method	URL path	Required access
POST	/api/v1/user/receipt	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.userReceipt	string	yes	Whitespace trimmed
body.payload.source	string	yes	Whitespace trimmed; Allowed values ("self", "meadow", "retail")
body.payload.listed_hub_id	number	optional	—
body.payload.brl_id	number	optional	—

Example:

curl -X POST "$BASE_URL/api/v1/user/receipt" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"userReceipt":"https://files.example/receipt.jpg","source":"self"}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: message, receiptId and any additional receipt-processing data.

Source: app/v1/controller/receipt_controller.js:12 → addUserReceipt; routes: routes/v1/receipt_route.js:41; service: _addUserReceipt (app/v1/service/receipt_service.js:116).

Get receipts for customer

Method	URL path	Required access
GET	/api/v1/user/user-receipts	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query.limit	number	optional	—
query.offset	number	optional	—
query.status	string	optional	Whitespace trimmed; Allowed values ("PENDING", "APPROVED", "REJECTED")

Example:

curl -X GET "$BASE_URL/api/v1/user/user-receipts?limit=10&offset=0" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: count, data.

Source: app/v1/controller/receipt_controller.js:51 → getReceiptsForCustomer; routes: routes/v1/receipt_route.js:51; service: _getReceiptsForCustomer (app/v1/service/receipt_service.js:151).

Get all receipt status count

Method	URL path	Required access
GET	/api/v1/user/receipt-count	Origin + Brand key + Customer

Request fields: no body, query, or path fields are read by this controller. Context comes from the headers/middleware above.

Example:

curl -X GET "$BASE_URL/api/v1/user/receipt-count" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/receipt_controller.js:89 → getAllReceiptStatusCount; routes: routes/v1/receipt_route.js:61; service: _getAllReceiptStatusCount (app/v1/service/receipt_service.js:183).

Lifecycle

The receipt status enum has pending, approved and rejected, but Add user receipt only ever stores approved. It validates the receipt during the call, and a receipt that fails is not stored at all:

The checks, in order: brl_id is sent; userReceipt is a /api/v1/files/ link, as returned by the POST upload; this customer has a pending hold on that brl_id; the code's product is found; OCR finds that product's line and a purchase date on the receipt; and an active scan campaign covering that date has a claim limit with claims left. The approved receiptId then goes to Release points after verify. The journey is the hold path of the scan-to-claim web flow.

Related pages

• Batch Commerce API overview
• Orders and receipts
• Implementation notes