Products

A CFDI product (CFDI: Mexico's electronic invoice) is a good or service that your company offers its customers. Use this resource to manage your product and service records through the API, with their SAT keys (SAT: Mexico's tax authority, Servicio de Administración Tributaria) and their taxes.

Product model

The product model describes a product or service, with its tax details and taxes. Properties with the Id suffix are keys from the SAT catalogs: look them up in CFDI 4.0 catalogs or query them through the API in SAT catalogs.

Properties

Name
id
Type
string?
Description
The product's unique identifier, assigned by Fiscalapi.
Name
description
Type
string
required
Description
The product's description or name, up to 255 characters.
Name
unitPrice
Type
number | decimal
required
Description
The product's unit price, excluding taxes. It must be greater than 0 and no more than 999999999999.999999 (12 integer digits and 6 decimal places).
Name
satUnitMeasurementId
Type
string
required
expandable
Description
The unit of measure code. SAT catalog c_ClaveUnidad.
Default:
"H87"
Name
satTaxObjectId
Type
string
required
expandable
Description
The code that identifies the product's tax obligations. SAT catalog c_ObjetoImp.
Default:
"02"
Name
satProductCodeId
Type
string
required
expandable
Description
The product or service code. SAT catalog c_ClaveProdServ.
Default:
"01010101"
Name
productTaxes
Type
array of objects (ProductTax)?
Taxes that apply to the product.
Default:
[IVA 16%]
Name
taxId
Type
string
required
expandable
Description
The tax. SAT catalog c_Impuesto.
Type
enum:
Values
"001""002""003"
Name
taxFlagId
Type
string
required
expandable
Description
Whether the tax is transferred or withheld.
Type
enum:
Values
"T""R"
Name
taxTypeId
Type
string
required
expandable
Description
The tax type.
Type
enum:
Values
"Tasa""Cuota""Exento"
Name
rate
Type
decimal | number
required
Description
The tax rate or fixed amount, for example 0.160000 for a 16% rate. It must be 0 or greater and no more than 999999999999.999999; a fixed amount can be greater than 1.

GET/api/v4/products

List products

This endpoint returns products in pages of 10 by default. Use the query parameters to choose the page and its size.

Query parameters

Name
pageNumber
Type
integer | number
required
Description
The page number you want to retrieve.
Default:
1
Name
pageSize
Type
integer | number
required
Description
The number of records per page, from 1 to 50.
Default:
10

Request

GET

/api/v4/products?pageNumber=1&pageSize=2

curl --location 'https://test.fiscalapi.com/api/v4/products?pageNumber=1&pageSize=2' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": {
        "items": [
            {
                "description": "Libro de programacion",
                "unitPrice": 150.75,
                "satUnitMeasurementId": "H87",
                "satUnitMeasurement": {
                    "id": "H87",
                    "description": "Pieza",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "satTaxObjectId": "02",
                "satTaxObject": {
                    "id": "02",
                    "description": "Sí objeto de impuesto.",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "satProductCodeId": "81111602",
                "satProductCode": {
                    "id": "81111602",
                    "description": "Programaci?n para java",
                    "createdAt": "2025-01-07T15:05:58.2766667",
                    "updatedAt": null
                },
                "productTaxes": [
                    {
                        "productId": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
                        "tax": {
                            "id": "002",
                            "description": "IVA: Impuesto al valor agregado",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "rate": 0.16,
                        "taxFlag": {
                            "id": "T",
                            "description": "TRASLADO",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "taxType": {
                            "id": "Tasa",
                            "description": "TASA",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "id": "26372153-e692-4675-9772-acb1df0abc20",
                        "createdAt": "2025-04-19T15:52:15.3623078",
                        "updatedAt": "2025-04-19T15:52:15.3623087"
                    },
                    {
                        "productId": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
                        "tax": {
                            "id": "002",
                            "description": "IVA: Impuesto al valor agregado",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "rate": 0.010667,
                        "taxFlag": {
                            "id": "T",
                            "description": "TRASLADO",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "taxType": {
                            "id": "Tasa",
                            "description": "TASA",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "id": "52400183-30af-447d-9902-39b6089176e7",
                        "createdAt": "2025-04-19T15:52:15.3623100",
                        "updatedAt": "2025-04-19T15:52:15.3623101"
                    }
                ],
                "id": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
                "createdAt": "2025-04-19T15:50:27.3391795",
                "updatedAt": "2025-04-27T19:54:01.5113267"
            },
            {
                "description": "Refresco Coca-Cola 1L",
                "unitPrice": 50,
                "satUnitMeasurementId": "H87",
                "satUnitMeasurement": {
                    "id": "H87",
                    "description": "Pieza",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "satTaxObjectId": "02",
                "satTaxObject": {
                    "id": "02",
                    "description": "Sí objeto de impuesto.",
                    "createdAt": "2024-08-10T15:46:30.3730000",
                    "updatedAt": null
                },
                "satProductCodeId": "50202306",
                "satProductCode": {
                    "id": "50202306",
                    "description": "Refrescos",
                    "createdAt": "2025-01-07T15:05:55.1500000",
                    "updatedAt": null
                },
                "productTaxes": [
                    {
                        "productId": "27808326-1824-4f3c-87fb-03ace1066f16",
                        "tax": {
                            "id": "002",
                            "description": "IVA: Impuesto al valor agregado",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "rate": 0.16,
                        "taxFlag": {
                            "id": "T",
                            "description": "TRASLADO",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "taxType": {
                            "id": "Tasa",
                            "description": "TASA",
                            "createdAt": "2024-08-10T15:46:30.3730000",
                            "updatedAt": null
                        },
                        "id": "3c9aee99-09be-4862-87d0-bad27ab6f7c0",
                        "createdAt": "2025-01-07T15:41:33.2040814",
                        "updatedAt": "2025-01-07T15:41:33.2040818"
                    }
                ],
                "id": "27808326-1824-4f3c-87fb-03ace1066f16",
                "createdAt": "2025-01-07T15:41:33.2040800",
                "updatedAt": "2025-02-04T19:14:01.8199284"
            }
        ],
        "pageNumber": 1,
        "totalPages": 2,
        "totalCount": 4,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/products

Create a product

This endpoint creates a product.

Request body

Name
description
Type
string
required
Description
The product's description or name, up to 255 characters. Fiscalapi rejects it if it's missing, empty, or longer than 255 characters.
Name
unitPrice
Type
number | decimal
required
Description
The product's unit price, excluding taxes. It must be greater than 0 and no more than 999999999999.999999 (12 integer digits and 6 decimal places). Fiscalapi rejects it if it's missing, 0, negative, or above the maximum.
Name
satUnitMeasurementId
Type
string?
Description
The unit of measure code. SAT catalog c_ClaveUnidad. Fiscalapi rejects a value that's empty, null, or not in the catalog.
Default:
"H87"
Name
satTaxObjectId
Type
string?
Description
The code that identifies the product's tax obligations. SAT catalog c_ObjetoImp. Fiscalapi rejects a value that's empty, null, or not in the catalog.
Default:
"02"
Name
satProductCodeId
Type
string?
Description
The product or service code. SAT catalog c_ClaveProdServ. If you send it, Fiscalapi rejects an empty value or a key that isn't in the catalog.
Default:
"01010101"
Name
productTaxes
Type
array of objects (ProductTax)?
Taxes that apply to the product. Each element is an object, not null, and each tax appears only once.
Default:
[IVA 16%]
Name
taxId
Type
string
required
Description
The tax. SAT catalog c_Impuesto. Fiscalapi rejects it if it's missing, empty, or not in the catalog.
Type
enum:
Values
"001""002""003"
Name
taxFlagId
Type
string
required
Description
Whether the tax is transferred or withheld. Fiscalapi rejects it if it's missing, empty, or not one of these values.
Type
enum:
Values
"T""R"
Name
taxTypeId
Type
string
required
Description
The tax type. SAT catalog c_TipoFactor. Fiscalapi rejects it if it's missing, empty, or not in the catalog.
Type
enum:
Values
"Tasa""Cuota""Exento"
Name
rate
Type
decimal | number
required
Description
The tax rate or fixed amount, for example 0.160000 for a 16% rate. It must be 0 or greater and no more than 999999999999.999999; a fixed amount can be greater than 1.

Errors

In the messages, <valor> is the value you sent and <n> is the number of characters in the description. In the ProductTaxes[n] fields, n is the tax's position in the list, starting at 0.

Status	When it happens	Message
400	The description is longer than 255 characters. It arrives as a validation failure on Description.	'Description' debe ser menor o igual que 255 caracteres. Ingresó <n> caracteres.
400	The unit price is above the maximum. It arrives as a validation failure on UnitPrice.	El precio unitario no puede ser mayor a 999999999999.999999.
400	The unit of measure key isn't in the catalog. It arrives as a validation failure on SatUnitMeasurementId. An empty value gets the empty field message.	La clave de unidad '<valor>' no existe en el catálogo c_ClaveUnidad del SAT.
400	The tax object (whether an item is subject to tax, `ObjetoImp`) isn't in the catalog. It arrives as a validation failure on SatTaxObjectId. An empty value gets the empty field message.	El objeto de impuesto '<valor>' no existe en el catálogo c_ObjetoImp del SAT.
400	The product or service key is empty or isn't in the catalog. It arrives as a validation failure on SatProductCodeId.	La clave de producto o servicio '<valor>' no existe en el catálogo c_ClaveProdServ del SAT.
400	An element of the tax list is `null`. It arrives as a validation failure on ProductTaxes[n]. See Null elements in lists.	'Product Taxes' no admite elementos null: cada elemento debe ser un objeto.
400	A tax is repeated: same tax, type, tax flag, and rate. The rate is compared to 6 decimal places, so `0.16` and `0.1600004` count as the same rate. It arrives as a validation failure on ProductTaxes[n] of the second occurrence. The message shows the rate as you sent it, rounded to 6 decimal places; for example, "El impuesto '002' Tasa 0.16 (T) se repite en el producto: cada impuesto va una sola vez."	El impuesto '<taxId>' <taxTypeId> <rate> (<taxFlagId>) se repite en el producto: cada impuesto va una sola vez.
400	The tax isn't in the catalog. It arrives as a validation failure on ProductTaxes[n].TaxId. An empty or missing value gets the empty field message.	El impuesto '<valor>' no existe en el catálogo c_Impuesto del SAT.
400	The tax flag isn't `T` or `R`. It arrives as a validation failure on ProductTaxes[n].TaxFlagId. An empty or missing value gets the empty field message.	La naturaleza del impuesto '<valor>' no es válida: usa T (traslado) o R (retención).
400	The tax type isn't in the c_TipoFactor catalog. It arrives as a validation failure on ProductTaxes[n].TaxTypeId. An empty or missing value gets the empty field message.	El tipo factor '<valor>' no existe en el catálogo c_TipoFactor del SAT.
400	The rate or fixed amount is negative. It arrives as a validation failure on ProductTaxes[n].Rate.	La tasa o cuota debe ser mayor o igual a 0.
400	The rate or fixed amount is above the maximum. It arrives as a validation failure on ProductTaxes[n].Rate.	La tasa o cuota no puede ser mayor a 999999999999.999999.

Request

POST

/api/v4/products

curl --location 'https://test.fiscalapi.com/api/v4/products' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "description": "Consulta Medica",
  "unitPrice": 1250,
}'

Response

{
    "data": {
        "description": "Consulta Medica",
        "unitPrice": 1250,
        "satUnitMeasurementId": "H87",
        "satUnitMeasurement": null,
        "satTaxObjectId": "02",
        "satTaxObject": null,
        "satProductCodeId": "01010101",
        "satProductCode": null,
        "productTaxes": [
            {
                "productId": "b2e8dba2-5986-426b-8c1b-6657c0cecbf7",
                "tax": null,
                "rate": 0.160000,
                "taxFlag": null,
                "taxType": null,
                "id": "c3601359-07a1-490d-a98d-b7cd0ec0956a",
                "createdAt": "2025-01-11T19:09:33.0999529",
                "updatedAt": "2025-01-11T19:09:33.0999671"
            }
        ],
        "id": "b2e8dba2-5986-426b-8c1b-6657c0cecbf7",
        "createdAt": "2025-01-11T19:09:33.0993925",
        "updatedAt": "2025-01-11T19:09:33.0994226"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/products/<id>

Get a product by ID

This endpoint returns a product by its ID.

Errors

In the message, <id> is the ID you sent. The message arrives in the details field of the response model.

Status	When it happens	Message
404	The product doesn't exist in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data).	No such resource for the given Id: <id>

Request

GET

/api/v4/products/<id>

curl --location 'https://test.fiscalapi.com/api/v4/products/2c6aafcf-8cd2-4fb1-94a8-687adc671380' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": {
        "description": "Consulta Medica",
        "unitPrice": 1250,
        "satUnitMeasurementId": "H87",
        "satUnitMeasurement": {
            "id": "H87",
            "description": "Pieza",
            "createdAt": "2024-08-10T15:46:30.3730000",
            "updatedAt": null
        },
        "satTaxObjectId": "02",
        "satTaxObject": {
            "id": "02",
            "description": "Sí objeto de impuesto.",
            "createdAt": "2024-08-10T15:46:30.3730000",
            "updatedAt": null
        },
        "satProductCodeId": "01010101",
        "satProductCode": {
            "id": "01010101",
            "description": "No se encuentra en el catálogo",
            "createdAt": "2025-01-07T15:05:58.2766667",
            "updatedAt": null
        },
        "productTaxes": [
            {
                "productId": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
                "tax": null,
                "rate": 0.16,
                "taxFlag": null,
                "taxType": null,
                "id": "26372153-e692-4675-9772-acb1df0abc20",
                "createdAt": "2025-04-19T15:52:15.3623078",
                "updatedAt": "2025-04-19T15:52:15.3623087"
            },
            {
                "productId": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
                "tax": null,
                "rate": 0.010667,
                "taxFlag": null,
                "taxType": null,
                "id": "52400183-30af-447d-9902-39b6089176e7",
                "createdAt": "2025-04-19T15:52:15.3623100",
                "updatedAt": "2025-04-19T15:52:15.3623101"
            }
        ],
        "id": "2c6aafcf-8cd2-4fb1-94a8-687adc671380",
        "createdAt": "2025-04-19T15:50:27.3391795",
        "updatedAt": "2025-04-27T19:54:01.5113267"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/products/<id>

Update a product

This endpoint updates a product.

Request body

Name
id
Type
string
required
Description
The product's unique identifier, assigned by Fiscalapi.
Name
description
Type
string
required
Description
The product's description or name, up to 255 characters. Fiscalapi rejects it if it's missing, empty, or longer than 255 characters.
Name
unitPrice
Type
number | decimal
required
Description
The product's unit price, excluding taxes. It must be greater than 0 and no more than 999999999999.999999. Fiscalapi rejects it if it's missing, 0, negative, or above the maximum.
Name
satUnitMeasurementId
Type
string
required
Description
The unit of measure code. SAT catalog c_ClaveUnidad. Fiscalapi rejects the request if it's missing, empty, null, or not in the catalog.
Name
satTaxObjectId
Type
string
required
Description
The code that identifies the product's tax obligations. SAT catalog c_ObjetoImp. Fiscalapi rejects the request if it's missing, empty, null, or not in the catalog.
Name
satProductCodeId
Type
string?
Description
The product or service code. SAT catalog c_ClaveProdServ. If you send it, Fiscalapi rejects an empty value or a key that isn't in the catalog. Updates have no default value: send the key the product should have.
Name
productTaxes
Type
array of objects (ProductTax)?
Taxes that apply to the product. Each element is an object, not null, and each tax appears only once. The taxes you send replace the saved ones. If you omit the list or send it empty, Fiscalapi keeps the saved taxes. It also keeps them if it rejects the update.
Name
taxId
Type
string
required
Description
The tax. SAT catalog c_Impuesto. Fiscalapi rejects it if it's missing, empty, or not in the catalog.
Type
enum:
Values
"001""002""003"
Name
taxFlagId
Type
string
required
Description
Whether the tax is transferred or withheld. Fiscalapi rejects it if it's missing, empty, or not one of these values.
Type
enum:
Values
"T""R"
Name
taxTypeId
Type
string
required
Description
The tax type. SAT catalog c_TipoFactor. Fiscalapi rejects it if it's missing, empty, or not in the catalog.
Type
enum:
Values
"Tasa""Cuota""Exento"
Name
rate
Type
decimal | number
required
Description
The tax rate or fixed amount, for example 0.160000 for a 16% rate. It must be 0 or greater and no more than 999999999999.999999; a fixed amount can be greater than 1.

Errors

In the messages, <valor> is the value you sent and <n> is the number of characters in the description. In the ProductTaxes[n] fields, n is the tax's position in the list, starting at 0.

Status	When it happens	Message
400	The description is longer than 255 characters. It arrives as a validation failure on Description.	'Description' debe ser menor o igual que 255 caracteres. Ingresó <n> caracteres.
400	The unit price is above the maximum. It arrives as a validation failure on UnitPrice.	El precio unitario no puede ser mayor a 999999999999.999999.
400	The unit of measure key isn't in the catalog. It arrives as a validation failure on SatUnitMeasurementId. An empty value gets the empty field message.	La clave de unidad '<valor>' no existe en el catálogo c_ClaveUnidad del SAT.
400	The tax object isn't in the catalog. It arrives as a validation failure on SatTaxObjectId. An empty value gets the empty field message.	El objeto de impuesto '<valor>' no existe en el catálogo c_ObjetoImp del SAT.
400	The product or service key is empty or isn't in the catalog. It arrives as a validation failure on SatProductCodeId.	La clave de producto o servicio '<valor>' no existe en el catálogo c_ClaveProdServ del SAT.
400	An element of the tax list is `null`. It arrives as a validation failure on ProductTaxes[n]. See Null elements in lists.	'Product Taxes' no admite elementos null: cada elemento debe ser un objeto.
400	A tax is repeated: same tax, type, tax flag, and rate. The rate is compared to 6 decimal places, so `0.16` and `0.1600004` count as the same rate. It arrives as a validation failure on ProductTaxes[n] of the second occurrence. The message shows the rate as you sent it, rounded to 6 decimal places; for example, "El impuesto '002' Tasa 0.16 (T) se repite en el producto: cada impuesto va una sola vez."	El impuesto '<taxId>' <taxTypeId> <rate> (<taxFlagId>) se repite en el producto: cada impuesto va una sola vez.
400	The tax isn't in the catalog. It arrives as a validation failure on ProductTaxes[n].TaxId. An empty or missing value gets the empty field message.	El impuesto '<valor>' no existe en el catálogo c_Impuesto del SAT.
400	The tax flag isn't `T` or `R`. It arrives as a validation failure on ProductTaxes[n].TaxFlagId. An empty or missing value gets the empty field message.	La naturaleza del impuesto '<valor>' no es válida: usa T (traslado) o R (retención).
400	The tax type isn't in the c_TipoFactor catalog. It arrives as a validation failure on ProductTaxes[n].TaxTypeId. An empty or missing value gets the empty field message.	El tipo factor '<valor>' no existe en el catálogo c_TipoFactor del SAT.
400	The rate or fixed amount is negative. It arrives as a validation failure on ProductTaxes[n].Rate.	La tasa o cuota debe ser mayor o igual a 0.
400	The rate or fixed amount is above the maximum. It arrives as a validation failure on ProductTaxes[n].Rate.	La tasa o cuota no puede ser mayor a 999999999999.999999.

Request

PUT

/api/v4/products/<id>

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/products/<id>' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "id":"<id>",
  "description": "Servicios fiscales",
  "unitPrice": 550,
  "satUnitMeasurementId": "E48",
  "satTaxObjectId": "02",
  "satProductCodeId": "81111500",
    "productTaxes": [
    {
      "taxId": "001",
      "rate": 0.100000,
      "taxFlagId": "R",
      "taxTypeId": "Tasa"
    },
    {
      "taxId": "002",
      "rate": 0.160000,
      "taxFlagId": "T",
      "taxTypeId": "Tasa"
    }
  ]

}'

Response

{
    "data": {
        "description": "Servicios fiscales actualizados",
        "unitPrice": 550,
        "satUnitMeasurementId": "E48",
        "satUnitMeasurement": null,
        "satTaxObjectId": "02",
        "satTaxObject": null,
        "satProductCodeId": "81111500",
        "satProductCode": null,
        "productTaxes": [
            {
                "productId": "5d2dfd35-9e1c-4263-973e-5121aef74087",
                "tax": null,
                "rate": 0.1,
                "taxFlag": null,
                "taxType": null,
                "id": "c28e3de5-bd16-4ab8-9313-f1d1350a1f1e",
                "createdAt": "2025-05-01T08:42:00.5208750",
                "updatedAt": "2025-05-01T08:42:00.5208762"
            },
            {
                "productId": "5d2dfd35-9e1c-4263-973e-5121aef74087",
                "tax": null,
                "rate": 0.16,
                "taxFlag": null,
                "taxType": null,
                "id": "e653d728-f99d-4db9-9bd6-f48a3084217c",
                "createdAt": "2025-05-01T08:42:00.5208775",
                "updatedAt": "2025-05-01T08:42:00.5208775"
            }
        ],
        "id": "5d2dfd35-9e1c-4263-973e-5121aef74087",
        "createdAt": "2025-05-01T08:41:31.8136976",
        "updatedAt": "2025-05-01T08:42:00.5208776"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/products/<id>

Delete a product

This endpoint deletes a product by its ID.

Request

DELETE

/api/v4/products/<id>

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/products/5d2dfd35-9e1c-4263-973e-5121aef74087' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}