Guide

Products

Browsing is public and requires no authentication. Listing and managing products requires a SELLER account with a shop and an active subscription. A separate set of staff-only endpoints handles categories, currency exchange rates, and moderation. Every endpoint mentioned on this page lives under https://api.swiftgoma.com/api/v1/products.

Catalog structure

Every product belongs to a subcategory, which belongs to a category. A product has one or more variants — even a product with no real variation (no size or color options) is modeled as a single default variant, which is what actually carries the price and stock.

Level	Examples	Managed by
Category	Alimentation & Boissons, Électronique	Staff
Subcategory	Boissons, Téléphones & tablettes	Staff
Product	“Riz parfumé 25kg”	Seller
Variant	Price + stock (e.g. 25kg bag at $12.50, 40 in stock)	Seller

Browsing the catalog

No authentication required. Only PUBLISHED products from PUBLISHED shops are ever returned.

Endpoint	Use it for
GET /	Search and filter — category, subcategory, shop, price range, currency, city, in-stock only, free-text search, and sorting (recent, popular, price asc/desc).
GET /popular	A shortcut for sortBy=popular — ranked by a rolling 30-day blend of sales, favorites, views, and reviews.
GET /slug/:slug	Full product detail — images, variants, rating summary, recent reviews, purchase count.

List and popular results are cached for 2 minutes per unique filter combination. Product detail by slug is cached for 5 minutes.

Multi-currency pricing

Every product is priced in a single currency — USD or CDF — set at creation and fixed after that. Cross-currency conversion for display purposes runs off staff-managed exchange rates rather than a live market feed.

POST /exchange-rates/preview (staff-only) converts an amount between currencies using the configured rate without writing anything — useful for building admin tooling around pricing.

Listing a product

Requires a SELLER account with an existing shop and an active subscription — plan tier determines how many products and photos-per-product are allowed.

1
Create the product
POST / (multipart/form-data) with the product fields, a JSON-encoded variants array, and up to 10 images. It's created as DRAFT.
2
Publish it
POST /:id/status with { "status": "PUBLISHED" } makes it visible in the public catalog.
3
Edit descriptive fields anytime
PUT /:id covers name, description, brand, unit, weight, and expiry — not images, variants, or status.

A few validation rules to know upfront

Name is 2–100 characters, description 20–1000. At least one variant is required, up to a maximum of 50. Prices and stock have per-currency bounds. Products in the Alimentation & Boissons category require a future-dated expiry — including on later edits, so clearing it isn't possible without also removing the product from that category.

Product status lifecycle

From	Can move to
DRAFT	PUBLISHED
PUBLISHED	ARCHIVED, DRAFT
ARCHIVED	DRAFT

Managing inventory

Stock is adjusted with a signed delta rather than set to an absolute value, and every change is logged.

Action	Endpoint
Adjust stock	POST /variants/:variantId/stock
View movement history	GET /variants/:variantId/stock/history

A negative amount that would take stock below zero is rejected atomically — concurrent adjustments on the same variant can't race each other into a negative balance.

Reviews

Any signed-in buyer who has actually received a product (order status DELIVERED or COMPLETED) can leave a 1–5 star rating with a comment via POST /:productId/reviews. One review per buyer per product — submitting again replaces the previous one rather than adding a second.

Categories & exchange rates

Both are staff-managed (ADMIN or SUPPORT) — full CRUD lives in the reference under Categories and Exchange Rates. A category can't be deleted while it still has subcategories, and a subcategory can't be deleted while products are still attached to it.

Moderation

Staff can browse every product on the platform and take one down, regardless of shop or current status.

Action	Endpoint
List all products	GET /admin
Get any product's detail	GET /admin/:id
Draft or archive a product	POST /admin/:id/status

Moderation can only take products down

The staff status endpoint only accepts DRAFT or ARCHIVED — it deliberately can't set a product to PUBLISHED, so staff can moderate a listing but can never publish on a seller's behalf.

Browse the Products endpoints in the API Reference