This version has a few major changes compared to 2023-07 (v1). We did our best to outline this upgrade process below. These are the top three to call out:

  1. πŸ‘‹ No more semi-compliant JSON:API responses in favor of dropping the JSON:API standard altogether, which means no more includes statements
  2. πŸ‘‹ Say goodbye to cursor-based pagination if favor of page and page_size
  3. πŸ™Œ Introduction of consistent response object formatting, query parameters, and identifiers


You can now fetch a single brand by ID. We've also migrated the autocomplete endpoint to a more generic one that accepts even more filter parameters. In that endpoint, term becomes filters[name][match]. The previous combination of term and sort[exact_match] can now be condensed to filters[name][eq], which is mutually exclusive with the filters[name][eq] param.


Our single products endpoint has been expanded to include three more endpoints relating to products.

The first of the three endpoints we added is a GET for a single product by ID. This returns the same product response you'd receive from the products index request. This endpoint's main utility is to verify that a product ID you may have in your system still exists in Weedmaps.

The second new endpoint fetches reviews for a specific product. It provides not only individual ratings for each dimension a product can be rated on, but also the average rating across all dimensions and the distribution of all ratings.

The third addition is a product classifier, powered by Weedmaps’ proprietary machine-learning model. Given a generic query term, this endpoint identifies the most closely matching products on Weedmaps. It also provides a confidence score to help you determine the accuracy of the match.


Additional Scope Requirements

Using the new classify and reviews endpoints on products requires additional scopes to be added to your JWT token. If you're interested in utilizing these, please contact Weedmaps at [email protected].


Menus see the addition of a single GET endpoint, but otherwise remain rather unchanged. The index endpoint now accepts more filters and sorting options.

Menu Items

Menu items see a number of deprecated fields being removed and new ones being added. The prices object (price_gram, price_eighth, etc) has been removed in favor of variants. If you were already using variants, that array has remained relatively unchanged and is backwards compatible with the new version.


External IDs Are Required

An external_id must be provided when creating a menu item in the new API. This should equate to the unique identifier in your system that most closely resembles a singular item available for purchase for a retailer. Since these are unique to a menu, they also act as an idempotency key to ensure we don't create duplicate records.

Another large change is how relationships like categories or menu are passed when creating or updating menu items. WM now simply accepts an array of IDs for that given attribute, such as category_ids. This also means the POST endpoint has moved to be off the menus endpoint instead of root menu items: /menu_items become /menus/{menu_id}/items.

On the topic of categories, we'll now do category, strain, and tags matching for you instead of you locating and provided our identifiers. Simply provide a list of category_names (in prioritized order), strain_names (any order), or tag_names (any order) and we'll take care of the rest.

Direct vs Indirect Management

Arguably the largest change to menu items is the ability manage them via your own external_id, without knowing any other identifier besides the Weedmaps Menu ID. This new flow allows you to feed Weedmaps a standard input and we'll generate the best menu item we can with that data. Best part is this is done as an upsert, which doesn't even require you to know if an item exists or not. Deleting an item by external_id also doesn't fail when the item does not exist.


Outside of menu items themselves, taxonomy saw the biggest increase in endpoints compared to the previous version. The major breaking change here is getting rid of UUIDs in favor of using integer IDs like we do everywhere else. This also means menu item responses will now have consistent identifiers with these endpoints.

Tags new return each individual tag with its associated group instead of tag groups with all tags within that group. This allows for better filtering capabilities and pagination, such as filtering on both tag and/or tag group name and when tags were last updated.

Similar to tags, categories also have a concept of groups (parents) they belong to. But different from tags, the entire category tree must be provided when creating a menu item or updating its categories. This is tricky when Weedmaps previously returned each individual category, leaving it up to the integrator to roll these up. We're then offering endpoints to solve both of these cases: one that's closest to the one we have today but paginated and another that returns our root categories with the entire tree of categories that fall beneath.

Lastly, we've added endpoints for fetching cannabinoids, terpenes, and strains. This is to support the added functionality to menu items, which includes managing more than just THC and CBD percentages and milligrams. You can now provide these measurements across all cannabinoids and terpenes WM has to offer.