Skip to content

Final POS API (1.2.4)

Welcome to the Final POS Public API—your playground for crafting the checkout and kiosk flows you want. Create your API keys in Manage (Settings > API Keys) and send them as x-api-key on every request. Customer endpoints use dynamic DTO generation so they adapt to your custom tables in real time, while the rest of the controllers follow a stable, static contract for predictable integrations.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License
UNLICENSED
Languages
Servers
Mock server
https://docs.finalpos.com/_mock/openapi
Official API
https://api.finalpos.com

Data Transfer Objects (DTOs)

Schemas

Customer

Operations

Customers

Operations

Custom Tables: structure

Operations

Custom Table: content

Operations

Custom Tables: content

Operations

Product

Operations

Products

Operations

Outlet

Operations

Outlets

Operations

Category

Operations

Categories

Operations

Station

Operations

Stations

Operations

Variant

Operations

Variants

Operations

Order

Operations

Orders

Operations

Transactions

Operations

Roles

Operations

Attachment

Operations

Account

Operations

Refunds

Operations

Create a new refund

Request

Creates a new refund record.

Security
X-Api-Key
Bodyapplication/jsonrequired
orderIdstringrequired

Order ID associated with the refund.

Example: "507f1f77bcf86cd799439011"
sessionIdstring

Session ID associated with the refund.

Example: "507f1f77bcf86cd799439012"
externalIdstring

External ID of the refund.

Example: "ext_refund_123"
currencystring

Currency of the refund.

Example: "USD"
lineItemsArray of objects(RefundsLineItemDto)required

Line items included in the refund.

Example: [{"name":"Sweet Tea","quantity":1,"price":"5.00","total":"5.00","productId":"507f1f77bcf86cd799439011","variantId":"507f1f77bcf86cd799439012"}]
lineItems[].​taxesArray of objects(RefundsTaxDto)

Taxes applied to the line item.

Example: [{"name":"Sales Tax","amount":"10.00","percentage":10}]
lineItems[].​discountobject

Discount applied to the line item.

Example: {"cartDiscount":{"amount":"5.00","percentage":5}}
lineItems[].​quantitynumber

Quantity of the line item.

Example: 2
lineItems[].​totalstring

Total amount of the line item.

Example: "50.00"
lineItems[].​pricestring

Price per unit of the line item.

Example: "25.00"
lineItems[].​namestring

Name of the line item.

Example: "Sweet Tea"
lineItems[].​subTotalstring

Subtotal of the line item before taxes.

Example: "45.00"
lineItems[].​skustring

SKU of the line item.

Example: "SKU-001"
lineItems[].​imagestring

Image URL of the line item.

Example: "https://example.com/image.jpg"
lineItems[].​productIdstringrequired

Product ID of the line item.

Example: "507f1f77bcf86cd799439011"
lineItems[].​productExternalIdstring

External product ID.

Example: "ext_prod_123"
lineItems[].​variantExternalIdstring

External variant ID.

Example: "ext_var_123"
lineItems[].​lineItemExternalIdstring

External line item ID.

Example: "ext_line_123"
lineItems[].​internalIdstring

Internal ID of the line item.

Example: "int_line_123"
lineItems[].​actionstring

Inventory action type for the line item.

Example: "restock"
lineItems[].​variantIdstringrequired

Variant ID of the line item.

Example: "507f1f77bcf86cd799439012"
lineItems[].​totalTaxstring

Total tax amount for the line item.

Example: "5.00"
lineItems[].​notestring

Note for the line item.

Example: "No ice please"
lineItems[].​descriptionstring

Description of the line item.

Example: "Refreshing sweet tea beverage"
reasonstring

Reason for the refund.

Example: "Customer requested refund"
refundedBystring

User ID of who processed the refund.

Example: "507f1f77bcf86cd799439013"
refundedByExternalIdstring

External ID of the user who processed the refund.

Example: "ext_user_123"
summaryobjectrequired

Summary of the refund amounts.

Example: {"total":"100.00","subTotal":"90.00","totalTaxes":"10.00"}
summary.​discountTotalstring

Total discount amount.

Example: "10.00"
summary.​shippingTotalstring

Total shipping amount.

Example: "5.00"
summary.​totalstring

Total amount of the refund.

Example: "100.00"
summary.​totalTaxesstring

Total taxes amount.

Example: "10.00"
summary.​subTotalstring

Subtotal before taxes and discounts.

Example: "90.00"
summary.​taxesArray of objects(RefundsSummaryTaxDto)

List of taxes applied to the refund.

Example: [{"name":"Sales Tax","percentage":10,"amount":"10.00"}]
summary.​tipobject

Tip included in the refund.

Example: {"amount":"5.00","percentage":15}
paymentArray of objects(RefundsPaymentDto)

Payment details for the refund.

Example: [{"paymentType":"credit_card","amount":"100.00","transactionId":"txn_123"}]
balancestring

Balance remaining after the refund.

Example: "0.00"
curl -i -X POST \
  https://docs.finalpos.com/_mock/openapi/v1/api/refunds \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "orderId": "507f1f77bcf86cd799439011",
    "sessionId": "507f1f77bcf86cd799439012",
    "externalId": "ext_refund_123",
    "currency": "USD",
    "lineItems": [
      {
        "name": "Sweet Tea",
        "quantity": 1,
        "price": "5.00",
        "total": "5.00",
        "productId": "507f1f77bcf86cd799439011",
        "variantId": "507f1f77bcf86cd799439012"
      }
    ],
    "reason": "Customer requested refund",
    "refundedBy": "507f1f77bcf86cd799439013",
    "refundedByExternalId": "ext_user_123",
    "summary": {
      "total": "100.00",
      "subTotal": "90.00",
      "totalTaxes": "10.00"
    },
    "payment": [
      {
        "paymentType": "credit_card",
        "amount": "100.00",
        "transactionId": "txn_123"
      }
    ],
    "balance": "0.00"
  }'

Responses

The refund has been successfully created.

Bodyapplication/json
idstring

Unique identifier for the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
createdAtstring(date-time)

Timestamp when the Refunds was created.

Example: "2025-12-07T19:31:48.436+00:00"
updatedAtstring(date-time)

Timestamp when the Refunds was last updated.

Example: "2025-12-07T19:35:48.436+00:00"
companyIdstring

Company ID associated with the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
orderIdstring

Order ID associated with the refund.

Example: "507f1f77bcf86cd799439011"
sessionIdstring

Session ID associated with the refund.

Example: "507f1f77bcf86cd799439012"
externalIdstring

External ID of the refund.

Example: "ext_refund_123"
currencystring

Currency of the refund.

Example: "USD"
fromFinalboolean

Flag to indicate if the Refund is created from Final.

Example: false
lineItemsArray of objects(RefundsLineItemDto)

Line items included in the refund.

Example: [{"name":"Sweet Tea","quantity":1,"price":"5.00","total":"5.00","productId":"507f1f77bcf86cd799439011","variantId":"507f1f77bcf86cd799439012"}]
reasonstring

Reason for the refund.

Example: "Customer requested refund"
refundedBystring

User ID of who processed the refund.

Example: "507f1f77bcf86cd799439013"
refundedByExternalIdstring

External ID of the user who processed the refund.

Example: "ext_user_123"
summaryobject

Summary of the refund amounts.

Example: {"total":"100.00","subTotal":"90.00","totalTaxes":"10.00"}
paymentArray of objects(RefundsPaymentDto)

Payment details for the refund.

Example: [{"paymentType":"credit_card","amount":"100.00","transactionId":"txn_123"}]
balancestring

Balance remaining after the refund.

Example: "0.00"
Response
application/json
{
  "id": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "createdAt": "2025-12-07T19:31:48.436+00:00",
  "updatedAt": "2025-12-07T19:35:48.436+00:00",
  "companyId": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "orderId": "507f1f77bcf86cd799439011",
  "sessionId": "507f1f77bcf86cd799439012",
  "externalId": "ext_refund_123",
  "currency": "USD",
  "fromFinal": false,
  "lineItems": [
    { … }
  ],
  "reason": "Customer requested refund",
  "refundedBy": "507f1f77bcf86cd799439013",
  "refundedByExternalId": "ext_user_123",
  "summary": {
    "total": "100.00",
    "subTotal": "90.00",
    "totalTaxes": "10.00"
  },
  "payment": [
    { … }
  ],
  "balance": "0.00"
}

Get a refund by ID

Request

Retrieves a single refund by its unique identifier.

Security
X-Api-Key
Path
idstringrequired

Refunds ID

curl -i -X GET \
  'https://docs.finalpos.com/_mock/openapi/v1/api/refunds/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

The refund has been successfully retrieved.

Bodyapplication/json
idstring

Unique identifier for the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
createdAtstring(date-time)

Timestamp when the Refunds was created.

Example: "2025-12-07T19:31:48.436+00:00"
updatedAtstring(date-time)

Timestamp when the Refunds was last updated.

Example: "2025-12-07T19:35:48.436+00:00"
companyIdstring

Company ID associated with the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
orderIdstring

Order ID associated with the refund.

Example: "507f1f77bcf86cd799439011"
sessionIdstring

Session ID associated with the refund.

Example: "507f1f77bcf86cd799439012"
externalIdstring

External ID of the refund.

Example: "ext_refund_123"
currencystring

Currency of the refund.

Example: "USD"
fromFinalboolean

Flag to indicate if the Refund is created from Final.

Example: false
lineItemsArray of objects(RefundsLineItemDto)

Line items included in the refund.

Example: [{"name":"Sweet Tea","quantity":1,"price":"5.00","total":"5.00","productId":"507f1f77bcf86cd799439011","variantId":"507f1f77bcf86cd799439012"}]
reasonstring

Reason for the refund.

Example: "Customer requested refund"
refundedBystring

User ID of who processed the refund.

Example: "507f1f77bcf86cd799439013"
refundedByExternalIdstring

External ID of the user who processed the refund.

Example: "ext_user_123"
summaryobject

Summary of the refund amounts.

Example: {"total":"100.00","subTotal":"90.00","totalTaxes":"10.00"}
paymentArray of objects(RefundsPaymentDto)

Payment details for the refund.

Example: [{"paymentType":"credit_card","amount":"100.00","transactionId":"txn_123"}]
balancestring

Balance remaining after the refund.

Example: "0.00"
Response
application/json
{
  "id": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "createdAt": "2025-12-07T19:31:48.436+00:00",
  "updatedAt": "2025-12-07T19:35:48.436+00:00",
  "companyId": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "orderId": "507f1f77bcf86cd799439011",
  "sessionId": "507f1f77bcf86cd799439012",
  "externalId": "ext_refund_123",
  "currency": "USD",
  "fromFinal": false,
  "lineItems": [
    { … }
  ],
  "reason": "Customer requested refund",
  "refundedBy": "507f1f77bcf86cd799439013",
  "refundedByExternalId": "ext_user_123",
  "summary": {
    "total": "100.00",
    "subTotal": "90.00",
    "totalTaxes": "10.00"
  },
  "payment": [
    { … }
  ],
  "balance": "0.00"
}

Update a refund by ID

Request

Updates an existing refund record.

Security
X-Api-Key
Path
idstringrequired

Refunds ID

Bodyapplication/jsonrequired
orderIdstring

Order ID associated with the refund.

Example: "507f1f77bcf86cd799439011"
sessionIdstring

Session ID associated with the refund.

Example: "507f1f77bcf86cd799439012"
externalIdstring

External ID of the refund.

Example: "ext_refund_123"
currencystring

Currency of the refund.

Example: "USD"
lineItemsArray of objects(RefundsLineItemDto)

Line items included in the refund.

Example: [{"name":"Sweet Tea","quantity":1,"price":"5.00","total":"5.00","productId":"507f1f77bcf86cd799439011","variantId":"507f1f77bcf86cd799439012"}]
reasonstring

Reason for the refund.

Example: "Customer requested refund"
refundedBystring

User ID of who processed the refund.

Example: "507f1f77bcf86cd799439013"
refundedByExternalIdstring

External ID of the user who processed the refund.

Example: "ext_user_123"
summaryobject

Summary of the refund amounts.

Example: {"total":"100.00","subTotal":"90.00","totalTaxes":"10.00"}
paymentArray of objects(RefundsPaymentDto)

Payment details for the refund.

Example: [{"paymentType":"credit_card","amount":"100.00","transactionId":"txn_123"}]
balancestring

Balance remaining after the refund.

Example: "0.00"
curl -i -X PUT \
  'https://docs.finalpos.com/_mock/openapi/v1/api/refunds/{id}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "orderId": "507f1f77bcf86cd799439011",
    "sessionId": "507f1f77bcf86cd799439012",
    "externalId": "ext_refund_123",
    "currency": "USD",
    "lineItems": [
      {
        "name": "Sweet Tea",
        "quantity": 1,
        "price": "5.00",
        "total": "5.00",
        "productId": "507f1f77bcf86cd799439011",
        "variantId": "507f1f77bcf86cd799439012"
      }
    ],
    "reason": "Customer requested refund",
    "refundedBy": "507f1f77bcf86cd799439013",
    "refundedByExternalId": "ext_user_123",
    "summary": {
      "total": "100.00",
      "subTotal": "90.00",
      "totalTaxes": "10.00"
    },
    "payment": [
      {
        "paymentType": "credit_card",
        "amount": "100.00",
        "transactionId": "txn_123"
      }
    ],
    "balance": "0.00"
  }'

Responses

The refund has been successfully updated.

Bodyapplication/json
idstring

Unique identifier for the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
createdAtstring(date-time)

Timestamp when the Refunds was created.

Example: "2025-12-07T19:31:48.436+00:00"
updatedAtstring(date-time)

Timestamp when the Refunds was last updated.

Example: "2025-12-07T19:35:48.436+00:00"
companyIdstring

Company ID associated with the Refunds.

Example: "o1p2q3r4s5t6u7v8w9x0y1z2"
orderIdstring

Order ID associated with the refund.

Example: "507f1f77bcf86cd799439011"
sessionIdstring

Session ID associated with the refund.

Example: "507f1f77bcf86cd799439012"
externalIdstring

External ID of the refund.

Example: "ext_refund_123"
currencystring

Currency of the refund.

Example: "USD"
fromFinalboolean

Flag to indicate if the Refund is created from Final.

Example: false
lineItemsArray of objects(RefundsLineItemDto)

Line items included in the refund.

Example: [{"name":"Sweet Tea","quantity":1,"price":"5.00","total":"5.00","productId":"507f1f77bcf86cd799439011","variantId":"507f1f77bcf86cd799439012"}]
reasonstring

Reason for the refund.

Example: "Customer requested refund"
refundedBystring

User ID of who processed the refund.

Example: "507f1f77bcf86cd799439013"
refundedByExternalIdstring

External ID of the user who processed the refund.

Example: "ext_user_123"
summaryobject

Summary of the refund amounts.

Example: {"total":"100.00","subTotal":"90.00","totalTaxes":"10.00"}
paymentArray of objects(RefundsPaymentDto)

Payment details for the refund.

Example: [{"paymentType":"credit_card","amount":"100.00","transactionId":"txn_123"}]
balancestring

Balance remaining after the refund.

Example: "0.00"
Response
application/json
{
  "id": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "createdAt": "2025-12-07T19:31:48.436+00:00",
  "updatedAt": "2025-12-07T19:35:48.436+00:00",
  "companyId": "o1p2q3r4s5t6u7v8w9x0y1z2",
  "orderId": "507f1f77bcf86cd799439011",
  "sessionId": "507f1f77bcf86cd799439012",
  "externalId": "ext_refund_123",
  "currency": "USD",
  "fromFinal": false,
  "lineItems": [
    { … }
  ],
  "reason": "Customer requested refund",
  "refundedBy": "507f1f77bcf86cd799439013",
  "refundedByExternalId": "ext_user_123",
  "summary": {
    "total": "100.00",
    "subTotal": "90.00",
    "totalTaxes": "10.00"
  },
  "payment": [
    { … }
  ],
  "balance": "0.00"
}

Delete a refund by ID

Request

Deletes a refund by its unique identifier.

Security
X-Api-Key
Path
idstringrequired

Refunds ID

curl -i -X DELETE \
  'https://docs.finalpos.com/_mock/openapi/v1/api/refunds/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

The refund has been successfully deleted.

Bodyapplication/json
statusCodenumberrequired

HTTP status code

Example: 200
messagestringrequired

Message describing the result of the operation

Example: "Resource with Id 123 deleted successfully"
Response
application/json
{
  "statusCode": 200,
  "message": "Resource with Id 123 deleted successfully"
}

Session

Operations

ZapierTriggers

Operations