Skip to content
AzimeaDocs
Dashboard

Create or update a catalogue item

POST
/items
curl --request POST \
--url https://api.azimea.com/v1/items \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "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 }'

Adds a product, plan or service from your own system to the catalogue Azimea recommends in emails, or updates it. id is your own id for the item: sending the same id again updates the same item, and a field left out keeps its value. A new item defaults to a product, in stock and active; kind is product, plan, service or other. To stop recommending an item but keep its history, send active: false instead of deleting it. Items synced from a connected store are not written here. Needs the items:write permission. Refusals come back as catalog.* codes on the field, for example catalog.item_name_missing, catalog.item_currency_invalid, or catalog.items_limit once the catalogue holds 100,000 items.

Media typeapplication/json
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
}

The item as stored

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
id

Azimea’s id for the item.

string format: guid
source

Where the item comes from: store (synced from a connected shop, edited only there), file (an import) or api.

string
storeId

The connected store the item belongs to; null for items from a file or the API.

string format: guid
nullable
externalId

Your own id for the item, the one you sent as id.

string
kind

product, plan, service or other.

string
name

The item’s name.

string
description

A description, up to 5,000 characters.

string
nullable
url

Where the item can be bought or read about: a full address starting with https://.

string
nullable
imageUrl

An image of the item: a full address starting with https://.

string
nullable
price

The current price, in currency.

number format: decimal
nullable
comparePrice

The price before a discount. Higher than price when set.

number format: decimal
nullable
currency

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

string
nullable
inStock

true when the item can be bought.

boolean
stockQuantity

How many are left; null when you do not track it.

integer format: int32
nullable
categories

The item’s categories. They drive the “one category” and “for each person” recommendations in emails.

Array<string>
attributes

Extra fields you attached, by key.

object
key
additional properties
active

false stops recommending the item and keeps its history.

boolean
createdAt

When the item was added.

string format: date-time
updatedAt

When it last changed; null if it never did.

string format: date-time
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": true,
"value": {
"id": "01a10900-0000-7000-8000-000000000001",
"source": "api",
"storeId": null,
"externalId": "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,
"createdAt": "2026-10-05T09:00:00+00:00",
"updatedAt": null
},
"status": 0,
"errors": [],
"fieldErrors": null
}

Validation failed: see errors[].code and fieldErrors

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