Skip to main content
POST
/
orders
Create order
curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientId": 101,
  "items": [
    {
      "quantity": 2,
      "priceListItemId": 501,
      "name": "Consulting",
      "description": "Monthly consulting package",
      "unitPrice": 100,
      "unitId": 1,
      "vatRate": 20,
      "discountType": "percentage",
      "discountValue": 10,
      "discountName": "Loyalty discount"
    }
  ],
  "number": "20260001",
  "quotationId": 601,
  "client": {
    "name": "Acme s.r.o.",
    "type": "company",
    "subjectId": "12345678",
    "taxId": "2020123456",
    "vatId": "SK2020123456",
    "isVatPayer": true,
    "email": "billing@acme.test",
    "street": "Main Street 1",
    "city": "Bratislava",
    "zip": "81101",
    "countryId": 703,
    "hasDeliveryAddress": true,
    "deliveryStreet": "Warehouse Street 5",
    "deliveryCity": "Trnava",
    "deliveryZip": "91701",
    "deliveryCountryId": 703
  },
  "businessCaseId": 701,
  "numericalSeriesId": 12,
  "issueDate": "2026-03-03",
  "discountType": "percentage",
  "discountValue": 10,
  "transferTaxLiability": false,
  "deliveryMethodId": 1,
  "paymentMethodId": 1,
  "currencyId": 1,
  "languageId": 1,
  "note": "Thank you for your order.",
  "textAboveItems": "Thank you for working with us."
}
'
{
  "id": 501,
  "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19",
  "type": "order",
  "number": "20260001",
  "webDokladUrl": "https://app.fintoro.sk/web-doklad/obj/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1",
  "pdfDownloadUrl": "https://app.fintoro.sk/api/public/v1/orders/501/pdf",
  "company": {
    "name": "Fintoro s.r.o.",
    "subjectId": "12345678",
    "legalForm": "Limited liability company",
    "taxId": "2020123456",
    "vatId": "SK2020123456",
    "vatPayerTypeId": 4,
    "country": "Slovakia",
    "city": "Bratislava",
    "street": "Main Street 1",
    "zip": "81101",
    "logo": "https://cdn.fintoro.sk/company/logo.svg",
    "signature": "https://cdn.fintoro.sk/company/signature.png",
    "registrationCourt": "City Court Bratislava III",
    "registrationNumber": "12345/B",
    "email": "support@fintoro.sk",
    "phone": "+421900000000",
    "web": "https://fintoro.sk"
  },
  "clientId": 101,
  "client": {
    "name": "Acme s.r.o.",
    "type": "company",
    "subjectId": "12345678",
    "taxId": "2020123456",
    "vatId": "SK2020123456",
    "isVatPayer": true,
    "email": "billing@acme.test",
    "street": "Main Street 1",
    "city": "Bratislava",
    "zip": "81101",
    "countryId": 703,
    "country": {
      "id": 703,
      "name": "Slovakia",
      "code": "SK",
      "eu": true
    },
    "hasDeliveryAddress": true,
    "deliveryStreet": "Warehouse 9",
    "deliveryCity": "Kosice",
    "deliveryZip": "04001",
    "deliveryCountryId": 703,
    "deliveryCountry": {
      "id": 703,
      "name": "Slovakia",
      "code": "SK",
      "eu": true
    }
  },
  "issueDate": "2026-03-03",
  "businessCaseId": 701,
  "discountType": "percentage",
  "discountValue": 10,
  "transferTaxLiability": false,
  "numericalSeriesId": 12,
  "deliveryMethodId": 1,
  "paymentMethodId": 1,
  "currencyId": 1,
  "languageId": 1,
  "note": "Thank you for your order.",
  "textAboveItems": "Thank you for working with us.",
  "itemsTotal": 200,
  "itemsTotalWithVat": 240,
  "total": 200,
  "totalWithVat": 240,
  "hasVat": true,
  "items": [
    {
      "id": 1,
      "name": "Consulting",
      "description": "Monthly consulting package",
      "unitPrice": 100,
      "unitId": 1,
      "quantity": 2,
      "vatRate": 20,
      "discountName": "Loyalty discount",
      "discountType": "percentage",
      "discountValue": 10,
      "total": 200,
      "totalWithVat": 240
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer token created for a specific company in Integrations → API.

Headers

​
Idempotency-Key
string

Optional request identifier for safe retries. Use a unique value for each create request you want to retry safely.

Example:

"invoice-create-2026-03-03-001"

Body

application/json

Payload used to create an order. The usual happy path is clientId plus items; the backend can resolve many other values automatically. You must send either clientId or the client object.

​
clientId
integer | null
required

ID of an existing client. This is the recommended way to create an order. If you also send the client object, it is used only as a sparse snapshot override for this specific document.

Example:

101

​
items
object[]
required

Order items. This field is always required. Per-item uuid is not part of the request contract; if you send it, the backend ignores it. warehouseAllocations are not supported for orders.

Required array length: 1 - 100 elements

Payload for a single order line item. Three modes are supported: a manual item, priceListItemId + quantity, or priceListItemId with sparse override fields. quantity is always required. If you omit priceListItemId, you must also send name, unitPrice, and vatRate. unitId is optional; when you omit it for a manual item, the backend defaults to unit 1 (piece / Unit::Piece). If you send priceListItemId, the backend can hydrate the name, unit, unit price, and VAT rate from the price list item, and the payload then acts only as a sparse override.

​
number
string | null

Manual order number. If omitted, the backend generates it from the numbering series. If you send number, do not send numericalSeriesId in the same payload.

Required string length: 1 - 20
Example:

"20260001"

​
quotationId
integer | null

Optional ID of the quotation the order is created from. The document must be available in the token scope and must not be linked to another order.

Example:

601

​
client
object

Sparse client payload. With clientId, it only overrides the snapshot stored on this document. Without clientId, the backend uses it to resolve or create the client.

​
businessCaseId
integer | null

Optional business case ID. When sent, it must be available in the token scope and to the client resolved as the final clientId.

Example:

701

​
numericalSeriesId
integer | null

Numbering series ID. If omitted together with number, the primary numbering series for orders is used. If you send numericalSeriesId, do not send manual number in the same payload.

Example:

12

​
issueDate
string<date>

Issue date in Y-m-d format. It must be after 2009-01-01 and before a date one year in the future. If omitted, the current date is used.

Example:

"2026-03-03"

​
discountType
enum<string> | null

Whole-document discount type.

Available options:
percentage,
fixed
Example:

"percentage"

​
discountValue
number<float> | null

Whole-document discount value.

Required range: x >= 0
Example:

10

​
transferTaxLiability
boolean

Reverse-charge flag. If omitted, false is used.

Example:

false

​
deliveryMethodId
integer

Delivery method ID from the delivery method reference table. Resolution priority is payload -> client preference -> company document settings.

Example:

1

​
paymentMethodId
integer

Payment method ID from the payment method reference table. Resolution priority is payload -> client preference -> company document settings.

Example:

1

​
currencyId
integer

Currency ID from the currency reference table. Resolution priority is payload -> client preference -> company document settings.

Example:

1

​
languageId
integer

Language ID from the language reference table. Resolution priority is payload -> client preference -> company document settings.

Example:

1

​
note
string | null

Document note. Resolution priority is payload -> client preference -> company document settings.

Maximum string length: 3000
Example:

"Thank you for your order."

​
textAboveItems
string | null

Text displayed above items. Resolution priority is payload -> client preference -> company document settings.

Maximum string length: 3000
Example:

"Thank you for working with us."

Response

The order was created.

Order.

​
id
integer
Example:

501

​
uuid
string
Example:

"6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19"

​
type
string
Example:

"order"

​
number
string
Example:

"20260001"

​
webDokladUrl
string<uri>

Absolute URL of the public web document for this order.

Example:

"https://app.fintoro.sk/web-doklad/obj/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1"

​
pdfDownloadUrl
string<uri>

Absolute URL of the Fintoro API endpoint that downloads this order PDF as an attachment.

Example:

"https://app.fintoro.sk/api/public/v1/orders/501/pdf"

​
company
object

Supplier snapshot stored directly on this document.

​
clientId
integer

Live ID of the client linked to the order.

Example:

101

​
client
object

Historical client snapshot stored directly on this document.

​
issueDate
string<date>
Example:

"2026-03-03"

​
businessCaseId
integer | null

Optional business case ID. When sent, it must belong to the client selected on the document.

Example:

701

​
discountType
enum<string> | null
Available options:
percentage,
fixed
Example:

"percentage"

​
discountValue
number<float> | null
Example:

10

​
transferTaxLiability
boolean
Example:

false

​
numericalSeriesId
integer | null
Example:

12

​
deliveryMethodId
integer

Delivery method ID from the delivery method reference table.

Example:

1

​
paymentMethodId
integer

Payment method ID from the payment method reference table.

Example:

1

​
currencyId
integer

Currency ID from the currency reference table.

Example:

1

​
languageId
integer

Language ID from the language reference table.

Example:

1

​
note
string | null
Example:

"Thank you for your order."

​
textAboveItems
string | null
Example:

"Thank you for working with us."

​
itemsTotal
number<float>
Example:

200

​
itemsTotalWithVat
number<float>
Example:

240

​
total
number<float>
Example:

200

​
totalWithVat
number<float>
Example:

240

​
hasVat
boolean
Example:

true

​
items
object[]