🔒
Requires write_order access scope. More access scope

The Cancel Order API allows canceling an order by specifying its unique ID and an optional cancel reason. Once canceled, the order's status will be updated to cancelled.

This API is especially useful for:

Managing order cancellations effectively.
Logging cancel reasons for reporting purposes.
Synchronizing order statuses across platforms.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`order_id`	string	Yes	Unique identifier of the order to cancel	`"order_78901"`

Body Parameters

Parameter	Type	Required	Description	Example
`reason`	string	Yes	Explanation for cancellation	`"Customer requested cancellation"`

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"`	Subtotal
`currency`	string	`"USD"`	Currency
`financial_status`	string	`"paid"`	Payment status
`status`	string	`"cancelled"`	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