Add applied modifier to an expense

POST/v1/expenses/{expenseId}/modifiers

Path parameters

expenseId string required

An opaque expense resource identifier.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1R

Body parameters

application/json · required

catalogModifierId string nullable

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

name string nullable

Display name of the resource.

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

ExampleService fee

description string nullable

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleMonthly office cleaning service

kind string nullable

kind for this expense.

Allowed values: "percentage", "fixed"

Examplepercentage

stage string nullable

stage for this expense.

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

Exampleprice

effect string nullable

effect for this expense.

Allowed values: "increase", "decrease"

Exampleincrease

value string nullable

Value returned by the operation.

Maximum length: 128 characters.

Example5

entryId string nullable

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

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1H

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 Expense is an outgoing payment source for a Vendor's service, whether that Vendor is an individual or a company. Client and Project are optional; a null Client means the current Workspace. 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.

ExampleOffice cleaning

data.entries[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleMonthly office cleaning service

data.entries[].unitCode string

Unit code from the workspace catalog.

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

Exampleitem

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.

Example3.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.

Example50.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.

ExampleService fee

data.modifiers[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleValue added tax

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/expenses/01JQ2T5Y5Q3R8W9N6M4K2H7P1R/modifiers" \ -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": "Service fee", "kind": "percentage", "stage": "price", "effect": "increase", "value": "5" }'

{ "data": { "entries": [ { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1H", "catalogEntryId": "Consulting services", "name": "Office cleaning", "description": "Monthly office cleaning service", "unitCode": "item", "quantity": "3.00", "pricePerUnit": "50.00", "currencyId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1F" } ], "modifiers": [ { "id": "01JQ2T5Y5Q3R8W9N6M4K2H7P1J", "catalogModifierId": "Consulting services", "entryId": null, "name": "Service fee", "description": "Value added tax", "kind": "percentage", "stage": "price", "effect": "increase", "value": "5", "currencyId": null } ], "currencyId": "01JQ2T5Y5Q3R8W9N6M4K2H7P1F", "updatedAt": "2026-01-15T12:00:00.000Z" } }