BizKitHub
DocsInteractive API Docs/api/v1/shop/complaint/create
post

/api/v1/shop/complaint/create

Create a new complaint case.

Use this endpoint to file a complaint, return request, or exchange request from your system. The complaint is automatically created with status new and an initial event is recorded in the timeline.

Typical flow:

  1. Create complaint via this endpoint
  2. Poll status via GET /detail
  3. Optionally update status via POST /set-status

Linking to orders: Provide orderHash to link the complaint to an existing order. The system will validate that the order belongs to your organisation.

Endpoint Info
Base URLapi.bizkithub.com
AuthBearer Token
Methods1
Authentication Required

This endpoint requires a valid API key passed as a query parameter or Bearer token.

Get your API key

Parameters

1 query, 16 body parameters

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

variantCodestringrequired

Organisation-defined complaint variant code.

Each organisation configures its own set of complaint types (e.g. reklamace, vraceni, vymena). The variant must exist and be active in the organisation settings before it can be used.

orderHashstring

Hash of the order this complaint is related to. The order must belong to the same organisation. If provided, the system automatically links the complaint to the order.

Length: 32 - 32
orderNumberstring

Human-readable order number for reference.

Use this field when the order is external or when you want to store the order number without linking to an internal order. If orderHash is provided, this field is optional and will be used as a display label only.

descriptionstringrequired

Customer-provided description and reason for the complaint.

Include as much detail as possible — product condition, circumstances, and what the customer expects. This text is visible to staff and can be shared with the customer.

customerNamestringrequired

Full name of the customer filing the complaint.

emailstring

Customer e-mail address for complaint communication.

Used for sending status updates and resolution notifications to the customer.

phonestring

Customer phone number in international format.

Preferred format: +<country_code> <local_number>
Example: +420 777123456

pricenumber

Total claimed amount in the specified currency.

The claimed amount represents the value the customer is requesting as refund, credit, or compensation. Use decimal precision up to two places.

currencystring

ISO 4217 currency code for the claimed amount. Defaults to organisation currency if omitted.

refundCountrystring

ISO 3166-1 alpha-2 country code for the refund bank account.

refundBankAccountstring

Bank account number for refund transfer.

Use the local bank account format (e.g. 123456789/0100 for CZ) or IBAN.

refundVariableSymbolstring

Variable symbol for the refund bank transfer. Typically the original order number.

branchIdnumber

Branch ID where the product should be sent for inspection or return.

resolutionMethodCodestring

Preferred resolution method code defined by the organisation.

Common values: repair (fix the product), exchange (replace with new), refund (return money), credit (issue store credit). The method must exist in the organisation settings.

dueDatestring

Deadline for complaint resolution. If omitted, the organisation default applies.

Format: date-time
itemsobject[]

List of items being complained about.

Each item can optionally reference an original order item by ID. If the complaint covers the entire order, you can omit this field and set the total claimed amount in the price field instead.

Example Request

JavaScript fetch

const response = await fetch("https://api.bizkithub.com/api/v1/shop/complaint/create?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "variantCode": "reklamace",
    "orderHash": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
    "orderNumber": "25000087",
    "description": "Product arrived damaged, visible scratch on the surface.",
    "customerName": "Jan Novák",
    "email": "jan@barasek.com",
    "phone": "+420 777123456",
    "price": 1500,
    "currency": "CZK",
    "refundCountry": "CZ",
    "refundBankAccount": "123456789/0100",
    "refundVariableSymbol": "25000087",
    "branchId": 0,
    "resolutionMethodCode": "repair",
    "dueDate": "2026-02-15T00:00:00.000Z",
    "items": [
      {
        "orderItemId": 0,
        "label": "Wireless headphones Model X",
        "quantity": 1,
        "price": 2490
      }
    ]
  })
});

const data = await response.json();
console.log(data);
post

Example Response

200Success
{
  "id": "a1b2c3d4e5f6g7h8"
}

cURL

Command line example

curl -X POST "https://api.bizkithub.com/api/v1/shop/complaint/create?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE" \
  -H "Content-Type: application/json" \
  -d '{
  "variantCode": "reklamace",
  "orderHash": "sSO98YxzR4KJiOu66Jn6K3wRwa4FPI7S",
  "orderNumber": "25000087",
  "description": "Product arrived damaged, visible scratch on the surface.",
  "customerName": "Jan Novák",
  "email": "jan@barasek.com",
  "phone": "+420 777123456",
  "price": 1500,
  "currency": "CZK",
  "refundCountry": "CZ",
  "refundBankAccount": "123456789/0100",
  "refundVariableSymbol": "25000087",
  "branchId": 0,
  "resolutionMethodCode": "repair",
  "dueDate": "2026-02-15T00:00:00.000Z",
  "items": [
    {
      "orderItemId": 0,
      "label": "Wireless headphones Model X",
      "quantity": 1,
      "price": 2490
    }
  ]
}'

Need an API key?

All BizKitHub API endpoints require authentication via API key.

Get API Key
Back to API DocumentationAPI Reference