Defining A Product Line

Overview

The goal of this section is to define a Product line. To do so, we will need to create a few different resources. The steps break down like this:

  1. Create a Brand
  2. Create a Product
  3. Create a Product Variant
  4. Fetch a Variant Attribute
  5. Fetch a Variant Value
  6. Create a Product Variant Option
  7. Create a Product Image (optional)
  8. Create a Batch (optional)

Step 1: Create a Brand

Brands represent a distributor, manufacturer, or seller of products. Two distinct types of Brands are represented in the Weedmaps Catalog API.

The first, a Custom brand resource, can be created on a per Organization basis. This is denoted by the attribute is_master: false.

The second type is a Master brand resource. These have Brand pages on Weedmaps, such as the Brands listed in this directory, and cannot be directly user created. This is denoted by the attribute is_master: true.

For this guide, we are going to create a Custom brand. We will visit the API Reference Brand POST to generate the cURL command. Required fields in the payload are name and an organization in the relationship. While is_master is a required field, it defaults to false so we do not need to include it in the payload. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/brands?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
    	"attributes": {
      	"name": "The A-Team", 
        "is_master": false
      },
      "relationships": {
      	"organization": {
        	"data": {
          	"type": "organizations",
            "id":"da78484e-4c16-4a85-b78e-18664c323623"
          }
        }
      },
      "type": "brands"
    }
  }'

📘

Be sure to save the brand ID from your response as it will be needed later in the guide.

Step 2: Create a Product

Now that you have a brand, you need a product that belongs to it. Like Brands, Weedmaps supports a Custom product resource as well as separate Master product resources. A Custom product can only be associated with a Custom brand. Likewise, a Master product can only be associated with a Master brand.

To create our first product, we will use the API Reference Product POST to generate the cURL command. Required fields in the payload are name, and a brand and an organization in the relationship. While is_master is a required field, it defaults to false so we do not need to include it in the payload. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/products?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
    	"attributes": {
      	"is_master": false,
        "name": "Faceman Weed",
        "description": "Will get you feeling suave and persuasive."
      },
      "relationships": {
        "brand": {
          "data": {
            "type": "brands",
            "id":"f41e5deb-0010-4849-9491-6af55c454dd7"
          }
        },
        "organization": {
          "data": {
            "type": "organizations",
            "id": "da78484e-4c16-4a85-b78e-18664c323623"
          }
        }
      },
      "type": "products"
    }
  }'

📘

Be sure to save the product ID from your response as it will be needed later in the guide.

Step 3: Create a Product Variant

The product_variant resource describes a version — or variant — of a product. A product_variant helps describe all the possibilities of a product line.

To create a product variant, we will use the API Reference Product Variant POST to generate the cURL command. Required fields in the payload are msrp_in_cents and sku, and a product in the relationship. While sold_by_weight is a required field, it defaults to false, so we do not need to include it in the payload. However, since we are making a flower product in this example, we will set it to true. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/product_variants?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
    	"attributes": {
      	"sold_by_weight": true,
        "msrp_in_cents": 2000,
        "sku": "I420AAY"
      },
      "relationships": {
      	"product": {
        	"data": {
            "type": "products",
            "id":"76154f4e-4899-43e6-838d-74653f816053"
          }
        }
      },
      "type": "product_variants"
    }
  }'

📘

Be sure to save the product_variant ID from your response as it will be needed later in the guide.

Step 4: Fetch a Variant Attribute

Now that you have your product_variant, you're able to move on to listing the various options available. The first step is to fetch a variant_attribute resource. A variant_attribute describes how a product line will be measured out in units. Examples might be the size of a T-shirt, or the weight breakpoint of flower. For our example, we will be using weight breakpoint.

While we could create a new variant_attribute, we have a list of weight breakpoint values already defined by Weedmaps that we can use. We will fetch the weight breakpoint ID to use. To fetch a variant_attribute, we will use the API Reference Variant Attribute GET to generate the cURL command. Including filter[name]=weight allows you to return all variant_attributes with weight in the name. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request GET \
  --url 'https://api-g.weedmaps.com/catalog/v1/variant_attributes?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623&filter[name]=weight' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]'

In this response, you will notice 10 variant_values in the relationship. Each of these corresponds to one of the values already defined by Weedmaps. We will be fetching one of them in the next section.

📘

Be sure to save the variant_attribute ID from your response — it will be different than the one in our example — as it will be needed later in the guide.

Step 5: Fetch a Variant Value

The variant_value resource is the unit of quantity for a given variant_attribute on a particular product_variant. For example, if your flower's variant_attribute is weight breakpoint, a corresponding variant_value might be 1 g. A t-shirt's variant_attribute of size could have a corresponding variant_value of large. As with the previous resources, an Organization can define its own custom variant_values or use common variant_values maintained by Weedmaps.

To fetch a variant_value, we will use the API Reference Variant Value GET to generate the cURL command. We will include filter[variant_attribute_id]=VARIANT_ATTRIBUTE_ID — use the variant_attribute ID you saved in the previous step — to limit the variant_values to those that belong to weight breakpoint. We will further filter the results using filter[value]=1 g to return the value 1 g. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request GET \
  --url 'https://api-g.weedmaps.com/catalog/v1/variant_values?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623&filter[value]=1%20g&filter[variant_attribute_id]=c0a1dd4d-3f67-43a4-8034-abc9d837b4ac' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]'

📘

Be sure to save the variant_value ID from your response — it will be different than the one in our example — as it will be needed later in the guide.

Step 6: Create a Product Variant Option

While a product_variant (SKU) helps describe all the possibilities of a product line, a product_variant_option resource specifies the different possible varieties of a SKU in that Product line. To create a product variant option, you'll need to combine a product variant, a variant attribute, and a variant value.

To create our product_variant_option, we will use the API Reference Product Variant Option POST to generate the cURL command. Required fields in the payload are the product_variant, variant_attribute, and variant_value in the relationship. Your generated cURL command should like similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/product_variant_options?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
    	"relationships": {
      	"product_variant": {
        	"data": {
          	"type": "product_variants",
            "id": "76a159be-1fd6-4726-90fa-ec814ec68d3a"
          }
        },
        "variant_attribute": {
        	"data": {
          	"type": "variant_attributes",
            "id": "c0a1dd4d-3f67-43a4-8034-abc9d837b4ac"
          }
        },
        "variant_value": {
        	"data": {
          	"type": "variant_values",
            "id": "adbfc32f-4005-481e-bfaf-f4f7674c336c"
          }
        }
      },
      "type": "product_variant_options"
    }
  }'

👍

Congratulations!

You have successfully created your first Product Variant Option resource. Remember, you'll need to move on to the Making Products Discoverable section before your product line will be visible on Weedmaps.

If you also want to understand how an image and THC/CBD data is added to a product, feel free to finish up this page. These sections are completely optional.

Step 7: Create a Product Image (optional)

People like to see the product they're purchasing; to make that happen, a product_image must be attached to the product we've created.

To create a product_image, we will use the API Reference Product Image POST to generate the cURL command. The only required field in the payload is image_url, and a product in the relationship. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/product_images?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
    	"attributes": {
        "image_url": "https://picsum.photos/id/237/600/400.jpg",
    	},
    	"relationships": {
      	"product": {
        	"data": {
          	"id": "76154f4e-4899-43e6-838d-74653f816053",
          	"type": "products"
        	}
      	}
    	},
      "type": "product_images"
  	}
	}'

Step 8: Create a Batch (optional)

Customers, and especially patients, look for the potency of the products they're purchasing. The last step is to attach the batch data to a product. Not to be confused with batching requests, this data informs the consumer how much THC and CBD are present in a given product. Just like with the product_image, this type of information helps customers with their purchasing decisions.

To create a batch, we will use the API Reference Batch POST to generate the cURL command. Required fields in the payload are cbd_amount, thc_amount, and unit_type, along with a product and organization in the relationship. Your generated cURL command should look similar to our example below.

curl --globoff \
  --request POST \
  --url 'https://api-g.weedmaps.com/catalog/v1/batches?scope_by[organization_id]=da78484e-4c16-4a85-b78e-18664c323623' \
  --header 'accept: application/vnd.api+json' \
  --header 'authorization: Bearer [ACCESS TOKEN HERE]' \
  --header 'content-type: application/vnd.api+json' \
  --data '{
  	"data": {
      "attributes": {
        "cbd_amount": 1.8,
        "thc_amount": 23.4,
        "unit_type": "percent"
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "da78484e-4c16-4a85-b78e-18664c323623",
            "type": "organizations"
          }
        },
        "product": {
          "data": {
            "id": "76154f4e-4899-43e6-838d-74653f816053",
            "type": "products"
          }
        }
      },
      "type": "batches"
    }
  }'

🚧

Only "percent" Values Are Visible

While both "percent" and "milligrams" are acceptable unit_type values, only "percent" values are currently supported in the Weedmaps UI for Catalog.