> ## Documentation Index > Fetch the complete documentation index at: https://help.vori.com/llms.txt > Use this file to discover all available pages before exploring further. # Refund a transaction > Records a refund your own system processed against a transaction Vori already recorded, and returns it as a transaction of its own. Only a transaction created through this API can be refunded. Quantities and amounts are negative, as they are when you read a refund back, and a line cannot return more than it has left after earlier refunds. Send a UUIDv7 as `id`; sending the same refund again under that ID returns the refund already recorded rather than creating a second, and sending different values under it is rejected. ## OpenAPI ````yaml /api/openapi.json post /v1/transactions/{id}/refunds openapi: 3.0.0 info: title: Vori API description: '' version: 1.0.0 contact: {} servers: - url: https://api.vori.com description: production security: [] tags: [] paths: /v1/transactions/{id}/refunds: post: tags: - Transactions summary: Refund a transaction description: >- Records a refund your own system processed against a transaction Vori already recorded, and returns it as a transaction of its own. Only a transaction created through this API can be refunded. Quantities and amounts are negative, as they are when you read a refund back, and a line cannot return more than it has left after earlier refunds. Send a UUIDv7 as `id`; sending the same refund again under that ID returns the refund already recorded rather than creating a second, and sending different values under it is rejected. operationId: createTransactionRefund parameters: - name: id required: true in: path schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRefundRequest' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/Transaction' '400': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/TransactionLaneNotFoundError' - $ref: '#/components/schemas/TransactionLaneStoreMismatchError' - $ref: '#/components/schemas/TransactionLaneNotVirtualError' - $ref: '#/components/schemas/TransactionEmployeeNotFoundError' - $ref: '#/components/schemas/TransactionEmployeeNotVirtualError' - $ref: '#/components/schemas/TransactionTotalsMismatchError' - $ref: '#/components/schemas/TransactionLineItemInvalidError' - $ref: '#/components/schemas/RefundTransactionNotRefundableError' - $ref: '#/components/schemas/RefundLineItemsNotFoundError' - $ref: '#/components/schemas/RefundPaymentsNotFoundError' - $ref: '#/components/schemas/RefundExceedsOriginalError' '403': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/InsufficientPermissionsError' - $ref: '#/components/schemas/NoBannerAssociationError' '409': description: '' content: application/json: schema: anyOf: - $ref: '#/components/schemas/TransactionAlreadyExistsError' - $ref: '#/components/schemas/TransactionRequestMismatchError' security: - bearer: [] components: schemas: CreateRefundRequest: type: object properties: id: type: string description: >- 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. format: uuid completed_at: type: string description: When the refund was completed in your system. format: date-time employee_id: type: string nullable: true description: >- 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: type: string nullable: true maxLength: 255 description: >- 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. lane_id: type: string nullable: true description: >- ID of the lane to record this refund under. Defaults to the lane Vori maintains for transactions submitted through this API. pattern: ^[0-9]+$ line_items: minItems: 1 maxItems: 2500 description: Products coming back on the refund. type: array items: $ref: '#/components/schemas/CreateRefundLineItem' metadata: type: object maxProperties: 50 additionalProperties: type: string maxLength: 500 example: order_source: shopify fulfillment_id: '88213' nullable: true description: >- 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. payments: minItems: 1 maxItems: 50 description: Payments the refund returns money to. type: array items: $ref: '#/components/schemas/CreateRefundPayment' tax_total: type: string description: >- Total sales tax refunded, as a negative amount. Must equal the sum of the line-item tax totals. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' total: type: string description: >- 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. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' description: >- A refund your own system processed against a transaction Vori already recorded, with the products coming back and the money going out. required: - id - completed_at - line_items - payments - tax_total - total Transaction: type: object properties: id: type: string description: Unique identifier for the record. cashback_amount: type: string description: Cash back requested by the shopper. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ completed_at: type: string description: Date and time when the transaction was finalized. format: date-time coupon_total: type: string description: Total savings from coupons. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ discount_total: type: string description: Total savings from manual or employee discounts. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ employee_id: type: string description: ID of the employee who processed the transaction. pattern: ^[0-9]+$ external_id: type: string nullable: true description: >- Your own identifier for the transaction, as supplied when it was recorded. gift_card_sales: description: Gift cards purchased in the transaction. type: array items: $ref: '#/components/schemas/TransactionGiftCardSale' gift_card_sales_total: type: string description: Total face value of gift cards purchased in the transaction. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ issued_coupons: description: Coupons issued to the shopper by the transaction. type: array items: $ref: '#/components/schemas/TransactionIssuedCoupon' item_modifier_total: type: string description: Total value of item modifiers. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ lane_id: type: string description: ID of the checkout lane that processed the transaction. pattern: ^[0-9]+$ line_items: description: Product line items included in the transaction. type: array items: $ref: '#/components/schemas/TransactionLineItem' loyalty_rewards_total: type: string description: Total savings from loyalty reward redemptions. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ metadata: type: object maxProperties: 50 additionalProperties: type: string maxLength: 500 example: order_source: shopify fulfillment_id: '88213' nullable: true description: >- Your own key/value pairs, exactly as supplied when the transaction was recorded. payments: description: Payments collected for the transaction. type: array items: $ref: '#/components/schemas/TransactionPayment' promo_savings: type: string description: Total savings from promotions. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ promo_total: type: string description: Sum of line-item totals after promotions are applied. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ receipt_type: nullable: true description: How the shopper took their receipt, or null when they took none. allOf: - $ref: '#/components/schemas/ReceiptType' refund_total: type: string description: Total value refunded against this transaction. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ refunds: description: >- Refunds of the transaction. Retrieve one with `GET /v1/transactions/{id}` for the products returned and how the money went back. type: array items: $ref: '#/components/schemas/CompactRefund' retail_total: type: string description: >- Sum of line-item retail totals after promotions and before discounts and tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ shopper_facing_id: type: string description: Human-readable transaction identifier shown to the shopper. shopper_id: type: string nullable: true description: >- ID of the loyalty shopper associated with the transaction, or null for an anonymous transaction. format: uuid source: description: Where the transaction came from. allOf: - $ref: '#/components/schemas/TransactionSource' started_at: type: string description: Date and time when the cashier started the transaction. format: date-time status: description: Current lifecycle status of the transaction. allOf: - $ref: '#/components/schemas/TransactionStatus' store_id: type: string description: ID of the store where the transaction was placed. pattern: ^[0-9]+$ subtotal: type: string description: Sum of line-item subtotals before promotions, discounts, and tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ tax_total: type: string description: Total tax charged on the transaction. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ taxable_amount: type: string description: Portion of the transaction subject to tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ tip_amount: type: string description: Tip added by the shopper. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ total: type: string description: >- Final transaction amount including tax. Sales are positive and refunds are negative. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ total_collected: type: string description: >- Total collected from the shopper, including the transaction total, tip, and cash back. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ type: description: Financial transaction type represented by the transaction. allOf: - $ref: '#/components/schemas/TransactionType' description: >- 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. required: - id - cashback_amount - completed_at - coupon_total - discount_total - employee_id - external_id - gift_card_sales - gift_card_sales_total - issued_coupons - item_modifier_total - lane_id - line_items - loyalty_rewards_total - metadata - payments - promo_savings - promo_total - receipt_type - refund_total - refunds - retail_total - shopper_facing_id - shopper_id - source - started_at - status - store_id - subtotal - tax_total - taxable_amount - tip_amount - total - total_collected - type TransactionLaneNotFoundError: type: object properties: error_code: type: string enum: - transaction_lane_not_found error_details: $ref: '#/components/schemas/TransactionLaneNotFoundErrorDetails' required: - error_code - error_details TransactionLaneStoreMismatchError: type: object properties: error_code: type: string enum: - transaction_lane_store_mismatch error_details: $ref: '#/components/schemas/TransactionLaneStoreMismatchErrorDetails' required: - error_code - error_details TransactionLaneNotVirtualError: type: object properties: error_code: type: string enum: - transaction_lane_not_virtual error_details: $ref: '#/components/schemas/TransactionLaneNotVirtualErrorDetails' required: - error_code - error_details TransactionEmployeeNotFoundError: type: object properties: error_code: type: string enum: - transaction_employee_not_found error_details: $ref: '#/components/schemas/TransactionEmployeeNotFoundErrorDetails' required: - error_code - error_details TransactionEmployeeNotVirtualError: type: object properties: error_code: type: string enum: - transaction_employee_not_virtual error_details: $ref: '#/components/schemas/TransactionEmployeeNotVirtualErrorDetails' required: - error_code - error_details TransactionTotalsMismatchError: type: object properties: error_code: type: string enum: - transaction_totals_mismatch error_details: $ref: '#/components/schemas/TransactionTotalsMismatchErrorDetails' required: - error_code - error_details TransactionLineItemInvalidError: type: object properties: error_code: type: string enum: - transaction_invalid_line_item error_details: $ref: '#/components/schemas/TransactionLineItemInvalidErrorDetails' required: - error_code - error_details RefundTransactionNotRefundableError: type: object properties: error_code: type: string enum: - refund_transaction_not_refundable error_details: $ref: '#/components/schemas/RefundTransactionNotRefundableErrorDetails' required: - error_code - error_details RefundLineItemsNotFoundError: type: object properties: error_code: type: string enum: - refund_line_items_not_found error_details: $ref: '#/components/schemas/RefundLineItemsNotFoundErrorDetails' required: - error_code - error_details RefundPaymentsNotFoundError: type: object properties: error_code: type: string enum: - refund_payments_not_found error_details: $ref: '#/components/schemas/RefundPaymentsNotFoundErrorDetails' required: - error_code - error_details RefundExceedsOriginalError: type: object properties: error_code: type: string enum: - refund_exceeds_original error_details: $ref: '#/components/schemas/RefundExceedsOriginalErrorDetails' required: - error_code - error_details InsufficientPermissionsError: type: object properties: error_code: type: string enum: - insufficient_permissions error_details: $ref: '#/components/schemas/InsufficientPermissionsErrorDetails' required: - error_code - error_details NoBannerAssociationError: type: object properties: error_code: type: string enum: - no_banner_association required: - error_code TransactionAlreadyExistsError: type: object properties: error_code: type: string enum: - transaction_already_exists error_details: $ref: '#/components/schemas/TransactionAlreadyExistsErrorDetails' required: - error_code - error_details TransactionRequestMismatchError: type: object properties: error_code: type: string enum: - transaction_request_mismatch error_details: $ref: '#/components/schemas/TransactionRequestMismatchErrorDetails' required: - error_code - error_details CreateRefundLineItem: type: object properties: discount_total: type: string description: >- Discounts being reversed on this line, as a positive amount. Recorded exactly as provided. Defaults to 0. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' item_modifiers: maxItems: 50 description: >- Fees and deposits (bottle deposits, CRV, bag fees) returned on this line. type: array items: $ref: '#/components/schemas/CreateRefundLineItemModifier' promo_savings: type: string description: >- Promotional savings being reversed on this line, as a positive amount. Recorded exactly as provided. Defaults to 0. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' quantity: type: string description: >- Number of units coming back, as a negative whole number. For items sold by weight, send -1 and provide the weight instead. Cannot return more than the line has left. pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' retail_price: type: string description: >- Price per unit — or, for items sold by weight, the price per unit of weight — the product sold at. Positive, as on the original transaction. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' tax_total: type: string description: >- Sales tax refunded on this line, as a negative amount. Defaults to 0. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' taxable_amount: type: string description: >- Portion of this line that was subject to sales tax, as a negative amount. Defaults to 0 (untaxed). format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' total: type: string description: >- Final amount refunded for this line including tax. Must equal (retail_price x quantity) — or (retail_price x weight) for items sold by weight — plus promo_savings, discount_total, the sum of fee/deposit amounts, and tax_total. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' transaction_line_item_id: type: string description: >- ID of the line on the original transaction that this line returns. Retrieve the transaction to read the IDs of its lines. format: uuid weight: type: string description: >- Measured weight coming back (e.g., pounds), as a negative amount, for items sold by weight. Send quantity -1 alongside it. Cannot return more than the line has left. pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' description: >- A product returned on a refund being recorded, with the quantity or weight coming back, the price it sold at, and the savings, fees, and tax being reversed with it. required: - quantity - retail_price - total - transaction_line_item_id CreateRefundPayment: type: object properties: amount: type: string description: >- Amount returned to this payment method, as a negative amount. Cannot return more than the payment has left. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' completed_at: type: string description: When the refund settled. Defaults to the refund's completed_at. format: date-time external_transaction_id: type: string maxLength: 250 description: >- Your payment processor's reference for the refund. Surrounding whitespace is removed; the value is otherwise stored as provided so your systems can look it up later, and it is never interpreted. transaction_payment_id: type: string description: >- ID of the payment on the original transaction that this returns money to. How it was tendered is taken from that payment. format: uuid description: >- Money returned on one of the payments the original transaction collected. required: - amount - external_transaction_id - transaction_payment_id TransactionGiftCardSale: type: object properties: id: type: string description: Unique identifier for the record. amount: type: string description: Amount loaded onto the gift card. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' gift_card_id: type: string nullable: true description: >- ID of the associated GiftCard that was funded by this sale. This value may be `null` if the sale was made while the POS was offline, and the transaction has not yet been back-filled. gift_card_transaction_id: type: string nullable: true description: >- ID of the associated GiftCardTransaction that funded the gift card. This value may be `null` if the sale was made while the POS was offline, and the transaction has not yet been back-filled. description: >- A gift card purchased on a transaction, with the amount loaded onto it and links to the gift card and the transaction that funded it. required: - id - amount - gift_card_id - gift_card_transaction_id TransactionIssuedCoupon: type: object properties: id: type: string description: Unique identifier for the record. coupon_code: type: string description: >- Coupon code the shopper presents to redeem the coupon on a later transaction. coupon_id: type: string description: ID of the coupon that was issued. ended_at: type: string description: Date and time after which the coupon can no longer be redeemed. format: date-time offer_benefit_value: type: string description: Value of the coupon to the shopper when redeemed. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' snap_incentive_program_id: type: string nullable: true description: ID of the SNAP incentive program the coupon was issued under. started_at: type: string description: Date and time from which the coupon can be redeemed. format: date-time description: >- A coupon issued to the shopper by a transaction, with its code, benefit value, and the window in which it can be redeemed. required: - id - coupon_code - coupon_id - ended_at - offer_benefit_value - snap_incentive_program_id - started_at TransactionLineItem: type: object properties: id: type: string description: Unique identifier for the record. coupon_total: type: string description: Total savings from coupons on this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ coupons: description: Coupons applied to this line. type: array items: $ref: '#/components/schemas/TransactionLineItemCoupon' department_id: type: string description: ID of the department the product is assigned to. discount_total: type: string description: Total savings from manual and employee discounts on this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ discounts: description: Manual and employee discounts applied to this line. type: array items: $ref: '#/components/schemas/TransactionLineItemDiscount' ebt_tax_waived_total: type: string description: Tax waived on this line because the product was paid for with EBT. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ free_quantity: type: string description: Portion of the quantity on this line given away free by a promotion. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' item_modifier_total: type: string description: >- Total of the fees and deposits charged on this line, such as bottle deposits and container redemption fees. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ item_modifiers: description: >- Fees and deposits charged on this line, such as bottle deposits, container redemption fees, and bag fees. type: array items: $ref: '#/components/schemas/TransactionLineItemModifier' loyalty_rewards: description: Loyalty rewards redeemed against this line. type: array items: $ref: '#/components/schemas/TransactionLineItemLoyaltyReward' loyalty_rewards_total: type: string description: Total savings from loyalty reward redemptions on this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ product: description: Product sold on this line. allOf: - $ref: '#/components/schemas/TransactionLineItemProduct' promo_savings: type: string description: Total savings from promotions on this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ promotions: description: Promotions applied to this line. type: array items: $ref: '#/components/schemas/TransactionLineItemPromotion' quantity: type: string description: >- Number of units sold on this line, or the weight sold for products priced by weight. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' refunded_order_line_item_id: type: string nullable: true description: >- ID of the original sale line this refund line returns, or null when this line is not a refund. retail_price: type: string description: Shelf price per unit before promotions, coupons, and discounts. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' retail_total: type: string description: Line total after promotions are applied, before discounts and tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ subtotal: type: string description: >- Retail price multiplied by quantity, before promotions, discounts, and tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ tax_total: type: string description: Total sales tax charged on this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ taxable_amount: type: string description: Portion of this line that is subject to tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ taxes: description: Sales taxes charged on this line. type: array items: $ref: '#/components/schemas/TransactionLineItemTax' total: type: string description: >- Final amount for this line, including tax. Positive on a sale and negative on a refund. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ transaction_type: deprecated: true description: Deprecated. Use `type`. allOf: - $ref: '#/components/schemas/TransactionType' type: description: Whether this line was sold, refunded, or voided. allOf: - $ref: '#/components/schemas/TransactionType' variable_weights: description: >- Weight readings recorded for this line when the product is sold by weight. type: array items: $ref: '#/components/schemas/TransactionLineItemVariableWeight' wic_adjusted_price: type: string nullable: true description: >- Price per unit the shopper paid under WIC, or null when WIC was not applied to this line. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ description: >- A product sold on a transaction, with its quantity, price, and totals, plus the coupons, discounts, loyalty rewards, promotions, fees, taxes, and weight readings recorded against it. required: - id - coupon_total - coupons - department_id - discount_total - discounts - ebt_tax_waived_total - free_quantity - item_modifier_total - item_modifiers - loyalty_rewards - loyalty_rewards_total - product - promo_savings - promotions - quantity - refunded_order_line_item_id - retail_price - retail_total - subtotal - tax_total - taxable_amount - taxes - total - transaction_type - type - variable_weights - wic_adjusted_price TransactionPayment: type: object properties: id: type: string description: Unique identifier for the record. authorized_amount: type: string description: >- Amount authorized for this payment, which is less than the requested amount on a partial approval. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ card_brand: nullable: true description: Card network used for the payment, or null for non-card payments. allOf: - $ref: '#/components/schemas/CardBrand' card_last4: type: string nullable: true minLength: 4 maxLength: 4 description: Last four digits of the card used, or null for non-card payments. pattern: ^[0-9]+$ cash_received: type: string nullable: true description: Cash handed over by the shopper, or null for non-cash payments. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' cashback_amount: type: string description: Cash back included in this payment. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ change_returned: type: string nullable: true description: Change given back to the shopper, or null for non-cash payments. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' completed_at: type: string description: Date and time when the payment was completed. format: date-time payment_type: description: How the payment was tendered. allOf: - $ref: '#/components/schemas/TransactionPaymentType' requested_amount: type: string description: Amount requested for this payment. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ reversals: description: Reversals recorded against this payment. type: array items: $ref: '#/components/schemas/TransactionPaymentReversal' terminal_was_online: type: boolean nullable: true description: >- Indicates if the payment terminal was online when the payment was authorized. This will be `null` for non-card payments. till_id: type: string nullable: true description: >- ID of the till the payment was collected into, or null when the payment was not tied to a till. format: uuid tip_amount: type: string description: Tip included in this payment. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ description: >- A payment collected on a transaction, covering how it was tendered, the amounts requested and authorized, any tip or cash back, the till it was paid into, and any reversals against it. required: - id - authorized_amount - card_brand - card_last4 - cash_received - cashback_amount - change_returned - completed_at - payment_type - requested_amount - reversals - terminal_was_online - till_id - tip_amount ReceiptType: type: string enum: - email - print - sms CompactRefund: type: object properties: id: type: string description: Unique identifier for the record. completed_at: type: string description: Date and time when the refund was finalized. format: date-time employee_id: type: string description: ID of the employee who processed the refund. pattern: ^[0-9]+$ lane_id: type: string description: ID of the checkout lane that processed the refund. pattern: ^[0-9]+$ shopper_facing_id: type: string description: Human-readable refund identifier shown to the shopper. started_at: type: string description: Date and time when the cashier started the refund. format: date-time store_id: type: string description: ID of the store where the refund was processed. pattern: ^[0-9]+$ subtotal: type: string description: Sum of line-item subtotals before promotions, discounts, and tax. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ tax_total: type: string description: Total tax refunded. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ total: type: string description: Final refund amount including tax. Refund totals are negative. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ description: >- A reference to a refund of a transaction, with where and when it was rung and the amounts refunded. Retrieve the refund itself for the products returned and how the money went back. required: - id - completed_at - employee_id - lane_id - shopper_facing_id - started_at - store_id - subtotal - tax_total - total TransactionSource: type: string enum: - api - migration - pos TransactionStatus: type: string enum: - completed - expired - suspended - voided TransactionType: type: string enum: - refund - sale - void TransactionLaneNotFoundErrorDetails: type: object properties: lane_id: type: string pattern: ^[0-9]+$ required: - lane_id TransactionLaneStoreMismatchErrorDetails: type: object properties: lane_id: type: string pattern: ^[0-9]+$ required: - lane_id TransactionLaneNotVirtualErrorDetails: type: object properties: lane_id: type: string pattern: ^[0-9]+$ required: - lane_id TransactionEmployeeNotFoundErrorDetails: type: object properties: employee_id: type: string pattern: ^[0-9]+$ required: - employee_id TransactionEmployeeNotVirtualErrorDetails: type: object properties: employee_id: type: string pattern: ^[0-9]+$ required: - employee_id TransactionTotalsMismatchErrorDetails: type: object properties: actual: type: string expected: type: string field: allOf: - $ref: '#/components/schemas/TransactionTotalsMismatchField' store_product_id: type: string pattern: ^[0-9]+$ required: - actual - expected - field TransactionLineItemInvalidErrorDetails: type: object properties: reason: allOf: - $ref: '#/components/schemas/TransactionLineItemInvalidReason' store_product_id: type: string pattern: ^[0-9]+$ required: - reason - store_product_id RefundTransactionNotRefundableErrorDetails: type: object properties: reason: allOf: - $ref: '#/components/schemas/RefundNotRefundableReason' transaction_id: type: string format: uuid required: - reason - transaction_id RefundLineItemsNotFoundErrorDetails: type: object properties: transaction_line_item_ids: type: array items: type: string format: uuid required: - transaction_line_item_ids RefundPaymentsNotFoundErrorDetails: type: object properties: transaction_payment_ids: type: array items: type: string format: uuid required: - transaction_payment_ids RefundExceedsOriginalErrorDetails: type: object properties: field: allOf: - $ref: '#/components/schemas/RefundExceedsField' remaining: type: string requested: type: string transaction_line_item_id: type: string format: uuid transaction_payment_id: type: string format: uuid required: - field - remaining - requested InsufficientPermissionsErrorDetails: type: object properties: action: allOf: - $ref: '#/components/schemas/Action' resource: allOf: - $ref: '#/components/schemas/Resource' required: - action - resource TransactionAlreadyExistsErrorDetails: type: object properties: id: type: string format: uuid required: - id TransactionRequestMismatchErrorDetails: type: object properties: fields: type: array items: type: string required: - fields CreateRefundLineItemModifier: type: object properties: amount: type: string description: >- Amount of this fee or deposit returned on this line, as a negative amount. format: negative-monetary pattern: ^(-[0-9]+(\.[0-9]+)?|0+(\.0+)?)$ example: '-199.99' item_modifier_id: type: string description: >- ID of the fee or deposit (e.g., bottle deposit, CRV, bag fee) as configured for your store. pattern: ^[0-9]+$ description: >- A fee or deposit returned on a line of a refund being recorded, such as a bottle deposit, CRV, or bag fee. required: - amount - item_modifier_id TransactionLineItemCoupon: type: object properties: id: type: string description: Unique identifier for the record. applied_amount: type: string description: Savings the coupon produced on this line item. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' coupon_code: type: string description: Coupon code that was scanned or entered at checkout. coupon_id: type: string description: ID of the coupon that was redeemed. offer_display_text: type: string description: Offer text shown on the receipt for the coupon. offer_id: type: string description: ID of the offer the coupon came from. description: >- A coupon redeemed against a line of a transaction, with the savings it produced and the offer it came from. required: - id - applied_amount - coupon_code - coupon_id - offer_display_text - offer_id TransactionLineItemDiscount: type: object properties: id: type: string description: Unique identifier for the record. applied_amount: type: string description: Savings the discount produced on this line item. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' discount_id: type: string nullable: true description: >- ID of the discount that was applied, or null when the cashier entered a one-off discount. discount_name: type: string description: Name of the discount shown to the cashier and on the receipt. discount_type: description: >- How the discount is calculated: a percentage off or a fixed amount off. allOf: - $ref: '#/components/schemas/DiscountType' discount_value: type: string description: >- Configured value of the discount, such as 10 for 10% off or 1.50 for $1.50 off. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' description: >- A discount applied to a line of a transaction, with its name, type, configured value, and the savings it produced. required: - id - applied_amount - discount_id - discount_name - discount_type - discount_value TransactionLineItemModifier: type: object properties: id: type: string description: Unique identifier for the record. amount: type: string description: Amount charged for the fee or deposit on this line item. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' item_modifier_id: type: string description: >- ID of the fee or deposit that was charged, such as a bottle deposit or CRV. pattern: ^[0-9]+$ quantity: type: string description: Number of units of the fee or deposit charged on this line item. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' tax_amount: type: string description: Tax charged on the fee or deposit. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' taxes: description: Taxes charged on the fee or deposit. type: array items: $ref: '#/components/schemas/TransactionLineItemTax' description: >- A fee or deposit charged on a line of a transaction, with the amount, quantity, and tax collected on it. required: - id - amount - item_modifier_id - quantity - tax_amount - taxes TransactionLineItemLoyaltyReward: type: object properties: id: type: string description: Unique identifier for the record. applied_amount: type: string description: Savings the loyalty reward produced on this line item. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' loyalty_reward_id: type: string description: ID of the loyalty reward that was redeemed. loyalty_reward_name: type: string description: Name of the loyalty reward at the time it was redeemed. offer_id: type: string description: ID of the offer associated with the loyalty reward. order_loyalty_reward_id: type: string description: >- ID of the transaction-level reward redemption this line item draws from. description: >- A loyalty reward redeemed against a line of a transaction, with the savings it produced and the offer it came from. required: - id - applied_amount - loyalty_reward_id - loyalty_reward_name - offer_id - order_loyalty_reward_id TransactionLineItemProduct: type: object properties: id: type: string description: ID of the product in your store's catalog. barcode: type: string description: >- UPC or PLU recorded for the product when it was sold, whether it was scanned or entered by hand. brand: type: string nullable: true description: Brand of the product. ebt_enabled: type: boolean description: Whether the product can be paid for with EBT. name: type: string description: Name of the product as it was sold. sold_by_weight: type: boolean description: Whether the product is priced by weight rather than by unit. unit_of_measure: type: string nullable: true description: Unit of measure the size is expressed in, such as oz or lb. unit_of_measure_amount: type: string nullable: true description: >- Size of the product in its unit of measure, such as 12 for a 12 oz can. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' wic_enabled: type: boolean description: Whether the product can be paid for with WIC. description: >- The product sold on a line of a transaction, along with the cost the store paid for it when known. required: - id - barcode - brand - ebt_enabled - name - sold_by_weight - unit_of_measure - unit_of_measure_amount - wic_enabled TransactionLineItemPromotion: type: object properties: id: type: string description: Unique identifier for the record. amount: type: string description: Portion of the line the promotion applied to. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' display_text: type: string nullable: true description: Text shown for the promotion on the receipt. offer_id: type: string description: ID of the offer the promotion belongs to. pattern: ^[0-9]+$ promotion_id: type: string description: ID of the promotion that produced the savings. pattern: ^[0-9]+$ savings: type: string description: Amount the promotion took off the line. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' description: >- A promotion applied to a line of a transaction, with the savings it produced, the amount it covered, and the text shown on the receipt. required: - id - amount - display_text - offer_id - promotion_id - savings TransactionLineItemTax: type: object properties: id: type: string description: Unique identifier for the record. amount: type: string description: Tax charged on this line item. format: monetary example: '199.99' pattern: ^-?[0-9]+(\.[0-9]+)?$ tax_rate: description: >- Tax rate that produced the charge, as it was configured when the transaction was completed. allOf: - $ref: '#/components/schemas/CompactTaxRate' description: >- Tax charged on a line of a transaction, with the amount collected and the tax rate that produced it. required: - id - amount - tax_rate TransactionLineItemVariableWeight: type: object properties: id: type: string description: Unique identifier for the record. variable_weight: description: >- Tare container weight subtracted from the scale reading, as it was recorded at the time of sale. allOf: - $ref: '#/components/schemas/CompactVariableWeight' description: >- An individual weight reading captured for a line of a transaction sold by weight. required: - id - variable_weight CardBrand: type: string enum: - american_express - atm - bill_me_later - china_union_pay - debit - diners_club - discover - ebt - jcb - mastercard - other - revolution_money - telecheck - undetermined - visa - voyager - wright_express TransactionPaymentType: type: string enum: - cash - cash_app - check - credit - debit - donation - doordash - ebt_cash - ebt_foodstamp - ecommerce - ewic - gift_card - gift_certificate - grubhub - house_account - instacart - lottery_payout - mfg_coupon - money_transfer - moneygram - paypal - qr_pay - ria_money_transfer - state_voucher - uber_eats - venmo - western_union - zelle TransactionPaymentReversal: type: object properties: id: type: string description: Unique identifier for the record. authorized_amount: type: string description: Amount actually released. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' card_brand: nullable: true description: >- Card network used for the reversed payment, or null for non-card payments. allOf: - $ref: '#/components/schemas/CardBrand' card_last4: type: string nullable: true minLength: 4 maxLength: 4 description: >- Last four digits of the card used for the reversed payment, or null for non-card payments. pattern: ^[0-9]+$ completed_at: type: string description: Date and time when the reversal was completed. format: date-time payment_type: description: How the reversed payment was tendered. allOf: - $ref: '#/components/schemas/TransactionPaymentType' requested_amount: type: string description: Amount requested to be released. format: positive-monetary pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' description: >- A reversal of a payment collected on a transaction, with the amount requested, the amount released, and how the payment was tendered. required: - id - authorized_amount - card_brand - card_last4 - completed_at - payment_type - requested_amount TransactionTotalsMismatchField: type: string enum: - line_total - order_total - payments_total - tax_total TransactionLineItemInvalidReason: type: string enum: - item_modifier_not_on_line - non_integer_quantity - retail_price_mismatch - weight_on_non_weight_item - weight_quantity_must_be_one - weight_required RefundNotRefundableReason: type: string enum: - not_a_sale - not_api_originated - not_completed RefundExceedsField: type: string enum: - line_discount_total - line_item_modifier_total - line_promo_savings - line_quantity - line_tax_total - line_taxable_amount - line_total - line_weight - payment_amount Action: type: string enum: - '*' - cancel - check_in - create - delete - read - record_events - refund - restart - update - void Resource: type: string enum: - '*' - accounting_integration - agent_chats - api_clients - asynchronous_tasks - banners - blackhawk_transactions - capabilities - coupons - custom_quick_actions - datacap_transactions - departments - discounts - ditto_auth_tokens - edge_agents - electronic_shelf_labels - employees - files - food_modifiers - gift_cards - gl_code_mappings - house_accounts - inventory - inventory_sessions - invoices - item_modifiers - label_dimension_sets - label_sheet_profiles - label_stock_products - lanes - loyalty_bonuses - loyalty_campaigns - loyalty_rewards - notification_templates - offers - order_guides - pos_banner_configurations - pos_orders - pos_tills - price_tags - product_ranges - products - promotions - purchase_orders - receiving - reporting - revision_sessions - revisions - roles - shopper_tags - shoppers - store_product_inventory_counts - store_product_lots - store_product_rules - store_product_tag_templates - store_snap_incentive_program_coupons - store_vendor_merge_requests - store_vendor_product_merge_requests - store_vendor_products - store_vendors - stores - tag_printings - tag_template_presets - tag_templates - tax_rates - users - variable_weights - vendor_merge_requests - vendor_product_merge_requests - vendors - wallet_payments - wic_products DiscountType: type: string enum: - amount_off - percentage_off CompactTaxRate: type: object properties: id: type: string description: Unique identifier for the tax rate. category: description: The kind of tax this rate represents. allOf: - $ref: '#/components/schemas/TaxRateCategory' name: type: string description: >- Name of the tax rate, such as the jurisdiction that levies it or the category it covers. value: type: string description: >- The rate charged. When `value_type` is `percentage`, this is a percentage of the taxable amount — `8.25` means 8.25%. When it is `amount`, this is a fixed amount of currency charged per unit sold. example: '8.25' pattern: ^[0-9]+(\.[0-9]+)?$ value_type: description: 'How `value` is applied: a fixed amount or a percentage.' allOf: - $ref: '#/components/schemas/TaxRateValueType' required: - id - category - name - value - value_type CompactVariableWeight: type: object properties: id: type: string nullable: true description: >- Unique identifier for the variable weight, or null when the weight was captured on a transaction without one. name: type: string description: Human-readable name for the tare container, such as "Produce bag". unit: description: >- Unit of measure the weight is expressed in, limited to the units the point of sale can weigh in. allOf: - $ref: '#/components/schemas/VariableWeightUnit' value: type: string description: >- Weight of the tare container, as a decimal string in the unit of measure. pattern: ^[0-9]+(\.[0-9]+)?$ example: '199.99' description: >- A compact reference to a tare container weight, embedded within other resources. Where it is embedded in a completed transaction, it is the immutable reading captured at the time of sale rather than a live reference. required: - id - name - unit - value TaxRateCategory: type: string description: The kind of tax a rate represents. enum: - other - sales TaxRateValueType: type: string description: >- How a tax rate applies its value: a fixed amount per unit sold, or a percentage of the taxable amount. enum: - amount - percentage VariableWeightUnit: type: string enum: - LBS - OZ securitySchemes: bearer: type: http scheme: bearer ```` ## Related topics - [Create transactions](/api/create-transactions.md) - [Process Refunds on the POS](/point-of-sale-pos/basic-cashier-functions/process-refunds-on-the-pos.md) - [The transaction object](/api/transactions/object.md)