--- title: "Create a new refund" method: POST path: "/v1/refund" tags: ["Refund"] --- # Create a new refund `POST /v1/refund` ## Request - Base URL: `https://api.finalpos.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.finalpos.com/v1/refund` - Auth: API key in header `x-api-key` Creates a new refund record. ## Request body - RefundCreateDto - `orderId` string, required: Order ID associated with the refund. - `outletId` string: Outlet ID associated with the refund. - `sessionId` string: Session ID associated with the refund. - `externalId` string: External ID of the refund. - `currency` 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'NZD' | 'CHF' | 'CNY' | 'INR' | 'MXN' | 'BRL' | 'ZAR' | 'SGD' | 'HKD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'THB' | 'MYR' | 'PHP' | 'IDR' | 'AED' | 'SAR' | 'ILS' | 'TRY' | 'RUB' | 'HTG' | 'BND' | 'CRC' | 'BDT' | 'UAH' | 'NGN' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BGN' | 'BMD' | 'BOB' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'COP' | 'CZK' | 'DOP' | 'DZD' | 'EGP' | 'ETB' | 'FJD' | 'GEL' | 'GHS' | 'GTQ' | 'GYD' | 'HNL' | 'IRR' | 'JMD' | 'KES' | 'KGS' | 'KHR' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'MAD' | 'MDL' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MUR' | 'MVR' | 'MZN' | 'NAD' | 'NIO' | 'NPR' | 'PAB' | 'PEN' | 'PGK' | 'PKR' | 'QAR' | 'RON' | 'RSD' | 'SBD' | 'SRD' | 'SYP' | 'TJS' | 'TMT' | 'TOP' | 'TTD' | 'TZS' | 'UYU' | 'UZS' | 'VES' | 'WST' | 'XCD' | 'YER' | 'ZMW' | 'CDF' | 'CUP' | 'ERN' | 'FKP' | 'GIP' | 'GMD' | 'KPW' | 'LRD' | 'LSL' | 'MGA' | 'MWK' | 'SCR' | 'SDG' | 'SHP' | 'SLE' | 'SOS' | 'SSP' | 'STN' | 'SZL' | 'VED' | 'XCG' | 'JPY' | 'KRW' | 'VND' | 'CLP' | 'ISK' | 'HUF' | 'TWD' | 'GNF' | 'BIF' | 'DJF' | 'KMF' | 'PYG' | 'RWF' | 'UGX' | 'VUV' | 'XAF' | 'XOF' | 'XPF' | 'KWD' | 'BHD' | 'OMR' | 'JOD' | 'TND' | 'LYD' | 'IQD': Currency of the Refund. ISO 4217 currency code. - `source` string: Source of the Refund. Closed vocabulary: in-store, public-api. - `lineItems` RefundLineItemDto[], required: Line items included in the refund. - `taxes` OrderTaxDto[]: Taxes applied to the line item. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` RefundDiscountDto - `cartDiscount` RefundCartDiscountDto - `amount` number: Amount of the cart discount. - `percentage` number: Percentage of the cart discount. - `itemDiscounts` RefundItemDiscountDto[]: Item discounts applied to the refund. Mirrors the order line item shape — one entry per item-level discount on the original line. - `amount` number: Amount of the item discount. - `percentage` number: Percentage of the item discount. - `label` string: Label for the item discount. - `fee` OrderLineItemFeeDto - `cartFee` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `itemFees` PriceModifierDetailDto[]: Item-level fees. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to post-discount line base, non-compounding). Each fee can carry its own tax behavior. - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `modifiers` OrderLineItemModifierDto[]: Refunded modifier rows for this line — the original line's modifiers[] re-extended to the refunded units (total = unitPrice × quantity × refunded quantity, exact; totalTax and taxes[].amount prorated by refunded ÷ original quantity; unitPrice and per-unit quantity unchanged). NOT fees. The amounts are already included in this refund line's total/totalTax and taxes[] buckets — stored for receipts and reporting, never re-added. - `modifierId` string, required: The modifier (the question, e.g. "Toppings") this selection answers. - `modifierName` string, required: Modifier name snapshot at sale time (renames never rewrite order history). - `choiceId` string, required: The chosen choice (embedded choice _id inside the modifier document). - `choiceName` string, required: Choice name snapshot at sale time — this is what prints on the receipt and kitchen ticket. - `unitPrice` number, required: Per-unit surcharge in minor currency units (e.g. cents for USD): the price of ONE unit of this choice on ONE unit of the line item. 0 is valid and recorded — a free choice such as "No pickles" still prints. - `quantity` number, required: Units of this choice per single line-item unit. 1 for single/multiple-selection modifiers; the stepper count for quantity-type modifiers (e.g. Extra shot ×2). - `total` number, required: Extended amount for the WHOLE line in minor currency units: unitPrice × quantity × lineItem.quantity. Included in the line item's total (see the money invariant on this schema). - `totalTax` number: Tax computed on `total` in minor currency units — Σ taxes[].amount. Included in the line item's totalTax. - `taxes` OrderTaxDto[]: Per-rate breakdown of totalTax, one bucket per rate that taxed this modifier row — a row can carry several tax groups. The amounts are already inside the parent line item's taxes[] buckets; never add them on top a second time. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `componentIndex` number: On a composite line: index into the line's `components` this modifier applies to (B28) — always set there, a composite has no modifiers of its own (B43). Absent on every other line. - `components` OrderLineItemComponentDto[]: Components of a refunded composite line, as sold, without the component tax fields (taxTableId, totalTax, taxes) — the refund's tax is on the line (B30). A composite is refunded as a whole line. - `productId` string, required: Product picked for this component. - `variantId` string, required: Variant picked for this component. - `name` string, required: Product name on the day of sale. - `attributes` string: Variant attributes as they read on the day of sale. - `sku` string: SKU of the component, as on the day of sale. - `productExternalId` string: External ID of the product. - `variantExternalId` string: External ID of the variant. - `partName` string: Part it was picked in ("Side"); absent when the part is untitled. - `quantity` number, required: Units of this component in ONE composite. - `price` number, required: This component's share of ONE composite's price, minor units, covering all of its quantity (not per unit). - `unitId` string: Unit the component was sold in, frozen at sale. - `unitAbbreviation` string: Abbreviation of that unit on the day of sale. - `unitRatioToBase` number: What one `unitId` was worth in base units on the day of sale. - `stockQuantity` number: Whole base units this component takes from its pool in ONE composite (B36d) — `toBase(quantity, unit)`, written by the till at sale; stock moves it × the line quantity. Absent on a by-the-piece component. - `stockVariantId` string: Variant whose pool the component drew from; absent when its own. - `taxTableId` string: Table that taxed this component with each item's own tax (B30); absent under the composite's tax group. - `totalTax` number: Tax on this component for the WHOLE line (all of its quantity, unlike price), minor units — Σ taxes[].amount (B30). Included in the line item's totalTax. - `taxes` OrderTaxDto[]: Per-rate breakdown of totalTax for the WHOLE line (all of its quantity), one bucket per rate that taxed this component (B30). The amounts are already inside the parent line item's taxes[] buckets; never add them on top a second time. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `lineNetWithFees` number: Customer-facing per-line total at refund time: (price × quantity) − sum(itemDiscounts) + sum(itemFees). Excludes cart-level discount and tax. - `quantity` number: Quantity of the line item. - `stockQuantity` number: How much left the pool for this refund, in the family's base unit — whole, frozen. `quantity` above is in the selling unit and may be fractional; the already-refunded ledger subtracts this one, so partial refunds of a weighed line never accumulate float dust. - `unitId` string: Unit the line was sold in — snapshot, so a refunds catalogue reads without the order. - `unitAbbreviation` string: Abbreviation as it read on the day of sale. - `unitRatioToBase` number: What one `unitId` was worth in base units then. - `stockVariantId` string: Variant whose pool the sale drew from, frozen with the rest. The restock has to put the goods back where they came from: resolving the pool from the variant as it stands today credits the wrong shelf the moment a merchant re-points it, which is what the snapshot exists to prevent. - `total` number: Total amount of the line item. - `price` number: Price per unit of the line item. - `name` string: Name of the line item. - `subTotal` number: Subtotal of the line item before taxes. - `sku` string: SKU of the line item. - `image` string: Image URL of the line item. - `productId` string, required: Product ID of the line item. - `productExternalId` string: External product ID. - `variantExternalId` string: External variant ID. - `lineItemExternalId` string: External line item ID. - `internalId` string: Internal ID of the line item. - `action` 'CUSTOM' | 'EXTERNAL_RESTOCK' | 'EXTERNAL_SALE' | 'PO_RECEIVED' | 'APPLIED_FROM_WOO' | 'BULK_RECOUNT' | 'TRANSFER' | 'UNIT_FAMILY_CHANGED' | 'COMPOSED_FOR_SALE' | 'SALE' | 'REFUND_DAMAGE' | 'REFUND_RESTOCK_RETURN' | 'RESTOCK_RETURN' | 'LOSS' | 'THEFT' | 'DAMAGE' | 'INVENTORY_RECOUNT' | 'STOCK_RECEIVED': Inventory action type for the line item. - `variantId` string, required: Variant ID of the line item. - `totalTax` number: Total tax amount for the line item. - `note` string: Note for the line item. - `description` string: Description of the line item. - `customSales` OrderCustomSaleDto[]: Custom sales included in the refund. - `customSaleId` string, required: ID of the custom sale. - `applyTaxes` boolean, required: Flag to indicate if the custom sale is applied. - `quantity` number, required: Quantity of the custom sale. - `name` string, required: Name of the custom sale. - `price` number, required: Price of the custom sale in minor currency units (e.g., cents for USD). - `totalTax` number, required: Total tax of the custom sale in minor currency units (e.g., cents for USD). - `total` number, required: Total of the custom sale in minor currency units (e.g., cents for USD). - `taxes` OrderTaxDto[]: Taxes of the custom sale. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` OrderCustomSaleDiscountDto - `cartDiscount` OrderCartDiscountDto, required - `amount` number, required: Amount of the cart discount in minor currency units (e.g., cents for USD). - `percentage` number, required: Percentage of the cart discount. - `label` string: Label of the cart discount. - `fee` OrderCustomSaleFeeDto - `cartFee` PriceModifierDetailDto, required - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `charges` ChargeDto[]: Payment charges for the custom sale (one per payment method). In a refund, holds the amount refunded per charge. - `chargeId` string, required: Identifier of the charge. - `paymentType` string, required: Type of the payment method used for this charge. - `amount` number, required: Amount in minor units. On the order = amount paid via this method; in a refund entry = amount refunded from this charge. - `transactionId` string: Transaction ID associated with the charge. - `processor` string: Processor of the charge. - `timestamp` string: Date and time of the charge. - `reservations` OrderReservationDto[]: Services included in the refund. - `productId` string, required: The bookable product sold by this reservation. - `internalId` string, required: Client-generated id of this reservation within the order. - `bookingId` string: The hold this reservation was sold from. - `name` string, required: Name of the service as it was sold. - `resourceName` string: Name of the resource as it was at sale time. - `price` number, required: Unit price in minor units. - `quantity` number: How many periods this row covers. - `fulfilledQuantity` number: How many of the sold periods have been performed. - `returnedQuantity` number: How many of the sold periods have been refunded. - `totalTax` number: Tax charged on this reservation, minor units. - `taxes` OrderTaxDto[]: Applied taxes, one entry per rate. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` OrderLineItemDiscountDto - `itemDiscounts` PriceModifierDetailDto[]: Item-level discounts. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to price × quantity, non-compounding). - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `cartDiscount` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `fee` OrderLineItemFeeDto - `cartFee` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `itemFees` PriceModifierDetailDto[]: Item-level fees. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to post-discount line base, non-compounding). Each fee can carry its own tax behavior. - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `total` number, required: Per-line total: (price × quantity) − item discounts + item fees. Excludes cart discount and tax. - `taxTableId` string: Tax table applied at sale time. - `resourceId` string, required: The resource whose capacity this reservation occupies. - `variantId` string: The variant sold for this reservation ("Haircut with Marco"). - `startAt` string, required: Start of the booked window (UTC). - `endAt` string, required: End of the booked window (UTC). - `bufferEndAt` string, required: End of the turnaround buffer (UTC). Equals endAt when the rules have none. - `lineItemInternalId` string: internalId of the line item that paid for this window: the composite line whose component booked it (FT-83, B41). Absent on a service sold on its own. - `componentIndex` number: Which of that composite line's `components` this booking belongs to (B41). Such a booking carries no money — price and total are 0, the component's share holds them. - `override` boolean: Staff force-booked past a full slot. - `overriddenBy` string: The staff member who forced the booking. - `reason` string: Reason for the refund. - `receiptId` string: Receipt ID of the refund. - `refundedBy` string: User ID of who processed the refund. - `refundedByExternalId` string: External ID of the user who processed the refund. - `summary` RefundSummaryDto, required - `subTotal` number: Legacy subtotal field. Retained for backward compatibility but not recommended for use in new development. - `discountTotal` number: Total discount amount. - `shippingTotal` number: Total shipping amount. - `total` number: Total amount of the refund. - `totalTaxes` number: Total taxes amount. - `isTaxInclusive` boolean, required: Flag to indicate if the refund is tax inclusive (mirrors source order). - `subtotalAfterFees` number, required: Math intermediate: grossSales + feesTotal (BEFORE discounts and tax). Magnitude. Receipts MUST NOT bind to this; refund receipts use grossSales for the items-only "Subtotal" line. Renamed from legacy `subTotal` for v16. - `taxes` OrderTaxDto[]: List of taxes applied to the refund. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `tip` RefundTipDto - `amount` number: Amount of the tip. - `percentage` number: Percentage of the tip. - `transactionId` string: Transaction ID of the payment method. - `tipTo` string: ID of the tip to. - `_id` string - `grossSales` number: Sum of refund lineItems[].price × quantity (+ customSales) in minor currency units. Stored positive (refund-side magnitude); the Sales Summary layer flips sign for display. - `modifiersTotal` number: Sum of refund lineItems[].modifiers[].total in minor currency units (magnitude) — refunded modifier value (FT-0010). Tracked separately from grossSales (which is price × quantity only). - `lineDiscountTotal` number: Sum of refund lineItems[].discount.itemDiscount.amount (magnitude). The "discounts reversed" reports use this directly; Sales Summary nets it against orders. - `cartDiscountTotal` number: Refund cart discount amount magnitude. - `feesTotal` number: Aggregate of all refund-side fees (= lineFeesTotal + cartFeesTotal) in minor currency units, magnitude. - `lineFeesTotal` number: Sum of refund lineItems[].fee.itemFee.amount (magnitude). - `cartFeesTotal` number: Sum of refund cartFees[].amount (magnitude). customSales[].fee.cartFee is an allocation and not summed separately. - `taxableFeesTotal` number: Sum of refund fees with an associated taxTableId. - `nonTaxableFeesTotal` number: Sum of refund fees with no taxTableId. - `taxableModifiersTotal` number: Sum of lineItems[].modifiers[].total for rows with a non-empty taxes[] (magnitude). Parity with taxableFeesTotal. - `nonTaxableModifiersTotal` number: Sum of lineItems[].modifiers[].total for rows with no taxes[] (magnitude). taxable + nonTaxable = modifiersTotal. - `totalTaxableSales` number: Sum of refund (price × qty) for lines with at least one tax bucket (magnitude). - `totalNonTaxableSales` number: Sum of refund (price × qty) for lines with no tax bucket (magnitude). - `tipTotal` number: Sum of refund tips[].amount in minor currency units (magnitude). - `cashRounding` number: Signed sum of refund payment[].cashRounding in minor currency units. - `payments` OrderSummaryPaymentsDto - `cardTotal` number: Sum of paymentMethods[].amount for card-family payment types (Terminal, TapToPay, Moto, Cloud, Bluetooth) in minor currency units. - `cashTotal` number: Sum of paymentMethods[].amount for cash payment type in minor currency units. - `customTotal` number: Sum of paymentMethods[].amount for non-integrated custom payment types (excludes liability tenders) in minor currency units. - `cardProcessingFeesTotal` number: Sum of paymentMethods[].processorFee for card-family payments in minor currency units. - `totalBeforeTip` number: Refund "TOTAL" magnitude on the receipt. Excl: grossSales − discountTotal + feesTotal + totalTaxes. Incl: grossSales − discountTotal + feesTotal. Equals `total − tipTotal` (magnitude). - `amountRefunded` number: Sum of refund payment[].amount in minor currency units (magnitude). Receipt "Amount paid" line on a refund renders this with a flipped sign. - `cartFees` OrderCartFeeDto[]: Cart fees included in the refund (same shape as order cartFees, with optional per-rate taxes). - `label` string, required: Label of the cart fee. - `id` string, required: ID of the cart fee. - `percentage` number, required: Percentage of the cart fee. - `amount` number, required: Amount of the cart fee in minor currency units (e.g., cents for USD). - `taxName` string: Name of the tax. - `taxTableId` string: ID of the tax table. - `tax` number: Tax of the cart fee in minor currency units (e.g., cents for USD). - `taxes` OrderTaxDto[]: Per-rate tax breakdown (e.g. gst, hst) so order/refund summary can show correct amounts per rate. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `payment` RefundPaymentDto[]: Payment details for the refund. - `transactionId` string: Transaction ID of the payment. - `paymentType` string: Type of payment method. - `amount` number: Amount of the payment. - `timestamp` string: Timestamp of the payment. - `processor` string: Payment processor used. - `saleId` string: Sale ID associated with the payment. - `tendered` number: What the customer physically presented for this payment leg. Cash legs: amount + change. Non-cash legs: equal to amount. Receipt "Cash tendered" line binds here. - `provider` 'stripe' | 'adyen' | 'external': PSP this refund leg was executed against (stripe | adyen). Follows the ORIGINAL sale payment's provider, not the station's current configuration. Absent on legs written before multi-provider support — readers must treat absence as stripe. - `tip` OrderTipDto - `percentage` number: Percentage of the tip. - `amount` number: Amount of the tip in minor currency units (e.g., cents for USD). - `tipTo` string: ID of the tip to. - `balance` number: Balance remaining after the refund. - `tips` RefundTipDto[]: Tips included in the refund. - `amount` number: Amount of the tip. - `percentage` number: Percentage of the tip. - `transactionId` string: Transaction ID of the payment method. - `tipTo` string: ID of the tip to. - `_id` string ## Response `201` The refund has been successfully created. - RefundResponseDto - `id` string: Unique identifier for the Refund. - `createdAt` string, date-time: Timestamp when the Refund was created. - `updatedAt` string, date-time: Timestamp when the Refund was last updated. - `companyId` string: Company ID associated with the Refund. - `orderId` string: Order ID associated with the refund. - `outletId` string: Outlet ID associated with the refund. - `sessionId` string: Session ID associated with the refund. - `externalId` string: External ID of the refund. - `currency` 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' | 'NZD' | 'CHF' | 'CNY' | 'INR' | 'MXN' | 'BRL' | 'ZAR' | 'SGD' | 'HKD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'THB' | 'MYR' | 'PHP' | 'IDR' | 'AED' | 'SAR' | 'ILS' | 'TRY' | 'RUB' | 'HTG' | 'BND' | 'CRC' | 'BDT' | 'UAH' | 'NGN' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BGN' | 'BMD' | 'BOB' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'COP' | 'CZK' | 'DOP' | 'DZD' | 'EGP' | 'ETB' | 'FJD' | 'GEL' | 'GHS' | 'GTQ' | 'GYD' | 'HNL' | 'IRR' | 'JMD' | 'KES' | 'KGS' | 'KHR' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'MAD' | 'MDL' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MUR' | 'MVR' | 'MZN' | 'NAD' | 'NIO' | 'NPR' | 'PAB' | 'PEN' | 'PGK' | 'PKR' | 'QAR' | 'RON' | 'RSD' | 'SBD' | 'SRD' | 'SYP' | 'TJS' | 'TMT' | 'TOP' | 'TTD' | 'TZS' | 'UYU' | 'UZS' | 'VES' | 'WST' | 'XCD' | 'YER' | 'ZMW' | 'CDF' | 'CUP' | 'ERN' | 'FKP' | 'GIP' | 'GMD' | 'KPW' | 'LRD' | 'LSL' | 'MGA' | 'MWK' | 'SCR' | 'SDG' | 'SHP' | 'SLE' | 'SOS' | 'SSP' | 'STN' | 'SZL' | 'VED' | 'XCG' | 'JPY' | 'KRW' | 'VND' | 'CLP' | 'ISK' | 'HUF' | 'TWD' | 'GNF' | 'BIF' | 'DJF' | 'KMF' | 'PYG' | 'RWF' | 'UGX' | 'VUV' | 'XAF' | 'XOF' | 'XPF' | 'KWD' | 'BHD' | 'OMR' | 'JOD' | 'TND' | 'LYD' | 'IQD': Currency of the Refund. ISO 4217 currency code. - `source` string: Source of the Refund. Closed vocabulary: in-store, public-api. - `lineItems` RefundLineItemDto[]: Line items included in the refund. - `taxes` OrderTaxDto[]: Taxes applied to the line item. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` RefundDiscountDto - `cartDiscount` RefundCartDiscountDto - `amount` number: Amount of the cart discount. - `percentage` number: Percentage of the cart discount. - `itemDiscounts` RefundItemDiscountDto[]: Item discounts applied to the refund. Mirrors the order line item shape — one entry per item-level discount on the original line. - `amount` number: Amount of the item discount. - `percentage` number: Percentage of the item discount. - `label` string: Label for the item discount. - `fee` OrderLineItemFeeDto - `cartFee` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `itemFees` PriceModifierDetailDto[]: Item-level fees. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to post-discount line base, non-compounding). Each fee can carry its own tax behavior. - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `modifiers` OrderLineItemModifierDto[]: Refunded modifier rows for this line — the original line's modifiers[] re-extended to the refunded units (total = unitPrice × quantity × refunded quantity, exact; totalTax and taxes[].amount prorated by refunded ÷ original quantity; unitPrice and per-unit quantity unchanged). NOT fees. The amounts are already included in this refund line's total/totalTax and taxes[] buckets — stored for receipts and reporting, never re-added. - `modifierId` string, required: The modifier (the question, e.g. "Toppings") this selection answers. - `modifierName` string, required: Modifier name snapshot at sale time (renames never rewrite order history). - `choiceId` string, required: The chosen choice (embedded choice _id inside the modifier document). - `choiceName` string, required: Choice name snapshot at sale time — this is what prints on the receipt and kitchen ticket. - `unitPrice` number, required: Per-unit surcharge in minor currency units (e.g. cents for USD): the price of ONE unit of this choice on ONE unit of the line item. 0 is valid and recorded — a free choice such as "No pickles" still prints. - `quantity` number, required: Units of this choice per single line-item unit. 1 for single/multiple-selection modifiers; the stepper count for quantity-type modifiers (e.g. Extra shot ×2). - `total` number, required: Extended amount for the WHOLE line in minor currency units: unitPrice × quantity × lineItem.quantity. Included in the line item's total (see the money invariant on this schema). - `totalTax` number: Tax computed on `total` in minor currency units — Σ taxes[].amount. Included in the line item's totalTax. - `taxes` OrderTaxDto[]: Per-rate breakdown of totalTax, one bucket per rate that taxed this modifier row — a row can carry several tax groups. The amounts are already inside the parent line item's taxes[] buckets; never add them on top a second time. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `componentIndex` number: On a composite line: index into the line's `components` this modifier applies to (B28) — always set there, a composite has no modifiers of its own (B43). Absent on every other line. - `components` OrderLineItemComponentDto[]: Components of a refunded composite line, as sold, without the component tax fields (taxTableId, totalTax, taxes) — the refund's tax is on the line (B30). A composite is refunded as a whole line. - `productId` string, required: Product picked for this component. - `variantId` string, required: Variant picked for this component. - `name` string, required: Product name on the day of sale. - `attributes` string: Variant attributes as they read on the day of sale. - `sku` string: SKU of the component, as on the day of sale. - `productExternalId` string: External ID of the product. - `variantExternalId` string: External ID of the variant. - `partName` string: Part it was picked in ("Side"); absent when the part is untitled. - `quantity` number, required: Units of this component in ONE composite. - `price` number, required: This component's share of ONE composite's price, minor units, covering all of its quantity (not per unit). - `unitId` string: Unit the component was sold in, frozen at sale. - `unitAbbreviation` string: Abbreviation of that unit on the day of sale. - `unitRatioToBase` number: What one `unitId` was worth in base units on the day of sale. - `stockQuantity` number: Whole base units this component takes from its pool in ONE composite (B36d) — `toBase(quantity, unit)`, written by the till at sale; stock moves it × the line quantity. Absent on a by-the-piece component. - `stockVariantId` string: Variant whose pool the component drew from; absent when its own. - `taxTableId` string: Table that taxed this component with each item's own tax (B30); absent under the composite's tax group. - `totalTax` number: Tax on this component for the WHOLE line (all of its quantity, unlike price), minor units — Σ taxes[].amount (B30). Included in the line item's totalTax. - `taxes` OrderTaxDto[]: Per-rate breakdown of totalTax for the WHOLE line (all of its quantity), one bucket per rate that taxed this component (B30). The amounts are already inside the parent line item's taxes[] buckets; never add them on top a second time. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `lineNetWithFees` number: Customer-facing per-line total at refund time: (price × quantity) − sum(itemDiscounts) + sum(itemFees). Excludes cart-level discount and tax. - `quantity` number: Quantity of the line item. - `stockQuantity` number: How much left the pool for this refund, in the family's base unit — whole, frozen. `quantity` above is in the selling unit and may be fractional; the already-refunded ledger subtracts this one, so partial refunds of a weighed line never accumulate float dust. - `unitId` string: Unit the line was sold in — snapshot, so a refunds catalogue reads without the order. - `unitAbbreviation` string: Abbreviation as it read on the day of sale. - `unitRatioToBase` number: What one `unitId` was worth in base units then. - `stockVariantId` string: Variant whose pool the sale drew from, frozen with the rest. The restock has to put the goods back where they came from: resolving the pool from the variant as it stands today credits the wrong shelf the moment a merchant re-points it, which is what the snapshot exists to prevent. - `total` number: Total amount of the line item. - `price` number: Price per unit of the line item. - `name` string: Name of the line item. - `subTotal` number: Subtotal of the line item before taxes. - `sku` string: SKU of the line item. - `image` string: Image URL of the line item. - `productId` string, required: Product ID of the line item. - `productExternalId` string: External product ID. - `variantExternalId` string: External variant ID. - `lineItemExternalId` string: External line item ID. - `internalId` string: Internal ID of the line item. - `action` 'CUSTOM' | 'EXTERNAL_RESTOCK' | 'EXTERNAL_SALE' | 'PO_RECEIVED' | 'APPLIED_FROM_WOO' | 'BULK_RECOUNT' | 'TRANSFER' | 'UNIT_FAMILY_CHANGED' | 'COMPOSED_FOR_SALE' | 'SALE' | 'REFUND_DAMAGE' | 'REFUND_RESTOCK_RETURN' | 'RESTOCK_RETURN' | 'LOSS' | 'THEFT' | 'DAMAGE' | 'INVENTORY_RECOUNT' | 'STOCK_RECEIVED': Inventory action type for the line item. - `variantId` string, required: Variant ID of the line item. - `totalTax` number: Total tax amount for the line item. - `note` string: Note for the line item. - `description` string: Description of the line item. - `customSales` OrderCustomSaleDto[]: Custom sales included in the refund. - `customSaleId` string, required: ID of the custom sale. - `applyTaxes` boolean, required: Flag to indicate if the custom sale is applied. - `quantity` number, required: Quantity of the custom sale. - `name` string, required: Name of the custom sale. - `price` number, required: Price of the custom sale in minor currency units (e.g., cents for USD). - `totalTax` number, required: Total tax of the custom sale in minor currency units (e.g., cents for USD). - `total` number, required: Total of the custom sale in minor currency units (e.g., cents for USD). - `taxes` OrderTaxDto[]: Taxes of the custom sale. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` OrderCustomSaleDiscountDto - `cartDiscount` OrderCartDiscountDto, required - `amount` number, required: Amount of the cart discount in minor currency units (e.g., cents for USD). - `percentage` number, required: Percentage of the cart discount. - `label` string: Label of the cart discount. - `fee` OrderCustomSaleFeeDto - `cartFee` PriceModifierDetailDto, required - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `charges` ChargeDto[]: Payment charges for the custom sale (one per payment method). In a refund, holds the amount refunded per charge. - `chargeId` string, required: Identifier of the charge. - `paymentType` string, required: Type of the payment method used for this charge. - `amount` number, required: Amount in minor units. On the order = amount paid via this method; in a refund entry = amount refunded from this charge. - `transactionId` string: Transaction ID associated with the charge. - `processor` string: Processor of the charge. - `timestamp` string: Date and time of the charge. - `reservations` OrderReservationDto[]: Services included in the refund. - `productId` string, required: The bookable product sold by this reservation. - `internalId` string, required: Client-generated id of this reservation within the order. - `bookingId` string: The hold this reservation was sold from. - `name` string, required: Name of the service as it was sold. - `resourceName` string: Name of the resource as it was at sale time. - `price` number, required: Unit price in minor units. - `quantity` number: How many periods this row covers. - `fulfilledQuantity` number: How many of the sold periods have been performed. - `returnedQuantity` number: How many of the sold periods have been refunded. - `totalTax` number: Tax charged on this reservation, minor units. - `taxes` OrderTaxDto[]: Applied taxes, one entry per rate. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `discount` OrderLineItemDiscountDto - `itemDiscounts` PriceModifierDetailDto[]: Item-level discounts. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to price × quantity, non-compounding). - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `cartDiscount` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `fee` OrderLineItemFeeDto - `cartFee` PriceModifierDetailDto - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `itemFees` PriceModifierDetailDto[]: Item-level fees. Each entry is applied independently per-unit (fixed amounts multiply by line quantity; percentages apply to post-discount line base, non-compounding). Each fee can carry its own tax behavior. - `percentage` number, required: Percentage as a decimal (e.g. 0.05 = 5%). Use 0.05 not 5 to avoid 500%. - `amount` number, required: Amount of the adjustment in minor currency units (e.g., cents for USD). - `label` string: Label for the adjustment. - `tax` number: Tax amount for the adjustment in minor currency units (e.g., cents for USD). - `taxTableId` string: Tax table ID for the adjustment. - `taxRateId` string: Tax rate ID for the adjustment. Identifies the specific rate within the tax table. - `total` number, required: Per-line total: (price × quantity) − item discounts + item fees. Excludes cart discount and tax. - `taxTableId` string: Tax table applied at sale time. - `resourceId` string, required: The resource whose capacity this reservation occupies. - `variantId` string: The variant sold for this reservation ("Haircut with Marco"). - `startAt` string, required: Start of the booked window (UTC). - `endAt` string, required: End of the booked window (UTC). - `bufferEndAt` string, required: End of the turnaround buffer (UTC). Equals endAt when the rules have none. - `lineItemInternalId` string: internalId of the line item that paid for this window: the composite line whose component booked it (FT-83, B41). Absent on a service sold on its own. - `componentIndex` number: Which of that composite line's `components` this booking belongs to (B41). Such a booking carries no money — price and total are 0, the component's share holds them. - `override` boolean: Staff force-booked past a full slot. - `overriddenBy` string: The staff member who forced the booking. - `reason` string: Reason for the refund. - `receiptId` string: Receipt ID of the refund. - `refundedBy` string: User ID of who processed the refund. - `refundedByExternalId` string: External ID of the user who processed the refund. - `summary` RefundSummaryDto - `subTotal` number: Legacy subtotal field. Retained for backward compatibility but not recommended for use in new development. - `discountTotal` number: Total discount amount. - `shippingTotal` number: Total shipping amount. - `total` number: Total amount of the refund. - `totalTaxes` number: Total taxes amount. - `isTaxInclusive` boolean, required: Flag to indicate if the refund is tax inclusive (mirrors source order). - `subtotalAfterFees` number, required: Math intermediate: grossSales + feesTotal (BEFORE discounts and tax). Magnitude. Receipts MUST NOT bind to this; refund receipts use grossSales for the items-only "Subtotal" line. Renamed from legacy `subTotal` for v16. - `taxes` OrderTaxDto[]: List of taxes applied to the refund. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `tip` RefundTipDto - `amount` number: Amount of the tip. - `percentage` number: Percentage of the tip. - `transactionId` string: Transaction ID of the payment method. - `tipTo` string: ID of the tip to. - `_id` string - `grossSales` number: Sum of refund lineItems[].price × quantity (+ customSales) in minor currency units. Stored positive (refund-side magnitude); the Sales Summary layer flips sign for display. - `modifiersTotal` number: Sum of refund lineItems[].modifiers[].total in minor currency units (magnitude) — refunded modifier value (FT-0010). Tracked separately from grossSales (which is price × quantity only). - `lineDiscountTotal` number: Sum of refund lineItems[].discount.itemDiscount.amount (magnitude). The "discounts reversed" reports use this directly; Sales Summary nets it against orders. - `cartDiscountTotal` number: Refund cart discount amount magnitude. - `feesTotal` number: Aggregate of all refund-side fees (= lineFeesTotal + cartFeesTotal) in minor currency units, magnitude. - `lineFeesTotal` number: Sum of refund lineItems[].fee.itemFee.amount (magnitude). - `cartFeesTotal` number: Sum of refund cartFees[].amount (magnitude). customSales[].fee.cartFee is an allocation and not summed separately. - `taxableFeesTotal` number: Sum of refund fees with an associated taxTableId. - `nonTaxableFeesTotal` number: Sum of refund fees with no taxTableId. - `taxableModifiersTotal` number: Sum of lineItems[].modifiers[].total for rows with a non-empty taxes[] (magnitude). Parity with taxableFeesTotal. - `nonTaxableModifiersTotal` number: Sum of lineItems[].modifiers[].total for rows with no taxes[] (magnitude). taxable + nonTaxable = modifiersTotal. - `totalTaxableSales` number: Sum of refund (price × qty) for lines with at least one tax bucket (magnitude). - `totalNonTaxableSales` number: Sum of refund (price × qty) for lines with no tax bucket (magnitude). - `tipTotal` number: Sum of refund tips[].amount in minor currency units (magnitude). - `cashRounding` number: Signed sum of refund payment[].cashRounding in minor currency units. - `payments` OrderSummaryPaymentsDto - `cardTotal` number: Sum of paymentMethods[].amount for card-family payment types (Terminal, TapToPay, Moto, Cloud, Bluetooth) in minor currency units. - `cashTotal` number: Sum of paymentMethods[].amount for cash payment type in minor currency units. - `customTotal` number: Sum of paymentMethods[].amount for non-integrated custom payment types (excludes liability tenders) in minor currency units. - `cardProcessingFeesTotal` number: Sum of paymentMethods[].processorFee for card-family payments in minor currency units. - `totalBeforeTip` number: Refund "TOTAL" magnitude on the receipt. Excl: grossSales − discountTotal + feesTotal + totalTaxes. Incl: grossSales − discountTotal + feesTotal. Equals `total − tipTotal` (magnitude). - `amountRefunded` number: Sum of refund payment[].amount in minor currency units (magnitude). Receipt "Amount paid" line on a refund renders this with a flipped sign. - `cartFees` OrderCartFeeDto[]: Cart fees included in the refund (same shape as order cartFees, with optional per-rate taxes). - `label` string, required: Label of the cart fee. - `id` string, required: ID of the cart fee. - `percentage` number, required: Percentage of the cart fee. - `amount` number, required: Amount of the cart fee in minor currency units (e.g., cents for USD). - `taxName` string: Name of the tax. - `taxTableId` string: ID of the tax table. - `tax` number: Tax of the cart fee in minor currency units (e.g., cents for USD). - `taxes` OrderTaxDto[]: Per-rate tax breakdown (e.g. gst, hst) so order/refund summary can show correct amounts per rate. - `name` string, required: Name of the tax. - `taxTableId` string: ID of the tax table. - `taxTableName` string: Name of the tax table. - `id` string: ID of the tax. - `percentage` number, required: Tax rate as a FRACTION, not a whole percent: send `0.15` for 15% (`0.09` = 9%). This is the platform-wide convention — the reporting canon applies it as `round(taxableAmount × percentage)`. A value above `1` is a whole-percent figure sent by mistake and is rejected with `400` (`15` would render as "1500%"). Must be between `0` and `1` inclusive. Amounts are unaffected — they stay in integer minor units (`6525` = $65.25). - `amount` number, required: Amount of the tax in minor currency units (e.g., cents for USD). - `taxableAmount` number: Taxable basis this rate was applied to in minor currency units; mode-agnostic. Required to derive per-rate Taxable Sales for tax breakdown reports under inclusive pricing. - `compounding` boolean: Flag to indicate if the tax is compounding. - `priority` number: Priority of the tax. - `_id` string - `payment` RefundPaymentDto[]: Payment details for the refund. - `transactionId` string: Transaction ID of the payment. - `paymentType` string: Type of payment method. - `amount` number: Amount of the payment. - `timestamp` string: Timestamp of the payment. - `processor` string: Payment processor used. - `saleId` string: Sale ID associated with the payment. - `tendered` number: What the customer physically presented for this payment leg. Cash legs: amount + change. Non-cash legs: equal to amount. Receipt "Cash tendered" line binds here. - `provider` 'stripe' | 'adyen' | 'external': PSP this refund leg was executed against (stripe | adyen). Follows the ORIGINAL sale payment's provider, not the station's current configuration. Absent on legs written before multi-provider support — readers must treat absence as stripe. - `tip` OrderTipDto - `percentage` number: Percentage of the tip. - `amount` number: Amount of the tip in minor currency units (e.g., cents for USD). - `tipTo` string: ID of the tip to. - `balance` number: Balance remaining after the refund. - `tips` RefundTipDto[]: Tips included in the refund. - `amount` number: Amount of the tip. - `percentage` number: Percentage of the tip. - `transactionId` string: Transaction ID of the payment method. - `tipTo` string: ID of the tip to. - `_id` string - `minorUnits` number: The Minor Units of the Refund to convert the amount from minor units to major units. ## Other responses - `400`: Bad request. Returns validation errors or other request-related errors. --- [API](https://skmtc.dev/finalpos/apis/final-pos-public-api.md) · [All operations](https://skmtc.dev/finalpos/apis/final-pos-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finalpos/apis/final-pos-public-api/revisions/6a6842dcb479?raw)