Skip to main content
A customer is a company or person that is a buyer, a supplier or both. A customer record consists of main fields and related sub-records (addresses, telephones, bank accounts, …).

Required fields

string
required
Customer code, unique within the company. Send "Next" on create to generate it.
string
required
Customer name.
string
required
Digits only: a 10-digit tax number (VKN) or an 11-digit Turkish national ID number (TCKN).

General fields

Risk

Only RiskAction 2 is enforced by the API; 0 and 1 never block a request. When it is 2, a sales order with a customer movement, a sales invoice and a purchase-return invoice for this customer are rejected if they break the limit (error 6020 for orders, 3028 for invoices). The limit is in the company’s default currency; amounts in other currencies are converted with the document’s exchange rate.
  • RiskControl 1 (current balance): rejected when the customer’s balance (debit minus credit of all customer movements) plus the document’s amount would exceed the limit.
  • RiskControl 2 (sales amount): rejected when the document’s amount alone exceeds the limit; the balance is not considered.

E-invoice

E-invoice labels (mailbox aliases) cannot be sent through the API. Send QueryEInvoiceLabels: true on create to query them from the e-invoice integrator. Details are in the E-invoice labels section below.

Note

The text in Note can be shown on documents with the flags below. If any flag is true, Note is required. Flags that are not sent are treated as false. ShowNoteOnQuote, ShowNoteOnOrder, ShowNoteOnDespatch, ShowNoteOnInvoice

Identity schemes

IdentitySchemes holds additional identifiers based on UBL identity schemes (used in e-documents).
Each SchemeID can be sent at most once and Value cannot be empty. Valid SchemeID values: VKN, TCKN, HIZMETNO, MUSTERINO, TESISATNO, TELEFONNO, DISTRIBUTORNO, TICARETSICILNO, TAPDKNO, BAYINO, ABONENO, SAYACNO, EPDKNO, SUBENO, PASAPORTNO, URETICINO, CIFTCINO, IMALATCINO, DOSYANO, HASTANO, MERSISNO, ARACIKURUMVKN, ARACIKURUMETIKET, GTB_REFNO, GCB_TESCILNO, GTB_FIILI_IHRACAT_TARIHI, ARACKIMLIKNO, PLAKA, SEVKIYATNO

Sub-records

Customer sub-records can be managed in two ways:
  • When creating a customer: with the lists in the POST /customers body, in the same operation as the customer. If any record is invalid, the customer is not created either.
  • Afterwards: with each sub-record’s own endpoints (/customers/{customerId}/addresses and so on). They support list, get, create, update and delete.
Update customer does not change sub-records; use their own endpoints. If the customer is not visible to the user, all sub-record endpoints return 404.
Sub-records can also be fully replaced with PUT or partially updated with PATCH. See Partial update.

Addresses

/customers/{customerId}/addresses FullAddress in responses is the address combined with district, city and country, and is read-only.

Invoice address rules

A customer always has exactly one invoice address.
  • When creating a customer with a single address, that address becomes the invoice address. With several addresses, exactly one must have IsInvoiceAddress: true.
  • When adding an address, the customer’s first address always becomes the invoice address. A new address added with IsInvoiceAddress: true becomes the invoice address and the previous one loses the flag.
  • The flag of the invoice address cannot be removed by an update, and the invoice address cannot be deleted. Mark another address as the invoice address first.

Telephones

/customers/{customerId}/telephones /customers/{customerId}/links

Representatives

/customers/{customerId}/representatives

Bank accounts

/customers/{customerId}/bank-accounts Send either Iban, or Branch together with AccountNumber.

Group memberships

/customers/{customerId}/group-members
  • A customer can be a member of the same group detail only once.
  • Some groups may be defined as mandatory. When creating a customer, at least one detail from every mandatory group must be sent. This is checked only on create, not when a membership is deleted.

Parameters

/customers/{customerId}/parameters In responses, ParameterType is the definition type and Value is the value in that type’s format.

E-invoice labels

E-invoice labels (GİB mailbox aliases) cannot be sent through the API; they are read-only. Send QueryEInvoiceLabels: true when creating a customer to query the labels from the e-invoice integrator by TaxNumber after the customer is saved:
  • Labels found are saved, and the first one is marked as default.
  • If the query fails, the customer is still created; labels stay empty and the response Message says the labels could not be queried. Message also says so when no label is found for the tax number.
Labels are returned in EInvoiceLabels of Get customer.

Example

POST /api/v1/customers

Deleting

Deleting a customer also deletes its addresses, telephones, links, representatives, bank accounts, e-invoice labels, group memberships and parameters in the same operation. Documents such as invoices and orders are not affected; the deleted customer no longer appears in the API.