Skip to main content
POST
Create a product or service
Creates a new product or service in the organization’s catalog for CFDI invoicing.
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 Body

Tax Object

Example Request

Example Response

Common Errors

400 Bad Request

Missing required fields, invalid values, or a missing X-Organization-Id header on a session-authenticated request. Also returned when taxability and taxes don’t agree (e.g. "01" with IVA), or when taxIncluded is true with a transferred tax other than IVA at a rate:

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.

409 Conflict

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

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

application/json
description
string
required

Product or service description

Example:

"Ukelele"

productKey
number
required

SAT product/service key (clave de producto o servicio)

Example:

60131324

price
number
required

Unit price

Example:

345.6

taxIncluded
boolean
default:false

Whether taxes are already included in the price

Example:

true

taxability
string

SAT taxability code (objeto de impuesto). If omitted, it is derived: "02" when taxes is not empty, "01" otherwise. Must agree with taxes: "02" requires at least one tax; "01", "03" and "04" must have none.

Example:

"02"

taxes
object[]

Applicable taxes

localTaxes
object[]

Applicable local taxes

unitKey
string
default:H87

SAT unit of measure key (clave de unidad)

Example:

"H87"

unitName
string
default:Elemento

Unit of measure name

Example:

"Elemento"

sku
string

Internal SKU or identifier

Example:

"UKL-001"

livemode
boolean
default:true

Whether this is a live mode product

Example:

true

Response

id
string
required
Example:

"590ce6c56d04f840aa8438af"

organizationId
string
required
Example:

"org-uuid"

livemode
boolean
required
Example:

false

description
string
required
Example:

"Ukelele"

productKey
number
required
Example:

60131324

price
number
required
Example:

345.6

taxIncluded
boolean
required
Example:

true

taxability
string
required
Example:

"01"

taxes
object[]
required
localTaxes
object[]
required
unitKey
string
required
Example:

"H87"

unitName
string
required
Example:

"Elemento"

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
sku
object
Example:

"UKL-001"