Makeships Beta
Menu
Makeships Commerce · setup guide

Set up Makeships Commerce

Install the store in your own cloud, set up payments, tax, shipping and products from the admin, then connect it to Inventory and Procurement so stock and buying run themselves.

Time
About 30 minutes to install, an hour to configure the store
Local ports
App 3000 · Postgres 5435
Who does what
A developer installs; your team does the first-run setup in the app.

Before you start

Node.js 20.9+

22 LTS recommended, with pnpm

Postgres 16

Docker Compose starts one locally; use a managed Postgres in production

A domain on HTTPS

e.g. shop.example.com

Email provider

Resend, SMTP and others, chosen in the admin

Payments

Razorpay or Stripe keys; cash on delivery needs nothing

Optional

Shiprocket, Delhivery or AfterShip; an Anthropic or AI Gateway key for the AI features

For your developer

Install

  1. 1

    Get the code and create the settings file

    Copy the example settings and fill them in (table below). Generate secrets with openssl rand -hex 32.

    cd humlens/apps/humlens-commerce
cp .env.example .env
  2. 2

    Start the database and create the tables

    Docker Compose starts Postgres on port 5435. In production, point DATABASE_URL at your managed Postgres instead.

    docker compose up -d
pnpm install
pnpm migrate
  3. 3

    Run it

    The store opens at http://localhost:3000 and the admin at /admin.

    pnpm dev
  4. 4

    Deploy to production

    The self-host stack builds the image, runs migrations in a one-off container, then starts the store with Postgres and a volume for uploaded images. On a plain Node host, run pnpm migrate before pnpm build and pnpm start on every deploy.

    cp .env.selfhost.example .env
docker compose -f docker-compose.selfhost.yml up -d --build

For your developer

Settings

These go in the .env file, or your host's secret manager in production.

Setting Needed What it is
PAYLOAD_SECRET Required Long random string. Also encrypts keys saved under Integrations, so never change it after launch.
DATABASE_URL Required Postgres connection string
PAYLOAD_PUBLIC_SERVER_URL, NEXT_PUBLIC_SERVER_URL Required The store's public address, no trailing slash. Inventory and Procurement send change notifications here.
PREVIEW_SECRET Required Random string for draft previews
STORE_CURRENCIES, STORE_DEFAULT_CURRENCY Required e.g. INR,USD and INR
HUMLENS_SSO_SECRET When connected The same 32+ character random value in every connected app, so people move between apps without signing in again.
NEXT_PUBLIC_HUMLENS_INVENTORY_URL, …_PROCUREMENT_URL, …_COMMERCE_URL When connected Each app's public address. Apps with an address appear as links in the menu.
OPERATIONS_SYNC_MINUTES Optional Minutes between automatic syncs with Inventory and Procurement. Default 5.
STOCK_HOLD_MINUTES Optional How long stock is held while a customer pays. Default 30.
DISABLE_SCHEDULER, CRON_SECRET Serverless only Turn off the built-in schedule and call POST /api/operations/sync from a cron with the secret as a bearer token.
LICENSE_KEY Optional Your Growth or Enterprise license; it can also be pasted in the admin.
RAZORPAY_*, STRIPE_*, SHIPROCKET_*, DELHIVERY_* Optional Keys saved in the admin take priority over these.

For your team

First-run setup

Done in the app's own screens, in this order. No code involved.

  1. 01

    Create the first admin

    /admin

    The first account you create becomes the admin. Pick a store template, or start empty.

  2. 02

    Brand and configure the store

    Store Settings

    Name, logos and theme; currency, GST mode and rate; checkout rules; and under Inventory, the low-stock threshold.

  3. 03

    Connect payments and email

    Connect › Integrations

    Add Razorpay or Stripe and an email provider, then press Test connection on each.

  4. 04

    Set up shipping

    Connect › Shipping & logistics

    Pickup address, default parcel size, courier and returns policy. Skip this for digital-only stores.

  5. 05

    Add products

    Catalog › Products

    Set the product type and give every stocked product and variant a SKU. The SKU is what links the store to Inventory.

  6. 06

    Activate your plan

    Store Settings › Plan & license

    Paste your Growth license to turn on AI search, newsletters and Zoho Books invoicing. The free Community plan needs nothing.

Commerce · Inventory · Procurement

Connect the apps

Connect the store last, after Inventory has your opening stock. You need an API key from each app, created by an Owner or Admin there.

  1. 1

    Create API keys

    Inventory and Procurement › Settings › API keys

    Create a key named "Store" in each app and copy it straight away: it's shown once. Inventory keys start hinv_, Procurement keys start hprc_.

  2. 2

    Connect them in the store

    Connect › Integrations › Operations

    For each app, paste its address and key, press Test connection, pick the warehouse, choose the options, Save, then Sync now.

  3. 3

    Confirm notifications

    Inventory and Procurement › Settings › Integrations

    Each should show Store notifications: Working. From then on, stock changes reach the store within seconds.

Setting up all three? Do them in this order: Commerce, Inventory, then Procurement, and connect them last.

Check it works

  • The storefront and /admin load over HTTPS, and you can sign in.
  • Integrations shows Connected for your payment method and email.
  • A test order places successfully and the confirmation email arrives.
  • With Inventory connected: the order appears under Connect › Sync activity as Done, and Inventory's stock drops by the same amount.
  • Buying more than Inventory has stops checkout with "Only N of … left."

Troubleshooting

Payments succeed but orders don't appear

Register the payment webhook URL (https://your-store/api/payments/razorpay/webhooks or …/stripe/webhooks) with your provider.

Products show sold out right after connecting

Record opening stock in Inventory, then press Sync now.

"rejected the API key" in Sync activity

The key was revoked or its creator lost their role. Create a new key, paste it in, and press Retry on the item.

Stock only updates when you press Sync now

DISABLE_SCHEDULER is set without a cron. Remove it, or add the cron call.

Going live

  • PAYLOAD_SECRET is a fresh random value and never changes after launch.
  • pnpm migrate runs on every deploy.
  • Payment and courier webhooks use the production domain.
  • Daily database backups, with a restore tested once.
  • No demo data (pnpm seed) in the production database.

Rather have us set it up?

Our team can install Commerce in your AWS, GCP or Azure account and configure it with you.

Talk to us Back to Commerce

Other setup guides

Inventory Procurement