BizKitHub
DocsAPI ReferenceOrder/api/v1/shop/order/detail
getOrderPublic API v1

/api/v1/shop/order/detail

Public order detail addressed by the 32-char order hash. No API key is required — anyone with the hash (typically an emailed link) can read this. The response is enriched with all context a frontend typically needs to render an order page: prices (base + delivery + payment), payment progress (paidAmount), issued accounting documents (documents), full order timeline (events), tags, customer identity/tax info, order kind and group code, plus both the public and internal notes.

⚠ internalNotice carries organisation-internal context. Never display it to the paying customer — gate its rendering behind an operator role in the consuming frontend.

ordergetApiV1ShopOrderDetail

Parameters

1 query

Query parameters

· 1
hashstringRequired
Exampleexample_hash

Response schema

1 status code documented

200Success
object | object
One of 2:
Variant 1
exist"true"Required

Indicator of whether the order exists.

idstringRequired

Order number for system identification.

Example25000087
hashstringRequired

Unique hash of the order.

ExamplesSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S
localestringRequired

Communication locale code — controls the language of textual data (product names, descriptions, articles, storefront UI, transactional e-mails).

Preferred format: BCP 47 language tag — language[-Script][-REGION]. Use the full tag whenever the script or region matters:

  • en-GB vs. en-US (British vs. American spelling)
  • pt-PT vs. pt-BR (European vs. Brazilian Portuguese)
  • zh-Hans vs. zh-Hant (Simplified vs. Traditional Chinese)
  • sr-Latn vs. sr-Cyrl (Latin vs. Cyrillic Serbian)

Backwards-compatible fallback: the bare two-letter ISO 639-1 code (cs, en, pl, …) is accepted indefinitely — legacy clients that only send the language subtag continue to work unchanged.

Resolution algorithm (server-side): the input is resolved against the supported locale list via the [RFC 4647 Lookup] progressive-fallback strategy — trailing subtags are stripped one by one until a supported locale is found. Example: en-GB-oxendict → en-GB → en (matched). If no subtag combination is supported, the request is rejected.

Currently supported locales: cs, en, fr, it, pl, de, sk, sv, es, zh, ja, uk, da, hu, ro, nl, pt, fi, nb, hr. Region-specific variants (e.g. en-GB, pt-BR) are accepted and resolved to their base language when the exact variant is not registered separately.

Length: 2–35
Examplescsenen-GBpt-BRzh-Hans
kind"commerce" | "registration"Required

Behavioral category of the order (see POST /order/create). commerce for a standard order, registration for a sign-up / event admission. Lets the frontend swap copy and CTAs.

Default: commerceValues: commerceregistration
groupCodestringOptional

Organisation-defined order group code (shop__order_group.code).

Examplebranch-vinohrady
payDateDate | string | string | numberOptional

Date and time of order payment.

One of 4:
Variant 1
Date

Date and time of order payment.

Example2025-01-10T16:19:41.675Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
dueDateDate | string | string | numberOptional

Due date for payment. Used for bank-transfer flows and displayed on the order detail.

One of 4:
Variant 1
Date

Due date for payment. Used for bank-transfer flows and displayed on the order detail.

Example2025-01-24T00:00:00.000Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
statusobjectRequired
labelstringRequired

Public status label defined by the organization and order group.

ExamplePaid
colorstringRequired
Example#1e90ff
onlinePaymentStatusstringOptional
ExamplesCREATEDPAIDCANCELEDPAYMENT_METHOD_CHOSENTIMEOUTEDAUTHORIZEDREFUNDEDPARTIALLY_REFUNDED
onlinePaymentStatusLabelstringOptional
ExamplesPlatba vytvořenaPlatba uhrazenaPlatba zamítnutaPlatební metoda potvrzenaPlatbě vypršela životnostPlatba předautorizovánaPlatba vrácenaPlatba částečně vrácena
onlinePaymentCheckingbooleanRequired

Indicator of whether online payment checking is in progress.

Examplefalse
variableSymbolstringRequired

Unique bank/invoice variable symbol across all organisation.

Example25000087
internalNoticestringOptional

Organisation-internal note attached to the order. Never surfaced to the paying customer — the endpoint is public by hash, so a frontend that shows this must gate it behind an operator role.

ExamplePriorita, dohodnuto s klientem po telefonu.
publicNoticestringOptional

Public note for the order.

ExampleThank you for your order.
insertedDateDate | string | string | numberRequired

Date and time the order was created.

One of 4:
Variant 1
Date

Date and time the order was created.

Example2025-01-10T16:19:40.150Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
updatedDateDate | string | string | numberRequired

Date and time the order was last updated.

One of 4:
Variant 1
Date

Date and time the order was last updated.

Example2025-01-10T16:30:07.172Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
expirationDateDate | string | string | numberOptional

Date and time of order expiration. If this time is reached and the order is not paid, it will be automatically canceled.

One of 4:
Variant 1
Date

Date and time of order expiration. If this time is reached and the order is not paid, it will be automatically canceled.

Example2025-01-12T16:19:40.150Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
priceobjectRequired
priceWithVatnumberRequired

Cena s DPH.

Example0
currencystringRequired

Currency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.

ExamplesCZKEURUSD
priceWithoutVatnumberRequired

Cena bez DPH.

Example0
vatnumberRequired

Výše DPH v procentech.

Example21
currencyLocalestringRequired

Místní označení měny.

ExampleKč
saleobjectRequired
priceWithVatnumberRequired

Cena s DPH.

Example0
currencystringRequired

Currency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.

ExamplesCZKEURUSD
priceWithoutVatnumberRequired

Cena bez DPH.

Example0
vatnumberRequired

Výše DPH v procentech.

Example21
currencyLocalestringRequired

Místní označení měny.

ExampleKč
deliveryPriceobjectOptional
priceWithVatnumberRequired

Cena s DPH.

Example0
currencystringRequired

Currency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.

ExamplesCZKEURUSD
priceWithoutVatnumberRequired

Cena bez DPH.

Example0
vatnumberRequired

Výše DPH v procentech.

Example21
currencyLocalestringRequired

Místní označení měny.

ExampleKč
paymentPriceobjectOptional
priceWithVatnumberRequired

Cena s DPH.

Example0
currencystringRequired

Currency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.

ExamplesCZKEURUSD
priceWithoutVatnumberRequired

Cena bez DPH.

Example0
vatnumberRequired

Výše DPH v procentech.

Example21
currencyLocalestringRequired

Místní označení měny.

ExampleKč
paidAmountobjectRequired

Screen-friendly summary of the paid / refunded / remaining amounts.

totalReceivednumberRequired

Cumulative amount already received.

Example1200
refundednumberRequired

Total amount refunded to the customer.

Example0
remainingnumberRequired

Remaining amount to be paid (order price − totalReceived, clamped to 0).

Example0
customerobjectOptional
emailstringOptional

Contact email address.

The system validates the input as a standard email address and automatically applies normalization and canonicalization.

All API responses return the normalized form, and each email address is unique per organisation within the system.

Phone-only contacts: Since 2026-06-10 a contact may exist without an e-mail when it was registered only by phone (e.g. imports of phone-only records). Responses that expose such contacts use API_EMAIL_NULLABLE instead, where this field can be null. Endpoints that accept e-mail as input still require a valid value here — phone-only creation goes through admin-only import / BFF flows.

Examplejan@barasek.com
phonestringOptional

Customer phone number.

Example+420 777123456
firstNamestringOptional

Customer first name.

ExampleJan
lastNamestringOptional

Customer last name.

ExampleBarášek
companyNamestringOptional

Name of the customer's company.

ExampleCompany Ltd.
icstringOptional

Company registration number (IČO).

Example12345678
dicstringOptional

Tax identification number (DIČ).

ExampleCZ12345678
premiumbooleanRequired

Indicator of whether the customer is premium.

Examplefalse
itemsobject[]Required
Each array item:
idstringRequired

Order item ID.

ExamplesSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S_4186
isStornobooleanRequired

Indicator of whether the item is canceled.

Examplefalse
labelstringRequired

Order item description as HTML.

ExampleGymRoom reservation
countnumberRequired

Number of items.

Example1
priceobjectRequired
priceWithVatnumberRequired

Cena s DPH.

Example0
currencystringRequired

Currency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.

ExamplesCZKEURUSD
priceWithoutVatnumberRequired

Cena bez DPH.

Example0
vatnumberRequired

Výše DPH v procentech.

Example21
currencyLocalestringRequired

Místní označení měny.

ExampleKč
unitstringRequired

Item units.

Exampleks
vatnumberOptional
creditAmountnumberRequired

Credit value of the item.

Example0
productCodestringOptional
productNamestringOptional
productMainImageUrlstringOptional
Examplehttps://storage.xhp.cz/...
variantCodestringOptional
variantNamestringOptional
eventCalendarCodestringOptional
eventCodestringOptional
eventTitlestringOptional
branchstringOptional

Slug of the branch (pobočka) this line item was attributed to.

Examplegymroom-plzen
vouchersobject[]Required

Vouchers redeemed on this order. Their monetary effect (if any) is already reflected in items as a negative-priced row; this field is the canonical audit list of the codes themselves.

Each array item:
codestringRequired

Voucher code that was redeemed on the order.

ExampleSUMMER-15
type"fixed" | "percentage" | "free-credit" | "free-product"Required

Voucher type. fixed / percentage discount the order total (visible as a negative line item); free-credit grants credits to the customer account; free-product grants a product line item.

Default: fixedValues: fixedpercentagefree-creditfree-product
valuestringRequired

Type-dependent payload value. For fixed the discount amount in order currency, for percentage the percentage rate, for free-credit the credit amount.

Examples150103000
isOrderSingletonbooleanRequired

Whether this voucher cannot be combined with other vouchers on the same order.

Examplefalse
currencystringRequired
ExampleCZK
tagsobjectRequired
documentsobject[]Required

All files attached to the order (shop__order_file) — accounting documents (invoices, receipts, proformas), calendar events (.ics), delivery notes and arbitrary operator uploads. Each row carries the download URL and blob metadata; accounting rows additionally carry invoice metadata (type, sequenceNumber, issueDate, dueDate, paidDate, total, currency).

Each array item:
idstringRequired

Blob token — URL-safe stable identifier of the underlying storage object.

ExampleNa60Mbk8LwJIGxsns1JK3TnSE268qVa1
labelstringRequired

Human-friendly label from shop__order_file.label; falls back to the blob filename.

Examplereceipt-26000001.pdf
filenamestringRequired
Examplereceipt_26000001.pdf
downloadUrlstringRequired

Direct download link resolved via resolveBlobList (storage-slug scoped).

Examplehttps://storage.xhp.cz/org-slug/receipt/2026-01/26000001_....pdf
sizenumberRequired

File size in bytes.

Example52771
contentTypestringRequired
Examplesapplication/pdftext/calendar
insertedDateDate | string | string | numberRequired

When the file was attached to the order.

One of 4:
Variant 1
Date

When the file was attached to the order.

Example2026-06-10T08:03:21.571Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
typestringOptional

Accounting document type (shop__invoice_type.type). Present only when this file is a rendered invoice / receipt / proforma; absent for arbitrary attachments (e.g. calendar .ics).

Examplesinvoicereceiptproforma
sequenceNumberstringOptional

Organisation-scoped invoice sequence number. Present only for accounting documents.

Example2025-000123
issueDateDate | string | string | numberOptional
One of 4:
Variant 1
Date
Example2025-01-10T16:19:41.675Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
dueDateDate | string | string | numberOptional
One of 4:
Variant 1
Date
Example2025-01-24T00:00:00.000Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
paidDateDate | string | string | numberOptional
One of 4:
Variant 1
Date
Example2025-01-12T09:00:00.000Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
totalnumberOptional
Example1210
currencystringOptional
ExampleCZK
eventsobject[]Required

Chronological order timeline (status transitions, payment attempts, bank matches, issued documents). Internal-only rows are stripped — safe to render as a public activity feed.

Each array item:
type"statusHistory" | "onlinePayment" | "bankTransaction" | "accountingDocument"Required

Timeline event kind (status flip, gateway callback, bank match, document issued).

Default: statusHistoryValues: statusHistoryonlinePaymentbankTransactionaccountingDocument
labelstringRequired
ExampleOrder marked as paid
descriptionstringOptional
ExampleManual credit — cash on delivery.
dateDate | string | string | numberRequired
One of 4:
Variant 1
Date
Example2025-01-11T12:04:00.000Z
Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
color"primary" | "error" | "info" | "success"Optional
Default: primaryValues: primaryerrorinfosuccess
linksobjectRequired
onlinePaymentLinkstringOptional

Link to online payment of the order.

Examplehttps://bizkithub.com/order/pay?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S
returnUrlstringOptional

URL to which the customer is redirected after successful payment.

Examplehttps://gymroom.cz/eshop/dekujeme-eshop
Variant 2
exist"false"Required

Response example

application/json
{
  "exist": true,
  "id": "25000087",
  "hash": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
  "locale": "cs",
  "kind": "commerce",
  "groupCode": "branch-vinohrady",
  "payDate": "2025-01-10T16:19:41.675Z",
  "dueDate": "2025-01-24T00:00:00.000Z",
  "status": {
    "label": "Paid",
    "color": "#1e90ff",
    "onlinePaymentStatus": "CREATED",
    "onlinePaymentStatusLabel": "Platba vytvořena",
    "onlinePaymentChecking": false
  },
  "variableSymbol": "25000087",
  "internalNotice": "Priorita, dohodnuto s klientem po telefonu.",
  "publicNotice": "Thank you for your order.",
  "insertedDate": "2025-01-10T16:19:40.150Z",
  "updatedDate": "2025-01-10T16:30:07.172Z",
  "expirationDate": "2025-01-12T16:19:40.150Z",
  "price": {
    "priceWithVat": 0,
    "currency": "CZK",
    "priceWithoutVat": 0,
    "vat": 21,
    "currencyLocale": "Kč"
  },
  "sale": {
    "priceWithVat": 0,
    "currency": "CZK",
    "priceWithoutVat": 0,
    "vat": 21,
    "currencyLocale": "Kč"
  },
  "deliveryPrice": {
    "priceWithVat": 0,
    "currency": "CZK",
    "priceWithoutVat": 0,
    "vat": 21,
    "currencyLocale": "Kč"
  },
  "paymentPrice": {
    "priceWithVat": 0,
    "currency": "CZK",
    "priceWithoutVat": 0,
    "vat": 21,
    "currencyLocale": "Kč"
  },
  "paidAmount": {
    "totalReceived": 1200,
    "refunded": 0,
    "remaining": 0
  },
  "customer": {
    "email": "jan@barasek.com",
    "phone": "+420 777123456",
    "firstName": "Jan",
    "lastName": "Barášek",
    "companyName": "Company Ltd.",
    "ic": "12345678",
    "dic": "CZ12345678",
    "premium": false
  },
  "items": [
    {
      "id": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S_4186",
      "isStorno": false,
      "label": "GymRoom reservation",
      "count": 1,
      "price": {
        "priceWithVat": 0,
        "currency": "CZK",
        "priceWithoutVat": 0,
        "vat": 21,
        "currencyLocale": "Kč"
      },
      "unit": "ks",
      "vat": 0,
      "creditAmount": 0,
      "productCode": "example_productCode",
      "productName": "example_productName",
      "productMainImageUrl": "https://storage.xhp.cz/...",
      "variantCode": "example_variantCode",
      "variantName": "example_variantName",
      "eventCalendarCode": "example_eventCalendarCode",
      "eventCode": "example_eventCode",
      "eventTitle": "example_eventTitle",
      "branch": "gymroom-plzen"
    }
  ],
  "vouchers": [
    {
      "code": "SUMMER-15",
      "type": "fixed",
      "value": "150",
      "isOrderSingleton": false,
      "currency": "CZK"
    }
  ],
  "tags": {},
  "documents": [
    {
      "id": "Na60Mbk8LwJIGxsns1JK3TnSE268qVa1",
      "label": "receipt-26000001.pdf",
      "filename": "receipt_26000001.pdf",
      "downloadUrl": "https://storage.xhp.cz/org-slug/receipt/2026-01/26000001_....pdf",
      "size": 52771,
      "contentType": "application/pdf",
      "insertedDate": "2026-06-10T08:03:21.571Z",
      "type": "invoice",
      "sequenceNumber": "2025-000123",
      "issueDate": "2025-01-10T16:19:41.675Z",
      "dueDate": "2025-01-24T00:00:00.000Z",
      "paidDate": "2025-01-12T09:00:00.000Z",
      "total": 1210,
      "currency": "CZK"
    }
  ],
  "events": [
    {
      "type": "statusHistory",
      "label": "Order marked as paid",
      "description": "Manual credit — cash on delivery.",
      "date": "2025-01-11T12:04:00.000Z",
      "color": "primary"
    }
  ],
  "links": {
    "onlinePaymentLink": "https://bizkithub.com/order/pay?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
    "returnUrl": "https://gymroom.cz/eshop/dekujeme-eshop"
  }
}

Request example

GET /api/v1/shop/order/detail

get
curl -X GET "https://api.bizkithub.com/api/v1/shop/order/detail?hash=example_hash" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key