YBM Connect | Products

Manage your product catalog in YourBarMate.

Status

The state of a product is indicated by the status field:

"ACTIVE": The product is available for customers to order.
"INACTIVE": The product is permanently unavailable for customers to order. If customers attempt to add this product to a delivery, they are informed that this product is no longer available and YourBarMate suggests to deactivate the product on their end.
"OUT_OF_STOCK": The product is available to order. However, the delivery date is unknown. You can use this status for procurement products. If a customer orders multiple products in one session and some of the products have this status, two separate orders will be created, one for all products with status ACTIVE and one for all products with this status.

Vessel

A vessel is the smallest countable unit delivered to customers. Vessels may be delivered individually or in bundles.

Products may define the size and unit of a vessel. This is required if a product can be delivered in fraction quantities and allows customers to do inventory more accurately.

Vessels may have an optional type to label the vessel as described in vessel and bundle types.

{
  "vessel": {
    "size": 7,
    "unit": "dl",
    "type": "BO"
  }
}

If you need a mapping to your internal vessels, you can provide an id. The id is not visible to users, but will be included wherever the vessel is used, for example in the Webhook message.

{
  "vessel": {
    "id": "my-vessel-id",
    "size": 1.5,
    "unit": "kg",
    "type": "CT"
  }
}

Bundles

Bundles specify the type and quantity in which vessels are delivered. Bundle types are described in vessel and bundle types. Bundles with type "PX" may have a pallet_bundle property which specifies the bundle type and size delivered on the pallet.

{
  "bundles": [
    {
      "type": "BX",
      "size": 20
    },
    {
      "type": "PX",
      "size": 40,
      "pallet_bundle": {
        "type": "BX",
        "size": 20
      }
    }
  ]
}

If you need a mapping to your internal bundles, you can provide an id. The id is not visible to users, but will be included wherever the bundle is used, for example in the Webhook message.

{
  "bundles": [
    {
      "id": "my-bundle-id",
      "type": "BX",
      "size": 20
    }
  ]
}

In case your system represents every bundle as a product with its own ID, you can specify id_override. When a new delivery is created with that bundle, the items.id will be the override value.

{
  "bundles": [
    {
      "id_override": "my-product-id",
      "type": "BX",
      "size": 20
    }
  ]
}

Base unit ordering

The optional boolean allow_base_unit_ordering controls whether customers can order the product in base units in the shop. It defaults to true: omitting the property has the same effect as setting it to true. Set it to false to allow ordering only through one of the product's provided bundles.

When allow_base_unit_ordering is false, the product must have at least one bundle. Setting it to false while the product has no bundles is invalid and the API returns 400 Bad Request.

{
  "allow_base_unit_ordering": false,
  "bundles": [
    {
      "type": "CT",
      "size": 6
    }
  ]
}

Pricing

By default, total price is calculated based on the price property of the product and the quantity of the order.

However products support more options for scaled pricing, please see the scaled pricing documentation page for details.

Delivery settings

Delivery settings can be added to each product if it differs from the default delivery settings. When specified on the product level, these will always override the values defined on the account level.

You can override these properties:

delivery_days
delivery_date_overrides
dates_with_no_delivery

Please see the account documentation page for details.

Custom properties

Additional details can be provided for each product. All custom properties are optional.

The following can be added to each product:

manufacturer
brand
region
country - 2 letter country code, eg: CH, FR, US etc
vintage - integer for the year, eg: 2012
description
ingredients
allergens - array of allergen codes, eg ['A', 'D'] - see the list of allergen codes below
trace_allergens - array of allergen codes, eg ['H', 'N'] - see the list of allergen codes below
alcohol_content - in cents e.g: 500 = 5%, 1250 = 12.5%
color
grape_variety
wine_making
storage_advice
fishing_method
material
dry_weight - whole number in grams
net_weight - whole number in grams
total_weight - whole number in grams
external_url - a link to more information about the product
labels - array of 'NEW', 'BIO', 'SEASONAL', 'DISCOUNTED', 'VEGAN', 'VEGETARIAN', 'GLUTEN_FREE' labels

Allergen codes

Code	Allergen	Description
`A`	Cereals containing gluten	Cereals containing gluten, namely wheat (such as spelt and khorasan wheat), rye, barley, oats or hybrid strains thereof
`B`	Crustaceans	Crustaceans and products derived therefrom
`C`	Poultry eggs	Poultry eggs and products derived therefrom
`D`	Fish	Fish and products derived from fish, except a) fish gelatine used as a carrier for vitamin or carotenoid preparations; b) fish gelatine or isinglass used as a fining agent in beer and wine
`E`	Peanuts	Peanuts and products derived from peanuts
`F`	Soybeans	Soybeans and products derived from soybeans
`G`	Milk	Milk from mammals and products derived from it (including lactose)
`H`	Nuts	Nuts and products derived from them, namely almonds, hazelnuts, walnuts, cashews, pecans, Brazil nuts, pistachios, macadamia nuts or Queensland nuts. Except nuts used in the production of alcoholic distillates
`L`	Celery	Celery and products derived from it
`M`	Mustard	Mustard and products derived from it
`N`	Sesame seeds	Sesame seeds and products derived from them
`O`	Sulphur dioxide and sulphites	Sulphur dioxide and sulphites
`P`	Lupins	Lupins and products derived from them
`R`	Molluscs	Molluscs such as snails, mussels, squid

You can also submit allergen names as simple strings. We automatically map them to the above codes where possible. Unmatched strings are stored unchanged, but most views only display standard codes for consistent localisation.

Examples:

{
  "custom_properties": {
    "country": "CH",
    "description": "Something very healthy and green",
    "labels": ["BIO", "VEGAN", "GLUTEN_FREE"]
  }
}

{
  "custom_properties": {
    "country": "FR",
    "region": "Bordeaux",
    "vintage": 2021,
    "color": "red",
    "allergens": ["O"],
    "description": "Red wine - Matured for several months in barriques (French oak) - Goes well with: game, lamb, beef"
  }
}

Image

You can provide images for products that will be displayed in our webshop. When an image url is provided, our system will download and process the file. We host the images ourselves and they are publicly accessible - although not indexed by search engines or scrapable without login.

We automatically resize the images to 400x400 pixels and convert them to PNG.

When a new url is provided the image will be refreshed in our webshop.

When using the PATCH or PUT endpoints, if the url of the product image is the same as it was before, the image will not be refreshed. If you want to trigger a cache invalidation with the same URL, you can send a new etag or last_modified property and send it with the url - the image will be refreshed if the provided value is different from the stored value.