🔒 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.
📘 Public Request Parameters
Parameter Type Required Description Example idstring Yes The unique ID of the order. 1232123
Parameter Type Required Description Example is_returnboolean Yes Indicates if the refund includes the return of items. truepricestring Yes The refund amount for the partial refund. 81.00line_itemsarray of objects Yes List of line items(product) included in the refund. See below
line_items Object Fields
Field Type Required Description Example idstring Yes The unique ID of the LineItem. 31d95f28-baf0-47c9-ad53-dbf3833f1b85quantityint Yes The quantity of the product to refund. 1
📘 Public Response Parameters
Field Type Description Example Id stringUnique identifier of the refund order. "31e27a7a-6899-4709-93e2-b3d6177c7458"Status stringCurrent status of the refund (finished, pending, etc.). "finished"Number stringRefund order number. "SPZ00000020-S1"CreatedAt string (ISO8601)Timestamp of when the refund order was created. "2024-06-24T08:17:59Z"Note stringNotes about the refund order (optional). ""RefundFailReason stringReason for refund failure (if applicable). ""AllRefunded boolIndicates whether the order has been fully refunded (true/false). trueRefundStatus stringStatus 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). {...}
Field Type Description Example Id stringUnique identifier of the order. "633130-SPZ00000020"Note *stringNotes for the order (optional). "Urgent delivery requested"Number stringOrder number. "SPZ00000020"FinancialStatus stringFinancial status of the order. "refunded"Status stringCurrent status of the order (placed, cancelled, etc.). "placed"CancelReason *stringReason for cancellation (if applicable). "Out of stock"PaymentMethod stringPayment method used for the order. "bogus_gateway"FulfillmentStatus stringFulfillment status of the order (waiting, shipped, etc.). "waiting"DiscountCode stringDiscount code applied to the order. "SUMMER2024"DiscountApplications stringDetails of discounts applied. "[{...}]"CustomerNote stringNotes from the customer about the order. "Leave package at the front door."SalesPlatform stringThe platform where the order was placed. "shoplazza"LandingSite stringURL of the landing page where the order originated. "https://shop.com/landing"BuyerAcceptsMarketing boolIndicates if the customer has opted into marketing. trueCurrency stringCurrency of the order. "USD"TotalPrice stringTotal price of the order, including taxes and shipping. "21.10"TotalDiscount stringTotal discount applied to the order. "5.00"TotalTax stringTotal tax applied to the order. "1.50"TotalShipping stringTotal shipping cost for the order. "11.00"SubTotal stringSubtotal of the order (price before tax and shipping). "10.10"CodeDiscountTotal stringTotal discount from discount codes. "2.00"LineItemDiscountTotal stringTotal discount applied to line items. "1.00"Tags stringCustom tags for the order. "high-priority"CreatedAt string (ISO8601)Timestamp of when the order was created. "2024-06-24T08:16:57Z"UpdatedAt string (ISO8601)Timestamp of the last update to the order. "2024-06-24T08:18:00Z"CanceledAt *string (ISO8601)Timestamp of when the order was cancelled (if applicable). "2024-06-24T09:00:00Z"CustomerDeletedAt *string (ISO8601)Timestamp of when the customer deleted the order (if applicable). nullTotalRefundPrice stringTotal refund amount processed for the order. "21.10"RefundStatus *stringStatus of the refund process for the order. "customize"BrowserIP stringIP address of the customer when the order was placed. "192.168.0.1"Source stringReferrer or source of the order. "https://shop.com/checkout"EmailStatus stringEmail 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 stringTotal value of gift cards applied to the order. "0.00"ProductTaxIncluded boolIndicates whether the product prices include tax. trueAdditionalTotal stringTotal value of additional charges applied to the order. "0.00"AdditionalPrices []*AdditionalPriceList of additional charges applied to the order. [{...}]LogisticsCode stringLogistics or shipping code associated with the order. "LOG12345"Config *Config Configuration details for the order, including currency, language, and tax settings. {...}CheckoutUrl stringURL for the checkout page of the order. "https://shop.com/checkout/12345"
Field Type Description Example Id stringUnique identifier for the shipping line. "123456"Name stringName of the shipping method (required). "Express Delivery"Desc stringDescription of the shipping method. "Delivery within 2 days"SupportCod intIndicates if Cash on Delivery (COD) is supported (1 for yes, 0 for no). 1ShippingPrice stringPrice of the shipping service (required). "15.00"
Field Type Description Example UserId stringUnique identifier for the customer. "user_001"FirstName stringFirst name of the customer. "John"LastName stringLast name of the customer. "Doe"Email stringEmail address of the customer. "[email protected] "Phone stringPhone number of the customer. "+1234567890"CustomerRole stringRole of the customer (e.g., "buyer", "admin"). "buyer"Ext arrayAdditional custom fields for the customer in a key-value format.
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 errorsArray ["Order not found"]A list of errors encountered during the request processing.
Field Type Example Description errorString "store is not active"Indicates an error encountered during the process
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 RequestUnauthorized The request is missing valid authentication credentials or the credentials provided are invalid. Unauthorized404 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."
