Products

Create and manage products for your business. Products represent the goods or services you sell and are referenced as line items when creating invoices. Each product has a tax category that determines how VAT is applied.

Endpoints

Method	Endpoint	Description
POST	`/v1/products`	Create a new product
GET	`/v1/products`	List products (paginated, filterable)
GET	`/v1/products/{id}`	Get product details
PATCH	`/v1/products/{id}`	Update a product
DELETE	`/v1/products/{id}`	Delete a product (soft delete)

🔑
All endpoints on this page require authentication. See Authentication for details.

Tax Categories

Every product must have a tax category. This determines the VAT rate applied when the product appears on an invoice.

Category	Description
`STANDARD`	Standard VAT rate (7.5% in Nigeria)
`ZERO_RATED`	Taxable at 0% — applies to exports, basic food items, and other zero-rated supplies
`EXEMPT`	Not subject to VAT — applies to medical services, educational materials, etc.
`REDUCED`	Reduced VAT rate for specific goods or services
`CUSTOM`	Custom tax rate — set any percentage using the `taxPercent` field

When using CUSTOM, you must provide a taxPercent value. For all other categories, the tax rate is determined automatically based on FIRS rules.

Create a Product

Add a new product to your business.

curl -X POST https://e-invoicing.earnipay.com/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "name": "Cloud Hosting - Standard Plan",
    "description": "Monthly cloud hosting with 50GB storage and 2TB bandwidth",
    "unitPrice": 75000,
    "taxCategory": "STANDARD",
    "unit": "month"
  }'

Parameter	Type	Required	Description
`businessId`	string	Yes	ID of the business this product belongs to
`name`	string	Yes	Product name
`description`	string	No	Product description
`unitPrice`	number	Yes	Price per unit (in NGN)
`taxCategory`	string	Yes	One of: `STANDARD`, `ZERO_RATED`, `EXEMPT`, `REDUCED`, `CUSTOM`
`taxPercent`	number	No	Custom tax percentage (required when `taxCategory` is `CUSTOM`)
`unit`	string	No	Unit of measurement (e.g., `month`, `piece`, `hour`, `kg`)

{
  "statusCode": 201,
  "message": "Product created successfully.",
  "data": {
    "id": "prod_abc123",
    "businessId": "biz_xyz789",
    "name": "Cloud Hosting - Standard Plan",
    "description": "Monthly cloud hosting with 50GB storage and 2TB bandwidth",
    "unitPrice": 75000,
    "taxCategory": "STANDARD",
    "taxPercent": 7.5,
    "unit": "month",
    "createdAt": "2026-03-13T12:00:00.000Z",
    "updatedAt": "2026-03-13T12:00:00.000Z"
  }
}

Creating a product with a custom tax rate

Set taxCategory to CUSTOM and provide the taxPercent value:

curl -X POST https://e-invoicing.earnipay.com/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "name": "Consulting Services",
    "description": "Hourly technology consulting",
    "unitPrice": 150000,
    "taxCategory": "CUSTOM",
    "taxPercent": 5,
    "unit": "hour"
  }'

{
  "statusCode": 201,
  "message": "Product created successfully.",
  "data": {
    "id": "prod_def456",
    "businessId": "biz_xyz789",
    "name": "Consulting Services",
    "description": "Hourly technology consulting",
    "unitPrice": 150000,
    "taxCategory": "CUSTOM",
    "taxPercent": 5,
    "unit": "hour",
    "createdAt": "2026-03-13T12:15:00.000Z",
    "updatedAt": "2026-03-13T12:15:00.000Z"
  }
}

List Products

Retrieve a paginated list of products for your business. Filter by tax category, search by name, and sort results.

curl "https://e-invoicing.earnipay.com/v1/products?businessId=biz_xyz789&page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Required	Description
`businessId`	string	Yes	Filter by business ID
`page`	integer	No	Page number (default: `1`)
`limit`	integer	No	Items per page (default: `10`)
`search`	string	No	Search by product name
`taxCategory`	string	No	Filter by tax category (e.g., `STANDARD`, `ZERO_RATED`)
`sortBy`	string	No	Field to sort by (e.g., `name`, `unitPrice`, `createdAt`)
`sortOrder`	string	No	`asc` or `desc` (default: `desc`)

{
  "statusCode": 200,
  "message": "Products retrieved successfully.",
  "data": {
    "items": [
      {
        "id": "prod_abc123",
        "businessId": "biz_xyz789",
        "name": "Cloud Hosting - Standard Plan",
        "description": "Monthly cloud hosting with 50GB storage and 2TB bandwidth",
        "unitPrice": 75000,
        "taxCategory": "STANDARD",
        "taxPercent": 7.5,
        "unit": "month",
        "createdAt": "2026-03-13T12:00:00.000Z"
      },
      {
        "id": "prod_def456",
        "businessId": "biz_xyz789",
        "name": "Consulting Services",
        "description": "Hourly technology consulting",
        "unitPrice": 150000,
        "taxCategory": "CUSTOM",
        "taxPercent": 5,
        "unit": "hour",
        "createdAt": "2026-03-13T12:15:00.000Z"
      }
    ],
    "meta": {
      "totalItems": 2,
      "itemCount": 2,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

Filtering by tax category

Retrieve only products with a specific tax category:

curl "https://e-invoicing.earnipay.com/v1/products?businessId=biz_xyz789&taxCategory=ZERO_RATED" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

This is useful when building invoices that require specific tax treatment, such as export invoices (zero-rated) or medical supply invoices (exempt).

Get Product Details

Retrieve the full details of a specific product.

curl https://e-invoicing.earnipay.com/v1/products/prod_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Product retrieved successfully.",
  "data": {
    "id": "prod_abc123",
    "businessId": "biz_xyz789",
    "name": "Cloud Hosting - Standard Plan",
    "description": "Monthly cloud hosting with 50GB storage and 2TB bandwidth",
    "unitPrice": 75000,
    "taxCategory": "STANDARD",
    "taxPercent": 7.5,
    "unit": "month",
    "createdAt": "2026-03-13T12:00:00.000Z",
    "updatedAt": "2026-03-13T12:00:00.000Z"
  }
}

Update a Product

Update one or more product fields. Send only the fields you want to change.

curl -X PATCH https://e-invoicing.earnipay.com/v1/products/prod_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "unitPrice": 85000,
    "description": "Monthly cloud hosting with 100GB storage and 5TB bandwidth"
  }'

{
  "statusCode": 200,
  "message": "Product updated successfully.",
  "data": {
    "id": "prod_abc123",
    "businessId": "biz_xyz789",
    "name": "Cloud Hosting - Standard Plan",
    "description": "Monthly cloud hosting with 100GB storage and 5TB bandwidth",
    "unitPrice": 85000,
    "taxCategory": "STANDARD",
    "taxPercent": 7.5,
    "unit": "month",
    "createdAt": "2026-03-13T12:00:00.000Z",
    "updatedAt": "2026-03-13T16:45:00.000Z"
  }
}

💡
Updating a product does not affect existing invoices. Invoice line items capture the product details at the time of invoice creation. Only new invoices will use the updated values.

Delete a Product

Soft-delete a product. The record is preserved for existing invoices but no longer appears in list queries or can be added to new invoices.

curl -X DELETE https://e-invoicing.earnipay.com/v1/products/prod_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Product deleted successfully."
}

Error Handling

Status Code	Error	Description
`400`	Bad Request	Missing required fields, invalid tax category, or missing `taxPercent` for `CUSTOM` category
`401`	Unauthorized	Missing or expired access token
`403`	Forbidden	You don't have permission for this business
`404`	Not Found	Product ID doesn't exist or was deleted

{
  "statusCode": 400,
  "message": "taxPercent is required when taxCategory is CUSTOM.",
  "error": "Bad Request"
}