Sales Orders Quickstart

To start out, let's go through a simple tutorial of how a process might work. We will be creating an order in Shopify, importing the order into ShipEngine, creating a label for the order, and finally notifying Shopify that our items have been shipped.

Create an Order in Shopify

info Click the button below to create a fake order inside Shopify. This button will randomize a fake order with a demo Shopify account. The generated ID will be the external_order_id once you import your Shopify sales order

Shopify Order ID: (Click the "Create a Shopify Order" button)

Refresh the Order Source

By refreshing the order source, you will trigger ShipEngine to import the order you just created!

PUT /v-beta/order_sources/__YOUR_ORDER_SOURCE_ID_HERE__/refresh HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Query Sales Orders to Find the Order

Look for the external_order_id for your Shopify order you created earlier. We're going to sort the sales orders descending by order date, since we have just created the order. If the order isn't found in the results, simply query the next page, or increase your page size.

Sort Request Example

GET /v-beta/sales_orders?order_source_id=__YOUR_ORDER_SOURCE_ID_HERE__&sort_dir=desc&sort_by=order_date&page=1&page_size=1 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

We can also query the external_order_id directly.

External Order ID Request Example

GET /v-beta/sales_orders?external_order_id=1011295486011 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Create a Label with the Sales Order

You will need your sales_order_id from the request above to create a label from a sales order.

POST /v-beta/labels/sales_order/:sales_order_id HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "label_format": "pdf",
  "shipment": {
    "carrier_id": "se-123890",
    "service_code": "usps_priority_mail",
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "package_code": "package",
        "weight": {
          "value": 2,
          "unit": "pound"
        }
      }
    ]
  }
}

Notify the Order Source the Item has Shipped

Next, let's tell Shopify that we have shipped the sales order.

POST /v-beta/sales_orders/:sales_order_id/notify_shipped HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "tracking_number": "9374869901600064074368",
  "carrier_code": "usps",
  "sales_order_items": [
    {
      "sales_order_item_id": ":sales_order_item_id",
      "quantity": 1
    }
  ]
}

You should receive an HTTP Status 204 No Content with a successful submission. After that, you can Refresh your order source to update the sales order's status.