post https://{shopdomain}.myshoplaza.com/openapi/2022-01/orders//refund
Requires
write_order
access scope. More access scope
The Full Order Refund API processes a complete refund for an order, including all items, shipping, and applicable taxes. It also provides detailed information about the refunded order.
This API is especially useful for:
- Automating full refunds for customer orders.
- Tracking refund details, including shipping and taxes.
- Managing customer refunds and ensuring accurate records for financial reporting.
Request Parameters
Public Request Parameters
Path Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
id | string | Yes | The unique ID of the order. | 1232123 |
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. | "SPZ00000 020-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-SP Z00000020" |
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. | "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 | [ "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
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 | |
422 | Unprocessable Entity | ID is invalid or empty | "Invalid ID" |
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." |