ReturnsService class (accessed via client.returns) lets a shopper lodge and track returns against their own online orders — fetching the reason codes for your UI, creating a return, listing the customer’s returns, and reading one in detail.
How returns work in Galactic Core
A return is a record of a request, not an action that immediately moves money or stock. Your storefront lodges a return for one of the customer’s online orders; it is created withstatus: "pending" and the merchant resolves it from their Galactic Core admin. Through this API your storefront does two things: create returns and read their status as the merchant works through them.
The split of responsibilities is deliberate:
There is intentionally no “approve” or “refund” method on this service — those are merchant decisions. A storefront integration creates returns and reacts to the outcome.
The four ways a merchant resolves a return
You don’t pick the resolution, but you surface it to the shopper (return.return_type, and credit_offer when relevant):
- Refund — the amount is returned to the original payment method.
- Store credit — the shopper receives a balance to spend on a future order instead of cash. Unlike the others, this requires the shopper’s agreement — see below.
- Exchange — the returned item is swapped for a replacement of equal value (an even swap); the replacement ships and no money changes hands.
- Reject — the merchant declines an item; nothing is refunded or restocked for it.
Store credit requires the shopper’s acceptance
Refunds and exchanges are settled entirely by the merchant. Store credit is the exception: a shopper may want their money back rather than a balance, so it is offered, not imposed. When a merchant offers store credit, the return carries acredit_offer object with status: "pending" and an amount. Your storefront must present the choice and call one of:
acceptReturnCredit— the shopper takes the credit; it is added to their balance and the return is finalized.requestReturnRefund— the shopper declines; the merchant then arranges a refund directly (outside this API).
pending. Accepted credit becomes a redeemable balance you can read with getStoreCredit and spend at checkout via client.orders.createOrder (covered below).
Returns and their line items each carry a status
A single return can contain several items, and the merchant can resolve them independently — approving two and rejecting one, for example. So both the return (return.status) and every line (return.items[].status) have their own status. Display the per-item status, not just the overall one, so the shopper sees exactly what was accepted.
Overview
Returns follow a lifecycle managed by the merchant:- A signed-in customer lodges a return. It starts as
pending. - The merchant approves, processes (refund, store credit, or exchange), or cancels it in their admin.
- The customer tracks the return’s
statusand each item’s per-linestatusthrough this API.
- Publishable keys — all four methods.
createReturn,listReturns, andgetReturnalso need a customer session. - Secret keys — the same actions, for server-side use.
Returns are for online orders only. Every return has
channel: "online".createReturn, listReturns, and getReturn require a customer session in addition to the API key. Pass either xAuthToken (a session token from POST /v1/auth/login or POST /v1/auth/verify-otp) or xExternalAuth (a bring-your-own-auth assertion). listReturnReasons needs no customer session.
listReturnReasons
Returns the accepted return reason codes, each with a human-readable label for a storefront dropdown. No customer session required.
checkReturnEligibility
Answers whether one order can still be returned, and until when — call it before showing a shopper a
return form, so you never offer a return the API will refuse.
This is the companion to features.returns_window_days on getStoreInfo, and the two are
deliberately different. That field is the store’s policy (“30 days”), a store-level fact you
render on a product page or at checkout. This is the verdict for one order, which depends on when
that particular parcel was delivered and so cannot be cached alongside the policy.
The window is measured from delivery where the store records it, and from the order date otherwise
(an in-store sale counts from the day of sale). The same rule is enforced when the return is lodged,
so this reads it ahead of time rather than duplicating it — a request made after the window is
rejected with the date it closed.
Response
reason is window_closed when the period has passed and returns_disabled when the store does not
accept returns at all; it is null while eligible. When the merchant has stated no period,
window_days and closes_at are both null and eligible is true — say returns are accepted
without naming a deadline rather than assuming a common default, since none exists.
Requires a customer session — x-auth-token, x-external-auth, or x-idp-token, exactly one of
the three, as everywhere else in this service. The order must belong to the signed-in shopper, so this cannot be used
to probe whether an arbitrary order id exists on the store.
createReturn
Lodges a return against one of the authenticated customer’s own online orders. The return is created with status: "pending" for the merchant to review.
Pass the customer’s session token in
xAuthToken (or a bring-your-own-auth assertion in xExternalAuth). The order_id must belong to that customer, and each order_item_id must be a line on that order.201:
Returns availability: if the store has returns turned off, the request returns
422 with error code returns_disabled.
listReturns
Lists the authenticated customer’s own returns, newest first.
Response shape
Response (200)
getReturn
Returns a single return by ID, including its line items and current status. A return that does not exist or does not belong to the authenticated customer returns 404.
200:
The Return object
Store credit & offers
When a merchant resolves a return by offering store credit instead of a refund, the return carries acredit_offer ({ status, amount }). While credit_offer.status is pending, the shopper can accept the credit or ask for a refund instead. Accepted store credit lands in the customer’s balance and can be spent at checkout.
A return carries a
custom_fields array — fields the merchant defined themselves, such as an RMA number. See Custom Fields.getStoreCredit(options)
The signed-in customer’s total redeemable store credit balance.
200 — balance is 0 for a shopper with no credit. After a credit is issued (e.g. via
acceptReturnCredit) the balance is populated; currency stays null either way (the ledger does
not stamp a currency code — the balance is always in the store’s own currency):
acceptReturnCredit(options)
Accept a pending store-credit offer on one of the customer’s returns. The credit is issued to their balance and the return is finalized. Returns 409 if there is no pending offer.
200:
requestReturnRefund(options)
Decline the store-credit offer and request a refund instead (the merchant then handles the refund directly). Returns 409 if there is no pending offer.
Spending store credit at checkout
Store credit is spent on a subsequent order:apply_store_credit: true on client.orders.createOrder draws down the shopper’s balance automatically.
store_credit_balance (client.customers.getCustomer({ id, xAuthToken })).
Putting the store-credit flow together
A complete “the merchant offered me store credit, what now?” screen:After
requestReturnRefund, the merchant settles the refund with the shopper directly — there is no automatic money movement, so don’t tell the shopper the refund is already on its way.