Store
Products
Manage your product and category catalog. Products can have inventory control, compare-at prices, taxes and custom metadata.
List categories
/v1/product-categories
Optional parameters: is_active, parent_id (UUID or "root"), limit, page
Create category
/v1/product-categories
{
"name": "Electrónicos",
"description": "Productos electrónicos y gadgets",
"parent_id": null,
"sort_order": 1,
"is_active": true
}
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Category name |
parent_id | uuid | No | Parent category (for subcategories) |
description | string | No | Description |
sort_order | integer | No | Display order |
is_active | boolean | No | Whether it is active (default: true) |
Get / Update / Delete category
/v1/product-categories/{'{id}'}
/v1/product-categories/{'{id}'}
/v1/product-categories/{'{id}'}
When a category is deleted, its subcategories move to the parent and its products are unlinked.
List products
/v1/products
Optional parameters: status (active, draft, archived), category (UUID), search, featured, in_stock, limit, page
Create product
/v1/products
{
"name": "Laptop Pro 15",
"price": 25999.00,
"currency": "MXN",
"sku": "LAP-PRO-15",
"description": "Laptop profesional de 15 pulgadas",
"product_category_id": "uuid-de-la-categoria",
"track_stock": true,
"stock_quantity": 50,
"tax_rate": 16,
"is_featured": true,
"metadata": {
"brand": "TechCorp",
"warranty_months": 24
}
}
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Product name |
price | number | Yes | Price in decimals (100.00 = $100) |
currency | string | No | ISO 4217 currency (defaults to the account currency) |
status | string | No | active, draft, archived (default: active) |
product_category_id | uuid | No | Category UUID |
sku | string | No | SKU code |
description | string | No | Long description |
compare_at_price | number | No | Compare-at price (before) |
cost_price | number | No | Product cost |
track_stock | boolean | No | Enable inventory control |
stock_quantity | integer | No | Quantity in stock |
tax_rate | number | No | Tax rate (%) |
is_featured | boolean | No | Featured product |
image_url | url | No | Image URL |
metadata | object | No | Custom metadata |
Get / Update / Delete product
/v1/products/{'{id}'}
/v1/products/{'{id}'}
/v1/products/{'{id}'}
A product with pending orders cannot be deleted.
Sync prices and stock by SKU
/v1/products/sync
For an ERP or inventory system: send in bulk (up to 5000 rows) the sku and only the fields that changed. price and compare_at_price are before tax (Recaudo adds tax with tax_rate); stock turns on stock tracking; status can be active, draft or archived.
{
"items": [
{ "sku": "A-100", "price": 250.00, "stock": 12 },
{ "sku": "B-200", "price": 99.90, "compare_at_price": 129.00 },
{ "sku": "C-300", "status": "archived" }
]
}
{
"object": "product_sync",
"received": 3, "updated": 2, "unchanged": 1,
"not_found": [],
"invalid": []
}
The response says how many changed (updated), how many were already the same (unchanged), the SKUs that do not exist in the store (not_found, they are not created) and rows with invalid data (invalid, with the error); an invalid row does not stop the others. If a SKU is repeated, the last row wins. POST /v1/products/sync-stock still works to send stock only.
Options and extras
/v1/product-modifier-groups
/v1/product-modifier-groups
/v1/product-modifier-groups/{'{id}'}
/v1/product-modifier-groups/{'{id}'}
Option groups shared between products: sizes, extras or removed ingredients. Each option price includes taxes and is added to the product public price. With selection single one is chosen; with multiple, several up to max_selections. With is_required the group is mandatory.
{
"name": "Extras",
"selection": "multiple",
"max_selections": 3,
"is_required": false,
"options": [
{ "name": "Queso extra", "price": 15.00 },
{ "name": "Sin cebolla", "price": 0 }
],
"product_ids": ["uuid-del-producto"]
}
On update, options replaces the whole list. Send the id of the options you keep.
Link them to products with product_ids here, or with modifier_group_ids when creating or updating a product. Products return their modifier_groups.
When creating an order each item accepts modifiers (option ids) and note (short text). The server validates the options and computes the price; the order keeps a copy in the item metadata, so changing the menu does not alter past sales.