Parameters
1 query · JSON body
Query parameters
· 1apiKeystringRequiredYour BizKitHub API key (passed as GET parameter).
Key format: A 32-character string matching: ^(PROD|DEV_|ROOT)[A-Za-z0-9]{28}$
Prefixes: PROD (production key), DEV_ (individual developer), ROOT (system key with no limits). Learn more
PRODPGrFxpGEtrOZfuWhnoJohUYBXuOERequest body
application/jsoncustomerobjectRequiredPaying customer (payer). This customer pays the order and is used as the primary billing entity. If the specified customer account does not exist, the system will automatically create a new customer and link it to the order.
emailstringRequiredContact 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.
[email protected]namestringOptionalJan BarášekfirstNamestringOptionalJanlastNamestringOptionalBarášekphonestringOptionalContact phone number in international (national) format.
Preferred format: +<country_code> <local_number>
- Leading plus sign (
+) is required - Followed by the country calling code (e.g.
420) - One space after the country code
- Full local number without spaces
Example: +420 777123456
This format ensures unambiguous storage, validation, and compatibility with SMS, calling, and third-party integrations (e.g. Twilio, WhatsApp, CRM systems).
+420 777123456companyNamestringOptionalBizKitHubcompanyRegistrationNumberstringOptional05103118taxIdentificationNumberstringOptionalCZ9609040727streetAddressstringOptionalR. Novotného 1505citystringOptionalKladnocityPartstringOptionalKročehlavystateRegionstringOptionalStředočeský krajpostalCodestringOptional272 01countrystringOptionalCZČeská republikaCzechiaCzechnewsletterbooleanOptionalfalseprimaryLocalestringOptionalcsgroupsstring[]OptionalcustomerRealIpstringOptionalUser IP address used for GEO/IP intelligence.
Accepted formats:
- IPv4 dot-decimal, e.g.
1.1.1.1(4 octets, 0–255, no leading zeros). - IPv6 as defined by RFC 4291 — full
2001:0db8:0000:0000:0000:0000:0000:0001, zero-compressed2001:db8::1, IPv4-mapped::ffff:1.2.3.4, or scoped literals. Both upper- and lower-case hex are accepted.
Server-side canonicalization (ipNormalize in core/src/lib/network/ipNormalize.ts):
- Valid IPv4 is passed through verbatim.
- Valid IPv6 is lowercased (RFC 5952 §4.3).
- IPv4-mapped IPv6
::ffff:X.X.X.Xis unwrapped to plain IPv4 (RFC 4291 §2.5.5.2) so1.2.3.4and::ffff:1.2.3.4share onebrj__geo_iprow. - Loopback aliases (
::1,0.0.0.0,localhost, empty string) collapse to127.0.0.1. - Junk values that fail both IPv4 and IPv6 validation are silently rejected and replaced with
127.0.0.1(loopback).
On the wire: every response returns the canonicalized form — clients can safely rely on lowercase IPv6 and the plain-IPv4 unwrap when de-duping or joining. Server-originated writers (activity log, session log, ban list) resolve the visitor IP via resolveClientIp / resolveClientIpOrNull — always native IPv6 on Vercel Edge (there is no auto-mapping to ::ffff:X.X.X.X).
Enrichment: the system resolves reverse DNS, geolocation, ASN, mobile/proxy/hosting/Tor flags via our VikiTron GEO/IP resolver for both address families. Learn more
1.1.1.12001:4860:4860::8888referralIdstringOptionalcuRefNo = customer reference number.
1cGIHvFoQDGLAbcAissuerCustomerobjectOptionalOrder issuer. The party that issues the order (e.g. delegated purchase or invoicing). Use only when the order is issued by a specific customer. For common e-shop orders, this field should be omitted — the issuer is the organisation by default. If the specified customer does not exist, the system will automatically create one.
emailstringRequiredContact 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.
[email protected]namestringOptionalJan BarášekfirstNamestringOptionalJanlastNamestringOptionalBarášekphonestringOptionalContact phone number in international (national) format.
Preferred format: +<country_code> <local_number>
- Leading plus sign (
+) is required - Followed by the country calling code (e.g.
420) - One space after the country code
- Full local number without spaces
Example: +420 777123456
This format ensures unambiguous storage, validation, and compatibility with SMS, calling, and third-party integrations (e.g. Twilio, WhatsApp, CRM systems).
+420 777123456companyNamestringOptionalBizKitHubcompanyRegistrationNumberstringOptional05103118taxIdentificationNumberstringOptionalCZ9609040727streetAddressstringOptionalR. Novotného 1505citystringOptionalKladnocityPartstringOptionalKročehlavystateRegionstringOptionalStředočeský krajpostalCodestringOptional272 01countrystringOptionalCZČeská republikaCzechiaCzechnewsletterbooleanOptionalfalseprimaryLocalestringOptionalcsgroupsstring[]OptionalcustomerRealIpstringOptionalUser IP address used for GEO/IP intelligence.
Accepted formats:
- IPv4 dot-decimal, e.g.
1.1.1.1(4 octets, 0–255, no leading zeros). - IPv6 as defined by RFC 4291 — full
2001:0db8:0000:0000:0000:0000:0000:0001, zero-compressed2001:db8::1, IPv4-mapped::ffff:1.2.3.4, or scoped literals. Both upper- and lower-case hex are accepted.
Server-side canonicalization (ipNormalize in core/src/lib/network/ipNormalize.ts):
- Valid IPv4 is passed through verbatim.
- Valid IPv6 is lowercased (RFC 5952 §4.3).
- IPv4-mapped IPv6
::ffff:X.X.X.Xis unwrapped to plain IPv4 (RFC 4291 §2.5.5.2) so1.2.3.4and::ffff:1.2.3.4share onebrj__geo_iprow. - Loopback aliases (
::1,0.0.0.0,localhost, empty string) collapse to127.0.0.1. - Junk values that fail both IPv4 and IPv6 validation are silently rejected and replaced with
127.0.0.1(loopback).
On the wire: every response returns the canonicalized form — clients can safely rely on lowercase IPv6 and the plain-IPv4 unwrap when de-duping or joining. Server-originated writers (activity log, session log, ban list) resolve the visitor IP via resolveClientIp / resolveClientIpOrNull — always native IPv6 on Vercel Edge (there is no auto-mapping to ::ffff:X.X.X.X).
Enrichment: the system resolves reverse DNS, geolocation, ASN, mobile/proxy/hosting/Tor flags via our VikiTron GEO/IP resolver for both address families. Learn more
1.1.1.12001:4860:4860::8888referralIdstringOptionalcuRefNo = customer reference number.
1cGIHvFoQDGLAbcAcopyCustomersstring[]OptionalList of alternative e-mails of customers for e-mail copy.
cartIdstringOptionalb411056d304d9y6mHe2SoMFBL2Apxfnbitemsobject[]RequiredlabelstringRequiredMain order items label used in order detail and as invoice line.
Cheese burgerpricenumberOptionalAbsolute value in order-defined currency.
The item price can be zero. Enter the price as a real value and do not use multiplication. We also accept decimal numbers and handle them safely with a precision of up to two decimal places.
The price value is determined dynamically based on hierarchy. First, the price you set is used. If no price is set, we attempt to retrieve it from the product variant or the core product. If no price is found there either, the price will be zero.
vatnumberOptionalPercentage VAT rate.
countnumberOptionalInteger value. Quantity, count, hours, …
salenumberOptionalAbsolute value in order-defined currency.
10unitstringOptionalkshmkgproductCodestringOptionalLink order item to product when product code has been defined.
burgervariantCodestringOptionalLink order item to product variant when product code AND variant code has been defined.
cheese-burgereventCodestringOptionalLink order item to calendar event when event code has been defined.
2WRp6X5rSqQa321EjHB2mxZz74u74H84creditAmountnumberOptionalHow many credits should be added to customer account when order will be paid?
100specialActionsstring | string[]Optionalcreate-voucher:fixed:500branchstringOptionalSlug of the branch (pobočka) that processed this line item. When set, the item is bound to the branch via shop__order_item.branch_id and any credit grant/debit derived from this item is attributed to the branch (shop__contact_credit.payer_branch_id). Omit to leave the item at organisation level.
gymroom-plzenorderGroupIdstringOptionalOrganisation defined order group code.
branch-vinohradykind"commerce" | "registration"OptionalBehavioral category of the order. Decides which automatic workflows apply:
commerce(default): standard order; invoice/receipt is auto-issued by the status rule engine when the chosen status configures it. The customer receives the standard order-status notification.registration: order represents a sign-up for an event / form-style admission. No tax document is ever auto-issued (manual admin action via BFF can still issue one): the status rule engine skipscreate_invoice/create_receiptfor this order. A status withmark_as_paidstill records the payment date. Whether a zero-total registration is marked as paid right after creation follows the organisation settingorder_zero_total_auto_pay(default: yes; set it tocommerceto keep registrations unpaid) or the explicitpreventAutoPaymentflag. The customer receives a registration-confirmation email when the per-group or kind-specific notification template is configured (falls back to standard order-status template if not). Typically combined with all items priced at 0 and a dedicated organisation-defined order group for pairing.
commerceValues: commerceregistrationlocalestringOptionalCommunication 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-GBvs.en-US(British vs. American spelling)pt-PTvs.pt-BR(European vs. Brazilian Portuguese)zh-Hansvs.zh-Hant(Simplified vs. Traditional Chinese)sr-Latnvs.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.
csenen-GBpt-BRzh-HanscurrencystringOptionalCurrency code. Format: 3-letter uppercase code (e.g. CZK).
Supported values: CZK, EUR, USD.
Order currency (BIZKIT-90): explicit currency → currency of the cart (cartId) → organisation default. When cartId is in another currency than the explicit currency, the cart is re-priced into currency first (manual product / variant currency price, otherwise converted by the organisation rate and rounding). items[].price, deliveryPrice and paymentPrice are always taken as sent, in the order currency; an item without price gets its catalogue price in the order currency. Fixed-amount vouchers are defined in the organisation default currency and converted the same way. Note: items[] and cart items are both added to the order, so do not send the same products in both.
CZKEURUSDsalenumberOptionalAbsolute value in order-defined currency.
voucherListstring[]OptionalList of voucher codes to apply to the order.
paymentMethod"credits" | "money"OptionalPayment strategy.
credits(default): Uses customer credits first, remaining amount is paid with money.money: Forces full payment with money only; customer credits are ignored.
creditsValues: creditsmoneydeliveryPricenumberOptionalAbsolute value in order-defined currency.
10paymentPricenumberOptionalAbsolute value in order-defined currency.
0deliveryCodestringOptionalCode of the shipping method the customer chose (admin → Doprava, shop__order_delivery.code). Stored on the order so a shipment can later be created with the carrier account and service configured on that method. The delivery fee is then computed by BizKitHub (price rules, free-shipping threshold) and added as an order line; deliveryPrice is ignored. An unknown code rejects the order with 404.
zasilkovna-pickupdeliveryPointIdstringOptionalPickup point / parcel shop id returned by the carrier widget (e.g. Zásilkovna point id). Used as the destination when the shipment is created.
12345paymentCodestringOptionalCode of the payment method the customer chose (admin → Platby, shop__order_payment_method.code). Stored on the order; a fee above 0 is added as an order line. An unknown or inactive code rejects the order with 404.
comgateexpirationDatestringOptionaldate-time2024-05-01T10:00:00.000ZdueDatestringOptionaldate-time2024-05-01T10:00:00.000ZinternalNoticestringOptionalYour internal notice for organisation members. Customer should never see this notice.
publicNoticestringOptionalPublic notice defined by customer in cart. This notice can be displayed in e-mail and order detail page.
shipNotBeforestring | nullOptionalPostponed shipping ("odložené odeslání"): do not ship the order before this day. Plain day YYYY-MM-DD (Europe/Prague calendar day) or an ISO date-time (converted to its Prague day). Until the day arrives the order stays out of the fulfillment (packing) queue; on that day it returns to the queue automatically and the organisation is notified. The order status is not changed. Empty / null = ship as usual. Days more than 400 days ahead are rejected with 422.
When omitted and the organisation enabled the AI note reader (settings → Orders), BizKitHub reads publicNotice ("poslat až 10. 12.") and may set the day itself. Change or clear it later with POST /order/set-ship-not-before.
2026-12-15tagsobjectOptionalreturnUrlstringOptionalhttps://gymroom.cz/rezervace/dekujemenotificationUrlstringOptionalformDataobjectOptionalcodestringRequireddataobjectRequiredforceIgnoreNegativeCreditBalancebooleanOptionalMark the order as paid immediately. The customer can go into negative credit. Payment will not be processed.
falseforceIssueInvoicebooleanOptionalfalsepreventAutoPaymentbooleanOptionalControls the automatic "paid" mark for orders whose total is zero or negative after creation (free items, 100 % voucher, fully covered by credit).
- omitted (default): follows the organisation setting
order_zero_total_auto_pay(defaultall= zero-total orders are marked as paid immediately). true: the order stays unpaid (isPaid: false) in its initial status, no tax document is issued and later priced items make it a regular unpaid order. Use for inquiries / deal records whose price is filled in later.false: always auto-pay a zero-total order, regardless of the organisation setting.
Has no effect on orders with a positive total.forceIgnoreNegativeCreditBalance: truestill marks the order as paid unlesspreventAutoPaymentistrue.
trueassigneeobjectOptionalNominate the contact that will handle this order manually (consultation, real-estate, delegated fulfilment).
The assignee is optional and can also be set/updated later from the admin. On payment the assignee receives an internal e-mail notifying them that the order is now paid and ready to be processed.
Provide cuRefNo (16-char customer reference number) OR email. Either resolves to the same contact record — an existing e-mail is reused, an unknown e-mail creates a fresh contact. When neither identifier resolves to a valid contact the field is ignored (no error, no assignee).
cuRefNostringOptionalCustomer reference number (cuRefNo) of the contact that will handle this order manually. When both cuRefNo and email are provided, cuRefNo wins. Unknown or malformed values are silently ignored.
A1b2C3d4E5f6G7h8emailstringOptionalContact e-mail of the manual-handling assignee. If a matching contact exists it is reused, otherwise a new contact is created for this e-mail. Invalid values are silently ignored.
[email protected]parentIdstringOptionalHash of the parent order. The parent order must belong to the same organisation.
sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7ScustomerRealIpstringOptionalUser IP address used for GEO/IP intelligence.
Accepted formats:
- IPv4 dot-decimal, e.g.
1.1.1.1(4 octets, 0–255, no leading zeros). - IPv6 as defined by RFC 4291 — full
2001:0db8:0000:0000:0000:0000:0000:0001, zero-compressed2001:db8::1, IPv4-mapped::ffff:1.2.3.4, or scoped literals. Both upper- and lower-case hex are accepted.
Server-side canonicalization (ipNormalize in core/src/lib/network/ipNormalize.ts):
- Valid IPv4 is passed through verbatim.
- Valid IPv6 is lowercased (RFC 5952 §4.3).
- IPv4-mapped IPv6
::ffff:X.X.X.Xis unwrapped to plain IPv4 (RFC 4291 §2.5.5.2) so1.2.3.4and::ffff:1.2.3.4share onebrj__geo_iprow. - Loopback aliases (
::1,0.0.0.0,localhost, empty string) collapse to127.0.0.1. - Junk values that fail both IPv4 and IPv6 validation are silently rejected and replaced with
127.0.0.1(loopback).
On the wire: every response returns the canonicalized form — clients can safely rely on lowercase IPv6 and the plain-IPv4 unwrap when de-duping or joining. Server-originated writers (activity log, session log, ban list) resolve the visitor IP via resolveClientIp / resolveClientIpOrNull — always native IPv6 on Vercel Edge (there is no auto-mapping to ::ffff:X.X.X.X).
Enrichment: the system resolves reverse DNS, geolocation, ASN, mobile/proxy/hosting/Tor flags via our VikiTron GEO/IP resolver for both address families. Learn more
1.1.1.12001:4860:4860::8888attributionobjectOptionalOptional marketing attribution captured by the shop frontend. BizKitHub does not send it anywhere: it is stored with the order and returned as attribution by GET /order/detail, so your server can enrich its own conversion events (e.g. Meta Conversions API Purchase) after payment.
Values are not strictly validated: empty, oversized or malformed values are silently dropped (fbc/fbp must look like fb.<n>.<ms>.<id>, eventSourceUrl must be http(s)). The order is never rejected because of them.
fbcstringOptionalMeta click ID (_fbc cookie or fb.1.<ms>.<fbclid> built from the landing URL).
fb.1.1730530000000.IwAR2abcfbpstringOptionalMeta browser ID (_fbp cookie).
fb.1.1730530000000.123456789eventSourceUrlstringOptionalAbsolute http(s) URL of the page where the order was placed.
https://gymroom.cz/rezervace/smichovclientUserAgentstringOptionalBrowser user agent.
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)