Products API: Create, List, and Manage Shop Products

The Products API lets you manage every item your shop sells. You can create products with pricing and stock details, upload images, assign them to categories, and search or update them individually.

Create a product

POST /api/v1/shops/{shop_id}/products/ Creates a new product in the specified shop. Only name and price are required — all other fields have sensible defaults.

Request body

string

required

The display name of the product.

number

required

The selling price of the product. Must be greater than or equal to 0.

string

default:"\"\""

A detailed description of the product shown to customers.

string

default:"\"\""

The product’s barcode (EAN, UPC, or custom). Used for POS scanning and barcode lookup.

number

default:"0"

The purchase or production cost of the product. Used for profit margin calculations.

integer

default:"0"

Initial stock quantity.

integer

default:"10"

The stock level at which a low-stock alert is triggered.

string

default:"\"piece\""

Unit of measurement (e.g., "piece", "kg", "litre").

integer

ID of the category to assign this product to. Must belong to the same shop. Optional.

string

default:"\"\""

A URL pointing to the product’s primary image. To upload binary files directly, use the Upload product image endpoint after creation.

curl -X POST https://api.mutasib.com/api/v1/shops/42/products/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Organic Olive Oil 500ml",
    "price": 34.99,
    "cost": 18.50,
    "barcode": "6281234567890",
    "stock": 120,
    "low_stock_threshold": 20,
    "unit": "bottle",
    "category_id": 7,
    "description": "Cold-pressed extra virgin olive oil from local farms."
  }'

Returns 201 Created with a ProductOut object.

List products

GET /api/v1/shops/{shop_id}/products/ Returns a paginated list of products in the shop. Use the query parameters below to filter by category, search term, or active status.

Query parameters

integer

Filter products by a specific category ID.

string

Filter products whose name or barcode contains this string (case-insensitive).

boolean

When true, returns only products with is_active: true. Defaults to false.

curl "https://api.mutasib.com/api/v1/shops/42/products/?category_id=7&active_only=true" \
  -H "Authorization: Bearer <your_token>"

Returns 200 OK with an array of ProductOut objects.

Search products

GET /api/v1/shops/{shop_id}/products/search/ Performs a full-text search across product names and descriptions within the shop. This endpoint is optimized for quick lookups from POS or inventory management screens.

Query parameters

string

required

The search query string.

boolean

When true, limits results to active products only. Defaults to false.

curl "https://api.mutasib.com/api/v1/shops/42/products/search/?q=olive+oil&active_only=true" \
  -H "Authorization: Bearer <your_token>"

Returns 200 OK with an array of matching ProductOut objects.

Get a product

GET /api/v1/shops/{shop_id}/products/{product_id}/ Retrieves a single product by its ID.

curl https://api.mutasib.com/api/v1/shops/42/products/301/ \
  -H "Authorization: Bearer <your_token>"

Returns 200 OK with a ProductOut object, or 404 Not Found if the product does not exist in this shop.

Update a product

PATCH /api/v1/shops/{shop_id}/products/{product_id}/ Partially updates one or more fields on a product. Only the fields you include are changed.

string

Updated product name.

string

Updated product description.

string

Updated barcode value.

number

Updated selling price.

number

Updated purchase cost.

integer

Updated stock quantity. This sets the absolute stock level — it does not add or subtract.

integer

Updated low-stock alert threshold.

string

Updated unit of measurement.

integer

Updated category assignment.

boolean

Set to false to deactivate the product without deleting it.

curl -X PATCH https://api.mutasib.com/api/v1/shops/42/products/301/ \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 29.99,
    "stock": 85
  }'

Returns 200 OK with the updated ProductOut object.

Deactivate a product

DELETE /api/v1/shops/{shop_id}/products/{product_id}/ Soft-deletes a product by setting is_active to false. The product is hidden from POS and storefront views but remains in the database and can be reactivated via the Update product endpoint.

curl -X DELETE https://api.mutasib.com/api/v1/shops/42/products/301/ \
  -H "Authorization: Bearer <your_token>"

Returns 204 No Content on success.

This endpoint performs a soft delete. To permanently remove a product, contact Mutasib support. To reactivate a deactivated product, send PATCH /api/v1/shops/{shop_id}/products/{product_id}/ with { "is_active": true }.

Upload a product image

POST /api/v1/shops/{shop_id}/products/{product_id}/images/ Uploads a binary image file and attaches it to the product. The request must use multipart/form-data encoding. A product can have multiple images; use sort_order to control display order.

Form fields

file

required

The image file to upload. Accepted formats: JPEG, PNG, WebP.

string

Descriptive alt text for accessibility and SEO.

integer

Display order for this image. Lower numbers appear first. Defaults to 0.

curl -X POST https://api.mutasib.com/api/v1/shops/42/products/301/images/ \
  -H "Authorization: Bearer <your_token>" \
  -F "file=@olive_oil.jpg" \
  -F "alt_text=Organic olive oil bottle" \
  -F "sort_order=0"

Returns 201 Created with the uploaded image object containing id, image, alt_text, and sort_order.

Delete a product image

DELETE /api/v1/shops/{shop_id}/products/{product_id}/images/{image_id}/ Removes a specific image from the product. The image file is deleted from storage.

curl -X DELETE https://api.mutasib.com/api/v1/shops/42/products/301/images/5/ \
  -H "Authorization: Bearer <your_token>"

Returns 204 No Content on success.

ProductOut response fields

integer

Unique numeric identifier for the product.

integer

ID of the shop this product belongs to.

integer | null

ID of the assigned category, or null if uncategorized.

string | null

Display name of the assigned category, or null if uncategorized.

string

Display name of the product.

string

Product description.

string

The product’s barcode string.

string

Current selling price, returned as a decimal string (e.g., "34.99").

string

Purchase or production cost, returned as a decimal string (e.g., "18.50").

integer

Current inventory stock level.

integer

The stock level at which low-stock alerts fire.

string

Unit of measurement (e.g., "piece", "kg", "litre").

boolean

Whether the product is active and visible in POS and inventory views.

array

List of image objects attached to this product.

Show properties

integer

Unique image ID.

string

Public URL of the uploaded image.

string

Descriptive alt text for the image.

integer

Display order; lower numbers appear first.

string

ISO 8601 timestamp of when the product was created.

string

ISO 8601 timestamp of the most recent update.

Shops

Products

Sales & Inventory

Public & Misc

Products API: Create, List, and Manage Shop Products

Create a product

Request body

List products

Query parameters

Search products

Query parameters

Get a product

Update a product

Deactivate a product

Upload a product image

Form fields

Delete a product image

ProductOut response fields

​Create a product

​Request body

​List products

​Query parameters

​Search products

​Query parameters

​Get a product

​Update a product

​Deactivate a product

​Upload a product image

​Form fields

​Delete a product image

​ProductOut response fields

Create a product

Request body

List products

Query parameters

Search products

Query parameters

Get a product

Update a product

Deactivate a product

Upload a product image

Form fields

Delete a product image

ProductOut response fields