How to import orders via the Order API (V1)
Use this guide to send orders into details via a POST request. This article documents the Order API V1.0 (2023) and keeps the V1 behavior.
Note: The endpoint expects a JSON array of orders in the request body. Identifiers can be provided as UUID, barcode, or catalog_no. Barcodes must be unique.
Where to find the endpoint
Go to SETTINGS / SHARING and open the open api box named [JSON Orders Import].
Endpoint & URL format
Base URL:
https://openapi.berlin3.com:10000/orders/json_import/Path format (with credentials):
https://api.berlin3.com:10000/api/orders/json_import/<client_id>/<checksum>
Quick start
- Generate or locate your <client_id> and <checksum> in SETTINGS / SHARING.
- Build your POST request to the URL format above.
- Set header Content-Type: application/json.
- Send a JSON array of order objects in the request body.
Request parameters
| Parameter | Description | In | Expected Value |
|---|---|---|---|
| client_id | Unique client identifier | path | details client_id |
| checksum | API key | path | details open api key |
| params | Array of orders | body | JSON |
Payload schema (field overview)
Each order is an object. The table below lists available fields. Mandatory fields must be present in every order.
| API Field Name | Mandatory / Optional | Data Type | Expected Value | Field Description |
|---|---|---|---|---|
| order_date | Mandatory | string | YYYY-MM-DD | Date of the order. |
| account_id | Mandatory | integer | min e 1 | Internal ID of the account. |
| contra_account_id | Mandatory | integer | Internal ID of the contra account. | |
| invoice_project_id | Mandatory | integer | Internal ID of the invoicing project. | |
| vat_handling | Mandatory | integer | 1, 2, 3 | 1 = excluding VAT, 2 = including VAT, 3 = no VAT. |
| vat_territory | Mandatory | string | Territory for VAT calculation. | |
| vat_rate1 | Mandatory | number | Primary VAT rate. | |
| vat_rate2 | Mandatory | number | Secondary VAT rate. | |
| orderlines | array | Line items of the order (see fields below). | ||
| shipping_type_id | Optional | integer | Internal ID of shipping type. | |
| order_value | Optional | number | Total order value. | |
| uuid / barcode / catalog_no | Optional | string | Item identifiers. Barcodes must be unique. |
cURL example
curl -X POST
"https://api.berlin3.com:10000/api/orders/json_import/<client_id>/<checksum>"
-H "Content-Type: application/json"
-d '[
{
"order_date": "2015-06-01",
"account_id": 167,
"contra_account_id": 2,
"invoice_project_id": 4,
"currency": "EUR",
"order_type": 1,
"vat_handling": 1,
"vat_territory": "EU",
"vat_rate1": 19,
"vat_rate2": 0,
"orderlines": [
{"uuid": "b1862090-469e-4035-a073-9f106d270502", "ppu": 12.50, "order_qty": 1},
{"uuid": "c796d64c-90c6-493f-a8ea-0f244904069b", "ppu": 10.90, "order_qty": 3}
]
}
]'JSON schema (V1)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "import orders",
"description": "import orders from json",
"type": "array",
"items": {
"type": "object",
"required": [
"order_date",
"account_id",
"contra_account_id
