Skip to content
Hoursmith Docs
APIReferenceInvoices

Cancel an invoice

Cancel an invoice. Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Requires write scope and an Idempotency-Key. Unpaid DRAFT or SENT only. Releases time entries and expenses, deletes receipt attachments, revokes the public invoice/payment link and clears sent/view history; the number stays retired. Already cancelled: returned unchanged with a warning. Sends no email.

POST
/invoices/{id}/cancel

Authorization

BearerAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Header Parameters

Idempotency-Key*string

Caller-generated UUID/ULID; a retry with the same key and body replays the stored response.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

No input. Send an empty body or {}.

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/cancel" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",    "number": "string",    "status": "DRAFT",    "paymentStatus": "unpaid",    "subtotal": "string",    "discountAmount": "string",    "taxRate": "string",    "total": "string",    "amountPaid": "string",    "currency": "string",    "notes": "string",    "billToName": "string",    "issueDate": "2019-08-24",    "dueDate": "2019-08-24",    "sentAt": "2019-08-24T14:15:22Z",    "paidAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "deletedAt": "2019-08-24T14:15:22Z",    "balanceDue": "string",    "paymentMethods": {},    "billToAddress": "string",    "billToTaxNumber": "string",    "poNumber": "string",    "lastSentAt": "2019-08-24T14:15:22Z",    "viewCount": 0,    "lastViewedAt": "2019-08-24T14:15:22Z",    "groupBy": "project",    "timeRounding": "entry_15m",    "showProjectName": true,    "showTaskName": true,    "attachTimesheet": true,    "includeExpenseReceipts": true,    "reminderOffsets": [      0    ],    "lineItems": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "position": 0,        "kind": "time",        "sourceType": "TRACKED_TIME",        "description": "string",        "subtitle": "string",        "detail": "string",        "groupLabel": "string",        "quantity": "string",        "unitLabel": "string",        "unitPrice": "string",        "amount": "string",        "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",        "expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc"      }    ],    "lineItemCount": 0,    "draftLineSet": {      "selectedEntryIds": [        "ee27e6bf-496d-4836-8009-874d6a5da3e7"      ],      "expenseIds": [        "4e1e9976-0015-4c46-b3e7-b9d93419b799"      ],      "manualLineItems": [        {          "description": "string",          "projectName": "string",          "taskName": "string",          "quantity": "string",          "unitPrice": "string",          "unitLabel": "string",          "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8"        }      ],      "fixedFeeAllocations": [        {          "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",          "amount": "string"        }      ]    },    "draftLineSetComplete": 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"  }}
{  "error": {    "code": "unauthenticated",    "message": "string",    "fields": {      "property1": "string",      "property2": "string"    },    "requiredPlan": "studio",    "feature": "string",    "requestId": "string"  }}
Was this page helpful?