API Documentation

Everything you need to integrate nanocart into your site.

https://api.nanocart.io

Building with an AI coding agent? Install the official NanoCart skill — docs.nanocart.io → Build with AI — or point your tool at docs.nanocart.io/llms-full.txt.

Widget Integration

Add the nanocart widget to any page with a single script tag. No build step, no dependencies.

Script Tag

Include this once per page, replacing your-store with your store ID:

HTML

<script src="https://cdn.nanocart.io/v1/nanocart.min.js"
  data-store-id="your-store"></script>

Button Types

Use data attributes to create interactive buttons. All you need is the product slug from your admin panel.

Attribute	Behavior	Example
data-nanocart-buy="slug"	Adds product to cart and opens the cart drawer. Best for "Buy Now" actions.	`<button data-nanocart-buy="trucker-hat">Buy Now</button>`
data-nanocart-add="slug"	Adds product to cart and opens the cart drawer. Same as buy, use whichever label fits.	`<button data-nanocart-add="trucker-hat">Add to Cart</button>`
data-nanocart-product="slug"	Opens a product detail modal with image, variant selector, and add-to-cart.	`<button data-nanocart-product="trucker-hat">View Details</button>`

Full Example

HTML

<!DOCTYPE html>
<html>
<body>
  <h1>My Store</h1>

  <button data-nanocart-buy="trucker-hat">Buy Now</button>
  <button data-nanocart-product="trucker-hat">View Details</button>

  <script src="https://cdn.nanocart.io/v1/nanocart.min.js"
    data-store-id="your-store"></script>
</body>
</html>

Theming

The widget is fully themeable through a stable, documented API — script-tag attributes for the common knobs, and CSS custom properties on the host element (id nanocart-widget) for complete control. Merchants can also theme with zero code from the admin portal (Settings → Widget Appearance).

HTML

<!-- Attributes: light/dark base + accent -->
<script src="https://cdn.nanocart.io/v1/nanocart.min.js"
  data-store-id="your-store"
  data-theme="light"
  data-accent-color="#EF3E32"></script>

CSS

/* Full control: set --nc-* variables on the stable host id */
#nanocart-widget {
  --nc-accent: #EF3E32;
  --nc-bg: #1d2230;
  --nc-radius: 12px;
}

Your page CSS always wins over portal settings and attributes. The complete variable list (--nc-accent, --nc-bg, --nc-surface, --nc-border, --nc-text, --nc-text-muted, --nc-text-dim, --nc-text-strong, --nc-danger, --nc-success, --nc-radius, --nc-font) with defaults is documented in the support docs theming guide.

Product Alerts Signup (Pro/Expert)

Capture emails for product updates with the <nanocart-signup> element — bare email field + button in your store color; add show-options to render the option checkboxes configured in the portal (Subscribers page). Renders nothing unless the store is Pro/Expert with Product Alerts enabled. Style via nanocart-signup::part(row|input|button|option|consent|message); override text with the label, placeholder, success-message, and error-message attributes.

HTML

<nanocart-signup show-options></nanocart-signup>

Public endpoints (no auth): GET /shop/{storeId}/alerts-config returns the form config (options, consent, accent) or {"enabled": false}; POST /shop/{storeId}/alerts-signup accepts {email, options[], consent}. Bot protection is invisible (honeypot + timing + rate limits) — no captcha needed.

JavaScript API

The widget exposes window.nanocart for programmatic control:

// Add product by slug
nanocart.addBySlug('trucker-hat');

// Open product detail modal
nanocart.viewProduct('trucker-hat');

// Cart controls
nanocart.open();
nanocart.close();
nanocart.toggle();
nanocart.getItems();
nanocart.getCount();
nanocart.getSubtotal();
nanocart.clear();

Web Component: <nanocart-product>

Embed a fully self-contained product card anywhere on your page using the custom element. No JavaScript required beyond the widget script.

HTML

<nanocart-product slug="trucker-surf-hat"></nanocart-product>

The element renders inside a Shadow DOM, so its styles are fully isolated from your page CSS. It displays the product image, name, price, variant selector (including multi-axis variants), and an add-to-cart button — all synced with your store's live data.

Attributes

Attribute	Required	Description
slug	required	Product slug. Must match a slug returned by the products endpoint.

Multi-axis variant support

When a product has multiple option axes (e.g. Size and Color), the component renders a separate selector for each axis. The active variant is resolved from the combination of all selected values using the optionValues map on each variant (see Get Product).

HTML

<!-- Single product card -->
<nanocart-product slug="trucker-surf-hat"></nanocart-product>

<!-- Multiple cards side by side -->
<div style="display:flex;gap:16px">
  <nanocart-product slug="trucker-surf-hat"></nanocart-product>
  <nanocart-product slug="board-shorts"></nanocart-product>
</div>

Authentication

Public endpoints (products, categories, checkout) require no authentication. They're meant to be called from your storefront.

Admin endpoints require an API key passed in the x-api-key header. You can find your API key in the admin panel under Settings.

bash

curl https://api.nanocart.io/shop/my-store/admin/products \
  -H "x-api-key: sc_live_your_api_key_here"

API Key Format: sc_live_ followed by 64 hex characters. Keep your API key secret — it provides full admin access to your store.

Conventions

Prices

All monetary values are in cents (integers). Divide by 100 for display.

API Value	Display
999	$9.99
2800	$28.00
0	$0.00 (free)

Multi-currency: Each store has a single currency field (e.g. usd, eur, gbp). All price values in the API are in that currency's minor unit (cents for USD, pence for GBP, etc.). The currency is returned in the storefront config and store object so you can format amounts correctly for your locale.

Pagination

List endpoints return a lastKey field. If non-null, pass it as a query parameter to get the next page:

GET /shop/my-store/products?limit=20&lastKey=eyJzdG9yZUlkIjoi...

Dates

All timestamps are ISO 8601 UTC strings: 2026-02-24T15:30:00Z

Response Format

All responses return JSON with appropriate HTTP status codes. Error responses include an error field and optional code field.

Service Tiers

Each store has a tier that determines limits. Upgrade from the admin panel or via the subscription API.

Limit	Free	Standard	Pro	Expert
Price	$0	$5/mo	$10/mo	$25/mo
Active Products	2	25	100	Unlimited
Monthly Orders	5	500	5,000	Unlimited
Coupons	1	5	10	Unlimited
File Upload	5 MB	25 MB	50 MB	500 MB
Shipping Methods	Flat rate, Free	All	All	All
Local Pickup	No	Yes	Yes	Yes

Public API

These endpoints require no authentication. Call them from your storefront to display products and process orders.

GET /shop/{storeId}/products

List active products with optional filtering, sorting, and pagination.

Query Parameters

Parameter	Type	Default	Description
category	string	—	Filter by category slug
sort	string	newest	`newest`, `price`, or `featured`
limit	integer	50	Max results per page (max 50)
lastKey	string	—	Pagination token from previous response

Response

JSON

{
  "products": [
    {
      "productId": "dd9392ed-ea5a-494c-adbc-a8ce5288c2e8",
      "slug": "trucker-surf-hat",
      "name": "Trucker Surf Hat",
      "price": 2800,
      "compareAtPrice": null,
      "images": ["https://images.unsplash.com/photo-..."],
      "variants": [
        {
          "variantId": "d90da05a",
          "name": "Adjustable / Navy",
          "price": 2800,
          "sku": "TSH-ADJ-NVY",
          "optionValues": { "Size": "Adjustable", "Color": "Navy" }
        }
      ],
      "featured": false,
      "categoryId": "abc-123",
      "inventory": 50,
      "productType": "physical",
      "status": "active",
      "createdAt": "2026-02-23T20:59:28Z",
      "updatedAt": "2026-02-23T20:59:28Z"
    }
  ],
  "lastKey": null
}

GET /shop/{storeId}/products/{slug}

Get full details for a single product by slug.

Response

JSON

{
  "product": {
    "productId": "dd9392ed-ea5a-494c-adbc-a8ce5288c2e8",
    "slug": "trucker-surf-hat",
    "name": "Trucker Surf Hat",
    "description": "Classic trucker hat with embroidered surf logo.",
    "price": 2800,
    "compareAtPrice": null,
    "categoryId": "abc-123",
    "images": ["https://images.unsplash.com/photo-..."],
    "variants": [
      {
        "variantId": "d90da05a",
        "name": "Adjustable / Navy",
        "price": 2800,
        "sku": "TSH-ADJ-NVY",
        "inventory": 25,
        "optionValues": { "Size": "Adjustable", "Color": "Navy" }
      }
    ],
    "options": [
      { "name": "Size", "values": ["Adjustable"] },
      { "name": "Color", "values": ["Navy", "Black"] }
    ],
    "inventory": 50,
    "productType": "physical",
    "shippingRequired": true,
    "taxable": true,
    "tags": ["hats", "surf"],
    "featured": false,
    "status": "active",
    "createdAt": "2026-02-23T20:59:28Z",
    "updatedAt": "2026-02-23T20:59:28Z"
  }
}

Errors

Status	Response
404	`{"error": "Product not found"}`

GET /shop/{storeId}/categories

List all active categories for a store, sorted by sortOrder. Categories support a parent/child hierarchy via the parentId field. Top-level categories have an empty parentId. Subcategories reference their parent's categoryId.

Response

JSON

{
  "categories": [
    {
      "categoryId": "cat-001",
      "name": "Men's",
      "slug": "mens",
      "description": "Men's clothing and accessories",
      "image": "https://...",
      "parentId": "",
      "sortOrder": 0,
      "status": "active"
    },
    {
      "categoryId": "cat-002",
      "name": "Shirts",
      "slug": "shirts",
      "description": "Men's shirts",
      "image": "https://...",
      "parentId": "cat-001",
      "sortOrder": 0,
      "status": "active"
    },
    {
      "categoryId": "cat-003",
      "name": "Pants",
      "slug": "pants",
      "description": "",
      "image": "",
      "parentId": "cat-001",
      "sortOrder": 1,
      "status": "active"
    }
  ]
}

Category Fields

Field	Type	Description
categoryId	string	Unique category identifier
name	string	Category display name
slug	string	URL-friendly name (unique within store)
description	string	Optional description
image	string	Optional image URL (for category cards)
parentId	string	Empty string for top-level categories. Set to a parent `categoryId` to make this a subcategory.
sortOrder	number	Display order (lower = first)
status	string	`active` or `hidden`

Subcategory pattern: To build a hierarchical category tree, filter categories where parentId is empty to get top-level parents, then filter where parentId === parent.categoryId to get children. Products are assigned to a single categoryId — when displaying a parent category, you may want to also include products from its subcategories.

POST /shop/{storeId}/coupons/validate

Validate a coupon code and calculate the discount amount.

Request Body

JSON

{
  "code": "SAVE20",
  "subtotal": 4999
}

Response (valid)

JSON

{
  "valid": true,
  "type": "percent_off",
  "value": 20,
  "discountAmount": 999,
  "message": "20% off applied!"
}

Response (invalid)

JSON

{
  "valid": false,
  "message": "This coupon has expired"
}

Coupon Types: percent_off, fixed_amount, free_shipping

GET /shop/{storeId}/payment-methods

Returns which payment processors are configured for the store. Use this to decide which checkout buttons to show — only display buttons for processors that are actually enabled.

Response

JSON

{
  "stripe": true,
  "paypal": false
}

Both fields are booleans. A value of false means that processor is not configured for the store — do not show its checkout button. If both are false, show a "payments not configured" message rather than a dead button.

The nanocart widget calls this endpoint automatically on first cart open and caches the result for the page session. If you are building a custom checkout UI, fetch this endpoint once and render buttons accordingly.

POST /shop/{storeId}/checkout

Create a checkout session. Validates inventory, applies coupons, calculates shipping and tax, and returns a payment URL to redirect the customer to. Supports Stripe and PayPal.

Request Body

JSON

{
  "items": [
    {
      "productId": "dd9392ed-ea5a-494c-adbc-a8ce5288c2e8",
      "variantId": "d90da05a",
      "quantity": 2
    }
  ],
  "email": "customer@example.com",
  "couponCode": "SAVE20",
  "shippingMethod": "standard",
  "processor": "stripe"
}

Field	Type	Required	Description
items	array	required	Cart items with productId, optional variantId, and quantity
email	string	required	Customer email for order confirmation
couponCode	string	optional	Coupon code to apply
shippingMethod	string	optional	`standard` (default) or `local_pickup`
processor	string	optional	`stripe` (default) or `paypal` — must match a processor configured for the store

Response

JSON

{
  "sessionUrl": "https://www.sandbox.paypal.com/checkoutnow?token=...",
  "orderId": "a1b2c3d4-e5f6-..."
}

Redirect the customer to sessionUrl to complete payment. For Stripe this is a checkout.stripe.com URL; for PayPal it is a paypal.com approval URL. The redirect and return flow is identical from your code's perspective regardless of processor.

Errors

Status	Error
400	`Cart is empty`
400	`Email address is required for checkout.`
400	`Product {id} is not available`
400	`{item} is out of stock`
400	`PayPal is not configured for this store`
403	`This store has reached its monthly order limit`

Redirect URLs: After payment, the customer is redirected back to your site using the Referer or Origin header. Store the orderId in localStorage before redirecting so you can look up the order on your success page. This works the same for both Stripe and PayPal.

GET /shop/{storeId}/orders/{orderId}?email=customer@example.com

Look up an order by ID. Requires the customer's email for verification.

Query Parameters

Parameter	Type	Required	Description
email	string	required	Must match the order's email

Response

JSON

{
  "order": {
    "orderId": "a1b2c3d4-e5f6-...",
    "orderNumber": "MYS-1001",
    "email": "customer@example.com",
    "customerName": "John Doe",
    "items": [
      {
        "productId": "dd9392ed-...",
        "name": "Trucker Surf Hat",
        "variantName": "Adjustable / Navy",
        "price": 2800,
        "quantity": 2
      }
    ],
    "subtotal": 5600,
    "shippingCost": 499,
    "shippingMethod": "standard",
    "taxAmount": 336,
    "discountAmount": 0,
    "total": 6435,
    "shippingAddress": {
      "name": "John Doe",
      "line1": "123 Main St",
      "city": "Charleston",
      "state": "SC",
      "zip": "29401",
      "country": "US"
    },
    "status": "paid",
    "createdAt": "2026-02-24T12:00:00Z"
  }
}

GET /shop/{storeId}/storefront-config

Get the storefront configuration for a hosted store. Used by the storefront SPA on page load to get template, branding, and content settings. Only works for stores with an active hosted plan.

Response

JSON

{
  "storeId": "my-store",
  "storeName": "My Store",
  "currency": "usd",
  "template": "classic",
  "accentColor": "#418a9e",
  "backgroundColor": "#FFFFFF",
  "textColor": "#333333",
  "storeDescription": "Your store description here",
  "aboutContent": "About page content...",
  "aboutTitle": "About My Store",
  "aboutImage": "https://...",
  "heroTitle": "Welcome to My Store",
  "heroLayout": "center",
  "heroImage": "",
  "logo": "https://...",
  "showStoreName": true,
  "favicon": "",
  "announcementBar": {
    "enabled": false,
    "text": "",
    "backgroundColor": "#418a9e",
    "textColor": "#FFFFFF"
  },
  "socialLinks": {
    "instagram": "",
    "twitter": "",
    "facebook": "",
    "tiktok": "",
    "youtube": ""
  },
  "showPoweredBy": true
}

GET /shop/resolve-domain?domain={domain}

Look up a custom domain to find the associated store. Used by the hosted storefront SPA when running on a custom domain instead of a *.nanocart.io subdomain.

Query Parameters

Parameter	Type	Required	Description
domain	string	required	The custom domain to resolve (e.g. `shop.mybrand.com`)

Response

JSON

{
  "storeId": "my-store"
}

Errors

Status	Response
400	`{"error": "domain parameter is required"}`
404	`{"error": "Domain not found"}`

GET /shop/{storeId}/donation-config/{campaignId}

Configuration for the donate popup: amounts, frequencies, button text, branding. _default as the campaignId resolves the store's oldest active campaign. Inactive or missing campaigns return {"enabled": false}. Cached 5 minutes.

Response

JSON

{
  "enabled": true,
  "campaignId": "general-support",
  "name": "Support BlockFlockNow",
  "description": "Help cover our operating costs.",
  "buttonText": "Donate Now",
  "currency": "usd",
  "suggestedOneTime": [500, 1000, 2500, 5000, 10000],
  "suggestedMonthly": [500, 1000, 2000, 5000],
  "allowCustomAmount": true,
  "frequencies": ["one_time", "monthly"],
  "defaultFrequency": "one_time",
  "processors": { "stripe": true, "paypal": false },
  "recurringProcessors": { "stripe": true },
  "branding": true
}

GET /shop/{storeId}/donation-stats/{campaignId}

Live campaign stats for the <nanocart-donate-stats> widget. Only fields the merchant enabled in the campaign's stats settings are present — a disabled field is absent, not zero, so a "count only" widget receives no money figures at all. Cached 5 minutes.

Response

JSON

{
  "enabled": true,
  "campaignId": "general-support",
  "name": "Support BlockFlockNow",
  "currency": "usd",
  "branding": true,
  "showButton": true,
  "donationCount": 327,
  "activeMonthlySupporters": 41,
  "totalRaisedCents": 1523400,
  "mrrCents": 61500,
  "monthRaisedCents": 184200,
  "goal": { "amountCents": 250000, "currentCents": 184200, "metric": "month_total", "pct": 74 }
}

POST /shop/{storeId}/donate

Create a donation checkout session and get the redirect URL. The amount, frequency, currency, and campaign relationship are validated server-side — client values are never trusted for money math.

Request Body

JSON

{
  "campaignId": "general-support",
  "amountCents": 2500,
  "frequency": "one_time",
  "email": "donor@example.com",
  "processor": "stripe"
}

Field	Type	Required	Description
campaignId	string	required	Campaign slug, or `_default`
amountCents	integer	required	100–999999. Must be a suggested amount, or any value when the campaign allows custom amounts (one-time only)
frequency	string	required	`one_time` or `monthly` (monthly = Stripe only, preset amounts only)
email	string	optional	Prefills the receipt email at checkout
processor	string	optional	`stripe` (default) or `paypal` (one-time only)

Response

JSON

{ "sessionUrl": "https://checkout.stripe.com/c/pay/cs_...", "donationId": "f8647d18-..." }

Redirect the donor to sessionUrl. Donation records are finalized by webhooks — never rely on the browser's return. Error codes: CAMPAIGN_NOT_FOUND, AMOUNT_NOT_ALLOWED, FREQUENCY_NOT_ALLOWED, PROCESSOR_NOT_SUPPORTED, STRIPE_NOT_CONFIGURED, PAYPAL_NOT_CONFIGURED.

Admin API

All admin endpoints require authentication via the x-api-key header.

Stores

GET /shop/admin/stores

List all stores you have access to.

Response

JSON

{
  "stores": [
    {
      "storeId": "my-store",
      "name": "My Store",
      "tier": "standard",
      "status": "active",
      "domain": "https://mystore.com",
      "contactEmail": "me@mystore.com",
      "currency": "usd",
      "brandColor": "#418a9e",
      "apiKey": "sc_live_...",
      "createdAt": "2026-02-20T10:00:00Z"
    }
  ]
}

POST /shop/admin/stores

Create a new store. Returns the store details and API key.

Request Body

JSON

{
  "storeId": "my-store",
  "name": "My Store",
  "domain": "https://mystore.com",
  "contactEmail": "me@mystore.com",
  "stripePublishableKey": "pk_live_...",
  "stripeSecretKey": "sk_live_...",
  "stripeWebhookSecret": "whsec_...",
  "brandColor": "#418a9e"
}

Field	Type	Required	Description
storeId	string	required	3-32 chars, lowercase alphanumeric + hyphens
name	string	optional	Display name
domain	string	optional	Your storefront URL
contactEmail	string	optional	Store contact email
stripePublishableKey	string	optional	Stripe publishable key (`pk_live_` or `pk_test_`)
stripeSecretKey	string	optional	Stripe secret key (`sk_live_` or `sk_test_`)
stripeWebhookSecret	string	optional	Stripe webhook secret (`whsec_`)
brandColor	string	optional	Hex color for widget branding

Response (201)

JSON

{
  "store": { ... },
  "apiKey": "sc_live_abc123...",
  "message": "Store created successfully. Save your API key."
}

PUT /shop/admin/stores/{storeId}

Update store settings. Only include fields you want to change.

Request Body

JSON

{
  "name": "New Store Name",
  "domain": "https://newdomain.com",
  "brandColor": "#4292e7",
  "allowedDomains": ["mystore.com", "www.mystore.com"]
}

Allowed Domains: If set, only these domains can call your public API. Max 10 domains. Leave empty to allow all origins.

POST /shop/admin/stores/{storeId}/regenerate-key

Regenerate your API key. The old key becomes invalid immediately.

Response

JSON

{
  "apiKey": "sc_live_new_key_here...",
  "message": "API key regenerated. Old key is now invalid."
}

Products

POST /shop/{storeId}/admin/products

Create a new product.

Request Body

JSON

{
  "name": "Trucker Surf Hat",
  "price": 2800,
  "description": "Classic trucker hat with embroidered surf logo.",
  "categoryId": "abc-123",
  "compareAtPrice": 3500,
  "inventory": 50,
  "images": ["https://..."],
  "variants": [
    {
      "variantId": "d90da05a",
      "name": "Adjustable / Navy",
      "price": 2800,
      "sku": "TSH-ADJ-NVY",
      "inventory": 25,
      "optionValues": { "Size": "Adjustable", "Color": "Navy" }
    }
  ],
  "options": [
    { "name": "Size", "values": ["Adjustable"] },
    { "name": "Color", "values": ["Navy", "Black"] }
  ],
  "productType": "physical",
  "taxable": true,
  "tags": ["hats"],
  "status": "active",
  "featured": false
}

Field	Type	Required	Description
name	string	required	Product name
price	integer	required	Price in cents
description	string	optional	HTML description
categoryId	string	optional	Category UUID
compareAtPrice	integer	optional	Original price for sale display (must be > price)
inventory	integer	optional	Stock quantity. Null = unlimited.
images	array	optional	Array of image URLs
variants	array	optional	Product variants (variantId, name, price, sku, inventory, optionValues). `optionValues` is a key/value map of option axis name → selected value (e.g. `{"Color":"Navy","Size":"Small"}`). Used by the widget and web component for multi-axis variant resolution. Legacy flat-name format still supported.
options	array	optional	Option definitions for variant generation
productType	string	optional	`physical` (default) or `digital`
status	string	optional	`draft` (default), `active`
featured	boolean	optional	Featured product flag
slug	string	optional	URL slug. Auto-generated from name if omitted.
taxable	boolean	optional	Subject to tax (default true)
tags	array	optional	String tags for organization
shippingCost	integer	optional	Per-item shipping cost in cents (for per_item method)
fulfillmentVendorId	string	optional	Route this product to a fulfillment vendor — its orders are emailed to the vendor automatically (Pro/Expert)
vendorSku	string	optional	The vendor's own item number, shown on vendor order sheets. Variants may carry their own `vendorSku` that overrides this.
vendorNotes	string	optional	Per-product instruction for the vendor (e.g. "Front print, design #12")

Response (201)

JSON

{
  "product": {
    "productId": "dd9392ed-...",
    "slug": "trucker-surf-hat",
    "name": "Trucker Surf Hat",
    ...
  }
}

PUT /shop/{storeId}/admin/products

Update an existing product. Only include fields you want to change.

Request Body

JSON

{
  "productId": "dd9392ed-ea5a-494c-adbc-a8ce5288c2e8",
  "price": 3200,
  "inventory": 40,
  "status": "active"
}

Field	Type	Required	Description
productId	string	required	Product UUID to update

All other fields from Create are accepted. Only provided fields are updated.

DELETE /shop/{storeId}/admin/products

Archive a product. It remains in the database but is hidden from public listings.

Request Body

JSON

{
  "productId": "dd9392ed-ea5a-494c-adbc-a8ce5288c2e8"
}

Field	Type	Required	Description
name	string	required	Category name
description	string	optional	Category description
image	string	optional	Image URL (use the upload endpoint to get a URL first)
parentId	string	optional	Set to a parent `categoryId` to make this a subcategory. Omit or send empty string for top-level.
sortOrder	number	optional	Display order (default: 0)
status	string	optional	`active` (default) or `hidden`

Coupons

GET /shop/{storeId}/admin/coupons

List all coupons for this store.

JSON

{
  "coupons": [
    {
      "code": "SAVE20",
      "type": "percent_off",
      "value": 20,
      "minOrderAmount": 5000,
      "maxUses": 100,
      "currentUses": 42,
      "expiresAt": "2026-12-31T23:59:59Z",
      "status": "active"
    }
  ]
}

POST /shop/{storeId}/admin/coupons

Create a new coupon.

JSON

{
  "code": "SAVE20",
  "type": "percent_off",
  "value": 20,
  "minOrderAmount": 5000,
  "maxUses": 100,
  "expiresAt": "2026-12-31T23:59:59Z",
  "status": "active"
}

Field	Type	Required	Description
code	string	required	Coupon code (auto-uppercased)
type	string	required	`percent_off`, `fixed_amount`, or `free_shipping`
value	integer	required	Percentage (1-100) or cents amount
minOrderAmount	integer	optional	Minimum subtotal in cents
maxUses	integer	optional	Max number of times coupon can be used
expiresAt	string	optional	ISO datetime when coupon expires

PUT /shop/{storeId}/admin/coupons

Update a coupon. Code is required to identify which coupon to update.

JSON

{
  "code": "SAVE20",
  "value": 25,
  "maxUses": 200
}

DELETE /shop/{storeId}/admin/coupons

Deactivate a coupon.

JSON

{
  "code": "SAVE20"
}

Orders

GET /shop/{storeId}/admin/orders

List orders with optional filtering.

Query Parameters

Parameter	Type	Description
status	string	Filter by status (e.g. `paid`, `shipped`)
from	string	ISO datetime to filter from
to	string	ISO datetime to filter to
limit	integer	Results per page (default 50)
lastKey	string	Pagination token

Response

JSON

{
  "orders": [
    {
      "orderId": "a1b2c3d4-...",
      "orderNumber": "MYS-1001",
      "email": "customer@example.com",
      "customerName": "John Doe",
      "items": [...],
      "subtotal": 5600,
      "shippingCost": 499,
      "taxAmount": 336,
      "discountAmount": 0,
      "total": 6435,
      "status": "paid",
      "trackingNumber": null,
      "createdAt": "2026-02-24T12:00:00Z"
    }
  ],
  "lastKey": null
}

PUT /shop/{storeId}/admin/orders/{orderId}

Update order status, tracking number, or notes.

JSON

{
  "status": "shipped",
  "trackingNumber": "1Z999AA10123456784",
  "notes": "Shipped via UPS"
}

Settings

GET /shop/{storeId}/admin/settings

Get all store settings (tax, shipping, email, order config).

JSON

{
  "settings": {
    "tax_config": {
      "enabled": true,
      "useStripeTax": false,
      "defaultRate": 6
    },
    "shipping_config": {
      "method": "flat_rate",
      "flatRate": 499,
      "freeShippingEnabled": false,
      "freeShippingThreshold": 5000,
      "defaultItemShippingCost": 499,
      "tiers": [],
      "localPickupEnabled": false,
      "localPickupInstructions": ""
    },
    "email_config": {
      "fromEmail": "noreply@mystore.com",
      "fromName": "My Store"
    },
    "order_config": {
      "orderPrefix": "MYS",
      "nextOrderNumber": 1001
    }
  }
}

PUT /shop/{storeId}/admin/settings

Update a specific setting.

JSON

{
  "settingKey": "shipping_config",
  "value": {
    "method": "flat_rate",
    "flatRate": 599,
    "freeShippingEnabled": true,
    "freeShippingThreshold": 7500,
    "localPickupEnabled": true,
    "localPickupInstructions": "Pick up at 123 Main St, 9AM-5PM"
  }
}

Setting Key	Description
tax_config	Sales tax: `enabled` (master toggle), `useStripeTax` (automatic Stripe Tax for Stripe checkouts), `defaultRate` (flat percent applied to PayPal orders, and to Stripe orders when Stripe Tax is off)
shipping_config	Shipping method, rates, free shipping, local pickup
email_config	From email address and name for order emails
order_config	Order number prefix and next number

Shipping Methods: flat_rate (single rate), per_item (per product), tiered (by subtotal), free. Free tier stores are limited to flat_rate and free.

Reports

GET /shop/{storeId}/admin/reports

Get sales reports with revenue, order counts, top products, and tax breakdown.

Query Parameters

Parameter	Type	Default	Description
from	string	2020-01-01	Start date (ISO)
to	string	now	End date (ISO)
status	string	paid,shipped,delivered	Comma-separated order statuses to include

Response

JSON

{
  "period": { "from": "2026-02-01", "to": "2026-02-28" },
  "totalRevenue": 523400,
  "totalOrders": 156,
  "averageOrderValue": 3355,
  "totalTaxCollected": 28450,
  "taxByState": { "SC": 18900, "NC": 6200 },
  "totalShipping": 45200,
  "totalDiscounts": 12300,
  "topProducts": [
    { "productId": "...", "name": "Trucker Hat", "unitsSold": 156, "revenue": 155844 }
  ]
}

Uploads

POST /shop/{storeId}/admin/upload-url

Get a presigned S3 URL for uploading images or digital files. Use the returned fileUrl when creating/updating products or categories.

Request Body

Field	Type	Required	Description
fileName	string	required	Original file name
contentType	string	required	MIME type (e.g. `image/jpeg`, `image/png`)
uploadType	string	required	`product_image`, `digital_file`, `category_image`, or `storefront_image`
fileSizeMB	number	required	File size in megabytes (validated against tier limits)

Upload Types & S3 Paths

uploadType	S3 Path	Use For
`product_image`	`{storeId}/products/{file}`	Product images array
`digital_file`	`{storeId}/digital/{file}`	Downloadable digital products
`category_image`	`{storeId}/categories/{file}`	Category/subcategory card images
`storefront_image`	`{storeId}/storefront/{file}`	Hero images, about page images, logo

Example

JSON

{
  "fileName": "product-photo.jpg",
  "contentType": "image/jpeg",
  "uploadType": "product_image",
  "fileSizeMB": 2.5
}

Response

JSON

{
  "uploadUrl": "https://shoppingcart-assets.s3.amazonaws.com/...?X-Amz-Signature=...",
  "fileUrl": "https://shoppingcart-assets.s3.amazonaws.com/my-store/products/abc.jpg",
  "s3Key": "my-store/products/abc.jpg"
}

Upload your file with a PUT request to uploadUrl with the Content-Type header matching what you specified. Then use fileUrl in your product images array, category image field, etc.

Storefront

GET /shop/{storeId}/admin/storefront

Get the current storefront settings for your store.

Response

JSON

{
  "storefront": {
    "enabled": true,
    "template": "classic",
    "logo": "https://...",
    "showStoreName": true,
    "accentColor": "#418a9e",
    "backgroundColor": "#FFFFFF",
    "textColor": "#333333",
    "heroTitle": "Welcome to My Store",
    "heroLayout": "center",
    "heroImage": "",
    "storeDescription": "Your store description",
    "aboutTitle": "About My Store",
    "aboutContent": "About page content...",
    "aboutImage": "",
    "announcementBar": {
      "enabled": false,
      "text": "",
      "backgroundColor": "#418a9e",
      "textColor": "#FFFFFF"
    },
    "socialLinks": {
      "instagram": "",
      "twitter": "",
      "facebook": "",
      "tiktok": "",
      "youtube": ""
    },
    "showPoweredBy": true
  }
}

PUT /shop/{storeId}/admin/storefront

Update storefront settings. Only include the fields you want to change. Requires an active hosted plan.

Updatable Fields

Field	Type	Description
template	string	Template name: `classic`, `bold`, `compact`
logo	string	Store logo URL (recommended 240×72px). Use upload endpoint with `storefront_image` type.
showStoreName	boolean	Show store name text next to logo in nav (default: true)
accentColor	string	Primary accent color hex (e.g. `#418a9e`)
backgroundColor	string	Page background color hex
textColor	string	Body text color hex
heroTitle	string	Hero section heading (defaults to store name)
heroLayout	string	`center` (default), `image-left`, or `image-right`
heroImage	string	Hero image URL (used with image-left/image-right layouts)
storeDescription	string	Hero description text (displayed below title)
aboutTitle	string	About page heading (defaults to "About {storeName}")
aboutContent	string	About page body content (line breaks preserved)
aboutImage	string	About page image URL
announcementBar	object	`{ enabled, text, backgroundColor, textColor }`
socialLinks	object	`{ instagram, twitter, facebook, tiktok, youtube }`
showPoweredBy	boolean	Show "Powered by Nanocart" in footer
favicon	string	Favicon URL

Example

JSON

{
  "heroTitle": "Welcome to My Shop",
  "heroLayout": "image-right",
  "heroImage": "https://...",
  "accentColor": "#e74c3c",
  "aboutTitle": "Our Story"
}

Tier & Usage

GET /shop/{storeId}/admin/tier

Get current tier info, limits, and usage.

JSON

{
  "tier": "standard",
  "limits": {
    "maxProducts": 25,
    "maxMonthlyOrders": 500,
    "maxCoupons": 5,
    "maxUploadMB": 25,
    "allowedShippingMethods": ["flat_rate", "per_item", "tiered", "free"],
    "localPickup": true
  },
  "usage": {
    "activeProducts": 12,
    "activeCoupons": 2,
    "monthlyOrders": 47
  }
}

Subscriptions

POST /shop/admin/stores/{storeId}/subscribe

Create a Stripe subscription checkout session to upgrade your plan.

JSON

{
  "tier": "pro",
  "billingPeriod": "monthly"
}

Field	Type	Options
tier	string	`standard`, `pro`, `expert`
billingPeriod	string	`monthly`, `annual`

Response

JSON

{
  "sessionUrl": "https://checkout.stripe.com/c/pay/..."
}

GET /shop/admin/stores/{storeId}/subscription

Get current subscription details.

JSON

{
  "tier": "pro",
  "subscriptionId": "sub_...",
  "subscriptionStatus": "active",
  "billingPeriod": "monthly",
  "cancelAtPeriodEnd": false
}

POST /shop/admin/stores/{storeId}/cancel-subscription

Cancel subscription at end of billing period. Store keeps current tier until then.

JSON

{
  "message": "Subscription will cancel at end of billing period."
}

POST /shop/admin/stores/{storeId}/reactivate-subscription

Reactivate a subscription that was scheduled for cancellation. Undoes a cancel without charging anything — the next renewal date is unchanged.

Response

JSON

{
  "message": "Your Standard Widget plan has been reactivated. Your next renewal is unchanged."
}

Errors

Status	Response
400	`{"error": "No subscription found."}`
400	`{"error": "Your subscription is not scheduled for cancellation."}`

Webhooks

Webhooks let nanocart push real-time events to your server when things happen in your store. Configure a webhook URL in the admin panel under Settings → Webhooks.

Verification

Every request includes three headers you should verify before processing:

Header	Description
`x-nanocart-signature`	`sha256=<HMAC-SHA256 hex digest>` — computed over the raw request body using your webhook secret
`x-nanocart-timestamp`	Unix timestamp (seconds) of delivery. Reject if >300s old to prevent replay attacks.
`x-nanocart-delivery`	Unique delivery ID (UUID) for idempotency

Node.js

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const sig = req.headers['x-nanocart-signature'] || '';
  const ts  = req.headers['x-nanocart-timestamp'] || '';

  // Reject stale deliveries
  if (Math.abs(Date.now() / 1000 - parseInt(ts, 10)) > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)        // raw Buffer/string, before JSON.parse
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

app.post('/webhooks/nanocart', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifyWebhook(req, process.env.NANOCART_WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  const event = JSON.parse(req.body);
  // handle event.type ...
  res.sendStatus(200);
});

Event Types

All events share a common envelope:

JSON

{
  "eventType": "order.created",
  "storeId": "my-store",
  "timestamp": "2026-06-17T14:00:00Z",
  "data": { ... }
}

EVENT order.created

Fired when a Stripe checkout session completes and an order is recorded.

JSON

{
  "eventType": "order.created",
  "storeId": "my-store",
  "timestamp": "2026-06-17T14:00:00Z",
  "data": {
    "orderId": "a1b2c3d4-...",
    "orderNumber": "MYS-1001",
    "email": "customer@example.com",
    "customerName": "John Doe",
    "items": [
      { "productId": "...", "name": "Trucker Hat", "variantName": "Navy", "price": 2800, "quantity": 2 }
    ],
    "subtotal": 5600,
    "shippingCost": 499,
    "taxAmount": 336,
    "discountAmount": 0,
    "total": 6435,
    "status": "paid",
    "createdAt": "2026-06-17T14:00:00Z"
  }
}

EVENT order.shipped

Fired when an order status is updated to shipped (via PUT /admin/orders/{orderId}).

JSON

{
  "eventType": "order.shipped",
  "storeId": "my-store",
  "timestamp": "2026-06-17T16:00:00Z",
  "data": {
    "orderId": "a1b2c3d4-...",
    "orderNumber": "MYS-1001",
    "email": "customer@example.com",
    "trackingNumber": "1Z999AA10123456784",
    "status": "shipped"
  }
}

EVENT order.cancelled

Fired when an order status is updated to cancelled.

JSON

{
  "eventType": "order.cancelled",
  "storeId": "my-store",
  "timestamp": "2026-06-17T17:00:00Z",
  "data": {
    "orderId": "a1b2c3d4-...",
    "orderNumber": "MYS-1001",
    "email": "customer@example.com",
    "status": "cancelled"
  }
}

EVENT product.low_stock

Fired when a product variant's inventory drops to 5 or below after a completed order.

JSON

{
  "eventType": "product.low_stock",
  "storeId": "my-store",
  "timestamp": "2026-06-17T14:01:00Z",
  "data": {
    "productId": "dd9392ed-...",
    "productName": "Trucker Surf Hat",
    "slug": "trucker-surf-hat",
    "variantId": "d90da05a",
    "variantName": "Adjustable / Navy",
    "inventory": 3
  }
}

EVENT checkout.abandoned

Fired when a Stripe checkout session expires without payment (after ~30 min).

JSON

{
  "eventType": "checkout.abandoned",
  "storeId": "my-store",
  "timestamp": "2026-06-17T14:35:00Z",
  "data": {
    "orderId": "a1b2c3d4-...",
    "email": "customer@example.com",
    "items": [
      { "productId": "...", "name": "Trucker Hat", "quantity": 1, "price": 2800 }
    ],
    "subtotal": 2800
  }
}

EVENT webhook.test

Sent when you click "Send test event" in the admin panel. Use it to confirm your endpoint is reachable and your signature verification is correct.

JSON

{
  "eventType": "webhook.test",
  "storeId": "my-store",
  "timestamp": "2026-06-17T14:00:00Z",
  "data": {
    "message": "This is a test event from nanocart."
  }
}

Subscribers

Email capture, broadcasts, and custom email templates. Requires a Pro or Expert plan; other tiers receive 403 with "code": "TIER_LIMIT". Subscribers sign up through the <nanocart-signup> widget element or your hosted storefront; every broadcast automatically carries a signed unsubscribe link, and unsubscribed/bounced/complained addresses are suppressed for you.

GET /shop/{storeId}/admin/subscribers

List subscribers, paginated.

Query Parameters

Parameter	Type	Description
limit	integer	Results per page (default 50)
lastKey	string	Pagination token from the previous response

Response

JSON

{
  "subscribers": [
    {
      "email": "maya@example.com",
      "status": "active",
      "options": ["New drops"],
      "consent": true,
      "source": "widget",
      "createdAt": "2026-07-18T10:00:00Z"
    }
  ],
  "lastKey": null
}

DELETE /shop/{storeId}/admin/subscribers/{email}

Remove a subscriber. URL-encode the email address in the path.

POST /shop/{storeId}/admin/subscribers/send

Send a broadcast email to your subscribers. Runs as an async job — poll the sends history for status.

Request Body

JSON

{
  "kind": "product",
  "productId": "dd9392ed-...",
  "subject": "New drop just landed",
  "message": "Fresh colors are live — grab yours.",
  "productLink": "https://mystore.com/shop",
  "templateId": "tpl-123",
  "options": ["New drops"],
  "testOnly": false
}

Field	Type	Required	Description
kind	string	required	`product` (announcement with a product card) or `general`
productId	string	optional	Required when `kind` = `product`
subject	string	optional	Max 150 chars. Falls back to the template's default subject.
message	string	optional	Max 5000 chars. Optional when the chosen template has no `{{message}}` slot.
productLink	string	optional	URL for the "View product" button
templateId	string	optional	Custom template to use. Omit for the standard branded layout.
options	array	optional	Restrict the audience to subscribers who picked these alert options
testOnly	boolean	optional	`true` sends a single preview to your store contact email only

Response (202)

JSON

{ "sendId": "b1afb5d6-..." }

Audience is capped at 2,000 recipients per send. Suppressed addresses (unsubscribed, bounced, complained) are skipped automatically and reported in the send detail.

GET /shop/{storeId}/admin/subscribers/sends

Send history (latest 20). Status is pending while the job runs, then completed or failed with counts.

GET /shop/{storeId}/admin/subscribers/sends/{sendId}

Per-recipient outcome detail for one send.

Response

JSON

{
  "detail": {
    "requestedAt": "2026-07-30T12:00:00Z",
    "recipients": {
      "sent": ["maya@example.com"],
      "skipped": [{ "email": "gone@example.com", "reason": "unsubscribed" }],
      "failed": []
    }
  }
}

detail is null for sends made before per-recipient recording was introduced (July 2026). Details are retained for 90 days.

GET /shop/{storeId}/admin/subscribers/templates

List custom email templates (metadata only — fetch one for its HTML). Up to 20 per store.

POST /shop/{storeId}/admin/subscribers/templates

Create a custom email template.

Request Body

Field	Type	Required	Description
name	string	required	Max 60 chars
subject	string	optional	Default subject for sends using this template (max 150)
html	string	required	Email body HTML, max 50 KB. Placeholders: `{{store.name}}`, `{{store.logo}}`, `{{message}}`, `{{product.name}}`, `{{product.price}}`, `{{product.image}}`, `{{product.url}}`, `{{product.description}}`, `{{product_card}}`, `{{unsubscribe_url}}`. Unknown tags are stripped; if you omit the unsubscribe link, a standard compliance footer is appended automatically.

Response (201)

JSON

{
  "template": {
    "templateId": "tpl-123",
    "name": "Weekend sale",
    "subject": "New at {{store.name}}!",
    "usesProduct": true,
    "usesMessage": true,
    "createdAt": "2026-08-05T12:00:00Z",
    "updatedAt": "2026-08-05T12:00:00Z"
  }
}

POST /shop/{storeId}/admin/subscribers/templates/draft

AI-draft (or revise) template HTML from a plain-language description. Free.

Request Body

Field	Type	Required	Description
description	string	required	What you want, up to 1000 chars
currentHtml	string	optional	Existing HTML to revise instead of starting over

Response

JSON

{ "html": "<div style=..." }

GET /shop/{storeId}/admin/subscribers/templates/{templateId}

Fetch one template including its html.

PUT /shop/{storeId}/admin/subscribers/templates/{templateId}

Update a template. Full replace — send the complete name/subject/html, not a partial patch.

DELETE /shop/{storeId}/admin/subscribers/templates/{templateId}

Delete a template.

Donations

Donation campaigns, records, supporters, and reporting. Available on every plan: Free/Standard run 1 campaign, Pro/Expert up to 10 and may hide the "Powered by NanoCart" branding. Amounts are integer cents throughout. Monthly donations additionally require the merchant's Stripe webhook to include invoice.paid, invoice.payment_failed, customer.subscription.deleted, and customer.subscription.updated.

GET /shop/{storeId}/admin/donations/campaigns

List campaigns with live totals. Response includes limit (your plan's campaign cap) and brandingRemovable.

POST /shop/{storeId}/admin/donations/campaigns

Create a campaign. campaignId is the public slug used by the donate button and stats widget — lowercase letters, numbers, dashes; immutable after creation.

Request Body

JSON

{
  "campaignId": "general-support",
  "name": "Support BlockFlockNow",
  "description": "Help cover our operating costs.",
  "buttonText": "Donate Now",
  "successUrl": "/thank-you",
  "suggestedOneTime": [500, 1000, 2500, 5000, 10000],
  "suggestedMonthly": [500, 1000, 2000, 5000],
  "allowCustomAmount": true,
  "allowOneTime": true,
  "allowRecurring": true,
  "defaultFrequency": "one_time",
  "goalAmountCents": 250000,
  "goalMetric": "month_total",
  "statsConfig": { "showCount": true, "showRaised": true, "showMonthly": true, "showGoal": true, "showButton": true },
  "hideBranding": false,
  "status": "active"
}

Field	Type	Required	Description
campaignId	string	required	Public slug (max 41 chars), immutable
name	string	required	Shown as the donate popup title (max 80)
suggestedOneTime / suggestedMonthly	array	optional	Up to 8 amounts each, 100–999999 cents. Monthly requires at least one when `allowRecurring` is true.
allowCustomAmount	boolean	optional	One-time "other amount" field (default true; custom recurring is not supported)
goalAmountCents / goalMetric	integer / string	optional	Goal measured by `month_total`, `mrr`, or `all_time` — recurring revenue and totals are never mixed
statsConfig	object	optional	What the PUBLIC stats widget may show: showCount, showRaised, showMonthly, showGoal, showButton. Disabled fields never leave the API.
hideBranding	boolean	optional	Pro/Expert only — otherwise `403 TIER_LIMIT`

Response is 201 with the campaign incl. zeroed counters. A store at its campaign cap receives 403 TIER_LIMIT; a duplicate slug receives 409 DUPLICATE_CAMPAIGN.

GET /shop/{storeId}/admin/donations/campaigns/{campaignId}

Fetch one campaign including live counters (donationCount, totalRaisedCents, activeMonthlySupporters, mrrCents, monthRaisedCents).

PUT /shop/{storeId}/admin/donations/campaigns/{campaignId}

Update a campaign. Full replace — GET first, modify, and PUT the complete config (live counters and createdAt are preserved server-side; the slug cannot change). Same body and validation as create.

DELETE /shop/{storeId}/admin/donations/campaigns/{campaignId}

Delete a campaign — the donate button and stats widget stop rendering immediately. Donation records are kept; active Stripe subscriptions are NOT canceled (do that in Stripe).

GET /shop/{storeId}/admin/donations

List donation records, newest first.

Query Parameters

Parameter	Type	Description
kind	string	`one_time`, `recurring` (supporter records), or `recurring_payment` (individual monthly charges)
limit	integer	Results per page (default 50, max 200)
lastKey	string	Pagination token from the previous response

Response

JSON

{
  "donations": [
    {
      "donationId": "f8647d18-...",
      "kind": "one_time",
      "campaignId": "general-support",
      "status": "succeeded",
      "amountCents": 2500,
      "currency": "usd",
      "donorEmail": "donor@example.com",
      "donorName": "Dana Donor",
      "anonymous": false,
      "processor": "stripe",
      "createdAt": "2026-08-13T12:00:00Z"
    }
  ],
  "lastKey": null
}

GET /shop/{storeId}/admin/donations/supporters

Monthly supporters with status (active / past_due / canceled), monthlyCents, consecutiveMonths, lifetimeCents, and startedAt.

GET /shop/{storeId}/admin/donations/report

Donations report: range totals plus live stats and per-campaign breakdowns. Query: from / to (YYYY-MM-DD, inclusive; omit for all time).

Response

JSON

{
  "range": { "from": "2026-08-01", "to": "2026-08-31" },
  "totalRaisedCents": 184200,
  "giftCount": 41,
  "oneTimeCount": 28,
  "oneTimeTotalCents": 122700,
  "recurringPaymentCount": 13,
  "recurringTotalCents": 61500,
  "newSupporters": 6,
  "canceledSupporters": 1,
  "averageGiftCents": 4492,
  "largestGiftCents": 25000,
  "live": {
    "activeMonthlySupporters": 41,
    "mrrCents": 61500,
    "allTimeRaisedCents": 1523400,
    "allTimeDonationCount": 327
  },
  "campaigns": [ { "campaignId": "general-support", "name": "...", "totalRaisedCents": 1523400, "...": "..." } ]
}

Fulfillment Vendors

Custom fulfillment partners — a local print shop, a drop-ship supplier — that automatically receive an emailed order sheet when their products sell. Requires a Pro or Expert plan; other tiers receive 403 with "code": "TIER_LIMIT". Up to 10 vendors per store.

No prices, ever. Vendor emails are work orders, not receipts. The template system has no price placeholders, so a vendor email cannot include what you charge — by construction. Route products to a vendor with the fulfillmentVendorId, vendorSku, and vendorNotes fields on products (variants may carry their own vendorSku).

GET /shop/{storeId}/admin/vendors

List vendors (metadata only — fetch one for its templateHtml).

Response

JSON

{
  "vendors": [
    {
      "vendorId": "5d195554-...",
      "name": "Ace Print Shop",
      "channel": "email",
      "status": "active",
      "email": { "to": ["orders@aceprint.com"], "cc": [] },
      "subjectTemplate": "",
      "includeShipping": true,
      "includeCustomerContact": false,
      "notes": "Call 555-0100 with questions",
      "sentCount": 14,
      "createdAt": "2026-08-05T21:45:45Z",
      "updatedAt": "2026-08-05T21:45:45Z"
    }
  ],
  "limit": 10
}

POST /shop/{storeId}/admin/vendors

Create a vendor.

Request Body

JSON

{
  "name": "Ace Print Shop",
  "email": { "to": ["orders@aceprint.com"], "cc": [] },
  "subjectTemplate": "New order {{order.number}} — {{store.name}}",
  "templateHtml": "",
  "includeShipping": true,
  "includeCustomerContact": false,
  "notes": "Call 555-0100 with questions",
  "status": "active"
}

Field	Type	Required	Description
name	string	required	Max 60 chars
email.to	array	required	1–5 recipient addresses
email.cc	array	optional	Up to 5 Cc addresses
channel	string	optional	Only `email` today (default)
status	string	optional	`active` (default) or `paused`. Paused vendors are skipped at order time (recorded as skipped on the order).
subjectTemplate	string	optional	Subject line; tags `{{order.number}}`, `{{store.name}}`, `{{vendor.name}}` resolve. Max 150.
templateHtml	string	optional	Custom order-sheet HTML, max 50 KB. Empty = the standard NanoCart order sheet. Custom HTML must include `{{items_table}}` or an `{{#items}}…{{/items}}` block, or the request fails with `NO_ITEMS_PLACEHOLDER`. See the tag table below.
includeShipping	boolean	optional	Fill `{{shipping_address}}` with the customer ship-to (default true)
includeCustomerContact	boolean	optional	Fill `{{customer.name}}`/`{{customer.email}}` (default false)
notes	string	optional	Standing instructions sent with every order via `{{vendor.notes}}` (max 2000)

Template placeholders

Tag	Meaning
`{{items_table}}`	Complete line-items table: qty, product, item #, notes
`{{#items}}…{{/items}}`	Repeat block, rendered once per line item
`{{item.quantity}}` `{{item.name}}` `{{item.variant}}`	Line-item basics (inside a repeat block)
`{{item.vendorSku}}` `{{item.sku}}` `{{item.notes}}` `{{item.image}}`	Vendor item # (variant-level overrides product-level), store SKU, per-product notes, product photo URL
`{{order.number}}` `{{order.date}}` `{{order.id}}`	Order identity
`{{store.name}}` `{{store.logo}}`	Your store
`{{shipping_address}}`	Ship-to block (empty unless `includeShipping`)
`{{customer.name}}` `{{customer.email}}`	Empty unless `includeCustomerContact`
`{{vendor.name}}` `{{vendor.notes}}`	The vendor and your standing instructions

Unknown tags are stripped at send time. There are deliberately no price tags. Response is 201 with the full vendor object; a store at the 10-vendor cap receives 409 with "code": "LIMIT_REACHED".

GET /shop/{storeId}/admin/vendors/{vendorId}

Fetch one vendor including its templateHtml.

PUT /shop/{storeId}/admin/vendors/{vendorId}

Update a vendor. Full replace — GET the vendor first, modify, and PUT the complete record. A partial body resets omitted fields (an update without templateHtml clears the saved template). Same body and validation as create.

DELETE /shop/{storeId}/admin/vendors/{vendorId}

Delete a vendor. Products keep selling; their orders simply stop being forwarded. Order history is retained.

POST /shop/{storeId}/admin/vendors/draft

AI-draft (or revise) order-sheet HTML from a description. Free. Body: description (required, ≤1000 chars), currentHtml (optional). Returns { "html": "..." }.

POST /shop/{storeId}/admin/vendors/{vendorId}/test

Send yourself a test order sheet rendered with sample data. Goes to your store contact email with a [TEST] banner — the vendor is never contacted. Returns { "sentTo": "you@example.com" }.

POST /shop/{storeId}/admin/orders/{orderId}/send-vendor

Manually email an order to a vendor — for orders placed before the vendor was configured (items are matched by the products' current vendor routing) or deliberate re-sends.

Request Body

JSON

{ "vendorId": "5d195554-..." }

Orders containing vendor-routed items are emailed automatically after payment — this endpoint is only for manual sends. Failed automatic sends can be retried with POST /admin/orders/{orderId}/retry-pod using {"provider": "vendor"}; outcomes are recorded on the order's podFulfillments array with "provider": "vendor". While Test Mode (Settings → Fulfillment) is on, vendor emails are redirected to your store contact email with a [TEST] banner.

Error Codes

Error responses include an error message and an optional code for programmatic handling:

JSON

{
  "error": "Free plan allows 2 active products. Upgrade to Standard for 25.",
  "code": "TIER_PRODUCT_LIMIT",
  "tierLimit": true
}

Code	HTTP	Description
INVALID_API_KEY	401	API key doesn't exist or is invalid
STORE_SUSPENDED	403	Store has been suspended
INVALID_INPUT	400	Missing or malformed request data
STRIPE_NOT_CONFIGURED	400	Store has no Stripe keys set up
STRIPE_INVALID_KEYS	400	Stripe key format is wrong
STRIPE_AUTH_ERROR	400	Stripe rejected the keys
DOMAIN_NOT_ALLOWED	403	Origin domain not in allowedDomains
TIER_PRODUCT_LIMIT	403	Exceeded active product limit for tier
TIER_ORDER_LIMIT	403	Exceeded monthly order limit for tier
TIER_COUPON_LIMIT	403	Exceeded coupon limit for tier
TIER_UPLOAD_LIMIT	403	File size exceeds tier upload limit
TIER_SHIPPING_RESTRICTED	403	Shipping method not available on tier
DUPLICATE_COUPON	409	Coupon code already exists

Tier limit errors include "tierLimit": true so your app can detect upgrade prompts. The error message includes the current limit and the next tier's limit.

Last updated: August 2026

API Documentation

Widget Integration

Script Tag

Button Types

Full Example

Theming

Product Alerts Signup (Pro/Expert)

JavaScript API

Web Component: <nanocart-product>

Attributes

Multi-axis variant support

Authentication

Conventions

Prices

Pagination

Dates

Response Format

Service Tiers

Public API

Query Parameters

Response

Response

Errors

Response

Category Fields

Request Body

Response (valid)

Response (invalid)

Response

Request Body

Response

Errors

Query Parameters

Response

Response

Query Parameters

Response

Errors

Response

Response

Request Body

Response

Admin API

Stores

Response

Request Body

Response (201)

Request Body

Response

Products

Request Body

Response (201)

Request Body

Request Body

Categories

Request Body

Example: Top-level category

Example: Subcategory

Updatable Fields

Example: Move to subcategory and update sort order

Example: Promote to top-level

Coupons

Orders

Query Parameters

Response

Settings

Reports

Query Parameters

Response

Uploads

Request Body

Upload Types & S3 Paths

Example

Response

Storefront

Response

Updatable Fields

Example

Tier & Usage

Subscriptions