Integrator Setup

For Orders to be transmitted, there are callback (webhook) events that must be configured. If the integration is not configured accurately, the transmission of the events will not occur. As the integrated platform, you must provide us with the URL pattern(s) that the WM Orders interface should use.

An example URL is below.

https://integrator-host.com/callbacks/weedmaps/orders?merchant_id={{merchantId}}

📘

As of October 2020, your URL patterns must be provided to Weedmaps developers via your preferred line of communication (a private shared Slack channel or email).
Please note that a self-service interface is currently in development.

Callbacks

Callbacks, also referred to as webhooks, are secure HTTP requests made from Weedmaps to your configured system. These requests carry a payload that is the JSON-formatted Order object.
There are two callback events related to the WM Orders service: Draft and Create.
A specific callback URL can be configured for each of these events, or a single URL can be configured as a default for all events.

Merge Variables

Weedmaps callbacks support the use of merge variables in the configuration of the URL. To interpolate the values of these variables, use the format {{ variableName }} when configuring the URL string.

Below is an example URL with the merchantId variable as a query parameter.

https://integrator-host.com/callbacks/weedmaps/orders?merchant_id={{merchantId}}

Supported Merge Variables

As of October 2020, the merge variables listed below are supported by the Orders API.

• merchantId — The unique identifier for each location of a client retailer, also referred to as the Weedmaps Listing ID or simply Listing WMID. This identifier is the same ID used for the Catalog API menu integration.

Authenticating the Signature of a Callback

Callbacks from Weedmaps are signed with an HMAC SHA256 signature included as a header Signature on the callback request.

When establishing an integration with the Orders callbacks, integrators will be provided with a client secret that is unique to their integration. The client secret will be a version 4 UUID.

To confirm authenticity of the callback request:

1. Using HMAC SHA256 encryption, encrypt the JSON body of the callback as the message and the provided client secret as the secret.
2. Encode the encrypted string using Base64 encoding.
3. Compare the encoded string against the value of the Signature header on the callback request.
4. If these strings match, the callback is authentic.

Events

Draft

After a customer/patient has finished shopping and they are ready to check out, they are shown a preliminary order total with estimated taxes and fees. Before the order is sent to the retailer, Weedmaps sends the POS what's referred to as a Draft Order — or Draft event — to cross-check the accuracy of prices, applicable taxes and fees.

Below is a screenshot with an example of a Draft Order as it's displayed to a customer/patient in the Weedmaps UI.

The Draft event is asking for a quote. This gives the integrated POS platform the opportunity to more accurately represent the cost that the customer will incur.

The Draft event is a synchronous callback that expects a response confirming item availability and order totals estimation.

The order payload will be delivered in the request with a status of DRAFT "status":"DRAFT". This payload will also include line items, discounts, and any fees configured for Weedmaps orders. Limited or no customer information is provided during the Draft event.

Here is an example of a Draft event with a status of DRAFT.

{
  "fees": [
    {
      "name": "Weedmaps Service Fee",
      "amount": "0.00",
      "feeType": "WM_SERVICE_FEE"
    },
    {
      "name": "Delivery Fee",
      "amount": "0.00",
      "feeType": "DELIVERY_FEE"
    }
  ],
  "taxes": [
    {
      "name": "Excise tax",
      "amount": "0.24",
      "taxType": "EXCISE"
    },
    {
      "name": "Sales tax",
      "amount": "0.24",
      "taxType": "SALES"
    }
  ],
  "seller": {
    "id": "835493541",
    "name": "The Grow - North Side",
    "city": "Des Moines",
    "phone": "+13027451360",
    "address1": null,
    "address2": "",
    "province": "IA",
    "postalCode": "90277",
    "countryCode": "US"
  },
  "source": "WEEDMAPS",
  "status": "DRAFT",
  "orderId": "9779604",
  "version": "2020-05-08",
  "currency": "USD",
  "customer": {
    "id": "",
    "dob": null,
    "phone": "",
    "lastName": "",
    "firstName": "",
    "hasMedicalRecommendation": true,
    "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
  },
  "feeTotal": "0.00",
  "payments": [
    {
      "amount": "0.00",
      "paymentType": "CASH"
    }
  ],
  "subtotal": "20.00",
  "taxTotal": "0.48",
  "createdAt": "2020-09-29T18:07:38Z",
  "discounts": [],
  "documents": [],
  "lineItems": [
    {
      "id": "21533747",
      "url": "https://weedmaps.com/deliveries/commerce-delivery-demo/product-grams-8g",
      "name": "Product Grams 8g",
      "brand": null,
      "imageUrl": "https://images.weedmaps.com/large/image_missing.jpg",
      "quantity": 1,
      "externalId": "5f6a5043d9b18c4826795b1a",
      "wmProductId": "45885942",
      "adjustedPrice": "20.00",
      "originalPrice": "20.00",
      "weightBreakpoint": "TWO_GRAM"
    }
  ],
  "grandTotal": "20.48",
  "customerNote": "",
  "discountTotal": "0.00",
  "lastModifiedAt": "2020-09-29T18:07:34Z",
  "shippingAddress": {},
  "deliveryPackages": [],
  "fulfillmentMethod": "DELIVERY"
}

Responding to this event with an order payload will update the corresponding order with estimates relayed in the response. These updates will be relayed to the customer/patient through the Weedmaps UI.

Below is a screenshot using the same example order. The taxes and fees have been updated, and the new totals are shown to the customer/patient.

If this request times out or errors, then the original cart estimates presented to the customer/patient will remain unchanged in the ordering process.

Create

The Create event is an asynchronous callback that expects a response with status code 200 or 201. If the request receives an error or times out, two more attempts are made.

The order payload included in this request will have a status of PENDING and will contain the complete order including the customer/patient information.

Below is an example of a Create event with a status of PENDING.

{
  "fees": [
    {
      "name": "Weedmaps Service Fee",
      "amount": "0.00",
      "feeType": "WM_SERVICE_FEE"
    },
    {
      "name": "Delivery Fee",
      "amount": "0.00",
      "feeType": "DELIVERY_FEE"
    }
  ],
  "taxes": [
    {
      "name": "Excise tax",
      "amount": "0.27",
      "taxType": "EXCISE"
    },
    {
      "name": "Sales tax",
      "amount": "1.50",
      "taxType": "SALES"
    }
  ],
  "seller": {
    "id": "835493541",
    "name": "The Grow - North Side",
    "city": "Des Moines",
    "phone": "+13027451360",
    "address1": null,
    "address2": "",
    "province": "IA",
    "postalCode": "90277",
    "countryCode": "US"
  },
  "source": "WEEDMAPS",
  "status": "PENDING",
  "orderId": "9763822",
  "version": "2020-05-08",
  "currency": "USD",
  "customer": {
    "id": "9063167",
    "dob": "1976-03-03",
    "phone": "9997770082",
    "lastName": "Dobbs",
    "firstName": "Bob",
    "hasMedicalRecommendation": true,
    "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
  },
  "feeTotal": "0.00",
  "payments": [
    {
      "amount": "0.00",
      "paymentType": "CASH"
    }
  ],
  "subtotal": "10.00",
  "taxTotal": "1.77",
  "createdAt": "2020-09-28T22:24:44Z",
  "discounts": [],
  "documents": [
    {
      "url": "https://api-g.weedmaps.com/oos/merchants/835493541/documents/9763822--dde72278-facc-41ff-9548-d4e9b149edbd/url",
      "documentType": "MEDICAL_RECOMMENDATION"
    },
    {
      "url": "https://api-g.weedmaps.com/oos/merchants/835493541/documents/9763822--cba1ca4a-a1bc-43fc-94ad-4a1407a75a08/url",
      "documentType": "GOVERNMENT_ISSUED_ID"
    }
  ],
  "lineItems": [
    {
      "id": "21498418",
      "url": "https://weedmaps.com/deliveries/commerce-delivery-demo/product-grams-8g-custom",
      "name": "Product Grams 8g, CUSTOM",
      "brand": null,
      "imageUrl": "https://images.weedmaps.com/large/image_missing.jpg",
      "quantity": 1,
      "externalId": "5f6a5043d9b18c4826795b1a",
      "wmProductId": "46148193",
      "adjustedPrice": "10.00",
      "originalPrice": "10.00",
      "weightBreakpoint": "UNIT"
    }
  ],
  "grandTotal": "11.77",
  "customerNote": "",
  "discountTotal": "0.00",
  "lastModifiedAt": "2020-09-28T22:24:44Z",
  "shippingAddress": {
    "city": "Johnston",
    "address1": "6523 Northwest 97th Street",
    "address2": null,
    "latitude": "41.677185",
    "province": "IA",
    "longitude": "-93.751022",
    "postalCode": "50131",
    "countryCode": "US"
  },
  "deliveryPackages": [],
  "fulfillmentMethod": "DELIVERY"
}

Updating an Order

Adjustments are common practice when processing customer orders. Availability, discounts, and tax corrections are a few reasons as to why adjustments occur.

In the event of a DRAFT, respond with an HTTP status code of 200 and the Order object in the body after all adjustments have been made.

Based on the Order object in the response, Weedmaps presents the following to the customer/patient:

• Discounts, Totals, and Taxes will be displayed to reflect the values in the response.
• Line Items removed will be removed from the order displayed. (Deprecated 10-6-21 and will no longer be supported on 2-1-22: For Draft responses, set item quantity to zero so that changes are communicated to the customer. For Created Orders when changes result in zero line items, we advise canceling the order. )
• Line Items marked with a quantity of zero will be identified as "unavailable" and require the customer/patient to remove these items before the order can be submitted.

After the order has been finalized and submitted for fulfillment in the POS system, updates to the order must conform to the Order object structure and then be transmitted to the below HTTP endpoint.

https://api-g.weedmaps.com/oos/integrators/v2/merchants/:merchantId/orders/:orderId

• :merchantId is the WMID associated with the POS retailer's location.
• :orderId is the target order's reference identifier.

Components of the Order That Can Be Modified by the POS System

• lineItems
• Totals
• discounts
• shippingAddress
• payments

Components of the Order That Cannot Be Modified by the POS System

• Customer/Patient Information
• Seller Information
• source
• orderId
• Weedmaps Service Fee
• documents
• customerNote

📘

The Weedmaps Service Fee is enabled by default in the retail client's Weedmaps account. When enabled, the Weedmaps Service Fee is shared with the integrated POS platform in the Draft event.

Status Updates

When a customer/patient places an order on Weedmaps, they are provided status updates about their order via text message.

Though order status updates aren't required, they enhance the customer experience, and help build confidence and trust with the retailer. Weedmaps encourages retailers to keep its customers informed with order status updates.

Additionally, Weedmaps promotes retailers that go the extra mile to provide customers/patients with great customer service by awarding them with a Best of Weedmaps badge. Providing accurate order statuses helps retailers receive added visibility on Weedmaps.

Available Statuses for Orders

• DRAFT
• PENDING
• IN_PROGRESS
• READY_FOR_ATTAINMENT
• COMPLETE
• CANCELED_CUSTOMER
• CANCELED_SELLER
• FAILED

Below is a partial screenshot of a retailer page on Weedmaps with a "Best of Weedmaps" distinction.

Versioning

We continue to enhance our ordering system, and the Order object may change over time. Multiple versions of the Order object may become available when breaking changes are unavoidable.

As an integrated platform, you will need to specify which version of the Order object you want to receive in callbacks, and which version is included in an update request.

Backwards-Compatible Changes

The following changes are considered to be backwards-compatible:

• Adding new API resources
• Adding new optional request parameters to existing API methods
• Adding new properties to existing API responses
• Changing the order of properties in existing API responses
• Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings
• Adding or removing fixed prefixes (such as WM###### for an object ID)
• Adding new event types (your webhook listener should gracefully handle unfamiliar event types)

📘

You can safely assume the object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If, for example, you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

The Order Object

{
    "version": "<date>",
    "source": "<string>",
    "subtotal": "<decimal>",
    "taxTotal": "<decimal>",
    "discountTotal": "<decimal>",
    "feeTotal": "<decimal>",
    "grandTotal": "<decimal>",
    "status": "<string>",
    "orderId": "<string>",
    "createdAt": "<dateTime>",
    "lastModifiedAt": "<dateTime>",
    "currency": "<string>",
    "customer": {
        "firstName": "<string>",
        "lastName": "<string>",
        "id": "<string>",
        "phone": "<string>",
        "dob": "<date>",
        "hasMedicalRecommendation": "<boolean>",
        "medicalRecommendation": {
          "id": "<string>",
          "expires": "<string>",
          "caregiverId": "<string>",
          "province": "<string>"
        }
    },
    "seller": {
        "id": "<string>",
        "name": "<string>",
        "address1": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "province": "<string>",
        "countryCode": "<string>",
        "phone": "<string>",
        "postalCode": "<string>"
    },
    "customerNote": "<string>",
    "documents": [
        {
            "documentType": "<string>",
            "url": "<uri>"
        },
        {
            "documentType": "<string>",
            "url": "<uri>"
        }
    ],
    "lineItems": [
        {
            "id": "<string>",
            "externalId": "<string>",
            "wmProductId": "<string>",
            "name": "<string>",
            "weightBreakpoint": "<string>",
            "brand": "<string>",
            "quantity": "<integer>",
            "originalPrice": "<decimal>",
            "adjustedPrice": "<decimal>",
            "url": "<string>",
            "imageUrl": "<string>"
        },
        {
            "id": "<string>",
            "externalId": "<string>",
            "wmProductId": "<string>",
            "name": "<string>",
            "weightBreakpoint": "<string>",
            "brand": "<string>",
            "quantity": "<integer>",
            "originalPrice": "<decimal>",
            "adjustedPrice": "<decimal>",
            "url": "<string>",
            "imageUrl": "<string>"
        }
    ],
    "discounts": [
        {
            "appliesTo": "<string>",
            "discountType": "<string>",
            "value": "<decimal>",
            "amount": "<decimal>",
            "description": "<string>",
            "discountCode": "<string>"
        },
        {
            "appliesTo": "<string>",
            "discountType": "<string>",
            "value": "<decimal>",
            "amount": "<decimal>",
            "description": "<string>",
            "discountCode": "<string>"
        }
    ],
    "taxes": [
        {
            "name": "<string>",
            "taxType": "<string>",
            "amount": "<decimal>"
        },
        {
            "name": "<string>",
            "taxType": "<string>",
            "amount": "<decimal>"
        }
    ],
    "fees": [
        {
            "name": "<string>",
            "feeType": "<string>",
            "amount": "<decimal>"
        },
        {
            "name": "<string>",
            "feeType": "<string>",
            "amount": "<decimal>"
        }
    ],
    "fulfillmentMethod": "<string>",
    "deliveryPackages": [
        {
            "serviceIdentifier": "<string>",
            "id": "<string>",
            "statusUrl": "<string>"
        },
        {
            "serviceIdentifier": "<string>",
            "id": "<string>",
            "statusUrl": "<string>"
        }
    ],
    "payments": [
        {
            "paymentType": "<string>",
            "amount": "<decimal>"
        },
        {
            "paymentType": "<string>",
            "amount": "<decimal>"
        }
    ],
    "shippingAddress": {
        "address1": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "province": "<string>",
        "countryCode": "<string>",
        "postalCode": "<string>",
        "latitude": "<string>",
        "longitude": "<string>"
    }
}

Weedmaps Order Management v2020-08-05

Scroll down for code samples, example requests, and responses.

Schemas

Customer

{
  "id": "123456789",
  "firstName": "Geovanni",
  "lastName": "Feil",
  "phone": "+15555556852",
  "dob": "1980-01-01",
  "hasMedicalRecommendation": true,
  "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
}

Properties

MedicalRecommendation

{
    "id": "123456789",
    "expires": "2025-01-01",
    "caregiverId": "12345",
    "province": "CA"
}

Properties

CustomerId

"WM123456"

The Order's Customer ID — This value is provided by the party that created the order.

Properties

Discount

{
  "appliesTo": "SUBTOTAL",
  "discountType": "PERCENTAGE",
  "value": "5",
  "amount": "4.99",
  "description": "5% off flower",
  "discountCode": "5FLOWER"
}

Properties

Enumerated Values

Document

{
  "documentType": "GOVERNMENT_ISSUED_ID",
  "url": "https://example.com/photo.jpg?sig=1234abc"
}

Properties

Enumerated Values

Fee

{
  "name": "Weedmaps Service/Tech Fee",
  "feeType": "WM_SERVICE_FEE",
  "amount": "4.99"
}

Properties

LineItem

{
  "id": "123456789",
  "externalId": "abc12345",
  "wmProductId": "123456789",
  "name": "Mendo Berries Refined Live Resin™ 0.5g Cartridge",
  "weightBreakpoint": "GRAM",
  "brand": "Raw Garden™",
  "quantity": 2,
  "originalPrice": "99.99",
  "adjustedPrice": "75.99",
  "url": "https://weedmaps.com/dispensaries/awesome-dispensary/menu/golden-pineapple",
  "imageUrl": "https://images.weedmaps.com/products/000/106/848/avatar/large/1563555258-RG-vapecart-01.jpg"
}

Properties

Enumerated Values

MerchantId

"12345678"

Weedmaps identifier representing the merchant

Properties

Order

{
  "orderId": "99998888000",
  "version": "2020-04-20",
  "status": "IN_PROGRESS",
  "createdAt": "2020-04-20T16:20:00Z",
  "lastModifiedAt": "2020-04-20T16:20:00Z",
  "currency": "USD",
  "customer": {
    "id": "123456789",
    "firstName": "Geovanni",
    "lastName": "Feil",
    "phone": "+15555556852",
    "dob": "1980-01-01",
    "hasMedicalRecommendation": false,
    "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
  },
  "seller": {
    "id": "string",
    "name": "The Grow - North Side",
    "address1": "4 Pacocha Groves",
    "address2": "Apt. 307",
    "city": "Barrett",
    "province": "NY",
    "countryCode": "US",
    "phone": "+15555556852",
    "postalCode": "10000"
  },
  "customerNote": "I'll pick it up tomorrow",
  "documents": [
    {
      "documentType": "GOVERNMENT_ISSUED_ID",
      "url": "https://example.com/photo.jpg?sig=1234abc"
    }
  ],
  "lineItems": [
    {
      "id": "123456789",
      "externalId": "abc12345",
      "wmProductId": "123456789",
      "name": "Mendo Berries Refined Live Resin™ 0.5g Cartridge",
      "weightBreakpoint": "GRAM",
      "brand": "Raw Garden™",
      "quantity": 2,
      "originalPrice": "99.99",
      "adjustedPrice": "75.99",
      "url": "https://weedmaps.com/dispensaries/awesome-dispensary/menu/golden-pineapple",
      "imageUrl": "https://images.weedmaps.com/products/000/106/848/avatar/large/1563555258-RG-vapecart-01.jpg"
    }
  ],
  "discounts": [
    {
      "appliesTo": "SUBTOTAL",
      "discountType": "PERCENTAGE",
      "value": "5",
      "amount": "4.99",
      "description": "5% off flower",
      "discountCode": "5FLOWER"
    }
  ],
  "taxes": [
    {
      "name": "City excise tax",
      "taxType": "EXCISE",
      "amount": "4.99"
    }
  ],
  "fees": [
    {
      "name": "Weedmaps Service/Tech Fee",
      "feeType": "WM_SERVICE_FEE",
      "amount": "4.99"
    }
  ],
  "fulfillmentMethod": "DELIVERY",
  "deliveryPackages": [
    {
      "serviceIdentifier": "DISPATCH",
      "id": "A8919616",
      "statusUrl": "https://dispatch.weedmaps.com/A8919616/status"
    }
  ],
  "payments": [
    {
      "paymentType": "CASH",
      "amount": "99.99"
    }
  ],
  "shippingAddress": {
    "address1": "4 Pacocha Groves",
    "address2": "Apt. 307",
    "city": "Barrett",
    "province": "WY",
    "countryCode": "US",
    "postalCode": "10000",
    "latitude": "33.666633",
    "longitude": "-117.7584978"
  },
  "source": "WEEDMAPS",
  "subtotal": "99.99",
  "feeTotal": "4.99",
  "discountTotal": "4.99",
  "taxTotal": "4.99",
  "grandTotal": "99.99"
}

Properties

Enumerated Values

OrderId

"99998888000"

The Order ID — The party that generates the order decides the value for this field.

Properties

Package

{
  "serviceIdentifier": "DISPATCH",
  "id": "A8919616",
  "statusUrl": "https://dispatch.weedmaps.com/A8919616/status"
}

📘

As of May 27, 2020, this is reserved for future use.

Properties

PaymentMethod

{
  "paymentType": "CASH",
  "amount": "99.99"
}

Properties

Enumerated Values

Seller

{
  "id": "string",
  "name": "The Grow - North Side",
  "address1": "4 Pacocha Groves",
  "address2": "Apt. 307",
  "city": "Barrett",
  "province": "NY",
  "countryCode": "US",
  "phone": "+15555556852",
  "postalCode": "10000"
}

Information about the originating seller

Properties

Enumerated Values

ShippingAddress

{
  "address1": "4 Pacocha Groves",
  "address2": "Apt. 307",
  "city": "Barrett",
  "province": "WY",
  "countryCode": "US",
  "postalCode": "10000",
  "latitude": "33.666633",
  "longitude": "-117.7584978"
}

The destination for packages from the order

Properties

Enumerated Values

Tax

{
  "name": "City excise tax",
  "taxType": "EXCISE",
  "amount": "4.99"
}

Properties

Enumerated Values