ProjectsValidate a new payment

Validate a new payment

Runs the create-payment checks on a body without saving anything.

Unlike create it does not unlink the task's other instalments, so it rejects (37511) a second fixed-price instalment for a task that create would accept.

Use it to:

  • Validate an imported payment plan line before creating it

Rules across fields:

  • R1: As POST /v1/payment R1–R3.

Behaviour:

  • Idempotent.
  • Safe to retry.
  • Changes are visible to the next read immediately.

Next: POST /v1/payment

Not yet documented: examples.

curl -X POST "https://app3.timelog.com/your-account/api/v1/payment/validate-new-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "Name": "John Doe",
  "Comment": "example_string",
  "Amount": 3.14,
  "InvoiceDate": "2024-12-25T10:00:00Z",
  "IsReadyForInvoicing": true,
  "ProjectID": 123,
  "TaskID": 123,
  "ProductNumber": "example_string",
  "DiscountPercentage": 3.14,
  "ProjectSubContractID": 123,
  "Quantity": 3.14,
  "IsFixedPricePayment": true,
  "UnitType": 42
}'
"null"
POST
/v1/payment/validate-new-payment
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.
Content-Typestring
Required

The media type of the request body

Options: application/json
Namestring
Required

Instalment name.

Commentstring

Free-text comment.

Amountnumber

Instalment amount, in the project currency. Unit: project currency > Not yet documented: description.

Format: double
InvoiceDatestring
Required

Date the instalment is due for invoicing. Time zone: not yet documented. > Not yet documented: constraints → timezone.

Format: date-time
IsReadyForInvoicingboolean

Release the instalment for invoicing immediately.

ProjectIDinteger
Required

The project. Must exist (37014) and be accessible to the caller (403). Refers to ProjectRead.ProjectID. Look up valid values with GET /v1/project/get-all. Valid values come from GET /v1/project/get-all.

Format: int32
TaskIDinteger

Task to link the instalment to; only allowed (non-zero) on a task-driven-revenue contract, and the task must be on that contract (37949). 0 = none. Conditional. Must be 0 unless the contract is TaskDrivenRevenue (400 "TaskID can only be added when importing on a Task Driven Revenue Contract."). Refers to TaskRead.TaskID.

Format: int32
ProductNumberstring

Product number TEXT (not an ID). Only used when the InvoiceSetting_ProductNoActive feature is on: a supplied value must exist in the project's legal entity (37939); empty = the default product number for payments (fixed-price contracts: the project's fixed-price product number). Refers to ProductNumberRead.ProductNumber. - Feature InvoiceSetting_ProductNoActive is off — Stored as empty. - Empty and feature on — defaulted

DiscountPercentagenumber

Discount in percent. Unit: percent

Format: double
ProjectSubContractIDinteger
Required

The contract. Must belong to ProjectID (37042, raised inside model validation) and be FixedPriceBasic, TimeMaterialAccountEndBalancing, PrepaidServices or TaskDrivenRevenue (400 "The selected contract does not support import of payment."). Refers to ContractRead.ProjectSubContractID.

Format: int32
Quantitynumber

Quantity in UnitType units. Unit: UnitType

Format: double
IsFixedPricePaymentboolean

Make this the fixed-price instalment of TaskID. Only allowed on a task-driven-revenue contract (400 otherwise). Conditional. Must be false unless the contract is TaskDrivenRevenue.

UnitTypeinteger

Unit of Quantity. - Value not in the enum (e.g. 5) — 400. Allowed values: | Value | Name | Meaning | |---|---|---| | 0 | Undefined | No unit. | | 1 | Hours | Hours. | | 2 | Minutes | Minutes. | | 3 | Days | Days. | | 4 | Km | Kilometres. | | 6 | Pieces | Pieces. | | 7 | Liters | Litres. | | 8 | Meters | Metres. | | 9 | Kilograms | Kilograms. |

Format: int32 • Options: 0, 1, 2, 3, 4, 6, 7, 8, 9
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).

The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.

Not yet documented: how to obtain a token.

Not yet documented: token lifetime.

Body

application/json
Namestring
Required

Instalment name.

Commentstring

Free-text comment.

Amountnumber

Instalment amount, in the project currency.

Unit: project currency

Not yet documented: description.

InvoiceDatestring
Required

Date the instalment is due for invoicing.

Time zone: not yet documented.

Not yet documented: constraints → timezone.

IsReadyForInvoicingboolean

Release the instalment for invoicing immediately.

ProjectIDinteger
Required

The project. Must exist (37014) and be accessible to the caller (403).

Refers to ProjectRead.ProjectID. Look up valid values with GET /v1/project/get-all.

Valid values come from GET /v1/project/get-all.

TaskIDinteger

Task to link the instalment to; only allowed (non-zero) on a task-driven-revenue contract, and the task must be on that contract (37949). 0 = none.

Conditional. Must be 0 unless the contract is TaskDrivenRevenue (400 "TaskID can only be added when importing on a Task Driven Revenue Contract.").

Refers to TaskRead.TaskID.

ProductNumberstring

Product number TEXT (not an ID). Only used when the InvoiceSetting_ProductNoActive feature is on: a supplied value must exist in the project's legal entity (37939); empty = the default product number for payments (fixed-price contracts: the project's fixed-price product number).

Refers to ProductNumberRead.ProductNumber.

  • Feature InvoiceSetting_ProductNoActive is off — Stored as empty.

  • Empty and feature on — defaulted

DiscountPercentagenumber

Discount in percent.

Unit: percent

ProjectSubContractIDinteger
Required

The contract. Must belong to ProjectID (37042, raised inside model validation) and be FixedPriceBasic, TimeMaterialAccountEndBalancing, PrepaidServices or TaskDrivenRevenue (400 "The selected contract does not support import of payment.").

Refers to ContractRead.ProjectSubContractID.

Quantitynumber

Quantity in UnitType units.

Unit: UnitType

IsFixedPricePaymentboolean

Make this the fixed-price instalment of TaskID. Only allowed on a task-driven-revenue contract (400 otherwise).

Conditional. Must be false unless the contract is TaskDrivenRevenue.

UnitTypeinteger

Unit of Quantity.

  • Value not in the enum (e.g. 5) — 400.

Allowed values:

ValueNameMeaning
0UndefinedNo unit.
1HoursHours.
2MinutesMinutes.
3DaysDays.
4KmKilometres.
6PiecesPieces.
7LitersLitres.
8MetersMetres.
9KilogramsKilograms.
Allowed values:012346789

Responses

Success without content: HTTP 200 with the literal JSON body null. Literal JSON null.