Products#

Reusable product and service items, and the categories that group them. Physical products can opt
into branch-scoped inventory tracking; services and untracked products remain catalog-only items.

Overview#

• 🧾 One catalog for products and services — type distinguishes them
• 🗂️ Categories and sub-categories — at most one of each per item
• 🔁 Reused on invoices — selecting an item fills the line's name, description, price, tax and discount ($ or %)
• 🖼️ One image per item — JPEG, PNG, WebP or SVG up to 2 MB, served from a public URL
• 🔢 Optional per-order limit — maxQuantity caps how much of an item one invoice or POS cart may hold
• 📦 Optional inventory tracking — tracked physical products use server-owned branch balances
• 📥 Excel import / export — .xlsx, validated all-or-nothing
• 🔒 Per merchant — a catalog is never shared between merchants

All endpoints require Authorization: Bearer <token> and X-Tenant-ID, plus a user permission:

A missing permission returns 403 FORBIDDEN. API keys carry no user, so x-api-key calls to these endpoints are refused with 403 as well.

Merchant scope#

The merchant is taken from the access token. A merchant-scoped session may not read or write
another merchant's catalog, and passing a different merchantId returns 403 FORBIDDEN rather
than being ignored.

Platform-level tokens carry no merchant, so they must name one explicitly with the merchantId
query parameter (or, on a write, in the body).

Response shape#

Every endpoint answers with the platform envelope:

{ "success": true, "data": { }, "meta": { "page": 1, "limit": 10, "total": 42 } }

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Price must be 0 or greater" } }

The product object#

{
  "id": "2f1c...",
  "type": "product",
  "name": "Hardware Kit",
  "description": "Standard equipment bundle",
  "price": 480.50,
  "unit": "box",
  "unitLabel": "Box",
  "discountValue": 5,
  "discountType": "percent",
  "taxRate": 8.25,
  "productCode": "KIT-STD",
  "status": "active",
  "isFavorite": false,
  "imageUrl": "https://cdn.example.com/products/tenant-1/6f1c.../2f1c.../8d0b....png",
  "maxQuantity": 10,
  "soldQuantity": 12,
  "categoryId": "9b0e...",
  "categoryName": "Hardware",
  "subCategoryId": "41aa...",
  "subCategoryName": "Parts",
  "sku": "HW-KIT",
  "trackInventory": true,
  "lowQuantityThreshold": 2,
  "unitCost": 275.00,
  "allowZeroStockSale": false,
  "onHand": 12,
  "reserved": 4,
  "available": 8,
  "createdAt": "2026-09-23T02:55:30.000Z",
  "updatedAt": "2026-09-23T02:55:30.000Z"
}

price, discountValue, taxRate, maxQuantity, soldQuantity, lowQuantityThreshold,
unitCost, onHand, reserved, and available are JSON numbers when present, not strings.

imageUrl and maxQuantity are local to AuxCORE and are not sent to Aux365.

A fixed discount is deliberately not capped at the price: an invoice line carries a quantity, and
the line is where the charge is finally worked out.

curl "https://uat.auxcore.net/api/v1/products?status=active&limit=200" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": [ { "id": "2f1c...", "name": "Hardware Kit", "price": 480.50 } ],
  "meta": { "page": 1, "limit": 200, "total": 1 }
}

Get one product#

Returns 404 NOT_FOUND for an id outside the caller's merchant, so a missing product and another
merchant's product are indistinguishable.

{
  "type": "product",
  "name": "Hardware Kit",
  "price": 480.50,
  "discountValue": 5,
  "discountType": "percent",
  "taxRate": 8.25,
  "description": "Standard equipment bundle",
  "status": "active",
  "isFavorite": true,
  "categoryId": "9b0e...",
  "subCategoryId": "41aa..."
}

curl -X POST https://uat.auxcore.net/api/v1/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -F 'data={"type":"product","name":"Hardware Kit","price":480.50,"maxQuantity":10}' \
  -F "image=@kit.png"

Update a product#

Takes the same body as create and replaces every field, so send the whole object. Omitting
categoryId or taxRate clears it rather than leaving it alone. unit, isFavorite and
maxQuantity are the exceptions: omitted, they are left as they are.

The image is never touched by a JSON update. To change it, either:

• send the update as multipart (data + image, as for create) — the new image replaces the old one; or
• add "removeImage": true to the body to clear it.

The replaced image file is deleted from storage once the product points at the new one.

Updating a product never changes an invoice that already includes it: invoices keep their own copy
of each line.

Product image#

PUT    /api/v1/products/:id/image
DELETE /api/v1/products/:id/image

Change or remove only the image, without resending the product. PUT takes multipart/form-data
with the file in the image field (same rules and errors as a create with an image); DELETE
takes no body and succeeds on a product that has no image. Both return the updated product and
require invoices.manage.

curl -X PUT https://uat.auxcore.net/api/v1/products/2f1c.../image \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -F "image=@kit.webp"

Per-order quantity limit#

A product with a maxQuantity may appear in one order — an invoice, or a POS cart sent with a
payment — at most that many units, summed across all of the order's lines with its
productId. Two lines of 3 for a product limited to 5 are refused. Lines without a productId
(custom invoice lines, POS misc lines) never count.

Checked on:

external-payment also validates the product cart, but money may already have been collected by
the device SDK. A limit or other inventory rejection is therefore persisted with the financial
record instead of rejecting or reversing the payment. When POS inventory settlement is enabled and
the payment reaches finality, the server queues inventory work. Stock or location conflicts accepted
by Invoice become Pending Review; a terminal Transaction delivery failure remains operational
recovery work. Limits are not checked on invoices synchronised from Aux365 or generated by a
recurring schedule — those record an order that exists, they do not create one. A product that is
deleted after being added to an order has no limit.

{
  "success": false,
  "error": {
    "code": "QUANTITY_LIMIT_EXCEEDED",
    "message": "\"Diesel\" is limited to 50 per order; this order has 60.",
    "details": {
      "violations": [
        { "productId": "2f1c...", "name": "Diesel", "maxQuantity": 50, "requested": 60 }
      ]
    }
  }
}

400. details.violations lists every product over its limit, so a client can mark each
offending line. Enforce the limit in the client too (block the add or the quantity change), and
treat this error as the fallback.

{ "status": "inactive" }

{ "isFavorite": true }

{ "ids": ["2f1c...", "77ab..."] }

{
  "success": true,
  "data": { "deleted": 1, "notFound": ["77ab..."] }
}

Bulk edit#

Set one or more fields on many products at once — the ticked rows, or every product matching the
list filters. The edit runs as a background job so a large selection can report progress. Starting and cancelling need invoices.manage; reading a job needs invoices.view.

{
  "selection": { "mode": "ids", "ids": ["2f1c...", "77ab..."] },
  "changes": {
    "status": "inactive",
    "price": { "mode": "adjust_percent", "value": -10 },
    "taxRate": null
  }
}

{
  "success": true,
  "data": {
    "id": "9b2d...",
    "status": "running",
    "total": 1532,
    "processed": 600,
    "updated": 588,
    "unchanged": 12,
    "skipped": 0,
    "changes": { "status": "inactive" },
    "error": null,
    "cancelRequested": false,
    "createdAt": "2026-10-22T07:01:12.000Z",
    "startedAt": "2026-10-22T07:01:12.000Z",
    "finishedAt": null
  }
}

Active bulk edit#

The merchant's queued or running job in the same shape, or data: null — what a page opened mid-job reads to show the progress again.

Cancel a bulk edit#

A queued job is cancelled at once; a running one stops before its next batch and ends as cancelled. Answers with the job. Cancelling a finished job changes nothing.

Every changed product is announced to Aux365 as product.updated, except a change to isFavorite alone, which stays local.

Categories#

GET    /api/v1/product-categories
POST   /api/v1/product-categories
PUT    /api/v1/product-categories/:id
DELETE /api/v1/product-categories/:id

POST   /api/v1/product-categories/:id/sub-categories
PUT    /api/v1/product-categories/:id/sub-categories/:subId
DELETE /api/v1/product-categories/:id/sub-categories/:subId

The list returns each category with its sub-categories and usage counts:

{
  "success": true,
  "data": [
    {
      "id": "9b0e...",
      "name": "Hardware",
      "productCount": 4,
      "createdAt": "2026-09-23T02:50:00.000Z",
      "subCategories": [
        { "id": "41aa...", "categoryId": "9b0e...", "name": "Parts", "productCount": 2,
          "createdAt": "2026-09-23T02:51:00.000Z" }
      ]
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 1 }
}

The list takes search, page and limit (default 10, capped at 100).

Create and update both take { "name": "Hardware" }. Creating a category or sub-category responds 201; a delete responds { "success": true, "data": { "id": "..." } }.

Sub-categories are addressed through their parent category, so the parentage is checked by the
route itself.

Rules#

• A category name is unique per merchant, ignoring case.
• A sub-category name is unique within its category, ignoring case — the same name may exist under
  different categories.
• Names are trimmed and limited to 100 characters; whitespace-only is rejected.

Errors#

Deleting a category is refused until the products using it are reassigned or cleared. Once allowed,
it also removes that category's sub-categories.

curl -X POST https://uat.auxcore.net/api/v1/products/export   -H "Authorization: Bearer YOUR_TOKEN"   -H "X-Tenant-ID: your-tenant-id"   -H "Content-Type: application/json"   -d '{"ids": ["3f2504e0-4f89-41d3-9a0c-0305e82c3301"], "columns": ["tax", "status"]}'   -o products.xlsx

Import#

GET  /api/v1/products/import-template
POST /api/v1/products/import

import-template returns a blank .xlsx with the expected headers, dropdowns on Type, Status,
Discount Type and Unit, and an Instructions sheet.

POST /products/import takes multipart/form-data with the file in the file field, max 5 MB.

curl -X POST https://uat.auxcore.net/api/v1/products/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -F "file=@products.xlsx"

Columns#

Headers are matched by name, case-insensitively, so column order does not matter. Subcategory is
accepted as well as Sub-category, and ProductID / ID as well as Product ID. Blank rows are skipped.

Updating existing products#

A row whose Product ID is one of the caller's live products updates that product; every other
row adds a new one. To bulk-edit, export, change the cells, and import the file back.

• A Product ID that is not a valid id, is deleted, or belongs to another merchant is ignored: the
  row is added as a new product and listed in warnings.
• A column left out of the file keeps the product's current value, so a sheet with only Product ID,
  Name, Price and Tax edits only those. A blank Type, Status or Discount Type also keeps it; any
  other blank cell clears that field.
• A row identical to its product is counted as unchanged and not written.
• The same Product ID on two rows is a row error.
• Images and favorites are never changed by import.

Updating needs invoices.manage as well as invoices.create. A file that would change an
existing product without it is refused with 403 FORBIDDEN and nothing is written.

All or nothing#

A readable file always answers 200. Check data.imported, not the status code:

{
  "success": true,
  "data": {
    "imported": 0,
    "created": 0,
    "updated": 0,
    "unchanged": 0,
    "totalRows": 3,
    "validRows": 2,
    "errors": [
      { "row": 3, "column": "Price", "message": "Price must be 0 or greater" }
    ],
    "warnings": []
  }
}

If any row fails validation nothing is written — no row is added or updated, including the rows
that passed. row is the 1-based row number as Excel shows it, so it points at the line to fix.
Correct the file and upload it again.

On success imported is created + updated. warnings lists rows whose Product ID matched no
product and were added as new; re-uploading a file whose rows have no Product ID adds them again.
Images cannot be imported — add them per product afterwards. Import never creates categories — an
unknown Category or Sub-category is a row error.

400 VALIDATION_ERROR is returned when the file itself is unusable: not a readable .xlsx, missing
the Name or Price column, containing no product rows, or holding more than 2,000 rows.