Mark Invoice as Paid

Mark an invoice as paid when you receive payment. This endpoint updates the invoice status and records the payment timestamp.

Endpoint

Path Parameters

Request Body

State Transition Rules

This endpoint can only be called on invoices with status:

• sent - Invoice has been sent and is awaiting payment
• overdue - Invoice has passed its due date

Cannot be called on:

• draft - Invoice not yet sent
• paid - Invoice already paid
• canceled - Invoice has been canceled

Behavior

When called successfully:

1. Invoice status is updated to paid
2. paid_at field is set to the provided value (or current time)
3. updated_at timestamp is refreshed

Code Examples

import requests

invoice_id = "inv_01HXYZ123ABC"
url = f"http://localhost:8000/api/v1/invoices/{invoice_id}/mark-paid"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {
  "paid_at": "2025-11-24T13:00:00Z"
}

response = requests.post(url, json=data, headers=headers)
invoice = response.json()
print(invoice)

Response

Returns the updated invoice object:

{
  "id": "inv_01HXYZ123ABC",
  "organization_id": "org_01HABC456DEF",
  "status": "paid",
  "paid_at": "2025-11-24T13:00:00Z",
  "updated_at": "2025-11-24T13:00:00Z",
  ...
}

Error Scenarios

400 Bad Request

• Invalid invoice status (must be sent or overdue)
• Invalid paid_at datetime format

404 Not Found

• Invoice ID does not exist
• Invoice belongs to a different organization

401 Unauthorized

• Missing or invalid API key
• API key does not have permission to update invoices

Idempotency

Calling this endpoint multiple times on the same invoice is safe. If the invoice is already paid, subsequent calls will return the existing paid invoice without error.

Related Documentation

• Create & Send Invoices
• Invoice Data Model
• List & Retrieve Invoices