Record a manual refund
Record a manual refund. Records money from a MANUAL payment that was already returned outside Hoursmith; moves no money. Card (Stripe) payments are rejected with 409 — issue those refunds in the Hoursmith app. Exactly one of `amount` or `fullRemaining: true` (remaining principal and fee). Refunds cannot be deleted and never reopen a PAID invoice. Domain-idempotent per Idempotency-Key/requestId. Write scope; Owner/Admin only.
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Path Parameters
Invoice id.
Payment id from GET /invoices/{id}/payments.
Header Parameters
Caller-generated UUID/ULID. Same key + same body within 24h replays the original response; money writes are additionally idempotent at the domain level for that key.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/payments/497f6eca-6276-4993-bfeb-53cbbbba6f08/refund" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "refund": { "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" }, "payment": { "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" }, "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" }, "replayed": true }, "warnings": [ "string" ]}{ "data": { "refund": { "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" }, "payment": { "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" }, "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" }, "replayed": true }, "warnings": [ "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" }}{ "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" }}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.
List an invoice's lifecycle history
Read-only, newest first: created, edited, marked sent, emailed / reminded (recipients + delivery status, including failures), viewed by the client, payments, refunds, cancellation, corrections. `summary` answers sent/viewed/paid at a glance. Keyset-paginated with an opaque cursor. Read scope; Owner/Admin/Manager.