post https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders
Requires
write_orderaccess scope.
Merchants can use it to create orders on behalf of their customers. orders are useful for merchants that need to do the following tasks:
1: Place an order on Station A and transfer to Station B to create the order and make the payment through this interface.
2: Quickly create an order for the buyer to pay.
3: Migrate merchant orders from other systems.
4:The buyer purchases an item that is out of stock, and the order is supplemented after restocking.
Note: The operation is scoped to a specific shop, identified by its unique domain prefix (shopdomain), ensuring all updates are applied to the correct store.
Some order attribute values passed in the interface are not allowed to be modified in the subsequent checkout process after the order is successfully created.
Request Parameters
Public Request Parameters
Body Parameters
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| LineItems | Array of Object | Y | A list of products included in the order. Each line item contains details like product ID, variant ID, and quantity. |
| line_item.variant_id | string | Y | Unique identifier for the specific product variant. |
| line_item.product_id | string | Y | Unique identifier for the product associated with the line item. |
| line_item.quantity | int | Y | The quantity of the product being purchased. |
| shipping_address | Object | Y | The recipient's delivery address, including name, phone, email, and location details such as street address, city, province, country, and postal code. |
| shipping_address.first_name | string | N | First name of the recipient. |
| shipping_address.last_name | string | Y | Last name of the recipient. |
| shipping_address.phone | string | N | Recipient's phone number (e.g., +86 150 1447 1143). |
| shipping_address.email | string | Y | Email address of the recipient. |
| shipping_address.country | string | Y | Country where the order will be delivered (e.g., United States). |
| shipping_address.country_code | string | Y | ISO code for the recipient's Country code , (e.g., US). |
| shipping_address.province | string | N | Province or state (e.g., New Mexico). |
| shipping_address.province_code | string | Y | ISO code for the recipient's Province Code ,(e.g., NM). |
| shipping_address.city | string | Y | City for delivery (e.g., San Jose). |
| shipping_address.address | string | Y | The main street address for delivery (e.g., 1 Rue des Carrieres). |
| shipping_address.address1 | string | N | Additional address information (e.g., Suite 1234). |
| shipping_address.zip | string | N | ZIP or postal code for delivery (e.g., 87036). |
| shipping_address.latitude | string | N | Latitude of the delivery location (e.g., 22.54). |
| shipping_address.longitude | string | N | Longitude of the delivery location (e.g., 114.06). |
| tags | Array of String | N | Custom labels or tags for the order. |
| tax_total | string | Y | The total tax amount applied to the order, represented as a numeric string (e.g., "9.99"). |
| currency_code | string | Y | The currency code for the order (e.g., USD). |
| discount | string | N | Discount amount or percentage applied to the order (e.g., "10.00" or "10%"). |
| note | string | N | A note about the order, added by the merchant or customer. |
| payment_line | string | N | The payment method used for the order. •If you specify "COD" (Cash on Delivery) and the merchant has enabled this option, the order will use the Cash on Delivery payment method. •If "COD" is disabled by the merchant, any value entered will default to the payment method configured in the store’s admin settings. •For completed payment orders, payment_line reflects the final payment method used. For unpaid orders, payment_line serves as a suggested payment method and may not represent the final payment method used during checkout. |
| shipping_line | Object | N | Details of the shipping method selected for the order, including name, price, and description. |
| shipping_line.name | string | Y | Name of the shipping method (e.g., Free Shipping). |
| shipping_line.shipping_price | string | Y | Price of the shipping method, as a numeric string (e.g., "10.00"). |
| shipping_line.desc | string | N | Description of the shipping method. |
| refund_total | string | N | Total refund amount successfully processed for the order (e.g., "15.00"). |
| refund_line_items | Array of Object | N | Details of refunded items, including quantities, taxes, and discounts. |
| created_at | string | Y | The timestamp when the order was created. |
| updated_at | string | Y | The timestamp of the last update to the order. |
| order_status | string | Y | The current status of the order (e.g., pending, fulfilled, canceled). |
| financial_status | string | Y | The financial status of the order (e.g., paid, unpaid, refunded). |
Response Explanation
Public Response Fields
Successful 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 |
|---|---|---|
| 422 | StatusUnprocessableEntity | 1:The shipping address does not pass;ShippingAddress is nil. 2:Get transaction settings error;not exists checkout setting 3:Failed to create order line items;record_not_found 4:create_order_calculate_failed;order price calculate error 5:create_order_build_failed;customer or paymentline information error 6:order_id {order_id} CreateOrderBatchOption failed 7:Get Order Detail failed 8:DecreaseInventory failed |
| 406 | Create order failed | |
| 500 | StatusInternalServerError | Aborted/NotFound/Unimplemented/Unauthenticated/DeadlineExceeded |