Skip to content
AzimeaDocs
Dashboard

Create or update many catalogue items

POST
/items/batch
curl --request POST \
--url https://api.azimea.com/v1/items/batch \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "items": [ { "id": "plan-pro", "kind": "plan", "name": "Pro plan", "description": "Unlimited projects and priority support.", "url": "https://example.com/pricing#pro", "imageUrl": "https://example.com/img/pro.png", "price": 49, "comparePrice": 59, "currency": "EUR", "inStock": true, "stockQuantity": null, "categories": [ "plans" ], "attributes": { "billing": "monthly", "seats": 5 }, "active": true } ] }'

The same as POST /items for up to 1,000 items in one call, which counts as a single call for the rate limit. Each item is written or refused on its own: the answer counts the created, updated and failed items and gives one result per item, by its position in the request, with the reasons as catalog.* codes. More than 1,000 items refuses the whole call with catalog.batch_too_large. Needs the items:write permission.

Media typeapplication/json
object
items

The items to write, up to 1,000. Each is written exactly as POST /items would write it.

Array<object>
nullable
object
id

Required. Your own id for the item, at most 100 characters. Sending the same id again updates the item.

string
nullable
Example
plan-pro
kind

product, plan, service or other. A new item is a product unless you say otherwise.

string
nullable
Example
plan
name

Required, at most 300 characters.

string
nullable
Example
Pro plan
description

At most 5,000 characters.

string
nullable
Example
Unlimited projects and priority support.
url

A full address starting with https://, at most 2,000 characters.

string
nullable
Example
https://example.com/pricing#pro
imageUrl

A full address starting with https://, at most 2,000 characters.

string
nullable
Example
https://example.com/img/pro.png
price

Zero or more.

number format: decimal
nullable
Example
49
comparePrice

The price before a discount. Must be higher than price.

number format: decimal
nullable
Example
59
currency

The three-letter currency code, such as EUR or GBP.

string
nullable
Example
EUR
inStock

A new item is in stock unless you say otherwise.

boolean
nullable
Example
true
stockQuantity

A whole number of zero or more.

integer format: int32
nullable
Example
null
categories

At most 20, each a short name.

Array<string>
nullable
Example
[
"plans"
]
attributes

At most 50 fields, each a short lowercase key with a text, number or yes/no value.

object
key
additional properties
Example
{
"billing": "monthly",
"seats": 5
}
active

A new item is active. false stops recommending it but keeps its history.

boolean
nullable
Example
true
Example
{
"id": "plan-pro",
"kind": "plan",
"name": "Pro plan",
"description": "Unlimited projects and priority support.",
"url": "https://example.com/pricing#pro",
"imageUrl": "https://example.com/img/pro.png",
"price": 49,
"comparePrice": 59,
"currency": "EUR",
"inStock": true,
"stockQuantity": null,
"categories": [
"plans"
],
"attributes": {
"billing": "monthly",
"seats": 5
},
"active": true
}
Example
[
{
"id": "plan-pro",
"kind": "plan",
"name": "Pro plan",
"description": "Unlimited projects and priority support.",
"url": "https://example.com/pricing#pro",
"imageUrl": "https://example.com/img/pro.png",
"price": 49,
"comparePrice": 59,
"currency": "EUR",
"inStock": true,
"stockQuantity": null,
"categories": [
"plans"
],
"attributes": {
"billing": "monthly",
"seats": 5
},
"active": true
}
]
Example
{
"items": [
{
"id": "plan-pro",
"kind": "plan",
"name": "Pro plan",
"description": "Unlimited projects and priority support.",
"url": "https://example.com/pricing#pro",
"imageUrl": "https://example.com/img/pro.png",
"price": 49,
"comparePrice": 59,
"currency": "EUR",
"inStock": true,
"stockQuantity": null,
"categories": [
"plans"
],
"attributes": {
"billing": "monthly",
"seats": 5
},
"active": true
}
]
}

What happened to each item

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

object
created

How many items were created.

integer format: int32
updated

How many existing items were updated.

integer format: int32
failed

How many items were refused. The others were still written.

integer format: int32
results

One entry per item, in the order you sent them.

Array<object>
object
index

The item’s position in your request, starting at 0.

integer format: int32
status

created, updated or failed.

string
id

The item’s Azimea id; null when it failed.

string format: guid
nullable
errors

Why the item was refused; null when it was written.

Array<object>
nullable
object
code

A stable error code, listed in the error codes catalog.

string
field

The request field the problem is about; null when it is about the whole item.

string
nullable
params

The numbers the code refers to (a minimum, a maximum), when there are any.

object
key
additional properties
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": true,
"value": {
"created": 0,
"updated": 1,
"failed": 0,
"results": [
{
"index": 0,
"status": "updated",
"id": "01a10900-0000-7000-8000-000000000001",
"errors": null
}
]
},
"status": 0,
"errors": [],
"fieldErrors": null
}

Validation failed: see errors[].code (catalog.batch_too_large)

Media typeapplication/json
object
isSuccess

true when the call worked, false when errors say why it did not.

boolean
value

The answer itself; null when the call failed.

nullable
status

An internal result number. Rely on the HTTP status code instead.

integer format: int32
errors

What went wrong, one entry per problem; empty when the call worked.

Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
fieldErrors

The same problems grouped by the request field they belong to; null when none is tied to a field.

object
key
additional properties
Array<object>
object
code

A stable code such as audience.contact_not_found. Branch on this, never on message. Every code is listed in the error codes catalog.

string
message

An English sentence for your logs. Do not show it to end users: it can change.

string
params

The numbers the message mentions (a minimum, a maximum), when there are any.

object
key
additional properties
Example
{
"isSuccess": false,
"value": null,
"status": 5,
"errors": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
],
"fieldErrors": {
"email": [
{
"code": "validation.required",
"message": "Fill in this field.",
"params": null
}
]
}
}

Missing or invalid API key

The key lacks the items:write permission

Too many requests for this key