ProjectsValidate a payment update (dry run)

Validate a payment update (dry run)

Checks whether a payment update would be accepted, without saving anything.

Takes the PaymentUpdate body of PUT /v1/payment/{paymentID}, applies it to a detached copy of the payment and runs the same refusals (editability, amount derivation) and the save's business rules (draft invoice, invoice-date change on Time & Material Basic, share-ratio rule). Answers 200 with null.

Use it to:

  • Pre-check an instalment change before committing it from a sync job

Not for:

  • Saving → PUT /v1/payment/{paymentID}

Rules across fields:

  • R1: As PUT /v1/payment/{paymentID} R1: Amount needs a non-zero effective Quantity and a Discount below 100 %.

Behaviour:

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

Call first: GET /v1/payment/{paymentID}

Next: PUT /v1/payment/{paymentID}

Not yet documented: examples.

curl -X POST "https://app3.timelog.com/your-account/api/v1/payment/123/validate-update-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "Name": "null",
  "Amount": "null",
  "InvoiceDate": "null",
  "Quantity": "null"
}'
"null"
POST
/v1/payment/{paymentID}/validate-update-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.
path
paymentIDinteger
Required

The payment to check. Route constraint :int.

Format: int32
Content-Typestring
Required

The media type of the request body

Options: application/json
Namestringnull

New name (text) of the instalment. Null: null / omitted = unchanged; there is no way to clear the name. - Sent as empty string — 400 Code 200 'Name cannot be empty when supplied.' > Not yet documented: constraints → max length.

Min length: 1
Amountnumbernull

New amount of the instalment, in the project currency. Null: null / omitted = unchanged. Unit: project currency - Sent — Applied last (after Quantity); the unit Rate is then recalculated from the amount. - Effective Quantity (sent or stored) is 0 — 400 — the rate derivation would silently reset the amount to 0. - The payment's Discount is 100 % or more — 400 — same reason.

Format: double
InvoiceDatestringnull

New invoice date of the instalment. Null: null / omitted = unchanged. Time zone: none — only the date part is kept - Not a valid date — 400 Code 200 'Invoice date is not valid date.' - Any time of day — Truncated to the date (.Date), like the payment page. - The payment's contract is Time & Material Basic and the date changes — 400 '…invoice date is not allowed to change.' (37526). - Changed — On save the instalment's exchange rate to system currency is refreshed for the new date and the system-currency amount recalculated.

Format: date-time
Quantitynumbernull

New quantity, in the payment's UnitType units. Null: null / omitted = unchanged. Unit: the payment's UnitType (PaymentRead.UnitType) - Sent — The amount is recalculated from the stored unit Rate, Quantity and Discount (RecalculateAmount) — unless Amount is also sent, which then wins. > Not yet documented: constraints.

Format: double
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.

Path Parameters

paymentIDinteger
Required

The payment to check. Route constraint :int.

Body

application/json
Namestring,null

New name (text) of the instalment.

Null: null / omitted = unchanged; there is no way to clear the name.

  • Sent as empty string — 400 Code 200 'Name cannot be empty when supplied.'

Not yet documented: constraints → max length.

Amountnumber,null

New amount of the instalment, in the project currency.

Null: null / omitted = unchanged.

Unit: project currency

  • Sent — Applied last (after Quantity); the unit Rate is then recalculated from the amount.

  • Effective Quantity (sent or stored) is 0 — 400 — the rate derivation would silently reset the amount to 0.

  • The payment's Discount is 100 % or more — 400 — same reason.

InvoiceDatestring,null

New invoice date of the instalment.

Null: null / omitted = unchanged.

Time zone: none — only the date part is kept

  • Not a valid date — 400 Code 200 'Invoice date is not valid date.'

  • Any time of day — Truncated to the date (.Date), like the payment page.

  • The payment's contract is Time & Material Basic and the date changes — 400 '…invoice date is not allowed to change.' (37526).

  • Changed — On save the instalment's exchange rate to system currency is refreshed for the new date and the system-currency amount recalculated.

Quantitynumber,null

New quantity, in the payment's UnitType units.

Null: null / omitted = unchanged.

Unit: the payment's UnitType (PaymentRead.UnitType)

  • Sent — The amount is recalculated from the stored unit Rate, Quantity and Discount (RecalculateAmount) — unless Amount is also sent, which then wins.

Not yet documented: constraints.

Responses

Success without content: HTTP 200 with the literal JSON body null. The literal null: the update would pass the checks.