Skip to main content
POST
Create despatch
The despatch, its lines, the discounts of the lines, and the Lot/serial number entries of the lines are written in a single transaction: if any of them is invalid, nothing is saved and all errors are returned in one Message. Line errors start with the line number, for example Line 2: Quantity must be greater than 0.

Field rules

Required fields, customer snapshot, lines, Lot/serial number tracking.

Calculations

How amounts and totals are calculated (despatch lines use the same fields as order/quote lines).
The API does not calculate line amounts, but it checks that they add up (7124); see calculations. The despatch totals and AverageExchangeRate are filled from the lines, the main unit quantity of each line is calculated by the API, and the sum of a line’s Lot/serial number entries must equal its Quantity. Send UnitPrice excluding VAT.
  • If you send "Next" instead of DespatchNumber, the number is generated automatically: the inbound (ALİRSNO) or outbound (SATİRSNO) series, or, for an outbound despatch when the company uses e-Despatch, the company’s e-Despatch numbering.
  • The customer’s address, title, tax number and tax office are copied from CustomerCode and are not accepted in the request.
  • A successful response is 201 Created; the Location header points to the new despatch.

Minimal request

A request with only the required fields; the line amounts add up (the API checks them) and the header totals are filled from the lines. Replace the codes and names with those of your own company. For a Lot- or serial-tracked product the line must also carry Lots or SerialNumbers.

Error codes

Codes this endpoint can return. The general errors that apply to every endpoint (authentication, permissions, request headers, request limits) are not repeated here.

Authorizations

Authorization
string
header
required

Access token obtained from the Noyax auth service with your API key.

Headers

X-UserID
integer<int32>
required

ID of the Noyax user the request is made on behalf of. Written to the audit fields of created, updated and deleted records.

Required range: x >= 1
X-CompanyID
integer<int32>
required

ID of the company. The user must be assigned to this company. All reads and writes are limited to this company.

Required range: x >= 1
X-PeriodID
integer<int32>

ID of the accounting period. Optional; if sent, it is written to created records.

Required range: x >= 1

Body

DespatchType
integer<int32>
required

Required. 2: Inbound despatch (goods receipt), -2: Outbound despatch (dispatch). Cannot be changed after the despatch is created.

Example:

-2

DespatchNumber
null | string
required

Required. Despatch number, unique within the company for the same DespatchType. Send "Next" on create to generate it automatically: from the company's despatch number series for the type, or, for an outbound despatch when the company uses e-Despatch, from the e-Despatch numbering. At most 20 characters.

Example:

"IRS2026000125"

Date
null | string<date-time>
required

Required. Despatch date. The date part is stored as the despatch date; if a time is sent it is stored as the despatch time, otherwise the current time is used.

Example:

"2026-09-21T10:30:00"

CustomerCode
null | string
required

Required. Customer code (the customer's CustomerCode from GET /api/v1/customers). The despatch's address, title and tax fields are copied from the customer at the moment it is saved (the invoice address when the customer has one, otherwise the first address) and are not accepted in the request.

Example:

"C-0001"

Lines
object[]
required

Required, at least one line. The lines cannot be changed after the despatch is created.

DocumentNumber
null | string

Document number (free text). At most 100 characters.

Example:

"2026-15"

ActualDispatchDate
null | string<date>

Actual dispatch date. Date only (yyyy-MM-dd), no time part.

Example:

"2026-10-15"

Description
null | string

Description. At most 1000 characters.

DueDays
integer<int32>

Payment term in days. Cannot be less than 0.

Example:

30

SharingCode
null | string

Sharing code that limits who can see the despatch. Empty means visible to everyone; otherwise it must be one of the user's sharing codes.

ShipmentDefinitionCode
null | string

Shipment definition code from GET /api/v1/definitions/shipment-definitions.

DiscountTotal
number<double>

Total discount: the sum of the lines' DiscountAmount. Filled from the lines; a value sent in the request is ignored.

Example:

100

SubTotal
number<double>

Subtotal: the sum of the lines' AmountExcludingTax. Filled from the lines; a value sent in the request is ignored.

Example:

900

VatTotal
number<double>

Total VAT after withholding: the sum of the lines' VatAmount minus WithholdingTotal. Filled from the lines; a value sent in the request is ignored.

Example:

225

AdditionalTaxTotal
number<double>

Total additional tax: the sum of the lines' additional tax amounts. Filled from the lines; a value sent in the request is ignored.

Example:

225

WithholdingTotal
number<double>

Total withheld VAT: the sum of the lines' WithheldVatAmount. Filled from the lines; a value sent in the request is ignored.

Example:

0

GrandTotal
number<double>

Grand total: the sum of the lines' AmountIncludingTax minus WithholdingTotal. Filled from the lines; a value sent in the request is ignored.

Example:

1350

AverageExchangeRate
number<double>

Weighted average exchange rate: when every line has the same currency, Σ(AmountExcludingTax × ExchangeRate) / Σ AmountExcludingTax; when the lines have different currencies, 1, and the totals are converted to the default currency with each line's ExchangeRate. Filled from the lines; a value sent in the request is ignored.

Example:

1

Response

Created

Success
boolean
required

Whether the operation succeeded.

Example:

true

ResultCode
string
required

"0000" on success. On failure, the code of the first error; all errors are listed in Errors.

Example:

"0000"

Data
object
required

Response data. Null when Success is false.

Message
null | string

Error message when Success is false. Messages of all errors are joined into a single text.