post https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders//partial_refund
Requires
write_orderaccess 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
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_items Object 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
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" |
string | Email address of the customer. | "[email protected]" | |
| 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." |