---
title: Catalog availability data
slug: m53g0124
canonical_url: https://docs.coveo.com/en/m53g0124/
collection: coveo-for-commerce
source_format: adoc
---
# Catalog availability data

An [availability](https://docs.coveo.com/en/mc7e9096/) determines whether a given customer can purchase a given product or [variant](https://docs.coveo.com/en/mc7f0326/).
An availability can be a store inventory, a price list, or anything that controls which user has access to certain products or variants.

> **Note**
>
> A customer's ability to buy a specific product or variant is determined by the structure of your [catalog entity](https://docs.coveo.com/en/3143/).
> If your catalog entity exclusively includes product items, your customers will purchase these products.
> However, if your catalog entity contains variants, customers will purchase variant items, which represent specific sellable versions of the products.

## Availability item example

If you're trying to sell a `Coveo Soccer Shoes - Red` that has two size variants, `Coveo Soccer Shoes - Red ; Size 8` and `Coveo Soccer Shoes - Red ; Size 9`, the JSON of the items may look like the following:

> **Note**
>
> In your [catalog data](https://docs.coveo.com/en/obcf0333/), some of the fields discussed here, such as `ec_product_id`, `ec_variant_id`, `ec_availability_id`, and `ec_available_items`, may have different keys.

```json
{
  "documentId": "product://001-red",
  "ec_name": "Coveo Soccer Shoes - Red",
  "ec_product_id": "001-red",
  "objecttype": "Product",
  "ec_images": ["https://myimagegallery?productid"],
}
```

Similarly, the following JSON samples showcase the variant items:

```json
{
  "documentId": "variant://001-red-size-8",
  "ec_name": "Coveo Soccer Shoes - Red ; Size 8",
  "ec_product_id": "001-red",
  "objecttype": "Variant",
  "ec_variant_id": "001-red-size-8",
}
```

```json
{
  "documentId": "variant://001-red-size-9",
  "ec_name": "Coveo Soccer Shoes - Red ; Size 9",
  "ec_product_id": "001-red",
  "objecttype": "Variant",
  "ec_variant_id": "001-red-size-9",
}
```

Given the product and its variants, you can create an item to represent availability where a local store contains a finite amount of products:

```json
{
  "documentId": "store://s000001", <1>
  "ec_name": "Montreal Store",
  "lat": 45.4975,
  "long": -73.5687,
  "ec_availability_id": "s000001", <2>
  "objecttype": "Availability", <3>
  "ec_available_items": ["001-red-size-8","001-red-size-9"], <4>
}
```

The preceding JSON has generic information about the store location (`lat` and `long`) and name (`ec_name`).

<1> The value of the `documentId` [metadata](https://docs.coveo.com/en/218/) is the unique identifier of your item in the [index](https://docs.coveo.com/en/204/) and will also serve as the item's `uri` field value.
This value is essential to [update](https://docs.coveo.com/en/p4eb0515/) the item's information in the index.

<2> The `ec_availability_id` metadata uniquely identifies each [availability channel](https://docs.coveo.com/en/mc7e9096/) or price list.

<3> The `objecttype` metadata is crucial in identifying the item as an availability channel in the [index](https://docs.coveo.com/en/204/).

<4> The `ec_available_items` metadata defines which variants or products are available through a given channel.

> **Note**
>
> Depending on the way you've structured your data, your availability [metadata](https://docs.coveo.com/en/218/) might be contained in another source.
> Refer to [Leverage variants and availabilities](https://docs.coveo.com/en/3121/) for more information.

> **Important**
>
> If an item of the `availability` [catalog object](https://docs.coveo.com/en/ncig0154/) has more than 1,000 items listed in the `ec_available_items` field, we recommend that the related items (product or variant) also contain the `ec_available_items` field.
> 
> The value must be formatted as an array, but contain only one item, which is the unique identifier of the item, as shown in the following code samples.
> This will improve the performance of your index.
> 
> **Availability:**
> 
> ```json
{
  "documentId": "store://montreal",
  "FileExtension": ".html",
  "ec_name": "Montreal Store",
  "ec_available_items": ["001-red-8_wide", "001-red-7-narrow", "..."],
  "objecttype": "Availability"
}
```
> 
> **Related variant:**
> 
> ```json
{
  "documentId": "variant://001-red-8_wide",
  "FileExtension": ".html",
  "ec_name": "Coveo Soccer Shoes - Red / Size 8 - Wide",
  "ec_variant_id": "001-red-8_wide",
  "ec_available_items": ["001-red-8_wide"],
  "productsize": "8",
  "width": "wide",
  "ec_product_id": "001-red",
  "objecttype": "Variant"
}
```

### Returning availability information

Similarly to [variants](https://docs.coveo.com/en/m53g0506#product-variants), users are presented with various displayable products.
However, they select a variant or product from a specific availability channel when purchasing.

Akin to how variant information can be used to refine and filter search results, availability data can be used in a similar manner.
For instance, once a product has been identified in search results, a user might want to refine the results based on availability, displaying only those products available in a particular store or within a specific price list.
This is where availability data can help guide and enhance the search experience by providing meaningful filtering capabilities.

> **Important**
>
> Metadata keys defined in availabilities can be used for filtering with [facets](https://docs.coveo.com/en/198/), but can't be used for sorting results.

If you wish to showcase availability information on the product itself, you can store this data as a [dictionary](https://docs.coveo.com/en/2036/) on the product item.
For example, if you only wish to show products that can be shipped to the postal code the user lives in, your availability information needs to appear on the product.

See [Leverage variants and availabilities](https://docs.coveo.com/en/3121/) on how to achieve this.