Skip to content
Hoursmith Docs
APIReferenceInvoices

List an invoice's payments and refunds

List an invoice's payments and refunds. Read-only ledger, oldest first: payments and refunds with exact decimal amounts, fees, paidDate (YYYY-MM-DD), method label, the operator's note (refund rows carry none), refundOfPaymentId, and per succeeded payment the refunded and refundable totals. Provider account references and provider payment ids are never returned. Read scope; Owner/Admin/Manager (Members get 403).

GET
/invoices/{id}/payments

Authorization

BearerAuth
AuthorizationBearer <token>

Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.

In: header

Path Parameters

id*string

Invoice id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/payments"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",      "kind": "payment",      "provider": "manual",      "status": "pending",      "amount": "string",      "feeAmount": "string",      "feeLabel": "string",      "currency": "string",      "paidDate": "2019-08-24",      "methodId": "a79e32ca-882c-452b-a096-350276aed28d",      "methodLabel": "string",      "note": "string",      "refundOfPaymentId": "60024239-4a50-4f20-bd85-d743a04f16d0",      "refunded": {        "amount": "string",        "feeAmount": "string"      },      "refundable": {        "amount": "string",        "feeAmount": "string"      },      "refundPending": true,      "refundableViaApi": true,      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "warnings": [    "string"  ],  "invoice": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "number": "string",    "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",    "status": "DRAFT",    "paymentStatus": "unpaid",    "currency": "string",    "total": "string",    "amountPaid": "string",    "balanceDue": "string",    "issueDate": "2019-08-24",    "dueDate": "2019-08-24",    "sentAt": "2019-08-24T14:15:22Z",    "lastSentAt": "2019-08-24T14:15:22Z",    "paidAt": "2019-08-24T14:15:22Z"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
Was this page helpful?

Email a payment reminder

Emails a payment reminder with the invoice PDF for a SENT invoice (409 otherwise). Does not change the invoice. Requires the overdueReminders plan feature (402). Every recipient must already be on file for the invoice's client (billing email, client email or a client contact); any other address is rejected with 422 — add it as a client contact in Hoursmith first. Omitted `to` uses the client's default billing recipient, exactly as the app pre-fills it. A provider failure returns 200 with status `failed` and `sendError`, and the invoice is unchanged. A NOT SENT warning means nothing was delivered. A NOT CONFIRMED warning means the provider call had started (a timeout, or an answer that came too late to record): the email may have reached the recipient, so check with them before sending again. Send and remind share the app's send budget: a one-minute cooldown per invoice (send and remind share it), 10 emails per invoice per UTC day, 30 per user per hour across workspaces, 20 per workspace per UTC day while it is on the Free plan or a trial and sends through the Hoursmith sender, and 100 per workspace per hour. A spent budget is a 429 and nothing is sent. Write scope; Owner/Admin/Manager. Idempotency-Key required (a replay never re-sends).

Record a manual payment

Records money received outside Hoursmith (bank transfer, cash, cheque) against a SENT invoice; moves no money. Exactly one of `amount` or `fullBalance: true`. Overpayment, a non-SENT invoice (409), a client payment still being settled (409; a bank payment can take a few business days), a future paidDate or more decimals than the currency allows (422) are rejected. A payment can never be deleted; one that covers the balance permanently marks the invoice PAID. Optional receipt email goes only to the client's billing address; it spends the per-user, Free/trial Hoursmith-sender and per-workspace send budgets, and a spent budget never refuses the payment: it is recorded and receiptEmail reports the receipt as failed, with a warning naming the wait. Domain-idempotent: a retry with the same Idempotency-Key (or hosted requestId), even concurrent, returns the original payment (200, replayed: true) instead of recording twice. Write scope; Owner/Admin only. Available on every plan with API access.