Skip to main content
POST
Refund a transaction

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string<uuid>
required

Body

application/json

A refund your own system processed against a transaction Vori already recorded, with the products coming back and the money going out.

​
id
string<uuid>
required

Unique refund ID generated by your system (UUIDv7). It serves as the idempotency key for the request: sending the same refund twice with the same ID returns the refund 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 refund was completed in your system.

​
line_items
object[]
required

Products coming back on the refund.

Required array length: 1 - 2500 elements
​
payments
object[]
required

Payments the refund returns money to.

Required array length: 1 - 50 elements
​
tax_total
string<negative-monetary>
required

Total sales tax refunded, as a negative amount. Must equal the sum of the line-item tax totals.

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

"-199.99"

​
total
string<negative-monetary>
required

Final refund total including tax, as a negative amount. Must equal the sum of the line totals, and the payments must add up to this amount.

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

"-199.99"

​
employee_id
string | null

ID of the employee to record this refund 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 refund, such as a return number from your e-commerce platform. Surrounding whitespace is removed; the value is otherwise stored as provided and never interpreted, and you can filter transactions by it. Vori does not require it to be unique.

Maximum string length: 255
​
lane_id
string | null

ID of the lane to record this refund 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 refund 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:
​
return_to_inventory
boolean

Whether the products coming back return to your on-hand counts. Applies to every line that does not answer for itself; a line providing its own return_to_inventory overrides it. Defaults to false. Acted on when the refund is first recorded, so resending the same refund ID does not revisit it.

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,
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