Full Order 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:

  1. Automating full refunds for customer orders.
  2. Tracking refund details, including shipping and taxes.
  3. Managing customer refunds and ensuring accurate records for financial reporting.

Request Parameters

Public Request Parameters

📘

Path Parameters

ParameterTypeRequiredDescriptionExample
idstringYesThe unique ID of the order.1232123

Response Description

Public Response Fields

📘

Success Response

FieldTypeDescriptionExample
IdstringUnique identifier of the refund order."31e27a7a- 6899-4709-93e2-b3d6177c7458"
StatusstringCurrent status of the refund (finished, pending, etc.)."finished"
NumberstringRefund order number."SPZ00000 020-S1"
CreatedAtstring (ISO8601)Timestamp of when the refund order was created."2024-06-24T08:17:59Z"
NotestringNotes about the refund order (optional).""
RefundFailReasonstringReason for refund failure (if applicable).""
AllRefundedboolIndicates whether the order has been fully refunded (true/false).true
RefundStatusstringStatus of the refund process (pending, failed, finished, etc.)."finished"
OrderOrderAssociated order details (see Order struct).{...}
RefundrefundRecordRefund 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

FieldTypeDescriptionExample
IdstringUnique identifier for the shipping line."123456"
NamestringName of the shipping method (required)."Express Delivery"
DescstringDescription of the shipping method."Delivery within 2 days"
SupportCodintIndicates if Cash on Delivery (COD) is supported (1 for yes, 0 for no).1
ShippingPricestringPrice of the shipping service (required)."15.00"

Customer

FieldTypeDescriptionExample
UserIdstringUnique identifier for the customer."user_001"
FirstNamestringFirst name of the customer."John"
LastNamestringLast name of the customer."Doe"
EmailstringEmail address of the customer."[email protected]"
PhonestringPhone number of the customer."+1234567890"
CustomerRolestringRole of the customer (e.g., "buyer", "admin")."buyer"
ExtarrayAdditional 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.

FieldTypeExampleDescription
errorsArray[ "file number error"]A list of errors encountered during the request processing.
FieldTypeExampleDescription
errorString "store is not active"Indicates an error encountered during the process

Error Detail

Status CodeMessagePossible ReasonExample Response
400Bad RequestInvalid input format or request structure (e.g., missing required fields or incorrect data types).Bad Request
UnauthorizedThe request is missing valid authentication credentials or the credentials provided are invalid.Unauthorized
422Unprocessable EntityID is invalid or empty"Invalid ID"
404Not FoundThe Id provided is not found"Order not found"
406Not AcceptableCurrent order can not finish after-sale."After-sales is not included in current order."
Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!