Create a new order

curl https://api.goshippo.com/orders/ \ -H "Authorization: ShippoToken <API_TOKEN>" \ -d '{ "to_address": { "city": "San Francisco", "company": "Shippo", "country": "US", "email": "shippotle@shippo.com", "name": "Mr Hippo", "phone": "15553419393", "state": "CA", "street1": "215 Clayton St.", "zip": "94117" }, "line_items": [ { "quantity": 1, "sku": "HM-123", "title": "Hippo Magazines", "total_price": "12.10", "currency": "USD", "weight": "0.40", "weight_unit": "lb" } ], "placed_at": "2016-09-23T01:28:12Z", "order_number": "#1068", "order_status": "PAID", "shipping_cost": "12.83", "shipping_cost_currency": "USD", "shipping_method": "USPS First Class Package", "subtotal_price": "12.10", "total_price": "24.93", "total_tax": "0.00", "currency": "USD", "weight": "0.40", "weight_unit": "lb" }'

{ "placed_at": "2016-09-23T01:28:12Z", "to_address": { "country": "US", "name": "Shwan Ippotle", "company": "Shippo", "street1": "215 Clayton St.", "street2": "<string>", "street3": "", "street_no": "", "city": "San Francisco", "state": "CA", "zip": "94117", "phone": "+1 555 341 9393", "email": "shippotle@shippo.com", "is_residential": true, "metadata": "Customer ID 123456", "is_complete": true, "latitude": 123, "longitude": 123, "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": { "is_valid": false, "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" } ] }, "test": false }, "currency": "USD", "notes": "This customer is a VIP", "order_number": "#1068", "order_status": "PAID", "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": { "country": "US", "name": "Shwan Ippotle", "company": "Shippo", "street1": "215 Clayton St.", "street2": "<string>", "street3": "", "street_no": "", "city": "San Francisco", "state": "CA", "zip": "94117", "phone": "+1 555 341 9393", "email": "shippotle@shippo.com", "is_residential": true, "metadata": "Customer ID 123456", "is_complete": true, "latitude": 123, "longitude": 123, "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": { "is_valid": false, "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" } ] }, "test": false }, "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", "transactions": [ {} ] }

Authorizations

Authorization

string

header

default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb

required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

SHIPPO-API-VERSION

string

default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Order details.

placed_at

string

required

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

Example:

"2016-09-23T01:28:12Z"

to_address

object

required

Address object of the recipient / buyer. Will be returned expanded by default.

Show child attributes

currency

string

Required if total_price is provided
Currency of the total_price and total_tax amounts.

Example:

"USD"

notes

string

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

Example:

"This customer is a VIP"

order_number

string

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

Example:

"#1068"

order_status

enum<string>

Current state of the order. See the orders tutorial for the logic of how the status is handled.

Available options:

UNKNOWN,

AWAITPAY,

PAID,

REFUNDED,

CANCELLED,

PARTIALLY_FULFILLED,

SHIPPED

Example:

"PAID"

shipping_cost

string

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

Example:

"12.83"

shipping_cost_currency

string

Required if shipping_cost is provided
Currency of the shipping_cost amount.

Example:

"USD"

shipping_method

string

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.

Example:

"USPS First Class Package"

subtotal_price

string

Example:

"12.1"

total_price

string

Total amount paid by the buyer for this order.

Example:

"24.93"

total_tax

string

Total tax amount paid by the buyer for this order.

Example:

"0.0"

weight

string

Total weight of the order.

Example:

"0.4"

weight_unit

enum<string>

The unit used for weight.

Available options:

g,

kg,

lb,

oz

Example:

"lb"

from_address

object

Address object of the sender / seller. Will be returned expanded by default..

Show child attributes

line_items

object[]

Array of line item objects representing the items in this order. All objects will be returned expanded by default.

Show child attributes

Response

Order

placed_at

string

required

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

Example:

"2016-09-23T01:28:12Z"

to_address

object

required

Address object of the recipient / buyer. Will be returned expanded by default.

Show child attributes

currency

string

Required if total_price is provided
Currency of the total_price and total_tax amounts.

Example:

"USD"

notes

string

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

Example:

"This customer is a VIP"

order_number

string

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

Example:

"#1068"

order_status

enum<string>

Current state of the order. See the orders tutorial for the logic of how the status is handled.

Available options:

UNKNOWN,

AWAITPAY,

PAID,

REFUNDED,

CANCELLED,

PARTIALLY_FULFILLED,

SHIPPED

Example:

"PAID"

shipping_cost

string

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

Example:

"12.83"

shipping_cost_currency

string

Required if shipping_cost is provided
Currency of the shipping_cost amount.

Example:

"USD"

shipping_method

string

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.

Example:

"USPS First Class Package"

subtotal_price

string

Example:

"12.1"

total_price

string

Total amount paid by the buyer for this order.

Example:

"24.93"

total_tax

string

Total tax amount paid by the buyer for this order.

Example:

"0.0"

weight

string

Total weight of the order.

Example:

"0.4"

weight_unit

enum<string>

The unit used for weight.

Available options:

g,

kg,

lb,

oz

Example:

"lb"

from_address

object

Address object of the sender / seller. Will be returned expanded by default.

Show child attributes

line_items

Line Item · object[]

Array of line item objects representing the items in this order. All objects will be returned expanded by default.

Show child attributes

object_id

string

Unique identifier of the order object.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

object_owner

string

Username of the user who created the object.

Example:

"shippotle@shippo.com"

shop_app

enum<string>

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

Available options:

Amazon,

Bigcommerce,

CSV_Import,

eBay,

ePages,

Etsy,

Godaddy,

Magento,

Shippo,

Shopify,

Spreecommerce,

StripeRelay,

Walmart,

Weebly,

WooCommerce

Example:

"Shippo"

transactions

object[]

Array of transaction objects representing all shipping labels purchased for this order. All objects are returned expanded with a limited number of fields by default.

Overview

Shippo API

Enums

Addresses API v2

Authorizations

Headers

Body

Response