put https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders/
Requires
write_orderaccess 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.
Note: The operation is scoped to a specific shop, identified by its unique order ID, ensuring the correct order is updated.
Request Parameters
Public Request Parameters
Path Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Unique identifier for the order. | 1965351157616135991222 |
Body Parameters
| Field | Type | Description | Example |
|---|---|---|---|
| note | string | Order's note. | Updated order note |
| tags | string | Order tags, separated by commas. | tag1,tag2 |
| buyer_accepts_marketing | boolean | Whether the customer accepts marketing. | true |
| shipping_address.first_name | string | First name of consignee. | John |
| shipping_address.last_name | string | Last name of consignee. | Doe |
| shipping_address.email | string | Email of consignee. | [email protected] |
| shipping_address.phone | string | Phone number of consignee. | +123456789 |
| shipping_address.country | string | Country name. | United States |
| shipping_address.country_code | string | ISO country code. | US |
| shipping_address.province | string | Province or state name. | California |
| shipping_address.province_code | string | Province code. | CA |
| shipping_address.city | string | City name. | Los Angeles |
| shipping_address.address1 | string | Primary address line. | 123 Main St |
| shipping_address.address2 | string | Secondary address line. | Apt 4B |
| shipping_address.zip | string | ZIP or postal code. | 90001 |
| shipping_address.company | string | Company name (optional). | ABC Corp |
| shipping_address.latitude | string | Latitude of the delivery address. | 34.0522 |
| shipping_address.longitude | string | Longitude of the delivery address. | -118.2437 |
Response Explanation
Public Response Parameters
Success Response
| Object | Fields | Type | Desc |
|---|---|---|---|
| Order | id | string | Unique identifier for the order. |
| number | string | Order number, intended to simplify merchant references. | |
| note | string | A custom note input by the merchant regarding the order. | |
| status | string | The current Order status | |
| financial_status | string | Indicates the payment status of the order | |
| fulfillment_status | string | Represents the shipping or fulfillment progress of the order | |
| email_status | string | The status of recall emails for the order.waiting means “pending to send”send means “sent” | |
| cancel_reason | string | Reason for order cancellation, if applicable. | |
| recovery_status | string | The recovery_status field tracks the progress of an order recall processwaiting means “Waiting to be recalled”sending means “Recall notification in progress”recalling means “Recall in progress)”failed means “Recall failed)”success means “Recall successful)” | |
| payment_method | string | The payment method used for the order (e.g., apple_pay, credit_card, online). | |
| string | @Deprecated. | ||
| discount_applications | string | Details of discounts | |
| customer_note | string | A note provided by the customer during checkout. | |
| string | @Deprecated. | ||
| buyer_accepts_marketing | bool | Indicates whether the customer has agreed to receive marketing promotions. | |
| currency | string | Currency code for the order | |
| total_price | string | The final price paid by the customer, including taxes, discounts, tips, additional fee and shipping fees. | |
| sub_total | string | 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). | |
| total_discount | string | Total amount of discounts applied to the order, including product, shipping, and payment discounts. | |
| total_tax | string | Total tax amount applied to the products in the order， excluding shipping tax. | |
| total_shipping | string | Total shipping fee for the order. | |
| code_discount_total | string | Total discount from discount codes applied to the order. | |
| string | @Deprecated.total Product discount, numeric string, for example: "9.99",includes code_discount_total | ||
| gift_card_total | string | Gift card discount amount, numeric string, for example: "9.99" | |
| total_refund_price | string | Total refund amount has been successfully processed, numeric string, for example: "9.99" | |
| string | @Deprecated.Total discount refunded, numeric string, for example: "9.99" | ||
| additional_total | string | Total amount of additional charges, numeric string, for example: "9.99" | |
| addtional_prices | array of object | the detail list of additional charges | |
| addtional_prices.name | string | Name of the additional charge. | |
| addtional_prices.price | string | Amount of the additional charge. | |
| string | @Deprecated. | ||
| shipping_tax_total | string | Total shipping tax amount of the order. | |
| customer_deleted_at | string | Timestamp indicating when the customer associated with the order was deleted. | |
| created_at | string | Timestamp indicating when the order was created. | |
| updated_at | string | Timestamp indicating when the order was updated. | |
| deleted_at | string | Timestamp indicating when the order was deleted. | |
| canceled_at | string | Timestamp indicating when the order was canceled. | |
| placed_at | string | Timestamp indicating when the order was paid. | |
| total_tip_received | string | Total amount of tips received for the order. | |
| tags | string | Custom tags added to the order by merchants or the system. | |
| string | @Deprecated. IP address of the customer who placed the order. | ||
| string | @Deprecated. URL of the last page visited by the customer before checkout. | ||
| total_paid | string | Total amount paid by the customer for the order. | |
| string | @Deprecated.Product source url | ||
| object | @Deprecated. Product source | ||
| string | @Deprecated. Product source | ||
| string | @Deprecated. Timestamp of the creation | ||
| object | @Deprecated. Last interaction source | ||
| string | @Deprecated. Interaction source data. | ||
| string | @Deprecated. Timestamp of the last interaction. | ||
| shipping_line | object | Information about the shipping plan selected for the order. | |
| shipping_line.name | string | Name of the shipping plan. | |
| customer | Customer | Customer details | |
| shipping_address | Address | Delivery address | |
| billing_address | Address | Billing address | |
| payment_line | PaymentLine | Payment details | |
| line_items | array of LineItem | List of purchased products | |
| fulfillments | array of Fulfillment | List of fulfillments | |
| logistics_code | string | Logistics code | |
| refer_info | string | Visit information | |
| config | OrderConfig | Order configuration information | |
| string | @Deprecated. Platform where the order was placed | ||
| checkout_url | string | The checkout page url for the order with storeDomain | |
| location_line | LocationLine | Merchant's warehouse address. | |
| invoice_url | string | The checkout page url for the order without storeDomain |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
errors | Array | [ "file number error"] | A list of errors encountered during the request processing. |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| ErrorCode | Description | Possible reasons |
|---|---|---|
| Record not found | ||
| 422 | StatusUnprocessableEntity | 1.InvalidArgument 2.FailedPrecondition 3.AlreadyExists |
| 500 | StatusInternalServerError | Aborted |
| 499 | deadline is exceeded | |
| authentication metadata is invalid or a Credentials callback fails |