Log inStart for free

Technical documentation

Connect EcomWeb to your own systems.

Every command, module and data path on this page comes from the published @ecomweb/cli and @ecomweb/sdk.

Start for freeSee the developers page

Get started

From nothing to your first read.

The CLI's setup wizard handles the account, the store and the API key. The four steps below usually take about five minutes.

  1. Run the setup wizard

    npx @ecomweb/cli setup asks for your email, sends a six-digit code, then creates and stores an API key once you verify.

  2. Pick a store

    Choose an existing store or create one. The store ref is saved as the active store for every later command.

  3. Read some data

    ecomweb products list --output table confirms the API key, the store and your read access are all correct.

  4. Wire it into the storefront

    Install @ecomweb/sdk and read the same data straight from your storefront.

First-time setupshell
npx @ecomweb/cli setup

# check what the CLI is pointing at
ecomweb auth status
ecomweb stores list --output table

Requires Node.js 18 or newer.

Authentication and configuration

One API key, three ways to supply it.

Config lives in ~/.config/ecomweb/ with file permissions 0600. Command-line flags win first, then environment variables, then the config file.

Environment variables

VariableWhat it does
ECOMWEB_API_KEYAPI key, overriding the config file.
ECOMWEB_STORE_REFStore ref, overriding the active store.
ECOMWEB_API_URLAPI base URL, for pointing at another environment.

Worth knowing

  • Give every environment its own profile: ecomweb setup --profile staging, then add --profile staging to your commands.
  • ecomweb auth status shows which account you're signed in as and which store is active.
  • In the SDK, publicHttp serves public store data while authHttp carries a customer's session.
  • Never ship an API key in storefront code: keys belong on the server, in the CLI or in automation.
Configuration for automationshell
# non-interactive flow, for CI
ecomweb auth register --email team@example.com
ecomweb auth verify --email team@example.com --code 123456
ecomweb init --store-name "Cua Hang Mau"

# or skip the config file entirely
export ECOMWEB_API_KEY=ew_live_...
export ECOMWEB_STORE_REF=cua-hang-mau
ecomweb products list --quiet

Command line

Every part of the store has a command.

Commands are grouped by resource. Each group has list, get, create, update and delete where the resource supports them, plus the shared flags below.

Command groups

GroupCovers
productsProducts, variants, stats and batch operations.
ordersOrders, status transitions, fulfillment, delivery and cancellation.
customersCustomers, addresses and per-customer stats.
categories · collectionsCategories and collections that organise the catalog.
promotions · reviewsPromotion campaigns and customer reviews.
blog-posts · blog-categories · blog-tags · blog-settingsPosts, taxonomy and settings for the content side.
store-pages · store-menus · store-settingsContent pages, menus and store settings.
shipping-methods · shipping-zones · shipping-programsShipping methods, zones and programs.
banners · assetsBanners, images and video, including upload and linking to records.
analytics · stores · auth · healthSales figures, store switching, sessions and connection checks.

Shared flags

--output json|table|csv
Output format. Defaults to json.
--fields · --exclude · --full
Pick, drop or include every field in the response.
--dry-run
Preview the effect without writing anything.
--quiet
Print data only, suppressing the surrounding output.
--profile
Run the command against a different config profile.
--store-ref · --api-key · --api-url
Override the store, API key and API URL for a single command.
Reading and writing from the CLIshell
# read
ecomweb products list --status active --output table --fields id,name,status
ecomweb orders list --status pending --limit 50

# write from JSON, preview before applying
ecomweb products create --stdin --dry-run < product.json
ecomweb products create --stdin < product.json

# same command against another environment
ecomweb products list --profile staging

Write commands take JSON through --stdin or --file, so one command's output can be piped straight into the next.

ecomweb --help lists every group; add --help after a group name to list that group's own commands and flags.

JavaScript SDK

One factory call, eighteen data modules.

createEcomwebSdk takes two HTTP clients and returns modules that are already typed for TypeScript.

How the SDK works

  • Install: add "@ecomweb/sdk": "github:travistech20/ecomweb-sdk" to package.json.
  • IHttpClient is an interface of get, post, put, patch and delete, each returning ApiResponse<T>. You wrap fetch, axios or whatever you already use.
  • unwrap throws when a request fails, unwrapOrNull returns null on 404, ensureSuccess only checks the result. Failures throw ApiClientError with statusCode and code.
  • Detail reads such as products.getBySlug return null when nothing matches, which pairs well with Next.js notFound().

Data modules

  • products
  • collections
  • categories
  • cart
  • orders
  • blog
  • stores
  • search
  • banners
  • shipping
  • promotions
  • paymentMethods
  • reviews
  • customers
  • addresses
  • contentPages
  • menus
  • redirects
Set up and read a producttypescript
import { createEcomwebSdk, ApiClientError } from "@ecomweb/sdk";
import { http } from "./http"; // any IHttpClient: fetch, axios, ky...

const sdk = createEcomwebSdk({ publicHttp: http, authHttp: http });

try {
  const product = await sdk.products.getBySlug("cua-hang-mau", "ao-linen", {
    include_variants: true,
  });

  // getBySlug returns null on 404 instead of throwing
  if (!product) notFound();
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(error.statusCode, error.message);
  }
}

Store data

Paths you can read straight off the URL.

Every path is scoped to a store ref. /public serves public data; /tenant needs a customer session. Responses always carry three fields: success, data and error.

MethodPathReturns
GET/public/stores/{storeRef}Store details and configuration.
GET/public/stores/{storeRef}/products/slug/{slug}A product by slug, with variants on request.
GET/public/stores/{storeRef}/categoriesThe store's categories.
GET/public/stores/{storeRef}/collections/slug/{slug}A collection by slug.
GET/search/public/{storeRef}/catalogProduct search and type-ahead suggestions.
GET · POST · PUT · DELETE/public/stores/{storeRef}/cartA guest cart, identified by the x-session-id header.
POST/public/stores/{storeRef}/ordersCreate an order for a guest.
GET/tenant/stores/{storeRef}/customers/ordersOrders belonging to a signed-in customer.
GET/public/stores/{storeRef}/content-pages/{slug}A content page written in the admin.
GET/public/stores/{storeRef}/menus/ref/{ref}A storefront navigation menu.

The JavaScript SDK already wraps these paths. The table is here for when you call them from another language or need to debug.

Building the storefront

Data on the server, interaction in the browser.

This split keeps listing and detail pages fast while the cart still responds instantly.

  • Read products, categories and content pages in server components through publicHttp: the pages stay cacheable and the API key never ships.
  • Keep the cart in a client component: every call to the cart module needs a stable x-session-id for guests.
  • Serve images at the right size with buildTransformQuery and toRenderUrl instead of downloading originals and scaling them in the browser.
  • Keep old URLs alive with the redirects module, and pull navigation from the menus module so staff can change it from the admin.

See alsoSample storesDevelopers page

AI agents and automation

Read the schema, dry-run, then write.

The CLI is built for coding assistants to drive: output is JSON by default and every write can be previewed first.

  1. Fetch the schema

    ecomweb describe <resource> --operation create or update returns the valid fields before anything is written.

  2. Dry-run it

    Add --dry-run to see how far a change reaches without touching the store.

  3. Apply and record

    Re-run without --dry-run; the JSON result is enough to diff and to keep in a log.

A workflow for coding assistantsshell
# 1 · schema first, before writing anything
ecomweb describe products --operation update

# 2 · preview the change, nothing is written yet
ecomweb products update 42 --stdin --dry-run < patch.json

# 3 · apply it, JSON output the agent can parse
ecomweb products update 42 --stdin --quiet < patch.json

The rule of thumb: keep each command narrow in scope, rehearse on a separate profile, and ask a human before anything that moves prices, stock or orders.

Support

Need more detail for your case?

These pages track the currently published tooling. If your integration isn't covered here, tell the team.

Start for freeContact the team
EcomWeb technical documentation | EcomWeb