Skip to content
MicroPIM Docs

REST API Reference

MicroPIM provides a RESTful API for integrating with external systems, importing data, and building custom workflows.

Authentication

Section titled “Authentication”

All API requests require an API key sent via the X-API-KEY header.

Terminal window
curl -H "X-API-KEY: your-api-key" https://app.micropim.net/api/products

Requests without a valid API key return 401 Unauthorized.

Response Format

Section titled “Response Format”

All endpoints return a consistent JSON envelope:

{
  "status": 1,
  "data": { ... },
  "error": null
}

On error:

{
  "status": 0,
  "data": null,
  "error": "Error description"
}

Rate Limiting

Section titled “Rate Limiting”

API requests are rate-limited per IP. Read endpoints have a higher limit than write endpoints. When exceeded, the API returns 429 Too Many Requests.

Products

Section titled “Products”

List Products

Section titled “List Products”
GET /api/products

Query Parameters:

ParameterTypeDescription
searchstringSearch in name, description, and SKU
statusstringFilter by status: draft, active, archived, out_of_stock
brandintegerFilter by brand ID
channelstringFilter by publishing channel: web, mobile, api, marketplace, social, email
pageintegerPage number (default: 1)
limitintegerItems per page, 1-100 (default: 20)

Example Response:

{
  "status": 1,
  "data": {
    "products": [
      {
        "id": 1,
        "sku": "PROD-001",
        "slug": "product-name",
        "name": "Product Name",
        "description": "<p>Full description</p>",
        "short_description": "Brief summary",
        "product_type": "simple",
        "price": "99.9900",
        "sale_price": "79.9900",
        "cost_price": "50.0000",
        "currency": "EUR",
        "status": "active",
        "stock": 150,
        "in_stock": true,
        "ean": "1234567890123",
        "vat_rate": {
          "id": 1,
          "name": "Standard Rate",
          "rate": "19.0000",
          "country_code": "RO"
        },
        "brand": {
          "id": 1,
          "name": "Brand Name"
        },
        "supplier": {
          "id": 1,
          "name": "Supplier Name"
        },
        "categories": [
          {"id": 1, "name": "Electronics"}
        ],
        "images": [
          "https://cdn.example.com/image.webp"
        ],
        "publishing_channels": ["web", "marketplace"],
        "available_translations": ["en", "ro"],
        "product_condition": "new",
        "attributes": {}
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 100,
      "items_per_page": 20
    }
  },
  "error": null
}

Get Product Details

Section titled “Get Product Details”
GET /api/products/{id}

Returns the full product object as shown in the list response.

Create Product

Section titled “Create Product”
POST /api/products

Request Body:

{
  "name": "New Product",
  "sku": "SKU-001",
  "description": "Product description",
  "short_description": "Brief summary",
  "price": "99.99",
  "sale_price": "79.99",
  "cost_price": "50.00",
  "currency": "EUR",
  "status": "draft",
  "stock": 100,
  "ean": "1234567890123",
  "brand_id": 1,
  "supplier_id": 1,
  "category_ids": [1, 2],
  "publishing_channels": ["web", "marketplace"],
  "product_type": "simple"
}

Required fields: name, sku

Returns 201 Created with the full product object.

Update Product (Partial)

Section titled “Update Product (Partial)”
PATCH /api/products/{id}

Send only the fields you want to update:

{
  "price": "89.99",
  "description": "Updated description"
}

Returns 200 OK with the updated product.

Delete Product (Soft)

Section titled “Delete Product (Soft)”
DELETE /api/products/{id}

Sets the product status to archived. Returns 200 OK.

Barcode Lookup

Section titled “Barcode Lookup”
GET /api/products/barcode/{barcode}

Look up a product by EAN barcode. Returns the product with warehouse stock levels.

Section titled “AI Image Search”
POST /api/products/image-search

Upload an image file to find matching products. Send as multipart/form-data with field name image.

Accepted formats: JPEG, PNG, WebP, GIF

Upload Product Media

Section titled “Upload Product Media”
POST /api/products/{id}/media

Attach media to a product via URL.

{
  "file_url": "https://example.com/image.jpg",
  "alt_text": "Product image description",
  "position": 0
}

Returns 201 Created with the media details.

Variants

Section titled “Variants”

List Product Variants

Section titled “List Product Variants”
GET /api/products/{id}/variants

Example Response:

{
  "status": 1,
  "data": {
    "product_id": 1,
    "product_name": "T-Shirt",
    "variants": [
      {
        "id": 10,
        "sku": "TSHIRT-RED-M",
        "name": "T-Shirt - Red, Medium",
        "price": "29.9900",
        "sale_price": null,
        "cost": "15.0000",
        "stock_quantity": 50,
        "stock_status": "in_stock",
        "weight": "0.2500",
        "is_enabled": true,
        "position": 0,
        "image": "https://cdn.example.com/variant.webp",
        "attributes": [
          {"attribute_name": "Color", "value": "Red"},
          {"attribute_name": "Size", "value": "M"}
        ]
      }
    ],
    "total": 1
  },
  "error": null
}

Get Variant Details

Section titled “Get Variant Details”
GET /api/products/{id}/variants/{variantId}

Returns a single variant object as shown above.

Channels

Section titled “Channels”

List Active Channels

Section titled “List Active Channels”
GET /api/channels

Returns the publishing channels configured for the authenticated user’s organization.

Example Response:

{
  "status": 1,
  "data": {
    "channels": [
      {
        "value": "web",
        "label": "Web Store",
        "description": "Products visible on web storefront"
      },
      {
        "value": "marketplace",
        "label": "Marketplace",
        "description": "Products published to external marketplaces"
      }
    ],
    "total": 2
  },
  "error": null
}

If no channels are configured, defaults to web and mobile.

Categories

Section titled “Categories”

List Categories

Section titled “List Categories”
GET /api/categories

Query Parameters:

ParameterTypeDescription
parent_idintegerFilter by parent category ID

Get Category Tree

Section titled “Get Category Tree”
GET /api/categories/tree

Returns the full category hierarchy as a nested tree.

Create Category

Section titled “Create Category”
POST /api/categories
{
  "name": "Electronics",
  "description": "Electronic products",
  "parent_id": null
}

Required fields: name

Update Category

Section titled “Update Category”
PUT /api/categories/{id}

Delete Category

Section titled “Delete Category”
DELETE /api/categories/{id}

Category Children

Section titled “Category Children”
GET /api/categories/{id}/children

Returns direct child categories.

Category Products

Section titled “Category Products”
GET /api/categories/{id}/products

Returns products assigned to a category.

Assign Products to Category

Section titled “Assign Products to Category”
POST /api/categories/{id}/products
{
  "product_ids": [1, 2, 3]
}

Move Category

Section titled “Move Category”
POST /api/categories/{id}/move
{
  "parent_id": 5,
  "position": 0
}

Product Attributes

Section titled “Product Attributes”

List Attributes

Section titled “List Attributes”
GET /api/product-attributes

Get Attribute Details

Section titled “Get Attribute Details”
GET /api/product-attributes/{id}

Create Attribute

Section titled “Create Attribute”
POST /api/product-attributes

Update Attribute

Section titled “Update Attribute”
PUT|PATCH /api/product-attributes/{id}

Delete Attribute

Section titled “Delete Attribute”
DELETE /api/product-attributes/{id}

HTTP Status Codes

Section titled “HTTP Status Codes”
CodeDescription
200Success
201Created (new resource)
400Bad request (validation error)
401Unauthorized (missing or invalid API key)
403Forbidden (no organization access)
404Resource not found
429Rate limit exceeded
500Server error