Catalog Item

Suggest Edits

Information

A catalog_item is any single instance, or unit, of a product_variant that’s available for sale to customers/patients and includes the price displayed on the Listing Menu.

Below is a catalog_item example:

  • Big Green Brand > Delicious Hybrid Flower > 3.5g Pack for $40 (20 are available for sale from Sally’s Wicked House of Wax)

📘

external_id parameter

The external_id parameter can be populated with an ID from the client to help map external resources to a catalog_item. The external_id is sent to downstream features such as the Weedmaps Orders API and is as a reference ID.

API Requests

The request types and routes available for this resource as well as details on how to structure your requests are below. See API Reference - CatalogItem for examples on how the requests might look in various languages and to test the requests in the browser.

RequestRouteDescription
POST/catalog/v1/catalog_itemsCreate a new catalog_item (see Note 1 below)
GET/catalog/v1/catalog_itemsRequest the information for all catalog_items
GET/catalog/v1/catalog_items/:idRequest the information for a particular catalog_item
PATCH/catalog/v1/catalog_items/:idUpdate the information for an existing catalog_item (see Note 2 below)
DELETE/catalog/v1/catalog_items/:idDiscontinue an existing catalog_item (see Note 3 below)

📘

When creating a catalog_item, you must include the catalog and product_variant relationships in the payload. The combination of a particular catalog and product_variant can only be used once. If you attempt to create a catalog_item using a combination that is already in use, you will receive a 409 Conflict error as the catalog and product_variant combination has already been taken.

🚧

When updating a catalog_item, you cannot update a Custom product_variant in the relationship with another Custom product_variant. However, you can update it with a Master product_variant. If you want the catalog_item to use a different Custom product_variant, you should first send a PATCH request to discontinue the current catalog_item, then create a new catalog_item with a POST request using the new Custom product_variant.

🚧

The DELETE endpoint is deprecated and will not be supported after Aug. 10, 2020.

Sending in a DELETE request for a CatalogItem will no longer delete the CatalogItem. Instead, it will set its discontinued_at field to the current timestamp. You can "un-delete" a CatalogItem by sending a PATCH request and setting discontinued_at to nil.

After August 10, 2020, you will need to send a PATCH request to set a discontinued_at timestamp to designate a CatalogItem resource as no longer active. See below example.

POST

To create a CatalogItem, send a payload with the below structure to
/catalog/v1/catalog_items?scope_by[organization_id]=ORGANIZATION_ID.

{
  "data": {
    "type": "catalog_items",
    "attributes": {
      "price_in_cents": 2000
    },
    "relationships": {
      "catalog": {
        "data": {
          "type": "catalogs",
          "id": "CATALOG_ID"
          }
      },
      "product_variant": {
        "data": {
          "type": "product_variants",
          "id": "PRODUCT_VARIANT_ID"
          }
      }
    }
  }
}

Path

scope_by[organization_id] string
Required. Organization UUID.

Attributes

id string
Optional. UUID for the resource.

price_in_cents int32
Required. The price in cents.

available boolean
Optional. Defaults to false. Designates whether the CatalogItem is available.

online_orderable boolean
Optional. Defaults to true. Designates whether the CatalogItem is online orderable.

type string
Required. Must be catalog_items.

Relationships

Catalog

catalog_id string
Required. Related Catalog UUID.

type string
Required. Must be catalogs.

ProductVariant

product_variant_id string
Required. Related ProductVariant UUID.

type string
Required. Must be product_variants.

GET Index

To fetch all CatalogItems, send a request to
/catalog/v1/catalog_items?scope_by[organization_id]=ORGANIZATION_ID. By default, we only return the first 10 results from the request. You can adjust the number of returned results with page[size], or adjust the returned page with page[page].

Path

scope_by[organization_id] string
Required. Organization UUID.

page[size] int32
Optional. Number of elements per page.

page[page] int32
Optional. Number of the page.

filter[available] string
Optional. Filters by whether a CatalogItem is available or not. Set to true or false.

filter[discontinued] string
Optional. Filters by whether a CatalogItem is discontinued or not. Set to true or false.

filter[online_orderable] string
Optional. Filters by whether a CatalogItem is online orderable or not. Set to true or false.

filter[catalog_id] string
Optional. Filters by Catalog UUID.

filter[product_variant_id] string
Optional. Filters by ProductVariant UUID.

filter[product_variant][product_id] string
Optional. Filters by Product UUID.

filter[product_variant][product][brand_id] string
Optional. Filters by Brand UUID.

GET Show

To fetch a CatalogItem, send a request to
/catalog/v1/catalog_items/CATALOG_ITEM_ID?scope_by[organization_id]=ORGANIZATION_ID.

Path

scope_by[organization_id] string
Required. Organization UUID.

catalog_item_id string
Required. CatalogItem UUID you want to fetch.

PATCH

To update a CatalogItem, send a payload with the below structure to
/catalog/v1/catalog_items/CATALOG_ITEM_ID?scope_by[organization_id]=ORGANIZATION_ID.

{
  "data": {
    "type": "catalog_items",
    "attributes": {
      "price_in_cents": 2000
    },
    "relationships": {
      "catalog": {
        "data": {
          "type": "catalogs",
          "id": "CATALOG_ID"
          }
      },
      "product_variant": {
        "data": {
          "type": "product_variants",
          "id": "PRODUCT_VARIANT_ID"
          }
      }
    }
  }
}

Path

scope_by[organization_id] string
Required. Organization UUID.

catalog_item_id string
Required. CatalogItem UUID you want to update.

Attributes

price_in_cents int32
Optional. The price in cents.

available boolean
Optional. Defaults to false. Designates whether the CatalogItem is available.

online_orderable boolean
Optional. Defaults to true. Designates whether the CatalogItem is online orderable.

discontinued_at boolean
Optional. Defaults to true. Designates whether the CatalogItem is discontinued.

type string
Required. Must be catalog_items.

Relationships

Catalog

catalog_id string
Required. Related Catalog UUID.

type string
Required. Must be catalogs.

ProductVariant

product_variant_id string
Required. Related ProductVariant UUID.

type string
Required. Must be product_variants.

DELETE

To delete a CatalogItem, send a request to
/catalog/v1/catalog_items/CATALOG_ITEM_ID?scope_by[organization_id]=ORGANIZATION_ID.

Path

scope_by[organization_id] string
Required. Organization UUID.

catalog_item_id string
Required. CatalogItem UUID you want to delete.

Updated 11 months ago