Finance

Upsert invoice

Upsert an incoming service invoice with Client and Project context, authored net entries, and modifiers, preserving exact decimal values and the selected currency.

PUT/v1/invoices/{invoiceId}

Path parameters

invoiceId string required

An opaque invoice resource identifier.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1P

Body parameters

application/json · required
clientId string nullable

Optional client reference. Null means the current workspace owns the record; do not create a placeholder client.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1C
projectId string nullable

Project identifier within the current workspace.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1D
contactId string nullable

Contact identifier for the invoice, expense, income, or project contact in the current workspace.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1E
bankAccountId string nullable

ID of the related bank account.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1G
name string nullable

Display name of the resource.

Maximum length: 10000 characters.

ExampleConsulting services
description string nullable

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleConsulting services for January 2026
currencyId string required

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

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F
entries object[] required

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.

at most 1000 items

ShowHide 7 properties
entries[].id string required

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1H
entries[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

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

ExampleConsulting services
entries[].name string required

Display name of the resource.

Maximum length: 10000 characters.

ExampleConsulting service
entries[].description string required

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleMonthly consulting service
entries[].quantity string required

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

Maximum length: 128 characters.

Example2.00
entries[].unit string required

Unit code from the workspace catalog.

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

Examplehour
entries[].pricePerUnit string required

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

Maximum length: 128 characters.

Example100.00
modifiers object[] required

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.

at most 1000 items

ShowHide 6 properties
modifiers[].id string required

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1J
modifiers[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

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

ExampleConsulting services
modifiers[].name string required

Display name of the resource.

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

ExampleVAT
modifiers[].description string nullable

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleValue added tax
modifiers[].entryIndex number nullable

entry index within modifiers.

Example100
modifiers[].value string required

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.

Example15.00%
tags string[] nullable

Tags assigned to the record.

at most 100 items

Example1 item
paymentPlan object[] nullable

Payment schedule for the record.

at most 500 items

ShowHide 9 properties
paymentPlan[].id string required

Opaque identifier for this resource or reference.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1P
paymentPlan[].originalId string nullable

ID of the related original.

ExampleConsulting services
paymentPlan[].amount string required

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

Maximum length: 128 characters.

Example100.00
paymentPlan[].signedAmount string required

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

Maximum length: 128 characters.

Example100.00
paymentPlan[].amountMode string nullable

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

Allowed values: "replace"

Examplereplace
paymentPlan[].currencyId string required

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F
paymentPlan[].direction string required

direction within payment plan.

Allowed values: "inbound", "outbound"

Exampleinbound
paymentPlan[].bankAccountId string required

ID of the related bank account.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1G
paymentPlan[].createdAt string nullable

ISO 8601 timestamp for the authored or payment event. Recurring records preserve their scheduled occurrence.

Example2026-01-15T12:00:00.000Z
pendedAt string nullable

ISO 8601 timestamp for pended.

Example2026-01-15T12:00:00.000Z
cancelledAt string nullable

ISO 8601 timestamp for cancelled.

Example2026-01-15T12:00:00.000Z

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY
if-match string

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.

Send the complete writable representation or change set. Use the latest updatedAt for If-Match.

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 31 properties
data.id string

Opaque identifier for this resource or reference.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1P
data.shortId string

ID of the related short.

ExampleINV-0001
data.clientId string

Optional client reference. Null means the current workspace owns the record; do not create a placeholder client.

Examplenull
data.projectId string

Project identifier within the current workspace.

Examplenull
data.contactId string

Contact identifier for the invoice, expense, income, or project contact in the current workspace.

Examplenull
data.projectWebsite string nullable

project website for this invoice.

Examplehttps://example.com
data.clientWebsite string[] nullable

client website for this invoice.

Example1 item
data.clientType string nullable

client type for this invoice.

Allowed values: "individual", "company", "government"

Exampleindividual
data.contactWebsite string[] nullable

contact website for this invoice.

Example1 item
data.bankAccountId string

ID of the related bank account.

Examplenull
data.invoiceRecurringId string

ID of the related invoice recurring.

Examplenull
data.recurringSourceName string nullable

recurring source name for this invoice.

ExampleConsulting services
data.currency object

Referenced currency with its opaque ID and ISO 4217 currency code.

ShowHide 3 properties
data.currency.id string

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F
data.currency.code string

ISO 4217 currency code, such as SAR or USD.

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

ExampleSAR
data.currency.conversion object

Currency conversion quote used for reporting, including source, target, and rate.

ShowHide 3 properties
data.currency.conversion.from string

ISO 4217 code of the source currency in this persisted quote.

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

ExampleSAR
data.currency.conversion.to string

ISO 4217 code of the target reporting currency in this persisted quote.

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

ExampleSAR
data.currency.conversion.rate string

Exact decimal conversion rate from the quote source currency to its target currency.

Maximum length: 128 characters.

Example1.00
data.name string

Display name of the record.

ExampleConsulting services
data.description string

Optional human-readable description of the record.

ExampleConsulting services for January 2026
data.notes string

Notes attached to the record.

ExampleConsulting services
data.tags string[] nullable

Tags assigned to the record.

Example1 item
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.

at most 1000 items

ShowHide 7 properties
data.entries[].id string

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1H
data.entries[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

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

ExampleConsulting services
data.entries[].name string

Display name of the record.

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[].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[].unit string

Unit code from the workspace catalog.

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

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

at most 1000 items

ShowHide 6 properties
data.modifiers[].id string

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1J
data.modifiers[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

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

ExampleConsulting services
data.modifiers[].name string

Display name of the record.

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

ExampleVAT
data.modifiers[].description string nullable

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleValue added tax
data.modifiers[].entryIndex number nullable

entry index within modifiers.

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

Example15.00%
data.totals object nullable

totals for this invoice.

ShowHide 7 properties
data.totals.lineTotals object nullable

line totals within totals.

data.totals.base string nullable

base within totals.

Example200.00
data.totals.net string

Total before tax and other modifiers.

Example200.00
data.totals.tax string

Tax calculated from the workspace payable modifier.

Example30.00
data.totals.gross string

Total after tax and other price modifiers.

Example230.00
data.totals.payable string

Amount due after all applied modifiers.

Example230.00
data.totals.reporting string nullable

Amount converted to the workspace reporting currency.

Example230.00
data.recurringOn string nullable

recurring on for this invoice.

Example2026-01-15
data.settled boolean nullable

Whether effective transactions cover the amount due.

Examplefalse
data.createdBy string

Identifier of the identity that created the record.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1B
data.updatedBy string

Identifier of the identity that last updated the record.

Examplenull
data.deletedBy string

deleted by for this invoice.

Examplenull
data.settledAt string nullable

Timestamp when effective transactions covered the amount due.

Example2026-01-15T12:00:00.000Z
data.pendedAt string

ISO 8601 timestamp for pended.

Examplenull
data.cancelledAt string

ISO 8601 timestamp for cancelled.

Examplenull
data.createdAt string

ISO 8601 timestamp for the authored or payment event. Recurring records preserve their scheduled occurrence.

Example2026-01-15T12:00:00.000Z
data.updatedAt string

Timestamp used for stale-edit protection. Preserve the server value when updating.

Example2026-01-15T12:00:00.000Z
data.deletedAt string

ISO 8601 timestamp when the record was deleted, or null when it exists.

Examplenull

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
Example 400 response
{
  "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 ↗