Update an Order

Replaces an order with the record supplied.

You must pass the entire order, as any parts left out will be updated as blank. Retrieve the current order first, modify the fields you need, and submit the complete record.

Order items may be passed in as well. If an id field is passed with the order item it will be updated, otherwise it will be added. Any item that is omitted is removed from the order.

Shipments may not be modified with this process. Use the shipment operations instead.

Omitting folder_id leaves the order in its current folder rather than clearing the field.

Updating an order adds an entry to its history. Changing folder_id adds a further entry and triggers any rules assigned to the destination folder.

put

Authorizations

ORDERDESK-API-KEYstringRequired

Your API key, found under Store Settings on the API tab. This should be kept server-side.

ORDERDESK-STORE-IDstringRequired

Your store ID, found under Store Settings on the API tab.

Path parameters

order_idintegerRequired

Order Desk's internal order ID. This is not your source_id.

Example: 736745

Body

Order fields common to both reads and writes.

cc_numberstringOptional

Obfuscated credit card number. Enter only the last four digits. Returned as cc_number_masked.

Example: 4242

source_idstringOptional

Your original order ID. If blank, Order Desk's internal ID will be used.

Example: 6487172454

source_namestringOptional

Name of the order source, cart, or marketplace. If the source is not recognized or is not entered, this defaults to Order Desk.

Default: Order DeskExample: FoxyCart

emailstring · emailOptionalExample: avery.chen@example.com

shipping_methodstringOptional

Name of the selected shipping method.

Example: UPS Ground

shipping_totalnumber · doubleOptionalExample: 9.5

handling_totalnumber · doubleOptionalExample: 0.5

tax_totalnumber · doubleOptionalExample: 2.15

cc_expstringOptional

Credit card expiration in MM/YYYY format.

Example: 02/2026Pattern: ^\d{2}/\d{4}$

processor_responsestringOptional

Gateway transaction ID in <gateway_name>: <transaction_id> format.

Example: Authorize.net Transaction ID: 2221864944

payment_typestringOptional

Visa, MasterCard, PayPal, etc.

Example: Visa

payment_statusstring · enumOptional

Current payment status for the order. Defaults to Captured.

Default: CapturedPossible values:

processor_balancenumber · doubleOptional

Amount charged at the processor. This is decremented when refunds are made, and defaults to order_total.

Example: 21.17

refund_totalnumber · doubleOptional

Amount refunded on the order from within Order Desk.

Example: 0

customer_idstringOptional

Customer ID from the originating system.

Example: 5487542

ip_addressstringOptional

Customer's IP address.

fulfillment_namestringOptional

Once the order has been sent for fulfillment, the fulfillment method name is entered here.

fulfillment_idstringOptional

Internal ID of the fulfillment service, when available.

folder_idintegerOptional

ID of the folder containing the order. New orders default to the first folder when this is omitted. Omitting it on an update leaves the order in its current folder. See the Folders guide.

Example: 21654

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

date_updatedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

Other propertiesanyOptional

first_namestringOptionalExample: Avery

last_namestringOptionalExample: Chen

companystringOptional

address1stringOptionalExample: 1200 Campus Drive

address2stringOptional

address3stringOptional

Street address 3. Not available for customer addresses.

address4stringOptional

Street address 3. Not available for customer addresses.

citystringOptionalExample: Springfield

statestringOptional

State or region.

Example: IL

postal_codestringOptional

ZIP or postal code.

Example: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptionalExample: 555-555-5555

first_namestringOptionalExample: Avery

last_namestringOptionalExample: Chen

companystringOptional

address1stringOptionalExample: 1200 Campus Drive

address2stringOptional

address3stringOptional

Street address 3. Not available for customer addresses.

address4stringOptional

Street address 3. Not available for customer addresses.

citystringOptionalExample: Springfield

statestringOptional

State or region.

Example: IL

postal_codestringOptional

ZIP or postal code.

Example: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptionalExample: 555-555-5555

titlestringOptional

Return address title.

Example: Acme

namestringOptional

Shipping name.

Example: Doug Jones

companystringOptionalExample: Acme Manufacturing

address1stringOptionalExample: 817 E Maple Ln

address2stringOptional

citystringOptionalExample: Knoxville

statestringOptional

State or region.

Example: IL

postal_codestringOptionalExample: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptional

namestringOptionalExample: Spring Sale

codestringOptional

Code used for the discount. Optional.

Example: SPRING10

amountnumber · doubleOptional

The discount amount. Discounts should be stored as positive numbers.

Example: 5

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

usernamestringOptional

Name of the person who wrote the note.

Example: Doug Jones

contentstring · max: 1800OptionalExample: Customer asked us to leave this by the back door.

idintegerOptional

If an id field is passed the item will be updated. Otherwise it will be added.

Example: 1670028

namestringOptionalExample: ODU Campus Hoodie

pricenumber · doubleOptionalDefault: 0Example: 19

quantityintegerOptionalDefault: 1Example: 2

weightnumber · doubleOptionalExample: 1.2

codestringOptional

Item SKU or product code.

Example: ODU-HOOD-NVY-L

delivery_typestring · enumOptional

Available options are ship, noship, download, or future. Defaults to ship.

Default: shipPossible values:

category_codestringOptional

Further details about the type of item. Freeform text.

Example: Apparel

fulfillment_methodstringOptional

Fulfillment method responsible for this item, when one applies.

Other propertiesanyOptional

Responses

200

The order as stored after the update.

application/json

statusstring · enumRequired

Either success or error.

Possible values:

messagestringOptional

Describes the result. Always present when an error occurs.

execution_timestringOptional

Time taken to process the request.

Example: 0.1524 seconds

idstringRead-onlyOptional

Order Desk's internal ID number. Returned as a string, even though it is always numeric. Read-only.

Example: 925086

source_idstringOptional

Your original order ID. If blank, Order Desk's internal ID will be used.

Example: 6487172454

source_namestringOptional

Name of the order source, cart, or marketplace. If the source is not recognized or is not entered, this defaults to Order Desk.

Default: Order DeskExample: FoxyCart

emailstring · emailOptionalExample: avery.chen@example.com

shipping_methodstringOptional

Name of the selected shipping method.

Example: UPS Ground

shipping_totalnumber · doubleOptionalExample: 9.5

handling_totalnumber · doubleOptionalExample: 0.5

tax_totalnumber · doubleOptionalExample: 2.15

cc_expstringOptional

Credit card expiration in MM/YYYY format.

Example: 02/2026Pattern: ^\d{2}/\d{4}$

processor_responsestringOptional

Gateway transaction ID in <gateway_name>: <transaction_id> format.

Example: Authorize.net Transaction ID: 2221864944

payment_typestringOptional

Visa, MasterCard, PayPal, etc.

Example: Visa

payment_statusstring · enumOptional

Current payment status for the order. Defaults to Captured.

Default: CapturedPossible values:

processor_balancenumber · doubleOptional

Amount charged at the processor. This is decremented when refunds are made, and defaults to order_total.

Example: 21.17

refund_totalnumber · doubleOptional

Amount refunded on the order from within Order Desk.

Example: 0

customer_idstringOptional

Customer ID from the originating system.

Example: 5487542

ip_addressstringOptional

Customer's IP address.

fulfillment_namestringOptional

Once the order has been sent for fulfillment, the fulfillment method name is entered here.

fulfillment_idstringOptional

Internal ID of the fulfillment service, when available.

folder_idintegerOptional

ID of the folder containing the order. New orders default to the first folder when this is omitted. Omitting it on an update leaves the order in its current folder. See the Folders guide.

Example: 21654

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

date_updatedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

Other propertiesanyOptional

first_namestringOptionalExample: Avery

last_namestringOptionalExample: Chen

companystringOptional

address1stringOptionalExample: 1200 Campus Drive

address2stringOptional

address3stringOptional

Street address 3. Not available for customer addresses.

address4stringOptional

Street address 3. Not available for customer addresses.

citystringOptionalExample: Springfield

statestringOptional

State or region.

Example: IL

postal_codestringOptional

ZIP or postal code.

Example: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptionalExample: 555-555-5555

first_namestringOptionalExample: Avery

last_namestringOptionalExample: Chen

companystringOptional

address1stringOptionalExample: 1200 Campus Drive

address2stringOptional

address3stringOptional

Street address 3. Not available for customer addresses.

address4stringOptional

Street address 3. Not available for customer addresses.

citystringOptionalExample: Springfield

statestringOptional

State or region.

Example: IL

postal_codestringOptional

ZIP or postal code.

Example: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptionalExample: 555-555-5555

titlestringOptional

Return address title.

Example: Acme

namestringOptional

Shipping name.

Example: Doug Jones

companystringOptionalExample: Acme Manufacturing

address1stringOptionalExample: 817 E Maple Ln

address2stringOptional

citystringOptionalExample: Knoxville

statestringOptional

State or region.

Example: IL

postal_codestringOptionalExample: 62704

countrystringOptional

Country code or full country name.

Example: US

phonestringOptional

namestringOptionalExample: Spring Sale

codestringOptional

Code used for the discount. Optional.

Example: SPRING10

amountnumber · doubleOptional

The discount amount. Discounts should be stored as positive numbers.

Example: 5

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

usernamestringOptional

Name of the person who wrote the note.

Example: Doug Jones

contentstring · max: 1800OptionalExample: Customer asked us to leave this by the back door.

cc_number_maskedstringRead-onlyOptional

Obfuscated credit card number. This is the field returned in responses. Use cc_number when writing.

Example: xxxxxxxxxxxx4242

quantity_totalintegerRead-onlyOptional

Total number of all items in the order. Read-only.

Example: 3

weight_totalnumber · doubleRead-onlyOptional

Total weight of all items in the order. Read-only.

Example: 3.6

product_totalnumber · doubleRead-onlyOptional

Total price of all items in the order. Read-only.

Example: 57

discount_totalnumber · doubleRead-onlyOptional

Total value of all discounts, stored as a positive number. Read-only.

Example: 5

order_totalnumber · doubleRead-onlyOptional

Calculated price of the entire order. Read-only.

Example: 63.65

email_countstringRead-onlyOptional

Number of orders matching this email address. Returned as a string, even though it is always numeric. Read-only.

Example: 3

previous_folder_idstringRead-onlyOptional

The folder the order was in before its most recent move. Returned as a string. Read-only.

Example: 21654

tag_colorstringRead-onlyOptional

Not in use.

tag_namestringRead-onlyOptional

Not in use.

idintegerRead-onlyOptional

Order Desk's internal ID number for the order item. Read-only.

Example: 1670028

namestringOptionalExample: ODU Campus Hoodie

pricenumber · doubleOptionalDefault: 0Example: 19

quantityintegerOptionalDefault: 1Example: 2

weightnumber · doubleOptionalExample: 1.2

codestringOptional

Item SKU or product code.

Example: ODU-HOOD-NVY-L

delivery_typestring · enumOptional

Available options are ship, noship, download, or future. Defaults to ship.

Default: shipPossible values:

category_codestringOptional

Further details about the type of item. Freeform text.

Example: Apparel

fulfillment_methodstringOptional

Fulfillment method responsible for this item, when one applies.

Other propertiesanyOptional

idintegerRead-onlyOptionalExample: 44821

order_idintegerRead-onlyOptionalExample: 925086

store_idintegerRead-onlyOptionalExample: 11

tracking_numberstringOptional

Carrier-assigned tracking number. Use n/a if no tracking number is applicable.

Example: 1Z999AA10123456784

carrier_codestringOptional

Carrier code such as USPS or FedEx, when available.

Example: UPS

shipment_methodstringOptional

Shipping service name, such as First Class International.

Example: UPS Ground

weightnumber · doubleOptional

Final shipment weight.

Example: 2.4

costnumber · doubleOptional

Your cost to send the shipment.

Example: 9.5

statusstringOptional

Current shipment status, used by the EasyPost webhook.

tracking_urlstringOptional

If omitted, Order Desk attempts to determine it from the tracking number format and carrier code.

label_formatstringRead-onlyOptional

Format of the stored label, when one exists.

label_imagestringRead-onlyOptional

Stored shipping label, when one exists.

print_statusstringRead-onlyOptional

Whether the label has been printed.

cart_shipment_idstringRead-onlyOptional

Shipment ID in the originating cart, when known.

label_shipment_idstringRead-onlyOptional

Shipment ID at the label provider, when known.

Other propertiesanyOptional

date_shippedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

source_namestringOptional

What wrote this entry.

Example: API

notestringOptionalExample: Order Updated

date_addedstringOptional

Date and time in YYYY-MM-DD HH:MM:SS format. UTC unless otherwise stated.

Example: 2019-01-15 12:12:10

400

The update was rejected.

application/json

401

Authentication failed. See the Authentication guide, and note that an invalid store ID blocks your store rather than simply failing the request.

application/json

404

No record matches that ID in your store.

application/json

413

An item's metadata or variation_list is over the limit. See the Errors guide for the sizes.

application/json

429

You are sending too fast. Wait X-Retry-After seconds. See the Rate Limits guide.

application/json

default

The request could not be completed.

application/json

put/orders/{order_id}

curl "https://app.orderdesk.me/api/v2/orders/736745" \
  -X PUT \
  -H "ORDERDESK-STORE-ID: your-store-id" \
  -H "ORDERDESK-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"source_id": "6487172454", "source_name": "FoxyCart", "email": "avery.chen@example.com", "shipping_method": "UPS 2nd Day Air", "shipping_total": 14.5, "tax_total": 2.15, "payment_status": "Captured", "folder_id": 21655, "shipping": {"first_name": "Avery", "last_name": "Chen", "address1": "1200 Campus Drive", "city": "Springfield", "state": "IL", "postal_code": "62704", "country": "US", "phone": "555-555-5555"}, "order_items": [{"id": 1670028, "name": "ODU Campus Hoodie", "code": "ODU-HOOD-NVY-L", "price": 19, "quantity": 3, "weight": 1.2}]}'

{
  "status": "success",
  "message": "Order Updated.",
  "execution_time": "0.0208 seconds"
}

Last updated 9 days ago

Was this helpful?