Add applied entry to an invoice

POST/v1/invoices/{invoiceId}/entries

Path parameters

invoiceId string required

An opaque invoice resource identifier.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1P

Body parameters

application/json · required

catalogEntryId string nullable

Optional catalog entry reference used to seed this applied entry; catalog identity is separate from the saved applied fact.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleConsulting services

name string nullable

Display name of the resource.

Minimum length: 1 character. · Maximum length: 10000 characters.

ExampleConsulting service

description string nullable

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleConsulting services for January 2026

unitCode string nullable

Unit code from the workspace catalog.

Minimum length: 1 character. · Maximum length: 128 characters.

Exampleunspecified

quantity string nullable

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example2.00

pricePerUnit string nullable

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example100.00

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY

if-match string required

Quoted updatedAt timestamp used to reject stale writes. Send the latest value as If-Match: "<updatedAt>".

Minimum length: 3 characters. · pattern ^".+"$

Example"2026-01-15T12:00:00.000Z"

workspace-id string required

Workspace scope for the request. Required for workspace operations and must belong to the authenticated identity.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1A

An Invoice is an incoming service source. Use Client and Project for the service context and Entries for the priced units. It may be unpaid or partially paid; record cash separately through Transactions.

Response

200Success

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

data object

Returned records. Collections and batches use an array; single records use an object.

ShowHide 4 properties

data.entries object[]

Applied economic entries. Each entry is a reusable priced unit for a product, service, plan, or other calculable line. Entry prices are authored net prices; the workspace tax modifier calculates VAT.

ShowHide 8 properties

data.entries[].id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1H

data.entries[].catalogEntryId string

Optional catalog entry reference used to seed this applied entry; catalog identity is separate from the saved applied fact.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleConsulting services

data.entries[].name string

Display name of the record.

Minimum length: 1 character. · Maximum length: 10000 characters.

ExampleConsulting service

data.entries[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleMonthly consulting service

data.entries[].unitCode string

Unit code from the workspace catalog.

Minimum length: 1 character. · Maximum length: 128 characters.

Examplehour

data.entries[].quantity string

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example2.00

data.entries[].pricePerUnit string

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example100.00

data.entries[].currencyId string

Currency identifier for the amount. It selects the currency metadata used by the record.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F

data.modifiers object[]

Modifiers applied to one entry or the whole source. Supported values are signed fixed amounts or percentages, such as `15.00%` or `-25.00`; arbitrary multiplication and division are not supported.

ShowHide 10 properties

data.modifiers[].id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1J

data.modifiers[].catalogModifierId string

Optional catalog modifier reference used to seed this applied modifier; catalog identity is separate from the saved applied fact.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleConsulting services

data.modifiers[].entryId string

Public applied entry ID that binds this modifier to an entry in the same applied snapshot.

Minimum length: 1 character. · Maximum length: 128 characters.

Examplenull

data.modifiers[].name string

Display name of the record.

Minimum length: 1 character. · Maximum length: 10000 characters.

ExampleConsulting service

data.modifiers[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleMonthly consulting service

data.modifiers[].kind string

kind within modifiers.

Allowed values: "percentage", "fixed"

Examplepercentage

data.modifiers[].stage string

stage within modifiers.

Allowed values: "price", "tax", "settlement"

Exampleprice

data.modifiers[].effect string

effect within modifiers.

Allowed values: "increase", "decrease"

Exampleincrease

data.modifiers[].value string

Modifier value. A trailing `%` marks a percentage; a leading `-` marks a decrease. Modifiers support fixed or percentage adjustments, not arbitrary multiplication or division.

Maximum length: 128 characters.

Example5

data.modifiers[].currencyId string

Currency identifier for the amount. It selects the currency metadata used by the record.

Minimum length: 1 character. · Maximum length: 128 characters.

Examplenull

data.currencyId string

Currency identifier for the amount. It selects the currency metadata used by the record.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F

data.updatedAt string

Applied snapshot revision. Send the latest value in If-Match for child writes; the response returns the new revision.

Example2026-01-15T12:00:00.000Z

Possible errors

400 Invalid request

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error object

Error details returned for a failed request.

ShowHide 4 properties

error.code string

Stable machine-readable error or resource code.

Exampleinvalid_input

error.message string

Human-readable explanation of the result or error.

ExampleThe request could not be validated.

error.requestId string

Correlation identifier for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error.details object nullable

Additional structured details about the result or error.

ShowHide 1 property

error.details.issues object[]

Structured field issues returned when request validation fails.

ShowHide 3 properties

error.details.issues[].path string | number[]

Field path where the validation issue occurred.

One of: string alternative 1, number alternative 2

Example0 items

error.details.issues[].reason string

Machine-readable reason for the validation issue.

Allowed values: "expected_type", "required", "unexpected_property", "invalid_value", "invalid_json", "invalid_query", "unsupported_media_type", "body_too_large", "body_timeout", "conflicting_scope", "missing_header", "concurrency_required", "invalid_resource_id", "invalid_request"

Exampleinvalid_request

error.details.issues[].code string nullable

Stable machine-readable error or resource code.

Exampleinvalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "The request could not be validated.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "issues": [
        {
          "path": [],
          "reason": "invalid_request"
        }
      ]
    }
  }
}

View raw OpenAPI operation

Use the machine-readable contract for client generation and payload validation.

Open OpenAPI contract ↗

curl --include --fail-with-body --request POST "${NQD_API_URL:-http://api.nqd.localhost:1335}/v1/invoices/01JQ2T5Y5Q3R8W9N6M4K2H7P1P/entries" \ -H "Authorization: Bearer $NQD_API_KEY" \ -H "Workspace-Id: $NQD_WORKSPACE_ID" \ -H "If-Match: $NQD_IF_MATCH" \ -H "Content-Type: application/json" \ --data '{ "name": "Consulting service", "unitCode": "unspecified", "quantity": "2.00", "pricePerUnit": "100.00" }'

{ "data": { "entries": [ { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1H", "catalogEntryId": "Consulting services", "name": "Consulting service", "description": "Monthly consulting service", "unitCode": "hour", "quantity": "2.00", "pricePerUnit": "100.00", "currencyId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1F" } ], "modifiers": [ { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1J", "catalogModifierId": "Consulting services", "entryId": null, "name": "Consulting service", "description": "Monthly consulting service", "kind": "percentage", "stage": "price", "effect": "increase", "value": "5", "currencyId": null } ], "currencyId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1F", "updatedAt": "2026-01-15T12:00:00.000Z" } }