Emporia API (1.0.0)

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.

Auth

Sign in, sign up and password reset.

Sign in with email and password

Request Body schema: application/json
required
email
required
string <email>
password
required
string <password>
remember
required
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "ada@acme.test",
  • "password": "demo-password",
  • "remember": true
}

Response samples

Content type
application/json
{
  • "token": "demo-token",
  • "expiresAt": "2026-12-01T09:00:00Z",
  • "user": {
    }
}

Create an account and sign in

Request Body schema: application/json
required
name
required
string
company
required
string
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "company": "string",
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "token": "demo-token",
  • "expiresAt": "2026-12-01T09:00:00Z",
  • "user": {
    }
}

Sign out

Sent with an empty JSON body ({}).

Authorizations:
bearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Request a password reset email

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "Enter a valid email address."
}

Set a new password with a reset token

Request Body schema: application/json
required
token
required
string

Token from the reset link.

password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "Something went wrong."
}

Notifications

In-app notifications.

List notifications

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark notifications as read

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Onboarding

First-run setup wizard.

Complete the onboarding wizard

Authorizations:
bearerAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "workspace": "Acme Demo",
  • "teamSize": "11-50",
  • "goals": [
    ],
  • "dataSource": "sample",
  • "invites": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Overview

Sales, orders and what needs attention, for the period chosen on the Overview page.

Sales overview for a period

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).

Authorizations:
bearerAuth
query Parameters
period
string (OverviewPeriod)
Default: "30d"
Enum: "7d" "30d" "90d" "12m"

Responses

Response samples

Content type
application/json
{
  • "period": "7d",
  • "from": "2019-08-24",
  • "to": "2019-08-24",
  • "granularity": "day",
  • "kpis": [
    ],
  • "revenueSeries": [
    ],
  • "channels": [
    ],
  • "categories": [
    ],
  • "topProducts": [
    ],
  • "toShip": {
    },
  • "lowStock": {
    },
  • "topDiscounts": [
    ]
}

Orders

Order list, order page and the actions on an order (fulfil, refund, cancel).

List orders with filters, sorting and paging

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.

Authorizations:
bearerAuth
query Parameters
tab
string (OrderTab)
Enum: "all" "unfulfilled" "unpaid" "fulfilled" "refunded" "cancelled"

Status tab. unfulfilled is paid and not shipped, unpaid is payment pending. Leave it out for all orders.

search
string

Matches the order number (with or without #), the customer name or the customer email.

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "counts": {
    }
}

Every order that matches the filters, without paging

Used by the CSV export. Takes the same filters as the list, except page and pageSize.

Authorizations:
bearerAuth
query Parameters
tab
string (OrderTab)
Enum: "all" "unfulfilled" "unpaid" "fulfilled" "refunded" "cancelled"

Status tab. unfulfilled is paid and not shipped, unpaid is payment pending. Leave it out for all orders.

search
string

Matches the order number (with or without #), the customer name or the customer email.

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"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mark several orders as fulfilled

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "fulfilled": [
    ],
  • "skipped": [
    ]
}

Get one order with its lines, customer, address and history

Authorizations:
bearerAuth
path Parameters
id
required
string

Order id (for example ord_1001).

Responses

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "events": [
    ]
}

Mark a paid order as fulfilled

Only a paid order that has not shipped can be fulfilled. The status becomes fulfilled and a fulfilled event is added to the history.

Authorizations:
bearerAuth
path Parameters
id
required
string

Order id (for example ord_1001).

Request Body schema: application/json
required
carrier
required
string
trackingNumber
required
string
notifyCustomer
required
boolean

Email the customer the tracking link.

Responses

Request samples

Content type
application/json
{
  • "carrier": "DHL",
  • "trackingNumber": "string",
  • "notifyCustomer": true
}

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "events": [
    ]
}

Refund an order, in full or in part

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Order id (for example ord_1001).

Request Body schema: application/json
required
amount
required
integer >= 1

In cents, at most the order's refundable.

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).

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "reason": "string",
  • "restock": true
}

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "events": [
    ]
}

Cancel an order that has not shipped

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Order id (for example ord_1001).

Request Body schema: application/json
required
reason
required
string

May be empty.

restock
required
boolean

Put the items back in stock.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "restock": true
}

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "customer": {
    },
  • "shippingAddress": {
    },
  • "events": [
    ]
}

Products

Catalog list, product page (options and variants) and the write actions on products.

List products with filters, sorting and paging

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).

Authorizations:
bearerAuth
query Parameters
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"

out has no units in any variant, low has units but at least one variant at or under the low-stock threshold (or out), in_stock has units in every variant above the threshold.

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "counts": {
    },
  • "lowStockThreshold": 0
}

Create a product

The SKU of the product and of every variant must be unique in the whole catalog, ignoring case (SKUs are stored in upper case).

Authorizations:
bearerAuth
Request Body schema: application/json
required
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 price.

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 options.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "string",
  • "status": "active",
  • "price": 1,
  • "compareAtPrice": 0,
  • "cost": 0,
  • "sku": "string",
  • "options": [
    ],
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "string",
  • "status": "active",
  • "price": 1,
  • "compareAtPrice": 0,
  • "cost": 0,
  • "sku": "string",
  • "options": [
    ],
  • "variants": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "stats": {
    }
}

Every product that matches the filters, without paging

Used by the CSV export. Takes the same filters as the list, except page and pageSize.

Authorizations:
bearerAuth
query Parameters
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"

out has no units in any variant, low has units but at least one variant at or under the low-stock threshold (or out), in_stock has units in every variant above the threshold.

sort
string
Default: "name"
Enum: "name" "price" "stock" "sold"
direction
string
Default: "asc"
Enum: "asc" "desc"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Category names

Feeds the category filter and the category field of the product form.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • "Apparel",
  • "Footwear",
  • "Home"
]

Change the status of several products

Ids that no longer exist are skipped and reported; the call still succeeds.

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings non-empty
status
required
string (ProductStatus)
Enum: "active" "draft" "archived"

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "done": [
    ],
  • "skipped": [
    ]
}

Delete several products

Orders already placed keep what was bought. Ids that no longer exist are skipped and reported; the call still succeeds.

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "done": [
    ],
  • "skipped": [
    ]
}

Get one product with its options, variants and sales

Authorizations:
bearerAuth
path Parameters
id
required
string

Product id (for example prd_001).

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "string",
  • "status": "active",
  • "price": 1,
  • "compareAtPrice": 0,
  • "cost": 0,
  • "sku": "string",
  • "options": [
    ],
  • "variants": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "stats": {
    }
}

Replace a product

The body is the whole product, variants and their stock included. A product keeps its own SKUs; they only conflict with other products.

Authorizations:
bearerAuth
path Parameters
id
required
string

Product id (for example prd_001).

Request Body schema: application/json
required
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 price.

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 options.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "string",
  • "status": "active",
  • "price": 1,
  • "compareAtPrice": 0,
  • "cost": 0,
  • "sku": "string",
  • "options": [
    ],
  • "variants": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "category": "string",
  • "status": "active",
  • "price": 1,
  • "compareAtPrice": 0,
  • "cost": 0,
  • "sku": "string",
  • "options": [
    ],
  • "variants": [
    ],
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "stats": {
    }
}

Delete a product

Orders already placed keep what was bought.

Authorizations:
bearerAuth
path Parameters
id
required
string

Product id (for example prd_001).

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Inventory

Stock per variant, stock corrections and the movement history of a variant.

List variants with their stock, with filters, sorting and paging

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).

Authorizations:
bearerAuth
query Parameters
level
string (InventoryTab)
Enum: "all" "low" "out"

Stock-level tab. Leave it out for all variants. low has units, but no more than the threshold.

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 prd_001).

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "counts": {
    },
  • "lowStockThreshold": 0,
  • "product": {
    }
}

Every variant that matches the filters, without paging

Used by the CSV export. Takes the same filters as the list, except page and pageSize.

Authorizations:
bearerAuth
query Parameters
level
string (InventoryTab)
Enum: "all" "low" "out"

Stock-level tab. Leave it out for all variants. low has units, but no more than the threshold.

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 prd_001).

sort
string
Default: "name"
Enum: "name" "available" "committed"
direction
string
Default: "asc"
Enum: "asc" "desc"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Category names

Feeds the category filter.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • "Apparel",
  • "Footwear",
  • "Home"
]

Add the same quantity to several variants

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "skus": [
    ],
  • "quantity": 1,
  • "reason": "received",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "done": [
    ],
  • "skipped": [
    ]
}

Stock movements of a variant

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.

Authorizations:
bearerAuth
path Parameters
sku
required
string

Variant SKU (for example APP-001-M-BLK), unique in the catalog.

Responses

Response samples

Content type
application/json
{
  • "item": {
    },
  • "movements": [
    ],
  • "total": 0
}

Correct the stock of a variant

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.

Authorizations:
bearerAuth
path Parameters
sku
required
string

Variant SKU (for example APP-001-M-BLK), unique in the catalog.

Request Body schema: application/json
required
mode
required
string (AdjustMode)
Enum: "add" "remove" "set"
quantity
required
integer [ 0 .. 100000 ]

To add, to remove, or the new stock with set.

reason
required
string (AdjustReason)
Enum: "received" "correction" "damaged" "returned" "other"
note
required
string <= 200 characters

Optional; send an empty string for none.

Responses

Request samples

Content type
application/json
{
  • "mode": "add",
  • "quantity": 0,
  • "reason": "received",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "sku": "string",
  • "productId": "string",
  • "productName": "string",
  • "variantTitle": "string",
  • "category": "string",
  • "available": 0,
  • "committed": 0,
  • "incoming": {
    },
  • "level": "in_stock"
}

Customers

Customer list with segments, the customer page, internal notes, tags and marketing consent.

List customers with segments, filters, sorting and paging

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.

Authorizations:
bearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "counts": {
    },
  • "vipThreshold": 0
}

Every customer that matches the filters, without paging

Used by the CSV export. Takes the same filters as the list, except page and pageSize.

Authorizations:
bearerAuth
query Parameters
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"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Country codes

Feeds the country filter and the country field of the edit dialog.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • "AT",
  • "BE",
  • "FR",
  • "DE",
  • "IE",
  • "IT"
]

Add the same tag to several customers

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
required
Array of strings
tag
required
string

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "tag": "press"
}

Response samples

Content type
application/json
{
  • "done": [
    ],
  • "skipped": [
    ]
}

Customer page

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Change name, email and country

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).

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

Request Body schema: application/json
required
name
required
string <= 80 characters
email
required
string <email>
country
required
string

ISO 3166-1 alpha-2 code, one of /customers/countries.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Turn marketing consent on or off

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

Request Body schema: application/json
required
optIn
required
boolean

Responses

Request samples

Content type
application/json
{
  • "optIn": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Add an internal note

The note is signed with the name of the signed-in user. Customers never see notes.

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

Request Body schema: application/json
required
text
required
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Delete an internal note

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

noteId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Add a tag

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.

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

Request Body schema: application/json
required
tag
required
string

Responses

Request samples

Content type
application/json
{
  • "tag": "wholesale"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Remove a tag

Authorizations:
bearerAuth
path Parameters
id
required
string

Customer id (for example cus_001).

tag
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "country": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "marketingOptIn": true,
  • "tags": [
    ],
  • "segments": [
    ],
  • "stats": {
    },
  • "orders": [
    ],
  • "address": {
    },
  • "notes": [
    ]
}

Discounts

Discount codes with their conditions, limits, usage and the revenue they bring in.

List discount codes with status tabs, search, sorting and paging

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.

Authorizations:
bearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0,
  • "counts": {
    }
}

Create a discount code

A new code is enabled; it is scheduled or active depending on its start date.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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 scope categories, empty otherwise.

productIds
required
Array of strings

1 to 25 with scope products, empty otherwise.

minSubtotal
required
integer or null

Euro cents. Not together with minQuantity.

minQuantity
required
integer or null

1 to 1000. Not together with minSubtotal.

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 startsAt. Null = does not end.

Responses

Request samples

Content type
application/json
{
  • "code": "AUTUMN15",
  • "type": "percent",
  • "value": 0,
  • "scope": "all",
  • "categories": [
    ],
  • "productIds": [
    ],
  • "minSubtotal": 0,
  • "minQuantity": 0,
  • "usageLimit": 0,
  • "oncePerCustomer": true,
  • "startsAt": "2019-08-24T14:15:22Z",
  • "endsAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "code": "SPRING15",
  • "type": "percent",
  • "value": 0,
  • "status": "active",
  • "disabled": true,
  • "appliesTo": {
    },
  • "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": [
    ]
}

Categories a code can apply to

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • "string"
]

Find products to apply a code to

Matches the name or the SKU (case-insensitive). Returns at most 8 products; an empty search returns none.

Authorizations:
bearerAuth
query Parameters
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Enable, disable or delete several codes

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
action
required
string
Enum: "enable" "disable" "delete"
codes
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "action": "enable",
  • "codes": [
    ]
}

Response samples

Content type
application/json
{
  • "done": [
    ],
  • "skipped": [
    ]
}

Discount code page

Figures and the latest 10 orders that used the code, newest first. The code is not case sensitive.

Authorizations:
bearerAuth
path Parameters
code
required
string

Discount code (for example SPRING15), not case sensitive.

Responses

Response samples

Content type
application/json
{
  • "code": "SPRING15",
  • "type": "percent",
  • "value": 0,
  • "status": "active",
  • "disabled": true,
  • "appliesTo": {
    },
  • "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": [
    ]
}

Change a discount code

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.

Authorizations:
bearerAuth
path Parameters
code
required
string

Discount code (for example SPRING15), not case sensitive.

Request Body schema: application/json
required
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 scope categories, empty otherwise.

productIds
required
Array of strings

1 to 25 with scope products, empty otherwise.

minSubtotal
required
integer or null

Euro cents. Not together with minQuantity.

minQuantity
required
integer or null

1 to 1000. Not together with minSubtotal.

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 startsAt. Null = does not end.

Responses

Request samples

Content type
application/json
{
  • "code": "AUTUMN15",
  • "type": "percent",
  • "value": 0,
  • "scope": "all",
  • "categories": [
    ],
  • "productIds": [
    ],
  • "minSubtotal": 0,
  • "minQuantity": 0,
  • "usageLimit": 0,
  • "oncePerCustomer": true,
  • "startsAt": "2019-08-24T14:15:22Z",
  • "endsAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "code": "SPRING15",
  • "type": "percent",
  • "value": 0,
  • "status": "active",
  • "disabled": true,
  • "appliesTo": {
    },
  • "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": [
    ]
}

Disable or enable a code

Authorizations:
bearerAuth
path Parameters
code
required
string

Discount code (for example SPRING15), not case sensitive.

Request Body schema: application/json
required
disabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "disabled": true
}

Response samples

Content type
application/json
{
  • "code": "SPRING15",
  • "type": "percent",
  • "value": 0,
  • "status": "active",
  • "disabled": true,
  • "appliesTo": {
    },
  • "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": [
    ]
}

Delete a discount code

Orders that used the code keep it.

Authorizations:
bearerAuth
path Parameters
code
required
string

Discount code (for example SPRING15), not case sensitive.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Settings

Profile, notification preferences and security of the signed-in user.

Get the profile of the signed-in user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Replace the profile

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
email
required
string <email>
company
required
string
jobTitle
required
string
timezone
required
string
language
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "name": "Ada Demo",
  • "email": "ada@acme.test",
  • "company": "Acme Demo",
  • "jobTitle": "Head of Finance",
  • "timezone": "Europe/Berlin",
  • "language": "en"
}

Upload the avatar

The client sends a 256x256 JPEG as the avatar field (file name avatar.jpg).

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
avatar
required
string <binary>

Avatar image (JPEG, 256x256).

Responses

Response samples

Content type
application/json

Remove the avatar

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Get notification preferences

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "weeklyReport": true,
  • "lowStockAlerts": true,
  • "refundAlerts": true,
  • "newOrders": true,
  • "productUpdates": true,
  • "lowStockThreshold": 0,
  • "channel": "email"
}

Replace notification preferences

Authorizations:
bearerAuth
Request Body schema: application/json
required
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"

Responses

Request samples

Content type
application/json
{
  • "weeklyReport": true,
  • "lowStockAlerts": true,
  • "refundAlerts": true,
  • "newOrders": true,
  • "productUpdates": true,
  • "lowStockThreshold": 0,
  • "channel": "email"
}

Response samples

Content type
application/json
{
  • "weeklyReport": true,
  • "lowStockAlerts": true,
  • "refundAlerts": true,
  • "newOrders": true,
  • "productUpdates": true,
  • "lowStockThreshold": 0,
  • "channel": "email"
}

Get two-factor status and active sessions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Change the password

Authorizations:
bearerAuth
Request Body schema: application/json
required
current
required
string <password>
next
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "current": "pa$$word",
  • "next": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "Invalid email or password."
}

Enable or disable two-factor authentication

Authorizations:
bearerAuth
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Revoke an active session

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "twoFactorEnabled": true,
  • "sessions": [
    ]
}

Store settings

Store details, shipping zones, taxes, payment methods and checkout options. Only the Owner can change them.

All store settings

Every member can read them; only the Owner (store.manage) can change them.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "details": {
    },
  • "shipping": {
    },
  • "taxes": {
    },
  • "payments": {
    },
  • "checkout": {
    }
}

Save the store details

The currency is always EUR and cannot change.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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 # gives #1001. Can be empty.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "contactEmail": "user@example.com",
  • "currency": "EUR",
  • "timezone": "Europe/Rome",
  • "orderPrefix": "stri"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "contactEmail": "user@example.com",
  • "currency": "EUR",
  • "timezone": "Europe/Rome",
  • "orderPrefix": "stri"
}

Save the shipping zones and rates

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects (ShippingZone) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "zones": [
    ]
}

Response samples

Content type
application/json
{
  • "zones": [
    ]
}

Save the tax settings

Changing rates does not change the totals of orders already placed.

Authorizations:
bearerAuth
Request Body schema: application/json
required
pricesIncludeTax
required
boolean
required
Array of objects (TaxRate) non-empty

Responses

Request samples

Content type
application/json
{
  • "pricesIncludeTax": true,
  • "rates": [
    ]
}

Response samples

Content type
application/json
{
  • "pricesIncludeTax": true,
  • "rates": [
    ]
}

Save the payment methods

At least one method must be on. The bank transfer instructions are required when bank transfer is on. No real payment data is stored.

Authorizations:
bearerAuth
Request Body schema: application/json
required
card
required
boolean
paypal
required
boolean
bankTransfer
required
boolean
cashOnDelivery
required
boolean
bankTransferInstructions
required
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "card": true,
  • "paypal": true,
  • "bankTransfer": true,
  • "cashOnDelivery": true,
  • "bankTransferInstructions": "string"
}

Response samples

Content type
application/json
{
  • "card": true,
  • "paypal": true,
  • "bankTransfer": true,
  • "cashOnDelivery": true,
  • "bankTransferInstructions": "string"
}

Save the checkout options

Guest checkout or required customer accounts, and whether customers can leave an order note.

Authorizations:
bearerAuth
Request Body schema: application/json
required
customerAccounts
required
string
Enum: "optional" "required"
orderNotes
required
boolean

Responses

Request samples

Content type
application/json
{
  • "customerAccounts": "optional",
  • "orderNotes": true
}

Response samples

Content type
application/json
{
  • "customerAccounts": "optional",
  • "orderNotes": true
}

Team

Members of the workspace, their roles and pending invitations.

Get members, pending invitations and the member count

Every member can read the team.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Invite a person to the workspace

Pending invitations are listed with the team until accepted or revoked. Ownership cannot be granted by invitation.

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
required
string <email>
role
required
string (AssignableRole)
Enum: "admin" "staff" "viewer"

Any role except owner.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Send the invitation again and renew its expiry

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Revoke a pending invitation

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Change a member's role

The owner's role cannot be changed and nobody can be made owner here.

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Request Body schema: application/json
required
role
required
string (AssignableRole)
Enum: "admin" "staff" "viewer"

Any role except owner.

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Remove a member from the workspace

The owner cannot be removed.

Authorizations:
bearerAuth
path Parameters
id
required
string

Member or invitation id.

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "invites": [
    ],
  • "seats": {
    }
}

Developers

API keys and webhook endpoints of the workspace.

Get API keys and webhook endpoints

Every member can read them. Secrets are never included, only the key prefix.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Create an API key

The full secret is returned only in this response; only its first 12 characters are kept. At most 10 keys per workspace.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "access": "read",
  • "expiresInDays": 30
}

Response samples

Content type
application/json
{
  • "developers": {
    },
  • "secret": "pk_live_3fA9xK2mQ7vLw0ZpR8dTn5BcY1hGe4Sj"
}

Revoke an API key

Apps using the key stop working immediately.

Authorizations:
bearerAuth
path Parameters
id
required
string

API key id.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Add a webhook endpoint

The endpoint starts enabled. At most 5 endpoints per workspace.

Authorizations:
bearerAuth
Request Body schema: application/json
required
url
required
string <uri>

Must be an https:// URL.

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"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Edit or enable/disable a webhook endpoint

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "events": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Delete a webhook endpoint

Its delivery history is removed too.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ],
  • "webhooks": [
    ]
}

Send a test event to an endpoint

Sends a customer.created test event and records the delivery.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "event": "order.created",
  • "status": "succeeded",
  • "statusCode": 200,
  • "durationMs": 0,
  • "at": "2019-08-24T14:15:22Z"
}

List the recent deliveries of an endpoint

Newest first, at most 20. Every member can read them.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send a past delivery again

Creates a new delivery for the same event.

Authorizations:
bearerAuth
path Parameters
id
required
string

Webhook endpoint id.

deliveryId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "event": "order.created",
  • "status": "succeeded",
  • "statusCode": 200,
  • "durationMs": 0,
  • "at": "2019-08-24T14:15:22Z"
}