Migrate to Orders (Modern) from Orders (v2/Legacy)

Overview

This guide walks through the benefits, key differences, and upgrade path to Shipwell's modern Orders API framework from Orders (v2/Legacy).

• Shipwell Orders is the modern Orders API framework where Shipwell adds new order-related capabilities and enhancements.
• Shipwell maintains the Orders (v2/Legacy) framework for existing customers that utilize this legacy framework, however new capabilities and functionality will only be added to the modern Shipwell Orders API .
  • If you are a new Shipwell customer then you are already on the new modern Shipwell Orders API (unless you need to use a NetSuite App then Orders (v2/Legacy) is recommended).

Benefits of Migration

Shipwell's modern Orders API introduces significant new capabilities and improvements over the Orders (v2/Legacy) system including:

• Multi-Leg Shipments
  • Orders may now span multiple shipments
  • For example, the ability to aggregate and disaggregate multi-leg shipments for an order to optimize shipping costs (i.e. centralized warehouses, distribution centers, order/shipment pooling points that work with Shipwell's Load Optimization)
• Increased Data Efficiency
  • Save time and reduce manual data entry by automating data exchange to and/or from your ERP. This includes populating and supporting:
    • Mixed pallet handling units
    • Bill-to information
    • Order tags and documents
    • Flexible full or partial order fulfillment with a collaborative customer and supplier release workflow for Supplier Portal users.
• Various Order Types
  • Supports different order types such as purchase orders , sales orders , etc.
• Future Automation & Data Enhancements
  • Cost allocation options (i.e. cost allocation per pallet, box, etc.)
  • Additional order types and order-to-shipment automations will continue to be added

Leverage new platform functionality like Shipwell Dock Scheduling and Supplier Portal which requires using the new modern Orders as their functionality is not compatible with Orders (v2/Legacy).

Key Updates

The following highlights key updates to order object, endpoints, and events/webhook payloads.

Order Object Key New Fields/Properties

New and Required Fields/Properties

These new and required fields/properties are required.

Order Number

order_number must be unique across all orders in your account in the modern Orders API

"order_number": "abc123-1"

Order Item Amount

• Order item amount represents the individual unit of your product (e.g. a single flower). See order items property details . The order item amount includes a value (e.g. 5) and unit details (e.g. bags, pieces, cases, pallets).
  • Example: If you are shipping flowers you can use this to represent the individual flower units instead while a number of flowers would then go in a piece (e.g. case) and then a number of cases would go on a package (e.g. pallet).
• This field is NOT present on Shipwell's current shipment object which means that it does not transfer onto shipments when a shipment is created from an order.
  • For customers not concerned about representing this granularity then they may choose to leverage it in a manner similar to a piece type or a packaging type. If using the data in this manner, this information needs to be duplicated in the respective Piece Type or Packaging Type field to have this data transferred onto shipments.
  • For customers leveraging Supplier Portal , this field may also be used to represent a third layer of handling unit information that is useful when creating shipments or releases from an order. Contact your customer service representative to learn more about Supplier Portal .

// "items": [
      "amount": { // An order line item may have an amount with a unit and value (i.e. 5 BAGS, 10 PALLETS, etc.)
          "unit": "BAG",
          "value": "5" // 
      }
// ]

New and Optional Fields/Properties

These new and optional fields or properties are highly useful, but optional.

Order Bill-To

Specify the bill-to party for freight payments by populating an order's order.shippingrequirements.billto property via the create order or update order API endpoints.

Order Combined Handling Unit Info

Customers that have and want to designate mixed handling units (i.e. handling units that have multiple line items or even multiple orders) can submit this information within line items (order.items[].shipping_requirements.handling_unit_id and order.items[].shipping_requirements.combined_handling_unit_info when creating or updating orders. This will save your users time from having to manually create mixed handling units within Shipwell.

Learn how to specify mixed handling units on order create here and when updating an order here.

Order Tags

Tags are a way to annotate orders with shared references (i.e. "cold-storage", "west-coast", "priority") so orders may be looked up by these tags via API or in the Shipwell UI. Associate tags to orders do via the create order or update order API endpoints by specifying the tags in the order payload. These tags have special filters on the order dashboard to allow users to find orders by tag. Order tags will also be used in order optimization and other areas of Shipwell in the future. Tags may be created or updated before adding them to an order if the tag did not previously exist by using the create tag or update tag] API endpoints.

"tags": [
  {
      "id": "01HZ04BZBKT2A65H2M5VVNBBN7",
      "name": "First Tag",
      "slug": "first-tag",
      "color": "#006BA2"
  },
  {
      "id": "01J9ETRC8DDYGP5WSB6M9HP16Z",
      "name": "Example Tag",
      "slug": "example-tag",
      "color": "#77F94D"
  }
]

Order API Endpoints

The API endpoints for interacting with orders need to be migrated. You will need to update your API integrations to use the order API endpoints and payloads for the modern Orders API framework.

Events and Webhook Payloads

The following events and webhook payloads need to be migrated if they are utilized by your API integrations and/or webhook endpoints. For webhooks, you will need to subscribe to the new event types emitted/triggered by the modern Orders API framework and for event polling, you will need to retrieve events with a different name. The event names and fields/property for each event or webhook payload for that event type have been updated.

Migration Tips

Address Book Usage

Utilize the Address Book as much as possible for address and contact reuse across the platform. Existing addresses that you have stored in the address book may be referenced in the modern Orders API. Similar to Orders (v2/Legacy), it is important to leverage the Address Book in the modern Orders API for your pickup (ship_from) and delivery (ship_to) addresses because if you do not when an order is translated into a shipment then there will be manual required fields that your users will need to continuously fill out like address contact and location type.

Product Catalog Usage

Products may be referenced from your Product Catalog, but the data/details of the product are not currently transferred (this is planned to be supported in the future). You will need to query/reference the existing product details and reuse them when mapping item or product descriptions, etc.