> For the complete documentation index, see [llms.txt](https://help.orderdesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.orderdesk.com/api-documentation/v2-api-reference/orders/create-an-order-history-item.md).

# 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.

```json
{"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"tags":[{"name":"Orders"}],"servers":[{"url":"https://app.orderdesk.me/api/v2","description":"Production"}],"security":[{"OrderDeskStoreId":[],"OrderDeskApiKey":[]}],"components":{"securitySchemes":{"OrderDeskStoreId":{"type":"apiKey","in":"header","name":"ORDERDESK-STORE-ID","description":"Your store ID, found under Store Settings on the API tab."}},"schemas":{"ResponseEnvelope":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["success","error"],"description":"Either `success` or `error`."},"message":{"type":"string","description":"Describes the result. Always present when an error occurs."},"execution_time":{"type":"string","description":"Time taken to process the request."}}},"Order":{"description":"An order as stored in Order Desk. It contains the customer and shipping addresses, the line\nitems, the order totals, the payment details, and any shipments recorded against it.\n\nOrder Desk assigns each order an internal `id`. Your own identifier is stored in `source_id`,\nand the system the order came from is stored in `source_name`. Every path that takes an\n`order_id` refers to the Order Desk `id`. To retrieve an order by your own identifier, search\non `source_id` instead.\n\nThe `quantity_total`, `weight_total`, `product_total`, `discount_total`, and `order_total`\nfields are calculated from the line items and cannot be set directly.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Order Desk's internal ID number. Returned as a string, even though it is\nalways numeric. Read-only.\n"}}},{"$ref":"#/components/schemas/OrderFields"},{"type":"object","properties":{"cc_number_masked":{"type":"string","readOnly":true,"description":"Obfuscated credit card number. This is the field returned in responses. Use\n`cc_number` when writing.\n"},"quantity_total":{"type":"integer","readOnly":true,"description":"Total number of all items in the order. Read-only."},"weight_total":{"type":"number","format":"double","readOnly":true,"description":"Total weight of all items in the order. Read-only."},"product_total":{"type":"number","format":"double","readOnly":true,"description":"Total price of all items in the order. Read-only."},"discount_total":{"type":"number","format":"double","readOnly":true,"description":"Total value of all discounts, stored as a positive number. Read-only."},"order_total":{"type":"number","format":"double","readOnly":true,"description":"Calculated price of the entire order. Read-only."},"email_count":{"type":"string","readOnly":true,"description":"Number of orders matching this email address. Returned as a string, even\nthough it is always numeric. Read-only.\n"},"previous_folder_id":{"type":"string","readOnly":true,"description":"The folder the order was in before its most recent move. Returned as a\nstring. Read-only.\n"},"tag_color":{"type":"string","readOnly":true,"description":"Not in use."},"tag_name":{"type":"string","readOnly":true,"description":"Not in use."},"order_items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"order_shipments":{"type":"array","readOnly":true,"description":"List of shipments recorded against this order. These may not be modified through\nthe order object.\n","items":{"$ref":"#/components/schemas/Shipment"}},"order_history":{"type":"array","readOnly":true,"description":"Returned when `get_order_history` is set to 1 on a search, and after an order\nhistory entry is added.\n","items":{"$ref":"#/components/schemas/OrderHistoryEntry"}}}}]},"OrderFields":{"type":"object","description":"Order fields common to both reads and writes.","properties":{"source_id":{"type":"string","description":"Your original order ID. If blank, Order Desk's internal ID will be used."},"source_name":{"type":"string","default":"Order Desk","description":"Name of the order source, cart, or marketplace. If the source is not recognized or\nis not entered, this defaults to `Order Desk`.\n"},"email":{"type":"string","format":"email"},"shipping_method":{"type":"string","description":"Name of the selected shipping method."},"shipping_total":{"type":"number","format":"double"},"handling_total":{"type":"number","format":"double"},"tax_total":{"type":"number","format":"double"},"cc_exp":{"type":"string","pattern":"^\\d{2}/\\d{4}$","description":"Credit card expiration in `MM/YYYY` format."},"processor_response":{"type":"string","description":"Gateway transaction ID in `<gateway_name>: <transaction_id>` format."},"payment_type":{"type":"string","description":"Visa, MasterCard, PayPal, etc."},"payment_status":{"$ref":"#/components/schemas/PaymentStatus"},"processor_balance":{"type":"number","format":"double","description":"Amount charged at the processor. This is decremented when refunds are made, and\ndefaults to `order_total`.\n"},"refund_total":{"type":"number","format":"double","description":"Amount refunded on the order from within Order Desk."},"customer_id":{"type":"string","description":"Customer ID from the originating system."},"ip_address":{"type":"string","description":"Customer's IP address."},"fulfillment_name":{"type":"string","description":"Once the order has been sent for fulfillment, the fulfillment method name is entered here."},"fulfillment_id":{"type":"string","description":"Internal ID of the fulfillment service, when available."},"folder_id":{"type":"integer","description":"ID of the folder containing the order. New orders default to the first folder when\nthis is omitted. Omitting it on an update leaves the order in its current folder.\nSee the Folders guide.\n"},"date_added":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"description":"Order date stored in UTC."},"date_updated":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"description":"Date the order was last updated, stored in UTC."},"checkout_data":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra order details in key/value format. Used when the details may\nneed to be manually edited in Order Desk. Maximum total size is 3,500 characters\nwhen JSON-encoded.\n"},"order_metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra (hidden) order details in key/value format. Maximum total size\nis 2,000 characters when JSON-encoded.\n"},"shipping":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Shipping address details. If nothing is entered, the customer address will be copied\nhere.\n"},"customer":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Customer address details. If nothing is entered, the shipping address will be copied\nhere.\n"},"return_address":{"$ref":"#/components/schemas/ReturnAddress"},"discount_list":{"type":"array","description":"List of discounts applied to the order.","items":{"$ref":"#/components/schemas/Discount"}},"order_notes":{"type":"array","description":"List of notes on the order.","items":{"$ref":"#/components/schemas/OrderNote"}}}},"PaymentStatus":{"type":"string","default":"Captured","description":"Current payment status for the order. Defaults to `Captured`.","enum":["Approved","Authorized","Captured","Fully Refunded","Partially Refunded","Pending","Rejected","Voided"]},"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."},"KeyValue":{"type":"object","additionalProperties":true,"description":"A collection in key/value format. Must be flat, with no nested arrays. Keys must be\nstrings, and values must be strings, numbers, booleans, or null.\n\nWhen the collection is empty, the API returns an empty array (`[]`) rather than an\nempty object. Treat both as \"no entries\" when parsing.\n"},"Address":{"type":"object","description":"Customer or shipping address details. A first and last name combination or a company\nname must be entered to be a valid order.\n","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string","description":"Street address 3. Not available for customer addresses."},"address4":{"type":"string","description":"Street address 3. Not available for customer addresses."},"city":{"type":"string"},"state":{"type":"string","description":"State or region."},"postal_code":{"type":"string","description":"ZIP or postal code."},"country":{"type":"string","description":"Country code or full country name."},"phone":{"type":"string"}}},"ReturnAddress":{"type":"object","description":"If an order has a custom return address, it is entered here. This can be set by a rule,\nor when the order is inserted through the API.\n","properties":{"title":{"type":"string","description":"Return address title."},"name":{"type":"string","description":"Shipping name."},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"State or region."},"postal_code":{"type":"string"},"country":{"type":"string","description":"Country code or full country name."},"phone":{"type":"string"}}},"Discount":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Code used for the discount. Optional."},"amount":{"type":"number","format":"double","description":"The discount amount. Discounts should be stored as positive numbers."}}},"OrderNote":{"type":"object","description":"There is a 2,000 character max for all notes, including date and username metadata, so\nkeep note content under 1,800 characters to avoid data loss.\n","properties":{"date_added":{"$ref":"#/components/schemas/DateTime"},"username":{"type":"string","description":"Name of the person who wrote the note."},"content":{"type":"string","maxLength":1800}}},"OrderItem":{"description":"A product contained in an order. Items can be modified one at a time, or through the order\nitself: passing an `order_items` array to the order update operation will add items that have\nno `id`, update items that do, and remove any item that is omitted.\n\nModifying items recalculates the order totals.\n","allOf":[{"type":"object","properties":{"id":{"type":"integer","readOnly":true,"description":"Order Desk's internal ID number for the order item. Read-only."}}},{"$ref":"#/components/schemas/OrderItemFields"}]},"OrderItemFields":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number","format":"double","default":0},"quantity":{"type":"integer","default":1},"weight":{"type":"number","format":"double"},"code":{"type":"string","description":"Item SKU or product code."},"delivery_type":{"$ref":"#/components/schemas/DeliveryType"},"category_code":{"type":"string","description":"Further details about the type of item. Freeform text."},"fulfillment_method":{"type":"string","description":"Fulfillment method responsible for this item, when one applies."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`. Maximum total size is 5,000 characters when JSON-encoded.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra (hidden) item details in key/value format. Maximum total size is\n15,000 characters when JSON-encoded.\n"}}},"DeliveryType":{"type":"string","default":"ship","description":"Available options are `ship`, `noship`, `download`, or `future`. Defaults to `ship`.\n","enum":["ship","noship","download","future"]},"Shipment":{"description":"A record that some or all of an order has left the warehouse, along with the carrier and\ntracking number used. An order can contain multiple shipments, which is how a partial\nfulfillment is represented.\n\nShipments may not be modified through the order object.\n","allOf":[{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"order_id":{"type":"integer","readOnly":true},"store_id":{"type":"integer","readOnly":true}}},{"$ref":"#/components/schemas/ShipmentFields"},{"type":"object","properties":{"label_format":{"type":"string","readOnly":true,"description":"Format of the stored label, when one exists."},"label_image":{"type":"string","readOnly":true,"description":"Stored shipping label, when one exists."},"print_status":{"type":"string","readOnly":true,"description":"Whether the label has been printed."},"cart_shipment_id":{"type":"string","readOnly":true,"description":"Shipment ID in the originating cart, when known."},"label_shipment_id":{"type":"string","readOnly":true,"description":"Shipment ID at the label provider, when known."},"order_items":{"type":"array","readOnly":true,"description":"The order items covered by this shipment.","items":{"type":"object","additionalProperties":true}},"date_shipped":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true},"date_added":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true}}}]},"ShipmentFields":{"type":"object","properties":{"tracking_number":{"type":"string","description":"Carrier-assigned tracking number. Use `n/a` if no tracking number is applicable.\n"},"carrier_code":{"type":"string","description":"Carrier code such as `USPS` or `FedEx`, when available."},"shipment_method":{"type":"string","description":"Shipping service name, such as `First Class International`."},"weight":{"type":"number","format":"double","description":"Final shipment weight."},"cost":{"type":"number","format":"double","description":"Your cost to send the shipment."},"status":{"type":"string","description":"Current shipment status, used by the EasyPost webhook."},"tracking_url":{"type":"string","description":"If omitted, Order Desk attempts to determine it from the tracking number format and\ncarrier code.\n"}}},"OrderHistoryEntry":{"type":"object","description":"An entry in the order's history. History is append-only, and an order holds a maximum of\n250 entries.\n","properties":{"source_name":{"type":"string","description":"What wrote this entry."},"note":{"type":"string"},"date_added":{"$ref":"#/components/schemas/DateTime"}}}},"responses":{"BadRequestHistory":{"description":"The history entry was rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"Unauthorized":{"description":"Authentication failed. See the Authentication guide, and\nnote that an invalid store ID blocks your store rather than simply\nfailing the request.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"HistoryLimitReached":{"description":"This order already holds 250 history entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"NotFound":{"description":"No record matches that ID in your store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"RateLimited":{"description":"You are sending too fast. Wait `X-Retry-After` seconds. See\nthe Rate Limits guide.\n","headers":{"X-Tokens-Remaining":{"description":"Number of request tokens currently available.","schema":{"type":"integer"}},"X-Retry-After":{"description":"Seconds to wait before requests can resume.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"Error":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}}}},"paths":{"/orders/{order_id}/order-history":{"post":{"tags":["Orders"],"summary":"Create an Order History Item","description":"Adds an entry to an order's history. Order history is append-only, so entries\ncannot be edited or removed once written.\n\nPassing the `source_name` is not required and defaults to `API`. Setting it to\nthe name of your own system makes entries easier to attribute.\n\nAn order holds a maximum of 250 history entries. Requests beyond that limit\nreturn a `403` response, so routine polling should not be recorded here.\n","operationId":"createOrderHistoryItem","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","description":"The note content."},"source_name":{"type":"string","description":"Name of the system that added this entry.","default":"API"}}}}}},"responses":{"201":{"description":"The entry was added. Returns the order with its history.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequestHistory"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/HistoryLimitReached"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.orderdesk.com/api-documentation/v2-api-reference/orders/create-an-order-history-item.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.