🔒
Requires write_order access scope. More access scope

The Update Order Details API allows users to update the details of an existing order. This includes fields like the order note, tags, buyer marketing preferences, and shipping address.

This API is especially useful for:

Updating order details post-creation.
Modifying customer shipping information.
Ensuring marketing preferences align with customer consent.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`order_id`	string	Yes	Unique order identifier	`"order_12345"`

Body Parameters

Parameter	Type	Required	Description	Example
`order`	object	Yes	Contains order update details
`order.note`	string	No	Additional order information	`"Gift message: Happy Birthday!"`
`order.tags`	object	No	Order categorization labels
`order.tags.values`	array of strings	No	Tag values	`["urgent", "gift"]`
`order.buyer_accepts_marketing`	boolean	No	Marketing consent status	`true`
`order.shipping_address`	object	No	Updated delivery information
`order.shipping_address.last_name`	string	No	Recipient's surname	`"Smith"`
`order.shipping_address.first_name`	string	No	Recipient's given name	`"Jane"`
`order.shipping_address.phone`	string	No	Contact number	`"5559876543"`
`order.shipping_address.email`	string	No	Contact email	`"customer@example.com"`
`order.shipping_address.country`	string	No	Delivery country	`"Canada"`
`order.shipping_address.country_code`	string	No	ISO country code	`"CA"`
`order.shipping_address.province`	string	No	State/province	`"Ontario"`
`order.shipping_address.province_code`	string	No	ISO province code	`"ON"`
`order.shipping_address.area`	string	No	Regional designation	`"Downtown"`
`order.shipping_address.city`	string	No	City name	`"Toronto"`
`order.shipping_address.address`	string	No	Primary street address	`"200 King St"`
`order.shipping_address.address1`	string	No	Secondary address line	`"Suite 500"`
`order.shipping_address.company`	string	No	Business name	`"Tech Solutions Inc"`
`order.shipping_address.zip`	string	No	Postal code	`"M5H 3T4"`
`order.shipping_address.phone_area_code`	string	No	Telephone area code	`"1"`
`order.shipping_line`	object	No	Order's shipping line information Note: Only can be modified when order's status is `opened`
`order.shipping_line.shipping_name`	string	Yes	Name of the shipping method	`"Standard Shipping"`
`order.shipping_line.shipping_desc`	string	No	Description of the shipping method	`"3-5 business days delivery"`
`order.shipping_line.shipping_price`	string	Yes	Price of the shipping method, as a numeric string	`"10.00"`
`order.shipping_line.delivery_method`	string	Yes	Delivery method: 1-Express delivery, 2-Local delivery, 3-Store pickup.	`1`
`order.shipping_line.extra_info`	string	Yes	exta info	`"message"`
`order.additional_prices`	array of object	No	additional prices Note: 1. Only can be modified when order's status is `opened` 2.To remove additional pricing, use the clear_additional_prices 3.Changes affect store admin pricing only; checkout page prices remain unchanged
`order.additional_prices.name`	string	Yes	additional prices
`order.additional_prices.price`	string	Yes	additional prices price
`order.additional_prices.biz_id`	string	No	additional prices biz_id
`order.additional_prices.fee_title`	string	Yes	additional prices fee_title
`order.clear_additional_prices`	bool	No	Used to remove additional pricing

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"success"`	Status code of the API response
`message`	string	`"Order retrieved successfully"`	Descriptive message about the response
`data.order`	object	-	Complete order object containing all details

Order Object

Parameter	Type	Example	Description
`id`	string	`"ord_123"`	Order ID
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation time
`updated_at`	string	`"2023-01-01T00:00:00Z"`	Update time
`note`	string	`"Gift note"`	Merchant note
`number`	string	`"#1001"`	Order number
`total_price`	string	`"100.00"`	Total price
`sub_total`	string	`"90.00"`	The sum of the prices for all line items in the order. If order.config.product_tax_included is true, the amount includes total_tax (excluding shipping_tax_total); otherwise, it excludes tax. Formula: sub_total = sum(line_item.price * line_item.quantity).
`currency`	string	`"USD"`	Currency
`financial_status`	string	`"paid"`	Payment status
`status`	string	`"fulfilled"`	Order status
`cancelled_at`	string		Cancel time
`cancel_reason`	string		Cancel reason
`payment_method`	string		Payment method
`fulfillment_status`	string	`"fulfilled"`	Fulfillment status
`customer_deleted_at`	string		Customer deletion time
`deleted_at`	string		Order deletion time
`placed_at`	string	`"2023-01-01T00:00:00Z"`	Payment time
`tags`	string	`"vip"`	Order tags
`buyer_accepts_marketing`	boolean	`true`	Marketing consent
`code_discount_total`	string	`"10.00"`	Code discounts
`customer_note`	string	`"Handle with care"`	Customer note
`total_discount`	string	`"10.00"`	Total discounts
`total_tax`	string	`"5.00"`	Product taxes
`total_shipping`	string	`"5.00"`	Shipping cost
`line_items`	array[object]		Line items
`payment_line`	object		Payment line
`shipping_line`	object		Shipping line
`billing_address`	object		Billing address
`shipping_address`	object		Shipping address
`fulfillments`	array[object]		Fulfillments
`customer`	object		Customer info
`refer_info`	string	`"google"`	Referral info
`sales_platform`	string	`"web"`	Sales platform
`total_refund_price`	string	`"0.00"`	Refunded amount
`primary_market_price`	object		Market pricing
`total_tip_received`	string	`"5.00"`	Tips received
`discount_applications`	string	`"promo10"`	Discount details
`refund_status`	string	`"none"`	Refund status
`email_status`	string	`"sent"`	Email status
`recovery_status`	string	`"success"`	Recovery status
`total_paid`	string	`"100.00"`	Total paid amount
`payment_lines`	array[object]		Payment lines
`gift_card_total`	string	`"0.00"`	Gift card amount
`logistics_code`	string	`"DHL123"`	Logistics code
`shipping_tax_total`	string	`"1.00"`	Shipping tax
`location_line`	object		Location info
`additional_total`	string	`"0.00"`	Additional fees
`additional_prices`	array[object]		Fee details
`config`	object		Configuration
`checkout_url`	string	`"https://..."`	Checkout URL
`duty_total`	string	`"0.00"`	Duty fees

Fulfillment Object

Parameter	Type	Example	Description
`id`	string	`"ful_12345"`	Fulfillment/shipment ID
`order_id`	string	`"ord_123"`	Associated order ID
`status`	string	`"shipped"`	Current fulfillment status
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation timestamp
`updated_at`	string	`"2023-01-02T00:00:00Z"`	Last update timestamp
`tracking_company`	string	`"UPS"`	Shipping carrier name
`tracking_number`	string	`"1Z12345E"`	Package tracking number
`tracking_company_code`	string	`"ups"`	Carrier system code
`line_items`	array[object]	-	Shipped items
`tracking_url`	string	`"https://ups.com/track"`	Tracking page URL
`phone_number`	string	`"+1234567890"`	Contact phone for shipment

Line Items Object

Parameter	Type	Example	Description
`id`	string	`"li_12345"`	Unique line item identifier
`product_id`	string	`"prod_123"`	Associated product ID
`product_title`	string	`"Premium T-Shirt"`	Name of purchased product
`variant_id`	string	`"var_456"`	Product variant ID
`variant_title`	string	`"Blue / Medium"`	Variant description
`quantity`	uint32	`2`	Quantity purchased
`note`	string	`"Gift wrapping requested"`	Product-specific note
`image`	object	-	Product image details
`price`	string	`"29.99"`	Unit price
`compare_at_price`	string	`"39.99"`	Original/compare price
`total_price`	string	`"59.98"`	Total price (price × quantity)
`fulfillment_status`	string	`"fulfilled"`	Fulfillment status
`sku`	string	`"TSHIRT-BL-M"`	Inventory tracking code
`weight`	string	`"0.5"`	Product weight
`weight_unit`	string	`"kg"`	Weight measurement unit
`vendor`	string	`"Fashion Co"`	Product supplier
`product_url`	string	`"https://..."`	Product page URL
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation time
`updated_at`	string	`"2023-01-01T00:00:00Z"`	Update time
`options`	array[object]	-	Variant options
`product_slug`	string	`"premium-t-shirt"`	Product URL slug
`taxable`	boolean	`true`	Whether item is taxable
`requires_shipping`	boolean	`true`	Whether requires shipping
`spu`	string	`"SPU123"`	Standard Product Unit
`product_tags`	string	`"summer,sale"`	Product tags
`refund_quantity_total`	uint32	`0`	Total refunded quantity
`ship_quantity`	uint32	`2`	Shipped quantity
`custom`	boolean	`false`	Custom product flag
`trunk_price`	string	`"0.00"`	Trunk price
`discount_applications`	string	`"promo10"`	Applied discounts
`tax_price`	string	`"2.99"`	Tax amount
`duty_price`	string	`"0.00"`	Duty cost

Image Object

Parameter	Type	Example	Description
`src`	string	`"https://..."`	Image URL
`width`	int32	`800`	Image width
`height`	int32	`600`	Image height
`alt`	string	`"Blue T-Shirt"`	Alt text

Options Object

Parameter	Type	Example	Description
`name`	string	`"Color"`	Option name
`value`	string	`"Blue"`	Selected value

Payment Line Object

Parameter	Type	Example	Description
`payment_name`	string	`"VISA-1234"`	Display name of payment method
`payment_channel`	string	`"stripe"`	Payment service provider
`payment_method`	string		Specific payment type
`credit_card_number`	string	`""`	Masked card digits
`trans_channel`	string	`	Transaction channel
`trans_method`	string		Transaction method
`transaction_no`	string	`"txn_789012"`	Unique transaction ID

Shipping Line Object

Parameter	Type	Example	Description
`id`	string	`"ship_12345"`	Unique identifier for the shipping method
`name`	string	`"Express Delivery"`	Display name of the shipping method
`desc`	string	`"2-3 business days"`	Description of shipping terms

Billing Address/ Shipping Address Object

Parameter	Type	Example	Description
`first_name`	string	`"John"`	First name of the billing contact
`last_name`	string	`"Doe"`	Last name of the billing contact
`address`	string	`"1 Rue des Carrieres"`	Primary street address
`address1`	string	`"Suite 1234"`	Additional address line
`phone`	string	`"+861231231234"`	Contact phone number
`city`	string	`"SAN JOSE"`	City name
`zip`	string	`"87036"`	Postal/ZIP code
`province`	string	`"New Mexico"`	State/Province name
`country`	string	`"United States"`	Country name
`company`	string	`"ABC Limited"`	Company name
`latitude`	string	`"22.54"`	Geographic latitude
`longitude`	string	`"114.06"`	Geographic longitude
`name`	string	`"John Doe"`	Full name of billing contact
`country_code`	string	`"US"`	2-letter country code
`province_code`	string	`"NM"`	State/Province code
`phone_area_code`	string	`"+86"`	Phone country code
`email`	string	`"john.doe@example.com"`	Email address
`area`	string	`"Bay area"`	Regional area designation

Primary Market Price Object

Parameter	Type	Example	Description
`compare_at_price`	string	`"129.99"`	Original/list price in primary currency
`price`	string	`"99.99"`	Current selling price in primary currency
`total_price`	string	`"199.98"`	Extended price (price × quantity)
`actual_rate`	string	`"1.12"`	Currency conversion rate applied

Customer Object

Parameter	Type	Example	Description
`id`	string	`"cust_12345"`	Unique customer identifier
`email`	string	`"customer@example.com"`	Customer's email address
`first_name`	string	`"John"`	Customer's first name
`last_name`	string	`"Doe"`	Customer's last name
`phone`	string	`"+1234567890"`	Customer's phone number
`created_at`	string	`"2023-01-01T00:00:00Z"`	Customer account creation date
`updated_at`	string	`"2023-06-01T00:00:00Z"`	Last customer profile update
`order_count`	int32	`5`	Total orders placed by customer
`total_spent`	string	`"499.95"`	Lifetime spending amount

Location Line Object

Parameter	Type	Example	Description
`id`	string	`"1234567890"`	Unique identifier for the location line.
`location_id`	string	`"Doe"`	Identifier for the associated location.
`location_name`	string	`"123 Main St"`	Name of the location, such as a store or warehouse.

Config Object

Parameter	Type	Example	Description
`product_tax_included`	boolean	`true`	Tax inclusion flag
`requires_shipping`	boolean	`true`	Shipping requirement
`checkout_url`	string	`"https://store.com/checkout"`	Order checkout URL

Additional Charge Object

Parameter	Type	Example	Description
`name`	string	`"Gift Wrapping"`	System identifier for charge type
`price`	string	`"5.99"`	Charge amount in order currency
`biz_id`	string	`"gift_wrap_1"`	Business logic identifier
`fee_title`	string	`"Special Packaging"`	Customer-facing charge description

Market Setting Object

Parameter	Type	Example	Description
`primary_market_lang`	string	`"en"`	Primary market language code
`market_lang`	string	`"en-US"`	Localized market language
`market_id`	string		Unique market identifier
`market_currency`	string	`"USD"`	Market currency code
`market_currency_symbol`	object	-	Currency symbol details
`market_base_id`	string	`"base_us"`	Base market ID
`market_base_currency`	string	`"USD"`	Base market currency
`market_base_currency_symbol`	object	-	Base currency symbol
`primary_market_id`	string	`"primary_us"`	Primary market ID
`primary_market_currency`	string	`"USD"`	Primary currency code
`primary_market_currency_symbol`	object	-	Primary currency symbol
`market_price_setting`	object	-	Price calculation settings
`market_country`	string	`"US"`	2-letter country code

Currency Symbol Objects

Parameter	Type	Example	Description
`code`	string	`"USD"`	ISO currency code
`val`	string	`"$"`	Currency symbol
`left`	string	`"$"`	Left-side display
`right`	string	`""`	Right-side display

Market Price Setting Object

Parameter	Type	Example	Description
`local_currency_enabled`	boolean	`true`	Local currency active
`custom_rate_enabled`	boolean	`false`	Custom exchange rate
`custom_rate`	float	`1.0`	Manual exchange rate
`rate`	float	`1.12`	Current exchange rate
`back_rate`	float	`0.89`	Reverse exchange rate
`actual_rate`	float	`1.1198`	Precise exchange rate
`base_to_rate`	float	`1.0`	Base to local rate
`local_to_rate`	float	`1.0`	Local to base rate
`adjust`	int32	`0`	Price adjustment %
`price_round_enabled`	boolean	`true`	Price rounding active

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message