Create an Order
Adds an order to your store and returns it as stored, including the id assigned by Order Desk and the totals it calculated.
You must include some order_items and at least one of the following fields: customer_first_name, customer_last_name, customer_company, shipping_first_name, shipping_last_name, or shipping_company.
If only one of the shipping or customer addresses is supplied, the other is copied from it.
Passing source_id with your own order identifier is recommended, as this is what allows the order to be reconciled with your system later. Pass folder_id if the order should not be placed in your first folder.
If the order is recognized as a duplicate, a 400 response is returned with an existing_order_id field naming the order already in your store.
Your API key, found under Store Settings on the API tab. This should be kept server-side.
Your store ID, found under Store Settings on the API tab.
Order fields common to both reads and writes.
Obfuscated credit card number. Enter only the last four digits. Returned as
cc_number_masked.
4242Your original order ID. If blank, Order Desk's internal ID will be used.
6487172454Name of the order source, cart, or marketplace. If the source is not recognized or
is not entered, this defaults to Order Desk.
Order DeskExample: FoxyCartavery.chen@example.comName of the selected shipping method.
UPS Ground9.50.52.15Credit card expiration in MM/YYYY format.
02/2026Pattern: ^\d{2}/\d{4}$Gateway transaction ID in <gateway_name>: <transaction_id> format.
Authorize.net Transaction ID: 2221864944Visa, MasterCard, PayPal, etc.
VisaCurrent payment status for the order. Defaults to Captured.
CapturedPossible values: Amount charged at the processor. This is decremented when refunds are made, and
defaults to order_total.
21.17Amount refunded on the order from within Order Desk.
0Customer ID from the originating system.
5487542Customer's IP address.
Once the order has been sent for fulfillment, the fulfillment method name is entered here.
Internal ID of the fulfillment service, when available.
ID of the folder containing the order. New orders default to the first folder when this is omitted. Omitting it on an update leaves the order in its current folder. See the Folders guide.
21654Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10AveryChen1200 Campus DriveStreet address 3. Not available for customer addresses.
Street address 3. Not available for customer addresses.
SpringfieldState or region.
ILZIP or postal code.
62704Country code or full country name.
US555-555-5555AveryChen1200 Campus DriveStreet address 3. Not available for customer addresses.
Street address 3. Not available for customer addresses.
SpringfieldState or region.
ILZIP or postal code.
62704Country code or full country name.
US555-555-5555Return address title.
AcmeShipping name.
Doug JonesAcme Manufacturing817 E Maple LnKnoxvilleState or region.
IL62704Country code or full country name.
USSpring SaleCode used for the discount. Optional.
SPRING10The discount amount. Discounts should be stored as positive numbers.
5Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10Name of the person who wrote the note.
Doug JonesCustomer asked us to leave this by the back door.If an id field is passed the item will be updated. Otherwise it will be added.
1670028ODU Campus Hoodie0Example: 191Example: 21.2Item SKU or product code.
ODU-HOOD-NVY-LAvailable options are ship, noship, download, or future. Defaults to ship.
shipPossible values: Further details about the type of item. Freeform text.
ApparelFulfillment method responsible for this item, when one applies.
The order was created.
Either success or error.
Describes the result. Always present when an error occurs.
Time taken to process the request.
0.1524 secondsOrder Desk's internal ID number. Returned as a string, even though it is always numeric. Read-only.
925086Your original order ID. If blank, Order Desk's internal ID will be used.
6487172454Name of the order source, cart, or marketplace. If the source is not recognized or
is not entered, this defaults to Order Desk.
Order DeskExample: FoxyCartavery.chen@example.comName of the selected shipping method.
UPS Ground9.50.52.15Credit card expiration in MM/YYYY format.
02/2026Pattern: ^\d{2}/\d{4}$Gateway transaction ID in <gateway_name>: <transaction_id> format.
Authorize.net Transaction ID: 2221864944Visa, MasterCard, PayPal, etc.
VisaCurrent payment status for the order. Defaults to Captured.
CapturedPossible values: Amount charged at the processor. This is decremented when refunds are made, and
defaults to order_total.
21.17Amount refunded on the order from within Order Desk.
0Customer ID from the originating system.
5487542Customer's IP address.
Once the order has been sent for fulfillment, the fulfillment method name is entered here.
Internal ID of the fulfillment service, when available.
ID of the folder containing the order. New orders default to the first folder when this is omitted. Omitting it on an update leaves the order in its current folder. See the Folders guide.
21654Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10AveryChen1200 Campus DriveStreet address 3. Not available for customer addresses.
Street address 3. Not available for customer addresses.
SpringfieldState or region.
ILZIP or postal code.
62704Country code or full country name.
US555-555-5555AveryChen1200 Campus DriveStreet address 3. Not available for customer addresses.
Street address 3. Not available for customer addresses.
SpringfieldState or region.
ILZIP or postal code.
62704Country code or full country name.
US555-555-5555Return address title.
AcmeShipping name.
Doug JonesAcme Manufacturing817 E Maple LnKnoxvilleState or region.
IL62704Country code or full country name.
USSpring SaleCode used for the discount. Optional.
SPRING10The discount amount. Discounts should be stored as positive numbers.
5Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10Name of the person who wrote the note.
Doug JonesCustomer asked us to leave this by the back door.Obfuscated credit card number. This is the field returned in responses. Use
cc_number when writing.
xxxxxxxxxxxx4242Total number of all items in the order. Read-only.
3Total weight of all items in the order. Read-only.
3.6Total price of all items in the order. Read-only.
57Total value of all discounts, stored as a positive number. Read-only.
5Calculated price of the entire order. Read-only.
63.65Number of orders matching this email address. Returned as a string, even though it is always numeric. Read-only.
3The folder the order was in before its most recent move. Returned as a string. Read-only.
21654Not in use.
Not in use.
Order Desk's internal ID number for the order item. Read-only.
1670028ODU Campus Hoodie0Example: 191Example: 21.2Item SKU or product code.
ODU-HOOD-NVY-LAvailable options are ship, noship, download, or future. Defaults to ship.
shipPossible values: Further details about the type of item. Freeform text.
ApparelFulfillment method responsible for this item, when one applies.
4482192508611Carrier-assigned tracking number. Use n/a if no tracking number is applicable.
1Z999AA10123456784Carrier code such as USPS or FedEx, when available.
UPSShipping service name, such as First Class International.
UPS GroundFinal shipment weight.
2.4Your cost to send the shipment.
9.5Current shipment status, used by the EasyPost webhook.
If omitted, Order Desk attempts to determine it from the tracking number format and carrier code.
Format of the stored label, when one exists.
Stored shipping label, when one exists.
Whether the label has been printed.
Shipment ID in the originating cart, when known.
Shipment ID at the label provider, when known.
Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10What wrote this entry.
APIOrder UpdatedDate and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.
2019-01-15 12:12:10The order was rejected. On a duplicate, existing_order_id names the
order already on file.
Authentication failed. See the Authentication guide, and note that an invalid store ID blocks your store rather than simply failing the request.
An item's metadata or variation_list is over the limit. See
the Errors guide for the sizes.
You are sending too fast. Wait X-Retry-After seconds. See
the Rate Limits guide.
The request could not be completed.
curl "https://app.orderdesk.me/api/v2/orders" \
-X POST \
-H "ORDERDESK-STORE-ID: your-store-id" \
-H "ORDERDESK-API-KEY: your-api-key" \
-H "Content-Type: application/json" \
-d '{"source_id": "6487172454", "source_name": "FoxyCart", "email": "avery.chen@example.com", "shipping_method": "UPS Ground", "shipping_total": 9.5, "tax_total": 2.15, "payment_status": "Captured", "folder_id": 21654, "shipping": {"first_name": "Avery", "last_name": "Chen", "address1": "1200 Campus Drive", "city": "Springfield", "state": "IL", "postal_code": "62704", "country": "US", "phone": "555-555-5555"}, "order_items": [{"name": "ODU Campus Hoodie", "code": "ODU-HOOD-NVY-L", "price": 19, "quantity": 2, "weight": 1.2, "variation_list": {"Size": "Large", "Color": "Red"}}]}'
{
"status": "success",
"message": "text",
"execution_time": "0.1524 seconds",
"order": {
"id": "925086",
"source_id": "6487172454",
"source_name": "FoxyCart",
"email": "avery.chen@example.com",
"shipping_method": "UPS Ground",
"shipping_total": 9.5,
"handling_total": 0.5,
"tax_total": 2.15,
"cc_exp": "02/2026",
"processor_response": "Authorize.net Transaction ID: 2221864944",
"payment_type": "Visa",
"payment_status": "Captured",
"processor_balance": 21.17,
"refund_total": 0,
"customer_id": "5487542",
"ip_address": "text",
"fulfillment_name": "text",
"fulfillment_id": "text",
"folder_id": 21654,
"date_added": "2019-01-15 12:12:10",
"date_updated": "2019-01-15 12:12:10",
"checkout_data": {
"Order Notes": "Please leave by the back door"
},
"order_metadata": {
"fraud_protection_score": 0
},
"shipping": {
"first_name": "Avery",
"last_name": "Chen",
"company": "text",
"address1": "1200 Campus Drive",
"address2": "text",
"address3": "text",
"address4": "text",
"city": "Springfield",
"state": "IL",
"postal_code": "62704",
"country": "US",
"phone": "555-555-5555"
},
"customer": {
"first_name": "Avery",
"last_name": "Chen",
"company": "text",
"address1": "1200 Campus Drive",
"address2": "text",
"address3": "text",
"address4": "text",
"city": "Springfield",
"state": "IL",
"postal_code": "62704",
"country": "US",
"phone": "555-555-5555"
},
"return_address": {
"title": "Acme",
"name": "Doug Jones",
"company": "Acme Manufacturing",
"address1": "817 E Maple Ln",
"address2": "text",
"city": "Knoxville",
"state": "IL",
"postal_code": "62704",
"country": "US",
"phone": "text"
},
"discount_list": [
{
"name": "Spring Sale",
"code": "SPRING10",
"amount": 5
}
],
"order_notes": [
{
"date_added": "2019-01-15 12:12:10",
"username": "Doug Jones",
"content": "Customer asked us to leave this by the back door."
}
],
"cc_number_masked": "xxxxxxxxxxxx4242",
"quantity_total": 3,
"weight_total": 3.6,
"product_total": 57,
"discount_total": 5,
"order_total": 63.65,
"email_count": "3",
"previous_folder_id": "21654",
"tag_color": "text",
"tag_name": "text",
"order_items": [
{
"id": 1670028,
"name": "ODU Campus Hoodie",
"price": 19,
"quantity": 2,
"weight": 1.2,
"code": "ODU-HOOD-NVY-L",
"delivery_type": "ship",
"category_code": "Apparel",
"fulfillment_method": "text",
"variation_list": {
"Size": "Large",
"Color": "Red"
},
"metadata": {
"image": "https://example.com/odu-hoodie.jpg",
"print_sku": "x533"
}
}
],
"order_shipments": [
{
"id": 44821,
"order_id": 925086,
"store_id": 11,
"tracking_number": "1Z999AA10123456784",
"carrier_code": "UPS",
"shipment_method": "UPS Ground",
"weight": 2.4,
"cost": 9.5,
"status": "text",
"tracking_url": "text",
"label_format": "text",
"label_image": "text",
"print_status": "text",
"cart_shipment_id": "text",
"label_shipment_id": "text",
"order_items": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"date_shipped": "2019-01-15 12:12:10",
"date_added": "2019-01-15 12:12:10"
}
],
"order_history": [
{
"source_name": "API",
"note": "Order Updated",
"date_added": "2019-01-15 12:12:10"
}
]
}
}Last updated
Was this helpful?