Catalog API

The PIM Developer Hub

Welcome to the PIM developer hub. You'll find comprehensive guides and documentation to help you start working with PIM as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Working with Businesses and Locations

Overview

For starters, we'd like to clarify some terminology. This should help you understand what Weedmaps calls things in the following guides and in our API Reference docs.

At the highest level in the Weedmaps product hierarchy you have an Organization. We consider an Organization to be the primary business entity or retailer.

An Organization may have multiple locations, such as a dispensary or a delivery service where product is kept. These locations are referred to as Listings. Each Listing in Weedmaps is assigned a unique identifier called a Listing WMID. You may see this displayed as WMID in the Weedmaps UI, such as in a dispensary's Admin Panel. It's through this Listing WMID value that we associate a menu to a given location.

Speaking of menus, we call those Catalogs, hence the name Catalog Service.

Weedmaps Listings

In order to sync a POS with a Listing (location) on Weedmaps, each Catalog (menu) created needs to point to exactly one Listing WMID. Since a business can have many Catalogs — one for each Listing — those are all scoped under the primary business by the Organization ID. Said another way, an Organization can have multiple Listings, a Listing can only have one Catalog, and all Catalogs belongs to a single Organization.

When you create your first Catalog, an Organization is automatically generated for you if you don't specify an existing Organization in the request. This is explored in the example below.

Integrators and Clients with Multiple Locations

As an Integrator, you will need the Listing WMID for each of your client's locations. Accordingly, we recommend having a place in your UI where your clients can enter their own WMIDs directly.

The Listing Owner can find their Listing WMID in their Weedmaps Admin Panel. This is displayed to them as a WMID.

Create Your First Catalog

The goal is to create a Catalog for a location using the catalog resource. The first time you create a catalog for an Organization, you only need a listing_wmid. Each listing_wmid can only be used to create one catalog. If you try to re-use a listing_wmid, you will receive an error.

To create our first catalog, we will use the API Reference Catalog POST to generate the necessary cURL command. Required fields are the listing_wmid, type, and authorization. Since this is the first catalog we have created and we did not include an organization in the relationship, one was created for us.

curl --globoff \
    --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/catalogs' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
    "data": {
        "attributes": {
        "listing_wmid": 420710
      },
      "type": "catalogs"
    }
  }'
{
  "data" : {
    "attributes" : {
      "inserted_at" : "2020-04-29T17:52:27.068213",
      "listing_wmid" : 420710,
      "updated_at" : "2020-04-29T17:52:27.068213"
    },
    "id" : "f8382b94-7f0a-45bb-90b2-d3d70825a9e9",
    "links" : {
      "self" : "http://catalog-service.weedmaps.com/api/v1/catalogs/f8382b94-7f0a-45bb-90b2-d3d70825a9e9?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623"
    },
    "relationships" : {
      "catalog_items" : {
        "data" : [],
        "links" : {
          "related" : "https://api-g.weedmaps.com/catalog/v1/catalog_items",
          "self" : "https://api-g.weedmaps.com/catalog/v1/catalogs/f8382b94-7f0a-45bb-90b2-d3d70825a9e9/relationships/catalog_items"
        }
      },
      "organization" : {
        "data" : {
          "id" : "da78484e-4c16-4a85-b78e-18664c323623",
          "type" : "organizations"
        },
        "links" : {
          "related" : "https://api-g.weedmaps.com/catalog/v1/organizations/da78484e-4c16-4a85-b78e-18664c323623",
          "self" : "https://api-g.weedmaps.com/catalog/v1/catalogs/f8382b94-7f0a-45bb-90b2-d3d70825a9e9/relationships/organization"
        }
      }
    },
    "type" : "catalogs"
  },
  "included" : [],
  "links" : {
    "self" : "http://catalog-service.weedmaps.com/api/v1/catalogs/f8382b94-7f0a-45bb-90b2-d3d70825a9e9?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623"
  }
}

A couple things to note going forward:

  • The type field is required for all POST and PATCH requests. It's also needed for any request with a required relationship. However, the API Reference automatically inserts the necessary type information for you. Be sure to include it when building out your integration.
  • When entering your access_token in the authorization field, be sure to prefix it with Bearer.
  • You can add | json_pp to the end of the cURL command to have the JSON response returned with pretty print.

📘

Be sure to save the catalog ID and the organization ID from your response as they will be needed during the rest of the guide.

Create Multiple Catalogs for the Same Organization

As we mentioned earlier, an organization can have multiple catalogs. Creating a catalog when you already have an organization is very similar to the previous step, except this time you provide an organization in the relationship.

*You don't need to create a second catalog to continue with the guide.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/catalogs' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
    "data": {
        "attributes": {
        "listing_wmid": 710420
      },
      "relationships": {
        "organization": {
            "data":{
            "id": "da78484e-4c16-4a85-b78e-18664c323623",
            "type": "organizations"
          }
        }
      },
      "type": "catalogs"
    }
  }'
{
  "data": {
    "attributes": {
      "listing_wmid": 710420
    },
    "id" : "f8382b94-7f0a-45bb-90b2-ks8ds0kls93",
    "relationships": {
      "organization": {
        "data": {
          "id": "da78484e-4c16-4a85-b78e-18664c323623",
          "type": "organizations"
        }
      }
    },
    "type": "catalogs"
  }
}

Scoping API Requests by Catalog or Organization

Now that you have a catalog and an organization, you can use it to scope API requests to a particular location. The API Reference lists all endpoints that accept either a catalog_id or an organization_id as a scope. Either one of those two are required for all operations: using a catalog_id will limit operations to a location while using the organization_id to the whole business.

👍

Congratulations!

You now have all the necessary resources to start populating and syncing your Catalogs. But before we get to creating Products, let's begin by Understanding a Product Page on Weedmaps.

Updated about a year ago

Working with Businesses and Locations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.