- Itemoo
- Nhà phát triển
- API cho ERP
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ộcslugstring | nullbắt buộckeystringbắt buộcName of the API keyscopesstring[]bắt buộc
Lỗi
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcERP SKU paired with the item; null = not paired yeteanstring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcproductstringbắt buộcProduct (page) nameproductSkustringbắt buộcSKU of the product model that groups the items on one pagepricenumber | nullbắt buộcGross price in the brand currencystockinteger | nullbắt buộcnull = stock is not tracked (unlimited sale)reservedintegerbắt buộcUnits held by orders not yet acknowledged by the ERPavailablebooleanbắt buộc
Lỗi
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcCác trường
skustringbắt buộcSKU in your ERPcatalogNostringCatalogue number used to find the itemeanstringEAN/GTIN used to find the itemnamestringName in the ERP — helps pairing by handpriceGrossnumberpriceNetnumbervatRate"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 recalculationCác trường
currencystringbắt buộcpriceGrossnumber | nullbắt buộcGross price in the market currency; null returns the market to the recalculated price
dryRunbooleantrue = preview, nothing is saved
Phản hồi 200 · application/json
object
receivedintegerbắt buộcalreadyPairedintegerbắt buộcpairedobject[]bắt buộcCác trường
skustringbắt buộcitemKeystringbắt buộcItem key in Itemooby"ean" | "catalogNo"bắt buộc
unmatchedobject[]bắt buộcCác trường
skustringbắt buộccatalogNostring | nullbắt buộceanstring | nullbắt buộc
conflictsobject[]bắt buộcCác trường
skustringbắt buộcreasonstringbắt buộc
appliedbooleanbắt buộcfalse for dryRunpricesobjectbắt buộcCác trường
updatedintegerbắt buộcerrorsobject[]bắt buộcCác trường
skustringbắt buộcreasonstringbắt buộc
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcCác trường
skustringbắt buộcqtyintegerbắt buộc
Phản hồi 200 · application/json
object
savedintegerbắt buộcsoldOutintegerbắt buộcItems that became unavailable (stock 0)reservedDeductedintegerbắt buộcUnits subtracted for unacknowledged ordersunknownSkustring[]bắt buộcSaved, but no item has this SKU yet — takes effect once paired in the panelerrorsobject[]bắt buộcCác trường
skustringbắt buộcreasonstringbắt buộc
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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ộcCác trường
skustringbắt buộclotstringbắt buộcproducedAtstringISO date (YYYY-MM-DD) or date-timeexpiresAtstringISO date (YYYY-MM-DD) or date-timeqtyinteger
Phản hồi 200 · application/json
object
createdintegerbắt buộcupdatedintegerbắt buộcunknownSkustring[]bắt buộcerrorsobject[]bắt buộcCác trường
skustringbắt buộclotstringbắt buộcreasonstringbắt buộc
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
updatedSincequery | 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 |
limitquery | string | 1–200, default 100 Ví dụ: 100 |
allquery | "true" | "false" | true = also orders that are not ready to fulfil (unpaid) |
unacknowledgedquery | "true" | "false" | true = only orders not acknowledged by the ERP yet |
Phản hồi 200 · application/json
object
ordersOrder[]bắt buộcCác trường · Order
orderNostringbắt buộcchannelstringbắt buộcapp | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erpexternalobject | nullbắt buộcThe order in the sales channel; null for brand shop ordersCác trường
orderIdstringbắt buộcmarketplacestringbắt buộcstatusstring | nullbắt buộc
fulfilledBy"merchant" | "marketplace"bắt buộcmarketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping onlycreatedAtstring (date-time)bắt buộcupdatedAtstring (date-time)bắt buộcpaymentobjectbắt buộcCác trường
status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộcmethod"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộconline = 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 channelpaidAtstring (date-time) | nullbắt buộcapproval"pending" | "approved" | "rejected" | nullbắt buộcB2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộcacknowledgedAtstring (date-time) | nullbắt buộcWhen the ERP acknowledged the order (POST /orders/ack)readyToShipbooleanbắt buộccurrencystringbắt buộctotalnumberbắt buộctotalNetnumber | nullbắt buộccustomerDiscountnumberbắt buộcbuyerTypestringbắt buộcconsumer | businessvatobjectbắt buộcCác trường
scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộcdomestic = 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 countrycollectedByMarketplacenumber | nullbắt buộccountrystring | nullbắt buộcexportbooleanbắt buộcbuyerVatIdstring | nullbắt buộcviesobject | nullbắt buộcCác trường
statusstringbắt buộcrequestIdstring | nullbắt buộccheckedAtstring (date-time) | nullbắt buộc
shippingCostnumberbắt buộcdiscountnumberbắt buộcpromoCodestring | nullbắt buộcpromoDiscountnumberbắt buộcbuyerobjectbắt buộcCác trường
emailstring | nullbắt buộcnamestring | nullbắt buộcphonestring | nullbắt buộcpersonalDataRemovedbooleanbắt buộctrue = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectbắt buộcCác trường
methodstring | nullbắt buộcaddressobjectbắt buộcCác trường
line1string | nullbắt buộcline2string | nullbắt buộcpostalstring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộc
pointobject | nullbắt buộcPickup point (code, name, address) when chosenCác trường
invoiceobject | nullbắt buộcInvoice data entered by the buyer (company, taxId, address)Các trường
notestring | nullbắt buộccarrierstring | nullbắt buộctrackingNostring | nullbắt buộcinvoiceDocumentobject | nullbắt buộcInvoice attached with PUT /orders/{orderNo}/invoiceCác trường
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring | nullbắt buộchasPdfbooleanbắt buộc
itemsOrderLine[]bắt buộcCác trường · OrderLine
skustring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcqtynumberbắt buộcunitPricenumberbắt buộcdiscountnumberbắt buộcPromotion and customer discount on the whole line (not per unit)customerDiscountnumberbắt buộcPart of the discount coming from the B2B customer discountvatRatestring | nullbắt buộcvatCountrystring | nullbắt buộcCountry of the VAT rate (OSS: the buyer country)netTotalnumber | nullbắt buộcNet value of the line after discountsgiftbooleanbắt buộclotsobject[]bắt buộcBatches the line shipped fromCác trường
lotstringbắt buộcqtynumberbắt buộc
unitsstring[]bắt buộcItemoo QR codes of the shipped units
nextstring (date-time) | nullbắt buộcPass as updatedSince to get the next page; null = no more pages
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
formatquery | "csv" | "xml" | csv by default |
ackquery | "true" | "false" | true = mark the downloaded orders as acknowledged |
unacknowledgedquery | "true" | "false" | true by default |
updatedSincequery | string (date-time) | Ví dụ: 2026-10-16T08:30:00.000Z |
allquery | "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
| 1 | order_no | Order number (orderNo) |
| 2 | created_at | Order date and time (ISO 8601) |
| 3 | payment_status | Payment status (payment.status) |
| 4 | payment_method | Payment method (payment.method) |
| 5 | fulfillment | Fulfillment status: new | packing | shipped | delivered | cancelled |
| 6 | buyer_name | Buyer name |
| 7 | buyer_email | Buyer email |
| 8 | buyer_phone | Buyer phone |
| 9 | address_line1 | Shipping address, first line |
| 10 | postal_code | Postal code |
| 11 | city | City |
| 12 | country | Country (ISO 3166-1 alpha-2) |
| 13 | pickup_point | Pickup point code or name |
| 14 | shipping_method | Shipping method |
| 15 | shipping_cost | Shipping cost |
| 16 | discount | Order discount total (promotion + code + customer discount) |
| 17 | total | Order total (gross) |
| 18 | invoice_company | Invoice: company name |
| 19 | invoice_tax_id | Invoice: tax id |
| 20 | note | Buyer note |
| 21 | sku | Line: SKU |
| 22 | catalog_no | Line: catalogue number |
| 23 | name | Line: name |
| 24 | qty | Line: quantity |
| 25 | unit_price | Line: unit price (gross) |
| 26 | line_discount | Line: discount on the whole line |
| 27 | gift | Line: true for a free gift, false otherwise |
| 28 | lots | Line: shipped batches as "LOT:qty LOT:qty" |
| 29 | vat_rate | Line: VAT rate (23 | 8 | 5 | 0 | exempt | outside_scope) |
| 30 | line_net | Line: net value after discounts |
| 31 | total_net | Order total (net) |
| 32 | customer_discount | Order: B2B customer discount |
| 33 | channel | Sales channel (app | site | marketplace:…) |
| 34 | channel_order_no | Order number in the sales channel |
| 35 | fulfilled_by | Who ships: merchant | marketplace |
XML
<orders>Root element<order orderNo createdAt channel channelOrderNo? fulfilledBy?>+One order · orderNo: Order number · createdAt: Order date and time (ISO 8601) · channel: Sales channel (app | site | marketplace:…) · channelOrderNo: Order number in the sales channel · fulfilledBy: "marketplace" when the channel warehouse ships; omitted for merchant<payment status method>Payment · status: payment.status · method: payment.method
<fulfillment>Fulfillment status
<buyer>Buyer<name>?Name
<email>?Email
<phone>?Phone
<shipping>Delivery<method>?Shipping method
<address>?Address, first line
<postalCode>?Postal code
<city>?City
<country>?Country (ISO 3166-1 alpha-2)
<pickupPoint>?Pickup point code or name
<cost>Shipping cost (decimal point, two decimals)
<invoice>?Invoice data — only when the buyer gave a tax id<company>?Company name
<taxId>Tax id
<note>?Buyer note
<discount>Order discount total (promotion + code + customer discount) (decimal point, two decimals)
<total>Order total (gross) (decimal point, two decimals)
<totalNet>?Order total (net) (decimal point, two decimals)
<customerDiscount>?B2B customer discount (decimal point, two decimals)
<items>Order lines<item>+One order line<sku>?SKU
<catalogNo>?Catalogue number
<name>Name
<qty>Quantity
<unitPrice>Unit price (gross) (decimal point, two decimals)
<discount>?Discount on the whole line (decimal point, two decimals)
<gift>?"true" for a free gift; omitted otherwise
<vatRate>?VAT rate (23 | 8 | 5 | 0 | exempt | outside_scope)
<netTotal>?Net value of the line after discounts (decimal point, two decimals)
<lot number qty>*Batch the line shipped from · number: Batch number · qty: Quantity from this batch
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcunknownstring[]bắt buộcOrder numbers that do not exist in the brand
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
orderNopath · bắt buộc | string | Ví dụ: ITM-2026-000123 |
Nội dung yêu cầu application/json
itemsobject[]bắt buộcCác trường
skustringbắt buộclotstringbắt buộcqtyintegerThe whole line quantity by default
Phản hồi 200 · application/json
object
savedintegerbắt buộcerrorsstring[]bắt buộcRows that were skipped, as human-readable messages
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
orderNopath · bắt buộc | string | Ví dụ: ITM-2026-000123 |
Nội dung yêu cầu application/json
itemsobject[]bắt buộcCác trường
skustringbắt buộccodesstring[]bắt buộcItemoo QR codes; an empty list removes the units
Phản hồi 200 · application/json
object
savedintegerbắt buộcerrorsstring[]bắt buộcRows that were skipped, as human-readable messages
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
orderNopath · bắt buộc | string | Ví dụ: ITM-2026-000123 |
Nội dung yêu cầu application/json
numberstringbắt buộcksefNumberstringissuedAtstringISO date (YYYY-MM-DD) or date-timepdfBase64stringPDF file as base64 — the whole request is limited to 2 MB, so about 1.4 MB of PDFnotifyCustomerbooleanfalse = no email to the customer
Phản hồi 200 · application/json
object
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring (date-time)bắt buộchasPdfbooleanbắt buộcnotifiedbooleanbắt buộcThe customer got an email with the invoice
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
orderNopath · 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ộccarrierstringtrackingNostringreasonstringCancellation reason shown to the customerlotsobject[]Batches shipped, like PUT /orders/{orderNo}/lotsCác trường
skustringbắt buộclotstringbắt buộcqtyintegerThe whole line quantity by default
Phản hồi 200 · application/json
OrderAfterStatusChange
orderNostringbắt buộcchannelstringbắt buộcapp | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erpexternalobject | nullbắt buộcThe order in the sales channel; null for brand shop ordersCác trường
orderIdstringbắt buộcmarketplacestringbắt buộcstatusstring | nullbắt buộc
fulfilledBy"merchant" | "marketplace"bắt buộcmarketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping onlycreatedAtstring (date-time)bắt buộcupdatedAtstring (date-time)bắt buộcpaymentobjectbắt buộcCác trường
status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộcmethod"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộconline = 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 channelpaidAtstring (date-time) | nullbắt buộcapproval"pending" | "approved" | "rejected" | nullbắt buộcB2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộcacknowledgedAtstring (date-time) | nullbắt buộcWhen the ERP acknowledged the order (POST /orders/ack)readyToShipbooleanbắt buộccurrencystringbắt buộctotalnumberbắt buộctotalNetnumber | nullbắt buộccustomerDiscountnumberbắt buộcbuyerTypestringbắt buộcconsumer | businessvatobjectbắt buộcCác trường
scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộcdomestic = 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 countrycollectedByMarketplacenumber | nullbắt buộccountrystring | nullbắt buộcexportbooleanbắt buộcbuyerVatIdstring | nullbắt buộcviesobject | nullbắt buộcCác trường
statusstringbắt buộcrequestIdstring | nullbắt buộccheckedAtstring (date-time) | nullbắt buộc
shippingCostnumberbắt buộcdiscountnumberbắt buộcpromoCodestring | nullbắt buộcpromoDiscountnumberbắt buộcbuyerobjectbắt buộcCác trường
emailstring | nullbắt buộcnamestring | nullbắt buộcphonestring | nullbắt buộcpersonalDataRemovedbooleanbắt buộctrue = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectbắt buộcCác trường
methodstring | nullbắt buộcaddressobjectbắt buộcCác trường
line1string | nullbắt buộcline2string | nullbắt buộcpostalstring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộc
pointobject | nullbắt buộcPickup point (code, name, address) when chosenCác trường
invoiceobject | nullbắt buộcInvoice data entered by the buyer (company, taxId, address)Các trường
notestring | nullbắt buộccarrierstring | nullbắt buộctrackingNostring | nullbắt buộcinvoiceDocumentobject | nullbắt buộcInvoice attached with PUT /orders/{orderNo}/invoiceCác trường
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring | nullbắt buộchasPdfbooleanbắt buộc
itemsOrderLine[]bắt buộcCác trường · OrderLine
skustring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcqtynumberbắt buộcunitPricenumberbắt buộcdiscountnumberbắt buộcPromotion and customer discount on the whole line (not per unit)customerDiscountnumberbắt buộcPart of the discount coming from the B2B customer discountvatRatestring | nullbắt buộcvatCountrystring | nullbắt buộcCountry of the VAT rate (OSS: the buyer country)netTotalnumber | nullbắt buộcNet value of the line after discountsgiftbooleanbắt buộclotsobject[]bắt buộcBatches the line shipped fromCác trường
lotstringbắt buộcqtynumberbắt buộc
unitsstring[]bắt buộcItemoo QR codes of the shipped units
unchangedtrueThe same status was sent again — nothing changed, no email
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
codepath · bắt buộc | string | Itemoo 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ộcrecipientstringName of the access grant usedversionPassportVersion | nullbắt buộcCác trường · PassportVersion
hashstringbắt buộcSHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain headlayersobject[]bắt buộcCác trường
subject"product" | "variant" | "batch" | "unit"bắt buộcversionintegerbắt buộchashstringbắt buộc
eventsHeadstring | nullbắt buộcatstring (date-time)Present for a passport read at a point in time (?at=)
backupobject | nullbắt buộcBackup copy of the passport kept by a DPP service provider (Regulation (EU) 2024/1781 Annex III point (l)), when the brand designated oneCác trường
providerstringbắt buộcurlstringbắt buộc
identityProductIdentitybắt buộcCác trường · ProductIdentity
codestringbắt buộcItemoo code from the QR labellevel"unit" | "batch" | "variant" | "model"bắt buộcgtinstring | nullbắt buộcskustring | nullbắt buộcvariantobjectCác trường
labelstringbắt buộccatalogNostring | nullbắt buộc
lotstring | nullbắt buộcserialstring | nullbắt buộcexpiresAtstring (date-time) | nullbắt buộcstatusstringbắt buộcBatch status: ACTIVE | RECALLED | …uniqueProductIdentifierstringbắt buộcUnique 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ộcCác trường · ProductSummary
namestringbắt buộcbrandstringbắt buộccategory"chemicals" | "cosmetics" | "medical" | "food" | "supplements" | "electronics" | "appliances" | "batteries" | "textiles" | "furniture" | "toys" | "construction" | "other" | nullbắt buộcRegulatory product type — decides the mandatory information: chemicals | cosmetics | medical | food | supplements | electronics | appliances | batteries | textiles | furniture | toys | construction | otherdescriptionstringbắt buộcimagestringtranslationsobjectName and description in every language the brand provides (ISO 639-1 code → text);nameanddescriptionabove are in the language of the responseCác trường
namemap<string, string>bắt buộcdescriptionmap<string, string>bắt buộc
manufacturerEconomicOperator | nullbắt buộcCác trường · EconomicOperator
namestringbắt buộcaddressobjectbắt buộcCác trường
streetstring | nullbắt buộcpostalCodestring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộcISO 3166-1 alpha-2
emailstring | nullbắt buộcphonestring | nullbắt buộcShown only at the access level the brand chose for it (default: persons with a legitimate interest)source"company" | "registry"bắt buộccompany = the brand company data; registry = an operator from the company operator register designated in the passporttradeNamestring | nullRegistered 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ộcgln = 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 agencyiacstringIssuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vatvaluestringbắt buộc
eoristring | nullEORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
responsiblePersonEconomicOperator | nullbắt buộcCác trường · EconomicOperator
namestringbắt buộcaddressobjectbắt buộcCác trường
streetstring | nullbắt buộcpostalCodestring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộcISO 3166-1 alpha-2
emailstring | nullbắt buộcphonestring | nullbắt buộcShown only at the access level the brand chose for it (default: persons with a legitimate interest)source"company" | "registry"bắt buộccompany = the brand company data; registry = an operator from the company operator register designated in the passporttradeNamestring | nullRegistered 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ộcgln = 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 agencyiacstringIssuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vatvaluestringbắt buộc
eoristring | nullEORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
importerEconomicOperator | nullbắt buộcCác trường · EconomicOperator
namestringbắt buộcaddressobjectbắt buộcCác trường
streetstring | nullbắt buộcpostalCodestring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộcISO 3166-1 alpha-2
emailstring | nullbắt buộcphonestring | nullbắt buộcShown only at the access level the brand chose for it (default: persons with a legitimate interest)source"company" | "registry"bắt buộccompany = the brand company data; registry = an operator from the company operator register designated in the passporttradeNamestring | nullRegistered 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ộcgln = 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 agencyiacstringIssuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vatvaluestringbắt buộc
eoristring | nullEORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
authorisedRepresentativeEconomicOperator | nullbắt buộcCác trường · EconomicOperator
namestringbắt buộcaddressobjectbắt buộcCác trường
streetstring | nullbắt buộcpostalCodestring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộcISO 3166-1 alpha-2
emailstring | nullbắt buộcphonestring | nullbắt buộcShown only at the access level the brand chose for it (default: persons with a legitimate interest)source"company" | "registry"bắt buộccompany = the brand company data; registry = an operator from the company operator register designated in the passporttradeNamestring | nullRegistered 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ộcgln = 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 agencyiacstringIssuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vatvaluestringbắt buộc
eoristring | nullEORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
facilityEconomicOperator | nullbắt buộcCác trường · EconomicOperator
namestringbắt buộcaddressobjectbắt buộcCác trường
streetstring | nullbắt buộcpostalCodestring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộcISO 3166-1 alpha-2
emailstring | nullbắt buộcphonestring | nullbắt buộcShown only at the access level the brand chose for it (default: persons with a legitimate interest)source"company" | "registry"bắt buộccompany = the brand company data; registry = an operator from the company operator register designated in the passporttradeNamestring | nullRegistered 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ộcgln = 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 agencyiacstringIssuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vatvaluestringbắt buộc
eoristring | nullEORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
languagestringbắt buộcpublishedbooleanbắt buộcrecallRecall | nullbắt buộcCác trường · Recall
activetruebắt buộccertainbooleanbắt buộctrue = this exact code is recalled; false = the batch is unknown and may be affectedscope"product" | "batch" | "lotRange"bắt buộcproduct = the whole product; batch = one batch; lotRange = a range of batch numbers (lotFrom–lotTo)reasonstringbắt buộcinstructionsstring | nullbắt buộclotFromstring | nullbắt buộclotTostring | nullbắt buộckind"recall" | "notice"recall = the product is recalled; notice = safety notice, the product is not withdrawn
factsProvenanceFact[]bắt buộcCác trường · ProvenanceFact
keystringStable 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 namenamestringbắt buộcFact name in the response languagevaluestringbắt buộcprovenanceobjectCác trường
sourcestringbắt buộcDocument or block the fact comes fromversionstringdocumentUrlstringassertedBystringbắt buộcBrand that published the factassertedAtstring
documentsDocument[]bắt buộcCác trường · Document
titlestringbắt buộcurlstringbắt buộckindstringbắt buộccertificate | declaration | repair | dpp | manual | sds | …versionstringaccessstringpublic | legit | authority — present on documents beyond the public leveldocIdstringLibrary document identifier — the same as in{ docId }values of document fieldslanguagestringLanguage 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ộcComponents 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ộcItemoo code of the component passport (unit, batch, variant or model — also of another brand)uristring | nullbắt buộcAddress of a component passport outside Itemoo (DPP URL or GS1 Digital Link)urlstringbắt buộcWhere to read the component passportrolestring | nullbắt buộcnameanybắt buộcquantitynumber | nullbắt buộcunitstring | nullbắt buộclevel"model" | "unit"bắt buộcmodel — bill of components of the model; unit — installed in this unit (assembly events)sincestring | nullbắt buộcWhen the component was installed in this unit
lifecycleobjectbắt buộcLifecycle 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 410Các trường
status"active" | "recalled" | "end_of_life" | "archived" | "closed"bắt buộcsincestring (date-time) | nullbắt buộc
modelobjectbắt buộcModel passport fields visible at this levelunitobject | nullbắt buộcCác trường
serialstring | nullbắt buộcdataobjectbắt buộcstateobjectbắt buộcCác trường
statusstring | nullbắt buộcoriginal | 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ộcState of health, 0–100 (SoH, or SOCE / remaining capacity when only that is recorded)sohAtstring (date-time) | nullbắt buộccyclesnumber | nullbắt buộcincidentsintegerbắt buộc
historyobject[]bắt buộcCác trường
kindstringbắt buộcdataanybắt buộcoccurredAtstring (date-time)bắt buộcsourcestring
linksobjectbắt buộcCác trường
predecessorobject | nullbắt buộcPassport before remanufacturing or repurposing (Art. 77(7))Các trường
codestringbắt buộcurlstringbắt buộc
successorsobject[]bắt buộcNew passports created from this batteryCác trường
codestringbắt buộcurlstringbắt buộc
custodianobject | nullbắt buộcOperator 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ộcrolestringbắt buộcsincestring (date-time)bắt buộc
fieldsobjectbắt buộcEditable fields with their access levels, per layerCác trường
modelmap<string, object>bắt buộcCác trường
valueanybắt buộcaccess"public" | "legit" | "authority"bắt buộc
variantmap<string, object> | nullbắt buộcVariant layer (overrides the model)Các trường
valueanybắt buộcaccess"public" | "legit" | "authority"bắt buộc
batchmap<string, object> | nullbắt buộcBatch layer (inherited by units)Các trường
valueanybắt buộcaccess"public" | "legit" | "authority"bắt buộc
unitmap<string, object> | nullbắt buộcCác trường
valueanybắt buộcaccess"public" | "legit" | "authority"bắt buộc
unitMetaobject | nullbắt buộcUnit dates: code activation and placing on the market; predecessor passport codeCác trường
statusstringbắt buộcactivatedAtstring (date-time) | nullbắt buộcplacedOnMarketAtstring (date-time) | nullbắt buộcpredecessorCodestring | nullbắt buộc
versionsany[]bắt buộcVersion history of all layers with pseudonymous authors (see the public PassportHistory)chainmap<string, integer | null>bắt buộcPer layer: number of the first version whose hash does not verify, null = intact
Lỗi
| 401 |
|
| 403 |
|
| 404 |
|
| 410 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
codepath · bắt buộc | string | Itemoo code of a unit, batch, variant or product Ví dụ: A1B2C3D4 |
Phản hồi 200 · application/ld+json
object
@contextstringbắt buộcidstringbắt buộctype"Product"bắt buộcpassportobjectbắt buộcCác trường
type"DigitalProductPassport"bắt buộc
Lỗi
| 401 |
|
| 403 |
|
| 404 |
|
| 410 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
codepath · bắt buộc | string | Itemoo code of a unit, batch, variant or product Ví dụ: A1B2C3D4 |
Phản hồi 200 · application/json
PassportHistory
codestringbắt buộclevel"public" | "legit" | "authority"bắt buộcversionPassportVersion | nullbắt buộcCác trường · PassportVersion
hashstringbắt buộcSHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain headlayersobject[]bắt buộcCác trường
subject"product" | "variant" | "batch" | "unit"bắt buộcversionintegerbắt buộchashstringbắt buộc
eventsHeadstring | nullbắt buộcatstring (date-time)Present for a passport read at a point in time (?at=)
versionsobject[]bắt buộcCác trường
subject"product" | "variant" | "batch" | "unit"bắt buộcversionintegerbắt buộchashstringbắt buộcprevHashstring | nullbắt buộcatstring (date-time)bắt buộcsourcestringbắt buộcchangesobject[]bắt buộcCác trường
keystringbắt buộcop"add" | "change" | "remove"bắt buộcvalueanyredactedboolean
leavesmap<string, object>Leaf hashes (authority level only) to recompute the version hashCác trường
hstringbắt buộcaccess"public" | "legit" | "authority"bắt buộc
Lỗi
| 401 |
|
| 403 |
|
| 404 |
|
| 410 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
cursorquery | string | The cursor of the previous page (opaque); without it — the first page |
Phản hồi 200 · application/json
object
itemsobject[]bắt buộcCác trường
@contextstringbắt buộcidstringbắt buộc
cursorstring | nullbắt buộcThe cursor of the next page, null on the last one
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
skupath · bắt buộc | string | Product (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 fieldCác trường
valueanybắt buộcaccess"public" | "legit" | "authority"
Phản hồi 200 · application/json
object
productIdstringbắt buộcskustring | nullbắt buộcfieldsmap<string, object>bắt buộcCác trường
valueanybắt buộcaccess"public" | "legit" | "authority"bắt buộc
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ộcCác trường
codestringItemoo code of the unit — or sku + serialskustringserialstringdatamap<string, any | object>Unit fields; battery passport keys (battery.*) follow the field dictionary and have a fixed access levelCác trường
valueanybắt buộcaccess"public" | "legit" | "authority"
placedOnMarketAtstring | nullDate 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ộcsavedintegerbắt buộcunknownstring[]bắt buộcerrorsobject[]bắt buộcCác trường
rowintegerbắt buộccodestringbắt buộc
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
codepath · bắt buộc | string | Itemoo 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ộcassembly — component with its own passport installed or removed: data { action: install | remove, code (Itemoo code) or uri (https passport address), role? }dataobjectbắt buộcoccurredAtstring (date-time)Not in the future; now by defaultaccess"public" | "legit" | "authority"public for status by default, legit otherwise
Phản hồi 200 · application/json
object
idstringbắt buộccodestringbắt buộckindstringbắt buộcdataanybắt buộcaccessstringbắt buộcoccurredAtstring (date-time)bắt buộchashstring | nullbắt buộcSHA-256 of the event chained with the previous one (RFC 8785)
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 429 |
|
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ường | Kiểu | Mô tả |
|---|---|---|
productpath · bắt buộc | string | Product id, Itemoo code or SKU Ví dụ: KAW-250 |
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
productpath · bắt buộc | string | Product id, Itemoo code or SKU Ví dụ: KAW-250 |
Nội dung yêu cầu application/json
draftRevisionstringbắt buộcdraftRevisionfrom the last read; if the draft changed since, the call fails withdraftConflict— read againoperationsobject[]bắt buộcOperations applied in order; indexes refer to the page after the previous operationsdryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcCác trường
namestringbắt buộcProduct nameskustringbắt buộcSKU — unique in the brandcategorystringbắt buộcProduct category key (e.g. "chemicals")gtinstringGTIN / EAN (8–14 digits)operationsobject[]Optional text operations on the starting page (as inproduct_page_draft_patch)
langstringLanguage of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for reviewdryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcdraftRevisionfrom the last read; if the draft changed since, the call fails withdraftConflict— read againoperationsobject[]bắt buộcOperations applied in order; only theme, pages, navigation and seo, never legal pages or legal linksdryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
idpath · bắt buộc | string | Id of the post, article or campaign Ví dụ: post-ai-x7Kp2 |
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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
idstringExisting post id (edit); omit to createdraftRevisionstringdraftRevisionfrom the last read; if the draft changed since, the call fails withdraftConflict— read againtitlestringbắt buộcWorking name in the calendarmessagestringbắt buộcMain message of the postheadlinestringText on the graphictemplate"product" | "teaser" | "free"Graphic template; default: product when products are given, otherwise freeproductCodesstring[]Itemoo codes of the products in the postscheduledAtstring (date-time)Planned publication time (ISO 8601)variantsobject[]Các trường
platform"facebook" | "instagram" | "linkedin" | "tiktok"bắt buộctextstringbắt buộcPost text for this platformhashtagsstring[]altTextstringAlternative text of the graphic
dryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
idpath · bắt buộc | string | Id of the post, article or campaign Ví dụ: post-ai-x7Kp2 |
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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
idstringExisting draft article id; omit to createdraftRevisionstringdraftRevisionfrom the last read; if the draft changed since, the call fails withdraftConflict— read againlangstringLanguage of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for reviewtitlestringTitleexcerptstringShort summarybodystringBody: paragraphs separated by an empty line, "## " for subheadingscategorystringslugstringproductCodesstring[]dryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ường | Kiểu | Mô tả |
|---|---|---|
idpath · bắt buộc | string | Id of the post, article or campaign Ví dụ: post-ai-x7Kp2 |
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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
idstringExisting draft campaign id; omit to createdraftRevisionstringdraftRevisionfrom the last read; if the draft changed since, the call fails withdraftConflict— read againlangstringLanguage of the texts (two letters); default: the brand default language. Texts in other languages are marked as machine-written for reviewnamestringInternal nametitlestringNotification titlebodystringNotification texttargetobjectWhere the button leads; default: the brand appCác trường
type"app" | "product" | "group"bắt buộccodestringProduct code for type "product"groupstringShop category for type "group"
countriesstring[]productCodesstring[]Only people who scanned these products; empty = everyone with consentpushbooleanemailbooleandryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
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ộcidstringbắt buộcProduct id/code/SKU for productPage; otherwise the post, article or campaign iddryRunbooleanDefault true: nothing is saved — the result shows what would change and aplanToken. Ask the user, then call again with the SAME arguments,dryRun: falseand thatplanToken.planTokenstringplanTokenfrom the preview of exactly these arguments (required withdryRun: false, valid 10 minutes)
Phản hồi 200 · application/json
object
Lỗi
| 400 |
|
| 401 |
|
| 403 |
|
| 404 |
|
| 409 |
|
| 429 |
|
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);Dùng thử
Từ trình duyệt, chúng tôi chỉ gửi yêu cầu đọc và xem trước (dryRun). Khóa chỉ ở lại trong thẻ này — chúng tôi không bao giờ lưu nó.
Không thể gửi yêu cầu.
Dán khóa của riêng bạn để thử endpoint này.
Thông báo (webhook)
postorder.ready
Order ready to fulfil
idstringbắt buộcDelivery id — the same on retries; use it to ignore duplicatesevent"order.ready" | "order.cancelled" | "order.updated"bắt buộccreatedAtstring (date-time)bắt buộcdataOrderbắt buộcCác trường · Order
orderNostringbắt buộcchannelstringbắt buộcapp | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erpexternalobject | nullbắt buộcThe order in the sales channel; null for brand shop ordersCác trường
orderIdstringbắt buộcmarketplacestringbắt buộcstatusstring | nullbắt buộc
fulfilledBy"merchant" | "marketplace"bắt buộcmarketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping onlycreatedAtstring (date-time)bắt buộcupdatedAtstring (date-time)bắt buộcpaymentobjectbắt buộcCác trường
status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộcmethod"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộconline = 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 channelpaidAtstring (date-time) | nullbắt buộcapproval"pending" | "approved" | "rejected" | nullbắt buộcB2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộcacknowledgedAtstring (date-time) | nullbắt buộcWhen the ERP acknowledged the order (POST /orders/ack)readyToShipbooleanbắt buộccurrencystringbắt buộctotalnumberbắt buộctotalNetnumber | nullbắt buộccustomerDiscountnumberbắt buộcbuyerTypestringbắt buộcconsumer | businessvatobjectbắt buộcCác trường
scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộcdomestic = 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 countrycollectedByMarketplacenumber | nullbắt buộccountrystring | nullbắt buộcexportbooleanbắt buộcbuyerVatIdstring | nullbắt buộcviesobject | nullbắt buộcCác trường
statusstringbắt buộcrequestIdstring | nullbắt buộccheckedAtstring (date-time) | nullbắt buộc
shippingCostnumberbắt buộcdiscountnumberbắt buộcpromoCodestring | nullbắt buộcpromoDiscountnumberbắt buộcbuyerobjectbắt buộcCác trường
emailstring | nullbắt buộcnamestring | nullbắt buộcphonestring | nullbắt buộcpersonalDataRemovedbooleanbắt buộctrue = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectbắt buộcCác trường
methodstring | nullbắt buộcaddressobjectbắt buộcCác trường
line1string | nullbắt buộcline2string | nullbắt buộcpostalstring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộc
pointobject | nullbắt buộcPickup point (code, name, address) when chosenCác trường
invoiceobject | nullbắt buộcInvoice data entered by the buyer (company, taxId, address)Các trường
notestring | nullbắt buộccarrierstring | nullbắt buộctrackingNostring | nullbắt buộcinvoiceDocumentobject | nullbắt buộcInvoice attached with PUT /orders/{orderNo}/invoiceCác trường
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring | nullbắt buộchasPdfbooleanbắt buộc
itemsOrderLine[]bắt buộcCác trường · OrderLine
skustring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcqtynumberbắt buộcunitPricenumberbắt buộcdiscountnumberbắt buộcPromotion and customer discount on the whole line (not per unit)customerDiscountnumberbắt buộcPart of the discount coming from the B2B customer discountvatRatestring | nullbắt buộcvatCountrystring | nullbắt buộcCountry of the VAT rate (OSS: the buyer country)netTotalnumber | nullbắt buộcNet value of the line after discountsgiftbooleanbắt buộclotsobject[]bắt buộcBatches the line shipped fromCác trường
lotstringbắt buộcqtynumberbắt buộc
unitsstring[]bắt buộcItemoo QR codes of the shipped units
postorder.cancelled
Order cancelled
idstringbắt buộcDelivery id — the same on retries; use it to ignore duplicatesevent"order.ready" | "order.cancelled" | "order.updated"bắt buộccreatedAtstring (date-time)bắt buộcdataOrderbắt buộcCác trường · Order
orderNostringbắt buộcchannelstringbắt buộcapp | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erpexternalobject | nullbắt buộcThe order in the sales channel; null for brand shop ordersCác trường
orderIdstringbắt buộcmarketplacestringbắt buộcstatusstring | nullbắt buộc
fulfilledBy"merchant" | "marketplace"bắt buộcmarketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping onlycreatedAtstring (date-time)bắt buộcupdatedAtstring (date-time)bắt buộcpaymentobjectbắt buộcCác trường
status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộcmethod"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộconline = 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 channelpaidAtstring (date-time) | nullbắt buộcapproval"pending" | "approved" | "rejected" | nullbắt buộcB2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộcacknowledgedAtstring (date-time) | nullbắt buộcWhen the ERP acknowledged the order (POST /orders/ack)readyToShipbooleanbắt buộccurrencystringbắt buộctotalnumberbắt buộctotalNetnumber | nullbắt buộccustomerDiscountnumberbắt buộcbuyerTypestringbắt buộcconsumer | businessvatobjectbắt buộcCác trường
scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộcdomestic = 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 countrycollectedByMarketplacenumber | nullbắt buộccountrystring | nullbắt buộcexportbooleanbắt buộcbuyerVatIdstring | nullbắt buộcviesobject | nullbắt buộcCác trường
statusstringbắt buộcrequestIdstring | nullbắt buộccheckedAtstring (date-time) | nullbắt buộc
shippingCostnumberbắt buộcdiscountnumberbắt buộcpromoCodestring | nullbắt buộcpromoDiscountnumberbắt buộcbuyerobjectbắt buộcCác trường
emailstring | nullbắt buộcnamestring | nullbắt buộcphonestring | nullbắt buộcpersonalDataRemovedbooleanbắt buộctrue = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectbắt buộcCác trường
methodstring | nullbắt buộcaddressobjectbắt buộcCác trường
line1string | nullbắt buộcline2string | nullbắt buộcpostalstring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộc
pointobject | nullbắt buộcPickup point (code, name, address) when chosenCác trường
invoiceobject | nullbắt buộcInvoice data entered by the buyer (company, taxId, address)Các trường
notestring | nullbắt buộccarrierstring | nullbắt buộctrackingNostring | nullbắt buộcinvoiceDocumentobject | nullbắt buộcInvoice attached with PUT /orders/{orderNo}/invoiceCác trường
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring | nullbắt buộchasPdfbooleanbắt buộc
itemsOrderLine[]bắt buộcCác trường · OrderLine
skustring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcqtynumberbắt buộcunitPricenumberbắt buộcdiscountnumberbắt buộcPromotion and customer discount on the whole line (not per unit)customerDiscountnumberbắt buộcPart of the discount coming from the B2B customer discountvatRatestring | nullbắt buộcvatCountrystring | nullbắt buộcCountry of the VAT rate (OSS: the buyer country)netTotalnumber | nullbắt buộcNet value of the line after discountsgiftbooleanbắt buộclotsobject[]bắt buộcBatches the line shipped fromCác trường
lotstringbắt buộcqtynumberbắt buộc
unitsstring[]bắt buộcItemoo QR codes of the shipped units
postorder.updated
Fulfilment changed
idstringbắt buộcDelivery id — the same on retries; use it to ignore duplicatesevent"order.ready" | "order.cancelled" | "order.updated"bắt buộccreatedAtstring (date-time)bắt buộcdataOrderbắt buộcCác trường · Order
orderNostringbắt buộcchannelstringbắt buộcapp | site | marketplace:allegro | marketplace:ebay | marketplace:amazon | erpexternalobject | nullbắt buộcThe order in the sales channel; null for brand shop ordersCác trường
orderIdstringbắt buộcmarketplacestringbắt buộcstatusstring | nullbắt buộc
fulfilledBy"merchant" | "marketplace"bắt buộcmarketplace = shipped by the channel warehouse (e.g. FBA) — for bookkeeping onlycreatedAtstring (date-time)bắt buộcupdatedAtstring (date-time)bắt buộcpaymentobjectbắt buộcCác trường
status"pending" | "paid" | "failed" | "expired" | "refunded"bắt buộcmethod"online" | "transfer" | "on_delivery" | "on_pickup" | "deferred" | "marketplace"bắt buộconline = 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 channelpaidAtstring (date-time) | nullbắt buộcapproval"pending" | "approved" | "rejected" | nullbắt buộcB2B deferred payment over the limit
fulfillment"new" | "packing" | "shipped" | "delivered" | "cancelled"bắt buộcacknowledgedAtstring (date-time) | nullbắt buộcWhen the ERP acknowledged the order (POST /orders/ack)readyToShipbooleanbắt buộccurrencystringbắt buộctotalnumberbắt buộctotalNetnumber | nullbắt buộccustomerDiscountnumberbắt buộcbuyerTypestringbắt buộcconsumer | businessvatobjectbắt buộcCác trường
scheme"domestic" | "eu-domestic" | "oss" | "intra-eu" | "export" | "marketplace-collected" | "local"bắt buộcdomestic = 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 countrycollectedByMarketplacenumber | nullbắt buộccountrystring | nullbắt buộcexportbooleanbắt buộcbuyerVatIdstring | nullbắt buộcviesobject | nullbắt buộcCác trường
statusstringbắt buộcrequestIdstring | nullbắt buộccheckedAtstring (date-time) | nullbắt buộc
shippingCostnumberbắt buộcdiscountnumberbắt buộcpromoCodestring | nullbắt buộcpromoDiscountnumberbắt buộcbuyerobjectbắt buộcCác trường
emailstring | nullbắt buộcnamestring | nullbắt buộcphonestring | nullbắt buộcpersonalDataRemovedbooleanbắt buộctrue = personal data was erased (GDPR or the sales channel retention); amounts and lines stay
shippingobjectbắt buộcCác trường
methodstring | nullbắt buộcaddressobjectbắt buộcCác trường
line1string | nullbắt buộcline2string | nullbắt buộcpostalstring | nullbắt buộccitystring | nullbắt buộccountrystring | nullbắt buộc
pointobject | nullbắt buộcPickup point (code, name, address) when chosenCác trường
invoiceobject | nullbắt buộcInvoice data entered by the buyer (company, taxId, address)Các trường
notestring | nullbắt buộccarrierstring | nullbắt buộctrackingNostring | nullbắt buộcinvoiceDocumentobject | nullbắt buộcInvoice attached with PUT /orders/{orderNo}/invoiceCác trường
numberstringbắt buộcksefNumberstring | nullbắt buộcissuedAtstring | nullbắt buộchasPdfbooleanbắt buộc
itemsOrderLine[]bắt buộcCác trường · OrderLine
skustring | nullbắt buộccatalogNostring | nullbắt buộcnamestringbắt buộcqtynumberbắt buộcunitPricenumberbắt buộcdiscountnumberbắt buộcPromotion and customer discount on the whole line (not per unit)customerDiscountnumberbắt buộcPart of the discount coming from the B2B customer discountvatRatestring | nullbắt buộcvatCountrystring | nullbắt buộcCountry of the VAT rate (OSS: the buyer country)netTotalnumber | nullbắt buộcNet value of the line after discountsgiftbooleanbắt buộclotsobject[]bắt buộcBatches the line shipped fromCác trường
lotstringbắt buộcqtynumberbắt buộc
unitsstring[]bắt buộcItemoo 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));
}