> 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/models.md). # Models ## The DateTime object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."}}}} ``` ## The KeyValue object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}}} ``` ## The PaymentStatus object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"]}}}} ``` ## The DeliveryType object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"DeliveryType":{"type":"string","default":"ship","description":"Available options are `ship`, `noship`, `download`, or `future`. Defaults to `ship`.\n","enum":["ship","noship","download","future"]}}}} ``` ## The ResponseEnvelope object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"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."}}}}}} ``` ## The PaginatedEnvelope object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"PaginatedEnvelope":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"total_records":{"type":"integer","description":"Total number of records matching the filters, regardless of paging."},"records_returned":{"type":"integer","description":"Number of records returned in this response."},"offset":{"type":"integer","description":"The offset applied to this request."},"limit":{"type":"integer","description":"The limit applied to this request, after any reduction to the maximum.\n"}}}]},"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."}}}}}} ``` ## The Address object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}}}}} ``` ## The ReturnAddress object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}}}}} ``` ## The Discount object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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."}}}}}} ``` ## The OrderNote object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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}}},"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."}}}} ``` ## The OrderHistoryEntry object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}},"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."}}}} ``` ## The OrderItemFields object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"]},"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"}}}} ``` ## The OrderItem object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"]},"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"}}}} ``` ## The OrderItemWrite object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"OrderItemWrite":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"If an `id` field is passed the item will be updated. Otherwise it will be added.\n"}}},{"$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"]},"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"}}}} ``` ## The ShipmentFields object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}}}}} ``` ## The ShipmentWrite object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"ShipmentWrite":{"allOf":[{"$ref":"#/components/schemas/ShipmentFields"}]},"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"}}}}}} ``` ## The BatchShipmentWrite object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"BatchShipmentWrite":{"allOf":[{"type":"object","required":["order_id"],"properties":{"order_id":{"type":"integer","description":"Order Desk's internal ID for the order this shipment belongs to."}}},{"$ref":"#/components/schemas/ShipmentFields"}]},"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"}}}}}} ``` ## The Shipment object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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"}}},"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."}}}} ``` ## The OrderFields object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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 `: ` 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}}}}}} ``` ## The Order object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"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 `: ` 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"}}}}}} ``` ## The OrderCreate object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"OrderCreate":{"description":"A new order to be added to the store.","allOf":[{"type":"object","required":["order_items"],"properties":{"cc_number":{"type":"string","description":"Obfuscated credit card number. Enter only the last four digits. Returned as\n`cc_number_masked`.\n"}}},{"$ref":"#/components/schemas/OrderFields"},{"type":"object","properties":{"order_items":{"type":"array","minItems":1,"description":"At least one order item is required.","items":{"$ref":"#/components/schemas/OrderItemWrite"}}}}]},"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 `: ` 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}}},"OrderItemWrite":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"If an `id` field is passed the item will be updated. Otherwise it will be added.\n"}}},{"$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"]}}}} ``` ## The OrderUpdate object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"OrderUpdate":{"description":"A complete order record. Any parts left out will be updated as blank, with the exception\nof `folder_id`.\n","allOf":[{"type":"object","properties":{"cc_number":{"type":"string","description":"Obfuscated credit card number. Enter only the last four digits. Returned as\n`cc_number_masked`.\n"}}},{"$ref":"#/components/schemas/OrderFields"},{"type":"object","properties":{"order_items":{"type":"array","description":"If an `id` field is passed with the order item it will be updated, otherwise it\nwill be added. Any item that is omitted is removed from the order.\n","items":{"$ref":"#/components/schemas/OrderItemWrite"}}}}]},"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 `: ` 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}}},"OrderItemWrite":{"allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"If an `id` field is passed the item will be updated. Otherwise it will be added.\n"}}},{"$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"]}}}} ``` ## The InventoryItemFields object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"InventoryItemFields":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Product's unique SKU. This is how Order Desk matches an order line to an inventory\nrecord, so it must match the code that your orders arrive with.\n"},"price":{"type":"number","format":"double"},"cost":{"type":"number","format":"double","description":"Item cost in decimal format."},"weight":{"type":"number","format":"double","description":"The shipping weight of the item."},"stock":{"type":"integer","description":"The number of available units."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of special information about the inventory item. Used by some\nintegrations.\n"},"manufacturer_sku":{"type":"string","description":"The SKU used by the manufacturer. This can be used as `print_sku`."},"location":{"type":"string","description":"Warehouse or fulfillment method responsible for the item."},"update_source":{"type":"string","description":"The name of the last system to update the item's details. Setting this allows those\nupdates to be excluded later using the `update_source_not` search parameter.\n"}}},"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"}}}} ``` ## The InventoryItem object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"InventoryItem":{"description":"A product record, including the SKU, price, cost, weight, and stock count. Order Desk can\ndecrement stock as orders arrive and hold fulfillment when an item is out of stock.\n\nA valid inventory item includes a name and code (SKU). The code is how Order Desk matches an\norder line to an inventory record, so it must match the code that your orders arrive with.\n","allOf":[{"type":"object","properties":{"id":{"type":"integer","readOnly":true}}},{"$ref":"#/components/schemas/InventoryItemFields"},{"type":"object","properties":{"date_added":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true},"date_updated":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true}}}]},"InventoryItemFields":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Product's unique SKU. This is how Order Desk matches an order line to an inventory\nrecord, so it must match the code that your orders arrive with.\n"},"price":{"type":"number","format":"double"},"cost":{"type":"number","format":"double","description":"Item cost in decimal format."},"weight":{"type":"number","format":"double","description":"The shipping weight of the item."},"stock":{"type":"integer","description":"The number of available units."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of special information about the inventory item. Used by some\nintegrations.\n"},"manufacturer_sku":{"type":"string","description":"The SKU used by the manufacturer. This can be used as `print_sku`."},"location":{"type":"string","description":"Warehouse or fulfillment method responsible for the item."},"update_source":{"type":"string","description":"The name of the last system to update the item's details. Setting this allows those\nupdates to be excluded later using the `update_source_not` search parameter.\n"}}},"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"},"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."}}}} ``` ## The InventoryItemWrite object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"InventoryItemWrite":{"allOf":[{"type":"object","required":["name","code"]},{"$ref":"#/components/schemas/InventoryItemFields"}]},"InventoryItemFields":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Product's unique SKU. This is how Order Desk matches an order line to an inventory\nrecord, so it must match the code that your orders arrive with.\n"},"price":{"type":"number","format":"double"},"cost":{"type":"number","format":"double","description":"Item cost in decimal format."},"weight":{"type":"number","format":"double","description":"The shipping weight of the item."},"stock":{"type":"integer","description":"The number of available units."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of special information about the inventory item. Used by some\nintegrations.\n"},"manufacturer_sku":{"type":"string","description":"The SKU used by the manufacturer. This can be used as `print_sku`."},"location":{"type":"string","description":"Warehouse or fulfillment method responsible for the item."},"update_source":{"type":"string","description":"The name of the last system to update the item's details. Setting this allows those\nupdates to be excluded later using the `update_source_not` search parameter.\n"}}},"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"}}}} ``` ## The InventoryItemBatchWrite object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"InventoryItemBatchWrite":{"allOf":[{"type":"object","required":["id"],"properties":{"id":{"type":"integer","description":"Each inventory item must include an `id` field so the correct record can be\nproperly updated.\n"}}},{"$ref":"#/components/schemas/InventoryItemFields"}]},"InventoryItemFields":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Product's unique SKU. This is how Order Desk matches an order line to an inventory\nrecord, so it must match the code that your orders arrive with.\n"},"price":{"type":"number","format":"double"},"cost":{"type":"number","format":"double","description":"Item cost in decimal format."},"weight":{"type":"number","format":"double","description":"The shipping weight of the item."},"stock":{"type":"integer","description":"The number of available units."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of special information about the inventory item. Used by some\nintegrations.\n"},"manufacturer_sku":{"type":"string","description":"The SKU used by the manufacturer. This can be used as `print_sku`."},"location":{"type":"string","description":"Warehouse or fulfillment method responsible for the item."},"update_source":{"type":"string","description":"The name of the last system to update the item's details. Setting this allows those\nupdates to be excluded later using the `update_source_not` search parameter.\n"}}},"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"}}}} ``` ## The MoveOrdersRequest object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"MoveOrdersRequest":{"type":"object","required":["order_id_list"],"properties":{"order_id_list":{"type":"array","minItems":1,"description":"An array of Order Desk's internal order IDs.","items":{"type":"integer"}},"destination_folder_id":{"type":"integer","description":"The folder ID to which the orders should be moved."},"destination_folder_name":{"type":"string","description":"The name of the folder to which the orders should be moved. It must match exactly.\n"}}}}}} ``` ## The StoreSettings object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"StoreSettings":{"type":"object","readOnly":true,"description":"The store's configuration as set in the Order Desk interface. These settings are\nread-only through the API. New settings are added over time, so this list should be\ntreated as indicative rather than exhaustive.\n","additionalProperties":true,"properties":{"app_version":{"type":"string","description":"The Order Desk application version this store runs on."},"locale_code":{"type":"string","description":"Locale used for formatting, such as `en_US`."},"timezone":{"type":"string","description":"The store's timezone. The `_local` date filters are relative to this."},"store_country":{"type":"string","description":"Two-letter country code for the store."},"store_email":{"type":"string","description":"Address customer-facing mail is sent from."},"admin_email":{"type":"string","description":"Address store notifications are sent to."},"normalize_capitalization":{"type":"string","description":"Whether addresses are re-capitalized on import. `1` or `0`."},"normalize_phone_numbers":{"type":"string","description":"Whether phone numbers are reformatted on import. `1` or `0`."},"date_format":{"type":"string","description":"PHP date format used for full dates in the interface."},"short_date_format":{"type":"string","description":"PHP date format used for dates without a time."},"report_frequency":{"type":"string","description":"How often summary reports are sent."},"dashboard_report_type":{"type":"string","description":"Period the dashboard reports on, such as `daily`."},"store_url":{"type":"string","description":"The public URL of the storefront."},"custom_css":{"type":"string","description":"Custom CSS applied to the Order Desk interface."},"security_po_box_warn":{"type":"string","description":"Whether to flag orders shipping to a PO box."},"security_different_address_warn":{"type":"string","description":"Whether to flag orders whose shipping and customer addresses differ."},"security_different_country_warn":{"type":"string","description":"Whether to flag orders shipping to a different country."},"country_name_format":{"type":"string","description":"Whether countries render as codes or full names."},"all_orders_name":{"type":"string","description":"Display name for the all orders view."},"api_key":{"type":"string","description":"The store's API key. The whole response should be treated as sensitive."},"smtp_port":{"type":"string","description":"SMTP port, when outbound mail is configured."},"smtp_host":{"type":"string","description":"SMTP host, when outbound mail is configured."},"smtp_username":{"type":"string","description":"SMTP username, when outbound mail is configured."},"smtp_password":{"type":"string","description":"SMTP password, when outbound mail is configured."},"smtp_encryption":{"type":"string","description":"SMTP encryption mode, when outbound mail is configured."},"smtp_headers":{"type":"string","description":"Extra headers added to outbound mail."},"auto_update_stock_count":{"type":"string","description":"Whether incoming orders decrement inventory automatically."},"auto_create_inventory_items":{"type":"string","description":"Whether unknown SKUs create inventory records automatically."},"orders_per_page":{"type":"integer","description":"How many orders the interface shows per page."},"security_quantity_warn":{"type":"integer","description":"Quantity above which an order is flagged for review. `0` disables this check.\n"},"limit_address_field_char_length":{"type":"integer","description":"Maximum characters per address field. `0` means there is no limit."},"normalizeCapitalization":{"type":"integer","description":"Legacy duplicate of the `normalize_capitalization` setting."},"all_orders_column_view":{"type":"array","description":"Columns shown in the all orders view.","items":{"type":"object","additionalProperties":true}},"shipping_methods":{"type":"array","description":"Shipping methods configured for this store.","items":{"type":"object","additionalProperties":true}},"default_checkout_data_fields":{"type":"array","description":"Checkout data fields created on every new order.","items":{"type":"object","additionalProperties":true}}}}}}} ``` ## The Store object ```json {"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"components":{"schemas":{"Store":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"settings":{"$ref":"#/components/schemas/StoreSettings"},"folders":{"type":"object","additionalProperties":{"type":"string"},"description":"The store's folders, keyed by folder ID. These IDs are used by the `folder_id` field\nthroughout the API.\n"}}},"StoreSettings":{"type":"object","readOnly":true,"description":"The store's configuration as set in the Order Desk interface. These settings are\nread-only through the API. New settings are added over time, so this list should be\ntreated as indicative rather than exhaustive.\n","additionalProperties":true,"properties":{"app_version":{"type":"string","description":"The Order Desk application version this store runs on."},"locale_code":{"type":"string","description":"Locale used for formatting, such as `en_US`."},"timezone":{"type":"string","description":"The store's timezone. The `_local` date filters are relative to this."},"store_country":{"type":"string","description":"Two-letter country code for the store."},"store_email":{"type":"string","description":"Address customer-facing mail is sent from."},"admin_email":{"type":"string","description":"Address store notifications are sent to."},"normalize_capitalization":{"type":"string","description":"Whether addresses are re-capitalized on import. `1` or `0`."},"normalize_phone_numbers":{"type":"string","description":"Whether phone numbers are reformatted on import. `1` or `0`."},"date_format":{"type":"string","description":"PHP date format used for full dates in the interface."},"short_date_format":{"type":"string","description":"PHP date format used for dates without a time."},"report_frequency":{"type":"string","description":"How often summary reports are sent."},"dashboard_report_type":{"type":"string","description":"Period the dashboard reports on, such as `daily`."},"store_url":{"type":"string","description":"The public URL of the storefront."},"custom_css":{"type":"string","description":"Custom CSS applied to the Order Desk interface."},"security_po_box_warn":{"type":"string","description":"Whether to flag orders shipping to a PO box."},"security_different_address_warn":{"type":"string","description":"Whether to flag orders whose shipping and customer addresses differ."},"security_different_country_warn":{"type":"string","description":"Whether to flag orders shipping to a different country."},"country_name_format":{"type":"string","description":"Whether countries render as codes or full names."},"all_orders_name":{"type":"string","description":"Display name for the all orders view."},"api_key":{"type":"string","description":"The store's API key. The whole response should be treated as sensitive."},"smtp_port":{"type":"string","description":"SMTP port, when outbound mail is configured."},"smtp_host":{"type":"string","description":"SMTP host, when outbound mail is configured."},"smtp_username":{"type":"string","description":"SMTP username, when outbound mail is configured."},"smtp_password":{"type":"string","description":"SMTP password, when outbound mail is configured."},"smtp_encryption":{"type":"string","description":"SMTP encryption mode, when outbound mail is configured."},"smtp_headers":{"type":"string","description":"Extra headers added to outbound mail."},"auto_update_stock_count":{"type":"string","description":"Whether incoming orders decrement inventory automatically."},"auto_create_inventory_items":{"type":"string","description":"Whether unknown SKUs create inventory records automatically."},"orders_per_page":{"type":"integer","description":"How many orders the interface shows per page."},"security_quantity_warn":{"type":"integer","description":"Quantity above which an order is flagged for review. `0` disables this check.\n"},"limit_address_field_char_length":{"type":"integer","description":"Maximum characters per address field. `0` means there is no limit."},"normalizeCapitalization":{"type":"integer","description":"Legacy duplicate of the `normalize_capitalization` setting."},"all_orders_column_view":{"type":"array","description":"Columns shown in the all orders view.","items":{"type":"object","additionalProperties":true}},"shipping_methods":{"type":"array","description":"Shipping methods configured for this store.","items":{"type":"object","additionalProperties":true}},"default_checkout_data_fields":{"type":"array","description":"Checkout data fields created on every new order.","items":{"type":"object","additionalProperties":true}}}}}}} ``` --- # 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/models.md?ask=&goal= ``` `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.