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

FIELD

DESCRIPTION

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.

FIELD

DESCRIPTION

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.

FIELD

DESCRIPTION

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:

FIELD

DESCRIPTION

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, optional

ID 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:

FIELD

DESCRIPTION

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