Skip to main content
POST
Bulk import products/services from a CSV file
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.
This endpoint takes no organizationId in the URL. Authenticate with either a Supabase Bearer session (send the X-Organization-Id: <org-id> header — the user must be a member of that organization) or an API key (the organization resolves automatically from the key; any X-Organization-Id header sent alongside an API key is ignored).

Authentication

Accepts either:
  • A Supabase Bearer session (Authorization: Bearer <token>) with the X-Organization-Id: <org-id> header — the authenticated user must be a member of that organization.
  • An API key (X-API-Key: sk_...) with the write:products scope — the organization is resolved from the key itself.

Request

Content-Type: multipart/form-data

CSV Columns

The header row is required. Column names match the JSON Create Product field names. Row 1 is always treated as the header. Data rows are numbered starting at row 2.

Example Request

TypeScript SDK
With an API key, omit the X-Organization-Id header (and the SDK’s organizationId argument) entirely — it’s resolved from the key:
TypeScript SDK (API key)
Example products.csv:

Example Response

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, the header row is missing a required column (description, productKey, or price), or the X-Organization-Id header is missing on a session-authenticated request.

401 Unauthorized

Missing or invalid Bearer token / API key.

403 Forbidden

The authenticated user is not a member of the organization sent in X-Organization-Id, or the API key does not have the write:products scope.

Authorizations

X-API-Key
string
header
required

API Key for authentication (format: sk_...)

Headers

X-Organization-Id
string

Required for Supabase session auth. Ignored when authenticating with an API key (the organization resolves from the key).

Body

multipart/form-data
file
file

Response

Import summary with per-row success/error detail

totalRows
number
required

Total de filas de datos procesadas (sin contar el encabezado)

Example:

50

successCount
number
required

Número de productos creados exitosamente

Example:

47

errorCount
number
required

Número de filas que fallaron y no generaron un producto

Example:

3

errors
object[]
required

Detalle de errores por fila