Skip to navigation
Inventory

Introduction to the Variety API

Varieties describe what a variant is. A variety is a dimension such as COLOR or SIZE. A variety table is one set of values for that dimension, such as EU shoe sizes. A variety value is one entry in that set, with a display name and a sort order.

Items and variants hold codes only. An item variant has varietyN, varietyNTable and varietyNValue for positions 1 to 4. They match type, code on a variety table, and type, table, value on a variety value.

To build a size or color picker that shows the same options as Business Central and the Shopify integration:

  1. Sync GET /inventory/varietytable and GET /inventory/varietyvalue with sync=true and lastRowVersion, and keep them in a local cache keyed on id. Sync does not return deleted rows, so reload the cache in full now and then. See Replication.
  2. Read the variants with GET /inventory/itemvariant, or with GET /inventory/item?withVariants=true. Hide variants where blocked is true.
  3. For each position with a varietyN, look up the variety table by type and code. Skip the position when the table has useInVariantDescription set to false. The table description is the dimension name.
  4. Look up the value by type, table and value. The label is the table’s preTagInVariantDescription followed by the value description when the table has useDescriptionField set, otherwise followed by the raw value.
  5. When a variety table or value is not in your cache, show the raw code instead.
  6. Sort the values by sortOrder, then by value. The response order is not guaranteed.

GET /inventory/variety gives the general name of each dimension, for example “Colour”, shared by all its variety tables. Use it when you need one name across products, such as a shop-wide filter. Its flags are only defaults for new variety tables; always use the flags on the variety table.