@shoppexio/sdk

Official JavaScript/TypeScript SDK for the Shoppex Developer API.

This package wraps the /dev/v1/* API with a typed client surface for backend integrations, internal tools, and OAuth app installs.

Install

npm install @shoppexio/sdk

Quick start

import { ShoppexClient } from '@shoppexio/sdk';

const client = new ShoppexClient({
  apiKey: process.env.SHOPPEX_API_KEY!,
});

const me = await client.me.get();
const products = await client.products.list({ page: 1, limit: 20 });

for (const product of products.data) {
  console.log(product.uniqid ?? product.id, product.name);
}

There is also a runnable example in examples/basic-usage.ts.

Auth

Use one of these:

• apiKey for your own server-to-server integrations
• accessToken for OAuth installs

Included convenience services

• me
• products
• orders
• customers
• payments
• invoices
• coupons
• webhooks
• resellerProgram
• resellers

This covers the main commerce and ops flows out of the box:

• product reads and writes
• order creation, completion, fulfillment, and refunds
• customer reads and writes
• payment and invoice workflows
• coupon validation and management
• webhook management and delivery logs
• reseller program automation, invites, payouts, embeds, stock purchases, and inventory actions

Pagination helpers

Cursor-based resources expose listAll() and iterateAll() helpers.

const allProducts = await client.products.listAll({ limit: 100 });

for await (const order of client.orders.iterateAll({ limit: 100 })) {
  console.log(order);
}

For page-based webhook delivery logs:

const logs = await client.webhooks.listAllLogs({ page: 1, limit: 100 });

Reseller automation

The SDK wraps the Reseller Developer API for partner tooling and headless reseller workflows.

await client.resellerProgram.update({
  is_enabled: true,
  default_mode: 'BOTH',
  default_commission_percent: 25,
});

const invite = await client.resellers.invite({
  email: '[email protected]',
  mode: 'BOTH',
  product_access: [{
    product_id: '11111111-1111-4111-8111-111111111111',
    commission_percent_override: 30,
    max_quantity: 100,
  }],
});

// Once the invitation is accepted, use the reseller relationship id from
// resellers.list() or the dashboard detail view. Invitation ids are not valid
// for relationship-scoped stock, embed, payout, or analytics calls.
const relationshipId = '22222222-2222-4222-8222-222222222222';

await client.resellers.requestStockPurchase(relationshipId, {
  product_id: '11111111-1111-4111-8111-111111111111',
  quantity: 25,
});

await client.resellers.createEmbedCampaign(relationshipId, {
  name: 'Discord Launch',
  product_ids: ['11111111-1111-4111-8111-111111111111'],
});

Typed core models

For the most common resources, the SDK now defaults to typed shapes:

const orders = await client.orders.list({ limit: 20 });
console.log(orders.data[0].status);

const customers = await client.customers.list({ limit: 20 });
console.log(customers.data[0].email);

const payments = await client.payments.list({ limit: 20 });
console.log(payments.data[0].status);

const coupon = await client.coupons.get('coupon_123');
console.log(coupon.data.code);

const webhook = await client.webhooks.get('wh_123');
console.log(webhook.data.url);

Error handling

import { ShoppexApiError } from '@shoppexio/sdk';

try {
  await client.products.get('missing-id');
} catch (error) {
  if (error instanceof ShoppexApiError) {
    console.error(error.status, error.code, error.docUrl);
    console.error(error.details);
  }
}

Low-level access

If you need an endpoint that is not wrapped yet, use the typed raw client:

const response = await client.raw.GET('/dev/v1/me');

Docs

• Developer API docs: docs.shoppex.io/api-reference/introduction
• SDK docs: docs.shoppex.io/api-reference/sdks