Orders

With the API, you can retrieve and manage your brand’s orders. On LeafLink’s marketplace, orders can be placed by the client’s buyers (buyer-generated), or by the client themselves (seller-generated).

The following two methods are recommended for managing your order syncing process between LeafLink and your external system.

  1. Take advantage of webhook functionality. By using webhooks, you can listen for events on the orders that are being added or changed in LeafLink.
    • Webhooks will trigger in real-time when the order is placed or modified, eliminating the need to periodically check for changes.
  2. An alternative to using webhooks is to poll the /orders-received/ API endpoint periodically using the modified date filter parameter (modified__gte, for example).

For every order synced to or from your external system, an external_id key value pair should be updated in LeafLink to signify the order has successfully synced.

  • Associate a unique external_id from the external system to an order that is created/updated.
  • Using an external_id helps reduce the opportunity for overwriting data that should be treated separately.

The following sections describe popular use cases. For a full overview of order functionality please visit the API reference.

Please click here to review the best practices for the orders endpoint.

Transition an order

To transition an individual order from one state to another, send a POST request to /orders-received/{number}/transtion/{action}/, where {number} is the number for the orders and {action} is transition action.

The following request transitions order 593aaf1b-2768-4208-a6d2-a3d446a77ae0 from Accepted to Fulfilled.

POST /api/v2/orders-received/593aaf1b-2768-4208-a6d2-a3d446a77ae0/transition/fulfill/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json

Please keep in mind the impact of an order’s status on inventory. You can click here to get more information on the order status & the effects on inventory.

Order Statuses

  • Submitted - The buyer placed an order via LeafLink. Alternatively, someone from your team created an order on the buyer's behalf.
  • Accepted - You have accepted an organic or a manual order and are prepping to fulfill it.
  • Fulfilled - The order has been picked, packed, and staged for delivery.
  • Shipped - The product has been sent out for delivery and is no longer in your facility.
  • Complete - The retailer has received the order.
  • Rejected - You have chosen to cancel the order.
  • Backorder - The items in this order were on backorder at the time of purchase and will be accepted once they are back in stock.
  • Canceled - The retailer has chosen to cancel their order.

Create an Order

The ability to create orders via the Create Order endpoint is now available via LeafLink’s APIs:

  • The order object includes the ability to create orders via a POST request, allowing orders to be created in LeafLink from an external system.
  • Now sellers can use their system’s order creation process & sync orders into their LeafLink account, eliminating double entry & multiple login processes.

Please note, the API is a beta feature and is in active development & subject to change.

To create orders, define the seller, customer, status, and line_items field in your POST request to the /orders-received/ endpoint. Please reference the code examples in our API Reference.

/**
POST /api/v2/orders-received/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
*/

{
  "seller": 4335,
  "discount_amount": 0,
  "line_items": [
      {
        "ordered_unit_price": {
           "amount": 400.00,
           "currency": "USD"
       },
        "quantity": "5.0000",
        "sale_price": {
           "amount": 400,
           "currency": "USD"
       },
        "product": 21557
    }
  ],
  "customer": {
   "id": 268676
  }
}

Note: The above code example is for illustrating the required fields only. There are additional fields included in the api reference that would be present in a full create order POST request.

Note: The product & customer fields need to be active records in the environment that you are testing in.

List orders

To list orders, send a GET request to the /orders-received/ endpoint.

You can include various query parameters to filter or modify the records you receive in the response.

For example, to list orders in the Submitted state and to include line item details, you can add the status and include_children query parameters to the request. The following request returns only Submitted orders and appends line item details.

GET /api/v2/orders-received/?status=Submitted&include_children=line_items
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json

Visit the /orders-received/ endpoint reference for a full list of supported parameters.

Integration Tip

Price fields in the /line-items/ response:

  • The ordered_unit_price field is the standard price of the product at its sold-in unit. This means this price will be per case if sold in multiples (unit_multiplier > 1). This is the price that appears in the UI on the order screen.
  • The sales_price field is the discounted price of the product at its sold-in unit if the product is on sale. We recommend using this price for the product if the sale price is greater than 0.00. This is shown in red on the order screen with the original (ordered_unit_price) crossed out.
  • The wholesale_price field is the standard price of the product at its sold-in unit. This price is not order-specific and is more of a product attribute than an order attribute.

Frozen data:

You may see discrepancies between the line item data and the frozen_data because the line item data returned is the real-time pricing and product information associated with the order, while the frozen_data array is a snapshot of the product data associated with the inventory item at the time the order was created. If you change the line item price or quantity, the line item data will change, but the frozen_data will remain constant.

CA excise tax:

The State of California requires cannabis wholesalers to collect and remit excise tax. We recommend consulting the CDTFA for full details on the tax and how it applies to your business. By default, all LeafLink orders in California will have an excise tax calculated and added to the order total. California excise tax is calculated after all discounts are subtracted and shipping costs are added. LeafLink defaults to a 27% Excise Tax.

Retrieve an order

To retrieve an individual order, send a GET request to /orders-received/{number}/, where {number} is the number for the order you wish to retrieve

The following request returns the order with number 593aaf1b-2768-4208-a6d2-a3d446a77ae0.

GET /api/v2/orders-received/593aaf1b-2768-4208-a6d2-a3d446a77ae0/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json

Update an order

To update an order, send a PATCH request to /orders-received/{number}/, where {number} is the number for the order you wish to update

The following request adds a new line item to the order with number 593aaf1b-2768-4208-a6d2-a3d446a77ae0. When adding a new line item, include at least the following required fields: ordered_unit_price, quantity, and product.

/**
PATCH /api/v2/orders-received/593aaf1b-2768-4208-a6d2-a3d446a77ae0/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
*/

{
 "line_items": [
  {
   "ordered_unit_price": {
    "amount": 250.0,
    "currency": "USD"
   },
   "quantity": "15.0000",
   "product": 129768,
   "sale_price": {
    "amount": 200.0,
    "currency": "USD"
   }
  }
 ]
}

When you exclude the line item ID, our API will assume the product should be added as a new line item. In order to remove line items, you will need to delete them individually using the process explained here.

Integration Tip

Inventory will be impacted via the API in the same manner as with the UI. Meaning, if you add a product to an order in the Submitted or Accepted statuses, it will reserve inventory in LeafLink, and then consume it, once moved to Fulfilled. If you add a product to an order at any status after Accepted, inventory will not be reserved or consumed in LeafLink.

Last Updated: