Best Practices

Associating Organizations

When creating a Catalog, you may either associate it to an existing Organization or have it generate a new one. If you already have an Organization associated to a client/account in your system, we recommend passing along that Organization ID when creating a new Catalog for that client/account. This streamlines the management of products, product_variants, product_variant_options, and others by allowing the same ?scope_by[organization_id]=XXXX to be passed for all Listings under the same account.

Updating Resources

We want updating resources to be as easy as creating them. It's actually much more difficult to recreate all resources rather than updating the existing ones. While this may seem a bit obtuse, it's better for both you and Weedmaps to update resources as it requires less compute time and data processing for you, as well as limits the amount of requests — which are rate limited — we need to ingest.

It is absolutely not expected for Integrators to keep references/keys to each resource; however, it is also not necessary to request all of the resources with relationships to the resource needing a single update. We recommend using the include parameter to request related resources only as needed.

For example, to update a catalog_item price without the catalog_item.id on hand or even the product.id on hand, you would make a request to the GET /product_variants endpoint and add include=catalog_items. Then, find the correct product_variants by product_variant.sku to map to the POS SKU.

Caching Resources

In addition to limiting the number of repeat calls necessary, some Integrators choose to cache data that is fairly static to allow faster searching for customers, especially for commonly-accessed resources like the following:

Tags/Taxonomy — Changes are very rare and we recommend caching for a week or two.
Verified/Master Brands — Since only a handful of new Brands are published each day (approximately two to 4), we recommend caching for 2 or 3 hours.
Verified/Master Products — New products are added every hour, however some Integrators choose to cache the products of more popular Verified Brands that do not add products all that often. We do not recommend a time length for caching, but it can probably be deduced by comparing the intervals of Verified Products added for whichever Verified Brands.

For example, if an Integrator caches the taxonomy resources along with all Verified Products under STIIIZY, and a client retailer wants to create a new STIIIZY-brand Verified Product, caching would make the three or more requests to each resource unnecessary as well as save the client retailer the time typically normally spent waiting on the data to populate.

Filtering Resources

When a specific name is known for a Brand, we recommend using the name filter, whereas [name][search] is a fuzzy word search that can be used to find similar Brands or if the user is unsure of the spelling.

Discontinuing Resources

As stated in the various guides above, we do not delete the main resource types to maintain data integrity. Instead, we've opted to discontinue certain resource types.

Typically discontinuing should be reserved for products that are no longer going to be stocked, or will not be stocked for a period of time. If a product is out of stock and will be restocked, the available field should be used and set to false.

Keep this in mind specifically when re-creating a product. Rather than creating an entirely new product, which essentially creates a duplicate, the preferred workflow is to un-discontinue a product, product_variant, catalog_item by sending a PATCH request for the resource.

Another related scenario to consider is when synchronizing the POS data with Weedmaps data: Rather than discontinuing the entire catalog to clear "stuck" out of stock catalog_items, simply discontinue the catalog_items and then un-discontinue all the catalog_items that should be on the menu. This clears out the menu in Weedmaps and allows a semi-fresh state to start with, as well as the added benefit of making fewer requests to Weedmaps.

Retrying Failed Requests

Be sure to consider rate limiting when implementing retry logic.

Please set a retry limit to prevent runaway requests, especially when receiving a 4xx error.

Support

When requesting support, it is best to provide as much of the following information as possible:

listing_wmid, catalog_id, or organization.id
Resource IDs
Steps to reproduce the error when relevant
Screenshots, especially for UI-specific issues

When support is needed on development or testing related issues:

Provide the full request and response if possible.
Make sure the User-Agent is set correctly.
if possible, provide a timestamp: If we need to look through logs, a timestamp helps narrow it down further.

Check Listing (WMID) Access

There may be times when you want to see if you have access to a given listing. This may help you troubleshoot issues if you start receiving unauthorized responses from our API for a given WMID.

To check your access, send the following request, passing your bearer token in the header.

401: Your token does NOT have access to the provided WMID
404: Your token DOES have access; the catalog has not been created
200: Your token DOES have access; the existing catalog is returned

curl --globoff \
  --request GET \
  --url 'https://api-g.weedmaps.com/catalog/v1/catalogs?filter[listing_wmid]=<WMID_HERE>' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer <ACCESS_TOKEN_HERE>'

Re-Integrating a Client Retailer

We recommend utilizing the GET /catalogs endpoint and filtering by listing_wmid to first check if a new client retailer had a previous integration. If the retailer had integrated before, this will return a list of the catalog data and relationships to an organization associated to the provided listing_wmid. If not, it will return an error.

If the client retailer does not want to continue using the catalog_items already in their catalog, or your system does not yet support ingesting existing catalog or organization data, we recommend first fetching all non-discontinued catalog_items and proceeding to discontinue all of them.

Integrator Re-Sync Tooling

In a perfect world, there are never any dropped requests, internal service errors, Internet connectivity issues, or power outages; unfortunately, we need to plan for the worst.

With that in mind, when integrating with Weedmaps, bear in mind that we treat the POS as the source of truth: Only the POS system knows what should or should not exist in the Weedmaps catalog. In the unlikely event of a dropped request, Weedmaps has no way of knowing what data should or should not exist in our system.

When this happens, it is up to the POS provider to resolve any conflicts. A re-sync tool can be created by the POS that fetches data from Weedmaps Catalog API: It then looks for inconsistencies and then follows up with requests to Weedmaps Catalog API to either create, update, or delete/discontinue resources so that the POS and Weedmaps Catalog API are synchronized.

Inclusion of Related Resources

When using an include, we return each of the resources, not just the last-listed resource. For example, product.brand will return the associated Brand and Products as opposed to the Brand only.

A complete list of the allowed inclusions for each resource is below.

Batches

organization
product
product.brand
product.brand.organization
product.organization
product.tags
product.product_images
product.product_variants.product_variant_options
product.product_variants.product_variant_options.variant_attribute
product.product_variants.product_variant_options.variant_value

Brands

organization

Catalog Items

catalog
catalog.organization
product_variant
product_variant.product
product_variant.product.batches
product_variant.product.brand
product_variant.product.brand.organization
product_variant.product.product_images
product_variant.product.tags
product_variant.product_variant_options
product_variant.product_variant_options.variant_attribute
product_variant.product_variant_options.variant_value

Catalogs

organization
catalog_items
catalog_items.product_variant
catalog_items.product_variant.product
catalog_items.product_variant.product.batches
catalog_items.product_variant.product.brand
catalog_items.product_variant.product.product_images
catalog_items.product_variant.product.tags
catalog_items.product_variant.product_variant_options
catalog_items.product_variant.product_variant_options.ariant_attribute
catalog_items. product_variant.product_variant_options.variant_value

Products

batches
brand
brand.organization
organization
product_images
product_variants
product_variants.catalog_items
product_variants.product_variant_options
product_variants.product_variant_options.variant_attribute
product_variants.product_variant_options.variant_value
tags

Product Variant

catalog_items
product
product.batches
product.brand
product.brand.organization
product.organization
product.tags
product.product_images
product_variant_options
product_variant_options.variant_attribute
product_variant_options.variant_value
variant_attributes
variant_values.variant_attribute

Product Variant Options

product_variant
product_variant.product
product_variant.product.batches
product_variant.product.brand
product_variant.product.brand.organization
product_variant.product.organization
product_variant.product.product_images
product_variant.product.tags
variant_attribute
variant_value

Examples

One example shown below is pulling the entire catalog and all associated resources. This could be useful when ingesting data for a new client that already has an existing catalog.

curl -v --request GET \
 --url 'https://api-g.weedmaps.com/catalog/v1/catalogs?scope_by%5Borganization_id%5D=<org_uuid>&include=organization,catalog_items,catalog_items.product_variant,catalog_items.product_variant.product,catalog_items.product_variant.product.batches,catalog_items.product_variant.product.brand,catalog_items.product_variant.product.product_images,catalog_items.product_variant.product.tags,catalog_items.product_variant.product_variant_options,catalog_items.product_variant.product_variant_options.variant_attribute,catalog_items.product_variant.product_variant_options.variant_value' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer <access_token>'