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

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 SDK

const result = await timbrix.products.importCsv(
  "550e8400-e29b-41d4-a716-446655440000",
  file
)
console.log(result.successCount, result.errorCount)

Example products.csv:

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

{
  "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).

{
  "statusCode": 400,
  "message": "El CSV debe incluir las columnas requeridas: description, productKey, price"
}

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

SAT Catalogs

Invoices

Products

Users

Webhooks

API Keys

Import Products from CSV

Authentication

Path Parameters

Request

CSV Columns

Example Request

Example Response

Common Errors

400 Bad Request

​Authentication

​Path Parameters

​Request

​CSV Columns

​Example Request

​Example Response

​Common Errors

​400 Bad Request

Authentication

Path Parameters

Request

CSV Columns

Example Request

Example Response

Common Errors

400 Bad Request