Chuyển đến nội dung

Tài liệu tham chiếu · v1

Itemoo API for ERP

SKU, tồn kho, lô hàng, đơn hàng, hóa đơn và hộ chiếu sản phẩm — cho ERP, WMS và MES. Khóa API của thương hiệu với các phạm vi quyền.

Mô tả endpoint và trường bằng tiếng Anh — giống như mã và tên trường trong API.

Giới thiệu

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

Phạm vi khóa: any

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

Key scope: any.

Phản hồi 200 · application/json

object

  • brandstring | nullbắt buộc
  • slugstring | nullbắt buộc
  • keystringbắt buộc
    Name of the API key
  • scopesstring[]bắt buộc
Lỗi
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.

Ví dụ

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);

Items

List of items (SKUs)

get/v1/items

Phạm vi khóa: items

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

Key scope: items.

Phản hồi 200 · application/json

Item[]

  • skustring | nullbắt buộc
    ERP SKU paired with the item; null = not paired yet
  • eanstring | nullbắt buộc
  • catalogNostring | nullbắt buộc
  • namestringbắt buộc
  • productstringbắt buộc
    Product (page) name
  • productSkustringbắt buộc
    SKU of the product model that groups the items on one page
  • pricenumber | nullbắt buộc
    Gross price in the brand currency
  • stockinteger | nullbắt buộc
    null = stock is not tracked (unlimited sale)
  • reservedintegerbắt buộc
    Units held by orders not yet acknowledged by the ERP
  • availablebooleanbắt buộc
Lỗi
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.

Ví dụ

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);

Pair SKUs with items

put/v1/items

Phạm vi khóa: itemsxem trước: 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.

Nội dung yêu cầu application/json

  • itemsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
      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
      Các trường
      • currencystringbắt buộc
      • priceGrossnumber | nullbắt buộc
        Gross price in the market currency; null returns the market to the recalculated price
  • dryRunboolean
    true = preview, nothing is saved

Phản hồi 200 · application/json

object

  • receivedintegerbắt buộc
  • alreadyPairedintegerbắt buộc
  • pairedobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • itemKeystringbắt buộc
      Item key in Itemoo
    • by"ean" | "catalogNo"bắt buộc
  • unmatchedobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • catalogNostring | nullbắt buộc
    • eanstring | nullbắt buộc
  • conflictsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • reasonstringbắt buộc
  • appliedbooleanbắt buộc
    false for dryRun
  • pricesobjectbắt buộc
    Các trường
    • updatedintegerbắt buộc
    • errorsobject[]bắt buộc
      Các trường
      • skustringbắt buộc
      • reasonstringbắt buộc
Lỗi
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.

Ví dụ

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);

Stock

Stock levels

put/v1/stock

Phạm vi khóa: 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.

Nội dung yêu cầu application/json

  • itemsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • qtyintegerbắt buộc

Phản hồi 200 · application/json

object

  • savedintegerbắt buộc
  • soldOutintegerbắt buộc
    Items that became unavailable (stock 0)
  • reservedDeductedintegerbắt buộc
    Units subtracted for unacknowledged orders
  • unknownSkustring[]bắt buộc
    Saved, but no item has this SKU yet — takes effect once paired in the panel
  • errorsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • reasonstringbắt buộc
Lỗi
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.

Ví dụ

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

Phạm vi khóa: batchesvẫn hoạt động khi tài khoản bị tạm ngưng

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.

Nội dung yêu cầu application/json

  • itemsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • lotstringbắt buộc
    • producedAtstring
      ISO date (YYYY-MM-DD) or date-time
    • expiresAtstring
      ISO date (YYYY-MM-DD) or date-time
    • qtyinteger

Phản hồi 200 · application/json

object

  • createdintegerbắt buộc
  • updatedintegerbắt buộc
  • unknownSkustring[]bắt buộc
  • errorsobject[]bắt buộc
    Các trường
    • skustringbắt buộc
    • lotstringbắt buộc
    • reasonstringbắt buộc
Lỗi
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.

Ví dụ

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

Phạm vi khóa: 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.

Tham số

TrườngKiểuMô tả
updatedSince
query
string (date-time)Only orders changed at or after this moment — pass "next" from the previous page
Ví dụ: 2026-10-16T08:30:00.000Z
limit
query
string1–200, default 100
Ví dụ: 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

Phản hồi 200 · application/json

object

  • ordersOrder[]bắt buộc
    Các trường · Order
    • orderNostringbắt buộc
    • channelstringbắt buộc
      app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
    • externalobject | nullbắt buộc
      The order in the sales channel; null for brand shop orders
      Các trường
      • orderIdstringbắt buộc
      • marketplacestringbắt buộc
      • statusstring | nullbắt buộc
    • fulfilledBy"merchant" | "marketplace"bắt buộc
      marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
    • createdAtstring (date-time)bắt buộc
    • updatedAtstring (date-time)bắt buộc
    • paymentobjectbắt buộc
      Các trường
      • status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộc
      • method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộc
        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) | nullbắt buộc
      • approval"pending" | "approved" | "rejected" | nullbắt buộc
        B2B deferred payment over the limit
    • fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộc
    • acknowledgedAtstring (date-time) | nullbắt buộc
      When the ERP acknowledged the order (POST /orders/ack)
    • readyToShipbooleanbắt buộc
    • currencystringbắt buộc
    • totalnumberbắt buộc
    • totalNetnumber | nullbắt buộc
    • customerDiscountnumberbắt buộc
    • buyerTypestringbắt buộc
      consumer | business
    • vatobjectbắt buộc
      Các trường
      • scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộc
        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 | nullbắt buộc
      • countrystring | nullbắt buộc
      • exportbooleanbắt buộc
      • buyerVatIdstring | nullbắt buộc
      • viesobject | nullbắt buộc
        Các trường
        • statusstringbắt buộc
        • requestIdstring | nullbắt buộc
        • checkedAtstring (date-time) | nullbắt buộc
    • shippingCostnumberbắt buộc
    • discountnumberbắt buộc
    • promoCodestring | nullbắt buộc
    • promoDiscountnumberbắt buộc
    • buyerobjectbắt buộc
      Các trường
      • emailstring | nullbắt buộc
      • namestring | nullbắt buộc
      • phonestring | nullbắt buộc
      • personalDataRemovedbooleanbắt buộc
        true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
    • shippingobjectbắt buộc
      Các trường
      • methodstring | nullbắt buộc
      • addressobjectbắt buộc
        Các trường
        • line1string | nullbắt buộc
        • line2string | nullbắt buộc
        • postalstring | nullbắt buộc
        • citystring | nullbắt buộc
        • countrystring | nullbắt buộc
      • pointobject | nullbắt buộc
        Pickup point (code, name, address) when chosen
        Các trường
      • invoiceobject | nullbắt buộc
        Invoice data entered by the buyer (company, taxId, address)
        Các trường
        • notestring | nullbắt buộc
        • carrierstring | nullbắt buộc
        • trackingNostring | nullbắt buộc
        • invoiceDocumentobject | nullbắt buộc
          Invoice attached with PUT /orders/{orderNo}/invoice
          Các trường
          • numberstringbắt buộc
          • ksefNumberstring | nullbắt buộc
          • issuedAtstring | nullbắt buộc
          • hasPdfbooleanbắt buộc
        • itemsOrderLine[]bắt buộc
          Các trường · OrderLine
          • skustring | nullbắt buộc
          • catalogNostring | nullbắt buộc
          • namestringbắt buộc
          • qtynumberbắt buộc
          • unitPricenumberbắt buộc
          • discountnumberbắt buộc
            Promotion and customer discount on the whole line (not per unit)
          • customerDiscountnumberbắt buộc
            Part of the discount coming from the B2B customer discount
          • vatRatestring | nullbắt buộc
          • vatCountrystring | nullbắt buộc
            Country of the VAT rate (OSS: the buyer country)
          • netTotalnumber | nullbắt buộc
            Net value of the line after discounts
          • giftbooleanbắt buộc
          • lotsobject[]bắt buộc
            Batches the line shipped from
            Các trường
            • lotstringbắt buộc
            • qtynumberbắt buộc
          • unitsstring[]bắt buộc
            Itemoo QR codes of the shipped units
      • nextstring (date-time) | nullbắt buộc
        Pass as updatedSince to get the next page; null = no more pages
      Lỗi
      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.

      Ví dụ

      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);

      Orders file (CSV or XML)

      get/v1/orders/export

      Phạm vi khóa: 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.

      Tham số

      TrườngKiểuMô tả
      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)
      Ví dụ: 2026-10-16T08:30:00.000Z
      all
      query
      "true" | "false"

      Phản hồi 200 · text/csv, application/xml

      Orders file (attachment).

      Các cột của tệp đơn hàng

      1order_noOrder number (orderNo)
      2created_atOrder date and time (ISO 8601)
      3payment_statusPayment status (payment.status)
      4payment_methodPayment method (payment.method)
      5fulfillmentFulfillment status: new | packing | shipped | delivered | cancelled
      6buyer_nameBuyer name
      7buyer_emailBuyer email
      8buyer_phoneBuyer phone
      9address_line1Shipping address, first line
      10postal_codePostal code
      11cityCity
      12countryCountry (ISO 3166-1 alpha-2)
      13pickup_pointPickup point code or name
      14shipping_methodShipping method
      15shipping_costShipping cost
      16discountOrder discount total (promotion + code + customer discount)
      17totalOrder total (gross)
      18invoice_companyInvoice: company name
      19invoice_tax_idInvoice: tax id
      20noteBuyer note
      21skuLine: SKU
      22catalog_noLine: catalogue number
      23nameLine: name
      24qtyLine: quantity
      25unit_priceLine: unit price (gross)
      26line_discountLine: discount on the whole line
      27giftLine: true for a free gift, false otherwise
      28lotsLine: shipped batches as "LOT:qty LOT:qty"
      29vat_rateLine: VAT rate (23 | 8 | 5 | 0 | exempt | outside_scope)
      30line_netLine: net value after discounts
      31total_netOrder total (net)
      32customer_discountOrder: B2B customer discount
      33channelSales channel (app | site | marketplace:…)
      34channel_order_noOrder number in the sales channel
      35fulfilled_byWho 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
      Lỗi
      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.

      Ví dụ

      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);

      Acknowledge orders received by the ERP

      post/v1/orders/ack

      Phạm vi khóa: 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.

      Nội dung yêu cầu application/json

      • orderNosstring[]bắt buộc

      Phản hồi 200 · application/json

      object

      • acknowledgedintegerbắt buộc
      • unknownstring[]bắt buộc
        Order numbers that do not exist in the brand
      Lỗi
      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.

      Ví dụ

      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

      Phạm vi khóa: 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.

      Tham số

      TrườngKiểuMô tả
      orderNo
      path · bắt buộc
      string
      Ví dụ: ITM-2026-000123

      Nội dung yêu cầu application/json

      • itemsobject[]bắt buộc
        Các trường
        • skustringbắt buộc
        • lotstringbắt buộc
        • qtyinteger
          The whole line quantity by default

      Phản hồi 200 · application/json

      object

      • savedintegerbắt buộc
      • errorsstring[]bắt buộc
        Rows that were skipped, as human-readable messages
      Lỗi
      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.

      Ví dụ

      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

      Phạm vi khóa: 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.

      Tham số

      TrườngKiểuMô tả
      orderNo
      path · bắt buộc
      string
      Ví dụ: ITM-2026-000123

      Nội dung yêu cầu application/json

      • itemsobject[]bắt buộc
        Các trường
        • skustringbắt buộc
        • codesstring[]bắt buộc
          Itemoo QR codes; an empty list removes the units

      Phản hồi 200 · application/json

      object

      • savedintegerbắt buộc
      • errorsstring[]bắt buộc
        Rows that were skipped, as human-readable messages
      Lỗi
      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.

      Ví dụ

      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

      Phạm vi khóa: 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.

      Tham số

      TrườngKiểuMô tả
      orderNo
      path · bắt buộc
      string
      Ví dụ: ITM-2026-000123

      Nội dung yêu cầu application/json

      • numberstringbắt buộc
      • 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

      Phản hồi 200 · application/json

      object

      • numberstringbắt buộc
      • ksefNumberstring | nullbắt buộc
      • issuedAtstring (date-time)bắt buộc
      • hasPdfbooleanbắt buộc
      • notifiedbooleanbắt buộc
        The customer got an email with the invoice
      Lỗi
      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.

      Ví dụ

      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}

      Phạm vi khóa: 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.

      Tham số

      TrườngKiểuMô tả
      orderNo
      path · bắt buộc
      string
      Ví dụ: ITM-2026-000123

      Nội dung yêu cầu application/json

      • status"packing" | "shipped" | "delivered" | "cancelled"bắt buộc
      • carrierstring
      • trackingNostring
      • reasonstring
        Cancellation reason shown to the customer
      • lotsobject[]
        Batches shipped, like PUT /orders/{orderNo}/lots
        Các trường
        • skustringbắt buộc
        • lotstringbắt buộc
        • qtyinteger
          The whole line quantity by default

      Phản hồi 200 · application/json

      OrderAfterStatusChange

      • orderNostringbắt buộc
      • channelstringbắt buộc
        app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
      • externalobject | nullbắt buộc
        The order in the sales channel; null for brand shop orders
        Các trường
        • orderIdstringbắt buộc
        • marketplacestringbắt buộc
        • statusstring | nullbắt buộc
      • fulfilledBy"merchant" | "marketplace"bắt buộc
        marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
      • createdAtstring (date-time)bắt buộc
      • updatedAtstring (date-time)bắt buộc
      • paymentobjectbắt buộc
        Các trường
        • status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộc
        • method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộc
          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) | nullbắt buộc
        • approval"pending" | "approved" | "rejected" | nullbắt buộc
          B2B deferred payment over the limit
      • fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộc
      • acknowledgedAtstring (date-time) | nullbắt buộc
        When the ERP acknowledged the order (POST /orders/ack)
      • readyToShipbooleanbắt buộc
      • currencystringbắt buộc
      • totalnumberbắt buộc
      • totalNetnumber | nullbắt buộc
      • customerDiscountnumberbắt buộc
      • buyerTypestringbắt buộc
        consumer | business
      • vatobjectbắt buộc
        Các trường
        • scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộc
          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 | nullbắt buộc
        • countrystring | nullbắt buộc
        • exportbooleanbắt buộc
        • buyerVatIdstring | nullbắt buộc
        • viesobject | nullbắt buộc
          Các trường
          • statusstringbắt buộc
          • requestIdstring | nullbắt buộc
          • checkedAtstring (date-time) | nullbắt buộc
      • shippingCostnumberbắt buộc
      • discountnumberbắt buộc
      • promoCodestring | nullbắt buộc
      • promoDiscountnumberbắt buộc
      • buyerobjectbắt buộc
        Các trường
        • emailstring | nullbắt buộc
        • namestring | nullbắt buộc
        • phonestring | nullbắt buộc
        • personalDataRemovedbooleanbắt buộc
          true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
      • shippingobjectbắt buộc
        Các trường
        • methodstring | nullbắt buộc
        • addressobjectbắt buộc
          Các trường
          • line1string | nullbắt buộc
          • line2string | nullbắt buộc
          • postalstring | nullbắt buộc
          • citystring | nullbắt buộc
          • countrystring | nullbắt buộc
        • pointobject | nullbắt buộc
          Pickup point (code, name, address) when chosen
          Các trường
        • invoiceobject | nullbắt buộc
          Invoice data entered by the buyer (company, taxId, address)
          Các trường
          • notestring | nullbắt buộc
          • carrierstring | nullbắt buộc
          • trackingNostring | nullbắt buộc
          • invoiceDocumentobject | nullbắt buộc
            Invoice attached with PUT /orders/{orderNo}/invoice
            Các trường
            • numberstringbắt buộc
            • ksefNumberstring | nullbắt buộc
            • issuedAtstring | nullbắt buộc
            • hasPdfbooleanbắt buộc
          • itemsOrderLine[]bắt buộc
            Các trường · OrderLine
            • skustring | nullbắt buộc
            • catalogNostring | nullbắt buộc
            • namestringbắt buộc
            • qtynumberbắt buộc
            • unitPricenumberbắt buộc
            • discountnumberbắt buộc
              Promotion and customer discount on the whole line (not per unit)
            • customerDiscountnumberbắt buộc
              Part of the discount coming from the B2B customer discount
            • vatRatestring | nullbắt buộc
            • vatCountrystring | nullbắt buộc
              Country of the VAT rate (OSS: the buyer country)
            • netTotalnumber | nullbắt buộc
              Net value of the line after discounts
            • giftbooleanbắt buộc
            • lotsobject[]bắt buộc
              Batches the line shipped from
              Các trường
              • lotstringbắt buộc
              • qtynumberbắt buộc
            • unitsstring[]bắt buộc
              Itemoo QR codes of the shipped units
          • unchangedtrue
            The same status was sent again — nothing changed, no email
          Lỗi
          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.

          Ví dụ

          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}

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          code
          path · bắt buộc
          stringItemoo code of a unit, batch, variant or product
          Ví dụ: A1B2C3D4

          Phản hồi 200 · application/json

          BrandPassport

          • level"public" | "legit" | "authority"bắt buộc
          • recipientstring
            Name of the access grant used
          • versionPassportVersion | nullbắt buộc
            Các trường · PassportVersion
            • hashstringbắt buộc
              SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
            • layersobject[]bắt buộc
              Các trường
              • subject"product" | "variant" | "batch" | "unit"bắt buộc
              • versionintegerbắt buộc
              • hashstringbắt buộc
            • eventsHeadstring | nullbắt buộc
            • atstring (date-time)
              Present for a passport read at a point in time (?at=)
          • backupobject | nullbắt buộc
            Backup copy of the passport kept by a DPP service provider (Regulation (EU) 2024/1781 Annex III point (l)), when the brand designated one
            Các trường
            • providerstringbắt buộc
            • urlstringbắt buộc
          • identityProductIdentitybắt buộc
            Các trường · ProductIdentity
            • codestringbắt buộc
              Itemoo code from the QR label
            • level"unit" | "batch" | "variant" | "model"bắt buộc
            • gtinstring | nullbắt buộc
            • skustring | nullbắt buộc
            • variantobject
              Các trường
              • labelstringbắt buộc
              • catalogNostring | nullbắt buộc
            • lotstring | nullbắt buộc
            • serialstring | nullbắt buộc
            • expiresAtstring (date-time) | nullbắt buộc
            • statusstringbắt buộc
              Batch status: ACTIVE | RECALLED | …
            • uniqueProductIdentifierstringbắt buộc
              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
          • productProductSummarybắt buộc
            Các trường · ProductSummary
            • namestringbắt buộc
            • brandstringbắt buộc
            • category"chemicals" | "cosmetics" | "medical" | "food" | "supplements" | "electronics" | "appliances" | "batteries" | "textiles" | "furniture" | "toys" | "construction" | "other" | nullbắt buộc
              Regulatory product type — decides the mandatory information: chemicals | cosmetics | medical | food | supplements | electronics | appliances | batteries | textiles | furniture | toys | construction | other
            • descriptionstringbắt buộc
            • 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
              Các trường
              • namemap<string, string>bắt buộc
              • descriptionmap<string, string>bắt buộc
          • manufacturerEconomicOperator | nullbắt buộc
            Các trường · EconomicOperator
            • namestringbắt buộc
            • addressobjectbắt buộc
              Các trường
              • streetstring | nullbắt buộc
              • postalCodestring | nullbắt buộc
              • citystring | nullbắt buộc
              • countrystring | nullbắt buộc
                ISO 3166-1 alpha-2
            • emailstring | nullbắt buộc
            • phonestring | nullbắt buộc
              Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
            • source"company" | "registry"bắt buộc
              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)
              Các trường
              • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
                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
              • valuestringbắt buộc
            • eoristring | null
              EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
          • responsiblePersonEconomicOperator | nullbắt buộc
            Các trường · EconomicOperator
            • namestringbắt buộc
            • addressobjectbắt buộc
              Các trường
              • streetstring | nullbắt buộc
              • postalCodestring | nullbắt buộc
              • citystring | nullbắt buộc
              • countrystring | nullbắt buộc
                ISO 3166-1 alpha-2
            • emailstring | nullbắt buộc
            • phonestring | nullbắt buộc
              Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
            • source"company" | "registry"bắt buộc
              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)
              Các trường
              • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
                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
              • valuestringbắt buộc
            • eoristring | null
              EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
          • importerEconomicOperator | nullbắt buộc
            Các trường · EconomicOperator
            • namestringbắt buộc
            • addressobjectbắt buộc
              Các trường
              • streetstring | nullbắt buộc
              • postalCodestring | nullbắt buộc
              • citystring | nullbắt buộc
              • countrystring | nullbắt buộc
                ISO 3166-1 alpha-2
            • emailstring | nullbắt buộc
            • phonestring | nullbắt buộc
              Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
            • source"company" | "registry"bắt buộc
              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)
              Các trường
              • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
                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
              • valuestringbắt buộc
            • eoristring | null
              EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
          • authorisedRepresentativeEconomicOperator | nullbắt buộc
            Các trường · EconomicOperator
            • namestringbắt buộc
            • addressobjectbắt buộc
              Các trường
              • streetstring | nullbắt buộc
              • postalCodestring | nullbắt buộc
              • citystring | nullbắt buộc
              • countrystring | nullbắt buộc
                ISO 3166-1 alpha-2
            • emailstring | nullbắt buộc
            • phonestring | nullbắt buộc
              Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
            • source"company" | "registry"bắt buộc
              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)
              Các trường
              • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
                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
              • valuestringbắt buộc
            • eoristring | null
              EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
          • facilityEconomicOperator | nullbắt buộc
            Các trường · EconomicOperator
            • namestringbắt buộc
            • addressobjectbắt buộc
              Các trường
              • streetstring | nullbắt buộc
              • postalCodestring | nullbắt buộc
              • citystring | nullbắt buộc
              • countrystring | nullbắt buộc
                ISO 3166-1 alpha-2
            • emailstring | nullbắt buộc
            • phonestring | nullbắt buộc
              Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
            • source"company" | "registry"bắt buộc
              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)
              Các trường
              • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
                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
              • valuestringbắt buộc
            • eoristring | null
              EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
          • languagestringbắt buộc
          • publishedbooleanbắt buộc
          • recallRecall | nullbắt buộc
            Các trường · Recall
            • activetruebắt buộc
            • certainbooleanbắt buộc
              true = this exact code is recalled; false = the batch is unknown and may be affected
            • scope"product" | "batch" | "lotRange"bắt buộc
              product = the whole product; batch = one batch; lotRange = a range of batch numbers (lotFrom–lotTo)
            • reasonstringbắt buộc
            • instructionsstring | nullbắt buộc
            • lotFromstring | nullbắt buộc
            • lotTostring | nullbắt buộc
            • kind"recall" | "notice"
              recall = the product is recalled; notice = safety notice, the product is not withdrawn
          • factsProvenanceFact[]bắt buộc
            Các trường · 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
            • namestringbắt buộc
              Fact name in the response language
            • valuestringbắt buộc
            • provenanceobject
              Các trường
              • sourcestringbắt buộc
                Document or block the fact comes from
              • versionstring
              • documentUrlstring
              • assertedBystringbắt buộc
                Brand that published the fact
              • assertedAtstring
          • documentsDocument[]bắt buộc
            Các trường · Document
            • titlestringbắt buộc
            • urlstringbắt buộc
            • kindstringbắt buộc
              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[]bắt buộc
            Components with their own passport visible at this level (Regulation (EU) 2024/1781 Art. 2(4); CIRPASS-2 D4.1 recommendation 5)
            Các trường · PassportComponent
            • codestring | nullbắt buộc
              Itemoo code of the component passport (unit, batch, variant or model — also of another brand)
            • uristring | nullbắt buộc
              Address of a component passport outside Itemoo (DPP URL or GS1 Digital Link)
            • urlstringbắt buộc
              Where to read the component passport
            • rolestring | nullbắt buộc
            • nameanybắt buộc
            • quantitynumber | nullbắt buộc
            • unitstring | nullbắt buộc
            • level"model" | "unit"bắt buộc
              model — bill of components of the model; unit — installed in this unit (assembly events)
            • sincestring | nullbắt buộc
              When the component was installed in this unit
          • lifecycleobjectbắt buộc
            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
            Các trường
            • status"active" | "recalled" | "end_of_life" | "archived" | "closed"bắt buộc
            • sincestring (date-time) | nullbắt buộc
          • modelobjectbắt buộc
            Model passport fields visible at this level
          • unitobject | nullbắt buộc
            Các trường
            • serialstring | nullbắt buộc
            • dataobjectbắt buộc
            • stateobjectbắt buộc
              Các trường
              • statusstring | nullbắt buộc
                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 | nullbắt buộc
                State of health, 0–100 (SoH, or SOCE / remaining capacity when only that is recorded)
              • sohAtstring (date-time) | nullbắt buộc
              • cyclesnumber | nullbắt buộc
              • incidentsintegerbắt buộc
            • historyobject[]bắt buộc
              Các trường
              • kindstringbắt buộc
              • dataanybắt buộc
              • occurredAtstring (date-time)bắt buộc
              • sourcestring
            • linksobjectbắt buộc
              Các trường
              • predecessorobject | nullbắt buộc
                Passport before remanufacturing or repurposing (Art. 77(7))
                Các trường
                • codestringbắt buộc
                • urlstringbắt buộc
              • successorsobject[]bắt buộc
                New passports created from this battery
                Các trường
                • codestringbắt buộc
                • urlstringbắt buộc
            • custodianobject | nullbắt buộc
              Operator responsible for the passport of a waste battery after a transfer (producer, PRO or waste management operator — Art. 77(7))
              Các trường
              • namestringbắt buộc
              • rolestringbắt buộc
              • sincestring (date-time)bắt buộc
          • fieldsobjectbắt buộc
            Editable fields with their access levels, per layer
            Các trường
            • modelmap<string, object>bắt buộc
              Các trường
              • valueanybắt buộc
              • access"public" | "legit" | "authority"bắt buộc
            • variantmap<string, object> | nullbắt buộc
              Variant layer (overrides the model)
              Các trường
              • valueanybắt buộc
              • access"public" | "legit" | "authority"bắt buộc
            • batchmap<string, object> | nullbắt buộc
              Batch layer (inherited by units)
              Các trường
              • valueanybắt buộc
              • access"public" | "legit" | "authority"bắt buộc
            • unitmap<string, object> | nullbắt buộc
              Các trường
              • valueanybắt buộc
              • access"public" | "legit" | "authority"bắt buộc
          • unitMetaobject | nullbắt buộc
            Unit dates: code activation and placing on the market; predecessor passport code
            Các trường
            • statusstringbắt buộc
            • activatedAtstring (date-time) | nullbắt buộc
            • placedOnMarketAtstring (date-time) | nullbắt buộc
            • predecessorCodestring | nullbắt buộc
          • versionsany[]bắt buộc
            Version history of all layers with pseudonymous authors (see the public PassportHistory)
          • chainmap<string, integer | null>bắt buộc
            Per layer: number of the first version whose hash does not verify, null = intact
          Lỗi
          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.

          Ví dụ

          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);

          Passport in JSON-LD with all access levels

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

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          code
          path · bắt buộc
          stringItemoo code of a unit, batch, variant or product
          Ví dụ: A1B2C3D4

          Phản hồi 200 · application/ld+json

          object

          • @contextstringbắt buộc
          • idstringbắt buộc
          • type"Product"bắt buộc
          • passportobjectbắt buộc
            Các trường
            • type"DigitalProductPassport"bắt buộc
          Lỗi
          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.

          Ví dụ

          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);

          Passport version history with hash leaves

          get/v1/passport/{code}/history

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          code
          path · bắt buộc
          stringItemoo code of a unit, batch, variant or product
          Ví dụ: A1B2C3D4

          Phản hồi 200 · application/json

          PassportHistory

          • codestringbắt buộc
          • level"public" | "legit" | "authority"bắt buộc
          • versionPassportVersion | nullbắt buộc
            Các trường · PassportVersion
            • hashstringbắt buộc
              SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
            • layersobject[]bắt buộc
              Các trường
              • subject"product" | "variant" | "batch" | "unit"bắt buộc
              • versionintegerbắt buộc
              • hashstringbắt buộc
            • eventsHeadstring | nullbắt buộc
            • atstring (date-time)
              Present for a passport read at a point in time (?at=)
          • versionsobject[]bắt buộc
            Các trường
            • subject"product" | "variant" | "batch" | "unit"bắt buộc
            • versionintegerbắt buộc
            • hashstringbắt buộc
            • prevHashstring | nullbắt buộc
            • atstring (date-time)bắt buộc
            • sourcestringbắt buộc
            • changesobject[]bắt buộc
              Các trường
              • keystringbắt buộc
              • op"add" | "change" | "remove"bắt buộc
              • valueany
              • redactedboolean
            • leavesmap<string, object>
              Leaf hashes (authority level only) to recompute the version hash
              Các trường
              • hstringbắt buộc
              • access"public" | "legit" | "authority"bắt buộc
          Lỗi
          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.

          Ví dụ

          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);

          All brand passports in JSON-LD, page by page

          get/v1/passport/export

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          cursor
          query
          stringThe cursor of the previous page (opaque); without it — the first page

          Phản hồi 200 · application/json

          object

          • itemsobject[]bắt buộc
            Các trường
            • @contextstringbắt buộc
            • idstringbắt buộc
          • cursorstring | nullbắt buộc
            The cursor of the next page, null on the last one
          Lỗi
          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.

          Ví dụ

          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);

          Model passport fields with access levels

          put/v1/passport/products/{sku}

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          sku
          path · bắt buộc
          stringProduct (model) SKU
          Ví dụ: AKU-100

          Nội dung yêu cầu application/json

          • fieldsmap<string, any | object>bắt buộc
            { key: value } or { key: { value, access } }; value null removes the field
            Các trường
            • valueanybắt buộc
            • access"public" | "legit" | "authority"

          Phản hồi 200 · application/json

          object

          • productIdstringbắt buộc
          • skustring | nullbắt buộc
          • fieldsmap<string, object>bắt buộc
            Các trường
            • valueanybắt buộc
            • access"public" | "legit" | "authority"bắt buộc
          Lỗi
          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.

          Ví dụ

          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

          Phạm vi khóa: 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.

          Nội dung yêu cầu application/json

          • itemsobject[]bắt buộc
            Các trường
            • 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
              Các trường
              • valueanybắt buộc
              • 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

          Phản hồi 200 · application/json

          object

          • receivedintegerbắt buộc
          • savedintegerbắt buộc
          • unknownstring[]bắt buộc
          • errorsobject[]bắt buộc
            Các trường
            • rowintegerbắt buộc
            • codestringbắt buộc
          Lỗi
          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.

          Ví dụ

          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

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          code
          path · bắt buộc
          stringItemoo code of a unit, batch, variant or product
          Ví dụ: A1B2C3D4

          Nội dung yêu cầu application/json

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

          Phản hồi 200 · application/json

          object

          • idstringbắt buộc
          • codestringbắt buộc
          • kindstringbắt buộc
          • dataanybắt buộc
          • accessstringbắt buộc
          • occurredAtstring (date-time)bắt buộc
          • hashstring | nullbắt buộc
            SHA-256 of the event chained with the previous one (RFC 8785)
          Lỗi
          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.

          Ví dụ

          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

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          product
          path · bắt buộc
          stringProduct id, Itemoo code or SKU
          Ví dụ: KAW-250

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Edit a product page draft

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

          Phạm vi khóa: draftsxem trước: 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.

          Tham số

          TrườngKiểuMô tả
          product
          path · bắt buộc
          stringProduct id, Itemoo code or SKU
          Ví dụ: KAW-250

          Nội dung yêu cầu application/json

          • draftRevisionstringbắt buộc
            draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
          • operationsobject[]bắt buộc
            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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Create product drafts

          post/v1/drafts/products

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu application/json

          • productsobject[]bắt buộc
            Các trường
            • namestringbắt buộc
              Product name
            • skustringbắt buộc
              SKU — unique in the brand
            • categorystringbắt buộc
              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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Brand website draft

          get/v1/drafts/site

          Phạm vi khóa: 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.

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Edit the brand website draft

          put/v1/drafts/site

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu application/json

          • draftRevisionstringbắt buộc
            draftRevision from the last read; if the draft changed since, the call fails with draftConflict — read again
          • operationsobject[]bắt buộc
            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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          One post

          get/v1/drafts/publications/{id}

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          id
          path · bắt buộc
          stringId of the post, article or campaign
          Ví dụ: post-ai-x7Kp2

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Create or edit a post draft

          post/v1/drafts/publications

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu 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
          • titlestringbắt buộc
            Working name in the calendar
          • messagestringbắt buộc
            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[]
            Các trường
            • platform"facebook" | "instagram" | "linkedin" | "tiktok"bắt buộc
            • textstringbắt buộc
              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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          One article

          get/v1/drafts/articles/{id}

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          id
          path · bắt buộc
          stringId of the post, article or campaign
          Ví dụ: post-ai-x7Kp2

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Create or edit an article draft

          post/v1/drafts/articles

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu 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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          One campaign

          get/v1/drafts/campaigns/{id}

          Phạm vi khóa: 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.

          Tham số

          TrườngKiểuMô tả
          id
          path · bắt buộc
          stringId of the post, article or campaign
          Ví dụ: post-ai-x7Kp2

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Create or edit a campaign draft

          post/v1/drafts/campaigns

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu 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
            Các trường
            • type"app" | "product" | "group"bắt buộc
            • 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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Discard a draft of this key

          post/v1/drafts/discard

          Phạm vi khóa: draftsxem trước: 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.

          Nội dung yêu cầu application/json

          • kind"productPage" | "publication" | "article" | "campaign"bắt buộc
          • idstringbắt buộc
            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)

          Phản hồi 200 · application/json

          object

          Lỗi
          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.

          Ví dụ

          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);

          Thông báo (webhook)

          postorder.ready

          Order ready to fulfil

          The order was paid, confirmed as cash on delivery or approved (B2B deferred payment) and can be packed.
          • idstringbắt buộc
            Delivery id — the same on retries; use it to ignore duplicates
          • event"order.ready" | "order.cancelled" | "order.updated"bắt buộc
          • createdAtstring (date-time)bắt buộc
          • dataOrderbắt buộc
            Các trường · Order
            • orderNostringbắt buộc
            • channelstringbắt buộc
              app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
            • externalobject | nullbắt buộc
              The order in the sales channel; null for brand shop orders
              Các trường
              • orderIdstringbắt buộc
              • marketplacestringbắt buộc
              • statusstring | nullbắt buộc
            • fulfilledBy"merchant" | "marketplace"bắt buộc
              marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
            • createdAtstring (date-time)bắt buộc
            • updatedAtstring (date-time)bắt buộc
            • paymentobjectbắt buộc
              Các trường
              • status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộc
              • method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộc
                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) | nullbắt buộc
              • approval"pending" | "approved" | "rejected" | nullbắt buộc
                B2B deferred payment over the limit
            • fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộc
            • acknowledgedAtstring (date-time) | nullbắt buộc
              When the ERP acknowledged the order (POST /orders/ack)
            • readyToShipbooleanbắt buộc
            • currencystringbắt buộc
            • totalnumberbắt buộc
            • totalNetnumber | nullbắt buộc
            • customerDiscountnumberbắt buộc
            • buyerTypestringbắt buộc
              consumer | business
            • vatobjectbắt buộc
              Các trường
              • scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộc
                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 | nullbắt buộc
              • countrystring | nullbắt buộc
              • exportbooleanbắt buộc
              • buyerVatIdstring | nullbắt buộc
              • viesobject | nullbắt buộc
                Các trường
                • statusstringbắt buộc
                • requestIdstring | nullbắt buộc
                • checkedAtstring (date-time) | nullbắt buộc
            • shippingCostnumberbắt buộc
            • discountnumberbắt buộc
            • promoCodestring | nullbắt buộc
            • promoDiscountnumberbắt buộc
            • buyerobjectbắt buộc
              Các trường
              • emailstring | nullbắt buộc
              • namestring | nullbắt buộc
              • phonestring | nullbắt buộc
              • personalDataRemovedbooleanbắt buộc
                true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
            • shippingobjectbắt buộc
              Các trường
              • methodstring | nullbắt buộc
              • addressobjectbắt buộc
                Các trường
                • line1string | nullbắt buộc
                • line2string | nullbắt buộc
                • postalstring | nullbắt buộc
                • citystring | nullbắt buộc
                • countrystring | nullbắt buộc
              • pointobject | nullbắt buộc
                Pickup point (code, name, address) when chosen
                Các trường
              • invoiceobject | nullbắt buộc
                Invoice data entered by the buyer (company, taxId, address)
                Các trường
                • notestring | nullbắt buộc
                • carrierstring | nullbắt buộc
                • trackingNostring | nullbắt buộc
                • invoiceDocumentobject | nullbắt buộc
                  Invoice attached with PUT /orders/{orderNo}/invoice
                  Các trường
                  • numberstringbắt buộc
                  • ksefNumberstring | nullbắt buộc
                  • issuedAtstring | nullbắt buộc
                  • hasPdfbooleanbắt buộc
                • itemsOrderLine[]bắt buộc
                  Các trường · OrderLine
                  • skustring | nullbắt buộc
                  • catalogNostring | nullbắt buộc
                  • namestringbắt buộc
                  • qtynumberbắt buộc
                  • unitPricenumberbắt buộc
                  • discountnumberbắt buộc
                    Promotion and customer discount on the whole line (not per unit)
                  • customerDiscountnumberbắt buộc
                    Part of the discount coming from the B2B customer discount
                  • vatRatestring | nullbắt buộc
                  • vatCountrystring | nullbắt buộc
                    Country of the VAT rate (OSS: the buyer country)
                  • netTotalnumber | nullbắt buộc
                    Net value of the line after discounts
                  • giftbooleanbắt buộc
                  • lotsobject[]bắt buộc
                    Batches the line shipped from
                    Các trường
                    • lotstringbắt buộc
                    • qtynumberbắt buộc
                  • unitsstring[]bắt buộc
                    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.
              • idstringbắt buộc
                Delivery id — the same on retries; use it to ignore duplicates
              • event"order.ready" | "order.cancelled" | "order.updated"bắt buộc
              • createdAtstring (date-time)bắt buộc
              • dataOrderbắt buộc
                Các trường · Order
                • orderNostringbắt buộc
                • channelstringbắt buộc
                  app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
                • externalobject | nullbắt buộc
                  The order in the sales channel; null for brand shop orders
                  Các trường
                  • orderIdstringbắt buộc
                  • marketplacestringbắt buộc
                  • statusstring | nullbắt buộc
                • fulfilledBy"merchant" | "marketplace"bắt buộc
                  marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
                • createdAtstring (date-time)bắt buộc
                • updatedAtstring (date-time)bắt buộc
                • paymentobjectbắt buộc
                  Các trường
                  • status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộc
                  • method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộc
                    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) | nullbắt buộc
                  • approval"pending" | "approved" | "rejected" | nullbắt buộc
                    B2B deferred payment over the limit
                • fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộc
                • acknowledgedAtstring (date-time) | nullbắt buộc
                  When the ERP acknowledged the order (POST /orders/ack)
                • readyToShipbooleanbắt buộc
                • currencystringbắt buộc
                • totalnumberbắt buộc
                • totalNetnumber | nullbắt buộc
                • customerDiscountnumberbắt buộc
                • buyerTypestringbắt buộc
                  consumer | business
                • vatobjectbắt buộc
                  Các trường
                  • scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộc
                    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 | nullbắt buộc
                  • countrystring | nullbắt buộc
                  • exportbooleanbắt buộc
                  • buyerVatIdstring | nullbắt buộc
                  • viesobject | nullbắt buộc
                    Các trường
                    • statusstringbắt buộc
                    • requestIdstring | nullbắt buộc
                    • checkedAtstring (date-time) | nullbắt buộc
                • shippingCostnumberbắt buộc
                • discountnumberbắt buộc
                • promoCodestring | nullbắt buộc
                • promoDiscountnumberbắt buộc
                • buyerobjectbắt buộc
                  Các trường
                  • emailstring | nullbắt buộc
                  • namestring | nullbắt buộc
                  • phonestring | nullbắt buộc
                  • personalDataRemovedbooleanbắt buộc
                    true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
                • shippingobjectbắt buộc
                  Các trường
                  • methodstring | nullbắt buộc
                  • addressobjectbắt buộc
                    Các trường
                    • line1string | nullbắt buộc
                    • line2string | nullbắt buộc
                    • postalstring | nullbắt buộc
                    • citystring | nullbắt buộc
                    • countrystring | nullbắt buộc
                  • pointobject | nullbắt buộc
                    Pickup point (code, name, address) when chosen
                    Các trường
                  • invoiceobject | nullbắt buộc
                    Invoice data entered by the buyer (company, taxId, address)
                    Các trường
                    • notestring | nullbắt buộc
                    • carrierstring | nullbắt buộc
                    • trackingNostring | nullbắt buộc
                    • invoiceDocumentobject | nullbắt buộc
                      Invoice attached with PUT /orders/{orderNo}/invoice
                      Các trường
                      • numberstringbắt buộc
                      • ksefNumberstring | nullbắt buộc
                      • issuedAtstring | nullbắt buộc
                      • hasPdfbooleanbắt buộc
                    • itemsOrderLine[]bắt buộc
                      Các trường · OrderLine
                      • skustring | nullbắt buộc
                      • catalogNostring | nullbắt buộc
                      • namestringbắt buộc
                      • qtynumberbắt buộc
                      • unitPricenumberbắt buộc
                      • discountnumberbắt buộc
                        Promotion and customer discount on the whole line (not per unit)
                      • customerDiscountnumberbắt buộc
                        Part of the discount coming from the B2B customer discount
                      • vatRatestring | nullbắt buộc
                      • vatCountrystring | nullbắt buộc
                        Country of the VAT rate (OSS: the buyer country)
                      • netTotalnumber | nullbắt buộc
                        Net value of the line after discounts
                      • giftbooleanbắt buộc
                      • lotsobject[]bắt buộc
                        Batches the line shipped from
                        Các trường
                        • lotstringbắt buộc
                        • qtynumberbắt buộc
                      • unitsstring[]bắt buộc
                        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.
                  • idstringbắt buộc
                    Delivery id — the same on retries; use it to ignore duplicates
                  • event"order.ready" | "order.cancelled" | "order.updated"bắt buộc
                  • createdAtstring (date-time)bắt buộc
                  • dataOrderbắt buộc
                    Các trường · Order
                    • orderNostringbắt buộc
                    • channelstringbắt buộc
                      app | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erp
                    • externalobject | nullbắt buộc
                      The order in the sales channel; null for brand shop orders
                      Các trường
                      • orderIdstringbắt buộc
                      • marketplacestringbắt buộc
                      • statusstring | nullbắt buộc
                    • fulfilledBy"merchant" | "marketplace"bắt buộc
                      marketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping only
                    • createdAtstring (date-time)bắt buộc
                    • updatedAtstring (date-time)bắt buộc
                    • paymentobjectbắt buộc
                      Các trường
                      • status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộc
                      • method"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộc
                        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) | nullbắt buộc
                      • approval"pending" | "approved" | "rejected" | nullbắt buộc
                        B2B deferred payment over the limit
                    • fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộc
                    • acknowledgedAtstring (date-time) | nullbắt buộc
                      When the ERP acknowledged the order (POST /orders/ack)
                    • readyToShipbooleanbắt buộc
                    • currencystringbắt buộc
                    • totalnumberbắt buộc
                    • totalNetnumber | nullbắt buộc
                    • customerDiscountnumberbắt buộc
                    • buyerTypestringbắt buộc
                      consumer | business
                    • vatobjectbắt buộc
                      Các trường
                      • scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộc
                        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 | nullbắt buộc
                      • countrystring | nullbắt buộc
                      • exportbooleanbắt buộc
                      • buyerVatIdstring | nullbắt buộc
                      • viesobject | nullbắt buộc
                        Các trường
                        • statusstringbắt buộc
                        • requestIdstring | nullbắt buộc
                        • checkedAtstring (date-time) | nullbắt buộc
                    • shippingCostnumberbắt buộc
                    • discountnumberbắt buộc
                    • promoCodestring | nullbắt buộc
                    • promoDiscountnumberbắt buộc
                    • buyerobjectbắt buộc
                      Các trường
                      • emailstring | nullbắt buộc
                      • namestring | nullbắt buộc
                      • phonestring | nullbắt buộc
                      • personalDataRemovedbooleanbắt buộc
                        true = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
                    • shippingobjectbắt buộc
                      Các trường
                      • methodstring | nullbắt buộc
                      • addressobjectbắt buộc
                        Các trường
                        • line1string | nullbắt buộc
                        • line2string | nullbắt buộc
                        • postalstring | nullbắt buộc
                        • citystring | nullbắt buộc
                        • countrystring | nullbắt buộc
                      • pointobject | nullbắt buộc
                        Pickup point (code, name, address) when chosen
                        Các trường
                      • invoiceobject | nullbắt buộc
                        Invoice data entered by the buyer (company, taxId, address)
                        Các trường
                        • notestring | nullbắt buộc
                        • carrierstring | nullbắt buộc
                        • trackingNostring | nullbắt buộc
                        • invoiceDocumentobject | nullbắt buộc
                          Invoice attached with PUT /orders/{orderNo}/invoice
                          Các trường
                          • numberstringbắt buộc
                          • ksefNumberstring | nullbắt buộc
                          • issuedAtstring | nullbắt buộc
                          • hasPdfbooleanbắt buộc
                        • itemsOrderLine[]bắt buộc
                          Các trường · OrderLine
                          • skustring | nullbắt buộc
                          • catalogNostring | nullbắt buộc
                          • namestringbắt buộc
                          • qtynumberbắt buộc
                          • unitPricenumberbắt buộc
                          • discountnumberbắt buộc
                            Promotion and customer discount on the whole line (not per unit)
                          • customerDiscountnumberbắt buộc
                            Part of the discount coming from the B2B customer discount
                          • vatRatestring | nullbắt buộc
                          • vatCountrystring | nullbắt buộc
                            Country of the VAT rate (OSS: the buyer country)
                          • netTotalnumber | nullbắt buộc
                            Net value of the line after discounts
                          • giftbooleanbắt buộc
                          • lotsobject[]bắt buộc
                            Batches the line shipped from
                            Các trường
                            • lotstringbắt buộc
                            • qtynumberbắt buộc
                          • unitsstring[]bắt buộc
                            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));
                      }