Heads up, our devs are blazing ahead—docs are catching up, so some features might not be fully documented yet.
Visit our websiteAPI Documentation

OrderSettlement

OrderSettlement

List order settlements

get

List all settlements for an order.

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
pageNumberintegerOptional

Reference to a specific page in a result set.

pageSizeintegerOptional

The number of items per page in a result set.

sortBystringOptional

Defines which field the resource list is sorted by.

sortDirectionstring · enumOptional
ENUM Description
ASC Sort in ascending order
DESC Sort in descending order
Possible values:
Responses
200
Example response
get
GET /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Example response

{
  "items": [
    {
      "amount": 1,
      "createdAt": "2025-07-30T18:11:51.725Z",
      "displayMessages": [
        {
          "key": "text",
          "message": "text",
          "timestamp": "2025-07-30T18:11:51.725Z"
        }
      ],
      "externalId": "text",
      "externalPaymentReference": "text",
      "idMethod": "NO_CVM_RULE_PERFORMED",
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "ledgerNumber": "text",
      "ledgerType": "LEDGER",
      "parameters": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "settledAt": "2025-07-30T18:11:51.725Z",
      "settlementCode": "text",
      "settlementUid": "text",
      "settlementName": "text",
      "state": "NOT_STARTED",
      "status": "NEW",
      "storeSettlementIssuerUid": "text",
      "tenantUserDisplayName": "text",
      "tenantUserUid": "text",
      "storePaymentMethodUid": "text",
      "currency": {
        "amount": 1,
        "code": "text",
        "exchangeRate": 1
      },
      "additionalDetails": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "paymentCount": 1,
      "paymentAmount": 1,
      "orderReceiptUid": "text"
    }
  ],
  "paging": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalCount": 1
  }
}

Create a new order settlement

post

Create a new settlement for an order.

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
Body

Create a new settlement

amountintegerRequired

in cents, e.g. 1,50 as 150

deviceIdentifierstringOptional
externalIdstringOptional

External reference for the settlement

storePaymentMethodUidstringRequiredPattern: ^[A-Za-z0-9-_]*
settlementUidstringOptionalPattern: ^[A-Za-z0-9-_]+
Responses
200
Example response
application/json
post
POST /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "amount": 1,
  "deviceIdentifier": "text",
  "externalId": "text",
  "parameters": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "storePaymentMethodUid": "text",
  "settlementUid": "text"
}
200

Example response

{
  "amount": 1,
  "createdAt": "2025-07-30T18:11:51.725Z",
  "displayMessages": [
    {
      "key": "text",
      "message": "text",
      "timestamp": "2025-07-30T18:11:51.725Z"
    }
  ],
  "externalId": "text",
  "externalPaymentReference": "text",
  "idMethod": "NO_CVM_RULE_PERFORMED",
  "lastModifiedAt": "2025-07-30T18:11:51.725Z",
  "ledgerNumber": "text",
  "ledgerType": "LEDGER",
  "parameters": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "settledAt": "2025-07-30T18:11:51.725Z",
  "settlementCode": "text",
  "settlementUid": "text",
  "settlementName": "text",
  "state": "NOT_STARTED",
  "status": "NEW",
  "storeSettlementIssuerUid": "text",
  "tenantUserDisplayName": "text",
  "tenantUserUid": "text",
  "storePaymentMethodUid": "text",
  "currency": {
    "amount": 1,
    "code": "text",
    "exchangeRate": 1
  },
  "additionalDetails": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "paymentCount": 1,
  "paymentAmount": 1,
  "orderReceiptUid": "text"
}

Get order settlement details

get

Get details for a specific settlement on an order.

Authorizations
Path parameters
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
settlementUidstringRequired

Reference to a settlement on an order.

Pattern: ^[A-Za-z0-9-_]+
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
checkStatusbooleanOptional

Check external payment gateways and fetch status

includeDisplayMessagesbooleanOptional

Include display messages in the response

Responses
200
Example response
application/json
get
GET /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements/{settlementUid} HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Example response

{
  "amount": 1,
  "createdAt": "2025-07-30T18:11:51.725Z",
  "displayMessages": [
    {
      "key": "text",
      "message": "text",
      "timestamp": "2025-07-30T18:11:51.725Z"
    }
  ],
  "externalId": "text",
  "externalPaymentReference": "text",
  "idMethod": "NO_CVM_RULE_PERFORMED",
  "lastModifiedAt": "2025-07-30T18:11:51.725Z",
  "ledgerNumber": "text",
  "ledgerType": "LEDGER",
  "parameters": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "settledAt": "2025-07-30T18:11:51.725Z",
  "settlementCode": "text",
  "settlementUid": "text",
  "settlementName": "text",
  "state": "NOT_STARTED",
  "status": "NEW",
  "storeSettlementIssuerUid": "text",
  "tenantUserDisplayName": "text",
  "tenantUserUid": "text",
  "storePaymentMethodUid": "text",
  "currency": {
    "amount": 1,
    "code": "text",
    "exchangeRate": 1
  },
  "additionalDetails": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "paymentCount": 1,
  "paymentAmount": 1,
  "orderReceiptUid": "text"
}

Delete an order settlement

delete

Delete a settlement on an order.

Authorizations
Path parameters
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
settlementUidstringRequired

Reference to a settlement on an order.

Pattern: ^[A-Za-z0-9-_]+
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
forceDeletebooleanOptional

Force Delete on a settlement

Responses
204
No Content
delete
DELETE /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements/{settlementUid} HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List payments for settlement

get

A payment belongs to an order settlement with payment method INVOICE. Normally invoices are paid via bank and the payments imported or also registered by hand. But if a customer pays the invoice by another method in the store (e.g. cash or card), it is made as a settlement on a new order without any lines, and then shown as paymentSettlement.

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
settlementUidstringRequired

Reference to a settlement on an order.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
Responses
200
Example response
application/json
get
GET /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements/{settlementUid}/payments HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Example response

{
  "items": [
    {
      "paymentUid": "text",
      "amount": 1,
      "paidAt": "2025-07-30T18:11:51.725Z",
      "externalReference": "text",
      "paymentSettlementUid": "text",
      "createdAt": "2025-07-30T18:11:51.725Z",
      "createdBy": "text"
    }
  ]
}

Add payment for settlement

post

Add a payment for a settlement. amount is in cents. If paidAt is nil, it is set to now.

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
settlementUidstringRequired

Reference to a settlement on an order.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
Body
amountintegerRequired
paidAtstring · date-timeOptional
externalReferencestringOptional
paymentUidstringOptionalPattern: ^[A-Za-z0-9-_]*
Responses
201
Example response
application/json
post
POST /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements/{settlementUid}/payments HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "amount": 1,
  "paidAt": "2025-07-30T18:11:51.725Z",
  "externalReference": "text",
  "paymentUid": "text"
}
201

Example response

{
  "paymentUid": "text",
  "amount": 1,
  "paidAt": "2025-07-30T18:11:51.725Z",
  "externalReference": "text",
  "paymentSettlementUid": "text",
  "createdAt": "2025-07-30T18:11:51.725Z",
  "createdBy": "text"
}

Create new payment-settlement

post

A payment belongs to an order settlement with payment method INVOICE. Normally invoices are paid via bank and the payments imported or also registered by hand. But if a customer pays the invoice by another method in store (e.g. cash or card) it is made as a settlement on a new order without any lines, and this is what we do here, meaning the path parameters must refer to the order and settlement for which this is a payment.

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
orderUidstringRequired

Reference to an Order.

Pattern: ^[A-Za-z0-9-_]+
settlementUidstringRequired

Reference to a settlement on an order.

Pattern: ^[A-Za-z0-9-_]+
Body

Create a new settlement

amountintegerRequired

in cents, e.g. 1,50 as 150

deviceIdentifierstringOptional
externalIdstringOptional

External reference for the settlement

storePaymentMethodUidstringRequiredPattern: ^[A-Za-z0-9-_]*
settlementUidstringOptionalPattern: ^[A-Za-z0-9-_]+
Responses
201
Example response
application/json
post
POST /v2/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/settlements/{settlementUid}/payment-settlements HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "amount": 1,
  "deviceIdentifier": "text",
  "externalId": "text",
  "parameters": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "storePaymentMethodUid": "text",
  "settlementUid": "text"
}
201

Example response

{
  "shippingAddress": {
    "address": "text",
    "city": "text",
    "companyName": "text",
    "countryCode": "text",
    "email": "text",
    "firstname": "text",
    "lastname": "text",
    "mobile": "text",
    "postalCode": "text",
    "vatNumber": "text",
    "displayName": "text"
  },
  "createdAt": "2025-07-30T18:11:51.725Z",
  "customerAddress": {
    "address": "text",
    "city": "text",
    "companyName": "text",
    "countryCode": "text",
    "email": "text",
    "firstname": "text",
    "lastname": "text",
    "mobile": "text",
    "postalCode": "text",
    "vatNumber": "text",
    "displayName": "text"
  },
  "customerUid": "text",
  "customerContact": {
    "customerContactUid": "text",
    "firstname": "text",
    "lastname": "text",
    "email": "text",
    "mobile": "text",
    "displayName": "text"
  },
  "deliveryState": "NOT_STARTED",
  "externalOrderNumber": "text",
  "externalVoucherNumber": "text",
  "invoiceAddress": {
    "address": "text",
    "city": "text",
    "companyName": "text",
    "countryCode": "text",
    "email": "text",
    "mobile": "text",
    "firstname": "text",
    "lastname": "text",
    "postalCode": "text",
    "displayName": "text",
    "customerAddressUid": "text"
  },
  "items": [
    {
      "actions": [
        {
          "comment": "text",
          "createdAt": "2025-07-30T18:11:51.725Z",
          "createdBy": "text",
          "handlingActionUid": "text",
          "handlingActionName": "text",
          "handlingDescription": "text",
          "handlingUid": "text",
          "handlingName": "text",
          "lastModifiedAt": "2025-07-30T18:11:51.725Z",
          "lastModifiedBy": "text",
          "orderHandlingActionUid": "text"
        }
      ],
      "allowedActions": [
        "QUANTITY_SOLD"
      ],
      "createdAt": "2025-07-30T18:11:51.725Z",
      "discountReasonCode": "text",
      "externalId": "text",
      "itemCost": 1,
      "itemDiscountAmount": 1,
      "itemDiscountPercentage": 1,
      "itemGrossProfitAmount": 1,
      "itemGrossProfitPercentage": 1,
      "itemPrice": 1,
      "itemVatAmount": 1,
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "ledgerNumber": "text",
      "name": "text",
      "note": "text",
      "orderItemUid": "text",
      "orderLinks": [
        {
          "orderUid": "text",
          "orderItemUid": "text",
          "orderNumber": "text",
          "storeUid": "text",
          "type": "CREDIT"
        }
      ],
      "originalItemPrice": 1,
      "productUid": "text",
      "productType": "STOCK",
      "properties": [
        {
          "uid": "text",
          "key": "text",
          "value": "text"
        }
      ],
      "quantityCredited": 1,
      "quantityDelivered": 1,
      "quantityOrdered": 1,
      "quantityReserved": 1,
      "returnReasonCode": "text",
      "serialnumber": "text",
      "sku": "text",
      "sortOrder": 1,
      "tenantUserDisplayName": "text",
      "tenantUserUid": "text",
      "totalCost": 1,
      "totalDiscountAmount": 1,
      "totalGrossProfitAmount": 1,
      "totalPrice": 1,
      "totalVatAmount": 1,
      "vatCodeUid": "text",
      "warehouseUid": "text",
      "warehouseName": "text",
      "internalInfo": "text",
      "productProperties": [
        {
          "productPropertyUid": "text",
          "propertyName": "text",
          "propertyOptionName": "text",
          "propertyType": "TEXT",
          "propertyText": "text",
          "propertyUid": "text",
          "propertyOptionUid": "text",
          "required": true
        }
      ],
      "coverImage": {
        "productMediaUid": "text",
        "mainUrl": "text",
        "thumbnailUrl": "text"
      },
      "deliveryUid": "text",
      "compensationReasonCode": "text",
      "orderReceiptUid": "text",
      "allowDeliveryFromDate": "2025-07-30T18:11:51.725Z",
      "reservationType": "NONE",
      "reservationDetails": {
        "warehouse": {
          "warehouseName": "text"
        },
        "purchaseOrder": {
          "purchaseOrderUid": "text",
          "purchaseOrderItemUid": "text",
          "expectedDeliveryDate": "2025-07-30T18:11:51.725Z",
          "purchaseOrderNumber": "text",
          "quantityOrdered": 1
        }
      }
    }
  ],
  "lastModifiedAt": "2025-07-30T18:11:51.725Z",
  "note": "text",
  "orderUid": "text",
  "orderNumber": "text",
  "orderState": "OPEN",
  "orderTotals": {
    "costTotal": 1,
    "grandTotal": 1,
    "grossProfitAmount": 1,
    "grossProfitPercentage": 1,
    "specifiedVat": [
      {
        "vatAmount": 1,
        "vatDescription": "text",
        "vatRate": 1
      }
    ],
    "subtotal": 1,
    "totalDiscount": 1,
    "totalVat": 1
  },
  "orderhandlingState": "NOT_STARTED",
  "orderhandlings": [
    {
      "active": true,
      "createdAt": "2025-07-30T18:11:51.725Z",
      "createdBy": "text",
      "description": "text",
      "handlingUid": "text",
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "lastModifiedBy": "text",
      "name": "text",
      "orderHandlingUid": "text",
      "state": "NOT_STARTED"
    }
  ],
  "settleState": "NOT_STARTED",
  "settledAt": "2025-07-30T18:11:51.725Z",
  "settlementTotals": {
    "change": 1,
    "remaining": 1,
    "remainingRounded": 1,
    "totals": 1,
    "remainingPrePayment": 1
  },
  "settlements": [
    {
      "amount": 1,
      "createdAt": "2025-07-30T18:11:51.725Z",
      "displayMessages": [
        {
          "key": "text",
          "message": "text",
          "timestamp": "2025-07-30T18:11:51.725Z"
        }
      ],
      "externalId": "text",
      "externalPaymentReference": "text",
      "idMethod": "NO_CVM_RULE_PERFORMED",
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "ledgerNumber": "text",
      "ledgerType": "LEDGER",
      "parameters": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "settledAt": "2025-07-30T18:11:51.725Z",
      "settlementCode": "text",
      "settlementUid": "text",
      "settlementName": "text",
      "state": "NOT_STARTED",
      "status": "NEW",
      "storeSettlementIssuerUid": "text",
      "tenantUserDisplayName": "text",
      "tenantUserUid": "text",
      "storePaymentMethodUid": "text",
      "currency": {
        "amount": 1,
        "code": "text",
        "exchangeRate": 1
      },
      "additionalDetails": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "paymentCount": 1,
      "paymentAmount": 1,
      "orderReceiptUid": "text"
    }
  ],
  "storeUid": "text",
  "storeName": "text",
  "systemOrigin": "text",
  "tenantUserDisplayName": "text",
  "tenantUserUid": "text",
  "tillUid": "text",
  "type": "OFFER",
  "validUntil": "2025-07-30T18:11:51.725Z",
  "vatFree": true,
  "vatPrint": "SUM",
  "voucherNumber": "text",
  "deliveryDate": "2025-07-30",
  "discounts": [
    {
      "orderDiscountUid": "text",
      "discountCode": "text",
      "type": "PERCENTAGE",
      "amount": 1,
      "name": "text",
      "origin": "LOYALTY",
      "validTo": "2025-07-30T18:11:51.725Z",
      "maxUsage": 1,
      "productSkus": [
        "text"
      ],
      "orderItemUids": [
        "text"
      ],
      "externalTransactionId": "text",
      "scope": "WHOLE_ORDER",
      "discountReasonCode": "text",
      "createdAt": "2025-07-30T18:11:51.725Z",
      "createdBy": "text",
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "lastModifiedBy": "text",
      "campaignUid": "text"
    }
  ],
  "compensationReasonUid": "text",
  "lastModifiedBy": "text"
}

Search in settlements

post

Retrieves a filtered list of settlements for the organization. Results are sorted by createdAt in descending order when no sorting parameter is specified. The spreadsheet response is a report containing only key settlement fields (pagination does not apply to spreadsheet responses).

Authorizations
Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
organizationUidstringRequired

Reference to an organization.

Pattern: ^[A-Za-z0-9-_]+
Query parameters
pageNumberintegerOptional

Reference to a specific page in a result set.

pageSizeintegerOptional

The number of items per page in a result set.

sortBystringOptional

Defines which field the resource list is sorted by.

sortDirectionstring · enumOptional
ENUM Description
ASC Sort in ascending order
DESC Sort in descending order
Possible values:
Body
storeUidsstring[]Optional
storePaymentMethodUidsstring[]Optional
settlementCodestringOptional
externalIdsstring[]Optional
externalPaymentReferencesstring[]Optional
hasEhfInvoicebooleanOptional

EHF = "Elektronisk handelsformat"

hasPaymentBalanceOutstandingbooleanOptional
Responses
200
Example response
post
POST /v2/tenants/{tenantUid}/organizations/{organizationUid}/settlements/search HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 321

{
  "storeUids": [
    "text"
  ],
  "storePaymentMethodUids": [
    "text"
  ],
  "settlementCode": "text",
  "createdAt": {
    "from": "2025-07-30T18:11:51.725Z",
    "to": "2025-07-30T18:11:51.725Z"
  },
  "states": [
    "NOT_STARTED"
  ],
  "statuses": [
    "NEW"
  ],
  "externalIds": [
    "text"
  ],
  "externalPaymentReferences": [
    "text"
  ],
  "hasEhfInvoice": true,
  "hasPaymentBalanceOutstanding": true
}
200

Example response

{
  "items": [
    {
      "amount": 1,
      "createdAt": "2025-07-30T18:11:51.725Z",
      "displayMessages": [
        {
          "key": "text",
          "message": "text",
          "timestamp": "2025-07-30T18:11:51.725Z"
        }
      ],
      "externalId": "text",
      "externalPaymentReference": "text",
      "idMethod": "NO_CVM_RULE_PERFORMED",
      "lastModifiedAt": "2025-07-30T18:11:51.725Z",
      "ledgerNumber": "text",
      "ledgerType": "LEDGER",
      "parameters": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "settledAt": "2025-07-30T18:11:51.725Z",
      "settlementCode": "text",
      "settlementUid": "text",
      "settlementName": "text",
      "state": "NOT_STARTED",
      "status": "NEW",
      "storeSettlementIssuerUid": "text",
      "tenantUserDisplayName": "text",
      "tenantUserUid": "text",
      "storePaymentMethodUid": "text",
      "currency": {
        "amount": 1,
        "code": "text",
        "exchangeRate": 1
      },
      "additionalDetails": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "paymentCount": 1,
      "paymentAmount": 1,
      "orderReceiptUid": "text"
    }
  ],
  "paging": {
    "pageNumber": 1,
    "pageSize": 1,
    "totalCount": 1
  }
}
PreviousOrderHandlingNextPaymentMethod

Was this helpful?