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>",
"unitOfMeasure": {
"unit": <string>,
"value": <string>
}
},
{
"id": "<string>",
"externalId": "<string>",
"wmProductId": "<string>",
"name": "<string>",
"weightBreakpoint": "<string>",
"brand": "<string>",
"quantity": "<integer>",
"originalPrice": "<decimal>",
"adjustedPrice": "<decimal>",
"url": "<string>",
"imageUrl": "<string>",
"unitOfMeasure": {
"unit": <string>,
"value": <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>",
"processor": "<string>",
"transactionId": "<string>",
"success": "<boolean>"
},
{
"paymentType": "<string>",
"amount": "<decimal>",
"processor": "<string>",
"transactionId": "<string>",
"success": "<boolean>"
}
],
"requestedSchedulingInfo": {
"windowStartAt": "<UTC DateTime in ISO 8601 format>",
"windowEndAt": "<UTC DateTime in ISO 8601 format>"
},
"shippingAddress": {
"address1": "<string>",
"address2": "<string>",
"city": "<string>",
"province": "<string>",
"county": "<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
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | false | none | none |
firstName | string | true | none | none |
lastName | string | true | none | none |
phone | string¦null | false | none | none |
dob | string(date) | true | none | YYYY-MM-DD |
hasMedicalRecommendation | boolean | false | none | none |
medicalRecommendation | MedicalRecommendation | false | none | none |
MedicalRecommendation
{
"id": "123456789",
"expires": "2025-01-01",
"caregiverId": "12345",
"province": "CA"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | false | none | none |
expires | string(date)¦null | false | none | none |
caregiverId | string | false | none | none |
province | string | false | none | none |
CustomerId
"WM123456"
The Order's Customer ID — This value is provided by the party that created the order.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | The Order's Customer ID. This value is provided by the party that created the order. |
Discount
{
"appliesTo": "SUBTOTAL",
"discountType": "PERCENTAGE",
"value": "5",
"amount": "4.99",
"description": "5% off flower",
"discountCode": "5FLOWER"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
appliesTo | string | true | none | What part of the order the discount applies to. |
discountType | string | false | none | none |
value | string(decimal) | false | none | The discount value, either monetary amount or percentage. For example, 5% would be "5". $2.00 would be "2.00". |
amount | string(decimal) | false | none | The total amount of discount applied |
description | string | false | none | none |
discountCode | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
appliesTo | DELIVERY_FEE |
appliesTo | WM_SERVICE_FEE |
appliesTo | SUBTOTAL |
discountType | FIXED_AMOUNT |
discountType | PERCENTAGE |
Document
{
"documentType": "GOVERNMENT_ISSUED_ID",
"url": "https://example.com/photo.jpg?sig=1234abc"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
documentType | string | false | none | none |
url | string(uri) | false | none | none |
Enumerated Values
Property | Value |
---|---|
documentType | MEDICAL_RECOMMENDATION |
documentType | GOVERNMENT_ISSUED_ID |
Fee
{
"name": "Weedmaps Service/Tech Fee",
"feeType": "WM_SERVICE_FEE",
"amount": "4.99"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | none |
feeType | string | false | none | Fee type. Delivery fee will be DELIVERY_FEE. |
amount | string(decimal) | false | none | none |
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",
"unitOfMeasure": {
"unit": "GRAM",
"value": "1"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | false | none | none |
externalId | string | true | none | Product external identifier as provided by POS |
wmProductId | string | false | none | Weedmaps Product ID Initially, this represents a product with multiple breakpoints, but it will eventually represent a single breakpoint. |
name | string | true | none | none |
weightBreakpoint* | string | true | none | Product weight breakpoint (such as 1/8th, unit, and so on) |
brand | string | false | none | none |
quantity | integer | true | none | quantity of units for this line item. If set to zero, the line item is rendered as unavailable |
originalPrice | string(decimal) | false | none | Item original price (gross) |
adjustedPrice | string(decimal) | true | none | Price after adjustments. Supersedes originalPrice if both have non-null values. This is the value rendered to the customer as the amount they will pay for this line item per single unit quantity. |
url | string | false | none | none |
imageUrl | string | false | none | none |
unitOfMeasure | UnitOfMeasure | false | none | The unit of measure for the line item |
*deprecation note: unitOfMeasure will be replacing weightBreakpoint in the future. For now, when wightBreakpoint has a value of CUSTOM unitOfMeasure should be populated.
Enumerated Values
Property | Value |
---|---|
weightBreakpoint | UNIT |
weightBreakpoint | HALF_GRAM |
weightBreakpoint | GRAM |
weightBreakpoint | TWO_GRAM |
weightBreakpoint | EIGHTH_OUNCE |
weightBreakpoint | QUARTER_OUNCE |
weightBreakpoint | HALF_OUNCE |
weightBreakpoint | OUNCE |
weightBreakpoint | CUSTOM |
UnitOfMeasure
{
"unitOfMeasure": {
"unit": "GRAM",
"value": "1"
}
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
unit | string | true | none | Units for the unit of measure of the product |
value | integer | true | none | Number of the units above in the unit of measure |
MerchantId
"12345678"
Weedmaps identifier representing the merchant
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | Weedmaps identifier representing the merchant |
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",
"unitOfMeasure": {
"unit": "GRAM",
"value": "1"
}
}
],
"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": "CREDIT",
"amount": "99.99",
"processor": "MERRCO",
"transactionId": "abc123-456def",
"success": true
}
],
"requestedSchedulingInfo": {
"windowStartAt": "<UTC DateTime in ISO 8601 format>",
"windowEndAt": "<UTC DateTime in ISO 8601 format>"
},
"shippingAddress": {
"address1": "4 Pacocha Groves",
"address2": "Apt. 307",
"city": "Barrett",
"province": "WY",
"county": "Carbon",
"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
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
orderId | OrderId | false | none | The Order ID. The party that generates the order decides the value for this field. |
version | string(date) | true | none | Version release date |
status | string | true | none | Current status for the order - READY_FOR_ATTAINMENT should be used when the order is ready for pickup or to send out for delivery. |
createdAt | string(date-time) | false | none | none |
lastModifiedAt | string(date-time) | false | none | none |
currency | string | false | none | none |
customer | Customer | true | Required for Order updates but not required during a Draft response | Customer information |
seller | Seller | false | none | Information about the originating seller |
customerNote | string | false | none | Free-form field for Customer to communicate to the Vendor |
documents | [Document] | false | none | Documents supporting the order |
lineItems | [LineItem] | true | none | A non empty array of line items |
discounts | [Discount] | false | none | Array of order level discounts |
taxes | [Tax] | true | none | Array of taxes applied to the order. An empty array is acceptable |
fees | [Fee] | true | none | Array of fees applied to the order. An empty array is acceptable |
fulfillmentMethod | string | false | none | The customer selected attainment option |
deliveryPackages | [Package] | false | none | Array of packages encapsulating individual delivery tasks. Orders may be satisfied through multiple delivery tasks. |
payments | [PaymentMethod] | false | none | none |
requestedSchedulingInfo | Schedule Information | false | none | If the user selected a scheduled window then this object will be non-null. If there is no selected scheduled window then this will be null. |
shippingAddress | ShippingAddress | false | none | The destination for packages from the order |
source | string | true | none | none |
subtotal | string(decimal) | true | none | none |
feeTotal | string(decimal) | true | none | none |
discountTotal | string(decimal) | true | none | none |
taxTotal | string(decimal) | true | none | none |
grandTotal | string(decimal) | true | none | none |
Enumerated Values
Property | Value |
---|---|
status | DRAFT |
status | PENDING |
status | IN_PROGRESS |
status | READY_FOR_ATTAINMENT |
status | COMPLETE |
status | CANCELED_CUSTOMER |
status | CANCELED_SELLER |
currency | USD |
currency | CAD |
fulfillmentMethod | PICKUP |
fulfillmentMethod | DELIVERY |
source | WEEDMAPS |
OrderId
"99998888000"
The Order ID — The party that generates the order decides the value for this field.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
anonymous | string | false | none | The Order ID. The party that generates the order decides the value for this field. |
Package
{
"serviceIdentifier": "DISPATCH",
"id": "A8919616",
"statusUrl": "https://dispatch.weedmaps.com/A8919616/status"
}
As of May 27, 2020, this is reserved for future use.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
serviceIdentifier | string | false | none | Custom identifier for the delivery service utilized, set by the POS |
id | string | false | none | Identifier for the package/tasks record in the delivery service utilized |
statusUrl | string | false | none | Fully formed URL intended to be presented to the customer/patient to view a more detailed status of their delivery |
PaymentMethod
{
"paymentType": "CREDIT",
"amount": "99.99",
"processor": "MERRCO",
"transactionId": "abc123-456def"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
paymentType | string | false | none | none |
amount | string(decimal) | false | none | none |
processor | string | false | none | none |
transactionId | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
paymentType | CASH |
paymentType | CREDIT |
paymentType | DEBIT |
processor | MERRCO |
Schedule Information
requestedSchedulingInfo: {
"windowStartAt": "2020-04-29T4:20:00Z",
"windowEndAt": "2020-04-29T6:20:00Z"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
windowStartAt | UTC DateTime in ISO 8601 format | true | none | This date time represents the start of the time window the user selected for their order, required if the 'requestedSchedulingInfo' field is non null |
windowEndAt | UTC DateTime in ISO 8601 format | true | none | This date time represents the end of the time window the user selected for their order, required if the 'requestedSchedulingInfo' field is non null |
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
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | false | none | If this originates from WM, it will be the Listing ID |
name | string | false | none | The listing name |
address1 | string | false | none | none |
address2 | string¦null | false | none | none |
city | string | false | none | none |
province | string | false | none | Two-letter state or province code |
countryCode | string | false | none | none |
phone | string | false | none | none |
postalCode | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
countryCode | US |
countryCode | CA |
ShippingAddress
{
"address1": "4 Pacocha Groves",
"address2": "Apt. 307",
"city": "Barrett",
"province": "WY",
"county": "Carbon",
"countryCode": "US",
"postalCode": "10000",
"latitude": "33.666633",
"longitude": "-117.7584978"
}
The destination for packages from the order
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
address1 | string | false | none | none |
address2 | string | false | none | none |
city | string | false | none | none |
province | string | false | none | Two-letter state or province code |
county | string | false | none | Name of the county or similar regional locality |
countryCode | string | false | none | none |
postalCode | string | false | none | none |
latitude | string | false | none | none |
longitude | string | false | none | none |
Enumerated Values
Property | Value |
---|---|
countryCode | US |
countryCode | CA |
Tax
{
"name": "City excise tax",
"taxType": "EXCISE",
"amount": "4.99"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | none |
taxType | string | false | none | none |
amount | string(decimal) | false | none | none |
Enumerated Values
Property | Value |
---|---|
taxType | EXCISE |
taxType | SALES |
Updated 11 months ago