post https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders//payment/success
Requires
write_orderaccess scope. More access scope
This interface defaults to using a test payment gateway, which simulates the completion of orders and payment, so the corresponding payment amount does not participate in the store's sales statistics.
The Order Payment Success API finalizes payment for an order and updates its status to indicate that payment has been completed. Once the payment succeeds, the order’s status becomes "placed", and its financial status changes to "paid".
This API is especially useful for:
- Completing an order checkout process.
- Confirming payment receipt and updating order records.
- Triggering post-payment workflows (e.g., sending order confirmation emails).
Request Parameters
Public Request Parameters
Path Parameter
| Name | Type | Required | Desc | Example |
|---|---|---|---|---|
id | string | Yes | The unique ID of the order to be marked as paid. Usually has a format like "633130-00000009". | "633130-00000009" |
Body Parameters
| Name | Type | Required | Desc | Example |
|---|---|---|---|---|
billing_address | object | No | The billing address details. If omitted, the existing billing address (if any) remains unchanged. | N/A |
| billing_address. first_name | string | No | The first name of the person associated with the payment method. | "John" |
| billing_address. last_name | string | No | The last name of the person associated with the payment method. | "Smith" |
| billing_address. | string | No | The email address used for billing. | "john.smith@email.com" |
| billing_address. country | string | No | The name of the billing address country, for example: "United States". | "United States" |
| billing_address. country_code | string | No | The two-letter code for the country, for example: "US". | "US" |
| billing_address. province | string | No | The region (province/state/prefecture) for the billing address, for example: "Alaska". | "Alaska" |
| billing_address. province_code | string | No | Abbreviation of the region, for example: "US-AK". | "US-AK" |
| billing_address. area | string | No | The area of the billing address. | "Downtown" |
| billing_address. city | string | No | The city, town, or village of the billing address. | "Anchorage" |
| billing_address. address1 | string | No | The main street address line, for example: "1 Rue des Carrieres". | "1 Main Street" |
| billing_address. address2 | string | No | Apartment/floor/room number, for example: "Suite 1234". | "Apt 202" |
| billing_address. company | string | No | The company name for the billing address, if applicable. | "ABC Limited" |
| billing_address. latitude | string | No | The latitude of the billing address, for example: "22.54". | "61.2175" |
| billing_address. longitude | string | No | The longitude of the billing address, for example: "114.06". | "-149.8858" |
| billing_address. zip | string | No | The ZIP or postal code, for example: "87036". | `"99501 |
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 LineItemv | 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 | UnprocessableError | 1:cannot get total_price of order |
| "can't convert TotalPrice %s to decimal: fractional part too long" | ||
| 400 | ||
| 500 | StatusInternalServerError | Aborted/NotFound/Unimplemented/Unauthenticated/DeadlineExceeded |