Required Fields
Which product fields you have to send, and how that changes between simple products, complex products and variants.
How products are structured
The Type field decides which fields Axiom expects:
- A simple product is sold on its own. It carries everything needed to order it: SKU, codes, unit size, unit label and prices.
- A complex product is a parent that groups one or more variants. The parent holds the shared, descriptive information, and each variant holds the details that make it individually orderable.
That split is why a field can be required on a simple product, optional on a complex parent, and required again on every variant.
Field requirements
| Field | Simple Product | Complex Product | Variant |
|---|---|---|---|
| Type | Required | Required | Not accepted |
| Identifier | Required | Required | Required |
| Language Code | Optional | Optional | Not accepted |
| Name | Required | Required | Required |
| Brand | Required | Required | Required |
| Manufacturer | Required | Required | Not accepted |
| SKU | Required | Optional | Required |
| Codes | Required | Not accepted | Required |
| Options | Not accepted | Not accepted | Required |
| Unit Size | Required | Optional | Required |
| Unit Label | Required | Optional | Required |
| Prices | Optional | Not accepted | Optional |
| Description | Optional | Optional | Optional |
| Properties | Optional | Optional | Optional |
| Categories | Optional | Optional | Not accepted |
| Images | Optional | Optional | Optional |
| Resources | Optional | Optional | Optional |
| Product Page URL | Optional | Optional | Optional |
- Required — we reject the product if the field is missing.
- Optional — safe to leave out.
- Not accepted — don't send the field at this level. The notes below explain where the value belongs instead.
Notes on the exceptions
- Type describes the product, not the variant. If you add a variant to a simple product, it converts to a complex product automatically.
- Manufacturer is set once on the parent product, and every variant reports the manufacturer of the product it belongs to.
- Codes are rejected outright on a complex parent: sending
codesalongside"type": "complex"fails validation. Put the codes on each variant instead. Every simple product and every variant needs exactly one MPN and exactly one UNSPSC code, and no other code type can appear more than once. - Options are what distinguish one variant from another, so they exist only on variants. Each variant needs at least one option, and an option name can appear only once within the same variant. Axiom does not check that two variants differ, so it is on you to give each one a distinguishing value.
- Prices sent on a complex parent are ignored — price each variant instead. Prices are optional in the payload, but buyers can only order a product once it has an approved price. See Price Lists.
- Categories are assigned to the product, and every variant of that product is categorised with it.
- Language Code is set on the product, and its variants use the product's language. To publish the same product in another language, send it again with the same identifiers and a different language code. See Multi-language support.
- Images are not enforced by validation, but a product without at least one image shows poorly in search results and on the product page, so treat them as required in practice.
Fields returned but not submitted
Ships to is not a field you send. The countries and regions that can see and buy a
product are derived from its approved price lists, and ships_to is returned on the
product detail response to tell you what that currently resolves to. A ships_to sent in a product
payload is ignored.
Optional fields not listed above
The table covers the descriptive product data. Two further optional fields can travel in the same payload:
| Field | Where | What it does |
|---|---|---|
stocks | Simple products and variants | Stock level, lead time and always-available flag, per country. Not accepted on a complex parent |
shipping_detail | Products only | Dispatch dimensions and weight, each as a unit and value pair |
Both are optional, and both are covered in the stock and lead time guide.