AdminClient

Your ERP, warehouse, CRM or app on a shop's products, stock, orders, customers, marketing, reviews, quotations, keys and webhooks, through the Admin API. Use it on your server only.

Get started

1. Make a key. In the Store Hugs panel, open Shop Settings → Integration API and add an Admin key (sa_live_…). Choose its scopes and, optionally, the IP addresses your servers call from. The key is shown once; keep it in your server's secrets.

2. Install the SDK:

   npm install @storehugs/integration
   

3. Make a client and a first call:

   import { AdminClient } from '@storehugs/integration';
   
   const admin = new AdminClient({ apiKey: process.env.STOREHUGS_ADMIN_KEY! });
   
   const shop = await admin.shop();
   console.log(shop.name, shop.plan, shop.currency);
   

4. Sync. Read every record changed since your last run, oldest change first, and keep the last updatedAt you saw:

   for await (const product of admin.products.all({
       updatedSince: lastSyncedAt,
   })) {
       await saveToErp(product);
       lastSyncedAt = product.updatedAt ?? lastSyncedAt;
   }
   

5. Write safely. Every write is retried with the same Idempotency-Key (see retries). Pass the updatedAt you read with a change, so a newer edit is never overwritten (409 edit_conflict):

   const product = await admin.products.get(12);
   await admin.products.update(
       12,
       { price: 19.5 },
       { unmodifiedSince: product.updatedAt ?? undefined },
   );
   

The key names the shop; there's no shop id to pass. A request from a browser (with an Origin header) is refused.

Options

Scopes

Each method needs the scope it names. A key without it gets 403 insufficient_scope.

Lists and sync

Every resource with a list has two methods:

• list(query?) resolves to one CursorPage<T>: data, and meta.nextCursor for the next page (null on the last).
• all(query?) is an async iterator over every record, fetching the next page as you read.

They take these query fields, and the resource's filters below:

const page = await admin.orders.list({ status: 'processing', limit: 50 });
const next = page.meta.nextCursor
    ? await admin.orders.list({
          status: 'processing',
          limit: 50,
          cursor: page.meta.nextCursor,
      })
    : null;

Changes with UpdateOptions

Methods that change a record (update, setMembership) take UpdateOptions last:

Other writes take RequestOptions (idempotencyKey, signal, headers).

Models and methods

Each page describes every method in full: its parameters, the fields it sends and gets back, its refusals and an example.