🔒
Requires write_order access 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

📘
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. email*	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

📘
Public Response Parameters

Success Response

📘
The relationships between entities.

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 process `waiting` 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).
	~~discount_code~~	string	@Deprecated.
	discount_applications	string	Details of discounts
	customer_note	string	A note provided by the customer during checkout.
	~~landing_site~~	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.
	~~line_item_discount_total~~	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"`
	~~total_refund_discount~~	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.
	~~total_refund_tax~~	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.
	~~browser_ip~~	string	@Deprecated. IP address of the customer who placed the order.
	~~last_landing_url~~	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.
	~~source~~	string	@Deprecated.Product source url
	~~source_name~~	object	@Deprecated. Product source
	~~source_name.data~~	string	@Deprecated. Product source
	~~source_name.created_at~~	string	@Deprecated. Timestamp of the creation
	~~last_referrer_show~~	object	@Deprecated. Last interaction source
	~~last_referrer_show.data~~	string	@Deprecated. Interaction source data.
	~~last_referrer_show.created_at~~	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
	~~sales_platform~~	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

API Structure Overview