Create or upsert a product by external_id

POST

/api/public/v1/products

Code sample: cURL

curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/products' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "external_id": "svc-erp-integration",
  "name": "ERP integration implementation",
  "description": "Implementation and go-live support for ERP e-invoicing",
  "sku": "ZTX-SVC-ERP",
  "item_type": "service",
  "service_category": "Software implementation",
  "default_unit_code": "C62",
  "default_unit_price_naira": 200000,
  "default_tax_category_code": "STANDARD_VAT",
  "default_vat_rate": 0.075,
  "is_active": true
}'

• Production API
• Staging API

Authorizations

• HTTPBearer

Request Body ^required

Media type application/json

ProductCreateInput

ERP-supplied product upsert payload (keyed by external_id).

object

external_id

required

External Id

string

>= 1 characters <= 255 characters

name

required

Name

string

>= 1 characters <= 500 characters

description

Any of:

string

string

null

null

sku

Any of:

string

string

<= 200 characters

null

null

item_type

Item Type

string

default: good

Allowed values: good service

hsn_code

Any of:

string

string

<= 100 characters

null

null

product_category

Any of:

string

string

<= 255 characters

null

null

isic_code

Any of:

string

string

<= 20 characters

null

null

service_category

Any of:

string

string

<= 255 characters

null

null

default_unit_code

Default Unit Code

string

default: C62 <= 10 characters

default_unit_price_naira

Any of:

number

number

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

default_tax_category_code

Default Tax Category Code

string

default: STANDARD_VAT <= 64 characters

default_vat_rate

Any of:

number

number

<= 1

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

is_active

Is Active

boolean

default: true

Examples

Example Service item

Create or update a service catalog item

{
  "external_id": "svc-erp-integration",
  "name": "ERP integration implementation",
  "description": "Implementation and go-live support for ERP e-invoicing",
  "sku": "ZTX-SVC-ERP",
  "item_type": "service",
  "service_category": "Software implementation",
  "default_unit_code": "C62",
  "default_unit_price_naira": 200000,
  "default_tax_category_code": "STANDARD_VAT",
  "default_vat_rate": 0.075,
  "is_active": true
}

Responses

200

Successful Response

Media type application/json

ProductResponse

Stable response shape for public-API product endpoints.

The Product DB model uses default_unit_price (naira-denominated Numeric) and default_tax_rate (percentage stored 0-100, e.g. 7.5). The public-API surface exposes them as default_unit_price_naira and default_vat_rate (0-1 fractional rate) — a model validator rewrites the inbound attributes so ERPs see a consistent shape across all public-API resources.

object

id

required

Id

string format: uuid

external_id

required

Any of:

string

string

null

null

name

required

Name

string

description

Any of:

string

string

null

null

sku

Any of:

string

string

null

null

item_type

required

Item Type

string

Allowed values: good service

hsn_code

Any of:

string

string

null

null

product_category

Any of:

string

string

null

null

isic_code

Any of:

string

string

null

null

service_category

Any of:

string

string

null

null

default_unit_code

required

Default Unit Code

string

default_unit_price_naira

required

Default Unit Price Naira

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

default_tax_category_code

required

Default Tax Category Code

string

default_vat_rate

required

Default Vat Rate

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

is_active

required

Is Active

boolean

Examples

Example Product upserted

Existing product updated

{
  "id": "086c9f4a-c469-4be6-b3c3-4b022b27e9f6",
  "external_id": "svc-erp-integration",
  "name": "ERP integration implementation",
  "description": "Implementation and go-live support for ERP e-invoicing",
  "sku": "ZTX-SVC-ERP",
  "item_type": "service",
  "default_unit_code": "C62",
  "default_unit_price_naira": "200000.00",
  "default_tax_category_code": "STANDARD_VAT",
  "default_vat_rate": "0.075",
  "is_active": true
}

422

Validation Error

Media type application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Examples

Example Sample response

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}