New order creation

POST

/v2/supplier-order

curl --request POST \
  --url 'https://api-admin.billz.ai/v2/supplier-order?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 '{ "name": "новый заказ", "accepting_date": "2024-12-17", "is_from_file": false, "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a", "supplier_id": "28110831-9bc5-485f-830c-18472f9481b1" }'

• Production

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

• BearerAuth

Parameters

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

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 Body^required

Media typeapplication/json

object

name

required

Empty -> 400 “name is required”

string

shop_id

required

string

supplier_id

required

string

accepting_date

string

payment_date

string

settlement_type

Type of settlement with the supplier: commission — commission, consegnation — consignment (the value is spelled exactly this way), realization — realization. Informational field: the debt to the supplier accrues for the full order amount when the order is sent, regardless of the type.

string

Allowed values: commission consegnation realization

is_from_file

boolean

invoice_number

integer format: int64

comment

string

type

supplier_order or returned

string

returned_supplier_order_id

string

id

Generated by the server

string

external_id

Generated by the server

integer format: int32

company_id

string

created_by

string

allowed_shops

string

Example

{
  "name": "новый заказ",
  "accepting_date": "2024-12-17",
  "is_from_file": false,
  "shop_id": "6f244db4-75d6-4fac-9841-14867d45e36a",
  "supplier_id": "28110831-9bc5-485f-830c-18472f9481b1"
}

Responses

200

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

Media typeapplication/json

One of:

object

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

object

Response of an asynchronous method without the Billz-Response-Channel header — the event has been published.

object

message

Correlation_id of the published event

string format: uuid

object

object

message

Correlation_id, if Billz-Response-Channel: HTTP is not set

string

status_code

integer format: int32

id

Id of the created order

string

error

object

code

string

message

string

data

object

accepted_by

object

id

string

name

string

accepting_date

string

allowed_shops

string

comment

string

company_id

string

created_at

string

created_by

object

id

string

name

string

deleted_at

integer

edit_supplier_id

string

external_id

integer

id

string

invoice_number

integer

is_finished

boolean

is_from_file

boolean

items_count

integer

left_measurement_value

number

name

string

payment_date

string

payments

Array<object>

nullable

object

processed_supply_price

number

retail_price_change_type

string

returned_measurement_value

number

returned_payments

number

returned_supplier_order_id

string

returned_supplier_order_name

string

sale_progress

number

session_id

string

settlement_type

Type of settlement with the supplier: commission — commission, consegnation — consignment, realization — realization; an empty string means the type is not set. Does not affect the debt to the supplier.

string

Allowed values: commission consegnation realization ""

shop

object

id

string

name

string

shop_id

string

status_id

string

supplier

object

balance

number

created_at

string

debt_value

number

deleted_at

integer

external_id

integer

id

string

name

string

orders_frequency

integer

paid_count

integer

phone_numbers

Array<string>

nullable

returned_payments

number

total_order_measurement_value

number

total_paid_amount

number

total_purchase_measurement_value

number

total_purchase_price

number

total_returned_amount

number

unpaid_count

integer

supplier_id

string

to_return_amount

number

total_accepted_measurement_value

number

total_amount_debit

number

total_measurement_value

number

total_measurement_value_to_return

number

total_paid_amount

number

total_price

number

total_retail_price

number

total_returned_amount

number

total_supply_price

number

type

string

correlation_id

string

topic

string

session_id

string

company_id

string

Example

{
  "data": {
    "settlement_type": "commission"
  }
}