Node.js SDK — installation and usage

Overview

Install: npm install @merch/sdk. TypeScript-first, Promise + async/await, ESM and CommonJS, webhook signature verification. Node 18+. The SDK is open-source (MIT) and follows semantic versioning. It abstracts OAuth 2.0 token management, retries with exponential backoff, idempotency keys for write operations, and webhook signature verification.

Requirements

• Node.js 18 or newer
• An active client_id and client_secret from the customer portal
• (Optional) webhook_secret if you receive webhooks

Installation

npm install @merch/sdk

Authentication and client setup

import { MerchClient } from '@merch/sdk';

const client = new MerchClient({
  clientId: process.env.MERCH_CLIENT_ID,
  clientSecret: process.env.MERCH_CLIENT_SECRET,
  region: 'eu',
});
// OAuth 2.0 token cached and rotated automatically

List open quotes

const quotes = await client.quotes.list({ status: 'open', limit: 50 });
quotes.forEach(q => console.log(q.id, q.totalLandedUsd, q.leadTimeDays));

Create an order from a quote

const order = await client.orders.create({
  quoteId: 'qt_a1b2c3',
  deliveryAddress: {
    name: 'Acme HR',
    line1: '123 Oxford St',
    city: 'London',
    country: 'GB',
    postalCode: 'W1A 1AA',
  },
  paymentTerms: 'net30',
});
console.log(order.id, order.expectedDelivery);

Verify and handle a webhook

import { verifyWebhook } from '@merch/sdk/webhooks';

app.post('/webhooks/merch', (req, res) => {
  const event = verifyWebhook(req.body, req.headers['x-merch-signature'], 'whsec_...');
  if (event.type === 'order.shipped') {
    await updateInternalStatus(event.data.orderId, 'shipped');
  }
  res.sendStatus(200);
});

Error handling

The SDK raises typed exceptions for common error cases: AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError. Network errors are retried automatically with exponential backoff (up to 5 attempts by default). 429 responses respect the Retry-After header.

Idempotency

Write operations (orders.create, quotes.accept) accept an idempotency key. The SDK generates one automatically per call; pass your own to safely retry across process boundaries.

Pagination

List endpoints return paginated results. The SDK exposes both an iterator interface (preferred) and explicit cursor handling for advanced use cases. Page size defaults to 50, max 200.

Logging and observability

The SDK integrates with your standard logging library. Set log_level=DEBUG (or equivalent) to see HTTP requests, retries, and rate-limit handling. Sensitive headers (Authorization, webhook secrets) are automatically redacted.

Testing

A sandbox environment is available at https://sandbox.api.merch.am. Sandbox client credentials are issued separately; sandbox state resets weekly. Test webhooks with client.webhooks.test_send() (or the equivalent in your language).

Versioning and upgrades

The SDK follows semantic versioning. Major versions may include breaking changes; minor and patch versions are backwards-compatible. Deprecation notices appear in CHANGELOG.md with a minimum 6-month removal window. Subscribe to GitHub releases for notifications.

Source code

SDK source on GitHub: github.com/merch (placeholder — public access enabled at GA in Q1 2027). Issues and PRs welcome.

Support

Email developers@merch.am with SDK questions. Production-impacting issues escalate to same-day response for clients with active MSA.