Products

List products

• In addition to the tag, name, exactname and skufilter, you can use boolean filters sold, purchased, is_available and inventoried for product filtering at a given site.
• The show_online flag is used to indicate if this product is shown or hidden. When it is true, Site expects this product should be shown to customers. Otherwise it should be hidden. Hint: Site needs to enable the Online Products feature then edit it under Products > Online Products on Back Office.

• You can specify a list of fields in the query string in order to return additional data on the endpoint. This can be particularly useful for syncing a menu without needing to pull down every individual item.
• Available fields are image, categories, option_sets, availability, unit_price, unit_price_ex_tax, unit_tax, variants, variant_parent_id, variant_attributes and docket_name.

Get a product

Whenever possible, specify a site ID in your request. The sites section will collapse into the top level of the response, making it much flatter:

The variant_attributes field is only present on products that take part in a variant family, and its shape tells you which part the product plays:

• On a variant template (a product with variants), each attribute name maps to the list of values its children may be created with, e.g. {"Colour": ["Blue", "Red"]}.
• On a child variant (a product with a variant_parent_id), each attribute name maps to the single value that child was created with, e.g. {"Colour": "Red"}.
• On any other product the field is omitted entirely.

Attribute names and their values are sorted alphabetically.

When requested as a fields value on the list endpoints, variant_attributes is always present, and products that take no part in a variant family report an empty object.

The pricing of the modifiers above relates to the use of pop-up modifiers in Kounta by Lightspeed whereby site's can set specific pricing when a modifier is attached to a particular product.

Create a product

You can create a product without making it available at any sites.

• Only the name and either unit_price or unit_price_ex_tax fields are required. The price will be added to the base price list. If no taxes are specified, the product is assumed to be tax free.
• After you create a product, you should add it to one or more sites for sale. See the Update a product action for details.
• See Images for how to add product images.
• is_modifier is optional. If not provided it will default to false.
• is_modifier cannot be set to true on products that have variants.
• variable_price is optional and will default to false if not provided.
• If variable_price is true the POS will always prompt for a price that must be between min_sell_price and max_sell_price.
• docket_name is optional. If provided, it must be a string with a maximum length of 255 characters. It will be displayed on the docket instead of the product name.
• online_description is optional. If provided, it must be a string with a maximum length of 2000 characters. It is the description shown to customers online, as opposed to description, which is for internal use.

If you create a product for sale at a specific site, you can include site-specific information inline:

If the site you specify has been assigned an alternate price list, the price you specify will be assigned to both the base and the assigned price lists.

• When option_sets is provided is must have at least one item.
• The option_sets must only contain unique and valid option sets.
• The order that option sets provided in will be reflected on the POS.
• When updating a product the option_sets will always replace any existing option_sets.

Variant products are created in two separate requests. Both requests create and return one normal product resource and emit the normal products/created webhook for that product.

• For a template, variant_attributes maps each attribute name to one or more allowed values. The parent price defaults to zero.
• For a child, provide variant_parent_id and use variant_attributes to map each template attribute name to exactly one value. The child name is generated from the parent and values unless name is supplied.
• Child values must already exist in the template's allowed values, and duplicate combinations are rejected.
• Creating a child whose combination of values another child already uses returns a 400 Bad Request. Each combination may only be used once per template.

Update a product

• To add or remove tags or taxes, you need to replace their entire collections.
• is_modifier, is_inventory and is_sold are optional. If not provided the value will remain the same.
• is_modifier cannot be set to true on products that have variants.
• variable_price is optional and will default to false if not provided.
• If variable_price is true the POS will always prompt for a price that must be between min_sell_price and max_sell_price.
• online_description is optional. If not provided the value will remain the same.

To make products available for sale on one or more sites:

• taxes and cost_taxes should be a list of tax IDs.
• Including a unit_price or cost_price will set the product's sell price or cost price (tax inclusive price) on the site's current price list.

All fields are optional. You can make a product available on a site as simply as:

List of Webhooks

Here is a list of the supported webhook topics.

Important: It is possible for individual sites to override the company-level product; such as a different price. However, the webhooks below are only subscriptions to the company-level products or enabling /disabling product on any given sites. Changes to site-level products or price lists will not cause the webhook to be triggered.

products/created

When a product is created. You will receive the complete product.

products/updated

When a company-level product is updated or a product is enabled or disabled on any given sites. You will receive the complete product after the modifications have been applied.

You also may provide the following attribute filters:

• show_online

Note that when filtering by show_online, any changes to products where show_online is true will trigger a webhook notification.

products/deleted

When a product is deleted. You will receive the complete product.

Important: A company-level product may be assigned to none, one or several sites. Unassigning a product from a site is not the same as removing it at a company level. This webhook is only triggered if the product is deleted at a company-level.

products/availability

When a product's availability has changed (e.g. is_available from true to false or amount from 5 to 4), you will receive the updated product availability data as below.

Important: When creating products/availability webhook, site_ids filter is required as this feature is strictly site-level

Units

The current units of measure we support are ml for millilitre, l for liter, g for gram, kg for kilogram and unit case insensitive.