Skip to main content

​
Overview

The Products API allows you to manage your product catalog, including physical products, services, pricing, stock tracking, and tax configuration.

​
Product Object

​
id
integer
Unique identifier for the product
​
name
string
Product name
​
sku
string
Stock Keeping Unit (unique identifier)
​
description
string
Product description
​
product_type
enum
Product type: physical, service, digital
​
price
decimal
Sale price
​
cost
decimal
Cost price (for profit margin calculations)
​
track_stock
boolean
Whether to track inventory for this product
​
is_active
boolean
Whether the product is active and available for sale
​
default_tax_id
integer
Default tax to apply when adding to documents
​
profit
decimal
Calculated profit (price - cost)
​
profit_margin
decimal
Calculated profit margin percentage
​
created_at
timestamp
Creation timestamp
​
updated_at
timestamp
Last update timestamp

​
List Products

Retrieve a paginated list of products.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
per_page
integer
default:"15"
Number of items per page
​
filter[is_active]
boolean
Filter by active status
​
filter[track_stock]
boolean
Filter products that track stock
​
filter[product_type]
string
Filter by product type: physical, service, digital
​
search
string
Search by name, SKU, or description
​
sort
string
default:"name"
Sort field: name, sku, price, -created_at

​
Response

{
  "data": [
    {
      "id": 78,
      "name": "Premium Product",
      "sku": "PROD-001",
      "description": "High quality premium product",
      "product_type": "physical",
      "price": "125.00",
      "cost": "80.00",
      "track_stock": true,
      "is_active": true,
      "default_tax_id": 1,
      "profit": "45.00",
      "profit_margin": "56.25",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-03-10T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 8,
    "per_page": 15,
    "total": 115
  }
}

​
Example

curl -X GET "https://acme.yourdomain.com/api/v1/products?filter[is_active]=true&search=premium" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
By default, only active products are returned. Products are scoped globally (not per workspace), but stock levels are workspace-specific.

​
Get Product

Retrieve a specific product by ID, including stock information.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

{
  "data": {
    "id": 78,
    "name": "Premium Product",
    "sku": "PROD-001",
    "description": "High quality premium product",
    "product_type": "physical",
    "price": "125.00",
    "cost": "80.00",
    "track_stock": true,
    "is_active": true,
    "default_tax_id": 1,
    "profit": "45.00",
    "profit_margin": "56.25",
    "default_tax": {
      "id": 1,
      "name": "ITBIS",
      "rate": "18.00"
    },
    "stock_in_current_workspace": {
      "workspace_id": 2,
      "quantity": "150.00",
      "minimum_quantity": "20.00"
    },
    "workspace_stocks": [
      {
        "workspace_id": 1,
        "workspace_name": "Main Store",
        "quantity": "100.00",
        "minimum_quantity": "20.00"
      },
      {
        "workspace_id": 2,
        "workspace_name": "Warehouse",
        "quantity": "150.00",
        "minimum_quantity": "50.00"
      }
    ],
    "stock_movements": [
      {
        "id": 450,
        "type": "sale",
        "quantity": "-10.00",
        "from_workspace_id": 2,
        "created_at": "2024-03-20T10:30:00Z",
        "created_by": {
          "id": 5,
          "name": "John Doe"
        }
      }
    ]
  }
}

​
Example

curl -X GET https://acme.yourdomain.com/api/v1/products/78 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

​
Create Product

Create a new product.

​
Request Body

​
name
string
required
Product name
​
sku
string
required
Unique SKU identifier
​
description
string
Product description
​
product_type
enum
default:"physical"
Product type: physical, service, digital
​
price
decimal
required
Sale price
​
cost
decimal
Cost price
​
track_stock
boolean
default:"false"
Enable inventory tracking
​
is_active
boolean
default:"true"
Product active status
​
default_tax_id
integer
Default tax ID
​
workspace_stocks
array
Initial stock quantities per workspace (only if track_stock is true)
​
workspace_stocks[].workspace_id
integer
Workspace ID
​
workspace_stocks[].current_quantity
decimal
Initial stock quantity
​
workspace_stocks[].minimum_quantity
decimal
Minimum stock alert threshold

​
Response

{
  "data": {
    "id": 120,
    "name": "New Product",
    "sku": "PROD-120",
    "price": "99.99",
    "cost": "60.00",
    "track_stock": true,
    "is_active": true,
    "created_at": "2024-03-20T15:00:00Z"
  },
  "message": "Producto creado correctamente."
}

​
Example

curl -X POST https://acme.yourdomain.com/api/v1/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Product",
    "sku": "PROD-120",
    "description": "A great new product",
    "product_type": "physical",
    "price": 99.99,
    "cost": 60.00,
    "track_stock": true,
    "default_tax_id": 1,
    "workspace_stocks": [
      {
        "workspace_id": 2,
        "current_quantity": 100,
        "minimum_quantity": 10
      }
    ]
  }'
Users can only set initial stock for workspaces they have access to. Users with the view_all_locations permission can set stock for all workspaces.

​
Update Product

Update an existing product.

​
Path Parameters

​
id
integer
required
Product ID

​
Request Body

Same as Create Product. All fields are optional.
Changing track_stock from true to false will delete all stock records. This action cannot be undone.

​
Response

{
  "data": {
    "id": 120,
    "price": "109.99",
    "updated_at": "2024-03-20T16:00:00Z"
  },
  "message": "Producto actualizado correctamente."
}

​
Delete Product

Delete (soft delete) a product.
Products that have been used in invoices or quotations cannot be deleted. They can only be deactivated.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

{
  "message": "Producto eliminado correctamente."
}

​
Activate Product

Activate a deactivated product.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

{
  "message": "Product activated successfully."
}

​
Deactivate Product

Deactivate an active product. Deactivated products cannot be added to new documents.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

{
  "message": "Product deactivated successfully."
}

​
Quick Create Product

Quickly create a basic product with minimal information (useful for point-of-sale scenarios).

​
Request Body

​
name
string
required
Product name
​
price
decimal
required
Sale price

​
Response

{
  "data": {
    "id": 121,
    "name": "Quick Product",
    "sku": "AUTO-121",
    "price": "49.99",
    "track_stock": false,
    "is_active": true
  }
}
Quick create automatically generates a SKU and sets sensible defaults. The product is created without inventory tracking.

​
Search Products

Products can be searched using the list endpoint with the search parameter, which searches across:
  • Product name
  • SKU
  • Description

​
Example

curl -X GET "https://acme.yourdomain.com/api/v1/products?search=laptop" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Product Import

Bulk import products from CSV or Excel files.

​
Create Import

Upload a file for import.

​
Process Import

Process the uploaded file and create products.

​
Download Template

Download a CSV template for bulk product imports.

Inventory

Manage product stock levels

Invoices

Use products in invoices

Taxes

Configure product taxes

Build docs developers (and LLMs) love

Get started for freeTalk to us