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. |
| 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 |