Skip to main content

​
Product Data Model

Before managing products via the API, it is essential to understand how entities relate to each other and in what order they must be created.

​
Entity Hierarchy

​
Required Creation Order

  1. Get catalog — GET /v1/catalogs → your catalog_id
  2. Create product — POST /v1/products with catalog_id
  3. Create options — POST /v1/products/{id}/options → save the value IDs
  4. Create variants — POST /v1/products/{id}/variants with option_values
  5. Add media — POST /v1/products/{product_id}/variants/{variant_id}/media
  6. Assign categories — POST /v1/products/{id}/categories with tag_ids
Categories (POST /v1/categories) are global and can be created at any time — they don’t depend on the product.

​
Key Rules

Catalogs are read-only. They are created automatically when the merchant is registered. The API only allows querying them with GET /v1/catalogs.
Options MUST exist before creating variants. The option_values field is required and needs at least 1 ID. If you send option_values: [] or omit the field, you will receive a 422 error.
Categories are global. Creating a category does not associate it with any product. You must explicitly assign it with POST /v1/products/{product_id}/categories using tag_ids (array of IDs).
Images belong to variants, not to products. Each variant can have its own images.

​
Why are options required before variants?

Internally, each product needs at least one option with values to function correctly in the catalog. This applies even for simple products that have no real variations (no size, color, etc.).Product with variations (e.g. “Polo Negro”):
  • Option: “Talla” → Values: “S”, “M”, “L”
  • 3 variants, one per size
Simple product (e.g. “Dona Glaseada”):
  • Option: “Presentación” → Value: “Estándar”
  • 1 variant with that value
The option name is free-form. Examples: "Talla", "Color", "Presentación".

​
Statuses

​
Action Guides

Categories and Catalogs

Query catalogs and manage categories.

Manage Products

Full CRUD for products, variants, options, and media.