🔒
Requires write_order access scope. More access scope

The Partial Order Refund API processes a refund for specific items or a partial amount of an order, enabling granular control over the refund process.

This API is especially useful for:

Handling refunds for specific products or quantities in an order.
Managing partial refunds based on customer requests or issues.
Maintaining accurate refund and order tracking records.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`id`	string	Yes	The unique ID of the order.	`1232123`

Body Parameters

Parameter	Type	Required	Description	Example
`is_return`	boolean	Yes	Indicates if the refund includes the return of items.	`true`
`price`	string	Yes	The refund amount for the partial refund.	`81.00`
`line_items`	array of objects	No	List of line items(product) included in the refund.	See below

line_itemsObject Fields :

Field	Type	Required	Description	Example
`id`	string	Yes	The unique ID of the LineItem.	`31d95f28-baf0-47c9-ad53-dbf3833f1b85`
`quantity`	int	Yes	The quantity of the product to refund.	`1`

Response Description

Public Response Fields

📘
Public Response Parameters

Success Response

Field	Type	Description	Example
Id	`string`	Unique identifier of the refund order.	`"31e27a7a-6899-4709-93e2-b3d6177c7458"`
Status	`string`	Current status of the refund (`finished`, `pending`, etc.).	`"finished"`
Number	`string`	Refund order number.	`"SPZ00000020-S1"`
CreatedAt	`string` (ISO8601)	Timestamp of when the refund order was created.	`"2024-06-24T08:17:59Z"`
Note	`string`	Notes about the refund order (optional).	`""`
RefundFailReason	`string`	Reason for refund failure (if applicable).	`""`
AllRefunded	`bool`	Indicates whether the order has been fully refunded (`true`/`false`).	`true`
RefundStatus	`string`	Status of the refund process (`pending`, `failed`, `finished`, etc.).	`"finished"`
Order	*Order	Associated order details (see `Order` struct).	`{...}`
Refund	*RefundRecord	Refund record details (see `RefundRecord` struct).	`{...}`

Order Structure

Field	Type	Description	Example
Id	`string`	Unique identifier of the order.	`"633130- SPZ00000020"`
Note	`*string`	Notes for the order (optional).	`"Urgent delivery requested"`
Number	`string`	Order number.	`"SPZ00000020"`
FinancialStatus	`string`	Financial status of the order.	`"refunded"`
Status	`string`	Current status of the order (`placed`, `cancelled`, etc.).	`"placed"`
CancelReason	`*string`	Reason for cancellation (if applicable).	`"Out of stock"`
PaymentMethod	`string`	Payment method used for the order.	`"bogus_gateway"`
FulfillmentStatus	`string`	Fulfillment status of the order (`waiting`, `shipped`, etc.).	`"waiting"`
DiscountCode	`string`	Discount code applied to the order.	`"SUMMER2024"`
DiscountApplications	`string`	Details of discounts applied.	`"[{...}]"`
CustomerNote	`string`	Notes from the customer about the order.	`"Leave package at the front door."`
SalesPlatform	`string`	The platform where the order was placed.	`"shoplazza"`
LandingSite	`string`	URL of the landing page where the order originated.	`"https://shop.com/ landing"`
BuyerAcceptsMarketing	`bool`	Indicates if the customer has opted into marketing.	`true`
Currency	`string`	Currency of the order.	`"USD"`
TotalPrice	`string`	Total price of the order, including taxes and shipping.	`"21.10"`
TotalDiscount	`string`	Total discount applied to the order.	`"5.00"`
TotalTax	`string`	Total tax applied to the order.	`"1.50"`
TotalShipping	`string`	Total shipping cost for the order.	`"11.00"`
SubTotal	`string`	Subtotal of the order (price before tax and shipping).	`"10.10"`
CodeDiscountTotal	`string`	Total discount from discount codes.	`"2.00"`
LineItemDiscountTotal	`string`	Total discount applied to line items.	`"1.00"`
Tags	`string`	Custom tags for the order.	`"high-priority"`
CreatedAt	`string` (ISO8601)	Timestamp of when the order was created.	`"2024-06-24T 08:16:57Z"`
UpdatedAt	`string` (ISO8601)	Timestamp of the last update to the order.	`"2024-06-24T 08:18:00Z"`
CanceledAt	`*string` (ISO8601)	Timestamp of when the order was cancelled (if applicable).	`"2024-06-24T 09:00:00Z"`
CustomerDeletedAt	`*string` (ISO8601)	Timestamp of when the customer deleted the order (if applicable).	`null`
TotalRefundPrice	`string`	Total refund amount processed for the order.	`"21.10"`
RefundStatus	`*string`	Status of the refund process for the order.	`"customize"`
BrowserIP	`string`	IP address of the customer when the order was placed.	`"192.168.0.1"`
Source	`string`	Referrer or source of the order.	`"https://shop.com/ checkout"`
EmailStatus	`string`	Email delivery status (`waiting`, `sent`, etc.).	`"waiting"`
ShippingLine	ShippingLine	Details of the shipping method used.	`{...}`
Customer	Customer	Information about the customer who placed the order.	`{...}`
ShippingAddress	ShippingAddress	Shipping address of the customer.	`{...}`
BillingAddress	BillingAddress	Billing address of the customer.	`{...}`
PaymentLine	PaymentLine	Details of the payment method used.	`{...}`
LineItems	OrderLineItem	List of items included in the order.	`[{...}]`
GiftCardTotal	`string`	Total value of gift cards applied to the order.	`"0.00"`
ProductTaxIncluded	`bool`	Indicates whether the product prices include tax.	`true`
AdditionalTotal	`string`	Total value of additional charges applied to the order.	`"0.00"`
AdditionalPrices	`[]*AdditionalPrice`	List of additional charges applied to the order.	`[{...}]`
LogisticsCode	`string`	Logistics or shipping code associated with the order.	`"LOG12345"`
Config	Config	Configuration details for the order, including currency, language, and tax settings.	`{...}`
CheckoutUrl	`string`	URL for the checkout page of the order.	`"https://shop.com/ checkout/12345"`

ShippingLine

Field	Type	Description	Example
Id	`string`	Unique identifier for the shipping line.	`"123456"`
Name	`string`	Name of the shipping method (required).	`"Express Delivery"`
Desc	`string`	Description of the shipping method.	`"Delivery within 2 days"`
SupportCod	`int`	Indicates if Cash on Delivery (COD) is supported (`1` for yes, `0` for no).	`1`
ShippingPrice	`string`	Price of the shipping service (required).	`"15.00"`

Customer

Field	Type	Description	Example
UserId	`string`	Unique identifier for the customer.	`"user_001"`
FirstName	`string`	First name of the customer.	`"John"`
LastName	`string`	Last name of the customer.	`"Doe"`
Email	`string`	Email address of the customer.	`"john.doe@example.com"`
Phone	`string`	Phone number of the customer.	`"+1234567890"`
CustomerRole	`string`	Role of the customer (e.g., `"buyer"`, `"admin"`).	`"buyer"`
Ext	`array`	Additional custom fields for the customer in a key-value format.

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	`["Order not found"]`	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

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`
404	Not Found	The Id provided is not found	"Order not found"
406	Not Acceptable	Current order can not finish after-sale.	"After-sales is not included in current order."