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
product_variant_options, and others by allowing the same
?scope_by[organization_id]=XXXX to be passed for all Listings under the same account.
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_variant.sku to map to the POS SKU.
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.
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.
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.
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
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
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.
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.
When requesting support, it is best to provide as much of the following information as possible:
- 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.
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>'
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.
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.
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.
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
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
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
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
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 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
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>'
Updated 3 months ago