API docs by Redocly

onlinebon API (2.0.0)

Download OpenAPI specification:

URL: https://www.onlinebon.at

Onlinebon API allows consumers to manage their POS data of onlinebon.at.

API Versioning

The version of the endpoint you are requesting can be controlled by the api-version header:

api-version: 2
Version Released at
v1 01.03.2020
v2 01.01.2021

Test Environment

To test your implementation use the test environment at https://api-test.onlinebon.at

Authentication

Obtain and refresh access tokens

Exchange credentials for JWT

Request Body schema: application/json
required
username
required
string <email>
password
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "user@onlinebon.at",
  • "password": "your_password"
}

Response samples

Content type
application/json
{
  • "jwt": "eyJhbGciOiJIUzI1NiJ9.e30.XmNK3GpH3Ys_7wsYBfq4C3M6goz71I7dTgUkuIa5lyQ",
  • "expires_in": 300
}

Get SumUp access token

Returns a valid SumUp access token for the authenticated user's customer account. If the stored token is expired or about to expire (within 5 minutes), it is automatically refreshed using the stored refresh token.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "sup_sk_abc123def456ghi789jkl012mno345pqr",
  • "expires_at": "2026-02-23T15:30:00.000Z"
}

User

User endpoints (v1 + v2)

Get logged-in user (v1)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "status": true,
  • "email": "user@example.com",
  • "username": "string",
  • "role": "admin",
  • "created_at": "string",
  • "consents": [
    ],
  • "cashdesk": {
    },
  • "customer": {
    }
}

Get logged-in user (v2)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "is_active": true,
  • "email": "user@example.com",
  • "username": "string",
  • "role": "admin",
  • "created_at": "string",
  • "active_session": {
    },
  • "sum_up": {
    },
  • "status": {
    },
  • "consents": [
    ],
  • "cashdesk": {
    },
  • "company": {
    }
}

Productgroups (v1)

v1 product group management

List product groups

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
parent
string
noparent
boolean
active
boolean
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a product group

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
description
string
color
string
parent
string

Responses

Request samples

Content type
application/json
{
  • "name": "Arizona Cardinals",
  • "description": "string",
  • "color": "#cccccc",
  • "parent": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "description": "string",
  • "active": true,
  • "sells": 0,
  • "color": "string",
  • "customer": {
    },
  • "parent": {
    }
}

Get product group count

Authorizations:
bearerAuth
query Parameters
parent
string
noparent
boolean
active
boolean
search
string

Responses

Response samples

Content type
application/json
0
0

Find product group by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "description": "string",
  • "active": true,
  • "sells": 0,
  • "color": "string",
  • "customer": {
    },
  • "parent": {
    }
}

Update a product group

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
name
string
active
boolean
description
string
color
string
parent
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "active": true,
  • "description": "string",
  • "color": "string",
  • "parent": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "description": "string",
  • "active": true,
  • "sells": 0,
  • "color": "string",
  • "customer": {
    },
  • "parent": {
    }
}

List product groups (v2)

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
account
string

Account ID (admin only)

active
boolean
search
string
parent
string
noparent
boolean
business
string

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0,
  • "has_more": true,
  • "paginate": {
    }
}

Products

Product management (v1 + v2)

List products

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
productgroup
string
active
boolean
taxRate
number
quantityUnit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
Example: quantityUnit=pcs
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a product

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
nominale
required
number
purchasePrice
number
productgroup
required
string
taxRate
required
number
ean
string
quantityUnit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
color
string
config
Array of strings
active
boolean
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "nominale": 0,
  • "purchasePrice": 0,
  • "productgroup": "string",
  • "taxRate": 0,
  • "ean": "string",
  • "quantityUnit": "pcs",
  • "color": "string",
  • "config": [
    ],
  • "active": true,
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "active": true,
  • "description": "string",
  • "nominale": 0,
  • "purchasePrice": 0,
  • "taxRate": 0,
  • "sells": 0,
  • "ean": "string",
  • "quantityUnit": "pcs",
  • "trackStock": true,
  • "stockCount": 0,
  • "config": [
    ],
  • "productgroup": {
    }
}

Get product count

Authorizations:
bearerAuth
query Parameters
productgroup
string
active
boolean
taxRate
number
customer
string
search
string

Responses

Response samples

Content type
application/json
0
0

Find product by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "active": true,
  • "description": "string",
  • "nominale": 0,
  • "purchasePrice": 0,
  • "taxRate": 0,
  • "sells": 0,
  • "ean": "string",
  • "quantityUnit": "pcs",
  • "trackStock": true,
  • "stockCount": 0,
  • "config": [
    ],
  • "productgroup": {
    }
}

Update a product

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
name
string
nominale
number
purchasePrice
number
ean
string
config
Array of strings
active
boolean
description
string
quantityUnit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
productgroup
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "nominale": 0,
  • "purchasePrice": 0,
  • "ean": "string",
  • "config": [
    ],
  • "active": true,
  • "description": "string",
  • "quantityUnit": "pcs",
  • "productgroup": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "active": true,
  • "description": "string",
  • "nominale": 0,
  • "purchasePrice": 0,
  • "taxRate": 0,
  • "sells": 0,
  • "ean": "string",
  • "quantityUnit": "pcs",
  • "trackStock": true,
  • "stockCount": 0,
  • "config": [
    ],
  • "productgroup": {
    }
}

List products (v2)

Returns a paginated list of products with stock info if the stock-management feature is enabled.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
account
string

Account ID (admin only)

active
boolean
search
string
productgroup
string
taxRate
number
quantityUnit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
Example: quantityUnit=pcs

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0,
  • "has_more": true,
  • "paginate": {
    }
}

Payment Methods (v1)

v1 payment method listing

List payment methods

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Customers

Customer management — known as "clients" in v1, renamed to "customers" in v2

List clients

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
firstname
string
lastname
string
email
string
company
string
active
boolean
city
string
country
string
plz
integer
search
string
search_email
string
name_exists
boolean

Find clients where both first- and lastname exist

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a client

Authorizations:
bearerAuth
Request Body schema: application/json
firstname
string
lastname
string
uid
string
email
string <email>
company
string
phone
string
prefix
string
birthday
string <date>
comments
string
street
string
plz
string
city
string
country
string

Responses

Request samples

Content type
application/json
{
  • "firstname": "string",
  • "lastname": "string",
  • "uid": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "phone": "string",
  • "prefix": "string",
  • "birthday": "2019-08-24",
  • "comments": "string",
  • "street": "string",
  • "plz": "string",
  • "city": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "phone": "string",
  • "prefix": "string",
  • "uid": "string",
  • "birthday": "2019-08-24",
  • "comments": "string",
  • "address": {
    },
  • "customer": {
    }
}

Get client count

Authorizations:
bearerAuth
query Parameters
firstname
string
lastname
string
email
string
company
string
active
boolean
search
string

Responses

Response samples

Content type
application/json
0
0

Find client by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "phone": "string",
  • "prefix": "string",
  • "uid": "string",
  • "birthday": "2019-08-24",
  • "comments": "string",
  • "address": {
    },
  • "customer": {
    }
}

Update a client

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
active
boolean
firstname
string
lastname
string
email
string <email>
company
string
phone
string
prefix
string
uid
string
birthday
string <date>
comments
string
street
string
plz
integer
city
string
country
string

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "phone": "string",
  • "prefix": "string",
  • "uid": "string",
  • "birthday": "2019-08-24",
  • "comments": "string",
  • "street": "string",
  • "plz": 0,
  • "city": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "active": true,
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "company": "string",
  • "phone": "string",
  • "prefix": "string",
  • "uid": "string",
  • "birthday": "2019-08-24",
  • "comments": "string",
  • "address": {
    },
  • "customer": {
    }
}

List customers

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
account
string

Account ID (admin only)

search
string
active
boolean
tag_ids
string

Filter to customers carrying ALL of these tag ids. Pass a comma-separated list (e.g. tag_ids=id1,id2) or repeat the param (tag_ids=id1&tag_ids=id2).

revenue_min
number >= 0

Only customers whose lifetime revenue (in eurocent) is ≥ this value.

receipt_count_min
integer >= 0

Only customers with at least this many receipts (frequent buyers).

inactive_months
integer >= 1

Only customers whose last purchase is older than this many months. Customers who never purchased are excluded (use never_purchased for those).

never_purchased
boolean

When true, only customers with no (net) purchases.

top_revenue_percent
number [ 1 .. 100 ]

Only the top N% of the filtered population by lifetime revenue (1–100). The threshold is computed within the population matching the other filters.

sort_by
string
Default: "last_receipt"
Enum: "last_receipt" "revenue"

Field to sort by. Defaults to last_receipt.

sort_order
string
Default: "desc"
Enum: "asc" "desc"

Sort direction. Defaults to desc.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "count": 0,
  • "has_more": true,
  • "paginate": {
    }
}

Export customers as CSV

Exports customers matching the same filters as the list endpoint (account, search, active, tag_ids, and the segmentation filters) as a CSV file.

Authorizations:
bearerAuth
query Parameters
account
string

Account ID (admin only)

search
string
active
boolean
tag_ids
string

Filter to customers carrying ALL of these tag ids. Pass a comma-separated list (e.g. tag_ids=id1,id2) or repeat the param (tag_ids=id1&tag_ids=id2).

revenue_min
number >= 0

Only customers whose lifetime revenue (in eurocent) is ≥ this value.

receipt_count_min
integer >= 0

Only customers with at least this many receipts (frequent buyers).

inactive_months
integer >= 1

Only customers whose last purchase is older than this many months. Customers who never purchased are excluded (use never_purchased for those).

never_purchased
boolean

When true, only customers with no (net) purchases.

top_revenue_percent
number [ 1 .. 100 ]

Only the top N% of the filtered population by lifetime revenue (1–100).

Responses

Get customer by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "email": "user@example.com",
  • "active": true,
  • "company": "string",
  • "prefix": "string",
  • "phone": "string",
  • "address": {
    },
  • "birthday": "2019-08-24",
  • "receipt_count": 0,
  • "last_receipt": "2019-08-24T14:15:22Z",
  • "revenue": 0,
  • "tags": [
    ]
}

Tags

Customer tags — account-scoped labels, assignable to one or many customers

List account tags

Lists all tags of the account, for reuse and as a filter source.

Authorizations:
bearerAuth
query Parameters
account
string

Account ID (admin only)

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ]
}

Create a tag

Creates a tag for the account. Idempotent — returns the existing tag if a tag with the same name (case-insensitive) already exists.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
color
string
account
string

Account ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": "string",
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "color": "string"
}

Delete a tag

Deletes the tag and removes it from every customer in the account.

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
account
string

Account ID (admin only)

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Assign tags to a customer

Adds one or more tags to a single customer.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
tag_ids
required
Array of strings non-empty
account
string

Account ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "tag_ids": [
    ],
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "matched_count": 0,
  • "modified_count": 0
}

Remove tags from a customer

Removes one or more tags from a single customer.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
tag_ids
required
Array of strings non-empty
account
string

Account ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "tag_ids": [
    ],
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "matched_count": 0,
  • "modified_count": 0
}

Bulk assign tags

Adds one or more tags to one or more customers.

Authorizations:
bearerAuth
Request Body schema: application/json
required
customer_ids
required
Array of strings non-empty
tag_ids
required
Array of strings non-empty
account
string

Account ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "customer_ids": [
    ],
  • "tag_ids": [
    ],
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "matched_count": 0,
  • "modified_count": 0
}

Bulk remove tags

Removes one or more tags from one or more customers.

Authorizations:
bearerAuth
Request Body schema: application/json
required
customer_ids
required
Array of strings non-empty
tag_ids
required
Array of strings non-empty
account
string

Account ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "customer_ids": [
    ],
  • "tag_ids": [
    ],
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "matched_count": 0,
  • "modified_count": 0
}

Receipts (v2)

v2 receipt management

List receipts

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
search_serial
string
number
string
from
string <date>
until
string <date>
type
string
product_id
string
user_id
string

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "has_more": true,
  • "rows": [
    ],
  • "paginate": {
    }
}

Create a receipt

Creates a new receipt. When creating an ST (cancellation) receipt that references an original receipt with SumUp payments, the system will automatically attempt to refund all succeeded SumUp payment transactions.

Authorizations:
bearerAuth
Request Body schema: application/json
required
type
required
string
Enum: "RE" "ST" "KV"

RE=Invoice, ST=Cancellation (auto-refunds SumUp payments), KV=Cost estimation

client_id
string or null
required
object (ReceiptPaymentInput)
object (ReceiptDiscount)
required
Array of objects (ReceiptItemInput)
description
string
cancelled_receipt_id
string or null
object or null

Responses

Request samples

Content type
application/json
{
  • "type": "RE",
  • "client_id": "string",
  • "payment": {
    },
  • "discount": {
    },
  • "items": [
    ],
  • "description": "string",
  • "cancelled_receipt_id": "string",
  • "cost_estimation": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "number": "RE_00000001",
  • "date": "string",
  • "description": "string",
  • "is_demo": true,
  • "rksv_id": 0,
  • "net": 0,
  • "gross": 0,
  • "type": {
    },
  • "created_by": {
    },
  • "discount": {
    },
  • "extras": {
    },
  • "payment": {
    },
  • "security": {
    },
  • "customer": {
    },
  • "invoicing_company": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "cost_estimation": {
    },
  • "cancelled_receipt": {
    }
}

Get receipt by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
output
string
Default: "JSON"
Enum: "JSON" "HTML"

Response format: JSON or HTML

format
integer
Default: 58
Enum: 58 80

Receipt width in mm (58 or 80)

Responses

Response samples

Content type
{
  • "id": "string",
  • "number": "RE_00000001",
  • "date": "string",
  • "description": "string",
  • "is_demo": true,
  • "rksv_id": 0,
  • "net": 0,
  • "gross": 0,
  • "type": {
    },
  • "created_by": {
    },
  • "discount": {
    },
  • "extras": {
    },
  • "payment": {
    },
  • "security": {
    },
  • "customer": {
    },
  • "invoicing_company": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "cost_estimation": {
    },
  • "cancelled_receipt": {
    }
}

Cancel a receipt

Creates a cancellation (ST) receipt. Supports two modes:

  1. Automatic Refund (no payments body): mirrors original payments with negative amounts and auto-refunds via SumUp.
  2. Manual Refund (provide payments array): uses specified methods, skips SumUp auto-refund.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

The ID of the receipt to cancel

Request Body schema: application/json
required
Array of objects (CancellationPayment)

Omit for automatic refund. Provide for manual refund.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "id": "string",
  • "number": "RE_00000001",
  • "date": "string",
  • "description": "string",
  • "is_demo": true,
  • "rksv_id": 0,
  • "net": 0,
  • "gross": 0,
  • "type": {
    },
  • "created_by": {
    },
  • "discount": {
    },
  • "extras": {
    },
  • "payment": {
    },
  • "security": {
    },
  • "customer": {
    },
  • "invoicing_company": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "cost_estimation": {
    },
  • "cancelled_receipt": {
    }
}

List differential tax items

Returns receipt items that have a purchase price (aw) set, used for differential taxation reporting.

Authorizations:
bearerAuth
query Parameters
from
string <date>
until
string <date>
cashdesk
string

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total": {
    }
}

Check receipt validity at BMF (admin only)

Verifies the receipt signature against the Austrian tax authority (BMF).

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "number": "RE_00000001",
  • "date": "string",
  • "description": "string",
  • "is_demo": true,
  • "rksv_id": 0,
  • "net": 0,
  • "gross": 0,
  • "type": {
    },
  • "created_by": {
    },
  • "discount": {
    },
  • "extras": {
    },
  • "payment": {
    },
  • "security": {
    },
  • "customer": {
    },
  • "invoicing_company": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "cost_estimation": {
    },
  • "cancelled_receipt": {
    }
}

Send receipt via email

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "success": true
}

Update a payment on a receipt

Authorizations:
bearerAuth
path Parameters
id
required
string
paymentId
required
string
Example: 507f1f77bcf86cd799439022
Request Body schema: application/json
status
string
info
string or null
deadline
integer or null

Responses

Request samples

Content type
application/json
{
  • "status": "string",
  • "info": "string",
  • "deadline": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "number": "RE_00000001",
  • "date": "string",
  • "description": "string",
  • "is_demo": true,
  • "rksv_id": 0,
  • "net": 0,
  • "gross": 0,
  • "type": {
    },
  • "created_by": {
    },
  • "discount": {
    },
  • "extras": {
    },
  • "payment": {
    },
  • "security": {
    },
  • "customer": {
    },
  • "invoicing_company": {
    },
  • "items": [
    ],
  • "taxes": [
    ],
  • "cost_estimation": {
    },
  • "cancelled_receipt": {
    }
}

Sessions (v2)

Cashdesk session management

List sessions

Authorizations:
bearerAuth
query Parameters
cashdesk
string

Cashdesk ID (required for admin users)

limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
completion
string

Filter by completion status

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_count": 0,
  • "has_more": true
}

Start a cashdesk session

Authorizations:
bearerAuth
Request Body schema: application/json
change_funds
integer

Change funds in eurocent

Responses

Request samples

Content type
application/json
{
  • "change_funds": 1000
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "active": true,
  • "started_at": "string",
  • "change_funds": 0,
  • "ended_at": "string",
  • "report_id": "string",
  • "user": {
    }
}

Get session by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
output
string
Default: "JSON"
Enum: "JSON" "PDF" "FILE_URL"

Response format: JSON, PDF, or FILE_URL

Responses

Response samples

Content type
Example
{
  • "id": "string",
  • "active": true,
  • "started_at": "string",
  • "change_funds": 0,
  • "ended_at": "string",
  • "report_id": "string",
  • "user": {
    }
}

End a cashdesk session

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
end_session
required
boolean

Responses

Request samples

Content type
application/json
{
  • "end_session": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "active": true,
  • "started_at": "string",
  • "change_funds": 0,
  • "ended_at": "string",
  • "report_id": "string",
  • "user": {
    }
}

Orders (v2)

v2 order management

List orders (admin only)

Returns a paginated list of orders sorted by creation date descending. Accessible by admin users only.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
id
string
Example: id=507f1f77bcf86cd799439010

Filter by order ID

cashdesk_id
string
Example: cashdesk_id=507f1f77bcf86cd799439011

Filter by cashdesk ID

account_id
string
Example: account_id=507f1f77bcf86cd799439012

Filter by account (customer) ID

status
string
Enum: "pending" "payment_pending" "completed" "failed" "canceled" "aborted"

Filter by order status

after
string <date-time>
Example: after=2026-01-01T00:00:00.000Z

Return orders created at or after this ISO 8601 datetime

before
string <date-time>
Example: before=2026-12-31T23:59:59.999Z

Return orders created at or before this ISO 8601 datetime

Responses

Response samples

Content type
application/json
{
  • "total": 2,
  • "has_more": false,
  • "paginate": {
    },
  • "rows": [
    ]
}

Create an order

Creates a new order with items and payments. The order is automatically executed and a receipt is generated.

Authorizations:
bearerAuth
Request Body schema: application/json
required
cashdesk_id
string or null

Required for admin users

client_id
string or null
required
Array of objects (OrderItem)
required
Array of objects (OrderPayment)

Responses

Request samples

Content type
application/json
{
  • "cashdesk_id": "507f1f77bcf86cd799439011",
  • "items": [
    ],
  • "payments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Get an order by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Update an order

Update description, client, items, or add payments. Tracks changes in the order changelog.

  • Payments can only be added if the order has no existing payments.
  • When items is provided, it replaces all existing items.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
client_id
string or null
description
string or null
status
string
Enum: "payment_pending" "aborted"
Array of objects (OrderItem)
Array of objects (OrderPayment)

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "description": "string",
  • "status": "payment_pending",
  • "items": [
    ],
  • "payments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Add item to order

Adds a new item. Tracked in changelog with action='item_added'.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
amount
required
number

Quantity with 2 decimal precision

amount_unit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
text
required
string
gross
required
integer

Gross price in eurocent

tax_rate
required
number
product_id
string or null
Array of objects or null (ItemDiscount)
aw
number or null

Purchase price / Wareneinsatz in eurocent

serial
string or null
infos
string or null
has_ura
boolean or null

Responses

Request samples

Content type
application/json
{
  • "amount": 3,
  • "amount_unit": "pcs",
  • "text": "New Product",
  • "gross": 2990,
  • "tax_rate": 20,
  • "product_id": "507f1f77bcf86cd799439013"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Update order item

Updates fields of an existing item. Tracked in changelog with action='item_updated'.

Authorizations:
bearerAuth
path Parameters
id
required
string
itemId
required
string
Example: 507f1f77bcf86cd799439016
Request Body schema: application/json
quantity
number
quantity_unit
string (QuantityUnit)
Enum: "kg" "g" "l" "ml" "m" "mm" "pcs" "km" "min"
name
string
gross
integer
tax_rate
number
product_id
string or null
Array of objects or null (ItemDiscountUpdate)
aw
number or null
serial
string or null
infos
string or null
has_ura
boolean or null

Responses

Request samples

Content type
application/json
{
  • "quantity": 0,
  • "quantity_unit": "pcs",
  • "name": "string",
  • "gross": 0,
  • "tax_rate": 0,
  • "product_id": "string",
  • "discounts": [
    ],
  • "aw": 0,
  • "serial": "string",
  • "infos": "string",
  • "has_ura": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Remove item from order

Removes an item. Tracked in changelog with action='item_removed'.

Authorizations:
bearerAuth
path Parameters
id
required
string
itemId
required
string
Example: 507f1f77bcf86cd799439016

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Add payment to order

Adds a payment. Tracked in changelog with action='payment_added'. Supports SumUp integration.

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
value
required
integer

Payment amount in cents

payment_method_id
required
string
due_days
integer or null
status
string (PaymentStatus)
Enum: "open" "processing" "succeeded" "failed" "aborted" "refunded"
info
string or null
provider
string or null
Value: "sumup"
object (SumUpPaymentData)

Responses

Request samples

Content type
application/json
{
  • "value": 5000,
  • "payment_method_id": "507f1f77bcf86cd799439015",
  • "due_days": 0,
  • "status": "open",
  • "info": "string",
  • "provider": "sumup",
  • "sumup": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Update payment in order

Updates an existing payment. Tracked in changelog with action='payment_updated'.

Authorizations:
bearerAuth
path Parameters
id
required
string
paymentId
required
string
Example: 507f1f77bcf86cd799439022
Request Body schema: application/json
value
integer
due_days
integer
status
string (PaymentStatus)
Enum: "open" "processing" "succeeded" "failed" "aborted" "refunded"
info
string
object (SumUpPaymentData)

Responses

Request samples

Content type
application/json
{
  • "value": 0,
  • "due_days": 0,
  • "status": "open",
  • "info": "string",
  • "sumup": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Resolve stuck SumUp payment

Manually triggers a live SumUp transaction status check for a payment stuck in processing. Finds the SumUp payment on the order, calls the SumUp API, and transitions the payment and order to the resolved state if the transaction is available. If the transaction is not yet visible in SumUp's API, the current order state is returned unchanged (no error).

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "pending",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "receipt": {
    },
  • "customer": {
    },
  • "reader_status": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "change_logs": [
    ],
  • "is_cost_estimation": true,
  • "cost_estimation_valid_days": 0,
  • "text": "string",
  • "discount": {
    }
}

Menu Items (v2)

Navigation menu items

Get menu items for user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "accessableBy": [
    ],
  • "link": "string",
  • "children": [
    ]
}

Cashbooks (v2)

Cashbook management

Get cashbook balance

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "balance": 0,
  • "daily": 0
}

List cashbook entries

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_count": 0,
  • "has_more": true
}

Create a cashbook entry

Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
required
Array of objects
description
string or null
type
string
Enum: "betrieblich" "privat"
invoice
string or null
supplier
string or null

Responses

Request samples

Content type
application/json
{
  • "positions": [
    ],
  • "description": "string",
  • "type": "betrieblich",
  • "invoice": "string",
  • "supplier": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "number": 0,
  • "typ": "betrieblich",
  • "date": "2019-08-24T14:15:22Z",
  • "amount": 0,
  • "description": "string",
  • "balance": 0,
  • "createdBy": {
    }
}

Export cashbook entries

Returns a CSV or PDF export of cashbook entries for the given date range.

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
from
string <date>
until
string <date>
format
string
Default: "csv"
Enum: "csv" "pdf"

Responses

Response samples

Content type
application/json
{
  • "statusCode": 400,
  • "error": "Bad Request",
  • "message": "string"
}

Month Reports (v2)

Month report management

List month reports

Authorizations:
bearerAuth
query Parameters
cashdesk
string

Cashdesk ID (required for admin users)

limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "total_count": 0,
  • "has_more": true
}

Create a month report

Authorizations:
bearerAuth
Request Body schema: application/json
required
month
required
integer [ 1 .. 12 ]
year
required
integer
cashdesk
string

Cashdesk ID (admin only)

Responses

Request samples

Content type
application/json
{
  • "month": 3,
  • "year": 2026,
  • "cashdesk": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "start": "2026-03-01 00:00:00",
  • "end": "2026-03-31 23:59:59",
  • "month": "2026-03",
  • "revenue": 0,
  • "createdAt": "2026-04-01 08:30:00"
}

Get month report by ID

Authorizations:
bearerAuth
path Parameters
id
required
string
query Parameters
output
string
Default: "JSON"
Enum: "JSON" "PDF" "FILE_URL"

Response format: JSON, PDF, or FILE_URL

Responses

Response samples

Content type
Example
{
  • "id": "string",
  • "start": "2026-03-01 00:00:00",
  • "end": "2026-03-31 23:59:59",
  • "month": "2026-03",
  • "revenue": 0,
  • "createdAt": "2026-04-01 08:30:00"
}

Payments (v2)

Payment listing and management

List payments

Returns a paginated, sortable list of payments. Accessible by admins (all cashdesks) and owners (own cashdesk only, automatically scoped).

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
cashdesk
string
Example: cashdesk=507f1f77bcf86cd799439011

Filter by cashdesk ID (admin only — owners are always scoped to their own cashdesk)

provider
string
Value: "sumup"

Filter by payment provider

status
string (PaymentStatus)
Enum: "open" "processing" "succeeded" "failed" "aborted" "refunded"

Filter by payment status

from
string <date-time>
Example: from=2026-01-01T00:00:00.000Z

Filter payments created at or after this ISO 8601 datetime

until
string <date-time>
Example: until=2026-12-31T23:59:59.999Z

Filter payments created at or before this ISO 8601 datetime

sumup_client_transaction_id
string

Filter by SumUp client transaction ID (exact match)

sort_by
string
Default: "created_at"
Enum: "created_at" "updated_at" "amount" "status"
sort_order
string
Default: "desc"
Enum: "asc" "desc"

Responses

Response samples

Content type
application/json
{
  • "total": 42,
  • "rows": [
    ],
  • "has_more": true,
  • "paginate": {
    }
}

Get payment by ID

Returns a single payment with its resolved cashdesk and payment method. If the payment has a SumUp client_transaction_id, the live SumUp transaction is fetched and attached under sumup_transaction. If the fetch fails or no credentials are available, sumup_transaction is null. For SumUp payments, the related webhook event record is also returned under webhook_event (or null if no webhook has been received yet for this transaction).

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "payment": {
    },
  • "sumup_transaction": { },
  • "webhook_event": {
    }
}

Refund a SumUp payment (admin only)

Triggers a refund for a succeeded SumUp payment via the SumUp API and marks the payment as refunded. Requires the payment to have a SumUp transaction_id.

Prerequisites:

  • Payment provider must be sumup
  • Payment must have a sumup.transaction_id (set after the transaction was completed)
  • The account must have valid SumUp credentials stored

Error cases:

  • 400 — not a SumUp payment, missing transaction ID, no credentials, or SumUp rejected the refund (e.g. insufficient funds in the merchant account)
  • 404 — payment not found
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439033",
  • "amount": 1990,
  • "change": 10,
  • "status": "open",
  • "error": "string",
  • "method": {
    },
  • "cashdesk": {
    },
  • "provider": "sumup",
  • "currency": "EUR",
  • "deadline": 0,
  • "info": "string",
  • "sumup": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Files (v2)

Image upload, optimization and thumbnail generation

Upload and optimize an image

Validates the uploaded image (PNG, JPEG or WebP, max 10 MB), optimizes the original and generates the named receipt thumbnail formats, then stores everything on the account's S3 bucket with public-read access.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

The image file (PNG, JPEG or WebP)

account_id
string

Target account ID. Admin only; non-admins always upload to their own account.

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "public_id": "eb3ce6c7-ce7e-4638-a072-e5054706f601",
  • "name": "string",
  • "mime": "image/png",
  • "location": "http://example.com",
  • "thumbs": [],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Receipts (v3)

List receipts (cursor pagination)

Cursor-paginated alternative to GET /v2/receipts. Does not return a total count.

Pages are ordered by (date DESC, _id DESC). To fetch the next page, pass the next_cursor from the previous response in the cursor query parameter. When next_cursor is null, the end of the result set has been reached. Cursors are opaque base64url strings and should not be parsed by the client.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 30
cursor
string

Opaque cursor from a previous response's paginate.next_cursor.

number
string
type
string

Single receipt-type prefix (e.g. RE).

types
string

Comma-separated list of receipt-type prefixes (e.g. RE,ST).

product_id
string
user_id
string
serial
string
serial_search
string

Case-insensitive prefix search on item serial numbers.

from
string <date-time>
until
string <date-time>
origin
string
reversal
boolean
client_id
string
payment_method_id
string
payment_status
string
cashdesk
string

Admin-only. For non-admin users the cashdesk is forced to the caller's.

account
string

Admin-only. For non-admin users the account is forced to the caller's customer.

demo
boolean

Admin-only override. For non-admin users demo is forced to the cashdesk's demo flag.

Responses

Response samples

Content type
application/json
{
  • "rows": [
    ],
  • "paginate": {
    }
}