Create an Order History Item
Adds an entry to an order's history. Order history is append-only, so entries cannot be edited or removed once written.
Passing the source_name is not required and defaults to API. Setting it to the name of your own system makes entries easier to attribute.
An order holds a maximum of 250 history entries. Requests beyond that limit return a 403 response, so routine polling should not be recorded here.
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 Desk's internal order ID. This is not your source_id.
736745The note content.
Shipped via UPS, tracking 1Z999AA10123456784Name of the system that added this entry.
APIExample: Warehouse SyncThe entry was added. Returns the order with its history.
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 history entry was rejected.
Authentication failed. See the Authentication guide, and note that an invalid store ID blocks your store rather than simply failing the request.
This order already holds 250 history entries.
No record matches that ID in your store.
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/736745/order-history" \
-X POST \
-H "ORDERDESK-STORE-ID: your-store-id" \
-H "ORDERDESK-API-KEY: your-api-key" \
-H "Content-Type: application/json" \
-d '{"note": "Shipped via UPS, tracking 1Z999AA10123456784", "source_name": "Warehouse Sync"}'
{
"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?