Manage Products

This guide covers all operations to query, create, update, and delete products and their sub-entities.

Important Rules

Before you begin, keep these rules in mind — they apply to all product management:

• Product status: Currently the only supported value is "published". The status is returned as-is in responses.
• option_values is immutable: Once a variant is created, you cannot change its option_values via PATCH. If you need to fix them, delete the variant and create it again.
• Supported currencies: MXN, PEN, COP, CLP, ARS, BRL, VES, BOB, USD, PYG, UYU, CRC, EUR.
• Currency must match the catalog's currency: All variants of a product must use the same currency configured in the catalog. Using a different currency may cause internal inconsistencies.
• Responses: PATCH returns 200 with the updated resource. DELETE returns 204 with no body.
• Every product requires at least one variant: Even simple products (no sizes or colors) need at minimum one option and one variant. Use a generic name like "Presentation" or "Unit".
• No batch endpoints: Each entity must be created individually.

Query Products

List products

Returns a paginated list of products with all their sub-entities.

The response includes pagination:

{
  "data": [ /* array of products */ ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_pages": 4,
    "total_items": 100,
    "has_more": true
  }
}

Get a product

Returns a product with all its options, variants (with media), and categories.

Response example:

{
  "id": 9876,
  "created_at": "2026-01-15T10:00:00Z",
  "name": "Polo Negro",
  "description": "Polo de algodón pima de alta calidad",
  "characteristics": "Material: 100% algodón pima. Peso: 180g/m².",
  "status": "published",
  "categories": [
    { "id": 1, "name": "Ropa" }
  ],
  "options": [
    {
      "id": 10,
      "name": "Talla",
      "values": [
        { "id": 100, "name": "S" },
        { "id": 101, "name": "M" },
        { "id": 102, "name": "L" }
      ]
    }
  ],
  "variants": [
    {
      "id": 500,
      "name": "Polo Negro - Talla M",
      "base_price": 49.90,
      "currency": "PEN",
      "status": "available",
      "media": [
        {
          "id": 1000,
          "title": "Front view",
          "url": "https://cdn.example.com/polo-negro-m-front.jpg"
        }
      ]
    }
  ]
}

Create a Complete Product

1. Create the product

2. Add options

The response includes the IDs of the created values. Save these IDs to use them when creating variants.

3. Create variants

Each variant must include option_values with at least one option value ID.

4. Add media to the variant

5. Assign categories

This endpoint is idempotent: if a tag is already assigned, it is skipped and the response is 200. Only returns 201 when new tags are assigned.

Update Entities

Delete Entities

Simple Product (no variations)

Not all products have sizes or colors. Even so, every product requires at least one option and one variant. Use a generic name for the option.

Common Errors

Validation errors (422) return a body with details about the failing field:

{
  "detail": [
    {
      "loc": ["body", "option_values"],
      "msg": "List should have at least 1 item",
      "type": "too_short"
    }
  ]
}