Refund

Create a new refund

Creates a new refund record.

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

Request body

orderIdstring required

Order ID associated with the refund.

outletIdstring

Outlet ID associated with the refund.

sessionIdstring

Session ID associated with the refund.

externalIdstring

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.

sourcestring

Source of the Refund. Closed vocabulary: in-store, public-api.

reasonstring

Reason for the refund.

receiptIdstring

Receipt ID of the refund.

refundedBystring

User ID of who processed the refund.

refundedByExternalIdstring

External ID of the user who processed the refund.

balancenumber

Balance remaining after the refund.

Example request

{
  "orderId": "507f1f77bcf86cd799439011",
  "outletId": "507f1f77bcf86cd799439010",
  "sessionId": "507f1f77bcf86cd799439012",
  "externalId": "1234567890",
  "currency": "USD",
  "source": "in-store",
  "lineItems": [
    {
      "name": "Sweet Tea",
      "quantity": 1,
      "price": 5000,
      "total": 5000,
      "productId": "507f1f77bcf86cd799439011",
      "variantId": "507f1f77bcf86cd799439012"
    }
  ],
  "customSales": [
    {
      "customSaleId": "1234567890",
      "quantity": 1,
      "name": "Custom Sale 1",
      "price": 100050,
      "totalTax": 100050,
      "total": 100050,
      "taxes": [
        {
          "name": "Tax 1",
          "percentage": 10,
          "amount": 100050,
          "taxTableName": "Tax Table 1",
          "compounding": true,
          "priority": 1,
          "taxTableId": "1234567890",
          "id": "1234567890"
        }
      ],
      "discount": {
        "cartDiscount": {
          "amount": 100050,
          "percentage": 0.15,
          "label": "Cart Discount 1"
        }
      },
      "fee": {
        "cartFee": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        }
      },
      "charges": [
        {
          "chargeId": "1234567890",
          "paymentType": "credit card",
          "amount": 100050,
          "transactionId": "507f1f77bcf86cd799439011",
          "processor": "Stripe",
          "timestamp": "2026-10-17T10:35:58.123Z"
        }
      ]
    }
  ],
  "reservations": [
    {
      "productId": "a1b2c3d4e5f6a7b8c9d0e1f2",
      "internalId": "f7c1…",
      "bookingId": "a1b2c3d4e5f6a7b8c9d0e1f2",
      "name": "Haircut",
      "resourceName": "Marco",
      "price": 5000,
      "quantity": 1,
      "fulfilledQuantity": 1,
      "totalTax": 750,
      "taxes": [
        {
          "id": "gst",
          "name": "GST",
          "percentage": 5,
          "amount": 250
        }
      ],
      "discount": {
        "itemDiscounts": [
          {
            "percentage": 10,
            "amount": 500,
            "label": "Item Sale"
          }
        ],
        "cartDiscount": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        }
      },
      "fee": {
        "cartFee": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        },
        "itemFees": [
          {
            "percentage": 0.02,
            "amount": 100,
            "label": "Handling",
            "tax": 5,
            "taxTableId": "def456"
          }
        ]
      },
      "total": 5000,
      "taxTableId": "tax_standard",
      "resourceId": "o1p2q3r4s5t6u7v8w9x0y1z2",
      "variantId": "o1p2q3r4s5t6u7v8w9x0y1z6",
      "startAt": "2026-09-05T13:00:00.000Z",
      "endAt": "2026-09-05T15:00:00.000Z",
      "bufferEndAt": "2026-09-05T15:30:00.000Z",
      "lineItemInternalId": "li_01",
      "overriddenBy": "o1p2q3r4s5t6u7v8w9x0y1z9"
    }
  ],
  "reason": "Customer requested refund",
  "receiptId": "RCP-2025-001",
  "refundedBy": "507f1f77bcf86cd799439013",
  "refundedByExternalId": "ext_user_123",
  "summary": {
    "subTotal": 10000,
    "discountTotal": 1000,
    "shippingTotal": 500,
    "total": 10000,
    "totalTaxes": 1000,
    "subtotalAfterFees": 10000,
    "taxes": [
      {
        "name": "Sales Tax",
        "percentage": 10,
        "amount": 1000,
        "id": "507f1f77bcf86cd799439011",
        "taxTableId": "507f1f77bcf86cd799439012",
        "taxTableName": "Dev Tax"
      }
    ],
    "tip": {
      "amount": 500,
      "percentage": 15,
      "transactionId": "1234567890",
      "tipTo": "1234567890"
    },
    "grossSales": 10842,
    "cashRounding": 2,
    "payments": {
      "cardTotal": 44500,
      "cashTotal": 14875,
      "cardProcessingFeesTotal": 1126
    },
    "totalBeforeTip": 10000,
    "amountRefunded": 10000
  },
  "cartFees": [
    {
      "id": "507f1f77bcf86cd799439011",
      "label": "Custom fee",
      "amount": 1000,
      "percentage": 0.1,
      "tax": 250,
      "taxName": "Dev Tax",
      "taxes": []
    }
  ],
  "payment": [
    {
      "paymentType": "credit_card",
      "amount": 10000,
      "transactionId": "txn_123"
    }
  ],
  "balance": 10000,
  "tips": [
    {
      "_id": "507f1f77bcf86cd799439014",
      "amount": 500,
      "percentage": 15,
      "transactionId": "1234567890",
      "tipTo": "1234567890"
    }
  ]
}

Response

The refund has been successfully created.

idstring

Unique identifier for the Refund.

createdAtstring date-time

Timestamp when the Refund was created.

updatedAtstring date-time

Timestamp when the Refund was last updated.

companyIdstring

Company ID associated with the Refund.

orderIdstring

Order ID associated with the refund.

outletIdstring

Outlet ID associated with the refund.

sessionIdstring

Session ID associated with the refund.

externalIdstring

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.

sourcestring

Source of the Refund. Closed vocabulary: in-store, public-api.

reasonstring

Reason for the refund.

receiptIdstring

Receipt ID of the refund.

refundedBystring

User ID of who processed the refund.

refundedByExternalIdstring

External ID of the user who processed the refund.

balancenumber

Balance remaining after the refund.

minorUnitsnumber

The Minor Units of the Refund to convert the amount from minor units to major units.

Example response

{
  "id": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "createdAt": "2025-12-07T19:31:48.436+00:00",
  "updatedAt": "2025-12-07T19:35:48.436+00:00",
  "companyId": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "orderId": "507f1f77bcf86cd799439011",
  "outletId": "507f1f77bcf86cd799439010",
  "sessionId": "507f1f77bcf86cd799439012",
  "externalId": "1234567890",
  "currency": "USD",
  "source": "in-store",
  "lineItems": [
    {
      "name": "Sweet Tea",
      "quantity": 1,
      "price": 5000,
      "total": 5000,
      "productId": "507f1f77bcf86cd799439011",
      "variantId": "507f1f77bcf86cd799439012"
    }
  ],
  "customSales": [
    {
      "customSaleId": "1234567890",
      "quantity": 1,
      "name": "Custom Sale 1",
      "price": 100050,
      "totalTax": 100050,
      "total": 100050,
      "taxes": [
        {
          "name": "Tax 1",
          "percentage": 10,
          "amount": 100050,
          "taxTableName": "Tax Table 1",
          "compounding": true,
          "priority": 1,
          "taxTableId": "1234567890",
          "id": "1234567890"
        }
      ],
      "discount": {
        "cartDiscount": {
          "amount": 100050,
          "percentage": 0.15,
          "label": "Cart Discount 1"
        }
      },
      "fee": {
        "cartFee": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        }
      },
      "charges": [
        {
          "chargeId": "1234567890",
          "paymentType": "credit card",
          "amount": 100050,
          "transactionId": "507f1f77bcf86cd799439011",
          "processor": "Stripe",
          "timestamp": "2026-10-17T10:35:58.123Z"
        }
      ]
    }
  ],
  "reservations": [
    {
      "productId": "a1b2c3d4e5f6a7b8c9d0e1f2",
      "internalId": "f7c1…",
      "bookingId": "a1b2c3d4e5f6a7b8c9d0e1f2",
      "name": "Haircut",
      "resourceName": "Marco",
      "price": 5000,
      "quantity": 1,
      "fulfilledQuantity": 1,
      "totalTax": 750,
      "taxes": [
        {
          "id": "gst",
          "name": "GST",
          "percentage": 5,
          "amount": 250
        }
      ],
      "discount": {
        "itemDiscounts": [
          {
            "percentage": 10,
            "amount": 500,
            "label": "Item Sale"
          }
        ],
        "cartDiscount": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        }
      },
      "fee": {
        "cartFee": {
          "percentage": 0.1,
          "amount": 500,
          "label": "Holiday Discount",
          "tax": 50,
          "taxTableId": "o1p2q3r4s5t6u7v8w9x0y1z2",
          "taxRateId": "a1b2c3d4e5f6g7h8i9j0k1l2"
        },
        "itemFees": [
          {
            "percentage": 0.02,
            "amount": 100,
            "label": "Handling",
            "tax": 5,
            "taxTableId": "def456"
          }
        ]
      },
      "total": 5000,
      "taxTableId": "tax_standard",
      "resourceId": "o1p2q3r4s5t6u7v8w9x0y1z2",
      "variantId": "o1p2q3r4s5t6u7v8w9x0y1z6",
      "startAt": "2026-09-05T13:00:00.000Z",
      "endAt": "2026-09-05T15:00:00.000Z",
      "bufferEndAt": "2026-09-05T15:30:00.000Z",
      "lineItemInternalId": "li_01",
      "overriddenBy": "o1p2q3r4s5t6u7v8w9x0y1z9"
    }
  ],
  "reason": "Customer requested refund",
  "receiptId": "RCP-2025-001",
  "refundedBy": "507f1f77bcf86cd799439013",
  "refundedByExternalId": "ext_user_123",
  "summary": {
    "subTotal": 10000,
    "discountTotal": 1000,
    "shippingTotal": 500,
    "total": 10000,
    "totalTaxes": 1000,
    "subtotalAfterFees": 10000,
    "taxes": [
      {
        "name": "Sales Tax",
        "percentage": 10,
        "amount": 1000,
        "id": "507f1f77bcf86cd799439011",
        "taxTableId": "507f1f77bcf86cd799439012",
        "taxTableName": "Dev Tax"
      }
    ],
    "tip": {
      "amount": 500,
      "percentage": 15,
      "transactionId": "1234567890",
      "tipTo": "1234567890"
    },
    "grossSales": 10842,
    "cashRounding": 2,
    "payments": {
      "cardTotal": 44500,
      "cashTotal": 14875,
      "cardProcessingFeesTotal": 1126
    },
    "totalBeforeTip": 10000,
    "amountRefunded": 10000
  },
  "cartFees": [
    {
      "id": "507f1f77bcf86cd799439011",
      "label": "Custom fee",
      "amount": 1000,
      "percentage": 0.1,
      "tax": 250,
      "taxName": "Dev Tax",
      "taxes": []
    }
  ],
  "payment": [
    {
      "paymentType": "credit_card",
      "amount": 10000,
      "transactionId": "txn_123"
    }
  ],
  "balance": 10000,
  "tips": [
    {
      "_id": "507f1f77bcf86cd799439014",
      "amount": 500,
      "percentage": 15,
      "transactionId": "1234567890",
      "tipTo": "1234567890"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.