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

NameTypeRequiredRestrictionsDescription
idstringfalsenonenone
firstNamestringtruenonenone
lastNamestringtruenonenone
phonestring¦nullfalsenonenone
dobstring(date)truenoneYYYY-MM-DD
hasMedicalRecommendationbooleanfalsenonenone
medicalRecommendationMedicalRecommendationfalsenonenone

MedicalRecommendation

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

Properties

NameTypeRequiredRestrictionsDescription
idstringfalsenonenone
expiresstring(date)¦nullfalsenonenone
caregiverIdstringfalsenonenone
provincestringfalsenonenone

CustomerId

"WM123456"

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

Properties

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenoneThe 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

NameTypeRequiredRestrictionsDescription
appliesTostringtruenoneWhat part of the order the discount applies to.
discountTypestringfalsenonenone
valuestring(decimal)falsenoneThe discount value, either monetary amount or percentage. For example, 5% would be "5". $2.00 would be "2.00".
amountstring(decimal)falsenoneThe total amount of discount applied
descriptionstringfalsenonenone
discountCodestringfalsenonenone

Enumerated Values

PropertyValue
appliesToDELIVERY_FEE
appliesToWM_SERVICE_FEE
appliesToSUBTOTAL
discountTypeFIXED_AMOUNT
discountTypePERCENTAGE

Document

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

Properties

NameTypeRequiredRestrictionsDescription
documentTypestringfalsenonenone
urlstring(uri)falsenonenone

Enumerated Values

PropertyValue
documentTypeMEDICAL_RECOMMENDATION
documentTypeGOVERNMENT_ISSUED_ID

Fee

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

Properties

NameTypeRequiredRestrictionsDescription
namestringfalsenonenone
feeTypestringfalsenoneFee type. Delivery fee will be DELIVERY_FEE.
amountstring(decimal)falsenonenone

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

NameTypeRequiredRestrictionsDescription
idstringfalsenonenone
externalIdstringtruenoneProduct external identifier as provided by POS
wmProductIdstringfalsenoneWeedmaps Product ID

Initially, this represents a product with multiple breakpoints, but it
will eventually represent a single breakpoint.
namestringtruenonenone
weightBreakpoint*stringtruenoneProduct weight breakpoint (such as 1/8th, unit, and so on)
brandstringfalsenonenone
quantityintegertruenonequantity of units for this line item. If set to zero, the line item is rendered as unavailable
originalPricestring(decimal)falsenoneItem original price (gross)
adjustedPricestring(decimal)truenonePrice 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.
urlstringfalsenonenone
imageUrlstringfalsenonenone
unitOfMeasureUnitOfMeasurefalsenoneThe 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

PropertyValue
weightBreakpointUNIT
weightBreakpointHALF_GRAM
weightBreakpointGRAM
weightBreakpointTWO_GRAM
weightBreakpointEIGHTH_OUNCE
weightBreakpointQUARTER_OUNCE
weightBreakpointHALF_OUNCE
weightBreakpointOUNCE
weightBreakpointCUSTOM

UnitOfMeasure

{
  "unitOfMeasure": {
    "unit": "GRAM",
    "value": "1"
  }
}

Properties

NameTypeRequiredRestrictionsDescription
unitstringtruenoneUnits for the unit of measure of the product
valueintegertruenoneNumber of the units above in the unit of measure

MerchantId

"12345678"

Weedmaps identifier representing the merchant

Properties

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenoneWeedmaps 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

NameTypeRequiredRestrictionsDescription
orderIdOrderIdfalsenoneThe Order ID. The party that generates the order decides the value for this field.
versionstring(date)truenoneVersion release date
statusstringtruenoneCurrent status for the order - READY_FOR_ATTAINMENT should be used when the order is ready for pickup or to send out for delivery.
createdAtstring(date-time)falsenonenone
lastModifiedAtstring(date-time)falsenonenone
currencystringfalsenonenone
customerCustomertrueRequired for Order updates but not required during a Draft responseCustomer information
sellerSellerfalsenoneInformation about the originating seller
customerNotestringfalsenoneFree-form field for Customer to communicate to the Vendor
documents[Document]falsenoneDocuments supporting the order
lineItems[LineItem]truenoneA non empty array of line items
discounts[Discount]falsenoneArray of order level discounts
taxes[Tax]truenoneArray of taxes applied to the order. An empty array is acceptable
fees[Fee]truenoneArray of fees applied to the order. An empty array is acceptable
fulfillmentMethodstringfalsenoneThe customer selected attainment option
deliveryPackages[Package]falsenoneArray of packages encapsulating individual delivery tasks. Orders may be satisfied through multiple delivery tasks.
payments[PaymentMethod]falsenonenone
requestedSchedulingInfoSchedule InformationfalsenoneIf 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.
shippingAddressShippingAddressfalsenoneThe destination for packages from the order
sourcestringtruenonenone
subtotalstring(decimal)truenonenone
feeTotalstring(decimal)truenonenone
discountTotalstring(decimal)truenonenone
taxTotalstring(decimal)truenonenone
grandTotalstring(decimal)truenonenone

Enumerated Values

PropertyValue
statusDRAFT
statusPENDING
statusIN_PROGRESS
statusREADY_FOR_ATTAINMENT
statusCOMPLETE
statusCANCELED_CUSTOMER
statusCANCELED_SELLER
currencyUSD
currencyCAD
fulfillmentMethodPICKUP
fulfillmentMethodDELIVERY
sourceWEEDMAPS

OrderId

"99998888000"

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

Properties

NameTypeRequiredRestrictionsDescription
anonymousstringfalsenoneThe 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

NameTypeRequiredRestrictionsDescription
serviceIdentifierstringfalsenoneCustom identifier for the delivery service utilized, set by the POS
idstringfalsenoneIdentifier for the package/tasks record in the delivery service utilized
statusUrlstringfalsenoneFully 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

NameTypeRequiredRestrictionsDescription
paymentTypestringfalsenonenone
amountstring(decimal)falsenonenone
processorstringfalsenonenone
transactionIdstringfalsenonenone

Enumerated Values

PropertyValue
paymentTypeCASH
paymentTypeCREDIT
paymentTypeDEBIT
processorMERRCO

Schedule Information

requestedSchedulingInfo: {
  "windowStartAt": "2020-04-29T4:20:00Z",
  "windowEndAt": "2020-04-29T6:20:00Z"
}

Properties

NameTypeRequiredRestrictionsDescription
windowStartAtUTC DateTime in ISO 8601 formattruenoneThis date time represents the start of the time window the user selected for their order, required if the 'requestedSchedulingInfo' field is non null
windowEndAtUTC DateTime in ISO 8601 formattruenoneThis 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

NameTypeRequiredRestrictionsDescription
idstringfalsenoneIf this originates from WM, it will be the Listing ID
namestringfalsenoneThe listing name
address1stringfalsenonenone
address2string¦nullfalsenonenone
citystringfalsenonenone
provincestringfalsenoneTwo-letter state or province code
countryCodestringfalsenonenone
phonestringfalsenonenone
postalCodestringfalsenonenone

Enumerated Values

PropertyValue
countryCodeUS
countryCodeCA

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

NameTypeRequiredRestrictionsDescription
address1stringfalsenonenone
address2stringfalsenonenone
citystringfalsenonenone
provincestringfalsenoneTwo-letter state or province code
countystringfalsenoneName of the county or similar regional locality
countryCodestringfalsenonenone
postalCodestringfalsenonenone
latitudestringfalsenonenone
longitudestringfalsenonenone

Enumerated Values

PropertyValue
countryCodeUS
countryCodeCA

Tax

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

Properties

NameTypeRequiredRestrictionsDescription
namestringfalsenonenone
taxTypestringfalsenonenone
amountstring(decimal)falsenonenone

Enumerated Values

PropertyValue
taxTypeEXCISE
taxTypeSALES