Products API

The Products API covers a tenant's full catalog: search and listing, product detail, create/edit/delete, variants, media, automotive compatibility (fitment), materials/supplies/BOM/modifiers (manufacturing and POS), bulk operations (rollback, visual flow editing, AI mutations), CSV import/export, categorization, and publishing to marketplaces, collections, and categories.

Read this before any other article in this section. Unlike other domains in this API, there is no single response contract here — that's the single most important finding in the whole domain, and it shapes how you should read every article that follows.

Domain architecture

"Products" in this API is actually three independent lambdas behind three separate route bases, each with its own authorization scheme:

All of them require authentication; each lambda's internal routing is done by its own code via path/method, not by API Gateway.

Base URL and authentication

https://api.fenicia.io

There is no version prefix (/v1) in the URL. Every request requires an API key sent as a Bearer token:

Authorization: Bearer fkapi_your_api_key

⚠️ There is no single response envelope

In the Orders domain, every response follows {data, meta} / {error}. That is not true in Products. Only one endpoint in the whole domain uses that envelope; the rest respond with ad-hoc shapes per endpoint — some wrapped, some not wrapped at all, some as a flat array.

Real examples, so you can calibrate the variety:

{
  "data": [
    { "sku": "CAM-ROJO-M", "title": { "value": "Camisa Roja Talla M" }, "price": 499.0, "status": "active" }
  ],
  "meta": {
    "pagination": { "page": 0, "limit": 20, "total": 143, "totalPages": 8, "hasMore": true }
  }
}

[
  { "sku": "CAM-ROJO-M", "title": { "value": "Camisa Roja Talla M" }, "price": 499.0, "status": "active" }
]

See Catalog and search for the full detail on GET /products and its two shapes.

Pagination

page and limit are the pagination parameters across the entire listing surface. The base is consistent (page starts at 0), but the default and ceiling of limit vary by endpoint — there is no single global value:

• page: integer, base 0 across all listing endpoints.
• limit: the most common default in lambda-products is 20; the underlying library's validator (validatePagination) uses 50 as a generic default and applies a ceiling of 500 on the vast majority of routes.
• Ceiling exception: async CSV export uses EXPORT_MAX_LIMIT = 10000, far above the rest of the domain.

Confirm the exact default and maximum in each endpoint's article before assuming them — Catalog and search documents those of GET /products, and Bulk CSV documents those of import/export.

Projection with extend

GET /products/{id} (and, at the library level, the rest of the listing endpoints) supports ?extend= to request fields that don't come by default in the base projection (the default response weighs ~3 KB per product; without extend, several heavy fields are intentionally omitted).

You can combine several comma-separated values: ?extend=variants,inventory,seo.

Full response detail with each value in Retrieve a product.

Permissions

The permission catalog lives in @fenicia/core. Each route base uses its own namespace, with one notable exception:

PRODUCTS.READ    products:read      PRODUCTS.CREATE   products:create
PRODUCTS.UPDATE  products:update    PRODUCTS.DELETE   products:delete
PRODUCTS.IMPORT  products:import    PRODUCTS.EXPORT   products:export
PRODUCTS.SYNC    products:sync      PRODUCTS.MANAGE   products:manage
PRODUCTS.ALL     products:*

COLLECTIONS.* follows the same pattern (READ/CREATE/UPDATE/DELETE) for /collections/....

Stacked RBAC — some routes require two permissions, not one

Most endpoints validate a single permission. A subset requires two, stacked, and there is a documented asymmetry between dev and production:

Don't assume "one permission per route" when integrating: confirm in the specific article (Channel publishing, Bulk operations) whether the route you're calling requires more than one.

Irreversible operations

Known limits of this API version

• No granular endpoints for attributes/custom fields, SEO, or price schemas: all of that is read via ?extend= but only written by resending the full product payload via PUT /products/{id}. See Manage products.
• No endpoints to delete or reorder media: the full media[] array is rewritten via PUT /products/{id}. See Variants and media.
• No HTTP "bundle" entity exists: the only product-of-products composition mechanism with its own endpoints is BOM (oriented to manufacturing/consumption). bundleConfig is a data sub-shape managed inside the product payload, with no /products/{sku}/bundle routes. See Data model and Materials and BOM.

Quick example

curl "https://api.fenicia.io/products?limit=5" \
  -H "Authorization: Bearer $FENICIA_API_KEY"

Section map

Next steps

• Catalog and search
• Data model
• Error catalog