Sign in

v1

latestOpenAPI 3.1.02026-07-1270243932.3 KB
Orders

Create a new order

Creates a new order object.

post/orders

Headers

SHIPPO-API-VERSIONstring
Example:2018-02-08

Optional string used to pick a non-default API version to use. See our <a href="https://docs.goshippo.com/docs/api_concepts/apiversioning/">API version</a> guide.

Request body

currencystring

Required if total_price is provided<br> Currency of the <code>total_price</code> and <code>total_tax</code> amounts.

notesstring

Custom buyer- or seller-provided notes about the order.

order_numberstring

An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.

order_status'UNKNOWN' | 'AWAITPAY' | 'PAID' | 'REFUNDED' | 'CANCELLED' | 'PARTIALLY_FULFILLED' | 'SHIPPED'

Current state of the order. See the <a href="https://docs.goshippo.com/docs/orders/orders/">orders tutorial</a> for the logic of how the status is handled.

placed_atstring required

Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.

shipping_coststring

Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.

shipping_cost_currencystring

Required if shipping_cost is provided<br> Currency of the <code>shipping_cost</code> amount.

shipping_methodstring

Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.

subtotal_pricestring
total_pricestring

Total amount paid by the buyer for this order.

total_taxstring

Total tax amount paid by the buyer for this order.

weightstring

Total weight of the order.

weight_unit'g' | 'kg' | 'lb' | 'oz'

The unit used for weight.

Example request

{
  "currency": "USD",
  "notes": "This customer is a VIP",
  "order_number": "#1068",
  "order_status": "PAID",
  "placed_at": "2016-09-23T01:28:12Z",
  "shipping_cost": "12.83",
  "shipping_cost_currency": "USD",
  "shipping_method": "USPS First Class Package",
  "subtotal_price": "12.1",
  "total_price": "24.93",
  "total_tax": "0.0",
  "weight": "0.4",
  "weight_unit": "lb",
  "from_address": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "validate": true
  },
  "to_address": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "validate": true
  },
  "line_items": [
    {
      "currency": "USD",
      "manufacture_country": "US",
      "max_delivery_time": "2016-07-23T00:00:00Z",
      "max_ship_time": "2016-07-23T00:00:00Z",
      "quantity": 20,
      "sku": "HM-123",
      "title": "Hippo Magazines",
      "total_price": "12.1",
      "variant_title": "June Edition",
      "weight": "0.4",
      "weight_unit": "lb"
    }
  ]
}

Response

Order

currencystring

Required if total_price is provided<br> Currency of the <code>total_price</code> and <code>total_tax</code> amounts.

notesstring

Custom buyer- or seller-provided notes about the order.

order_numberstring

An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.

order_status'UNKNOWN' | 'AWAITPAY' | 'PAID' | 'REFUNDED' | 'CANCELLED' | 'PARTIALLY_FULFILLED' | 'SHIPPED'

Current state of the order. See the <a href="https://docs.goshippo.com/docs/orders/orders/">orders tutorial</a> for the logic of how the status is handled.

placed_atstring required

Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.

shipping_coststring

Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.

shipping_cost_currencystring

Required if shipping_cost is provided<br> Currency of the <code>shipping_cost</code> amount.

shipping_methodstring

Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose.

subtotal_pricestring
total_pricestring

Total amount paid by the buyer for this order.

total_taxstring

Total tax amount paid by the buyer for this order.

weightstring

Total weight of the order.

weight_unit'g' | 'kg' | 'lb' | 'oz'

The unit used for weight.

object_idstring

Unique identifier of the order object.

object_ownerstring

Username of the user who created the object.

shop_app'Amazon' | 'Bigcommerce' | 'CSV_Import' | 'eBay' | 'ePages' | 'Etsy' | 'Godaddy' | 'Magento' | 'Shippo' | 'Shopify' | 'Spreecommerce' | 'StripeRelay' | 'Walmart' | 'Weebly' | 'WooCommerce'

Platform the order was created on and, if applicable, imported from. Orders created via the Shippo API or dashboard will have the value "Shippo".

transactionsobject[]

Array of <a href="/shippoapi/public-api/transactions">transaction</a> objects representing all shipping labels purchased for this order. All objects are returned expanded with a limited number of fields by default.

Example response

{
  "currency": "USD",
  "notes": "This customer is a VIP",
  "order_number": "#1068",
  "order_status": "PAID",
  "placed_at": "2016-09-23T01:28:12Z",
  "shipping_cost": "12.83",
  "shipping_cost_currency": "USD",
  "shipping_method": "USPS First Class Package",
  "subtotal_price": "12.1",
  "total_price": "24.93",
  "total_tax": "0.0",
  "weight": "0.4",
  "weight_unit": "lb",
  "from_address": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "object_created": "2014-07-09T02:19:13.174Z",
    "object_id": "d799c2679e644279b59fe661ac8fa488",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-09T02:19:13.174Z",
    "validation_results": {
      "messages": [
        {
          "code": "Unknown Street",
          "source": "Shippo Address Validator",
          "text": "City, State and ZIP Code are valid, but street address is not a match.",
          "type": "address_warning"
        }
      ]
    }
  },
  "to_address": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "object_created": "2014-07-09T02:19:13.174Z",
    "object_id": "d799c2679e644279b59fe661ac8fa488",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-09T02:19:13.174Z",
    "validation_results": {
      "messages": [
        {
          "code": "Unknown Street",
          "source": "Shippo Address Validator",
          "text": "City, State and ZIP Code are valid, but street address is not a match.",
          "type": "address_warning"
        }
      ]
    }
  },
  "line_items": [
    {
      "currency": "USD",
      "manufacture_country": "US",
      "max_delivery_time": "2016-07-23T00:00:00Z",
      "max_ship_time": "2016-07-23T00:00:00Z",
      "quantity": 20,
      "sku": "HM-123",
      "title": "Hippo Magazines",
      "total_price": "12.1",
      "variant_title": "June Edition",
      "weight": "0.4",
      "weight_unit": "lb",
      "object_id": "abf7d5675d744b6ea9fdb6f796b28f28"
    }
  ],
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_owner": "shippotle@shippo.com",
  "shop_app": "Shippo"
}