Skip to main content
POST
Create a transaction

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

A completed checkout to record against a store, with its products, payments, and totals.

id
string<uuid>
required

Unique transaction ID generated by your system (UUIDv7). It serves as the idempotency key for the request: sending the same transaction twice with the same ID returns the transaction already recorded rather than creating a duplicate. Generate it before your first attempt and reuse it on every retry. Sending different values under an ID already used is rejected.

completed_at
string<date-time>
required

When the transaction was completed in your system.

line_items
object[]
required

Products on the transaction. May be empty for a gift-card-only transaction.

Maximum array length: 2500
payments
object[]
required

Payments applied to the transaction.

Required array length: 1 - 50 elements
store_id
string
required

ID of the store where the transaction took place.

Pattern: ^[0-9]+$
tax_total
string<positive-monetary>
required

Total sales tax charged on the transaction. Must equal the sum of the line-item tax totals.

Pattern: ^[0-9]+(\.[0-9]+)?$
Example:

"199.99"

total
string<positive-monetary>
required

Final transaction total including tax. Must equal the sum of the line totals plus the gift card sale amounts, and the payments must add up to this amount.

Pattern: ^[0-9]+(\.[0-9]+)?$
Example:

"199.99"

employee_id
string | null

ID of the employee to record this transaction under. Defaults to the employee Vori maintains for transactions submitted through this API.

Pattern: ^[0-9]+$
external_id
string | null

Your own identifier for this transaction, such as an order number from your e-commerce platform. Stored exactly as provided and never interpreted, and you can filter transactions by it. It must be unique among the transactions and refunds in your banner.

Maximum string length: 255
gift_card_sales
object[]

Gift cards sold on the transaction.

Maximum array length: 100
lane_id
string | null

ID of the lane to record this transaction under. Defaults to the lane Vori maintains for transactions submitted through this API.

Pattern: ^[0-9]+$
metadata
object | null

Your own key/value pairs, stored with the transaction and returned unchanged. Vori never interprets them. Up to 50 keys; key names up to 40 characters of letters, numbers, underscores, and hyphens; values up to 500 characters. Keys beginning with "vori" are reserved. Do not put personal or sensitive information here — these values flow into reporting and data exports.

Example:
shopper_id
string<uuid>

ID of the loyalty shopper who placed the transaction, if known. Links the transaction to their loyalty account.

Response

A completed checkout at a store, covering the lane, cashier, and shopper, the products sold, the savings applied, the payments collected, and any refunds against it.

id
string
required

Unique identifier for the record.

cashback_amount
string<monetary>
required

Cash back requested by the shopper.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

completed_at
string<date-time>
required

Date and time when the transaction was finalized.

coupon_total
string<monetary>
required

Total savings from coupons.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

discount_total
string<monetary>
required

Total savings from manual or employee discounts.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

employee_id
string
required

ID of the employee who processed the transaction.

Pattern: ^[0-9]+$
external_id
string | null
required

Your own identifier for the transaction, as supplied when it was recorded.

gift_card_sales
object[]
required

Gift cards purchased in the transaction.

gift_card_sales_total
string<monetary>
required

Total face value of gift cards purchased in the transaction.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

issued_coupons
object[]
required

Coupons issued to the shopper by the transaction.

item_modifier_total
string<monetary>
required

Total value of item modifiers.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

lane_id
string
required

ID of the checkout lane that processed the transaction.

Pattern: ^[0-9]+$
line_items
object[]
required

Product line items included in the transaction.

loyalty_rewards_total
string<monetary>
required

Total savings from loyalty reward redemptions.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

metadata
object | null
required

Your own key/value pairs, exactly as supplied when the transaction was recorded.

Example:
payments
object[]
required

Payments collected for the transaction.

points_earned
string
required

Loyalty points the shopper earned on this transaction, computed from the products sold and the store banner loyalty program. Zero when the transaction names no shopper or the banner has no active loyalty program. Negative on a refund, which reverses the points the original sale earned.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

promo_savings
string<monetary>
required

Total savings from promotions.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

promo_total
string<monetary>
required

Sum of line-item totals after promotions are applied.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

receipt_type
enum<string> | null
required

How the shopper took their receipt, or null when they took none.

Available options:
email,
print,
sms
refund_total
string<monetary>
required

Total value refunded against this transaction.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

refunds
object[]
required

Refunds of the transaction. Retrieve one with GET /v1/transactions/{id} for the products returned and how the money went back.

retail_total
string<monetary>
required

Sum of line-item retail totals after promotions and before discounts and tax.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

shopper_facing_id
string
required

Human-readable transaction identifier shown to the shopper.

shopper_id
string<uuid> | null
required

ID of the loyalty shopper associated with the transaction, or null for an anonymous transaction.

source
enum<string>
required

Where the transaction came from.

Available options:
api,
external_pos,
migration,
pos
started_at
string<date-time>
required

Date and time when the cashier started the transaction.

status
enum<string>
required

Current lifecycle status of the transaction.

Available options:
completed,
expired,
suspended,
voided
store_id
string
required

ID of the store where the transaction was placed.

Pattern: ^[0-9]+$
subtotal
string<monetary>
required

Sum of line-item subtotals before promotions, discounts, and tax.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

tax_total
string<monetary>
required

Total tax charged on the transaction.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

taxable_amount
string<monetary>
required

Portion of the transaction subject to tax.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

tip_amount
string<monetary>
required

Tip added by the shopper.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

total
string<monetary>
required

Final transaction amount including tax. Sales are positive and refunds are negative.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

total_collected
string<monetary>
required

Total collected from the shopper, including the transaction total, tip, and cash back.

Pattern: ^-?[0-9]+(\.[0-9]+)?$
Example:

"199.99"

type
enum<string>
required

Financial transaction type represented by the transaction.

Available options:
refund,
sale,
void