ProjectsUpdate a payment

Update a payment

Changes the name, amount, invoice date and/or quantity of a contract payment (billing-plan instalment) and returns it.

Partial update (PaymentUpdate): only the fields you send change; an empty object is accepted and changes nothing. Quantity recalculates the amount from the unit rate; Amount recalculates the unit rate (and wins when both are sent); a new invoice date refreshes the exchange rate to system currency. Refused (400) for payments without a contract, booked or on a draft invoice, on contract models that do not allow editing payments, for an amount that cannot be derived (quantity 0, discount 100 %), and for an invoice-date change on a Time & Material Basic contract. Answers 200 with the payment re-read as PaymentRead. Requires access to the payment's project (same gate as GET /v1/payment/{paymentID}).

Use it to:

  • Re-schedule an instalment (InvoiceDate) or change its amount from an ERP / PSA billing plan
  • Rename an instalment so it reads correctly on the invoice

Not for:

  • Creating instalments → POST /v1/payment
  • Changing a continuous contract's periodic fee → POST /v1/contract/update-recurring-contract-payment-plan-amount
  • Discount, unit, task, product number or fixed-price flag — not in the body

Rules across fields:

  • R1: Amount needs a non-zero effective Quantity (sent or stored) and a stored Discount below 100 % (400).
  • R2: Applied in the order InvoiceDate, Quantity, Amount: when Quantity and Amount are both sent, Amount is kept and the rate derived from it.

Behaviour:

  • Idempotent.
  • Same body → same stored values. An empty object saves nothing.
  • Safe to retry.
  • Side effect: Updates the instalment row and its budget periods (recurrence contracts).
  • Side effect: Recalculates dependants by contract type: fixed-price recurrence (rate / quantity changes), task-driven revenue (task + contract), fixed-price basic (contract), multi-customer split, continuous item invoicing (disbursements), contract payment-plan sync, invoicing potential, registration currency data, pending-booking status.
  • Side effect: A changed invoice date refreshes the instalment's exchange rate to system currency for that date.
  • Changes are visible to the next read immediately.

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

Next: GET /v1/payment/{paymentID}

See also: POST /v1/payment/{paymentID}/validate-update-payment, DELETE /v1/payment/{paymentID}

Not yet documented: behaviour → events emitted; examples.

curl -X PUT "https://app3.timelog.com/your-account/api/v1/payment/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "Name": "null",
  "Amount": "null",
  "InvoiceDate": "null",
  "Quantity": "null"
}'
{
  "Properties": {
    "Name": "John Doe",
    "PaymentID": 123,
    "PaymentGuid": "123e4567-e89b-12d3-a456-426614174000",
    "Comment": "example_string",
    "Amount": 3.14,
    "InvoiceDate": "2024-12-25T10:00:00Z",
    "IsReadyForInvoicing": true,
    "InstallmentType": 42,
    "ProjectID": 123,
    "TaskID": 123,
    "ProductNumberID": 123,
    "Discount": 3.14,
    "ProjectSubContractID": 123,
    "Quantity": 3.14,
    "UnitType": 42,
    "Rate": 3.14,
    "IsFixedPricePayment": true,
    "ExpensesCost": 3.14
  },
  "Links": [
    {
      "Href": "example_string",
      "Rel": "example_string"
    }
  ],
  "Actions": [
    {}
  ]
}
PUT
/v1/payment/{paymentID}
PUT
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 change. 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 change. 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

Propertiesobject

One billing-plan instalment of a contract: what will be invoiced (name, quantity × rate less discount = amount), when (InvoiceDate), on which project / contract / task, and whether it is ready for invoicing. The TAF self link points to GET /v1/payment/{PaymentID}; each entity also lists the six payment TAF actions.

Linksarray
Actionsobject[]