shoplazza-admin-api-node

A small TypeScript package for working with the Shoplazza Admin REST API.

This package is scaffolded from the Shoplazza docs and supports multiple public API versions.

• Apps overview: https://www.shoplazza.dev/reference/overview-23
• Overview: https://www.shoplazza.dev/v2026.01/reference/overview-25
• API usage: https://www.shoplazza.dev/v2026.01/reference/api-usage
• Rate limits: https://www.shoplazza.dev/v2026.01/reference/api-rate-limits

As listed on overview-23 on April 9, 2026, the public versions are:

• 2022-01
• 2024-07
• 2025-06
• 2026-01 (beta)

What this package includes

• ShoplazzaAdminClient with a typed request() API
• Multi-version support with forVersion() and per-request apiVersion
• Built-in typed REST resource helpers for articles, customers, orders, and products
• More built-in resources: blogs, collections, categories, collects, pages, themes, locations, files
• Dedicated shop helpers: getShop() and updateShop(shopId, body)
• Factory helpers for nested resources like productImages(productId), productVariants(productId), themeFiles(themeId), and metafields(ownerResource, ownerId)
• Billing helpers from the v2026.01/reference/overview Billing API overview: applicationCharges, recurringApplicationCharges, createUsageCharge(...), customizeRecurringCharge(...), recurringChargeTransactions(...)
• File helpers from Shop&Settings: createUploadFileTask(...), getUploadFileTask(...), getFileDetails(...), deleteFile(...)
• Automatic Access-Token header injection
• Base URL generation using the documented REST pattern: https://{shopdomain}.myshoplaza.com/openapi/{version}/{endpoint}
• Simple retry handling for 429 Too Many Requests
• Exported version metadata/helpers so integrations can choose stable vs beta versions

Install

npm install shoplazza-admin-api-node

Quick start

import { ShoplazzaAdminClient } from "shoplazza-admin-api-node";

const client = new ShoplazzaAdminClient({
  accessToken: process.env.SHOPLAZZA_ACCESS_TOKEN!,
  shop: process.env.SHOPLAZZA_SHOP!,
  apiVersion: "2026-01"
});

const products = await client.products.list({
  page_size: 20
});

const product = await client.products.get("product-id");

const createdOrder = await client.orders.create({
  order: {
    email: "[email protected]"
  }
});

const blogs = await client.blogs.list({ page_size: 20 });
const pages = await client.pages.list({ page_size: 20 });
const collections = await client.collections.list({ page_size: 20 });
const themes = await client.themes.list();
const recurringCharges = await client.recurringApplicationCharges.list();

Typed resource responses now line up with common Shoplazza payload shapes:

const productResponse = await client.products.get("gid://shoplazza/Product/1");

productResponse.data.product.id;
productResponse.data.product.title;
productResponse.data.product.variants?.[0]?.sku;

Additional built-in resources work the same way:

await client.categories.list();
await client.collects.list({ collection_id: "col_123" });
await client.locations.list();
await client.files.list({ page_size: 20 });
await client.getShop();
await client.updateShop("shop_123", {
  shop: {
    customer_email: "[email protected]"
  }
});
await client.applicationCharges.list();
await client.getFileDetails("file_123");

Nested helpers:

await client.productImages("prod_123").list();
await client.productVariants("prod_123").list();
await client.metafields("product", "prod_123").list({ page_size: 50 });
await client.themeFiles("theme_123").get({
  type: "layout",
  location: "theme.liquid"
});

Billing helpers:

await client.applicationCharges.create({
  application_charge: {
    name: "Pro Setup",
    price: "19.99",
    return_url: "https://example.com/billing/return"
  }
});

await client.recurringApplicationCharges.create({
  recurring_application_charge: {
    name: "Growth Plan",
    price: "29.99",
    capped_amount: "200.00",
    terms: "$0.20 per event",
    return_url: "https://example.com/billing/return"
  }
});

await client.createUsageCharge("charge_123", {
  usage_charge: {
    description: "Extra API usage",
    price: "5.00"
  }
});

await client.customizeRecurringCharge("charge_123", {
  recurring_application_charge: {
    capped_amount: "500.00"
  }
});

await client.recurringChargeTransactions("charge_123").list();

File upload helpers:

const task = await client.createUploadFileTask({
  original_source_list: [
    "https://cdn.example.com/banner.png"
  ]
});

await client.getUploadFileTask(task.data.task_id);
await client.getFileDetails("file_123");
await client.deleteFile("file_123");

Multi-version usage

You can switch versions by cloning the client:

const latestClient = new ShoplazzaAdminClient({
  accessToken: process.env.SHOPLAZZA_ACCESS_TOKEN!,
  shop: process.env.SHOPLAZZA_SHOP!,
  apiVersion: "2026-01"
});

const stableClient = latestClient.forVersion("2025-06");
const legacyClient = latestClient.forVersion("2022-01");

await stableClient.products.list();
await legacyClient.orders.list();

You can also override the version for a single request:

const response = await client.request({
  apiVersion: "2024-07",
  method: "GET",
  path: "products"
});

If you want version-aware branching in your app:

import {
  getLatestShoplazzaApiVersion,
  getShoplazzaApiVersionDetails,
  SHOPLAZZA_API_VERSION_DETAILS
} from "shoplazza-admin-api-node";

const latestStable = getLatestShoplazzaApiVersion({ includeBeta: false });
const latestAny = getLatestShoplazzaApiVersion();
const details = getShoplazzaApiVersionDetails("2026-01");

Custom requests

Use request() when you want to call an endpoint that does not fit the built-in helpers:

const response = await client.request({
  method: "GET",
  path: "shop",
  query: {
    fields: ["id", "name"]
  }
});

Resource helpers

Each built-in resource exposes:

• list(query?)
• get(id, query?)
• create(body, query?)
• update(id, body, query?)
• delete(id, query?)
• withVersion(apiVersion)

You can also create your own helper:

const paymentOrders = client.resource("shoplazza-payment/payment-orders");
const list = await paymentOrders.list();
const legacyPaymentOrders = paymentOrders.withVersion("2024-07");

Theme files use a specialized helper because the docs expose file operations and version history through custom endpoints:

const themeFiles = client.themeFiles("theme_123");

await themeFiles.get({
  type: "layout",
  location: "theme.liquid"
});

await themeFiles.create({
  doc: {
    type: "sections",
    location: "sections/hero.liquid",
    content: "<section>Hero</section>"
  }
});

await themeFiles.update({
  doc: {
    type: "sections",
    location: "sections/hero.liquid",
    content: "<section>Updated Hero</section>"
  }
});

await themeFiles.listVersions({
  type: "sections",
  location: "sections/hero.liquid"
});

await themeFiles.listVersionRecords();

Configuration

const client = new ShoplazzaAdminClient({
  accessToken: "token",
  shop: "your-shop",
  apiVersion: "2026-01",
  maxRetries: 4,
  retryDelayMs: 500
});

Options

• accessToken: Shoplazza Admin API access token
• shop: shop subdomain or full *.myshoplaza.com hostname
• apiVersion: defaults to 2026-01; supported public versions are 2022-01, 2024-07, 2025-06, and 2026-01
• baseDomain: defaults to myshoplaza.com
• fetch: optional custom fetch implementation
• headers: optional default headers
• maxRetries: retries for rate-limit or transient failures
• retryDelayMs: base retry delay in milliseconds

Notes

• The package targets the REST Admin API only.
• Response payloads follow Shoplazza's common envelope shape: { code, message, data }.
• Built-in resource helpers are intentionally light wrappers around the documented REST URL pattern, so you can still use request() for endpoints with custom shapes.
• The package exports SUPPORTED_SHOPLAZZA_API_VERSIONS, DEFAULT_SHOPLAZZA_API_VERSION, and isSupportedShoplazzaApiVersion() for version-aware integrations.
• It now also exports SHOPLAZZA_API_VERSION_DETAILS, getLatestShoplazzaApiVersion(), getShoplazzaApiVersionDetails(), and compareShoplazzaApiVersions().