Skip to main content
POST
Create purchase invoice
The invoice, its lines, the discounts of the lines, and, for lines with a stock movement, the Lot/serial number entries, 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, stock movement, Lot/serial number tracking.

Calculations

How amounts and totals are calculated (invoice lines use the same fields as order/despatch lines).
The API does not calculate line amounts, but it checks that they add up (3126); see calculations. The invoice totals, AverageExchangeRate and the header’s withholding fields are filled from the lines. Send UnitPrice excluding VAT.
  • If you send "Next" instead of InvoiceNumber, the number is generated from the ALFATNO series.
  • The customer is given with CustomerCode or, when you only have it, the customer’s tax number (CustomerTaxNumber); one of them is required and CustomerCode wins when both are sent. If more than one customer has the tax number, the request is rejected as ambiguous (0580); send CustomerCode instead.
  • The customer’s address, title, tax number and tax office are copied from the customer and are not accepted in the request.
  • The invoice always records a customer ledger entry (a credit).
  • A successful response is 201 Created; the Location header points to the new invoice.

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. WarehouseName is required for products that track stock; for a Lot- or serial-tracked product the line must also carry Lots or SerialNumbers. ProfileId and InvoiceTypeCode are not used on purchase invoices.

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

InvoiceNumber
null | string
required

Required. Invoice number, unique within the company for this invoice type (sales and purchase return invoices share one numbering). Send "Next" on create to generate it automatically from the relevant number series or, when applicable, from the e-Invoice or e-Archive numbering. At most 20 characters.

Example:

"FAT2026000125"

Date
null | string<date-time>
required

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

Example:

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

Lines
object[]
required

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

CustomerTaxNumber
null | string

Customer's tax number (VKN or TCKN), as an alternative to CustomerCode for finding the customer. Used only when CustomerCode is empty; if more than one customer has this tax number, send CustomerCode instead.

Example:

null

DocumentNumber
null | string

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

Description
null | string

Description. At most 1000 characters.

CustomerCode
null | string

Customer code (the customer's CustomerCode from GET /api/v1/customers). When creating, send CustomerCode or CustomerTaxNumber; one of them is required, and if both are sent CustomerCode is used. The invoice's address, title and tax fields are copied from the customer at the moment it is saved and are not accepted in the request.

Example:

"C-0001"

DueDays
integer<int32>

Payment term in days. Cannot be less than 0.

SharingCode
null | string

Sharing code that limits who can see the invoice. 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

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

Consolidated
boolean

Whether the invoice consolidates several despatches/orders. Free-form flag, not validated by the API.

PrintDescription
boolean

Whether the description should be printed on the invoice document.

ApplyWithholding
boolean

Whether withholding (tevkifat) applies: true when a line has a WithholdingCode. Filled from the lines; a value sent in the request is ignored.

WithholdingCode
null | string

The lines' withholding code when every withheld line uses the same code, share numerator and denominator; otherwise empty. Filled from the lines; a value sent in the request is ignored.

WithholdingNumerator
integer<int32>

The lines' common withholding share numerator; 1 when the lines differ or none is withheld. Filled from the lines; a value sent in the request is ignored.

WithholdingDenominator
integer<int32>

The lines' common withholding share denominator; 1 when the lines differ or none is withheld. Filled from the lines; a value sent in the request is ignored.

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

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

ProfileId
null | string

UBL profile ID of the e-document (e.g. "TEMELFATURA", "TICARIFATURA"). Used on sales and purchase return invoices, where it is required when the company uses e-Invoice; ignored on purchase and sales return invoices. When both ProfileId and InvoiceTypeCode are sent, InvoiceTypeCode must be one of the values allowed for this ProfileId.

InvoiceTypeCode
null | string

UBL invoice type code of the e-document (e.g. "SATIS", "IADE"). Used on sales and purchase return invoices, where it is required when the company uses e-Invoice; ignored on purchase and sales return invoices. 'IADE' and 'TEVKIFATIADE' are required on a purchase return invoice and not allowed on a sales invoice. On a sales invoice with 'IHRACKAYITLI', a line with VAT and no VatExemptionCode gets 701.

WithholdingTaxRate
number<double>

Withholding tax rate (stopaj), used for self-employment/producer-receipt style invoices. Stored as sent.

SocialSecurityRate
number<double>

Social security (Bağ-Kur) rate, used for self-employment/producer-receipt style invoices. Stored as sent.

MarketRate
number<double>

Market (borsa) rate, used for producer-receipt style invoices. Stored as sent.

ReturnedInvoiceNumber
null | string

Number of the invoice this one returns goods against (Alış/Satış İade). Free text, not validated against an existing invoice.

ReturnedInvoiceDate
null | string<date>

Date of the invoice this one returns goods against. Date only (yyyy-MM-dd), no time part.

Example:

"2026-10-15"

OrderReferenceNumber
null | string

Reference order number (free text, informational only).

OrderReferenceDate
null | string<date>

Date of the reference order. Date only (yyyy-MM-dd), no time part.

Example:

"2026-10-15"

BranchNumber
null | string

Branch number (informational).

BranchTitle
null | string

Branch title (informational).

BranchAddress
null | string

Branch address (informational).

InvestmentIncentiveDocumentNumber
null | string

Investment incentive certificate number.

InvestmentIncentiveDocumentDate
null | string<date>

Investment incentive certificate date. Date only (yyyy-MM-dd), no time part.

Example:

"2026-10-15"

EnergyPeriodStart
null | string<date-time>

Energy period start date/time, for energy sector invoices.

EnergyPeriodEnd
null | string<date-time>

Energy period end date/time, for energy sector invoices.

DeliveryInfo
null | object

Export delivery information. Stored and returned as sent, not validated.

PaymentMeans
object[]

Payment methods. Stored and returned as sent, not validated.

ReferencedDespatches
object[]

Referenced despatches. Stored and returned as sent, not validated.

CustomerIdentitySchemes
object[]

Customer identity schemes. Stored and returned as sent, not validated.

PublicSectorSpendingUnit
null | object

Public sector (Kamu) payer spending unit. Stored and returned as sent, not validated.

SgkInfo
null | object

SGK (social security) invoice information. Stored and returned as sent, not validated.

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.