curl --request POST \
--url https://app.polygon-one.com/api/v1/articles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Pine plank 20 mm",
"shortDescription": "Kiln-dried pine plank, 20 × 100 × 2400 mm",
"internalArticleNr": "ART-1001",
"hsCode": "4407.11",
"articleType": "purchase",
"weightPerPieceKg": 2.5,
"supplierId": "5a1d8c3e-7f24-4b9a-a6e0-1c3f5b8d2e94"
}
'{
"article": {
"id": "7c4e2b19-3a85-4d6f-b210-8e9a5c1d7f36",
"name": "Pine plank 20 mm",
"shortDescription": "Kiln-dried pine plank, 20 × 100 × 2400 mm",
"internalArticleNr": "ART-1001",
"externalArticleNr": null,
"ean": null,
"hsCode": "4407.11",
"articleType": "purchase",
"sourceScope": "standing",
"eudrRelevant": true,
"commodityGroup": "wood",
"needsManualCheck": false,
"hsPlausibility": null,
"deletedAt": null
}
}{
"jobId": "d2f7a4c9-8e15-4b63-9a2d-1c6e5f0b8d37",
"status": "queued",
"statusUrl": "/api/import-jobs/d2f7a4c9-8e15-4b63-9a2d-1c6e5f0b8d37"
}{
"error": "Validation failed",
"details": [
{
"origin": "string",
"code": "too_small",
"minimum": 1,
"inclusive": true,
"path": [
"address",
"street"
],
"message": "Address is required."
}
]
}{
"error": "Invalid or expired API key"
}{
"error": "Forbidden"
}{
"error": "Article has unresolved warnings. Resubmit with acknowledgeWarnings=true to override.",
"warnings": [
{
"type": "duplicateName",
"existingInternalArticleNr": "ART-0999"
}
]
}{
"error": "batchTooLarge",
"maxBatchSize": 5000
}{
"error": {
"code": "rate_limited",
"message": "…"
}
}{
"error": "Internal server error"
}Create Article
Create a single article (synchronous), or bulk-import articles (asynchronous). For purchase articles, a supplier must be specified (via supplierId or supplierName). Sale articles are automatically linked to your company. Batch rows upsert idempotently on internalArticleNr. Batch form (array, or {"rows": […]} envelope, max 5000 rows) is asynchronous: it stages an import job and returns 202 with a jobId — poll GET /api/v1/import-jobs/{jobId} for progress and the final result. A single object stays synchronous (201). See the Batch Import guide.
curl --request POST \
--url https://app.polygon-one.com/api/v1/articles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Pine plank 20 mm",
"shortDescription": "Kiln-dried pine plank, 20 × 100 × 2400 mm",
"internalArticleNr": "ART-1001",
"hsCode": "4407.11",
"articleType": "purchase",
"weightPerPieceKg": 2.5,
"supplierId": "5a1d8c3e-7f24-4b9a-a6e0-1c3f5b8d2e94"
}
'{
"article": {
"id": "7c4e2b19-3a85-4d6f-b210-8e9a5c1d7f36",
"name": "Pine plank 20 mm",
"shortDescription": "Kiln-dried pine plank, 20 × 100 × 2400 mm",
"internalArticleNr": "ART-1001",
"externalArticleNr": null,
"ean": null,
"hsCode": "4407.11",
"articleType": "purchase",
"sourceScope": "standing",
"eudrRelevant": true,
"commodityGroup": "wood",
"needsManualCheck": false,
"hsPlausibility": null,
"deletedAt": null
}
}{
"jobId": "d2f7a4c9-8e15-4b63-9a2d-1c6e5f0b8d37",
"status": "queued",
"statusUrl": "/api/import-jobs/d2f7a4c9-8e15-4b63-9a2d-1c6e5f0b8d37"
}{
"error": "Validation failed",
"details": [
{
"origin": "string",
"code": "too_small",
"minimum": 1,
"inclusive": true,
"path": [
"address",
"street"
],
"message": "Address is required."
}
]
}{
"error": "Invalid or expired API key"
}{
"error": "Forbidden"
}{
"error": "Article has unresolved warnings. Resubmit with acknowledgeWarnings=true to override.",
"warnings": [
{
"type": "duplicateName",
"existingInternalArticleNr": "ART-0999"
}
]
}{
"error": "batchTooLarge",
"maxBatchSize": 5000
}{
"error": {
"code": "rate_limited",
"message": "…"
}
}{
"error": "Internal server error"
}Authorizations
API key generated in Settings > API Keys. Include as Authorization: Bearer <key>.
Body
- Option 1 · object
- Option 2 · object[]
- Option 3 · object
Article name
1Internal article number (must be unique per company)
1HS code — EUDR relevance and commodity group are determined automatically
1Short description of the article.
Defaults to purchase. Sale articles are automatically linked to your company as supplier.
purchase, sale External article number, e.g. a supplier's or customer's number.
EAN / GTIN barcode.
Weight of one piece in kg; must be greater than 0. Lets order lines be sent as a piece count.
standing (default): the source is fixed. perOrder: the source varies per order and order import creates one copy of the article per order.
standing, perOrder Link to an existing supplier (recommended — fetch IDs via GET /api/v1/suppliers). Required for purchase articles if supplierName is not provided.
Fallback when you have no supplierId (prefer supplierId). Matched against your existing suppliers ignoring case and surrounding/repeated whitespace; if none matches, a new supplier is created. Required for purchase articles if supplierId is not provided.
Optional supplier contact email. Used when creating a new supplier via supplierName.
Explicit EUDR classification; overrides the one derived from the HS code.
Explicit EUDR commodity group; overrides the one derived from the HS code.
cattle, cocoa, coffee, oil_palm, rubber, soya, wood, non_relevant Set to true to override soft duplicate warnings. If omitted/false and the article triggers a soft warning (duplicate name or duplicate EAN), the request returns 409 with a machine-readable warnings array instead of creating the article. A hard duplicate of internalArticleNr always returns 409 and cannot be overridden.
Response
Article created successfully (single)
The stored article fields. Further keys may be present and are not part of the contract; read the full article with GET /api/v1/articles/{id}.
Show child attributes
Show child attributes