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    

Frequently Asked Questions

Why JSON:API?

Weedmaps Catalog API uses the JSON:API specification. It is recommended to interact with JSON:API via a formal client library (https://jsonapi.org/implementations/), rather than error-prone manual code.

Why are you asking me to use a client library?

We really think it will make your life easier. JSON:API is fairly chatty, and it's easy to misplace a { or [ character when rolling API calls by hand. The client libraries push all of that boilerplate down out of your way and let you concentrate on business logic.

What are the steps needed to create a Product?

The steps to create a product are detailed in the Defining a Product Line section of our Integrator Guide.

How do I make my Product visible on my Weedmaps page?

To learn how to make your Product visible in your Weedmaps page, visit the Making Products Discoverable section of our Integrator Guide.

How do you associate VariantAttributes and VariantValues to a ProductVariant?

In the Defining a Product Line section, we detail the steps to create a ProductVariant, apply a VariantAttribute, add a VariantValue, and then associate them together by creating a ProductVariantOption.

How does one work with Master Products?

To learn how to work with Master Products, visit the Product page where we detail how to use a Master Product as well as how to create your own Custom Product.

Why do I have to make so many separate GET show calls?

You probably don't. To use a real example, let's say you have a VariantAttribute called "Weight Breakpoint", and you want to retrieve all of the VariantValues associated with it. One way to do this would be to do a separate GET show call for every VariantValue ID.

Another way is to do a GET show call on the "Weight Breakpoint" VariantAttribute, but provide include=variant_values in your query parameters.

Includes can even be multi-stage. So if you do a GET show on a specific Product, you can add include=product_variants.product_variant_options.variant_attributes, and so on.

One of the many benefits of using a JSON:API client library is that (assuming you have a variable called weight_breakpoint representing the VariantAttribute mentioned above) you can simply refer to weight_breakpoint.variant_values, which is quite nicely readable. Details will depend on your specific client library implementation.

Why is my Product not showing up on Weedmaps?

  • It could lack a Category Tag as detailed in Making Your Product Line Visible.
  • Its Catalog Items could all have a 0 price. Check out the Managing Quantity Available section of our Displaying Items for Sale guide.
  • A created Catalog Item defaults to available: false. You must explicitly set it as available: true. You can update its availability using the PATCH endpoint.
  • Our systems are eventually consistent, so there may be some delay in creations or updates appearing, depending on system load.

How do I set a redirect_uri which is related to a specific clientId? / How to authenticate?

The redirect uri must be static. That redirect should be occurring in the client's browser. We recommend using an oauth2 client library that works with your web framework, so that you don't have to roll that all on your own. Failing to use a client library for both the oauth2 and JSON:API access is going to make interactions much harder for you than they need to be.

Since the redirect occurs in the client's browser, you should already know the client's ID from whatever your usual authentication mechanism is for your own application, at the point that the client's browser accesses the redirect uri. At the end of the oauth2 process, your callback endpoint should request an access and refresh token. You'll need to keep both around, but this all should be made much easier by your oauth2 client library.

You can send the access token to us in an authentication header to access your resources, but you must use your client library's expiration and refresh check first so that it will request a new token when the old one expires.

If you don't do the expiration/refresh check, then you will be forcing your users to go through the entire re-authorize process again (in their browser) every 2 weeks. We will be shortening the lifetime of the access tokens dramatically soon, and so you will experience this more and more often in the future.

For additional information about our authorization process, visit our OAuth guide.

What is the base URI I should use?

https://api-g.weedmaps.com/catalog/v1 is our base URI.

Why don't you have a batch endpoint for initial imports or maintenance updates?

We don't expect to need it for server performance concerns, and the added complexity required for processing batch data in a single compound request has proven troublesome.

Batch endpoints

  • don't respect the JSON:API specification, making tooling less useful.
  • increase latency for each request (especially with more complex data nesting), threatening SLA compliance.
  • re-invent the wheels already provided by several JSON:API client implementations.
  • require decisions about how responses should reflect mixed results in which some components were successful and other failed.
    • For example, assume a scenario in which you want to do a "batch" of 100 POST calls, 97 of which will succeed, and 3 of which will fail (for whatever reason). As an Integrator, keeping those calls separate allows you to see which calls succeeded, which failed, and (most importantly) why the 3 failures failed, with specifically-tailored error messages explaining how to retry with modified payloads.

Can you pass something along in the callback during authorization, so we know which user in our system we are authorizing for?

In short, this should not be needed. The client's browser is making the request, and they should already be authorized with you in a way that you can identify. OAuth2 is quite complicated, and we strongly suggest using a client library for this part of the process as well.

Is there a way to sort results returned by the API?

At this time, we do not provide a way to sort the results of an API call.

Updated 2 months ago

FAQ


Suggested Edits are limited on API Reference Pages

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