Upsert income records in a batch

PUT/v1/income

Body parameters

application/json · array of records · required

name string required

Display name of the resource.

Maximum length: 10000 characters.

ExampleProduct sale

description string required

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleProduct receipt 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.

ExampleProduct sale

entries[].name string required

Display name of the resource.

Maximum length: 10000 characters.

ExampleProduct sale

entries[].description string required

Human-readable description of the resource.

Maximum length: 10000 characters.

ExampleProduct receipt for January 2026

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.

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

ExampleProduct sale

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%

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

tags string[] required

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.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1W

paymentPlan[].originalId string nullable

ID of the related original.

ExampleProduct sale

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

id string required

Opaque identifier for this resource or reference.

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

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1W

expectedUpdatedAt string nullable

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

Example2026-01-15T12:00:00.000Z

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY

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

Income is an incoming cash source that does not require a service-work relationship. Use it for capital, inheritance, product receipts, or other standalone receipts. A buyer Client is optional. 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 17 properties

data[].id string

Opaque identifier for this resource or reference.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1W

data[].name string

Display name of the record.

ExampleProduct sale

data[].description string

Optional human-readable description of the record.

ExampleProduct receipt for January 2026

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

ExampleProduct sale

data[].entries[].name string

Display name of the record.

Maximum length: 10000 characters.

ExampleProduct sale

data[].entries[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleProduct receipt for January 2026

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.

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

ExampleProduct sale

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

totals for this income.

ShowHide 6 properties

data[].totals.lineTotals object

line totals within totals.

data[].totals.base string

base within totals.

Example400.00

data[].totals.net string

Total before tax and other modifiers.

Example400.00

data[].totals.tax string

Tax calculated from the workspace payable modifier.

Example60.00

data[].totals.gross string

Total after tax and other price modifiers.

Example460.00

data[].totals.payable string

Amount due after all applied modifiers.

Example460.00

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

ID of the related bank account.

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

Examplenull

data[].tags string[]

Tags assigned to the record.

Example1 item

data[].createdBy string

Identifier of the identity that created the record.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1B

data[].updatedBy string

Identifier of the identity that last updated the record.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1B

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

Timestamp when effective transactions covered the amount due.

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

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 ↗