🔒
Requires write_order access scope. More access scope

The Pay Order Success API allows users to marks an order as successfully paid and updates billing information if provided.

This API is especially useful for:

Completing payment for manually created orders
Processing payments from external payment gateways or existing gateways.
Updating billing information post-payment

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`order_id`	string	Yes	Unique order identifier	`"order_12345"`

Body Parameters

Parameter	Type	Required	Description	Example
`billing_address.first_name`	string	No	Recipient's given name	`"John"`
`billing_address.last_name`	string	No	Recipient's surname	`"Doe"`
`billing_address.email`	string	No	Contact email	`"john.doe@example.com"`
`billing_address.country`	string	No	Billing country	`"United States"`
`billing_address.country_code`	string	No	ISO country code	`"US"`
`billing_address.province`	string	No	State/province	`"California"`
`billing_address.province_code`	string	No	ISO province code	`"CA"`
`billing_address.area`	string	No	Regional designation	`"Bay Area"`
`billing_address.city`	string	No	City name	`"San Francisco"`
`billing_address.address`	string	No	Primary street address	`"123 Main Street"`
`billing_address.address1`	string	No	Secondary address line	`"Apt 4B"`
`billing_address.company`	string	No	Business name	`"Acme Inc."`
`billing_address.longitude`	string	No	Geographic longitude coordinate	`"-122.4194"`
`billing_address.latitude`	string	No	Geographic latitude coordinate	`"37.7749"`
`billing_address.zip`	string	No	Postal code	`"94105"`
`billing_address.source`	string	No	Origin or source of the address data	`"web_checkout"`
`billing_address.tags`	string	No	Address categorization labels	`"primary, office"`
`gateway`	string	No	Payment gateway identifier(Can be customized)	"customize"
`payment_line.payment_channel`	string	required if payment_line existed	Payment service provider	"paypal"
`payment_line.payment_method`	string	required if payment_line existed	Specific payment type	"online"
`payment_line.transaction_no`	string	required if payment_line existed	Unique transaction ID	"3240166068620277548"

Usage Scenarios

Test Order (Using Bogus Gateway)

Use Case: Use this for testing orders. The created order will have a test order tag.
Parameter Requirements: Do not include payment_line neither gateway in the request body parameters.

curl --location 'https://{subdomain}.myshoplaza.com/openapi/2025-06/orders/{order_id}/payment/success' \
--header 'access-token: {access-token}' \
--header 'Content-Type: application/json' \
--data '{
  "billing_address": {
    "first_name": "name"
  }
}'

Response Example

{
  "code": "Success",
  "data": {
    "order": {
      "id": "365154185097449134715",
      "created_at": "2025-10-31T07:57:29Z",
      "updated_at": "2025-10-31T08:09:22Z",
      // ... other order fields ...
      "payment_line": {
        "payment_name": "bogus",
        "payment_channel": "bogus",
        "payment_method": "bogus_gateway",
        "transaction_no": "bg_365154185097449134715"
      }
      // ... other order fields ...
    }
  }
}

Custom Payment Method (Non-test Order)

Use Case: For custom payment integrations without specific payment channel requirements.
Parameter Requirements: Include gateway but do not include payment_line in the request body parameters.

curl --location 'https://{subdomain}.myshoplaza.com/openapi/2025-06/orders/{order_id}/payment/success' \
--header 'access-token: {access-token}' \
--header 'Content-Type: application/json' \
--data '{
  "billing_address": {
    "first_name": "name"
  },
  "gateway": "customize"
}'

Response Example

{
  "code": "Success",
  "data": {
    "order": {
      "id": "365154185097449134715",
      "created_at": "2025-10-31T07:57:29Z",
      "updated_at": "2025-10-31T08:09:22Z",
      // ... other order fields ...
      "payment_line": {
        "payment_name": "customize",
        "payment_channel": "customize_payment",
        "payment_method": "customize_payment",
        "transaction_no": "cpn_6265-00000219"
      }
      // ... other order fields ...
    }
  }
}

Use Store's Existing Payment Method (Non-test Order)

Use Case: Use this for integrating with existing payment methods configured in the store.
Parameter Requirements: Include both gateway and payment_line in the request body parameters.

curl --location 'https://{subdomain}.myshoplaza.com/openapi/2025-06/orders/{order_id}/payment/success' \
--header 'access-token: {access-token}' \
--header 'Content-Type: application/json' \
--data '{
  "billing_address": {
    "first_name": "name"
  },
  "gateway": "customize",
  "payment_line": {
    "payment_channel": "paypal",
    "payment_method": "online",
    "transaction_no": "3240166068620277548"
  }
}'

Response Example

{
  "code": "Success",
  "data": {
    "order": {
      "id": "365154185097449134715",
      "created_at": "2025-10-31T07:57:29Z",
      "updated_at": "2025-10-31T08:09:22Z",
      // ... other order fields ...
      "payment_line": {
        "payment_name": "customize",
        "payment_channel": "paypal",
        "payment_method": "online",
        "transaction_no": "3240166068620277548"
      }
      // ... other order fields ...
    }
  }
}

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"`	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).
`currency`	string	`"USD"`	Currency
`financial_status`	string	`"paid"`	Payment status
`status`	string	`"fulfilled"`	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