POST /v2/orders

Orders can be created or updated via a POST method to https://api.shipup.co/v2/orders, which accepts a JSON object describing the order. This payload also includes the order's fulfillments, line items, and trackers through nested fields.

If you use this endpoint to start sending order information, you must keep using this endpoint to send the subsequent order information as the order fulfillment and shipment progress. For example, do not use the POST /v1/trackers endpoint to add a tracker to your order. You must instead send a new order payload including the tracker using the POST /v2/orders endpoint

Orders, fulfillments, and line items not found via merchant_id will be created, and those that are found will be updated. Trackers not found via tracking_number will be created, and those that are found will be updated.

To understand how to adapt all your use cases to the Shipup data model and how to send them via API, please refer to Shipup's tutorials.

Request payload:

The below tables show which fields you can send to create or update an order

FIELDDESCRIPTION
merchant_id
string, required
Unique identifier used by the online retailer for the order
ordered_at
datetime, optional
Time at which the order was placed. This parameter is required if you want to send pre-shipment notifications for this order.
language_code
string, optional, see available values
Customer language
Defaults to your company's main language if not provided
email
string, optional
Customer's email address
phone
string, optional
Customer's mobile phone. The format will be handled by Shipup. If you have several phone numbers, you can send them all in this field, separated by a | (pipe symbol)
order_number
string, optional
Shop order reference
custom_variables
object, optional
Order custom variables
first_name
string, optional
Customer's first name
last_name
string, optional
Customer's last name
mute_notifications
boolean, optional
If set to true, no notification will be sent for this order.
Defaults to false
canceled
boolean, optional
If set to true, the order will be canceled. Defaults to false.
line_items
array of objects, optional
Order's list of unfulfilled line items. Once fulfilled, line items are placed in the order's fulfillments
See line Item payload below
shipping_address
object, optional
Recipient address.
See shipping address payload below
fulfillments
array of objects, optional
List of order's fulfillments.
See fulfillment payload below
{
  "merchant_id": "O_MER_TEST5",
  "order_number": "O_N_TEST5",
  "fulfillments": [
    {
      "merchant_id": "MY_FULFILLMENT_ID",
      "shipping_address": {
        "address1": "123 road street",
        "city": "City",
        "zip": "12345",
        "country": "Country"
      },
      "warehouse_merchant_id": "location_1",
      "trackers": [
        {
          "tracking_number": "1231121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_1",
              "description": "Product Description",
              "title": "Product name"
            }
          ]
        },
        {
          "tracking_number": "12341121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_2",
              "title": "Product name 2",
              "variant_title": "Product variant name (Blue)"
            }
          ]
        }
      ],
      "line_items": [
        {
          "merchant_id": "MY_UNSHIPPED_PRODUCT_ID"
        }
      ]
    }
  ]
}
// status
201
// ⚠️ This payload is invalid.
// Do not use it as an example

{
  "merchant_id": "O_MER_TEST5",
  "order_number": "O_N_TEST5",
  "fulfillments": [
    {
      "merchant_id": "MY_FULFILLMENT_ID",
      "shipping_address": {
        "address1": "123 road street",
        "city": "City",
        "zip": "12345",
        "country": {}
      },
      "trackers": [
        {
          "tracking_number": "1231121212",
          "line_items": [
            {
              "merchant_id": "MY_SHIPPED_PRODUCT_ID_1",
              "description": "Product Description",
              "title": "Product name"
            }
          ]
        },
        {
          "tracking_number": true,
          "line_items": [
            {
              "title": "Product name 2",
              "variant_title": "Product variant name (Blue)"
            }
          ]
        }
      ],
      "line_items": [
        {
          "merchant_id": "MY_UNSHIPPED_PRODUCT_ID",
          "canceled": "true"
        }
      ]
    }
  ]
}
// status
400

// body
{
  "errors": {
    "fulfillments": {
      "0": {
        "country": "Wrong data type: given, Hash ({}) expected: String",
        "trackers": {
          "1": {
            "tracking_number": "Wrong data type: given, TrueClass (true) expected: String or Numeric",
            "line_items": {
              "0": {
                "merchant_id": "Required"
              }
            }
          }
        },
        "line_items": {
          "0": {
            "canceled": "Wrong data type: given, String (true) expected: TrueClass or FalseClass"
          }
        }
      }
    }
  }
}

Shipping Address payload:

πŸ“˜

For convenience, the shipping address can be placed in the order payload or in the fulfillment payload. Prefer the former if all shipments will be sent to the same address. The latter is recommended if the order can be shipped to multiple addresses.

FIELDDESCRIPTION
address1
string, optional
Street address, including street number
address2
string, optional
Optional additional field for the street address
city
string, optional
City, town or village
zip
string, optional
Postal code (zip, postcode, Eircode, …)
country
string, optional
Country name. This is for presentation only and the below country_code field should be provided in priority
country_code
string, optional, 2 letter ISO code, e.g. FR or GB
Country code
state
string, optional
State name. This is for presentation only and the below state_code should be provided in priority
state_code
string, optional, 2 letter ISO code (US and CA), e.g. NY
State code (US and Canada only)
first_name
string, optional
Address first name
last_name
string, optional
Address last name
name
string, optional
Address full name
company_title
string, optional
Name of the company (for business addresses)

Line item payload:

πŸ“˜

Line items can be placed in the order, fulfillment, or tracker payloads: In the order until they are fulfilled, in the fulfillment until they are assigned to a tracker, in which case they're finally placed in the tracker.

FIELDDESCRIPTION
merchant_id
string, required
Unique identifier used by the online retailer for this line_item
title
string, optional
Product title
variant_title
string, optional
Variant title
name
string, optional
Full name of the product
description
string, optional
Product description
quantity
integer, optional
Product quantity of the line item in the fulfillment. This field must not change. If part of the quantity of the line item is canceled, please use canceled_quantity field.
requires_shipping
boolean, optional
If false, no notification will be sent for this product. Defaults to true
shipped_quantity
integer, optional
(This field is only available in line_items that are nested inside a tracker)
Product quantity of the line item within a tracker, in case not all of its fulfilled quantity can fit in a single package. This field must be smaller than or equal to quantity. (See use case)
sku
string, optional
Stock Keeping Unit of the product
thumbnail
object, optional
An object formed of the src, width and height keys. Dimensions are in px
{ "src": "https://*.jpg", "width": "400", "height": "400" }
canceled
boolean, optional
Whether or not the item is canceled from the order
canceled_quantity
integer, optional
If the line item is only partly canceled, this field will indicate which quantity is canceled. The quantity field must remain unchanged. If the canceled quantity evolves, this field must change. If the canceled_quantity is greater than or equal to the quantity, the canceled field will be forced to true. (See use case)

Fulfillment Payload:

FIELDDESCRIPTION
merchant_id
string, required
ID used by the shop for the fulfillment
fulfillment_number
string, optional
Shop reference of the fulfillment. For instance, this can be the order number suffixed by an underscore and the fulfillment count (ABCD_1)
estimated_delivery_range_start
datetime, optional
Estimated delivery date for the fulfillment. If estimated_delivery_range_end is also provided, a range will be displayed. Otherwise, estimated_delivery_range_start will be displayed alone
estimated_delivery_range_end
datetime, optional
End of estimated delivery date range
custom_variables
object, optional
Custom variables for the fulfillment
status_code
string, optional, see available values
Fulfillment status. This field is required if you want to send pre-shipment notifications. Each status_code is associated with a pre-shipment notification
warehouse_merchant_id string, optionalID of the warehouse (or equivalent) for this fulfillment. When not provided, we will associate the fulfillment to the company's default warehouse.
shipping_address
object, optional
An address is a physical address.
See address payload above
line_items
array of objects, optional
Fulfilled line items (not shipped yet). Before fulfillment, line items are placed in the order object. Once shipped, they are placed in the tracker object.
See line Item payload above
trackers
array of objects, optional
Trackers related to this fulfillment
See tracker payload below

Tracker payload:

FIELDDESCRIPTION
carrier_code
string, optional
Code uniquely identifying a shipping carrier. See available values
carrier_service_code
string, optional
Code uniquely identifying a shipping carrier's service. See available values
custom_variables
object, optional
Object containing custom variables. Those variables can be reused to customize or add logic in the notifications
expected_delivery_at
datetime, optional
Expected delivery time for the package

If provided, this date will be used as the merchant expected delivery. Read more in the tracker object's displayable_expected_delivery_date field description
line_items
array of objects, optional
Line item shipped in this tracker.
See line Item payload above
mute_notifications
boolean, optional
If set to true, no notification will be generated for this tracker.
Defaults to false
tracking_number
string, required
Package tracking number
untracked_carrier_name
string, optional
Carrier name to be displayed as a fallback if Shipup can't find a matching carrier
untracked_carrier_url
string, optional
Carrier tracking URL to be displayed as a fallback if Shipup can't find a matching carrier