BizKitHub
DocsAPI ReferenceOrder/api/v1/shop/order/create
postOrderPublic API v1

/api/v1/shop/order/create

Create a new order. After create a order, please redirect customer to links.orderPageLink.

customer is the payer; issuerCustomer (optional) is the issuer — if omitted, the issuer is the organisation.

orderpostApiV1ShopOrderCreate

Parameters

1 query · JSON body

Query parameters

· 1
apiKeystringRequired

Your 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

ExamplePRODPGrFxpGEtrOZfuWhnoJohUYBXuOE

Request body

application/json
customerobjectRequired

Paying 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.

emailstringRequired

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
namestringOptional
ExampleJan Barášek
firstNamestringOptional
ExampleJan
lastNamestringOptional
ExampleBarášek
phonestringOptional

Contact 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).

Example+420 777123456
companyNamestringOptional
ExampleBizKitHub
companyRegistrationNumberstringOptional
Example05103118
taxIdentificationNumberstringOptional
ExampleCZ9609040727
streetAddressstringOptional
ExampleR. Novotného 1505
citystringOptional
ExampleKladno
cityPartstringOptional
ExampleKročehlavy
stateRegionstringOptional
ExampleStředočeský kraj
postalCodestringOptional
Example272 01
countrystringOptional
ExamplesCZČeská republikaCzechiaCzech
newsletterbooleanOptional
Default: false
primaryLocalestringOptional
Examplecs
groupsstring[]Optional
customerRealIpstringOptional

User IP address used for GEO/IP intelligence.
Accepted formats: IPv4 (e.g. 1.1.1.1), IPv6 (e.g. 2001:4860:4860::8888)
Normalization:

  • ::1, 0.0.0.0, localhost (or empty value) is normalized to 127.0.0.1
  • Invalid values are rejected (the API expects a valid IP string).

If provided, the system can resolve additional context (reverse DNS, geolocation, ASN, proxy/hosting flags) via our internal VikiTron GEO/IP resolver. Learn more

Examples1.1.1.12001:4860:4860::8888
referralIdstringOptional

cuRefNo = customer reference number.

Length: 16–16
Example1cGIHvFoQDGLAbcA
issuerCustomerobjectOptional

Order 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.

emailstringRequired

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
namestringOptional
ExampleJan Barášek
firstNamestringOptional
ExampleJan
lastNamestringOptional
ExampleBarášek
phonestringOptional

Contact 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).

Example+420 777123456
companyNamestringOptional
ExampleBizKitHub
companyRegistrationNumberstringOptional
Example05103118
taxIdentificationNumberstringOptional
ExampleCZ9609040727
streetAddressstringOptional
ExampleR. Novotného 1505
citystringOptional
ExampleKladno
cityPartstringOptional
ExampleKročehlavy
stateRegionstringOptional
ExampleStředočeský kraj
postalCodestringOptional
Example272 01
countrystringOptional
ExamplesCZČeská republikaCzechiaCzech
newsletterbooleanOptional
Default: false
primaryLocalestringOptional
Examplecs
groupsstring[]Optional
customerRealIpstringOptional

User IP address used for GEO/IP intelligence.
Accepted formats: IPv4 (e.g. 1.1.1.1), IPv6 (e.g. 2001:4860:4860::8888)
Normalization:

  • ::1, 0.0.0.0, localhost (or empty value) is normalized to 127.0.0.1
  • Invalid values are rejected (the API expects a valid IP string).

If provided, the system can resolve additional context (reverse DNS, geolocation, ASN, proxy/hosting flags) via our internal VikiTron GEO/IP resolver. Learn more

Examples1.1.1.12001:4860:4860::8888
referralIdstringOptional

cuRefNo = customer reference number.

Length: 16–16
Example1cGIHvFoQDGLAbcA
copyCustomersstring[]Optional

List of alternative e-mails of customers for e-mail copy.

cartIdstringOptional
Exampleb411056d304d9y6mHe2SoMFBL2Apxfnb
itemsobject[]Required
Each array item:
labelstringRequired

Main order items label used in order detail and as invoice line.

ExampleCheese burger
pricenumberOptional

Absolute 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.

vatnumberOptional

Percentage VAT rate.

countnumberOptional

Integer value. Quantity, count, hours, …

salenumberOptional

Absolute value in order-defined currency.

Example10
unitstringOptional
Exampleskshmkg
productCodestringOptional

Link order item to product when product code has been defined.

Exampleburger
variantCodestringOptional

Link order item to product variant when product code AND variant code has been defined.

Examplecheese-burger
eventCodestringOptional

Link order item to calendar event when event code has been defined.

Example2WRp6X5rSqQa321EjHB2mxZz74u74H84
creditAmountnumberOptional

How many credits should be added to customer account when order will be paid?

Example100
specialActionsstring | string[]Optional
One of 2:
Variant 1
string
Examplecreate-voucher:fixed:500
Variant 2
string[]
branchstringOptional

Slug 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.

Examplegymroom-plzen
orderGroupIdstringOptional

Organisation defined order group code.

Examplebranch-vinohrady
kind"commerce" | "registration"Optional

Behavioral 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 will NOT auto-fire mark_as_paid / create_invoice / create_receipt for this order. 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.
Default: commerceValues: commerceregistration
localestringOptional

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
currencystringOptional

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

ExamplesCZKEURUSD
salenumberOptional

Absolute value in order-defined currency.

voucherListstring[]Optional

List of voucher codes to apply to the order.

paymentMethod"credits" | "money"Optional

Payment strategy.

  • credits (default): Uses customer credits first, remaining amount is paid with money.
  • money: Forces full payment with money only; customer credits are ignored.
Default: creditsValues: creditsmoney
deliveryPricenumberOptional

Absolute value in order-defined currency.

Example10
paymentPricenumberOptional

Absolute value in order-defined currency.

Example0
expirationDatestringOptionaldate-time
Example2024-05-01T10:00:00.000Z
dueDatestringOptionaldate-time
Example2024-05-01T10:00:00.000Z
internalNoticestringOptional

Your internal notice for organisation members. Customer should never see this notice.

publicNoticestringOptional

Public notice defined by customer in cart. This notice can be displayed in e-mail and order detail page.

tagsobjectOptional
returnUrlstringOptional
Examplehttps://gymroom.cz/rezervace/dekujeme
notificationUrlstringOptional
formDataobjectOptional
codestringRequired
dataobjectRequired
forceIgnoreNegativeCreditBalancebooleanOptional

Mark the order as paid immediately. The customer can go into negative credit. Payment will not be processed.

Default: false
forceIssueInvoicebooleanOptional
Default: false
assigneeobjectOptional

Nominate 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).

cuRefNostringOptional

Customer 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.

Length: 16–16
ExampleA1b2C3d4E5f6G7h8
emailstringOptional

Contact 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.

Exampleagent@example.com
parentIdstringOptional

Hash of the parent order. The parent order must belong to the same organisation.

Length: 32–32
ExamplesSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S

Response schema

1 status code documented

200Success
orderNumberstringRequired
Example25000087
hashstringRequired
ExamplesSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S
linksobjectRequired
orderPageLinkstringRequired
Examplehttps://bizkithub.com/order?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S
payLinkstringRequired
Examplehttps://bizkithub.com/order/pay?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S

Response example

application/json
{
  "orderNumber": "25000087",
  "hash": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
  "links": {
    "orderPageLink": "https://bizkithub.com/order?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
    "payLink": "https://bizkithub.com/order/pay?hash=sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S"
  }
}

Request example

POST /api/v1/shop/order/create

post
curl -X POST "https://api.bizkithub.com/api/v1/shop/order/create?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "customer": {
    "email": "jan@barasek.com",
    "name": "Jan Barášek",
    "firstName": "Jan",
    "lastName": "Barášek",
    "phone": "+420 777123456",
    "companyName": "BizKitHub",
    "companyRegistrationNumber": "05103118",
    "taxIdentificationNumber": "CZ9609040727",
    "streetAddress": "R. Novotného 1505",
    "city": "Kladno",
    "cityPart": "Kročehlavy",
    "stateRegion": "Středočeský kraj",
    "postalCode": "272 01",
    "country": "CZ",
    "newsletter": false,
    "primaryLocale": "cs",
    "groups": [
      "string"
    ],
    "customerRealIp": "1.1.1.1",
    "referralId": "1cGIHvFoQDGLAbcA"
  },
  "issuerCustomer": {
    "email": "jan@barasek.com",
    "name": "Jan Barášek",
    "firstName": "Jan",
    "lastName": "Barášek",
    "phone": "+420 777123456",
    "companyName": "BizKitHub",
    "companyRegistrationNumber": "05103118",
    "taxIdentificationNumber": "CZ9609040727",
    "streetAddress": "R. Novotného 1505",
    "city": "Kladno",
    "cityPart": "Kročehlavy",
    "stateRegion": "Středočeský kraj",
    "postalCode": "272 01",
    "country": "CZ",
    "newsletter": false,
    "primaryLocale": "cs",
    "groups": [
      "string"
    ],
    "customerRealIp": "1.1.1.1",
    "referralId": "1cGIHvFoQDGLAbcA"
  },
  "copyCustomers": [
    "janbarasek@gmail.com"
  ],
  "cartId": "b411056d304d9y6mHe2SoMFBL2Apxfnb",
  "items": [
    {
      "label": "Cheese burger",
      "price": 0,
      "vat": 0,
      "count": 0,
      "sale": 10,
      "unit": "ks",
      "productCode": "burger",
      "variantCode": "cheese-burger",
      "eventCode": "2WRp6X5rSqQa321EjHB2mxZz74u74H84",
      "creditAmount": 100,
      "specialActions": "create-voucher:fixed:500;add-credit:15",
      "branch": "gymroom-plzen"
    }
  ],
  "orderGroupId": "branch-vinohrady",
  "kind": "commerce",
  "locale": "cs",
  "currency": "CZK",
  "sale": 0,
  "voucherList": [
    "SUMMER-15"
  ],
  "paymentMethod": "credits",
  "deliveryPrice": 10,
  "paymentPrice": 0,
  "expirationDate": "2024-05-01T10:00:00.000Z",
  "dueDate": "2024-05-01T10:00:00.000Z",
  "internalNotice": "example_internalNotice",
  "publicNotice": "example_publicNotice",
  "tags": {},
  "returnUrl": "https://gymroom.cz/rezervace/dekujeme",
  "notificationUrl": "example_notificationUrl",
  "formData": {
    "code": "example_code",
    "data": {}
  },
  "forceIgnoreNegativeCreditBalance": false,
  "forceIssueInvoice": false,
  "assignee": {
    "cuRefNo": "A1b2C3d4E5f6G7h8",
    "email": "agent@example.com"
  },
  "parentId": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S"
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key