Orders & refunds

@orbcart/admin runs on your server. Never import it into browser code or expose its secret key to a storefront.

Connect

Load both values from your server's environment:

import { createAdmin } from "@orbcart/admin";

const admin = createAdmin({
  url: env.ORBCART_URL,
  key: env.ORBCART_SECRET_KEY,
});

Find an Order

const order = await admin.orders.get("NG-2026-004711");

Replace that example number with one from your checkout. You can also pass the Order ID. This reads the Order's authoritative state, not a search projection.

To browse Orders:

const page = await admin.orders.list();

if (page.next) {
  const nextPage = await admin.orders.list({ after: page.next });
}

The list can lag a few seconds behind a purchase. Use get() when the current state matters.

Refund one unit

Pass IDs from the Order and a stable key for this refund operation:

const refund = await admin.orders.refund(
  order.id,
  { lines: [{ line: "l_1", quantity: 1 }], reason: "return" },
  { idempotencyKey: "return-4711-backpack" },
);

Replace l_1 with the actual Line ID. OrbCart calculates the refund from the Order's frozen amounts, including its discounts and tax. You do not send a price.

Keep the same key when retrying the same refund after a restart. Use a new key for a different refund. Check refund.status; an unclear provider response is not a confirmed refund.

End a promotion

await admin.offers.invalidate({ tags: ["summer-sale"] });

This invalidates matching Offers in open Carts. Previously placed Orders keep their original amounts.

See how your systems supply Offers →