post

/orders

Creates an Order. To learn more about creating or updating orders, See Orders Overview.

An order can be created with an existing catalog product or a custom product.

Required Fields

  • products
  • billing_address
Read Only Fields
ID date_modified date_shipped
order_source cart_id subtotal_tax
shipping_cost_tax shipping_cost_tax_class_id handling_cost_tax
handling_cost_tax_class_id wrapping_cost_tax wrapping_cost_tax_class_id
total_tax payment_status currency_id
currency_code currency_exchange_rate currency_exchange_rate
default_currency_id default_currency_code coupon_discount
status subtotal_tax store_credit_amount
shipping_address_count coupons

Authorization

apiKey - X-Auth-Token
apiKey - X-Auth-Client

Request Parameters

2 Headers

Request Body

3 Examples
Schema
object
id
integer

The ID of the order, a read-only value. Do not pass in PUT or POST.

1 validation
customer_id
integer

The ID of the customer placing the order; or 0 if it was a guest order.

1 validation
date_created
string

The date this order was created. If not specified, will default to the current time. The date should be in RFC 2822 format, e.g.: Tue, 20 Nov 2012 00:00:00 +0000

2 validations
date_modified
string

A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT operation.

2 validations
date_shipped
string

A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT operation.

2 validations
status_id
integer

The status ID of the order.

1 validation
cart_id
string

The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

1 validation
status
string

The status will include one of the (string, optiona) - values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation.

1 validation
custom_status
string

Contains the same (string, optiona) - value as the Order Statuses object’s custom_label property.

1 validation
subtotal_ex_tax
string

Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_inc_tax
string

Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_tax
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
base_shipping_cost
string

The value of the base shipping cost. (Float, Float-As-String, Integer)

1 validation
shipping_cost_ex_tax
string

The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_inc_tax
string

The value of shipping cost, including tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
shipping_cost_tax_class_id
integer

Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
base_handling_cost
string

The value of the base handling cost. (Float, Float-As-String, Integer)

1 validation
handling_cost_ex_tax
string

The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_inc_tax
number

The value of the handling cost, including tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
handling_cost_tax_class_id
integer

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
base_wrapping_cost
integer

The value of the base wrapping cost. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_ex_tax
string

The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_inc_tax
string

The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_tax_class_id
integer

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
total_ex_tax
string

Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_inc_tax
string

Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_tax
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
items_total
number

The total number of items in the order.

1 validation
items_shipped
number

The number of items that have been shipped.

1 validation
payment_method
string

The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.

1 validation
payment_provider_id
string

The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).

1 validation
payment_status
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.

refunded_amount
string

The amount refunded from this transaction. (Float, Float-As-String, Integer)

1 validation
order_is_digital
boolean

Whether this is an order for digital products.

1 validation
store_credit_amount
string

Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
gift_certificate_amount
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
ip_address
string

IP Address of the customer, if known.

1 validation
geoip_country
string

The full name of the country where the customer made the purchase, based on the IP.

1 validation
geoip_country_iso2
string

The country where the customer made the purchase, in ISO2 format, based on the IP.

1 validation
currency_id
integer

The ID of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
currency_code
string

The currency code of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
currency_exchange_rate
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
default_currency_id
integer

A read-only value. Do not pass in a POST or PUT.

1 validation
default_currency_code
string

The currency code of the default currency for this type of transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
staff_notes
string

Any additional notes for staff.

1 validation
customer_message
string

Message that the customer entered (number, optiona) -o the Order Comments box during checkout.

1 validation
discount_amount
string

Amount of discount for this transaction. (Float, Float-As-String, Integer)

1 validation
coupon_discount
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
shipping_address_count
number

The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.

is_deleted
boolean

Indicates whether the order was deleted (archived). Set to to true, to archive an order.

1 validation
is_email_opt_in
boolean

Indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT.

1 validation
credit_card_type
integer
ebay_order_id
string

If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.

1 validation
billing_address
object

Required to create an order.

required
order_source
string

Orders submitted via the store’s website will include a www value. Orders submitted via the API will be set to external. A read-only value. Do not pass in a POST or PUT.

1 validation
external_source
string

For orders submitted or modified via the API, using a PUT or POST operation, you can optionally pass in a value identifying the system used to generate the order. For example: POS. Otherwise, the value will be null.

1 validation
products
object
required
shipping_addresses
object
coupons
object
external_id
string

ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ‘external_id’ cannot be written to. Please remove it from your request before trying again. It can not be overwritten once set.

1 validation
external_merchant_id
string

Id of the external merchant.

1 validation
form_fields
array[object]

If you have required address form fields they will need to be set as optional before creating an order via API.

1 validation
channel_id
number

Shows where the order originated. The channel_id will default to 1. Read-Only.

1 validation
tax_provider_id
string

BasicTaxProvider - Tax is set to manual.

AvaTaxProvider - This is for when the tax provider has been set to automatic and the order was NOT created by the API. Used for Avalara.

“” (blank) - When the tax provider is unknown. This includes legacy orders and orders previously created via API. This can be set when creating an order using a POST.

1 validation

Responses

2 Examples
Schema
object
id
integer

The ID of the order, a read-only value. Do not pass in PUT or POST.

1 validation
customer_id
integer

The ID of the customer placing the order; or 0 if it was a guest order.

1 validation
date_created
string

The date this order was created. If not specified, will default to the current time. The date should be in RFC 2822 format, e.g.: Tue, 20 Nov 2012 00:00:00 +0000

2 validations
date_modified
string

A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT operation.

2 validations
date_shipped
string

A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT operation.

2 validations
status_id
integer

The status ID of the order.

1 validation
cart_id
string

The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

1 validation
status
string

The status will include one of the (string, optiona) - values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation.

1 validation
custom_status
string

Contains the same (string, optiona) - value as the Order Statuses object’s custom_label property.

1 validation
subtotal_ex_tax
string

Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_inc_tax
string

Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
subtotal_tax
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
base_shipping_cost
string

The value of the base shipping cost. (Float, Float-As-String, Integer)

1 validation
shipping_cost_ex_tax
string

The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_inc_tax
string

The value of shipping cost, including tax. (Float, Float-As-String, Integer)

1 validation
shipping_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
shipping_cost_tax_class_id
integer

Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
base_handling_cost
string

The value of the base handling cost. (Float, Float-As-String, Integer)

1 validation
handling_cost_ex_tax
string

The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_inc_tax
number

The value of the handling cost, including tax. (Float, Float-As-String, Integer)

1 validation
handling_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
handling_cost_tax_class_id
integer

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
base_wrapping_cost
integer

The value of the base wrapping cost. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_ex_tax
string

The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_inc_tax
string

The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_tax
string

A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
wrapping_cost_tax_class_id
integer

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)

1 validation
total_ex_tax
string

Override value for the total, excluding tax. If specified, the field total_inc_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_inc_tax
string

Override value for the total, including tax. If specified, the field total_ex_tax is also required. (Float, Float-As-String, Integer)

1 validation
total_tax
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (Float, Float-As-String, Integer)

1 validation
items_total
number

The total number of items in the order.

1 validation
items_shipped
number

The number of items that have been shipped.

1 validation
payment_method
string

The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.

1 validation
payment_provider_id
string

The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).

1 validation
payment_status
string

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.

refunded_amount
string

The amount refunded from this transaction. (Float, Float-As-String, Integer)

1 validation
order_is_digital
boolean

Whether this is an order for digital products.

1 validation
store_credit_amount
string

Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
gift_certificate_amount
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
ip_address
string

IP Address of the customer, if known.

1 validation
geoip_country
string

The full name of the country where the customer made the purchase, based on the IP.

1 validation
geoip_country_iso2
string

The country where the customer made the purchase, in ISO2 format, based on the IP.

1 validation
currency_id
integer

The ID of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
currency_code
string

The currency code of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
currency_exchange_rate
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
default_currency_id
integer

A read-only value. Do not pass in a POST or PUT.

1 validation
default_currency_code
string

The currency code of the default currency for this type of transaction. A read-only value. Do not pass in a POST or PUT.

1 validation
staff_notes
string

Any additional notes for staff.

1 validation
customer_message
string

Message that the customer entered (number, optiona) -o the Order Comments box during checkout.

1 validation
discount_amount
string

Amount of discount for this transaction. (Float, Float-As-String, Integer)

1 validation
coupon_discount
string

A read-only value. Do not pass in a POST or PUT. (Float, Float-As-String, Integer)

1 validation
shipping_address_count
number

The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.

is_deleted
boolean

Indicates whether the order was deleted (archived). Set to to true, to archive an order.

1 validation
is_email_opt_in
boolean

Indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT.

1 validation
credit_card_type
integer
ebay_order_id
string

If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.

1 validation
billing_address
object

Required to create an order.

required
order_source
string

Orders submitted via the store’s website will include a www value. Orders submitted via the API will be set to external. A read-only value. Do not pass in a POST or PUT.

1 validation
external_source
string

For orders submitted or modified via the API, using a PUT or POST operation, you can optionally pass in a value identifying the system used to generate the order. For example: POS. Otherwise, the value will be null.

1 validation
products
object
required
shipping_addresses
object
coupons
object
external_id
string

ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ‘external_id’ cannot be written to. Please remove it from your request before trying again. It can not be overwritten once set.

1 validation
external_merchant_id
string

Id of the external merchant.

1 validation
form_fields
array[object]

If you have required address form fields they will need to be set as optional before creating an order via API.

1 validation
channel_id
number

Shows where the order originated. The channel_id will default to 1. Read-Only.

1 validation
tax_provider_id
string

BasicTaxProvider - Tax is set to manual.

AvaTaxProvider - This is for when the tax provider has been set to automatic and the order was NOT created by the API. Used for Avalara.

“” (blank) - When the tax provider is unknown. This includes legacy orders and orders previously created via API. This can be set when creating an order using a POST.

1 validation

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
Path Params
1 path param not set
store_hash
$$.env
2 variables not set
X-Auth-Token
X-Auth-Client