Set a promise-to-pay date

POST/v1/documents/{id}/promise-to-pay

Coming the week of 11 January 2027

This endpoint ships in the week of 11 January 2027. The shape shown here can still change before release.

Records the date a client promised to pay an invoice and pauses its reminders until then.

When a client tells you they will pay on a certain date, record it here. The invoice's reminder sequence sends no further steps until the promise-to-pay date has passed; if the invoice is still unpaid after that, the sequence carries on. Send null to clear the date.

The date is stored on the invoice and recorded in the audit log. See Promise to pay.

Permission: documents.edit
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: set_promise_to_pay
CLI: freeinvoiceautomation doc promise
Available: From the week of 11 January 2027

set_promise_to_pay

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/promise-to-pay \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "promise_to_pay_date": "2027-02-15"
}'

{
  "data": {
    "id": "0193f2b4-2c3d-7e4f-9a5b-6c7d8e9f0a1b",
    "number": "INV-2027-0042",
    "status": "overdue",
    "due_date": "2027-01-31",
    "balance_minor": "120000",
    "currency": "USD",
    "promise_to_pay_date": "2027-02-15"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. A retry with the same key returns the stored response. See Idempotency.

Path Parameters

idstring<uuid>required

Id of the invoice.

Body

application/json

promise_to_pay_datestring<date> | nullrequired

The date the client promised to pay (YYYY-MM-DD), or null to clear it.

Response

200 - application/json

idstring<uuid>

Id of the invoice.

numberstring | null

Invoice number.

statusenum<string>

Invoice status.

Available options: draft, sent, partially_paid, paid, overdue, void

due_datestring<date> | null

Due date of the invoice.

balance_minorstring

Amount still owed, in minor units.

currencystring

Invoice currency.

promise_to_pay_datestring<date> | null

The promise-to-pay date now on the invoice.

Errors

document_voided

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

Send a reminder nowPrevious List late-fee policiesNext

set_promise_to_pay

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/promise-to-pay \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "promise_to_pay_date": "2027-02-15"
}'

{
  "data": {
    "id": "0193f2b4-2c3d-7e4f-9a5b-6c7d8e9f0a1b",
    "number": "INV-2027-0042",
    "status": "overdue",
    "due_date": "2027-01-31",
    "balance_minor": "120000",
    "currency": "USD",
    "promise_to_pay_date": "2027-02-15"
  }
}