Returning Customer

A shopper with an account and an order behind them signs back in, looks at their history and profile, lodges a return, and redeems the store credit they are offered against their next purchase. Customer-self reads (profile, returns) run with the publishable client plus the shopper’s session token; order history and sign-in run with the secret client on your server. Workflow Examples has the client setup.

1. Signing the shopper back in

Login is a secret-key call on your server; a publishable key returns 403. It returns the customer record and a session whose access_token is the shopper’s session token, which goes back to the browser as xAuthToken for the customer-self calls below.

// On your server — secret client
const { customer, session } = await server.authentication.login({
  requestBody: { email: 'john.doe@example.com', password: '••••••••' },
});
// session.access_token  → the shopper's x-auth-token for steps 3–5

Response

{
  "message": "Login successful",
  "user": { "id": "df648f68-39b3-4ba6-9be2-ff0a9393c02b", "email": "john.doe@example.com", "email_confirmed": true },
  "customer": {
    "id": "15ecd58f-a8f8-49e4-9098-96f1fa8308e9",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+12125550142",
    "tier": "bronze",
    "total_purchases": 0,
    "created_at": "2026-06-20T11:36:54.174303+00:00"
  },
  "session": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<redacted>.signature",
    "refresh_token": "5h2g7k9m1n3p...",
    "expires_in": 3600
  }
}

For passwordless sign-in, server.authentication.sendMagicLink(...) and the OTP pair (sendMagicLink → verifyOtp) return the same { user, customer, session } envelope. server.authentication.refreshToken(...) renews an expiring token.

2. Order history

Order history is a secret-key read on your server. listOrders returns the customer’s orders newest-first, filtered by payment_status or paged with the cursor. A publishable key returns 403 here, so order data never leaves your server.

// On your server — secret client
const { orders } = await server.orders.listOrders({ limit: 5 });

Response

{
  "orders": [
    {
      "id": "0468af54-5f6b-4be5-a4e6-3aa7a79450ba",
      "order_number": "ORD-1781955469360",
      "customer_id": "15ecd58f-a8f8-49e4-9098-96f1fa8308e9",
      "customer_email": "john.doe@example.com",
      "customer_name": "John Doe",
      "subtotal": 598,
      "shipping_amount": 5.99,
      "discount_amount": 0,
      "total_amount": 603.99,
      "currency": "USD",
      "payment_method": "card",
      "payment_status": "paid",
      "order_status": "shipped",
      "tracking_number": "1Z999AA10123456784",
      "created_at": "2026-06-20T11:37:50.273614+00:00"
    }
  ]
}

getOrder returns one order with its line items:

const order = await server.orders.getOrder({ id: '0468af54-5f6b-4be5-a4e6-3aa7a79450ba' });
// order.items[0].product_name === 'Samsung Galaxy Watch 6'  ·  order.order_status === 'shipped'

Response

{
  "id": "0468af54-5f6b-4be5-a4e6-3aa7a79450ba",
  "order_number": "ORD-1781955469360",
  "payment_status": "paid",
  "order_status": "shipped",
  "total_amount": 603.99,
  "tracking_number": "1Z999AA10123456784",
  "items": [
    {
      "id": "d72a3cbe-2232-4e84-a25c-fe1245c5e5e0",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "product_name": "Samsung Galaxy Watch 6",
      "product_sku": "SAM-WATCH-6-44-0186",
      "quantity": 2,
      "unit_price": 299,
      "total_price": 598
    }
  ]
}

3. The customer’s profile

The shopper reads their own profile with the publishable client plus their session token. getCustomer requires the {id} to match the resolved session, and a mismatch returns 403, so a shopper can only ever read their own record. address, last_purchase, and store_metrics are nullable; tier is the loyalty tier.

const profile = await storefront.customers.getCustomer({
  id: '15ecd58f-a8f8-49e4-9098-96f1fa8308e9',
  xAuthToken: session.access_token,
});

Response

{
  "id": "15ecd58f-a8f8-49e4-9098-96f1fa8308e9",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+12125550142",
  "address": null,
  "status": "active",
  "join_date": "2026-06-20",
  "external_id": null,
  "marketing_consent": true,
  "total_purchases": 0,
  "last_purchase": null,
  "store_credit_balance": 0,
  "created_at": "2026-06-20T11:36:54.174303+00:00",
  "updated_at": "2026-06-20T11:36:54.174303+00:00",
  "store_metrics": null
}

Stores that run their own identity provider (Auth0, Clerk, Cognito, Firebase, NextAuth, SSO) pass a signed xExternalAuth assertion instead of xAuthToken — the same customer-self endpoints accept either. See Authentication for the assertion format.

4. Lodging a return

createReturn (publishable client plus session token) returns part or all of a delivered order. It takes a reason_code from the public reason list, a return_type, and the order lines being sent back, and the return lands in pending for the merchant to review. The reason codes that populate the form need no session:

const { data: reasons } = await storefront.returns.listReturnReasons();

Response

{
  "data": [
    { "code": "damaged", "label": "Arrived damaged" },
    { "code": "defective", "label": "Defective / not working" },
    { "code": "wrong_item", "label": "Wrong item received" },
    { "code": "not_as_described", "label": "Not as described" },
    { "code": "wrong_size", "label": "Wrong size / fit" },
    { "code": "no_longer_needed", "label": "No longer needed" },
    { "code": "arrived_late", "label": "Arrived too late" },
    { "code": "other", "label": "Other (please describe)" }
  ]
}

The return itself:

const { data: ret } = await storefront.returns.createReturn({
  xAuthToken: session.access_token,
  requestBody: {
    order_id: 'a80a5298-eba4-41b3-8e87-a26ff89b493d',
    reason_code: 'damaged',
    return_type: 'full_refund',
    items: [
      { order_item_id: '585eaedb-fde2-4452-b101-33173741578a', quantity: 1, condition: 'damaged' },
    ],
  },
});
// ret.status === 'pending'  ·  ret.return_number === 'RET-20260620-d41309'

Response

{
  "data": {
    "id": "75eef130-2aba-414b-b6ef-3c19b71205b6",
    "return_number": "RET-20260620-d41309",
    "order_id": "a80a5298-eba4-41b3-8e87-a26ff89b493d",
    "channel": "online",
    "status": "pending",
    "return_type": "full_refund",
    "reason_code": "damaged",
    "reason_description": null,
    "total_return_amount": 299,
    "refund_amount": 299,
    "refund_method": null,
    "created_at": "2026-06-20T10:48:26.132147+00:00",
    "processed_at": null,
    "credit_offer": { "status": "none", "amount": null },
    "items": [
      {
        "id": "8b7c00d4-b557-4697-8933-3ed891295e39",
        "order_item_id": "585eaedb-fde2-4452-b101-33173741578a",
        "product_name": "Samsung Galaxy Watch 6",
        "quantity": 1,
        "unit_price": 299,
        "return_amount": 299,
        "condition": "damaged",
        "status": "pending",
        "rejection_reason": null,
        "media": []
      }
    ]
  }
}

Returns must be enabled for the store. If the merchant has them turned off, createReturn returns 422 with { error: { code: "returns_disabled" } }. Approving a return and reviewing the items is a merchant action done in admin — not via this API.

5. Tracking the return

listReturns gives the shopper all of their own returns and getReturn one by id, both on the publishable client plus session token.

const { data: myReturns } = await storefront.returns.listReturns({
  xAuthToken: session.access_token,
});
// myReturns[0].status moves pending → approved → processing → completed as the merchant works it

Response

{
  "data": [
    {
      "id": "75eef130-2aba-414b-b6ef-3c19b71205b6",
      "return_number": "RET-20260620-d41309",
      "order_id": "a80a5298-eba4-41b3-8e87-a26ff89b493d",
      "channel": "online",
      "status": "pending",
      "return_type": "full_refund",
      "reason_code": "damaged",
      "total_return_amount": 299,
      "refund_amount": 299,
      "credit_offer": { "status": "none", "amount": null },
      "created_at": "2026-06-20T10:48:26.132147+00:00"
    }
  ]
}

6. The resolution branches: store credit or a refund

Reviewing the return, the merchant can offer store credit instead of a cash refund. The return’s credit_offer.status flips to offered/pending with an amount, and the shopper takes one of two paths from there. Both run on the publishable client plus session token. The balance before any resolution — a shopper who has never been credited has nothing yet:

const { data: before } = await storefront.returns.getStoreCredit({
  xAuthToken: session.access_token,
});
// before.balance === 0

Response

{ "data": { "balance": 0, "currency": null } }

currency is null here, and stays null even after credit is issued: the store-credit ledger does not stamp a currency code, because the balance is always in the store’s own currency. balance is the amount.

Path A — accepting the store credit

acceptReturnCredit takes the credit. Galactic Core issues it to the shopper’s balance and returns the new credit record.

const { data: credit } = await storefront.returns.acceptReturnCredit({
  id: '75eef130-2aba-414b-b6ef-3c19b71205b6',
  xAuthToken: session.access_token,
});
// credit.amount === 24.95 → now on the customer's balance

Response

{
  "data": { "store_credit_id": "90cfe13f-2486-4be7-947a-db299ff241c3", "amount": 24.95 }
}

The balance after accepting is populated, with currency still null:

const { data: after } = await storefront.returns.getStoreCredit({
  xAuthToken: session.access_token,
});

Response

{ "data": { "balance": 24.95, "currency": null } }

Path B — declining the credit for a cash refund

A shopper who would rather have their money back declines the offer with requestReturnRefund. The return moves to refund_requested and the merchant handles the payout outside this API. The call is valid only while a store-credit offer is pending, and returns 409 otherwise.

const { data: refund } = await storefront.returns.requestReturnRefund({
  id: '75eef130-2aba-414b-b6ef-3c19b71205b6',
  xAuthToken: session.access_token,
});
// refund.status === 'refund_requested' → no store credit issued; balance stays 0

Response

{
  "data": { "status": "refund_requested" }
}

The two paths are mutually exclusive on the same offer: the shopper takes either the credit (Path A) or the refund (Path B), never both. The step below follows Path A, where the shopper kept the $24.95 credit.

7. Spending the credit on the next order

At the shopper’s next checkout, apply_store_credit: true on the order body applies the $24.95 kept in Path A, optionally capped with store_credit_amount. The amount actually applied comes back as store_credit_applied. Order creation is a secret-key, HMAC-signed call, so this runs on your server — Storefront checkout has the signing recipe.

const { order } = await server.orders.createOrder({
  idempotencyKey: `order-${customer.id}-${Date.now()}`,
  xTimestamp: timestamp,
  xSignature: signature,
  requestBody: {
    customer_email: 'john.doe@example.com',
    customer_name: 'John Doe',
    items: [
      { product_id: '0186665f-f0a1-4c79-976a-919b5b1c2daa', variant_id: 'e98631a9-7852-4fe8-8efe-988935d5922a', quantity: 1, unit_price: 299, total_price: 299 },
    ],
    subtotal: 299,
    shipping_amount: 5.99,
    total_amount: 304.99,
    payment_status: 'pending',
    apply_store_credit: true,
  },
});
// order.store_credit_applied → the credit Galactic Core deducted toward this order

Response

{
  "order": {
    "id": "b2f7e1a4-9c33-4d80-8a6e-51c0d9e7f2a1",
    "order_number": "ORD-1781955480500",
    "customer_id": "15ecd58f-a8f8-49e4-9098-96f1fa8308e9",
    "subtotal": 299,
    "shipping_amount": 5.99,
    "total_amount": 304.99,
    "currency": "USD",
    "payment_status": "pending"
  },
  "store_credit_applied": 24.95
}

store_credit_applied is the amount of the customer’s balance Galactic Core spent against this order, here the $24.95 kept in Path A. Where the credit fully covers the order, Galactic Core also reflects it in the order’s discount_amount and stamps the order notes with [STORE_CREDIT_APPLIED <amount>].

Store credit comes off the order total automatically, without the integration moving money. The remaining balance is charged through the normal payment step.

What’s next

Search & discovery covers search, recommendations, and dynamic pricing for the next purchase.
Storefront checkout walks the full guest-to-paid path for a new shopper.
Reviews and support threads follow once the return resolves.

Overview

Storefront

Marketplace

Integrations

Reference

1. Signing the shopper back in

2. Order history

3. The customer’s profile

4. Lodging a return

5. Tracking the return

6. The resolution branches: store credit or a refund

Path A — accepting the store credit

Path B — declining the credit for a cash refund

7. Spending the credit on the next order

What’s next

​1. Signing the shopper back in

​2. Order history

​3. The customer’s profile

​4. Lodging a return

​5. Tracking the return

​6. The resolution branches: store credit or a refund

​Path A — accepting the store credit

​Path B — declining the credit for a cash refund

​7. Spending the credit on the next order

​What’s next

1. Signing the shopper back in

2. Order history

3. The customer’s profile

4. Lodging a return

5. Tracking the return

6. The resolution branches: store credit or a refund

Path A — accepting the store credit

Path B — declining the credit for a cash refund

7. Spending the credit on the next order

What’s next