Referenz · v1

Itemoo API for ERP

SKUs, Bestände, Chargen, Bestellungen, Rechnungen und der Produktpass — für ERP, WMS und MES. Ein API-Schlüssel der Marke mit Berechtigungen.

OpenAPI herunterladen (JSON)Änderungsprotokoll

Beschreibungen von Endpunkten und Feldern sind auf Englisch — wie die Codes und Feldnamen der API.

https://itemoo.eu/v1

SKUs, stock levels, batches, orders and product passports of a brand — for ERP, WMS and MES systems.

Authentication. The brand owner creates a key in the panel (Integrations → API keys) and sees it only once. Send it as Authorization: Bearer itm_… (or the X-Api-Key header). Every key has scopes: items, stock, batches, orders, passport. The API is part of plans with the Integrations module; batches work also for a suspended brand.

Limits. 120 calls per minute per IP address; repeated excess blocks the address for 30 minutes (429).

Errors. { statusCode, error, code, params?, message }. Rely on the stable code and params; message is for people and follows the Accept-Language header (without it: English).

SKUs are compared case-insensitively, ignoring leading and trailing spaces.

Compatibility. Within /v1 we only add: new endpoints, optional request fields, response fields and enum values. Ignore fields you don’t know. Every response carries X-Itemoo-Api-Version — the release you are talking to; endpoints being retired send Deprecation and Sunset headers.

Notifications (webhooks). Itemoo sends a POST with JSON { id, event, createdAt, data } for the events below. Header X-Itemoo-Signature: t=<unix>,v1=<HMAC-SHA256(secret, t + "." + body)> — the secret (whsec_…) is in the panel; compare in constant time and reject timestamps older than 5 minutes. Headers X-Itemoo-Event and X-Itemoo-Delivery repeat the event and the delivery id. Reply with 2xx within 10 seconds (redirects are not followed); otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.

Key

Check the key

get/v1/ping

Schlüsselberechtigung: any

Returns the brand and the scopes of the key. Use it to test the connection.

Key scope: any.

Antwort 200 · application/json

object

brandstring | nullPflicht
slugstring | nullPflicht
keystringPflicht
Name of the API key
scopesstring[]Pflicht

Fehler

401	`API_KEY_INVALID` — Missing or invalid API key
403	`BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/ping' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/ping', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/ping');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Items

List of items (SKUs)

get/v1/items

Schlüsselberechtigung: items

Every item for sale: SKU, EAN, catalogue number, name, product, price and stock (null = stock not tracked).

Key scope: items.

Antwort 200 · application/json

Item[]

skustring | nullPflicht
ERP SKU paired with the item; null = not paired yet
eanstring | nullPflicht
catalogNostring | nullPflicht
namestringPflicht
productstringPflicht
Product (page) name
productSkustringPflicht
SKU of the product model that groups the items on one page
pricenumber | nullPflicht
Gross price in the brand currency
stockinteger | nullPflicht
null = stock is not tracked (unlimited sale)
reservedintegerPflicht
Units held by orders not yet acknowledged by the ERP
availablebooleanPflicht

Fehler

401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/items' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/items', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/items');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Pair SKUs with items

put/v1/items

Schlüsselberechtigung: itemsVorschau: dryRun

Assigns ERP SKUs to items recognised by catalogue number or EAN. Unmatched rows do not create new products — they come back in unmatched and land on the “To pair” list in the panel. dryRun: true = preview without saving.

Optional prices per paired SKU: priceGross, priceNet, vatRate — one amount is enough, the other is computed from the rate; two amounts must match the rate within 0.01 (otherwise the row is listed in prices.errors). Prices in the brand additional markets: prices: [{ currency: "EUR", priceGross: 12.5 }] (gross, market currency).

Key scope: items.

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- skustringPflicht
  SKU in your ERP
- catalogNostring
  Catalogue number used to find the item
- eanstring
  EAN/GTIN used to find the item
- namestring
  Name in the ERP — helps pairing by hand
- priceGrossnumber
- priceNetnumber
- vatRate"0" | "5" | "8" | "23" | "exempt" | "outside_scope"
  23 | 8 | 5 | 0 | exempt (VAT-exempt) | outside_scope (outside the scope of VAT)
- pricesobject[]
  Prices in the brand additional markets — never overwritten by exchange-rate recalculation
  Felder
  - currencystringPflicht
  - priceGrossnumber | nullPflicht
    Gross price in the market currency; null returns the market to the recalculated price
dryRunboolean
true = preview, nothing is saved

Antwort 200 · application/json

object

receivedintegerPflicht
alreadyPairedintegerPflicht
pairedobject[]Pflicht
Felder
- skustringPflicht
- itemKeystringPflicht
  Item key in Itemoo
- by"ean" | "catalogNo"Pflicht
unmatchedobject[]Pflicht
Felder
- skustringPflicht
- catalogNostring | nullPflicht
- eanstring | nullPflicht
conflictsobject[]Pflicht
Felder
- skustringPflicht
- reasonstringPflicht
appliedbooleanPflicht
false for dryRun
pricesobjectPflicht
Felder
- updatedintegerPflicht
- errorsobject[]Pflicht
  Felder
  - skustringPflicht
  - reasonstringPflicht

Fehler

400	`ERP_ITEMS_EXPECTED` — Expected { "items": [ … ] } `ERP_MAX_ITEMS` — At most {n} items in one call params: `n` `ITEMS_MAX_20000` — At most 20,000 items at once
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/items' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"KAW-250","ean":"5901234123457"},{"sku":"KAW-1000","catalogNo":"K-1000","priceGross":89.9,"vatRate":"23"}],"dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/items', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "KAW-250",
        "ean": "5901234123457"
      },
      {
        "sku": "KAW-1000",
        "catalogNo": "K-1000",
        "priceGross": 89.9,
        "vatRate": "23"
      }
    ],
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/items');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"KAW-250","ean":"5901234123457"},{"sku":"KAW-1000","catalogNo":"K-1000","priceGross":89.9,"vatRate":"23"}],"dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Stock

Stock levels

put/v1/stock

Schlüsselberechtigung: stock

Overwrites the stock of every SKU (integer ≥ 0), reduced by the units in orders you haven’t acknowledged yet (POST /orders/ack). 0 = item unavailable in the shop. The ERP is the source of truth: the stock you send overwrites ours; shop sales between synchronisations reduce it on their own. SKUs without an item are saved — they take effect once the item is paired in the panel (returned in unknownSku). A row with an invalid quantity is listed in errors; the rest is saved.

Key scope: stock.

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- skustringPflicht
- qtyintegerPflicht

Antwort 200 · application/json

object

savedintegerPflicht
soldOutintegerPflicht
Items that became unavailable (stock 0)
reservedDeductedintegerPflicht
Units subtracted for unacknowledged orders
unknownSkustring[]Pflicht
Saved, but no item has this SKU yet — takes effect once paired in the panel
errorsobject[]Pflicht
Felder
- skustringPflicht
- reasonstringPflicht

Fehler

400	`ERP_ITEMS_EXPECTED` — Expected { "items": [ … ] } `ERP_MAX_ITEMS` — At most {n} items in one call params: `n` `ITEMS_MAX_20000` — At most 20,000 items at once
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/stock' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"KAW-250","qty":12},{"sku":"KAW-1000","qty":0}]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/stock', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "KAW-250",
        "qty": 12
      },
      {
        "sku": "KAW-1000",
        "qty": 0
      }
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/stock');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"KAW-250","qty":12},{"sku":"KAW-1000","qty":0}]}',
]);
$data = json_decode(curl_exec($ch), true);

Batches

Batches (LOT)

put/v1/batches

Schlüsselberechtigung: batchesfunktioniert auch bei gesperrtem Konto

Creates a batch or fills in the dates and quantity of an existing one. The LOT is unique within a product. The batch status (e.g. recall) is changed only by a person in the panel. Works also for a suspended brand (product safety).

Key scope: batches.

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- skustringPflicht
- lotstringPflicht
- producedAtstring
  ISO date (YYYY-MM-DD) or date-time
- expiresAtstring
  ISO date (YYYY-MM-DD) or date-time
- qtyinteger

Antwort 200 · application/json

object

createdintegerPflicht
updatedintegerPflicht
unknownSkustring[]Pflicht
errorsobject[]Pflicht
Felder
- skustringPflicht
- lotstringPflicht
- reasonstringPflicht

Fehler

400	`ERP_ITEMS_EXPECTED` — Expected { "items": [ … ] } `ERP_MAX_ITEMS` — At most {n} items in one call params: `n`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/batches' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"KAW-250","lot":"L2026-10","producedAt":"2026-10-01","expiresAt":"2027-10-01","qty":500}]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/batches', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "KAW-250",
        "lot": "L2026-10",
        "producedAt": "2026-10-01",
        "expiresAt": "2027-10-01",
        "qty": 500
      }
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/batches');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"KAW-250","lot":"L2026-10","producedAt":"2026-10-01","expiresAt":"2027-10-01","qty":500}]}',
]);
$data = json_decode(curl_exec($ch), true);

Orders

Orders to fulfil

get/v1/orders

Schlüsselberechtigung: orders

By default only orders ready to fulfil (paid or cash on delivery). Paging: pass next from the previous response as updatedSince (≥ condition — the last order may come back; recognise it by orderNo). all=true = unpaid ones too.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`updatedSince` query	string (date-time)	Only orders changed at or after this moment — pass "next" from the previous page Beispiel: 2026-10-16T08:30:00.000Z
`limit` query	string	1–200, default 100 Beispiel: 100
`all` query	"true" \| "false"	true = also orders that are not ready to fulfil (unpaid)
`unacknowledged` query	"true" \| "false"	true = only orders not acknowledged by the ERP yet

Antwort 200 · application/json

object

ordersOrder[]Pflicht
Felder · Order
- orderNostringPflicht
- channelstringPflicht
  app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
- externalobject | nullPflicht
  The order in the sales channel; null for brand shop orders
  Felder
  - orderIdstringPflicht
  - marketplacestringPflicht
  - statusstring | nullPflicht
- fulfilledBy"merchant" | "marketplace"Pflicht
  marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
- createdAtstring (date-time)Pflicht
- updatedAtstring (date-time)Pflicht
- paymentobjectPflicht
  Felder
  - status"pending" | "paid" | "failed" | "expired" | "refunded"Pflicht
  - method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"Pflicht
    online = card/BLIK/wallet in the shop; transfer = bank transfer; on_delivery = cash on delivery; on_pickup = paid at pickup; deferred = B2B deferred payment; marketplace = paid in the sales channel
  - paidAtstring (date-time) | nullPflicht
  - approval"pending" | "approved" | "rejected" | nullPflicht
    B2B deferred payment over the limit
- fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"Pflicht
- acknowledgedAtstring (date-time) | nullPflicht
  When the ERP acknowledged the order (POST /orders/ack)
- readyToShipbooleanPflicht
- currencystringPflicht
- totalnumberPflicht
- totalNetnumber | nullPflicht
- customerDiscountnumberPflicht
- buyerTypestringPflicht
  consumer | business
- vatobjectPflicht
  Felder
  - scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"Pflicht
    domestic = seller country VAT; eu-domestic = EU consumer below the OSS threshold (seller country rates); oss = EU consumer, buyer country rates; intra-eu = intra-EU supply to a VAT-registered business, 0%; export = outside the EU, 0%; marketplace-collected = the sales channel collected the buyer country tax; local = VAT of the channel warehouse country
  - collectedByMarketplacenumber | nullPflicht
  - countrystring | nullPflicht
  - exportbooleanPflicht
  - buyerVatIdstring | nullPflicht
  - viesobject | nullPflicht
    Felder
    statusstringPflicht
    requestIdstring | nullPflicht
    checkedAtstring (date-time) | nullPflicht
- shippingCostnumberPflicht
- discountnumberPflicht
- promoCodestring | nullPflicht
- promoDiscountnumberPflicht
- buyerobjectPflicht
  Felder
  - emailstring | nullPflicht
  - namestring | nullPflicht
  - phonestring | nullPflicht
  - personalDataRemovedbooleanPflicht
    true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
- shippingobjectPflicht
  Felder
  - methodstring | nullPflicht
  - addressobjectPflicht
    Felder
    line1string | nullPflicht
    line2string | nullPflicht
    postalstring | nullPflicht
    citystring | nullPflicht
    countrystring | nullPflicht
  - pointobject | nullPflicht
    Pickup point (code, name, address) when chosen
    Felder
- invoiceobject | nullPflicht
  Invoice data entered by the buyer (company, taxId, address)
  Felder
- notestring | nullPflicht
- carrierstring | nullPflicht
- trackingNostring | nullPflicht
- invoiceDocumentobject | nullPflicht
  Invoice attached with PUT /orders/{orderNo}/invoice
  Felder
  - numberstringPflicht
  - ksefNumberstring | nullPflicht
  - issuedAtstring | nullPflicht
  - hasPdfbooleanPflicht
- itemsOrderLine[]Pflicht
  Felder · OrderLine
  - skustring | nullPflicht
  - catalogNostring | nullPflicht
  - namestringPflicht
  - qtynumberPflicht
  - unitPricenumberPflicht
  - discountnumberPflicht
    Promotion and customer discount on the whole line (not per unit)
  - customerDiscountnumberPflicht
    Part of the discount coming from the B2B customer discount
  - vatRatestring | nullPflicht
  - vatCountrystring | nullPflicht
    Country of the VAT rate (OSS: the buyer country)
  - netTotalnumber | nullPflicht
    Net value of the line after discounts
  - giftbooleanPflicht
  - lotsobject[]Pflicht
    Batches the line shipped from
    Felder
    lotstringPflicht
    qtynumberPflicht
  - unitsstring[]Pflicht
    Itemoo QR codes of the shipped units
nextstring (date-time) | nullPflicht
Pass as updatedSince to get the next page; null = no more pages

Fehler

400	`ERP_NOT_A_DATE` — {field}: “{value}” is not a date (YYYY-MM-DD) params: `field`, `value`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/orders?unacknowledged=true&limit=50' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders?unacknowledged=true&limit=50', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders?unacknowledged=true&limit=50');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

updatedSince (query)limit (query)all (query)unacknowledged (query)

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Orders file (CSV or XML)

get/v1/orders/export

Schlüsselberechtigung: orders

For ERPs that import files. By default only orders to fulfil that haven’t been acknowledged yet. ack=true marks the downloaded orders as handed over (like POST /orders/ack).

CSV — UTF-8 with BOM, semicolon-separated, CRLF line ends, amounts with a decimal comma (12,50). One row per order line; the order columns repeat on every line of the order. New columns are only ever added at the end.

XML — UTF-8, one <order> per order inside <orders>, the lines inside <items>; the element tree is listed below. Amounts with a decimal point. Element and attribute names follow the JSON fields of Order.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`format` query	"csv" \| "xml"	csv by default
`ack` query	"true" \| "false"	true = mark the downloaded orders as acknowledged
`unacknowledged` query	"true" \| "false"	true by default
`updatedSince` query	string (date-time)	Beispiel: 2026-10-16T08:30:00.000Z
`all` query	"true" \| "false"

Antwort 200 · text/csv, application/xml

Orders file (attachment).

Spalten der Bestelldatei

1	`order_no`	Order number (orderNo)
2	`created_at`	Order date and time (ISO 8601)
3	`payment_status`	Payment status (payment.status)
4	`payment_method`	Payment method (payment.method)
5	`fulfillment`	Fulfillment status: new \| packing \| shipped \| delivered \| cancelled
6	`buyer_name`	Buyer name
7	`buyer_email`	Buyer email
8	`buyer_phone`	Buyer phone
9	`address_line1`	Shipping address, first line
10	`postal_code`	Postal code
11	`city`	City
12	`country`	Country (ISO 3166-1 alpha-2)
13	`pickup_point`	Pickup point code or name
14	`shipping_method`	Shipping method
15	`shipping_cost`	Shipping cost
16	`discount`	Order discount total (promotion + code + customer discount)
17	`total`	Order total (gross)
18	`invoice_company`	Invoice: company name
19	`invoice_tax_id`	Invoice: tax id
20	`note`	Buyer note
21	`sku`	Line: SKU
22	`catalog_no`	Line: catalogue number
23	`name`	Line: name
24	`qty`	Line: quantity
25	`unit_price`	Line: unit price (gross)
26	`line_discount`	Line: discount on the whole line
27	`gift`	Line: true for a free gift, false otherwise
28	`lots`	Line: shipped batches as "LOT:qty LOT:qty"
29	`vat_rate`	Line: VAT rate (23 \| 8 \| 5 \| 0 \| exempt \| outside_scope)
30	`line_net`	Line: net value after discounts
31	`total_net`	Order total (net)
32	`customer_discount`	Order: B2B customer discount
33	`channel`	Sales channel (app \| site \| marketplace:…)
34	`channel_order_no`	Order number in the sales channel
35	`fulfilled_by`	Who ships: merchant \| marketplace

XML

<orders> Root element
- <order orderNo createdAt channel channelOrderNo? fulfilledBy?>+ One order · orderNo: Order number · createdAt: Order date and time (ISO 8601) · channel: Sales channel (app | site | marketplace:…) · channelOrderNo: Order number in the sales channel · fulfilledBy: "marketplace" when the channel warehouse ships; omitted for merchant
  - <payment status method> Payment · status: payment.status · method: payment.method
  - <fulfillment> Fulfillment status
  - <buyer> Buyer
    - <name>? Name
    - <email>? Email
    - <phone>? Phone
  - <shipping> Delivery
    - <method>? Shipping method
    - <address>? Address, first line
    - <postalCode>? Postal code
    - <city>? City
    - <country>? Country (ISO 3166-1 alpha-2)
    - <pickupPoint>? Pickup point code or name
    - <cost> Shipping cost (decimal point, two decimals)
  - <invoice>? Invoice data — only when the buyer gave a tax id
    - <company>? Company name
    - <taxId> Tax id
  - <note>? Buyer note
  - <discount> Order discount total (promotion + code + customer discount) (decimal point, two decimals)
  - <total> Order total (gross) (decimal point, two decimals)
  - <totalNet>? Order total (net) (decimal point, two decimals)
  - <customerDiscount>? B2B customer discount (decimal point, two decimals)
  - <items> Order lines
    - <item>+ One order line
      - <sku>? SKU
      - <catalogNo>? Catalogue number
      - <name> Name
      - <qty> Quantity
      - <unitPrice> Unit price (gross) (decimal point, two decimals)
      - <discount>? Discount on the whole line (decimal point, two decimals)
      - <gift>? "true" for a free gift; omitted otherwise
      - <vatRate>? VAT rate (23 | 8 | 5 | 0 | exempt | outside_scope)
      - <netTotal>? Net value of the line after discounts (decimal point, two decimals)
      - <lot number qty>* Batch the line shipped from · number: Batch number · qty: Quantity from this batch

Fehler

400	`ERP_NOT_A_DATE` — {field}: “{value}” is not a date (YYYY-MM-DD) params: `field`, `value`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/orders/export?format=csv' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/export?format=csv', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/export?format=csv');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

format (query)ack (query)unacknowledged (query)updatedSince (query)all (query)

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Acknowledge orders received by the ERP

post/v1/orders/ack

Schlüsselberechtigung: orders

Call it right after importing orders. Until acknowledged, an order reserves the goods: we reduce the stock you send by the units in unacknowledged orders, because your stock doesn’t include them yet. After acknowledgement we stop subtracting them. A status change (PUT /orders/{orderNo}) also acknowledges. The reservation expires on its own after 72 h. Repeating the call is safe.

Key scope: orders.

Anfrageinhalt application/json

orderNosstring[]Pflicht

Antwort 200 · application/json

object

acknowledgedintegerPflicht
unknownstring[]Pflicht
Order numbers that do not exist in the brand

Fehler

400	`ERP_ORDERNOS_EXPECTED` — Expected { "orderNos": [ … ] }
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/orders/ack' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"orderNos":["ITM-2026-000123"]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/ack', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "orderNos": [
      "ITM-2026-000123"
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/ack');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"orderNos":["ITM-2026-000123"]}',
]);
$data = json_decode(curl_exec($ch), true);

Batches (LOT) shipped in an order

put/v1/orders/{orderNo}/lots

Schlüsselberechtigung: orders

Which batches the order lines were shipped from — on a batch recall Itemoo notifies exactly these buyers. A line may ship from several batches: several entries with the same sku. A call replaces the batches of the line it concerns. They can also be sent as lots with PUT /orders/{orderNo}.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`orderNo` path · Pflicht	string	Beispiel: ITM-2026-000123

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- skustringPflicht
- lotstringPflicht
- qtyinteger
  The whole line quantity by default

Antwort 200 · application/json

object

savedintegerPflicht
errorsstring[]Pflicht
Rows that were skipped, as human-readable messages

Fehler

400	`ERP_ITEMS_EXPECTED` — Expected { "items": [ … ] } `ERP_MAX_ITEMS` — At most {n} items in one call params: `n` `LOTS_EXPECTED` — Provide batches: [{ sku or idx, lot, qty }] `LOTS_INVALID` — {errors} params: `errors` `LOT_LINE_NOT_FOUND` The order has no item {item} · params: `item` `LOT_NUMBER_MISSING` {label}: batch number missing · params: `label` `LOT_QTY_MIN` {label}: quantity must be ≥ 1 · params: `label` `LOT_QTY_OVER` {label}: batches cover {total} units, but the order has {qty} · params: `label`, `total`, `qty`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`ORDER_NOT_FOUND` — Order not found
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/orders/ITM-2026-000123/lots' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"KAW-250","lot":"L2026-10","qty":2}]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/ITM-2026-000123/lots', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "KAW-250",
        "lot": "L2026-10",
        "qty": 2
      }
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/ITM-2026-000123/lots');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"KAW-250","lot":"L2026-10","qty":2}]}',
]);
$data = json_decode(curl_exec($ch), true);

Units (Itemoo QR codes) shipped in an order

put/v1/orders/{orderNo}/units

Schlüsselberechtigung: orders

Which individual units (Itemoo QR codes) were packed on the order lines — a recall then reaches the buyer of that exact unit. A call replaces the units of the line it concerns; an empty list removes them. A code must belong to the product of the line and must not be sold in another order. Lines without batches get them from the units.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`orderNo` path · Pflicht	string	Beispiel: ITM-2026-000123

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- skustringPflicht
- codesstring[]Pflicht
  Itemoo QR codes; an empty list removes the units

Antwort 200 · application/json

object

savedintegerPflicht
errorsstring[]Pflicht
Rows that were skipped, as human-readable messages

Fehler

400	`ERP_ITEMS_EXPECTED` — Expected { "items": [ … ] } `ERP_MAX_ITEMS` — At most {n} items in one call params: `n` `UNITS_EXPECTED` — Provide the items with unit codes. `UNITS_INVALID` — Units not saved: {errors} params: `errors` `UNIT_LINE_NOT_FOUND` There is no item {item} in the order. · params: `item` `UNIT_QTY_OVER` {label}: more codes ({n}) than units ({qty}). · params: `label`, `n`, `qty` `UNIT_NOT_FOUND` Code {code} is not a unit of this brand. · params: `code` `UNIT_WRONG_PRODUCT` Code {code} belongs to a different product than “{label}”. · params: `code`, `label` `UNIT_TAKEN` Unit {code} is already sold in another order. · params: `code`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`ORDER_NOT_FOUND` — Order not found
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/orders/ITM-2026-000123/units' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"KAW-250","codes":["U7K2M9QX"]}]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/ITM-2026-000123/units', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "KAW-250",
        "codes": [
          "U7K2M9QX"
        ]
      }
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/ITM-2026-000123/units');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"KAW-250","codes":["U7K2M9QX"]}]}',
]);
$data = json_decode(curl_exec($ch), true);

Invoice for an order (number, KSeF, PDF)

put/v1/orders/{orderNo}/invoice

Schlüsselberechtigung: orders

You issue the invoice in the ERP (and send it to KSeF); here you attach it to the order. The customer gets an email with a link to the PDF, and the invoice is on their order page. Sending again replaces the previous one. notifyCustomer: false = no email. Orders from marketplaces get the invoice in the channel instead of an email.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`orderNo` path · Pflicht	string	Beispiel: ITM-2026-000123

Anfrageinhalt application/json

numberstringPflicht
ksefNumberstring
issuedAtstring
ISO date (YYYY-MM-DD) or date-time
pdfBase64string
PDF file as base64 — the whole request is limited to 2 MB, so about 1.4 MB of PDF
notifyCustomerboolean
false = no email to the customer

Antwort 200 · application/json

object

numberstringPflicht
ksefNumberstring | nullPflicht
issuedAtstring (date-time)Pflicht
hasPdfbooleanPflicht
notifiedbooleanPflicht
The customer got an email with the invoice

Fehler

400	`INVOICE_NUMBER_REQUIRED` — Enter the invoice number (letters, digits, / - . _) `KSEF_NUMBER_INVALID` — The KSeF number contains invalid characters `INVOICE_DATE_INVALID` — issuedAt: not a date (YYYY-MM-DD) `INVOICE_PDF_ONLY` — The invoice file must be a PDF `INVOICE_PDF_TOO_LARGE` — The invoice PDF is larger than 5 MB
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`ORDER_NOT_FOUND` — Order not found
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/orders/ITM-2026-000123/invoice' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"number":"FV/2026/10/123","issuedAt":"2026-10-16"}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/ITM-2026-000123/invoice', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "number": "FV/2026/10/123",
    "issuedAt": "2026-10-16"
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/ITM-2026-000123/invoice');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"number":"FV/2026/10/123","issuedAt":"2026-10-16"}',
]);
$data = json_decode(curl_exec($ch), true);

Fulfilment status from the ERP

put/v1/orders/{orderNo}

Schlüsselberechtigung: orders

status: packing | shipped | delivered | cancelled; for shipped also carrier and trackingNo. The customer gets the same emails as for a change in the panel. Repeating the same status changes nothing ("unchanged": true). A paid order can’t be cancelled from the ERP — it needs a refund in the panel. The call also acknowledges the order.

Key scope: orders.

Parameter

Feld	Typ	Beschreibung
`orderNo` path · Pflicht	string	Beispiel: ITM-2026-000123

Anfrageinhalt application/json

status"packing" | "shipped" | "delivered" | "cancelled"Pflicht
carrierstring
trackingNostring
reasonstring
Cancellation reason shown to the customer
lotsobject[]
Batches shipped, like PUT /orders/{orderNo}/lots
Felder
- skustringPflicht
- lotstringPflicht
- qtyinteger
  The whole line quantity by default

Antwort 200 · application/json

OrderAfterStatusChange

orderNostringPflicht
channelstringPflicht
app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
externalobject | nullPflicht
The order in the sales channel; null for brand shop orders
Felder
- orderIdstringPflicht
- marketplacestringPflicht
- statusstring | nullPflicht
fulfilledBy"merchant" | "marketplace"Pflicht
marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
createdAtstring (date-time)Pflicht
updatedAtstring (date-time)Pflicht
paymentobjectPflicht
Felder
- status"pending" | "paid" | "failed" | "expired" | "refunded"Pflicht
- method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"Pflicht
  online = card/BLIK/wallet in the shop; transfer = bank transfer; on_delivery = cash on delivery; on_pickup = paid at pickup; deferred = B2B deferred payment; marketplace = paid in the sales channel
- paidAtstring (date-time) | nullPflicht
- approval"pending" | "approved" | "rejected" | nullPflicht
  B2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"Pflicht
acknowledgedAtstring (date-time) | nullPflicht
When the ERP acknowledged the order (POST /orders/ack)
readyToShipbooleanPflicht
currencystringPflicht
totalnumberPflicht
totalNetnumber | nullPflicht
customerDiscountnumberPflicht
buyerTypestringPflicht
consumer | business
vatobjectPflicht
Felder
- scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"Pflicht
  domestic = seller country VAT; eu-domestic = EU consumer below the OSS threshold (seller country rates); oss = EU consumer, buyer country rates; intra-eu = intra-EU supply to a VAT-registered business, 0%; export = outside the EU, 0%; marketplace-collected = the sales channel collected the buyer country tax; local = VAT of the channel warehouse country
- collectedByMarketplacenumber | nullPflicht
- countrystring | nullPflicht
- exportbooleanPflicht
- buyerVatIdstring | nullPflicht
- viesobject | nullPflicht
  Felder
  - statusstringPflicht
  - requestIdstring | nullPflicht
  - checkedAtstring (date-time) | nullPflicht
shippingCostnumberPflicht
discountnumberPflicht
promoCodestring | nullPflicht
promoDiscountnumberPflicht
buyerobjectPflicht
Felder
- emailstring | nullPflicht
- namestring | nullPflicht
- phonestring | nullPflicht
- personalDataRemovedbooleanPflicht
  true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectPflicht
Felder
- methodstring | nullPflicht
- addressobjectPflicht
  Felder
  - line1string | nullPflicht
  - line2string | nullPflicht
  - postalstring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
- pointobject | nullPflicht
  Pickup point (code, name, address) when chosen
  Felder
invoiceobject | nullPflicht
Invoice data entered by the buyer (company, taxId, address)
Felder
notestring | nullPflicht
carrierstring | nullPflicht
trackingNostring | nullPflicht
invoiceDocumentobject | nullPflicht
Invoice attached with PUT /orders/{orderNo}/invoice
Felder
- numberstringPflicht
- ksefNumberstring | nullPflicht
- issuedAtstring | nullPflicht
- hasPdfbooleanPflicht
itemsOrderLine[]Pflicht
Felder · OrderLine
- skustring | nullPflicht
- catalogNostring | nullPflicht
- namestringPflicht
- qtynumberPflicht
- unitPricenumberPflicht
- discountnumberPflicht
  Promotion and customer discount on the whole line (not per unit)
- customerDiscountnumberPflicht
  Part of the discount coming from the B2B customer discount
- vatRatestring | nullPflicht
- vatCountrystring | nullPflicht
  Country of the VAT rate (OSS: the buyer country)
- netTotalnumber | nullPflicht
  Net value of the line after discounts
- giftbooleanPflicht
- lotsobject[]Pflicht
  Batches the line shipped from
  Felder
  - lotstringPflicht
  - qtynumberPflicht
- unitsstring[]Pflicht
  Itemoo QR codes of the shipped units
unchangedtrue
The same status was sent again — nothing changed, no email

Fehler

400	`ERP_STATUS_INVALID` — status: packing \| shipped \| delivered \| cancelled `ORDER_STATUS_TRANSITION` — Can’t change the status from “{from}” to “{to}” params: `from`, `to` `ORDER_NOT_PAID_YET` — The order hasn’t been paid yet `ORDER_AWAITS_APPROVAL` — The deferred payment is awaiting approval `ORDER_AWAITS_CUSTOMER` — Waiting for the customer’s decision about the missing items `ORDER_AWAITS_FOLLOWUP` — Part of the order is awaiting a follow-up shipment — mark it as delivered once that has been sent `NOTHING_TO_SHIP` — Nothing to ship — all items are cancelled or awaiting a follow-up shipment
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`ORDER_NOT_FOUND` — Order not found
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/orders/ITM-2026-000123' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"status":"shipped","carrier":"InPost","trackingNo":"6200000000000000"}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/orders/ITM-2026-000123', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "status": "shipped",
    "carrier": "InPost",
    "trackingNo": "6200000000000000"
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/orders/ITM-2026-000123');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"status":"shipped","carrier":"InPost","trackingNo":"6200000000000000"}',
]);
$data = json_decode(curl_exec($ch), true);

Passport

Product passport with all access levels

get/v1/passport/{code}

Schlüsselberechtigung: passport

The public data of the published page, model and unit fields with their access level (public | legit | authority), the current unit state (status, SoH, cycles) and the unit history. Recipients outside the brand read GET /q/{code}/passport of the public API with a token issued in the panel.

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`code` path · Pflicht	string	Itemoo code of a unit, batch, variant or product Beispiel: A1B2C3D4

Antwort 200 · application/json

BrandPassport

level"public" | "legit" | "authority"Pflicht
recipientstring
Name of the access grant used
versionPassportVersion | nullPflicht
Felder · PassportVersion
- hashstringPflicht
  SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
- layersobject[]Pflicht
  Felder
  - subject"product" | "variant" | "batch" | "unit"Pflicht
  - versionintegerPflicht
  - hashstringPflicht
- eventsHeadstring | nullPflicht
- atstring (date-time)
  Present for a passport read at a point in time (?at=)
backupobject | nullPflicht
Backup copy of the passport kept by a DPP service provider (Regulation (EU) 2024/1781 Annex III point (l)), when the brand designated one
Felder
- providerstringPflicht
- urlstringPflicht
identityProductIdentityPflicht
Felder · ProductIdentity
- codestringPflicht
  Itemoo code from the QR label
- level"unit" | "batch" | "variant" | "model"Pflicht
- gtinstring | nullPflicht
- skustring | nullPflicht
- variantobject
  Felder
  - labelstringPflicht
  - catalogNostring | nullPflicht
- lotstring | nullPflicht
- serialstring | nullPflicht
- expiresAtstring (date-time) | nullPflicht
- statusstringPflicht
  Batch status: ACTIVE | RECALLED | …
- uniqueProductIdentifierstringPflicht
  Unique product identifier of this code (EN 18219:2026): GS1 Digital Link with the batch and serial number of the code level, or the code address /q/{code} without a GTIN
productProductSummaryPflicht
Felder · ProductSummary
- namestringPflicht
- brandstringPflicht
- category"chemicals" | "cosmetics" | "medical" | "food" | "supplements" | "electronics" | "appliances" | "batteries" | "textiles" | "furniture" | "toys" | "construction" | "other" | nullPflicht
  Regulatory product type — decides the mandatory information: chemicals | cosmetics | medical | food | supplements | electronics | appliances | batteries | textiles | furniture | toys | construction | other
- descriptionstringPflicht
- imagestring
- translationsobject
  Name and description in every language the brand provides (ISO 639-1 code → text); name and description above are in the language of the response
  Felder
  - namemap<string, string>Pflicht
  - descriptionmap<string, string>Pflicht
manufacturerEconomicOperator | nullPflicht
Felder · EconomicOperator
- namestringPflicht
- addressobjectPflicht
  Felder
  - streetstring | nullPflicht
  - postalCodestring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
    ISO 3166-1 alpha-2
- emailstring | nullPflicht
- phonestring | nullPflicht
  Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
- source"company" | "registry"Pflicht
  company = the brand company data; registry = an operator from the company operator register designated in the passport
- tradeNamestring | null
  Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
- identifiersobject[]
  Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
  Felder
  - scheme"gln" | "duns" | "lei" | "vat" | "iso15459"Pflicht
    gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
  - iacstring
    Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
  - valuestringPflicht
- eoristring | null
  EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
responsiblePersonEconomicOperator | nullPflicht
Felder · EconomicOperator
- namestringPflicht
- addressobjectPflicht
  Felder
  - streetstring | nullPflicht
  - postalCodestring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
    ISO 3166-1 alpha-2
- emailstring | nullPflicht
- phonestring | nullPflicht
  Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
- source"company" | "registry"Pflicht
  company = the brand company data; registry = an operator from the company operator register designated in the passport
- tradeNamestring | null
  Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
- identifiersobject[]
  Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
  Felder
  - scheme"gln" | "duns" | "lei" | "vat" | "iso15459"Pflicht
    gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
  - iacstring
    Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
  - valuestringPflicht
- eoristring | null
  EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
importerEconomicOperator | nullPflicht
Felder · EconomicOperator
- namestringPflicht
- addressobjectPflicht
  Felder
  - streetstring | nullPflicht
  - postalCodestring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
    ISO 3166-1 alpha-2
- emailstring | nullPflicht
- phonestring | nullPflicht
  Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
- source"company" | "registry"Pflicht
  company = the brand company data; registry = an operator from the company operator register designated in the passport
- tradeNamestring | null
  Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
- identifiersobject[]
  Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
  Felder
  - scheme"gln" | "duns" | "lei" | "vat" | "iso15459"Pflicht
    gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
  - iacstring
    Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
  - valuestringPflicht
- eoristring | null
  EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
authorisedRepresentativeEconomicOperator | nullPflicht
Felder · EconomicOperator
- namestringPflicht
- addressobjectPflicht
  Felder
  - streetstring | nullPflicht
  - postalCodestring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
    ISO 3166-1 alpha-2
- emailstring | nullPflicht
- phonestring | nullPflicht
  Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
- source"company" | "registry"Pflicht
  company = the brand company data; registry = an operator from the company operator register designated in the passport
- tradeNamestring | null
  Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
- identifiersobject[]
  Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
  Felder
  - scheme"gln" | "duns" | "lei" | "vat" | "iso15459"Pflicht
    gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
  - iacstring
    Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
  - valuestringPflicht
- eoristring | null
  EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
facilityEconomicOperator | nullPflicht
Felder · EconomicOperator
- namestringPflicht
- addressobjectPflicht
  Felder
  - streetstring | nullPflicht
  - postalCodestring | nullPflicht
  - citystring | nullPflicht
  - countrystring | nullPflicht
    ISO 3166-1 alpha-2
- emailstring | nullPflicht
- phonestring | nullPflicht
  Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
- source"company" | "registry"Pflicht
  company = the brand company data; registry = an operator from the company operator register designated in the passport
- tradeNamestring | null
  Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
- identifiersobject[]
  Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
  Felder
  - scheme"gln" | "duns" | "lei" | "vat" | "iso15459"Pflicht
    gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
  - iacstring
    Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
  - valuestringPflicht
- eoristring | null
  EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
languagestringPflicht
publishedbooleanPflicht
recallRecall | nullPflicht
Felder · Recall
- activetruePflicht
- certainbooleanPflicht
  true = this exact code is recalled; false = the batch is unknown and may be affected
- scope"product" | "batch" | "lotRange"Pflicht
  product = the whole product; batch = one batch; lotRange = a range of batch numbers (lotFrom–lotTo)
- reasonstringPflicht
- instructionsstring | nullPflicht
- lotFromstring | nullPflicht
- lotTostring | nullPflicht
- kind"recall" | "notice"
  recall = the product is recalled; notice = safety notice, the product is not withdrawn
factsProvenanceFact[]Pflicht
Felder · ProvenanceFact
- keystring
  Stable English key of a standard fact (origin, materials, battery.capacityAh, chemical.ufi, …); absent for parameters defined by the brand — match on it, not on the translated name
- namestringPflicht
  Fact name in the response language
- valuestringPflicht
- provenanceobject
  Felder
  - sourcestringPflicht
    Document or block the fact comes from
  - versionstring
  - documentUrlstring
  - assertedBystringPflicht
    Brand that published the fact
  - assertedAtstring
documentsDocument[]Pflicht
Felder · Document
- titlestringPflicht
- urlstringPflicht
- kindstringPflicht
  certificate | declaration | repair | dpp | manual | sds | …
- versionstring
- accessstring
  public | legit | authority — present on documents beyond the public level
- docIdstring
  Library document identifier — the same as in { docId } values of document fields
- languagestring
  Language of the file (ISO 639-1 code, e.g. de), set by the brand at the document version; absent — multilingual file or not specified
componentsPassportComponent[]Pflicht
Components with their own passport visible at this level (Regulation (EU) 2024/1781 Art. 2(4); CIRPASS-2 D4.1 recommendation 5)
Felder · PassportComponent
- codestring | nullPflicht
  Itemoo code of the component passport (unit, batch, variant or model — also of another brand)
- uristring | nullPflicht
  Address of a component passport outside Itemoo (DPP URL or GS1 Digital Link)
- urlstringPflicht
  Where to read the component passport
- rolestring | nullPflicht
- nameanyPflicht
- quantitynumber | nullPflicht
- unitstring | nullPflicht
- level"model" | "unit"Pflicht
  model — bill of components of the model; unit — installed in this unit (assembly events)
- sincestring | nullPflicht
  When the component was installed in this unit
lifecycleobjectPflicht
Lifecycle status of the passport: recalled — an active recall covers the code (a safety notice does not); end_of_life — the unit was recycled or became waste; archived — the brand left Itemoo and the passport is kept read-only; closed — the brand closed the passport after the product was placed on the market (the passport shows the state as of the closing date, since). A passport is never deleted: removal is a status (CIRPASS-2 D4.1 recommendation 3); a retired code answers 410
Felder
- status"active" | "recalled" | "end_of_life" | "archived" | "closed"Pflicht
- sincestring (date-time) | nullPflicht
modelobjectPflicht
Model passport fields visible at this level
unitobject | nullPflicht
Felder
- serialstring | nullPflicht
- dataobjectPflicht
- stateobjectPflicht
  Felder
  - statusstring | nullPflicht
    original | repurposed | re-used | remanufactured | waste | recycled (Regulation (EU) 2023/1542 Annex XIII point 4(c); recycled ends the passport). null — not visible at this access level (a battery status is for persons with a legitimate interest only)
  - sohnumber | nullPflicht
    State of health, 0–100 (SoH, or SOCE / remaining capacity when only that is recorded)
  - sohAtstring (date-time) | nullPflicht
  - cyclesnumber | nullPflicht
  - incidentsintegerPflicht
- historyobject[]Pflicht
  Felder
  - kindstringPflicht
  - dataanyPflicht
  - occurredAtstring (date-time)Pflicht
  - sourcestring
- linksobjectPflicht
  Felder
  - predecessorobject | nullPflicht
    Passport before remanufacturing or repurposing (Art. 77(7))
    Felder
    codestringPflicht
    urlstringPflicht
  - successorsobject[]Pflicht
    New passports created from this battery
    Felder
    codestringPflicht
    urlstringPflicht
- custodianobject | nullPflicht
  Operator responsible for the passport of a waste battery after a transfer (producer, PRO or waste management operator — Art. 77(7))
  Felder
  - namestringPflicht
  - rolestringPflicht
  - sincestring (date-time)Pflicht
fieldsobjectPflicht
Editable fields with their access levels, per layer
Felder
- modelmap<string, object>Pflicht
  Felder
  - valueanyPflicht
  - access"public" | "legit" | "authority"Pflicht
- variantmap<string, object> | nullPflicht
  Variant layer (overrides the model)
  Felder
  - valueanyPflicht
  - access"public" | "legit" | "authority"Pflicht
- batchmap<string, object> | nullPflicht
  Batch layer (inherited by units)
  Felder
  - valueanyPflicht
  - access"public" | "legit" | "authority"Pflicht
- unitmap<string, object> | nullPflicht
  Felder
  - valueanyPflicht
  - access"public" | "legit" | "authority"Pflicht
unitMetaobject | nullPflicht
Unit dates: code activation and placing on the market; predecessor passport code
Felder
- statusstringPflicht
- activatedAtstring (date-time) | nullPflicht
- placedOnMarketAtstring (date-time) | nullPflicht
- predecessorCodestring | nullPflicht
versionsany[]Pflicht
Version history of all layers with pseudonymous authors (see the public PassportHistory)
chainmap<string, integer | null>Pflicht
Per layer: number of the first version whose hash does not verify, null = intact

Fehler

401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code
410	`codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand`
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/passport/A1B2C3D4' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/A1B2C3D4', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/A1B2C3D4');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

code

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Passport in JSON-LD with all access levels

get/v1/passport/{code}/dpp.jsonld

Schlüsselberechtigung: passport

The same document as the public GET /q/{code}/dpp.jsonld (Itemoo context https://itemoo.eu/ns/dpp/1.1/context.jsonld, fields mapped to the CIRPASS-2 ontology where the meaning matches), at the authority level: all fields of the brand. READ operation of CIRPASS-2 D4.1 recommendation 3. The EN 18222:2026 life cycle API with the EN 18223:2026 payload is /dpp-api/v1. Only products with a passport (the “Digital product passport” block or a passport obligation) — otherwise 404 PASSPORT_NONE; GET /passport/{code} still returns the data.

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`code` path · Pflicht	string	Itemoo code of a unit, batch, variant or product Beispiel: A1B2C3D4

Antwort 200 · application/ld+json

object

@contextstringPflicht
idstringPflicht
type"Product"Pflicht
passportobjectPflicht
Felder
- type"DigitalProductPassport"Pflicht

Fehler

401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data).
410	`codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand`
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/passport/A1B2C3D4/dpp.jsonld' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/A1B2C3D4/dpp.jsonld', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/A1B2C3D4/dpp.jsonld');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

code

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Passport version history with hash leaves

get/v1/passport/{code}/history

Schlüsselberechtigung: passport

All versions of the layers of the code (product, variant, batch, unit) with the changed fields, their values and the leaves of each version, so the brand system can recompute every hash on its own. Values erased under GDPR come as null with redacted.

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`code` path · Pflicht	string	Itemoo code of a unit, batch, variant or product Beispiel: A1B2C3D4

Antwort 200 · application/json

PassportHistory

codestringPflicht
level"public" | "legit" | "authority"Pflicht
versionPassportVersion | nullPflicht
Felder · PassportVersion
- hashstringPflicht
  SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
- layersobject[]Pflicht
  Felder
  - subject"product" | "variant" | "batch" | "unit"Pflicht
  - versionintegerPflicht
  - hashstringPflicht
- eventsHeadstring | nullPflicht
- atstring (date-time)
  Present for a passport read at a point in time (?at=)
versionsobject[]Pflicht
Felder
- subject"product" | "variant" | "batch" | "unit"Pflicht
- versionintegerPflicht
- hashstringPflicht
- prevHashstring | nullPflicht
- atstring (date-time)Pflicht
- sourcestringPflicht
- changesobject[]Pflicht
  Felder
  - keystringPflicht
  - op"add" | "change" | "remove"Pflicht
  - valueany
  - redactedboolean
- leavesmap<string, object>
  Leaf hashes (authority level only) to recompute the version hash
  Felder
  - hstringPflicht
  - access"public" | "legit" | "authority"Pflicht

Fehler

401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code
410	`codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand`
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/passport/A1B2C3D4/history' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/A1B2C3D4/history', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/A1B2C3D4/history');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

code

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

All brand passports in JSON-LD, page by page

get/v1/passport/export

Schlüsselberechtigung: passport

Products, variants with a GTIN and units of the brand as JSON-LD documents (authority level), 100 per page. Pass cursor of the response as cursor until it is null; passports added between pages do not shift the rest. For a backup copy or a move to another DPP service provider (BACKUP / TRANSFER of CIRPASS-2 D4.1 recommendation 3); the same passports in the EN 18223:2026 model and the EN 18222:2026 life cycle API are under /dpp-api/v1; the static public package is in the panel (Passport → Export).

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`cursor` query	string	The `cursor` of the previous page (opaque); without it — the first page

Antwort 200 · application/json

object

itemsobject[]Pflicht
Felder
- @contextstringPflicht
- idstringPflicht
cursorstring | nullPflicht
The cursor of the next page, null on the last one

Fehler

400	`DPP_CURSOR_INVALID` — The cursor is empty or does not come from the previous page of this query.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/passport/export' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/export', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/export');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

cursor (query)

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Model passport fields with access levels

put/v1/passport/products/{sku}

Schlüsselberechtigung: passport

Merges fields: { fields: { key: value } } or { fields: { key: { value, access } } }; value null removes the field. access: public | legit (persons with a legitimate interest) | authority (default legit). Up to 200 fields, 192 kB. Keys in the passport field dictionary namespaces (battery.*, product.*, compliance.*, safety.*, textile.*, medical.*, chemical.*, transport.*, materials.*, endOfLife.*, repair.*, documents.*) follow the dictionary: known keys only, typed values, the level (model, batch, unit) the field belongs to, and the default access level of the field; battery keys (Regulation (EU) 2023/1542 Annex XIII) have a fixed access level (another level → PASSPORT_ACCESS_FIXED). Other keys are free brand fields.

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`sku` path · Pflicht	string	Product (model) SKU Beispiel: AKU-100

Anfrageinhalt application/json

fieldsmap<string, any | object>Pflicht
{ key: value } or { key: { value, access } }; value null removes the field
Felder
- valueanyPflicht
- access"public" | "legit" | "authority"

Antwort 200 · application/json

object

productIdstringPflicht
skustring | nullPflicht
fieldsmap<string, object>Pflicht
Felder
- valueanyPflicht
- access"public" | "legit" | "authority"Pflicht

Fehler

400	`PASSPORT_FIELDS_INVALID` — Passport data: send fields as { key: value } or { key: { value, access } }; text up to 2,000 characters. `PASSPORT_FIELDS_TOO_MANY` — A passport can have at most 200 fields per product or unit. `PASSPORT_FIELDS_TOO_LARGE` — Passport data is too large (192 kB at most) — add long content as a document. `PASSPORT_FIELD_KEY_INVALID` — Passport field key: a letter, then letters, digits, _ . - (up to 64 characters). `PASSPORT_ACCESS_INVALID` — Access level: public, legit (legitimate interest) or authority. `PASSPORT_FIELD_UNKNOWN` — Field {key} is not in the passport field dictionary — check the name or use your own key outside the dictionary namespaces. params: `key` `PASSPORT_FIELD_NOT_WRITABLE` — Field {key} is filled by the system (code, manufacturer data) or by a unit event — it cannot be entered manually. params: `key` `PASSPORT_FIELD_SCOPE` — Field {key} does not belong to this level — enter model data on the product or variant and batch data on the batch. params: `key` `PASSPORT_ACCESS_FIXED` — Field {key} has a fixed access level ({access}) set by Annex XIII of Regulation 2023/1542. params: `key`, `access` `PASSPORT_VALUE_NUMBER` — {key}: enter a non-negative number. params: `key` `PASSPORT_VALUE_PERCENT` — {key}: enter a percentage from 0 to 100. params: `key` `PASSPORT_VALUE_TEXT` — {key}: enter text (up to 2,000 characters; a multilingual description up to 4,000 per language). params: `key` `PASSPORT_VALUE_LIST` — {key}: enter a list of texts (200 items at most). params: `key` `PASSPORT_VALUE_DATE` — {key}: a date as YYYY-MM or YYYY-MM-DD. params: `key` `PASSPORT_VALUE_CHOICE` — {key}: choose a value from the list. params: `key` `PASSPORT_VALUE_DOCUMENT` — {key}: choose a document from the library or a file (https address). params: `key` `PASSPORT_VALUE_INVALID` — {key}: the value does not match the field type — check the format in the passport field dictionary. params: `key` `PASSPORT_OPERATOR_NOT_FOUND` — Field {key} points to an operator outside the company register or an archived one. params: `key` `PASSPORT_OPERATOR_ROLE` — Field {key} needs an operator with the {role} role in the operator register. params: `key`, `role` `PASSPORT_DECLARATION_NOT_FOUND` — Field {key} points to a declaration of conformity outside the company register, archived or without an issued version. params: `key`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`PRODUCT_NOT_FOUND` — Product not found
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/passport/products/AKU-100' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"fields":{"chemistry":{"value":"LFP","access":"public"},"cathodeSupplier":"ACME"}}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/products/AKU-100', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "fields": {
      "chemistry": {
        "value": "LFP",
        "access": "public"
      },
      "cathodeSupplier": "ACME"
    }
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/products/AKU-100');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"fields":{"chemistry":{"value":"LFP","access":"public"},"cathodeSupplier":"ACME"}}',
]);
$data = json_decode(curl_exec($ch), true);

Static unit data from production (MES)

put/v1/passport/units

Schlüsselberechtigung: passport

Up to 1,000 units per call, each by code or by sku + serial; data merges like model fields. placedOnMarketAt declares when the unit was placed on the market; a battery unit placed on the market after the field set takes effect needs a complete passport (row error CODES_PASSPORT_INCOMPLETE). Unknown units are listed in unknown, invalid rows in errors — the rest is saved.

Key scope: passport.

Anfrageinhalt application/json

itemsobject[]Pflicht
Felder
- codestring
  Itemoo code of the unit — or sku + serial
- skustring
- serialstring
- datamap<string, any | object>
  Unit fields; battery passport keys (battery.*) follow the field dictionary and have a fixed access level
  Felder
  - valueanyPflicht
  - access"public" | "legit" | "authority"
- placedOnMarketAtstring | null
  Date the unit was placed on the market (YYYY-MM-DD), null clears it. A unit placed on the market after a field set takes effect must have a complete passport

Antwort 200 · application/json

object

receivedintegerPflicht
savedintegerPflicht
unknownstring[]Pflicht
errorsobject[]Pflicht
Felder
- rowintegerPflicht
- codestringPflicht

Fehler

400	`PASSPORT_FIELDS_INVALID` — Passport data: send fields as { key: value } or { key: { value, access } }; text up to 2,000 characters. `PASSPORT_IMPORT_MAX_1000` — At most 1,000 units in one import.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/passport/units' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"AKU-100","serial":"SN-0001","data":{"cellLot":"C-77"}}]}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/units', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "items": [
      {
        "sku": "AKU-100",
        "serial": "SN-0001",
        "data": {
          "cellLot": "C-77"
        }
      }
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/units');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"items":[{"sku":"AKU-100","serial":"SN-0001","data":{"cellLot":"C-77"}}]}',
]);
$data = json_decode(curl_exec($ch), true);

Append a unit event

post/v1/passport/units/{code}/events

Schlüsselberechtigung: passport

kind: status (data.status: original | repurposed | re-used | remanufactured | waste | recycled — recycled ends the passport), soh (data.soh, or Annex XIII point 4(b) metrics: soce, remainingCapacityPct, remainingPowerPct, remainingRoundTripEfficiencyPct, selfDischargePct 0–100, ohmicResistanceMOhm), cycles (data.cycles), incident (data.type: accident | deep_discharge | overheating | overcharge | mechanical_damage | other), temperature (data.celsius or minC / maxC), soc (data.socPct) or data (any fields). Optional occurredAt (ISO, not in the future) and access (battery events have the fixed level legit). Events are append-only and chained by SHA-256 hashes (hash in the response).

Key scope: passport.

Parameter

Feld	Typ	Beschreibung
`code` path · Pflicht	string	Itemoo code of a unit, batch, variant or product Beispiel: A1B2C3D4

Anfrageinhalt application/json

kind"status" | "soh" | "cycles" | "incident" | "temperature" | "soc" | "data" | "assembly"Pflicht
assembly — component with its own passport installed or removed: data { action: install | remove, code (Itemoo code) or uri (https passport address), role? }
dataobjectPflicht
occurredAtstring (date-time)
Not in the future; now by default
access"public" | "legit" | "authority"
public for status by default, legit otherwise

Antwort 200 · application/json

object

idstringPflicht
codestringPflicht
kindstringPflicht
dataanyPflicht
accessstringPflicht
occurredAtstring (date-time)Pflicht
hashstring | nullPflicht
SHA-256 of the event chained with the previous one (RFC 8785)

Fehler

400	`PASSPORT_EVENT_KIND_INVALID` — Event kind: status, soh, cycles, incident, temperature, soc or data. `PASSPORT_STATUS_INVALID` — Unit status: original, repurposed, re-used, remanufactured, waste or recycled. `PASSPORT_SOH_INVALID` — State of health (SoH) is a percentage from 0 to 100. `PASSPORT_CYCLES_INVALID` — The cycle count is a whole number from 0. `PASSPORT_INCIDENT_INVALID` — Incident type: accident, deep_discharge, overheating, overcharge, mechanical_damage or other. `PASSPORT_EVENT_DATE_INVALID` — The event date cannot be in the future or before 1990. `PASSPORT_ACCESS_INVALID` — Access level: public, legit (legitimate interest) or authority. `PASSPORT_TEMPERATURE_INVALID` — Temperature: degrees Celsius from −80 to 200 (celsius or minC / maxC). `PASSPORT_SOC_INVALID` — State of charge (socPct) is a percentage from 0 to 100. `PASSPORT_ACCESS_FIXED` — Field {key} has a fixed access level ({access}) set by Annex XIII of Regulation 2023/1542. params: `key`, `access` `PASSPORT_UNIT_RECYCLED` — The battery has been recycled — its passport has ceased to exist and accepts no entries (Regulation 2023/1542, Art. 77(8)). `PASSPORT_PERSONAL_DATA` — Field {key} contains personal data ({kind}) — it is not stored in the passport because the passport history cannot be changed. params: `key`, `kind`
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`PASSPORT_UNIT_NOT_FOUND` — No such unit in this brand.
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/passport/units/U7K2M9QX/events' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"soh","data":{"soh":96}}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/passport/units/U7K2M9QX/events', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "soh",
    "data": {
      "soh": 96
    }
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/passport/units/U7K2M9QX/events');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"kind":"soh","data":{"soh":96}}',
]);
$data = json_decode(curl_exec($ch), true);

Drafts

Product page for editing

get/v1/drafts/products/{product}/page

Schlüsselberechtigung: drafts

The working version of a product page as blocks with the text fields you may change and draftRevision (as the MCP tool product_page_get). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Parameter

Feld	Typ	Beschreibung
`product` path · Pflicht	string	Product id, Itemoo code or SKU Beispiel: KAW-250

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/drafts/products/KAW-250/page' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/products/KAW-250/page', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/products/KAW-250/page');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

product

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Edit a product page draft

put/v1/drafts/products/{product}/page

Schlüsselberechtigung: draftsVorschau: dryRun

Text operations on the product page (set, removeItem, addBlock, removeBlock); a published page gets a draft, the live page stays (as product_page_draft_patch). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Parameter

Feld	Typ	Beschreibung
`product` path · Pflicht	string	Product id, Itemoo code or SKU Beispiel: KAW-250

Anfrageinhalt application/json

draftRevisionstringPflicht
draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
operationsobject[]Pflicht
Operations applied in order; indexes refer to the page after the previous operations
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/drafts/products/KAW-250/page' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"draftRevision":"0123456789abcdef","operations":[{"op":"set","path":"2.lead","value":"Medium roast, notes of cocoa."}],"dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/products/KAW-250/page', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "draftRevision": "0123456789abcdef",
    "operations": [
      {
        "op": "set",
        "path": "2.lead",
        "value": "Medium roast, notes of cocoa."
      }
    ],
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/products/KAW-250/page');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"draftRevision":"0123456789abcdef","operations":[{"op":"set","path":"2.lead","value":"Medium roast, notes of cocoa."}],"dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

productJSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Create product drafts

post/v1/drafts/products

Schlüsselberechtigung: draftsVorschau: dryRun

New products in DRAFT status with the starting page of their category, optionally with text operations; up to 50 per call (as product_draft_create). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

productsobject[]Pflicht
Felder
- namestringPflicht
  Product name
- skustringPflicht
  SKU — unique in the brand
- categorystringPflicht
  Product category key (e.g. "chemicals")
- gtinstring
  GTIN / EAN (8–14 digits)
- operationsobject[]
  Optional text operations on the starting page (as in product_page_draft_patch)
langstring
Language of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for review
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/drafts/products' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"products":[{"name":"Coffee 250 g","sku":"KAW-250","category":"food"}],"dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/products', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "products": [
      {
        "name": "Coffee 250 g",
        "sku": "KAW-250",
        "category": "food"
      }
    ],
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/products');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"products":[{"name":"Coffee 250 g","sku":"KAW-250","category":"food"}],"dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Brand website draft

get/v1/drafts/site

Schlüsselberechtigung: drafts

The working version of the brand website and draftRevision (as site_draft_get). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/drafts/site' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/site', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/site');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Edit the brand website draft

put/v1/drafts/site

Schlüsselberechtigung: draftsVorschau: dryRun

Path operations on theme, pages, navigation and SEO; legal pages and legal links stay as they are (as site_draft_patch). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

draftRevisionstringPflicht
draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
operationsobject[]Pflicht
Operations applied in order; only theme, pages, navigation and seo, never legal pages or legal links
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X PUT 'https://itemoo.eu/v1/drafts/site' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"draftRevision":"0123456789abcdef","operations":[{"op":"set","path":"seo.description","value":"Coffee roasted in Krakow."}],"dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/site', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "draftRevision": "0123456789abcdef",
    "operations": [
      {
        "op": "set",
        "path": "seo.description",
        "value": "Coffee roasted in Krakow."
      }
    ],
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/site');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"draftRevision":"0123456789abcdef","operations":[{"op":"set","path":"seo.description","value":"Coffee roasted in Krakow."}],"dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

One post

get/v1/drafts/publications/{id}

Schlüsselberechtigung: drafts

A post with platform texts and draftRevision (as publication_get). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Parameter

Feld	Typ	Beschreibung
`id` path · Pflicht	string	Id of the post, article or campaign Beispiel: post-ai-x7Kp2

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/drafts/publications/post-ai-x7Kp2' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/publications/post-ai-x7Kp2', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/publications/post-ai-x7Kp2');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Create or edit a post draft

post/v1/drafts/publications

Schlüsselberechtigung: draftsVorschau: dryRun

A post always waits for approval by a team member (as publication_draft_upsert). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

idstring
Existing post id (edit); omit to create
draftRevisionstring
draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
titlestringPflicht
Working name in the calendar
messagestringPflicht
Main message of the post
headlinestring
Text on the graphic
template"product" | "teaser" | "free"
Graphic template; default: product when products are given, otherwise free
productCodesstring[]
Itemoo codes of the products in the post
scheduledAtstring (date-time)
Planned publication time (ISO 8601)
variantsobject[]
Felder
- platform"facebook" | "instagram" | "linkedin" | "tiktok"Pflicht
- textstringPflicht
  Post text for this platform
- hashtagsstring[]
- altTextstring
  Alternative text of the graphic
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/drafts/publications' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"New roast","message":"Our new medium roast is here.","dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/publications', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "title": "New roast",
    "message": "Our new medium roast is here.",
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/publications');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"title":"New roast","message":"Our new medium roast is here.","dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

One article

get/v1/drafts/articles/{id}

Schlüsselberechtigung: drafts

A knowledge article in all languages and draftRevision (as article_get). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Parameter

Feld	Typ	Beschreibung
`id` path · Pflicht	string	Id of the post, article or campaign Beispiel: post-ai-x7Kp2

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/drafts/articles/clx0article' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/articles/clx0article', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/articles/clx0article');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Create or edit an article draft

post/v1/drafts/articles

Schlüsselberechtigung: draftsVorschau: dryRun

A new article or a change of a draft article; a published article is edited in the panel (as article_draft_upsert). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

idstring
Existing draft article id; omit to create
draftRevisionstring
draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
langstring
Language of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for review
titlestring
Title
excerptstring
Short summary
bodystring
Body: paragraphs separated by an empty line, "## " for subheadings
categorystring
slugstring
productCodesstring[]
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/drafts/articles' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"How to brew","body":"Use 15 g of coffee per 250 ml of water.","dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/articles', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "title": "How to brew",
    "body": "Use 15 g of coffee per 250 ml of water.",
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/articles');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"title":"How to brew","body":"Use 15 g of coffee per 250 ml of water.","dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

One campaign

get/v1/drafts/campaigns/{id}

Schlüsselberechtigung: drafts

A push / newsletter campaign and draftRevision (as campaign_get), without recipient data. Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Parameter

Feld	Typ	Beschreibung
`id` path · Pflicht	string	Id of the post, article or campaign Beispiel: post-ai-x7Kp2

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X GET 'https://itemoo.eu/v1/drafts/campaigns/clx0campaign' \
  -H 'Authorization: Bearer itm_YOUR_KEY'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/campaigns/clx0campaign', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY },
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/campaigns/clx0campaign');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Create or edit a campaign draft

post/v1/drafts/campaigns

Schlüsselberechtigung: draftsVorschau: dryRun

Nothing is sent or scheduled — a team member sends it from the panel (as campaign_draft_upsert). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

idstring
Existing draft campaign id; omit to create
draftRevisionstring
draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
langstring
Language of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for review
namestring
Internal name
titlestring
Notification title
bodystring
Notification text
targetobject
Where the button leads; default: the brand app
Felder
- type"app" | "product" | "group"Pflicht
- codestring
  Product code for type "product"
- groupstring
  Shop category for type "group"
countriesstring[]
productCodesstring[]
Only people who scanned these products; empty = everyone with consent
pushboolean
emailboolean
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/drafts/campaigns' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"New roast","body":"Medium roast with cocoa notes - try it now.","dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/campaigns', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "title": "New roast",
    "body": "Medium roast with cocoa notes - try it now.",
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/campaigns');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"title":"New roast","body":"Medium roast with cocoa notes - try it now.","dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Discard a draft of this key

post/v1/drafts/discard

Schlüsselberechtigung: draftsVorschau: dryRun

Removes a draft created with this key and unchanged since (as draft_discard). Drafts only: nothing is published, sent or scheduled — a team member reviews and publishes in the Itemoo panel. Every write is a preview by default (dryRun omitted or true) and returns planToken; to save, repeat the SAME body with dryRun: false and that planToken (valid 10 minutes). The draft is signed with the person who created the key and the key name. Needs the plan feature “drafts from AI assistants”.

Key scope: drafts.

Anfrageinhalt application/json

kind"productPage" | "publication" | "article" | "campaign"Pflicht
idstringPflicht
Product id/code/SKU for productPage; otherwise the post, article or campaign id
dryRunboolean
Default true: nothing is saved — the result shows what would change and a planToken. Ask the user, then call again with the SAME arguments, dryRun: false and that planToken.
planTokenstring
planToken from the preview of exactly these arguments (required with dryRun: false, valid 10 minutes)

Antwort 200 · application/json

object

Fehler

400	`VAL_INVALID` — has an invalid value `DRAFT_PATCH_INVALID` — The draft change is not allowed or invalid — see the reason and detail fields. `DRAFT_PLAN_REQUIRED` — Saving needs the planToken from a preview (dryRun: true) of exactly this body. `DRAFT_PLAN_EXPIRED` — The preview expired — call it again (dryRun: true). `DRAFT_NOT_EDITABLE` — This object is no longer a draft — change it in the panel. `DRAFT_NOT_DISCARDABLE` — Only a draft created with this key (or by this person) and unchanged since can be discarded.
401	`API_KEY_INVALID` — Missing or invalid API key
403	`DRAFTS_NOT_AVAILABLE` — The company plan does not include drafts from AI assistants and the API. `DRAFT_ROLE_NOT_ALLOWED` — The role of the person who created the key does not allow this draft (or the person is no longer in the team). `TENANT_READ_ONLY` — The brand panel is read-only — changes are blocked. You can still publish product recalls and batches. Write to us to sort it out. `API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`DRAFT_NOT_FOUND` — This brand has no such product, post, article or campaign.
409	`DRAFT_CONFLICT` — The draft changed since it was read — read it again and repeat the change.
429	`DRAFT_DAILY_LIMIT` — The daily draft limit is used up (200 per person). `rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Beispiel

cURL

curl -X POST 'https://itemoo.eu/v1/drafts/discard' \
  -H 'Authorization: Bearer itm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"article","id":"clx0article","dryRun":true}'

JavaScript

const res = await fetch('https://itemoo.eu/v1/drafts/discard', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ITEMOO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "article",
    "id": "clx0article",
    "dryRun": true
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/v1/drafts/discard');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ITEMOO_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"kind":"article","id":"clx0article","dryRun":true}',
]);
$data = json_decode(curl_exec($ch), true);

Ausprobieren

Schlüssel Mein Schlüssel

JSON

Aus dem Browser senden wir nur Lesezugriffe und Vorschauen (dryRun). Der Schlüssel bleibt in diesem Tab — wir speichern ihn nicht.

Fügen Sie Ihren eigenen Schlüssel ein, um diesen Endpunkt auszuprobieren.

Benachrichtigungen (Webhooks)

postorder.ready

Order ready to fulfil

The order was paid, confirmed as cash on delivery or approved (B2B deferred payment) and can be packed.

idstringPflicht
Delivery id — the same on retries; use it to ignore duplicates
event"order.ready" | "order.cancelled" | "order.updated"Pflicht
createdAtstring (date-time)Pflicht
dataOrderPflicht
Felder · Order
- orderNostringPflicht
- channelstringPflicht
  app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
- externalobject | nullPflicht
  The order in the sales channel; null for brand shop orders
  Felder
  - orderIdstringPflicht
  - marketplacestringPflicht
  - statusstring | nullPflicht
- fulfilledBy"merchant" | "marketplace"Pflicht
  marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
- createdAtstring (date-time)Pflicht
- updatedAtstring (date-time)Pflicht
- paymentobjectPflicht
  Felder
  - status"pending" | "paid" | "failed" | "expired" | "refunded"Pflicht
  - method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"Pflicht
    online = card/BLIK/wallet in the shop; transfer = bank transfer; on_delivery = cash on delivery; on_pickup = paid at pickup; deferred = B2B deferred payment; marketplace = paid in the sales channel
  - paidAtstring (date-time) | nullPflicht
  - approval"pending" | "approved" | "rejected" | nullPflicht
    B2B deferred payment over the limit
- fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"Pflicht
- acknowledgedAtstring (date-time) | nullPflicht
  When the ERP acknowledged the order (POST /orders/ack)
- readyToShipbooleanPflicht
- currencystringPflicht
- totalnumberPflicht
- totalNetnumber | nullPflicht
- customerDiscountnumberPflicht
- buyerTypestringPflicht
  consumer | business
- vatobjectPflicht
  Felder
  - scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"Pflicht
    domestic = seller country VAT; eu-domestic = EU consumer below the OSS threshold (seller country rates); oss = EU consumer, buyer country rates; intra-eu = intra-EU supply to a VAT-registered business, 0%; export = outside the EU, 0%; marketplace-collected = the sales channel collected the buyer country tax; local = VAT of the channel warehouse country
  - collectedByMarketplacenumber | nullPflicht
  - countrystring | nullPflicht
  - exportbooleanPflicht
  - buyerVatIdstring | nullPflicht
  - viesobject | nullPflicht
    Felder
    statusstringPflicht
    requestIdstring | nullPflicht
    checkedAtstring (date-time) | nullPflicht
- shippingCostnumberPflicht
- discountnumberPflicht
- promoCodestring | nullPflicht
- promoDiscountnumberPflicht
- buyerobjectPflicht
  Felder
  - emailstring | nullPflicht
  - namestring | nullPflicht
  - phonestring | nullPflicht
  - personalDataRemovedbooleanPflicht
    true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
- shippingobjectPflicht
  Felder
  - methodstring | nullPflicht
  - addressobjectPflicht
    Felder
    line1string | nullPflicht
    line2string | nullPflicht
    postalstring | nullPflicht
    citystring | nullPflicht
    countrystring | nullPflicht
  - pointobject | nullPflicht
    Pickup point (code, name, address) when chosen
    Felder
- invoiceobject | nullPflicht
  Invoice data entered by the buyer (company, taxId, address)
  Felder
- notestring | nullPflicht
- carrierstring | nullPflicht
- trackingNostring | nullPflicht
- invoiceDocumentobject | nullPflicht
  Invoice attached with PUT /orders/{orderNo}/invoice
  Felder
  - numberstringPflicht
  - ksefNumberstring | nullPflicht
  - issuedAtstring | nullPflicht
  - hasPdfbooleanPflicht
- itemsOrderLine[]Pflicht
  Felder · OrderLine
  - skustring | nullPflicht
  - catalogNostring | nullPflicht
  - namestringPflicht
  - qtynumberPflicht
  - unitPricenumberPflicht
  - discountnumberPflicht
    Promotion and customer discount on the whole line (not per unit)
  - customerDiscountnumberPflicht
    Part of the discount coming from the B2B customer discount
  - vatRatestring | nullPflicht
  - vatCountrystring | nullPflicht
    Country of the VAT rate (OSS: the buyer country)
  - netTotalnumber | nullPflicht
    Net value of the line after discounts
  - giftbooleanPflicht
  - lotsobject[]Pflicht
    Batches the line shipped from
    Felder
    lotstringPflicht
    qtynumberPflicht
  - unitsstring[]Pflicht
    Itemoo QR codes of the shipped units

postorder.cancelled

Order cancelled

The order was cancelled outside your ERP (panel, customer or sales channel). Changes you make through this API send no notification.

idstringPflicht
Delivery id — the same on retries; use it to ignore duplicates
event"order.ready" | "order.cancelled" | "order.updated"Pflicht
createdAtstring (date-time)Pflicht
dataOrderPflicht
Felder · Order
- orderNostringPflicht
- channelstringPflicht
  app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
- externalobject | nullPflicht
  The order in the sales channel; null for brand shop orders
  Felder
  - orderIdstringPflicht
  - marketplacestringPflicht
  - statusstring | nullPflicht
- fulfilledBy"merchant" | "marketplace"Pflicht
  marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
- createdAtstring (date-time)Pflicht
- updatedAtstring (date-time)Pflicht
- paymentobjectPflicht
  Felder
  - status"pending" | "paid" | "failed" | "expired" | "refunded"Pflicht
  - method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"Pflicht
    online = card/BLIK/wallet in the shop; transfer = bank transfer; on_delivery = cash on delivery; on_pickup = paid at pickup; deferred = B2B deferred payment; marketplace = paid in the sales channel
  - paidAtstring (date-time) | nullPflicht
  - approval"pending" | "approved" | "rejected" | nullPflicht
    B2B deferred payment over the limit
- fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"Pflicht
- acknowledgedAtstring (date-time) | nullPflicht
  When the ERP acknowledged the order (POST /orders/ack)
- readyToShipbooleanPflicht
- currencystringPflicht
- totalnumberPflicht
- totalNetnumber | nullPflicht
- customerDiscountnumberPflicht
- buyerTypestringPflicht
  consumer | business
- vatobjectPflicht
  Felder
  - scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"Pflicht
    domestic = seller country VAT; eu-domestic = EU consumer below the OSS threshold (seller country rates); oss = EU consumer, buyer country rates; intra-eu = intra-EU supply to a VAT-registered business, 0%; export = outside the EU, 0%; marketplace-collected = the sales channel collected the buyer country tax; local = VAT of the channel warehouse country
  - collectedByMarketplacenumber | nullPflicht
  - countrystring | nullPflicht
  - exportbooleanPflicht
  - buyerVatIdstring | nullPflicht
  - viesobject | nullPflicht
    Felder
    statusstringPflicht
    requestIdstring | nullPflicht
    checkedAtstring (date-time) | nullPflicht
- shippingCostnumberPflicht
- discountnumberPflicht
- promoCodestring | nullPflicht
- promoDiscountnumberPflicht
- buyerobjectPflicht
  Felder
  - emailstring | nullPflicht
  - namestring | nullPflicht
  - phonestring | nullPflicht
  - personalDataRemovedbooleanPflicht
    true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
- shippingobjectPflicht
  Felder
  - methodstring | nullPflicht
  - addressobjectPflicht
    Felder
    line1string | nullPflicht
    line2string | nullPflicht
    postalstring | nullPflicht
    citystring | nullPflicht
    countrystring | nullPflicht
  - pointobject | nullPflicht
    Pickup point (code, name, address) when chosen
    Felder
- invoiceobject | nullPflicht
  Invoice data entered by the buyer (company, taxId, address)
  Felder
- notestring | nullPflicht
- carrierstring | nullPflicht
- trackingNostring | nullPflicht
- invoiceDocumentobject | nullPflicht
  Invoice attached with PUT /orders/{orderNo}/invoice
  Felder
  - numberstringPflicht
  - ksefNumberstring | nullPflicht
  - issuedAtstring | nullPflicht
  - hasPdfbooleanPflicht
- itemsOrderLine[]Pflicht
  Felder · OrderLine
  - skustring | nullPflicht
  - catalogNostring | nullPflicht
  - namestringPflicht
  - qtynumberPflicht
  - unitPricenumberPflicht
  - discountnumberPflicht
    Promotion and customer discount on the whole line (not per unit)
  - customerDiscountnumberPflicht
    Part of the discount coming from the B2B customer discount
  - vatRatestring | nullPflicht
  - vatCountrystring | nullPflicht
    Country of the VAT rate (OSS: the buyer country)
  - netTotalnumber | nullPflicht
    Net value of the line after discounts
  - giftbooleanPflicht
  - lotsobject[]Pflicht
    Batches the line shipped from
    Felder
    lotstringPflicht
    qtynumberPflicht
  - unitsstring[]Pflicht
    Itemoo QR codes of the shipped units

postorder.updated

Fulfilment changed

The fulfilment status or tracking number changed outside your ERP (e.g. in the panel). Changes you make through this API send no notification.

idstringPflicht
Delivery id — the same on retries; use it to ignore duplicates
event"order.ready" | "order.cancelled" | "order.updated"Pflicht
createdAtstring (date-time)Pflicht
dataOrderPflicht
Felder · Order
- orderNostringPflicht
- channelstringPflicht
  app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
- externalobject | nullPflicht
  The order in the sales channel; null for brand shop orders
  Felder
  - orderIdstringPflicht
  - marketplacestringPflicht
  - statusstring | nullPflicht
- fulfilledBy"merchant" | "marketplace"Pflicht
  marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
- createdAtstring (date-time)Pflicht
- updatedAtstring (date-time)Pflicht
- paymentobjectPflicht
  Felder
  - status"pending" | "paid" | "failed" | "expired" | "refunded"Pflicht
  - method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"Pflicht
    online = card/BLIK/wallet in the shop; transfer = bank transfer; on_delivery = cash on delivery; on_pickup = paid at pickup; deferred = B2B deferred payment; marketplace = paid in the sales channel
  - paidAtstring (date-time) | nullPflicht
  - approval"pending" | "approved" | "rejected" | nullPflicht
    B2B deferred payment over the limit
- fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"Pflicht
- acknowledgedAtstring (date-time) | nullPflicht
  When the ERP acknowledged the order (POST /orders/ack)
- readyToShipbooleanPflicht
- currencystringPflicht
- totalnumberPflicht
- totalNetnumber | nullPflicht
- customerDiscountnumberPflicht
- buyerTypestringPflicht
  consumer | business
- vatobjectPflicht
  Felder
  - scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"Pflicht
    domestic = seller country VAT; eu-domestic = EU consumer below the OSS threshold (seller country rates); oss = EU consumer, buyer country rates; intra-eu = intra-EU supply to a VAT-registered business, 0%; export = outside the EU, 0%; marketplace-collected = the sales channel collected the buyer country tax; local = VAT of the channel warehouse country
  - collectedByMarketplacenumber | nullPflicht
  - countrystring | nullPflicht
  - exportbooleanPflicht
  - buyerVatIdstring | nullPflicht
  - viesobject | nullPflicht
    Felder
    statusstringPflicht
    requestIdstring | nullPflicht
    checkedAtstring (date-time) | nullPflicht
- shippingCostnumberPflicht
- discountnumberPflicht
- promoCodestring | nullPflicht
- promoDiscountnumberPflicht
- buyerobjectPflicht
  Felder
  - emailstring | nullPflicht
  - namestring | nullPflicht
  - phonestring | nullPflicht
  - personalDataRemovedbooleanPflicht
    true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
- shippingobjectPflicht
  Felder
  - methodstring | nullPflicht
  - addressobjectPflicht
    Felder
    line1string | nullPflicht
    line2string | nullPflicht
    postalstring | nullPflicht
    citystring | nullPflicht
    countrystring | nullPflicht
  - pointobject | nullPflicht
    Pickup point (code, name, address) when chosen
    Felder
- invoiceobject | nullPflicht
  Invoice data entered by the buyer (company, taxId, address)
  Felder
- notestring | nullPflicht
- carrierstring | nullPflicht
- trackingNostring | nullPflicht
- invoiceDocumentobject | nullPflicht
  Invoice attached with PUT /orders/{orderNo}/invoice
  Felder
  - numberstringPflicht
  - ksefNumberstring | nullPflicht
  - issuedAtstring | nullPflicht
  - hasPdfbooleanPflicht
- itemsOrderLine[]Pflicht
  Felder · OrderLine
  - skustring | nullPflicht
  - catalogNostring | nullPflicht
  - namestringPflicht
  - qtynumberPflicht
  - unitPricenumberPflicht
  - discountnumberPflicht
    Promotion and customer discount on the whole line (not per unit)
  - customerDiscountnumberPflicht
    Part of the discount coming from the B2B customer discount
  - vatRatestring | nullPflicht
  - vatCountrystring | nullPflicht
    Country of the VAT rate (OSS: the buyer country)
  - netTotalnumber | nullPflicht
    Net value of the line after discounts
  - giftbooleanPflicht
  - lotsobject[]Pflicht
    Batches the line shipped from
    Felder
    lotstringPflicht
    qtynumberPflicht
  - unitsstring[]Pflicht
    Itemoo QR codes of the shipped units

Node.js

import crypto from 'node:crypto';

// header: X-Itemoo-Signature: t=<unix>,v1=<hex>
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Itemoo API for ERP

Einführung

Key

Antwort 200 · application/json

Beispiel

Items

Antwort 200 · application/json

Beispiel

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Stock

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Batches

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Orders

Parameter

Antwort 200 · application/json

Beispiel

Parameter

Antwort 200 · text/csv, application/xml

Spalten der Bestelldatei

XML

Beispiel

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Passport

Parameter

Antwort 200 · application/json

Beispiel

Parameter

Antwort 200 · application/ld+json

Beispiel

Parameter

Antwort 200 · application/json

Beispiel

Parameter

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Drafts

Parameter

Antwort 200 · application/json

Beispiel

Parameter

Anfrageinhalt application/json

Antwort 200 · application/json

Beispiel

Anfrageinhalt application/json