> ## 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.

# Import Products from CSV

Bulk-creates products or services from a CSV file. One product is created per data row. Processing is **partial**: valid rows are created even if other rows fail, and every failed row is reported individually with its row number and reason — no row is ever created silently with an invalid SAT key.

## 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

**Content-Type:** `multipart/form-data`

| Field  | Type          | Required | Description                                                                                                 |
| ------ | ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `file` | file (`.csv`) | Yes      | CSV file, max **5MB**. Must have a `.csv` extension or a `text/csv` / `application/vnd.ms-excel` MIME type. |

### CSV Columns

The header row is required. Column names match the JSON [Create Product](/api-reference/products/create) field names.

| Column        | Required | Default      | Description                                                                                         |
| ------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `description` | Yes      | —            | Product or service description                                                                      |
| `productKey`  | Yes      | —            | SAT product/service key. Must exist in the SAT `c_ClaveProdServ` catalog.                           |
| `price`       | Yes      | —            | Unit price (positive number)                                                                        |
| `unitKey`     | No       | `"H87"`      | SAT unit of measure key. Must exist in the SAT `c_ClaveUnidad` catalog.                             |
| `unitName`    | No       | `"Elemento"` | Unit of measure name                                                                                |
| `sku`         | No       | —            | Internal product SKU. Must be unique within the organization and within the file.                   |
| `taxIncluded` | No       | `false`      | Whether taxes are already included in the price. Accepts `true`/`false`, `1`/`0`, `si`/`no`, `yes`. |
| `taxability`  | No       | `"01"`       | SAT taxability code (objeto de impuesto)                                                            |
| `livemode`    | No       | `true`       | Whether this is a live mode product. Same accepted boolean values as `taxIncluded`.                 |

Row 1 is always treated as the header. Data rows are numbered starting at row 2.

## Example Request

```bash theme={null}
curl -X POST https://api.timbrix.mx/organizations/550e8400-e29b-41d4-a716-446655440000/products/import \
  -H "Authorization: Bearer <your_token>" \
  -F "file=@products.csv"
```

```typescript TypeScript SDK theme={null}
const result = await timbrix.products.importCsv(
  "550e8400-e29b-41d4-a716-446655440000",
  file
)
console.log(result.successCount, result.errorCount)
```

Example `products.csv`:

```csv theme={null}
description,productKey,price,unitKey,unitName,sku,taxIncluded,taxability,livemode
Ukelele,60131324,345.60,H87,Elemento,UKL-001,true,01,true
Guitarra acústica,60131327,2500.00,H87,Elemento,GTR-001,true,01,true
Producto inválido,99999999,100.00,,,BAD-001,,,
```

## Example Response

```json theme={null}
{
  "totalRows": 3,
  "successCount": 2,
  "errorCount": 1,
  "errors": [
    {
      "row": 4,
      "message": "La clave de producto o servicio \"99999999\" no existe en el catálogo SAT (c_ClaveProdServ)"
    }
  ]
}
```

| Field              | Type    | Description                                                   |
| ------------------ | ------- | ------------------------------------------------------------- |
| `totalRows`        | integer | Total data rows processed (excluding the header)              |
| `successCount`     | integer | Number of products created successfully                       |
| `errorCount`       | integer | Number of rows that failed and did not create a product       |
| `errors`           | array   | Per-row error detail                                          |
| `errors[].row`     | integer | 1-based row number as it appears in the file (header = row 1) |
| `errors[].message` | string  | Reason the row could not be imported                          |

## Common Errors

Row-level failures (invalid SAT keys, missing required columns in a row, duplicate SKU) do **not** fail the request — they are reported in the `errors` array of a `200 OK` response. The errors below abort the whole import instead.

### 400 Bad Request

No file was uploaded, the file is not a `.csv`, the file exceeds 5MB, the CSV is empty, or the header row is missing a required column (`description`, `productKey`, or `price`).

```json theme={null}
{
  "statusCode": 400,
  "message": "El CSV debe incluir las columnas requeridas: description, productKey, price"
}
```