Skip to content
BILLZ for developers

Single product creation

POST
/v2/product
curl --request POST \
  --url 'https://api-admin.billz.ai/v2/product?Billz-Response-Channel=HTTP' \
  --header 'Authorization: Bearer <token>' \
  --header 'Billz-Response-Channel: HTTP' \
  --header 'Content-Type: application/json' \
  --header 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  --data '{ "barcode": "24409390003634", "category_ids": [], "company_id": "17a36439-d140-454d-aedb-ae1585681db1", "has_expiration_date": false, "images": [], "free_price": false, "is_auto_delivery": true, "is_auto_tax": true, "is_divisible": false, "is_variative": false, "measurement_unit_id": "c5336f71-d684-4e2e-b5bc-307138593543", "name": "from api, shorten 3", "product_type_id": "69e939aa-9b8f-46a9-b605-8b2675475b7b", "retail_price": 11000, "shipments": [ { "has_trigger": false, "measurement_value": 1, "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a", "small_left_measurement_value": 0 } ], "shop_prices": [ { "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a", "retail_price": 11000, "supply_price": 1, "wholesale_price": 0, "min_price": 0, "max_price": 0 }, { "shop_id": "70919136-9481-4c7e-8581-685d750d67a9", "retail_price": 11000, "supply_price": 1, "wholesale_price": 0, "min_price": 0, "max_price": 0 }, { "shop_id": "803b542d-51e5-41ea-9124-51f248536286", "retail_price": 11000, "supply_price": 1, "wholesale_price": 0, "min_price": 0, "max_price": 0 } ], "sku": "JSI-62299", "supplier_ids": [], "supply_price": 1, "variants": [], "is_marked": false }'

Asynchronous method. To receive the result synchronously over HTTP, pass the Billz-Response-Channel: HTTP header — otherwise the response will be 200 {"message": "<correlation_id>"}. Maximum wait is 600 seconds, after which 408 with error.code = TIMEOUT is returned.

Error codes: 400 — input validation error; 404 — object not found; 408 — timed out waiting for the asynchronous result; 401, 403, 429, 500 — shared by all methods. Body formats and semantics: Response codes and errors.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
platform-id
string
default: 7d4a4c38-dd84-4902-b744-0488b80a4c01

Platform identifier. A static value is used for integrations.

Billz-Response-Channel
string
Allowed values: HTTP

HTTP — wait for the event processing result and return it in the HTTP response. Without the header the method returns only the correlation_id of the published event.

Query Parameters

Section titled “Query Parameters”
Billz-Response-Channel
string
Allowed values: HTTP

Same as the Billz-Response-Channel header — for clients that cannot send a custom header. If both are passed, the header applies.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
product_type_id
required

Product type

string
name
required

Name; at most 1000 characters

string
sku
required

SKU; no more than 1000 characters

string
barcode
required

Barcode; at most 1000 characters

string
measurement_unit_id
required
string
shipments
required

Initial stock intake by shops

Array<object>
object
shop_id
string format: uuid
measurement_value
number
small_left_measurement_value
number
has_trigger
boolean
supply_price
number
supplier_id
string format: uuid
shop_prices
required

Prices by shop

Array<object>
object
shop_id
string format: uuid
retail_price
number
supply_price
number
min_supply_price
number
max_supply_price
number
wholesale_price
number
min_price
number
max_price
number
prices_list
from_supply_price
company_id
string
id

Generated by the server

string
additional_barcodes

Additional barcodes

Array<object>
object
barcode
string
description

Description; no more than 10,000 characters

string
brand_id
string
category_ids
Array<string>
supplier_id

Supplier

string
supplier_ids
Array<string>
has_expiration_date
boolean
is_divisible
boolean
is_variative
boolean
supply_price
number format: double
retail_price
number format: double
profit_margin
number format: double
required_modificators_count
integer format: int32
max_modificators_count
integer format: int32
is_auto_tax
boolean
tax_tariff_id
string
delivery_tariff_id
string
is_auto_delivery
boolean
measurement_type

COUNTABLE|UNCOUNTABLE

string
selected_attributes
Array<string>
variants

Variations; if the limit is exceeded — 400

Array<object>
object
images
Array<object>
object
image
string
sequence_number
string
is_main
string
product_custom_fields
Array<object>
object
product_characteristic_id
string
value
string
packages
Array<string>
product_modificators
Array<string>
related_product_ids
Array<string>
set_products

Set contents; if the limit is exceeded — 400

Array<object>
object
stocktaking_id
string
is_marked
boolean
free_price
boolean
scale_plu
integer format: int32
is_scalable

Weighed product

boolean
shop_free_prices
Array<object>
object
shop_id
string
sell_with_free_price
string
billz-response-channel

Value HTTP — synchronous response. Works both as a header and as the query parameter ?Billz-Response-Channel=HTTP

string
Example
{
  "barcode": "24409390003634",
  "category_ids": [],
  "company_id": "17a36439-d140-454d-aedb-ae1585681db1",
  "has_expiration_date": false,
  "images": [],
  "free_price": false,
  "is_auto_delivery": true,
  "is_auto_tax": true,
  "is_divisible": false,
  "is_variative": false,
  "measurement_unit_id": "c5336f71-d684-4e2e-b5bc-307138593543",
  "name": "from api, shorten 3",
  "product_type_id": "69e939aa-9b8f-46a9-b605-8b2675475b7b",
  "retail_price": 11000,
  "shipments": [
    {
      "has_trigger": false,
      "measurement_value": 1,
      "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a",
      "small_left_measurement_value": 0
    }
  ],
  "shop_prices": [
    {
      "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a",
      "retail_price": 11000,
      "supply_price": 1,
      "wholesale_price": 0,
      "min_price": 0,
      "max_price": 0
    },
    {
      "shop_id": "70919136-9481-4c7e-8581-685d750d67a9",
      "retail_price": 11000,
      "supply_price": 1,
      "wholesale_price": 0,
      "min_price": 0,
      "max_price": 0
    },
    {
      "shop_id": "803b542d-51e5-41ea-9124-51f248536286",
      "retail_price": 11000,
      "supply_price": 1,
      "wholesale_price": 0,
      "min_price": 0,
      "max_price": 0
    }
  ],
  "sku": "JSI-62299",
  "supplier_ids": [],
  "supply_price": 1,
  "variants": [],
  "is_marked": false
}

Responses

Section titled “Responses”

200

Section titled “200”

Success. With the Billz-Response-Channel: HTTP header — the asynchronous response envelope, without it — {"message": "<correlation_id>"}.

Media typeapplication/json
One of:

Asynchronous response envelope. Returned when the Billz-Response-Channel: HTTP header is passed. The final HTTP code of the request is taken from the status_code field.

object
session_id

Customer session identifier

string format: uuid
status_code

Event processing status (also the final HTTP response code)

integer
error
object
code

Error code, empty string if there is no error

string
message

Error text, empty string if there is no error

string
correlation_id

Request identifier, matches the ID of the published event

string format: uuid
topic

Response event type, for example <event_type>.success

string
data

Operation result, if the method returns one

object
Examplegenerated
{
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status_code": 1,
  "error": {
    "code": "example",
    "message": "example"
  },
  "correlation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "topic": "example",
  "data": {}
}