Developers

Products

A Product is a product or service a Business sells, with its price and VAT rate. On this page: the fields of a Product, how to page through a Business’s Products and search them, and how to read, create, update and delete one — held to the same rules as the Product form in Essentio.

The Product model

A Product as the API answers it. A field that is null has not been filled in in Essentio. Every amount is an exact decimal string — "119.00", never a number — so nothing is rounded on its way.

Properties

  • Name
    id
    Type
    integer
    Description

    The Product’s identifier.

  • Name
    name
    Type
    string
    Description

    What the Product is called.

  • Name
    code
    Type
    string or null
    Description

    The Business’s own code for it, unique within the Business.

  • Name
    description
    Type
    string or null
    Description

    A longer description.

  • Name
    type
    Type
    string
    Description

    product or service. Another value may be added within v1: keep one you do not know.

  • Name
    price
    Type
    string
    Description

    The price as the Business entered it: with the VAT in it when vat_included is true, without it otherwise.

  • Name
    currency
    Type
    string
    Description

    The currency of the price, as an ISO 4217 code: EUR.

  • Name
    vat_rate
    Type
    string
    Description

    The VAT rate in percent: "19.00".

  • Name
    vat_included
    Type
    boolean
    Description

    Whether price holds the VAT.

  • Name
    price_without_vat
    Type
    string
    Description

    The price before VAT, at the currency’s scale. When vat_included, Essentio divides the VAT out of price for you.

  • Name
    price_with_vat
    Type
    string
    Description

    The price with the VAT, at the currency’s scale.

  • Name
    unit
    Type
    string
    Description

    What one of it is counted in: pcs, hour.

  • Name
    track_inventory
    Type
    boolean
    Description

    Whether the Business counts its stock.

  • Name
    stock_quantity, minimum_stock
    Type
    integer or null
    Description

    The stock held, and the level the Business wants to stay above.

  • Name
    category, sku, barcode
    Type
    string or null
    Description

    As on the form.

  • Name
    is_active
    Type
    boolean
    Description

    Whether the Product is active in Essentio.

  • Name
    is_archived
    Type
    boolean
    Description

    Whether the Product is archived.

  • Name
    notes
    Type
    string or null
    Description

    The Business’s own notes about the Product.

  • Name
    created_at
    Type
    timestamp
    Description

    When the Product was created, in UTC.

  • Name
    updated_at
    Type
    timestamp
    Description

    When the Product last changed, in UTC.

Billing a Product

To put a Product on a document, copy it onto a Line: its price_without_vat is the Line’s unit_price and its vat_rate the Line’s vat_rate, when the document is in the Product’s currency. A Product in another currency has no price there: send the Line’s own.

A Product carries no VAT category, so the Line takes the one of its rate: Z for a vat_rate of 0, S above it — the vat_category the Business’s setup answers with each rate. A Line in another category needs an exemption code: see A Line’s VAT.

Paging through Products

A list answers one page at a time, oldest first, exactly as every list does (Pagination): send each page’s next_cursor back as cursor until it is null. limit is 1 to 100, 25 when not sent.

GET/v1/products

List Products

Lists the Business’s Products a page at a time, oldest first, active or not. Every Role may read them, a Viewer’s key included.

Query parameters

  • Name
    limit
    Type
    integer
    Description

    How many Products a page holds: 1 to 100. Not sent: 25.

  • Name
    cursor
    Type
    string
    Description

    The next_cursor of the page before. Not sent: the first page.

  • Name
    search
    Type
    string
    Description

    Only the Products whose name, code, SKU or description contains this text, in any case. Send the same search with every page.

Answers

  • Name
    200
    Type
    ProductList
    Description

    data: the page’s Products. next_cursor: where the next page starts, or null on the last.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    The Role of the API key or Connected app may not do this.

  • Name
    422
    Type
    Error
    Description

    A limit out of range, or a cursor this API did not give.

Request

GET/v1/products
curl -G https://api.essentio.pro/v1/products \
  -H "Authorization: Bearer ess_your_api_key" \
  -d search=consulting

Response

{
  "data": [
    {
      "id": 7,
      "name": "Consulting",
      "code": "CONS-1",
      "description": "An hour of advice",
      "type": "service",
      "price": "119.00",
      "currency": "EUR",
      "vat_rate": "19.00",
      "vat_included": true,
      "price_without_vat": "100.00",
      "price_with_vat": "119.00",
      "unit": "hour",
      "track_inventory": false,
      "stock_quantity": null,
      "minimum_stock": null,
      "category": "Advice",
      "sku": null,
      "barcode": null,
      "is_active": true,
      "is_archived": false,
      "notes": null,
      "created_at": "2026-09-01T09:30:00+00:00",
      "updated_at": "2026-09-01T09:30:00+00:00"
    }
  ],
  "next_cursor": null
}
GET/v1/products/{product}

Retrieve a Product

One Product of the Business, by its id. Every Role may read it. A Product of another Business is not found.

Answers

  • Name
    200
    Type
    Product
    Description

    The Product.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    The Role of the API key or Connected app may not do this.

  • Name
    404
    Type
    Error
    Description

    The Business has no Product with this id.

Request

GET/v1/products/7
curl https://api.essentio.pro/v1/products/7 \
  -H "Authorization: Bearer ess_your_api_key"
POST/v1/products

Create a Product

Creates a Product of the Business, held to the same rules as the Product form in Essentio. An Admin’s or Member’s key may create; a Viewer’s may not. Send an Idempotency-Key to retry safely, as every create does (Idempotency) does.

Body

  • Name
    name
    Type
    string
    Description

    Required.

  • Name
    type
    Type
    string
    Description

    Required. product or service.

  • Name
    price
    Type
    string
    Description

    Required. A decimal string, at least 0: "119.00", with no more decimals than its currency has and at most 15 digits before the point. A JSON number is refused — send a string.

  • Name
    currency
    Type
    string
    Description

    Required. ISO 4217, one Essentio computes documents in.

  • Name
    vat_rate
    Type
    string
    Description

    The VAT rate in percent, a decimal string from 0 to 100: "19.00". The Business’s rates are in its setup. Not sent or null: 0. A JSON number is refused.

  • Name
    vat_included
    Type
    boolean
    Description

    Whether price holds the VAT. Not sent: false.

  • Name
    code
    Type
    string
    Description

    Unique within the Business. Not sent or blank: Essentio gives it one.

  • Name
    unit
    Type
    string
    Description

    Not sent or null: pcs.

  • Name
    track_inventory
    Type
    boolean
    Description

    Not sent: false.

  • Name
    stock_quantity, minimum_stock
    Type
    integer
    Description

    At least 0, at most 2147483647.

  • Name
    description, category, sku, barcode, notes
    Type
    string
    Description

    Optional, as on the form.

  • Name
    is_active
    Type
    boolean
    Description

    Not sent: true.

Answers

  • Name
    201
    Type
    Product
    Description

    The Product created — or, for a retry under the same Idempotency-Key, the one the first request created.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    422
    Type
    Error
    Description

    A field the rules refused (invalid_request, each field in errors), or an Idempotency-Key sent with another body (idempotency).

Request

POST/v1/products
curl https://api.essentio.pro/v1/products \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: 9b2e4c1a-3f5d-4e7a-8b6c-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consulting",
    "type": "service",
    "price": "119.00",
    "currency": "EUR",
    "vat_rate": "19.00",
    "vat_included": true,
    "unit": "hour"
  }'

Response: 201

{
  "id": 8,
  "name": "Consulting",
  "code": "PRD-CON-7K2Q",
  "description": null,
  "type": "service",
  "price": "119.00",
  "currency": "EUR",
  "vat_rate": "19.00",
  "vat_included": true,
  "price_without_vat": "100.00",
  "price_with_vat": "119.00",
  "unit": "hour",
  "track_inventory": false,
  "stock_quantity": null,
  "minimum_stock": null,
  "category": null,
  "sku": null,
  "barcode": null,
  "is_active": true,
  "is_archived": false,
  "notes": null,
  "created_at": "2026-09-27T10:15:00+00:00",
  "updated_at": "2026-09-27T10:15:00+00:00"
}
PATCH/v1/products/{product}

Update a Product

Changes the fields sent and nothing else, held to the same rules as a create. An Admin’s or Member’s key may update; a Viewer’s may not.

  • price and vat_rate are decimal strings; a JSON number is refused.
  • A price has no more decimals than the Product’s currency: the one sent with it, else the Product’s own. A currency sent with no price is refused when the Product’s price has more decimals than it.
  • A vat_rate or unit sent null keeps the Product’s own.
  • A code another Product of the Business holds is refused; the Product’s own may be sent again.
  • is_archived: true archives the Product.

Answers

  • Name
    200
    Type
    Product
    Description

    The Product as it now stands.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no Product with this id.

  • Name
    422
    Type
    Error
    Description

    A field the rules refused; each is named in errors.

Request

PATCH/v1/products/7
curl -X PATCH https://api.essentio.pro/v1/products/7 \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"price": "129.00"}'
DELETE/v1/products/{product}

Delete a Product

Deletes the Product, as Delete does in Essentio: it leaves the Business’s Products at once and is erased for good thirty days later. Documents that billed it keep their Lines as they are. An Admin’s or Member’s key may delete; a Viewer’s may not.

Answers

  • Name
    204
    Type
    none
    Description

    The Product was deleted. No body.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no Product with this id, or it was deleted already.

Request

DELETE/v1/products/7
curl -X DELETE https://api.essentio.pro/v1/products/7 \
  -H "Authorization: Bearer ess_your_api_key"