> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbrix.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Product

Creates a new product or service in the organization's catalog for CFDI invoicing.

## Authentication

Requires a valid Bearer token. The authenticated user must be an **owner** or **admin** of the organization.

## Path Parameters

| Parameter        | Type          | Required | Description     |
| ---------------- | ------------- | -------- | --------------- |
| `organizationId` | string (UUID) | Yes      | Organization ID |

## Request Body

| Field         | Type    | Required | Default      | Description                                            |
| ------------- | ------- | -------- | ------------ | ------------------------------------------------------ |
| `description` | string  | Yes      | —            | Product or service description                         |
| `productKey`  | integer | Yes      | —            | SAT product/service key (clave de producto o servicio) |
| `price`       | number  | Yes      | —            | Unit price                                             |
| `taxIncluded` | boolean | No       | `false`      | Whether taxes are already included in the price        |
| `taxability`  | string  | No       | `"01"`       | SAT taxability code (objeto de impuesto)               |
| `taxes`       | array   | No       | `[]`         | List of applicable taxes                               |
| `localTaxes`  | array   | No       | `[]`         | List of applicable local taxes                         |
| `unitKey`     | string  | No       | `"H87"`      | SAT unit of measure key (clave de unidad)              |
| `unitName`    | string  | No       | `"Elemento"` | Unit of measure name                                   |
| `sku`         | string  | No       | —            | Internal product SKU or identifier                     |
| `livemode`    | boolean | No       | `true`       | Whether this is a live mode product                    |

### Tax Object

| Field         | Type    | Required | Description                         |
| ------------- | ------- | -------- | ----------------------------------- |
| `type`        | string  | Yes      | Tax type (e.g. `"IVA"`, `"IEPS"`)   |
| `rate`        | number  | Yes      | Tax rate as a decimal (e.g. `0.16`) |
| `withholding` | boolean | No       | Whether it's a withholding tax      |
| `factor`      | string  | No       | Factor type (e.g. `"Tasa"`)         |

## Example Request

```bash theme={null}
curl -X POST http://localhost:3001/api/organizations/550e8400-e29b-41d4-a716-446655440000/products \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ukelele",
    "productKey": 60131324,
    "price": 345.6,
    "taxIncluded": true,
    "taxability": "01",
    "taxes": [{ "type": "IVA", "rate": 0.16 }],
    "localTaxes": [],
    "unitKey": "H87",
    "unitName": "Elemento",
    "sku": "UKL-001"
  }'
```

## Example Response

```json theme={null}
{
  "id": "590ce6c56d04f840aa8438af",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "livemode": true,
  "description": "Ukelele",
  "productKey": 60131324,
  "price": 345.6,
  "taxIncluded": true,
  "taxability": "01",
  "taxes": [{ "type": "IVA", "rate": 0.16 }],
  "localTaxes": [],
  "unitKey": "H87",
  "unitName": "Elemento",
  "sku": "UKL-001",
  "createdAt": "2025-01-26T10:00:00Z",
  "updatedAt": "2025-01-26T10:00:00Z"
}
```

## Common Errors

### 400 Bad Request

Missing required fields or invalid values.

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "productKey must be a positive integer",
    "price must be a positive number"
  ]
}
```

### 409 Conflict

A product with the same SKU already exists in this organization.

```json theme={null}
{
  "statusCode": 409,
  "message": "A product with SKU \"UKL-001\" already exists in this organization"
}
```