Download OpenAPI specification:
The HTTP contract that the Emporia template expects from a backend when it runs in
http mode (provideApi({ mode: 'http', baseUrl })).
This document was generated from the code: the operations come from the *.api.http.ts
implementations and the JSON shapes mirror the TypeScript interfaces in
src/app/**/*.models.ts and src/app/core/models/*.ts.
Authentication: every request to the base URL carries Authorization: Bearer <token>
(added by the auth interceptor). Errors are JSON { "message": "..." } with a 4xx/5xx
status; the message is shown to the user as is.
Roles: every workspace member has a role (owner, admin, staff, viewer). The UI
hides what a role may not do (see src/app/core/auth/permissions.ts), but the backend
must enforce the same rules and answer 403 otherwise. Operations below list the
permission they require.
| email required | string <email> |
| password required | string <password> |
| remember required | boolean |
{- "email": "ada@acme.test",
- "password": "demo-password",
- "remember": true
}{- "token": "demo-token",
- "expiresAt": "2026-12-01T09:00:00Z",
- "user": {
- "id": "usr_1001",
- "name": "Ada Demo",
- "email": "ada@acme.test",
- "company": "Acme Demo",
- "role": "owner"
}
}| name required | string |
| company required | string |
| email required | string <email> |
| password required | string <password> |
{- "name": "string",
- "company": "string",
- "email": "user@example.com",
- "password": "pa$$word"
}{- "token": "demo-token",
- "expiresAt": "2026-12-01T09:00:00Z",
- "user": {
- "id": "usr_1001",
- "name": "Ada Demo",
- "email": "ada@acme.test",
- "company": "Acme Demo",
- "role": "owner"
}
}| token required | string Token from the reset link. |
| password required | string <password> |
{- "token": "string",
- "password": "pa$$word"
}{- "message": "Something went wrong."
}| ids required | Array of strings |
{- "ids": [
- "ntf_101",
- "ntf_102"
]
}{- "message": "Invalid email or password."
}| workspace required | string |
| teamSize required | string (TeamSize) Enum: "1-10" "11-50" "51-200" "200+" |
| goals required | Array of strings (OnboardingGoal) Items Enum: "sales" "inventory" "customers" "reporting" "pricing" |
| dataSource required | string (DataSource) Enum: "store-api" "csv" "sample" |
| invites required | Array of strings Teammate emails to invite; empty strings are ignored. |
{- "workspace": "Acme Demo",
- "teamSize": "11-50",
- "goals": [
- "sales",
- "inventory"
], - "dataSource": "sample",
- "invites": [
- "grace@acme.test",
- ""
]
}{- "message": "Invalid email or password."
}Every member can read the overview. The period is the last 7 days, 30 days, 90 days or 12 months, today included; the previous period is the interval of the same length right before it.
Revenue is the money from orders that are paid or fulfilled, minus refunds (the same figure
as the Orders and Customers pages). Orders counts those orders and averageOrderValue is
revenue divided by orders. Refunds is the money returned on the orders placed in the period,
whatever their status. returningRate is the share of buyers in the period (0 to 100) who already
had a paid or fulfilled order before the period began. delta is the change against the previous
period: a percentage, or percentage points for returningRate; 0 when there is nothing to compare.
The revenue series has one point per day up to 30 days and one per week beyond (the last week may be
partial). categories and topProducts count product sales after the order discount and refunds,
before shipping and tax, so they add up to less than revenue. toShip lists paid orders that are
not fulfilled yet, whatever the period; lowStock uses the low-stock threshold of the notification
preferences (5 by default).
| period | string (OverviewPeriod) Default: "30d" Enum: "7d" "30d" "90d" "12m" |
{- "period": "7d",
- "from": "2019-08-24",
- "to": "2019-08-24",
- "granularity": "day",
- "kpis": [
- {
- "id": "revenue",
- "value": 0,
- "previous": 0,
- "delta": 0,
- "spark": [
- 0
]
}
], - "revenueSeries": [
- {
- "date": "2019-08-24",
- "revenue": 0,
- "previousRevenue": 0,
- "orders": 0
}
], - "channels": [
- {
- "channel": "online_store",
- "revenue": 0,
- "orders": 0
}
], - "categories": [
- {
- "category": "string",
- "revenue": 0
}
], - "topProducts": [
- {
- "productId": "string",
- "name": "string",
- "category": "string",
- "units": 0,
- "revenue": 0,
- "exists": true
}
], - "toShip": {
- "total": 0,
- "orders": [
- {
- "id": "string",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "total": 0,
- "items": 0
}
]
}, - "lowStock": {
- "total": 0,
- "threshold": 0,
- "items": [
- {
- "sku": "string",
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "quantity": 0
}
]
}, - "topDiscounts": [
- {
- "code": "string",
- "orders": 0,
- "discountTotal": 0
}
]
}Every member can read orders. The tab counts in the response ignore the tab filter
(but apply all the others), so each tab shows its own total.
| tab | string (OrderTab) Enum: "all" "unfulfilled" "unpaid" "fulfilled" "refunded" "cancelled" Status tab. |
| search | string Matches the order number (with or without |
| channel | string (SalesChannel) Enum: "online_store" "marketplace" "social" "pos" |
| period | string Enum: "7d" "30d" "90d" "12m" Only orders placed in the last 7 days, 30 days, 90 days or 12 months. Leave it out for all time. |
| sort | string Default: "createdAt" Enum: "createdAt" "total" |
| direction | string Default: "desc" Enum: "asc" "desc" |
| page | integer >= 1 Default: 1 Page number, starting at 1. |
| pageSize | integer >= 1 Default: 10 |
{- "items": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0
}
], - "total": 0,
- "page": 0,
- "pageSize": 0,
- "counts": {
- "all": 0,
- "unfulfilled": 0,
- "unpaid": 0,
- "fulfilled": 0,
- "refunded": 0,
- "cancelled": 0
}
}Used by the CSV export. Takes the same filters as the list, except page and pageSize.
| tab | string (OrderTab) Enum: "all" "unfulfilled" "unpaid" "fulfilled" "refunded" "cancelled" Status tab. |
| search | string Matches the order number (with or without |
| channel | string (SalesChannel) Enum: "online_store" "marketplace" "social" "pos" |
| period | string Enum: "7d" "30d" "90d" "12m" Only orders placed in the last 7 days, 30 days, 90 days or 12 months. Leave it out for all time. |
| sort | string Default: "createdAt" Enum: "createdAt" "total" |
| direction | string Default: "desc" Enum: "asc" "desc" |
[- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0
}
]Orders that cannot ship (not paid, already fulfilled, cancelled, refunded or unknown) are skipped and reported with the reason; the call still succeeds. The server picks the carrier and tracking number for each order that ships.
| ids required | Array of strings non-empty |
{- "ids": [
- "string"
]
}{- "fulfilled": [
- "string"
], - "skipped": [
- {
- "id": "string",
- "reason": "string"
}
]
}| id required | string Order id (for example |
{- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0,
- "subtotal": 0,
- "discount": 0,
- "discountCode": "string",
- "shipping": 0,
- "tax": 0,
- "net": 0,
- "refundable": 0,
- "lines": [
- {
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "sku": "string",
- "quantity": 0,
- "unitPrice": 0,
- "lineTotal": 0
}
], - "customer": {
- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "ordersCount": 0,
- "totalSpent": 0
}, - "shippingAddress": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "events": [
- {
- "id": "string",
- "type": "created",
- "at": "2019-08-24T14:15:22Z",
- "message": "string",
- "carrier": "string",
- "trackingNumber": "string",
- "notifiedCustomer": true,
- "amount": 0,
- "reason": "string",
- "restocked": true
}
]
}Only a paid order that has not shipped can be fulfilled. The status becomes fulfilled and a fulfilled event is added to the history.
| id required | string Order id (for example |
| carrier required | string |
| trackingNumber required | string |
| notifyCustomer required | boolean Email the customer the tracking link. |
{- "carrier": "DHL",
- "trackingNumber": "string",
- "notifyCustomer": true
}{- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0,
- "subtotal": 0,
- "discount": 0,
- "discountCode": "string",
- "shipping": 0,
- "tax": 0,
- "net": 0,
- "refundable": 0,
- "lines": [
- {
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "sku": "string",
- "quantity": 0,
- "unitPrice": 0,
- "lineTotal": 0
}
], - "customer": {
- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "ordersCount": 0,
- "totalSpent": 0
}, - "shippingAddress": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "events": [
- {
- "id": "string",
- "type": "created",
- "at": "2019-08-24T14:15:22Z",
- "message": "string",
- "carrier": "string",
- "trackingNumber": "string",
- "notifiedCustomer": true,
- "amount": 0,
- "reason": "string",
- "restocked": true
}
]
}Several partial refunds are allowed until the total is reached. While something is left to
refund the order keeps its status; when the whole total has been refunded the status
becomes refunded and the payment status refunded.
| id required | string Order id (for example |
| amount required | integer >= 1 In cents, at most the order's |
| reason required | string May be empty. |
| restock required | boolean Put the refunded items back in stock: all the units for a full refund, a share of them for a partial one (never the same unit twice). |
{- "amount": 1,
- "reason": "string",
- "restock": true
}{- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0,
- "subtotal": 0,
- "discount": 0,
- "discountCode": "string",
- "shipping": 0,
- "tax": 0,
- "net": 0,
- "refundable": 0,
- "lines": [
- {
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "sku": "string",
- "quantity": 0,
- "unitPrice": 0,
- "lineTotal": 0
}
], - "customer": {
- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "ordersCount": 0,
- "totalSpent": 0
}, - "shippingAddress": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "events": [
- {
- "id": "string",
- "type": "created",
- "at": "2019-08-24T14:15:22Z",
- "message": "string",
- "carrier": "string",
- "trackingNumber": "string",
- "notifiedCustomer": true,
- "amount": 0,
- "reason": "string",
- "restocked": true
}
]
}Works on unpaid and paid orders. A paid order is refunded for whatever was not refunded yet
(payment status refunded); an unpaid one has its payment voided.
| id required | string Order id (for example |
| reason required | string May be empty. |
| restock required | boolean Put the items back in stock. |
{- "reason": "string",
- "restock": true
}{- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "customerEmail": "user@example.com",
- "channel": "online_store",
- "status": "pending",
- "paymentStatus": "pending",
- "itemCount": 0,
- "total": 0,
- "refunded": 0,
- "subtotal": 0,
- "discount": 0,
- "discountCode": "string",
- "shipping": 0,
- "tax": 0,
- "net": 0,
- "refundable": 0,
- "lines": [
- {
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "sku": "string",
- "quantity": 0,
- "unitPrice": 0,
- "lineTotal": 0
}
], - "customer": {
- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "ordersCount": 0,
- "totalSpent": 0
}, - "shippingAddress": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "events": [
- {
- "id": "string",
- "type": "created",
- "at": "2019-08-24T14:15:22Z",
- "message": "string",
- "carrier": "string",
- "trackingNumber": "string",
- "notifiedCustomer": true,
- "amount": 0,
- "reason": "string",
- "restocked": true
}
]
}Every member can read products. The tab counts in the response ignore the tab filter
(but apply all the others), so each tab shows its own total. lowStockThreshold is the
value the "low stock" filter used (the lowStockThreshold of the notification
preferences).
| tab | string (ProductTab) Enum: "all" "active" "draft" "archived" Status tab. Leave it out for all products. |
| search | string Matches the name or SKU of the product, or the SKU of one of its variants (case-insensitive). |
| category | string Category name. Leave it out for all categories. |
| stock | string Enum: "in_stock" "low" "out"
|
| sort | string Default: "name" Enum: "name" "price" "stock" "sold" |
| direction | string Default: "asc" Enum: "asc" "desc" |
| page | integer >= 1 Default: 1 Page number, starting at 1. |
| pageSize | integer >= 1 Default: 10 |
{- "items": [
- {
- "id": "string",
- "name": "string",
- "sku": "string",
- "category": "string",
- "status": "active",
- "priceMin": 0,
- "priceMax": 0,
- "compareAtPrice": 0,
- "stock": 0,
- "variantCount": 0,
- "lowVariants": 0,
- "outVariants": 0,
- "sold": 0
}
], - "total": 0,
- "page": 0,
- "pageSize": 0,
- "counts": {
- "all": 0,
- "active": 0,
- "draft": 0,
- "archived": 0
}, - "lowStockThreshold": 0
}The SKU of the product and of every variant must be unique in the whole catalog, ignoring case (SKUs are stored in upper case).
| name required | string <= 120 characters |
| description required | string <= 2000 characters May be empty. |
| category required | string |
| status required | string (ProductStatus) Enum: "active" "draft" "archived" |
| price required | integer >= 1 In cents, tax excluded. |
| compareAtPrice required | integer or null Strike-through price in cents; when set it must be greater than |
| cost required | integer >= 0 Cost per item, in cents. |
| sku required | string <= 40 characters ^[A-Za-z0-9][A-Za-z0-9._-]*$ |
required | Array of objects (ProductOption) <= 2 items |
required | Array of objects (ProductVariantInput) [ 1 .. 100 ] items One per combination sold (not necessarily all of them). Without options there is exactly
one variant with empty |
{- "name": "string",
- "description": "string",
- "category": "string",
- "status": "active",
- "price": 1,
- "compareAtPrice": 0,
- "cost": 0,
- "sku": "string",
- "options": [
- {
- "name": "Size",
- "values": [
- "S",
- "M",
- "L"
]
}
], - "variants": [
- {
- "sku": "string",
- "options": {
- "Size": "M"
}, - "price": 1,
- "stock": 0
}
]
}{- "name": "string",
- "description": "string",
- "category": "string",
- "status": "active",
- "price": 1,
- "compareAtPrice": 0,
- "cost": 0,
- "sku": "string",
- "options": [
- {
- "name": "Size",
- "values": [
- "S",
- "M",
- "L"
]
}
], - "variants": [
- {
- "sku": "string",
- "options": {
- "Size": "M"
}, - "price": 1,
- "stock": 0,
- "title": "string"
}
], - "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "stats": {
- "unitsSold": 0,
- "revenue": 0,
- "ordersCount": 0,
- "recentOrders": [
- {
- "id": "string",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "quantity": 0
}
]
}
}Used by the CSV export. Takes the same filters as the list, except page and pageSize.
| tab | string (ProductTab) Enum: "all" "active" "draft" "archived" Status tab. Leave it out for all products. |
| search | string Matches the name or SKU of the product, or the SKU of one of its variants (case-insensitive). |
| category | string Category name. Leave it out for all categories. |
| stock | string Enum: "in_stock" "low" "out"
|
| sort | string Default: "name" Enum: "name" "price" "stock" "sold" |
| direction | string Default: "asc" Enum: "asc" "desc" |
[- {
- "id": "string",
- "name": "string",
- "sku": "string",
- "category": "string",
- "status": "active",
- "priceMin": 0,
- "priceMax": 0,
- "compareAtPrice": 0,
- "stock": 0,
- "variantCount": 0,
- "lowVariants": 0,
- "outVariants": 0,
- "sold": 0
}
]Ids that no longer exist are skipped and reported; the call still succeeds.
| ids required | Array of strings non-empty |
| status required | string (ProductStatus) Enum: "active" "draft" "archived" |
{- "ids": [
- "string"
], - "status": "active"
}{- "done": [
- "string"
], - "skipped": [
- {
- "id": "string",
- "reason": "string"
}
]
}Orders already placed keep what was bought. Ids that no longer exist are skipped and reported; the call still succeeds.
| ids required | Array of strings non-empty |
{- "ids": [
- "string"
]
}{- "done": [
- "string"
], - "skipped": [
- {
- "id": "string",
- "reason": "string"
}
]
}| id required | string Product id (for example |
{- "name": "string",
- "description": "string",
- "category": "string",
- "status": "active",
- "price": 1,
- "compareAtPrice": 0,
- "cost": 0,
- "sku": "string",
- "options": [
- {
- "name": "Size",
- "values": [
- "S",
- "M",
- "L"
]
}
], - "variants": [
- {
- "sku": "string",
- "options": {
- "Size": "M"
}, - "price": 1,
- "stock": 0,
- "title": "string"
}
], - "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "stats": {
- "unitsSold": 0,
- "revenue": 0,
- "ordersCount": 0,
- "recentOrders": [
- {
- "id": "string",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "quantity": 0
}
]
}
}The body is the whole product, variants and their stock included. A product keeps its own SKUs; they only conflict with other products.
| id required | string Product id (for example |
| name required | string <= 120 characters |
| description required | string <= 2000 characters May be empty. |
| category required | string |
| status required | string (ProductStatus) Enum: "active" "draft" "archived" |
| price required | integer >= 1 In cents, tax excluded. |
| compareAtPrice required | integer or null Strike-through price in cents; when set it must be greater than |
| cost required | integer >= 0 Cost per item, in cents. |
| sku required | string <= 40 characters ^[A-Za-z0-9][A-Za-z0-9._-]*$ |
required | Array of objects (ProductOption) <= 2 items |
required | Array of objects (ProductVariantInput) [ 1 .. 100 ] items One per combination sold (not necessarily all of them). Without options there is exactly
one variant with empty |
{- "name": "string",
- "description": "string",
- "category": "string",
- "status": "active",
- "price": 1,
- "compareAtPrice": 0,
- "cost": 0,
- "sku": "string",
- "options": [
- {
- "name": "Size",
- "values": [
- "S",
- "M",
- "L"
]
}
], - "variants": [
- {
- "sku": "string",
- "options": {
- "Size": "M"
}, - "price": 1,
- "stock": 0
}
]
}{- "name": "string",
- "description": "string",
- "category": "string",
- "status": "active",
- "price": 1,
- "compareAtPrice": 0,
- "cost": 0,
- "sku": "string",
- "options": [
- {
- "name": "Size",
- "values": [
- "S",
- "M",
- "L"
]
}
], - "variants": [
- {
- "sku": "string",
- "options": {
- "Size": "M"
}, - "price": 1,
- "stock": 0,
- "title": "string"
}
], - "id": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "stats": {
- "unitsSold": 0,
- "revenue": 0,
- "ordersCount": 0,
- "recentOrders": [
- {
- "id": "string",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "quantity": 0
}
]
}
}One row per variant. Every member can read the inventory. The tab counts in the response
ignore the level filter (but apply all the others), so each tab shows its own total.
committed is the number of units in paid orders that have not shipped yet. lowStockThreshold
is the value the low level used (the lowStockThreshold of the notification preferences).
| level | string (InventoryTab) Enum: "all" "low" "out" Stock-level tab. Leave it out for all variants. |
| search | string Matches the product name, the variant title or the variant SKU (case-insensitive). |
| category | string Category name. Leave it out for all categories. |
| product | string Only the variants of this product (for example |
| sort | string Default: "name" Enum: "name" "available" "committed" |
| direction | string Default: "asc" Enum: "asc" "desc" |
| page | integer >= 1 Default: 1 Page number, starting at 1. |
| pageSize | integer >= 1 Default: 10 |
{- "items": [
- {
- "sku": "string",
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "category": "string",
- "available": 0,
- "committed": 0,
- "incoming": {
- "quantity": 0,
- "expectedAt": "2019-08-24T14:15:22Z"
}, - "level": "in_stock"
}
], - "total": 0,
- "page": 0,
- "pageSize": 0,
- "counts": {
- "all": 0,
- "low": 0,
- "out": 0
}, - "lowStockThreshold": 0,
- "product": {
- "id": "string",
- "name": "string"
}
}Used by the CSV export. Takes the same filters as the list, except page and pageSize.
| level | string (InventoryTab) Enum: "all" "low" "out" Stock-level tab. Leave it out for all variants. |
| search | string Matches the product name, the variant title or the variant SKU (case-insensitive). |
| category | string Category name. Leave it out for all categories. |
| product | string Only the variants of this product (for example |
| sort | string Default: "name" Enum: "name" "available" "committed" |
| direction | string Default: "asc" Enum: "asc" "desc" |
[- {
- "sku": "string",
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "category": "string",
- "available": 0,
- "committed": 0,
- "incoming": {
- "quantity": 0,
- "expectedAt": "2019-08-24T14:15:22Z"
}, - "level": "in_stock"
}
]The bulk "Add stock" action: every variant gets the same quantity, reason and note. SKUs that no longer exist are skipped and reported; the call still succeeds.
| skus required | Array of strings non-empty |
| quantity required | integer [ 1 .. 100000 ] |
| reason required | string (AdjustReason) Enum: "received" "correction" "damaged" "returned" "other" |
| note required | string <= 200 characters |
{- "skus": [
- "string"
], - "quantity": 1,
- "reason": "received",
- "note": "string"
}{- "done": [
- "string"
], - "skipped": [
- {
- "sku": "string",
- "reason": "string"
}
]
}Newest first, at most 100. Sales come from the orders (every order that took the units out of stock); refunds and cancellations appear only when they put the units back (restock); the rest are manual corrections. The starting stock plus every movement is the stock now.
| sku required | string Variant SKU (for example |
{- "item": {
- "sku": "string",
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "category": "string",
- "available": 0,
- "committed": 0,
- "incoming": {
- "quantity": 0,
- "expectedAt": "2019-08-24T14:15:22Z"
}, - "level": "in_stock"
}, - "movements": [
- {
- "id": "string",
- "at": "2019-08-24T14:15:22Z",
- "delta": 0,
- "kind": "sale",
- "reason": "received",
- "note": "string",
- "orderId": "string",
- "orderNumber": 0,
- "user": "string"
}
], - "total": 0
}add and remove change the stock by quantity (more than zero), set makes quantity the
new stock (zero is allowed). The result can't be negative and must differ from the current
stock. A received correction also reduces the incoming reorder of the variant. When the
correction takes a variant of an active product under the low-stock threshold and the
low-stock alerts are on, the server adds a low_stock notification.
| sku required | string Variant SKU (for example |
| mode required | string (AdjustMode) Enum: "add" "remove" "set" |
| quantity required | integer [ 0 .. 100000 ] To add, to remove, or the new stock with |
| reason required | string (AdjustReason) Enum: "received" "correction" "damaged" "returned" "other" |
| note required | string <= 200 characters Optional; send an empty string for none. |
{- "mode": "add",
- "quantity": 0,
- "reason": "received",
- "note": "string"
}{- "sku": "string",
- "productId": "string",
- "productName": "string",
- "variantTitle": "string",
- "category": "string",
- "available": 0,
- "committed": 0,
- "incoming": {
- "quantity": 0,
- "expectedAt": "2019-08-24T14:15:22Z"
}, - "level": "in_stock"
}Customer list with segments, the customer page, internal notes, tags and marketing consent.
Every member can read customers. Orders, total spent (paid or fulfilled orders, minus refunds)
and last order come from the orders. The segment counts ignore the segment filter (but apply
the search and the country), so each tab shows its own total. Segments can overlap: new
is a first order in the last 30 days, returning is 2 or more orders, vip is the top 5%
of customers by total spent (among those who spent something; ties at the threshold are all
included), at_risk is 2 or more orders but none in the last 180 days, subscribed has
agreed to marketing. vipThreshold is the smallest total spent that counts as VIP right now.
| segment | string (CustomerSegmentTag) Enum: "new" "returning" "vip" "at_risk" "subscribed" Segment tab. Leave it out for all customers. |
| search | string Matches the name or the email (case-insensitive). |
| country | string ISO 3166-1 alpha-2 code. Leave it out for all countries. |
| sort | string Default: "name" Enum: "name" "orders" "spent" "lastOrder" "since" Customers without orders count as the oldest last order. |
| direction | string Default: "asc" Enum: "asc" "desc" |
| page | integer >= 1 Default: 1 Page number, starting at 1. |
| pageSize | integer >= 1 Default: 10 |
{- "items": [
- {
- "id": "cus_001",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "orders": 0,
- "totalSpent": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}
], - "total": 0,
- "page": 0,
- "pageSize": 0,
- "counts": {
- "all": 0,
- "new": 0,
- "returning": 0,
- "vip": 0,
- "at_risk": 0,
- "subscribed": 0
}, - "vipThreshold": 0
}Used by the CSV export. Takes the same filters as the list, except page and pageSize.
| segment | string (CustomerSegmentTag) Enum: "new" "returning" "vip" "at_risk" "subscribed" Segment tab. Leave it out for all customers. |
| search | string Matches the name or the email (case-insensitive). |
| country | string ISO 3166-1 alpha-2 code. Leave it out for all countries. |
| sort | string Default: "name" Enum: "name" "orders" "spent" "lastOrder" "since" Customers without orders count as the oldest last order. |
| direction | string Default: "asc" Enum: "asc" "desc" |
[- {
- "id": "cus_001",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "orders": 0,
- "totalSpent": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}
]The bulk "Add tag" action. Customers that no longer exist, or that already have 10 tags, are skipped and reported; the call still succeeds. A customer that already has the tag counts as done.
| ids required | Array of strings |
| tag required | string |
{- "ids": [
- "string"
], - "tag": "press"
}{- "done": [
- "string"
], - "skipped": [
- {
- "id": "string",
- "reason": "string"
}
]
}Figures, orders (newest first), the default address and the notes (newest first). The address is the shipping address of the latest order, and null when the customer has not ordered yet.
| id required | string Customer id (for example |
{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Customers can't be deleted: they have orders and tax records attached. The email is stored in lowercase and must be unique among customers (compared ignoring case).
| id required | string Customer id (for example |
| name required | string <= 80 characters |
| email required | string <email> |
| country required | string ISO 3166-1 alpha-2 code, one of |
{- "name": "string",
- "email": "user@example.com",
- "country": "string"
}{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}| id required | string Customer id (for example |
| optIn required | boolean |
{- "optIn": true
}{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}The note is signed with the name of the signed-in user. Customers never see notes.
| id required | string Customer id (for example |
| text required | string <= 500 characters |
{- "text": "string"
}{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}| id required | string Customer id (for example |
| noteId required | string |
{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Tags are lowercase letters, numbers and dashes, up to 24 characters; a customer has at most 10. Adding a tag the customer already has changes nothing.
| id required | string Customer id (for example |
| tag required | string |
{- "tag": "wholesale"
}{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}| id required | string Customer id (for example |
| tag required | string |
{- "id": "string",
- "name": "string",
- "email": "user@example.com",
- "country": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "marketingOptIn": true,
- "tags": [
- "string"
], - "segments": [
- "new"
], - "stats": {
- "orders": 0,
- "totalSpent": 0,
- "averageOrder": 0,
- "lastOrderAt": "2019-08-24T14:15:22Z"
}, - "orders": [
- {
- "id": "ord_1001",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0
}
], - "address": {
- "name": "string",
- "line1": "string",
- "line2": "string",
- "postalCode": "string",
- "city": "string",
- "region": "string",
- "country": "string",
- "countryName": "string"
}, - "notes": [
- {
- "id": "string",
- "text": "string",
- "author": "string",
- "createdAt": "2019-08-24T14:15:22Z"
}
]
}Every member can read discount codes. The status comes from the dates and the disabled flag:
disabled wins over everything, otherwise scheduled (not started yet), expired
(already ended) or active. usageCount is the number of orders with the code, whatever their
status; revenue and discountTotal count only paid or fulfilled orders (revenue minus
refunds). The tab counts ignore the tab filter (but apply the search), so each tab shows its
own total.
| tab | string (DiscountStatus) Enum: "active" "scheduled" "expired" "disabled" Status tab. Leave it out for all codes. |
| search | string Matches the code (case-insensitive). |
| sort | string Default: "code" Enum: "code" "usage" "ends" Codes that never end count as ending after all the others. |
| direction | string Default: "asc" Enum: "asc" "desc" |
| page | integer >= 1 Default: 1 Page number, starting at 1. |
| pageSize | integer >= 1 Default: 25 |
{- "items": [
- {
- "code": "SPRING15",
- "type": "percent",
- "value": 0,
- "status": "active",
- "disabled": true,
- "appliesTo": {
- "kind": "all",
- "categories": [
- "string"
], - "products": [
- {
- "id": "string",
- "name": "string"
}
]
}, - "minSubtotal": 0,
- "minQuantity": 0,
- "usageCount": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z",
- "revenue": 0,
- "discountTotal": 0
}
], - "total": 0,
- "page": 0,
- "pageSize": 0,
- "counts": {
- "all": 0,
- "active": 0,
- "scheduled": 0,
- "expired": 0,
- "disabled": 0
}
}A new code is enabled; it is scheduled or active depending on its start date.
| code required | string 3 to 24 capital letters, numbers and single dashes. Can't change after creation. |
| type required | string (DiscountType) Enum: "percent" "fixed" "free_shipping" |
| value required | integer Whole percentage 1-100, euro cents above 0 and up to 100000, or 0 for free shipping. |
| scope required | string Enum: "all" "categories" "products" |
| categories required | Array of strings At least one with |
| productIds required | Array of strings 1 to 25 with |
| minSubtotal required | integer or null Euro cents. Not together with |
| minQuantity required | integer or null 1 to 1000. Not together with |
| usageLimit required | integer or null At least 1, and not under the uses so far. Null = unlimited. |
| oncePerCustomer required | boolean |
| startsAt required | string <date-time> |
| endsAt required | string or null <date-time> After |
{- "code": "AUTUMN15",
- "type": "percent",
- "value": 0,
- "scope": "all",
- "categories": [
- "string"
], - "productIds": [
- "string"
], - "minSubtotal": 0,
- "minQuantity": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z"
}{- "code": "SPRING15",
- "type": "percent",
- "value": 0,
- "status": "active",
- "disabled": true,
- "appliesTo": {
- "kind": "all",
- "categories": [
- "string"
], - "products": [
- {
- "id": "string",
- "name": "string"
}
]
}, - "minSubtotal": 0,
- "minQuantity": 0,
- "usageCount": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z",
- "revenue": 0,
- "discountTotal": 0,
- "orders": 0,
- "recentOrders": [
- {
- "id": "ord_1042",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0,
- "discount": 0
}
]
}Matches the name or the SKU (case-insensitive). Returns at most 8 products; an empty search returns none.
| search | string |
[- {
- "id": "string",
- "name": "string",
- "sku": "string",
- "category": "string"
}
]Codes that no longer exist are skipped and reported; the call still succeeds. Deleting a code does not touch the orders that used it: they keep the code and the discount.
| action required | string Enum: "enable" "disable" "delete" |
| codes required | Array of strings non-empty |
{- "action": "enable",
- "codes": [
- "string"
]
}{- "done": [
- "string"
], - "skipped": [
- {
- "code": "string",
- "reason": "string"
}
]
}Figures and the latest 10 orders that used the code, newest first. The code is not case sensitive.
| code required | string Discount code (for example |
{- "code": "SPRING15",
- "type": "percent",
- "value": 0,
- "status": "active",
- "disabled": true,
- "appliesTo": {
- "kind": "all",
- "categories": [
- "string"
], - "products": [
- {
- "id": "string",
- "name": "string"
}
]
}, - "minSubtotal": 0,
- "minQuantity": 0,
- "usageCount": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z",
- "revenue": 0,
- "discountTotal": 0,
- "orders": 0,
- "recentOrders": [
- {
- "id": "ord_1042",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0,
- "discount": 0
}
]
}Replaces every setting. A code can't be renamed: code in the body must be the one in the URL.
The usage limit can't be lower than the uses so far. The enabled or disabled state is kept.
| code required | string Discount code (for example |
| code required | string 3 to 24 capital letters, numbers and single dashes. Can't change after creation. |
| type required | string (DiscountType) Enum: "percent" "fixed" "free_shipping" |
| value required | integer Whole percentage 1-100, euro cents above 0 and up to 100000, or 0 for free shipping. |
| scope required | string Enum: "all" "categories" "products" |
| categories required | Array of strings At least one with |
| productIds required | Array of strings 1 to 25 with |
| minSubtotal required | integer or null Euro cents. Not together with |
| minQuantity required | integer or null 1 to 1000. Not together with |
| usageLimit required | integer or null At least 1, and not under the uses so far. Null = unlimited. |
| oncePerCustomer required | boolean |
| startsAt required | string <date-time> |
| endsAt required | string or null <date-time> After |
{- "code": "AUTUMN15",
- "type": "percent",
- "value": 0,
- "scope": "all",
- "categories": [
- "string"
], - "productIds": [
- "string"
], - "minSubtotal": 0,
- "minQuantity": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z"
}{- "code": "SPRING15",
- "type": "percent",
- "value": 0,
- "status": "active",
- "disabled": true,
- "appliesTo": {
- "kind": "all",
- "categories": [
- "string"
], - "products": [
- {
- "id": "string",
- "name": "string"
}
]
}, - "minSubtotal": 0,
- "minQuantity": 0,
- "usageCount": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z",
- "revenue": 0,
- "discountTotal": 0,
- "orders": 0,
- "recentOrders": [
- {
- "id": "ord_1042",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0,
- "discount": 0
}
]
}| code required | string Discount code (for example |
| disabled required | boolean |
{- "disabled": true
}{- "code": "SPRING15",
- "type": "percent",
- "value": 0,
- "status": "active",
- "disabled": true,
- "appliesTo": {
- "kind": "all",
- "categories": [
- "string"
], - "products": [
- {
- "id": "string",
- "name": "string"
}
]
}, - "minSubtotal": 0,
- "minQuantity": 0,
- "usageCount": 0,
- "usageLimit": 0,
- "oncePerCustomer": true,
- "startsAt": "2019-08-24T14:15:22Z",
- "endsAt": "2019-08-24T14:15:22Z",
- "revenue": 0,
- "discountTotal": 0,
- "orders": 0,
- "recentOrders": [
- {
- "id": "ord_1042",
- "number": 0,
- "createdAt": "2019-08-24T14:15:22Z",
- "customerName": "string",
- "status": "pending",
- "paymentStatus": "pending",
- "total": 0,
- "refunded": 0,
- "discount": 0
}
]
}| name required | string |
| email required | string <email> |
| company required | string |
| jobTitle required | string |
| timezone required | string |
| language required | string |
{- "name": "Ada Demo",
- "email": "ada@acme.test",
- "company": "Acme Demo",
- "jobTitle": "Head of Finance",
- "timezone": "Europe/Berlin",
- "language": "en"
}{- "name": "Ada Demo",
- "email": "ada@acme.test",
- "company": "Acme Demo",
- "jobTitle": "Head of Finance",
- "timezone": "Europe/Berlin",
- "language": "en"
}| weeklyReport required | boolean |
| lowStockAlerts required | boolean |
| refundAlerts required | boolean |
| newOrders required | boolean |
| productUpdates required | boolean |
| lowStockThreshold required | number Units left at or below which low-stock alerts fire. |
| channel required | string Enum: "email" "slack" "both" |
{- "weeklyReport": true,
- "lowStockAlerts": true,
- "refundAlerts": true,
- "newOrders": true,
- "productUpdates": true,
- "lowStockThreshold": 0,
- "channel": "email"
}{- "weeklyReport": true,
- "lowStockAlerts": true,
- "refundAlerts": true,
- "newOrders": true,
- "productUpdates": true,
- "lowStockThreshold": 0,
- "channel": "email"
}| current required | string <password> |
| next required | string <password> |
{- "current": "pa$$word",
- "next": "pa$$word"
}{- "message": "Invalid email or password."
}| enabled required | boolean |
{- "enabled": true
}{- "twoFactorEnabled": true,
- "sessions": [
- {
- "id": "string",
- "device": "string",
- "location": "string",
- "lastSeen": "2019-08-24T14:15:22Z",
- "current": true
}
]
}Store details, shipping zones, taxes, payment methods and checkout options. Only the Owner can change them.
Every member can read them; only the Owner (store.manage) can change them.
{- "details": {
- "name": "string",
- "contactEmail": "user@example.com",
- "currency": "EUR",
- "timezone": "Europe/Rome",
- "orderPrefix": "stri"
}, - "shipping": {
- "zones": [
- {
- "id": "string",
- "name": "string",
- "countries": [
- "string"
], - "restOfWorld": true,
- "rates": [
- {
- "id": "string",
- "name": "string",
- "price": 0,
- "freeOver": 0
}
]
}
]
}, - "taxes": {
- "pricesIncludeTax": true,
- "rates": [
- {
- "country": "IT",
- "rate": 22
}
]
}, - "payments": {
- "card": true,
- "paypal": true,
- "bankTransfer": true,
- "cashOnDelivery": true,
- "bankTransferInstructions": "string"
}, - "checkout": {
- "customerAccounts": "optional",
- "orderNotes": true
}
}The currency is always EUR and cannot change.
| name required | string <= 60 characters |
| contactEmail required | string <email> |
| currency required | string Value: "EUR" |
| timezone required | string |
| orderPrefix required | string <= 4 characters Shown before the order number, for example |
{- "name": "string",
- "contactEmail": "user@example.com",
- "currency": "EUR",
- "timezone": "Europe/Rome",
- "orderPrefix": "stri"
}{- "name": "string",
- "contactEmail": "user@example.com",
- "currency": "EUR",
- "timezone": "Europe/Rome",
- "orderPrefix": "stri"
}Replaces all zones. A country can be in one zone only, at most one zone covers the rest of the world, and every zone needs a rate.
required | Array of objects (ShippingZone) [ 1 .. 10 ] items |
{- "zones": [
- {
- "id": "string",
- "name": "string",
- "countries": [
- "string"
], - "restOfWorld": true,
- "rates": [
- {
- "id": "string",
- "name": "string",
- "price": 0,
- "freeOver": 0
}
]
}
]
}{- "zones": [
- {
- "id": "string",
- "name": "string",
- "countries": [
- "string"
], - "restOfWorld": true,
- "rates": [
- {
- "id": "string",
- "name": "string",
- "price": 0,
- "freeOver": 0
}
]
}
]
}Changing rates does not change the totals of orders already placed.
| pricesIncludeTax required | boolean |
required | Array of objects (TaxRate) non-empty |
{- "pricesIncludeTax": true,
- "rates": [
- {
- "country": "IT",
- "rate": 22
}
]
}{- "pricesIncludeTax": true,
- "rates": [
- {
- "country": "IT",
- "rate": 22
}
]
}At least one method must be on. The bank transfer instructions are required when bank transfer is on. No real payment data is stored.
| card required | boolean |
| paypal required | boolean |
| bankTransfer required | boolean |
| cashOnDelivery required | boolean |
| bankTransferInstructions required | string <= 500 characters |
{- "card": true,
- "paypal": true,
- "bankTransfer": true,
- "cashOnDelivery": true,
- "bankTransferInstructions": "string"
}{- "card": true,
- "paypal": true,
- "bankTransfer": true,
- "cashOnDelivery": true,
- "bankTransferInstructions": "string"
}Guest checkout or required customer accounts, and whether customers can leave an order note.
| customerAccounts required | string Enum: "optional" "required" |
| orderNotes required | boolean |
{- "customerAccounts": "optional",
- "orderNotes": true
}{- "customerAccounts": "optional",
- "orderNotes": true
}Every member can read the team.
{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}Pending invitations are listed with the team until accepted or revoked. Ownership cannot be granted by invitation.
| email required | string <email> |
| role required | string (AssignableRole) Enum: "admin" "staff" "viewer" Any role except owner. |
{- "email": "user@example.com",
- "role": "admin"
}{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}| id required | string Member or invitation id. |
{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}| id required | string Member or invitation id. |
{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}The owner's role cannot be changed and nobody can be made owner here.
| id required | string Member or invitation id. |
| role required | string (AssignableRole) Enum: "admin" "staff" "viewer" Any role except owner. |
{- "role": "admin"
}{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}The owner cannot be removed.
| id required | string Member or invitation id. |
{- "members": [
- {
- "id": "usr_demo",
- "name": "Alex Morgan",
- "email": "demo@emporia.app",
- "role": "owner",
- "lastActiveAt": "2026-11-13T09:00:00Z",
- "joinedAt": "2025-05-22T10:00:00Z",
- "twoFactorEnabled": true
}
], - "invites": [
- {
- "id": "inv_jordan",
- "email": "jordan.lee@emporia.app",
- "role": "staff",
- "invitedBy": "Priya Raman",
- "sentAt": "2026-11-11T09:00:00Z",
- "expiresAt": "2026-11-18T09:00:00Z"
}
], - "seats": {
- "used": 2,
- "limit": 10
}
}Every member can read them. Secrets are never included, only the key prefix.
{- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}The full secret is returned only in this response; only its first 12 characters are kept. At most 10 keys per workspace.
| name required | string [ 1 .. 40 ] characters |
| access required | string (ApiKeyAccess) Enum: "read" "write" |
| expiresInDays required | integer or null Enum: 30 90 365 null Null = the key does not expire. |
{- "name": "string",
- "access": "read",
- "expiresInDays": 30
}{- "developers": {
- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}, - "secret": "pk_live_3fA9xK2mQ7vLw0ZpR8dTn5BcY1hGe4Sj"
}Apps using the key stop working immediately.
| id required | string API key id. |
{- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}The endpoint starts enabled. At most 5 endpoints per workspace.
| url required | string <uri> Must be an |
| description required | string |
| events required | Array of strings (WebhookEvent) non-empty Items Enum: "order.created" "order.paid" "order.shipped" "order.refunded" "order.cancelled" "product.created" "product.updated" "inventory.low_stock" "customer.created" |
{- "description": "string",
- "events": [
- "order.created"
]
}{- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}| id required | string Webhook endpoint id. |
| url | string <uri> |
| description | string |
| events | Array of strings (WebhookEvent) non-empty Items Enum: "order.created" "order.paid" "order.shipped" "order.refunded" "order.cancelled" "product.created" "product.updated" "inventory.low_stock" "customer.created" |
| enabled | boolean |
{- "description": "string",
- "events": [
- "order.created"
], - "enabled": true
}{- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}Its delivery history is removed too.
| id required | string Webhook endpoint id. |
{- "keys": [
- {
- "id": "key_prod",
- "name": "Production backend",
- "prefix": "pk_live_3fA9",
- "access": "write",
- "createdAt": "2026-04-28T09:00:00Z",
- "createdBy": "Alex Morgan",
- "lastUsedAt": "2026-11-14T13:00:00Z",
- "expiresAt": null
}
], - "webhooks": [
- {
- "id": "whk_crm",
- "description": "Sync customers and new orders to the CRM",
- "events": [
- "customer.created",
- "order.created"
], - "enabled": true,
- "createdAt": "2026-06-17T09:00:00Z",
- "lastDelivery": {
- "id": "dlv_crm_1",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 182,
- "at": "2026-11-14T13:00:00Z"
}
}
]
}Sends a customer.created test event and records the delivery.
| id required | string Webhook endpoint id. |
{- "id": "string",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 0,
- "at": "2019-08-24T14:15:22Z"
}Newest first, at most 20. Every member can read them.
| id required | string Webhook endpoint id. |
[- {
- "id": "string",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 0,
- "at": "2019-08-24T14:15:22Z"
}
]Creates a new delivery for the same event.
| id required | string Webhook endpoint id. |
| deliveryId required | string |
{- "id": "string",
- "event": "order.created",
- "status": "succeeded",
- "statusCode": 200,
- "durationMs": 0,
- "at": "2019-08-24T14:15:22Z"
}