Products

Properties

Properties

Retrieve a list of customers associated with an organisation.

Querying Products

Products can be queried in a few different ways:

• If the ID of the product is known, the product details can be retrieved directly using the Get Product endpoint. In the event that multiple products need to be retrieved, it is possible to bulk query product IDs using the id query parameter, with each product ID being supplied as a form-style query, for example:

  /products?id=prod_29ZaWHhqqGk00xyZI6SFPc8iON7&id=prod_29ZaSRuU445ChdFCEDrSWZIeczD

• If attempting to lookup products by a marketplace ID, this can be achieved by providing the marketplace parameter, and the marketplace product IDs via the marketplace_id parameter, in the same manner as the example displayed above.
  It is possible to query both platform and marketplace IDs within the same query, though it it not possible to query multiple marketplaces in a single query. For this use case, a seperate request should be made for each marketplace and set of applicable product IDs.

A maximum of 20 IDs can be queried in a single request. Attempting to query more than this will return an error.

• It is possible to search for products by their name. Simply pass a string to search for in the search parameter. This string can be a partial name, and case is ignored. If the search parameter is present, all other marketplace and ID parameters are ignored.

Query Parameters

Create a new product.

Products & Product Variants

Regardless of whether a product is a singular product, or a product with multiple variants, every product must have at least 1 variant. Attempting to create a product without a variant will fail.

Once created, the product data will include a field has_multiple_variants, which enables the client to adjust it's behaviour for single vs multi variant products if necessary.

The rationale behind this is that when modelling a product, the product data generally falls into 2 categories:

1. Data that is applicable for all variations of the product (eg. Name: Grey T-Shirt)
2. Data that is applicable on a per variation basis (eg. Size: Small, SKU: GREYTEE-SM)

Even in scenarios where products with no variations are being sold, giving the singular item a variant is a minor amount of additional overhead relative to the future flexibility it may provide:

• Move from selling products of one size to multiple sizes.
• Create a variant for eg. a 3-pack version of the item.
• A new variant for the item packaged in a presentational gift box.

Additionally, it becomes simpler to extend the functionality of this platform at a later date to add features such as per variant inventory, fulfilment from multiple locations, and so on.

Associating Products with External Marketplaces

Products created via this endpoint do not propagate through to external marketplaces automatically. This is because each external marketplace may require different configurations and settings to behave as expected, thus we leave this aspect up to the user.

The product can be linked to external platforms by making use of the marketplaces object, by adding a key/value pair in the format of:

"marketplaces": {
  "platform handle": "external platform product id"
}

For example:

"marketplaces": {
  "shopify": "6314278483"
}

All marketplace identifiers must be passed as strings, regardless of their original type.

The marketplaces object accepts multiple key/value pairs, though at this time we only allow one product from each marketplace to be linked to a given product. If this is an issue for your use case, please contact us to discuss it.

Automatic Product Linking

Linking a product allows any orders placed on the external marketplaces to be translated to products stored on this platform. For marketplaces that support it, it is possible to automatically link to or create a corresponding product on this platform when a new product is created on the marketplace. Please check your account preferences to configure this behaviour.

Where automatic creation/linking is enabled, internally we check the values for the gtin and sku field equivalents for the product on the marketplace. If a product on this platform has matching fields, the products are linked.

In the event of multiple products matching, we prioritise matching the sku over the gtin, as the latter may be shared amongst multiple products. If multiple matches are still returned, we link to the first matching product.

Product Dimensions

Where possible, all products should have their dimensions and weight added stored on record. This data is used as part of the automatic shipping calculations - failing to provide this information will result in manual intervention being necessary when creating shipping labels to provide the package dimensions and weight.

Retrieves an individual product.

Path Parameters

Update a product by it's ID.

Variants currently cannot be updated using this endpoint. Instead use the Update Variant endpoint. Attempts to update variants using this endpoint will be ignored.

Path Parameters

Delete a product with the given ID.

As products are an integral part of any order that a customer places, in the event that a product is deleted, references to a deleted product will remain in any orders that exist in the system. This may result in a 404 error if attempting to lookup products from an order that have been deleted since the order was placed. All orders store an immutable copy of key product information, such as the name, price and quantity of the product ordered. This is to ensure that in the event of a product being deleted, order records do not become inconsistent.

Path Parameters

Retrieves the variants associated with a given product.

As with the Get Products endpoint, the response from this endpoint is a paginated set of results. The results and cursor query parameters can be used to retrieve all the variants associated with a given product.

Path Parameters

Query Parameters

Create a variant for a given product.

As described in the Create Product documentation, each product is required to have at least one variant.

Products may have up to 200 variants. If this is going to be a limitation for your organisation please contact us to discuss possible solutions.

As with the parent product resource, marketplace identifiers are specified in the marketplaces object. It is similarly possible to add variant specific data using the metadata field. For more information on how marketplaces interact with products and variants, read the Automatic Linking section of the Create Product documentation.

The Product Variant Data Structure

Product variants hold information that is specific to the physical (or digital) item in question. For single variant items (eg. Apple AirPods Pro) this information will generally be a gtin and/or an sku. For multiple variant products (eg. iPhone 13), one might create 3 variants with the names: 128GB, 256GB & 512GB, with corresponding gtin/sku fields for each product variation.

Conditional Product Options (Not Used)

The phrases "product variant" and "product option" are used interchangeably below, with both being used to delineate between what exists on a given marketplace, and what exists on this platform.

The handling of product variations differs between marketplaces. Some marketplaces allow a limited number of combinations of attributes to create product variants, usually 2-3 seperate attributes, with each possible combination of attributes assigned an identifier (the equivalent of a product variant identifier). These are sometimes called conditional/nested product options, and are commonly seen on product pages where, eg. the colour of the item selected determines which sizes of the product are shown in stock.

The advantages of the above approach are that it it easy to implement and easy to understand. However, in certain situations such an approach can be limiting. In the event of a product having more than one or two options, structuring things as in the example above quickly becomes cumbersome - if a product has 5 options, with each option having 5 possible values, yet in reality the store only allows 50 possible combinations, the above structure requires either that we store 55 (that's 3125!) combinations, and only add stock for the 50 possible combinations, or we otherwise create a separate record of which combinations are available, which quickly adds complexity.

Attribute-Based Product Options (In Use)

Instead of storing possible combinations and then adding stock for the combinations that actually exist, we approach the problem from the other side - we create a variant for each item that is available for sale, assigning a name and ideally a gtin and sku to each variant. Then the variant is tagged with the attributes of the item.

This has a few of advantages:

• Adding attributes (ie. product options) is easy to do, and does not increase the number of variants that we have to track and search internally.

• It is possible to have many options for a single product.

  Due to the reduced complexity of storing and searching, it is possible to have many more product options without causing performance issues.

• It is flexible.

  Take the example of a company sending out boxes of chocolates, where they have boxes with several different flavours. Each combination of flavours is assigned a variant, and assigned the attribute flavours, along with each flavour listed within the box, eg. strawberry, dark chocolate, orange.

• Product options do not have to be selected in order.

  For example, a clothing brand is selling a style of shirt, available in all the standard chest sizes, and 32 different colours. A customer is looking to buy a shirt, and is relatively indifferent to which colour they buy, it just needs to be a 16" collar with a 34" sleeve.

  However, the marketplace uses conditional product options, meaning that the colour must be selected before the size. This results in the customer having to click through 6 colours of shirt, as the first 5 colours were not avaiable in their desired size.

  Instead attribute based product options are used. The customer selects the size that they want, at which point only the items that a) match the selected attributes, and b) are in stock are returned, thus negating the need for the trial and error approach.

Path Parameters

Retrieve an individual product variant for a given product.

Currently product geometry is set at the product level. We are considering adding the ability to set product geometry at the variant level (ie. length, width, height & mass).

Path Parameters

Deletes a product variant.

As with products, if a product variant is deleted, references to the variant may still exist within orders. This is due to the fact that it is necessary to keep an immutable record of the contents of a customer order.

All products are required to have at least one variant. Attempting to delete a product variant if it is the last variant assigned to a product will fail with a 400 status code. If attempting to delete all variants before deleting a product, deleting the product will automatically delete any remaining variants.

Path Parameters

Updates a given product variant.

Updates to product variants (and products) do not affect existing orders, where details are recorded as they existed at the point of the order being placed.

Path Parameters

Lookup products and product variants by either their IDs or their marketplace IDs.

In the event that one needs to query multiple products & corresponding variants, such as when one is creating an order, this endpoint provides a facility for doing so.

When queries for the requested products are run, the following behaviour should be taken into account:

• In the event that both the marketplaces and the id fields are supplied for either a product or variant, the id field is used, and the marketplaces field ignored. This remains the case even if the id field contains an empty value.

• If a product and variant combination cannot be found, the request will fail with a 404 error. This is to prevent products transparently disappearing during the lookup in the event that the client application does not check that the number of results returned corresponds to the number requested.

• A maximum of 50 entries can be queried per request.

• In the event of an entry not containing the variant details, if the product has a single variant associated with it, the response will contain this variant, otherwise the request will fail with a 400 error and a message indicating the need to supply a variant identifier.

• If multiple instances of the same product exist in the request, the response will only contain a single instance of the corresponding product details, with any requested variants contained within the single instance.

Detailed descriptions

body: The example request demonstrates a few ways of looking up products and corresponding variants. In the example, the following holds:

• Three products are requested for lookup, but two of these lookups correspond to the same product.
• The first lookup request where no variant is specified is a single variant product, and thus the variant array will be populated with the single variant associated with the product.
• For the requests which resolve to the same product, the variants requested differ. Both requested variants will be returned in the variants array.

The response will thus contain only 2 products, with the variants requested in each lookup combined and returned as a single product.

»»» type: The type of product, either physical or virtual.

For products with a type of virtual, they are not considered in the context of fulfilments and shipping.

»»» metadata: An object containing a series of key/value pairs of metadata that will be attached to the product.

A maximum of 50 pairs is allowed. Keys can be up to 64 characters in length, values up to 500. Keys may include alphanumeric characters and underscores. Values may contain UTF-8 text.

Enumerated Values

Endpoint for bulk updating product details.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• Metadata and marketplace fields are added to those that are already present. Such fields cannot be deleted using this endpoint, and instead must use the update product endpoint.

• Variants cannot be updated using this endpoint.

• All entries must contain a product ID. If any product ID is missing or invalid, the request will fail.

• Product responses will not have the variants populated.

• The endpoint will not return validation errors for individual entries in the request if present, but will instead fail with a generic validation error.

• In the event that the request contains conflicting marketplace IDs (i.e. the client attempts to assign an ID to a product when it has already been assigned to a different product), the request will fail, and the error message will contain a list of the existing product IDs that are already assigned to the specified ID.

Detailed descriptions

»»» type: The type of product, either physical or virtual.

For products with a type of virtual, they are not considered in the context of fulfilments and shipping.

»»» metadata: An object containing a series of key/value pairs of metadata that will be attached to the product.

A maximum of 50 pairs is allowed. Keys can be up to 64 characters in length, values up to 500. Keys may include alphanumeric characters and underscores. Values may contain UTF-8 text.

Enumerated Values

Endpoint for bulk creating products.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• Variants supplied with the product will also be created.
• Product responses will not have the variants populated.
• The endpoint may not return validation errors for individual entries in the request if present, but may instead fail with a generic validation error.
• In the event that the request contains conflicting marketplace IDs (i.e. the client attempts to assign an ID to a product when it has already been assigned to a different product), the request will fail, and the error message will contain a list of the existing product IDs that are already assigned to the specified ID.

In the event of the request being partially successful, a 202 Accepted status is returned, and the errors field of the response contains details of the elements that failed to create. In the event that all products in the request are successfully created, a 201 Created status is returned.

In both cases, the data parameter of the response will contain the products that were successfully created.

Detailed descriptions

»»» type: The type of product, either physical or virtual.

For products with a type of virtual, they are not considered in the context of fulfilments and shipping.

»»» metadata: An object containing a series of key/value pairs of metadata that will be attached to the product.

A maximum of 50 pairs is allowed. Keys can be up to 64 characters in length, values up to 500. Keys may include alphanumeric characters and underscores. Values may contain UTF-8 text.

Enumerated Values

Get product variants directly, without needing the product ID.

Query parameters can be supplied to query for variants based on SKUs, linked marketplace IDs, and directly by variant IDs.

Query Parameters

Create a product variant directly, passing the product ID in the body of the request.

Depreciated as no longer necessary, and will be removed at a future date without notice.

Use Create Product Variant endpoint instead, as it has the same functionality, except that the product ID is passed in the URL.

Retrieve a product variant by it's ID, without the corresponding product ID.

Depreciated in favour of using a combination of the product -> variant endpoint, and the search index API.

Path Parameters

Update a product variant directly, passing the product ID in the body of the request.

Depreciated as no longer necessary, and will be removed at a future date without notice.

Use Update Product Variant endpoint instead, as it has the same functionality, except that the product ID is passed in the URL.

Path Parameters

Endpoint for bulk creating product variants.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• All entries must contain a product ID for which the variant will be created against. If any product ID is missing or invalid, the variant will not be created and the request will only partially succeed.
• Product variant responses will have the products field populated, with this field containing the summary details of the product associated with the variant.
• The endpoint will not return validation errors for individual entries in the request if present, but will instead fail with a generic validation error.
• In the event that the request contains conflicting marketplace IDs (i.e. the client attempts to assign an ID to a product variant when it has already been assigned to a different product variant), the request will fail, and the error message will contain a list of the existing product variant IDs that are already assigned to the specified ID.
• Likewise, any product variant that attempts to use an SKU that is already in use will result in the variant not being created.

In the event of the request being partially successful, a 202 Accepted status is returned, and the errors field of the response contains details of the elements that failed to create. In the event that all product variants in the request are successfully created, a 201 Created status is returned.

In both cases, the data parameter of the response will contain the product variants that were successfully created.

Detailed descriptions

»»»»» type: The type of product, either physical or virtual.

For products with a type of virtual, they are not considered in the context of fulfilments and shipping.

»»»»» metadata: An object containing a series of key/value pairs of metadata that will be attached to the product.

A maximum of 50 pairs is allowed. Keys can be up to 64 characters in length, values up to 500. Keys may include alphanumeric characters and underscores. Values may contain UTF-8 text.

Enumerated Values

Endpoint for bulk updating product variant details.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• Marketplace fields are added to those that are already present. Such fields cannot be deleted using this endpoint, and instead must use the update product variant endpoint.

• All entries must contain a product variant ID. If any product variant ID is missing or invalid, the request will fail.

• Product variant responses will have the products field populated, with this field containing the summary details of the product associated with the variant.

• The endpoint will not return validation errors for individual entries in the request if present, but will instead fail with a generic validation error.

• In the event that the request contains conflicting marketplace IDs (i.e. the client attempts to assign an ID to a product variant when it has already been assigned to a different product variant), the request will fail, and the error message will contain a list of the existing product variant IDs that are already assigned to the specified ID.

Detailed descriptions

»»»»» type: The type of product, either physical or virtual.

For products with a type of virtual, they are not considered in the context of fulfilments and shipping.

»»»»» metadata: An object containing a series of key/value pairs of metadata that will be attached to the product.

A maximum of 50 pairs is allowed. Keys can be up to 64 characters in length, values up to 500. Keys may include alphanumeric characters and underscores. Values may contain UTF-8 text.

Enumerated Values