{ "openapi": "3.1.0", "info": { "title": "Invosend Invoice API", "version": "1.0.0", "summary": "Generate invoices and PDFs, manage them and their recurring series, and receive webhooks.", "description": "Public API of [Invosend](https://invosend.com). Authenticate with an API key (`Authorization: Bearer isk_live_...`) created in the dashboard; a paid plan and the workspace owner role are required.\n\n**Rate limits:** per workspace by plan (Professional 10, Specialist 20, Business 30, Enterprise 60 requests per minute by default) and 30 requests per minute per IP address, shared by all endpoints. Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`.\n\n**Errors** use `{ \"data\": null, \"error\": { \"status\", \"name\", \"message\" } }`.\n\nFull documentation: https://www.invosend.com/developers", "contact": { "name": "Invosend", "url": "https://invosend.com" } }, "servers": [ { "url": "https://app.invosend.com", "description": "Production" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Invoices", "description": "Create invoices and read or change them." }, { "name": "Recurring", "description": "Manage recurring series created with `is_recurring` / `recurring_interval`." }, { "name": "Webhooks", "description": "Events Invosend sends to your server." } ], "paths": { "/api/invoices/generate-external": { "post": { "tags": [ "Invoices" ], "summary": "Generate an invoice", "description": "Creates an invoice and its PDF. Uses 1 invoice credit per successful call. The invoice is **not emailed** (except follow-up invoices of a recurring series). Send `is_recurring` with `recurring_interval` to start a recurring series.", "operationId": "generateInvoice", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The invoice was created and the PDF generated.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateInvoiceResponse" }, "example": { "data": { "id": "cjld2cjxh0000qzrmn831i7rn", "invoice_number": "INV-1-202610-0007", "pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202610_0007_UNPAID.pdf", "credits_remaining": 24, "is_recurring": false, "template": { "id": "k3p9x2m7c0000abcd1234efgh", "name": "Classic", "source": "system_default" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "The workspace invoice credit balance is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A request with the same `Idempotency-Key` is still being processed. Retry in a moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The `Idempotency-Key` was already used with a different request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateInvoiceRequest" } } } } } }, "/api/invoices/external": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "description": "Lists invoices of the workspace, newest first.", "operationId": "listInvoices", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "A page of invoices.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ] } }, "/api/invoices/external/templates": { "get": { "tags": [ "Invoices" ], "summary": "List invoice templates", "description": "The invoice templates that can be named in `template` when generating an invoice. `available` says whether your plan allows it; `workspace_default` and `system_default` mark the defaults used when `template` is left out.", "operationId": "listTemplates", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The templates.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "available": { "type": "boolean" }, "system_default": { "type": "boolean" }, "workspace_default": { "type": "boolean" } } } } } }, "example": { "data": [ { "id": "k3p9x2m7c0000abcd1234efgh", "name": "Classic", "available": true, "system_default": true, "workspace_default": false }, { "id": "q8w2e4r6t0000zxcv5678bnmk", "name": "Modern", "available": true, "system_default": false, "workspace_default": true } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices/external/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice", "description": "Returns one invoice.", "operationId": "getInvoice", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The invoice.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ] } }, "/api/invoices/external/{id}/status": { "put": { "tags": [ "Invoices" ], "summary": "Update invoice status", "description": "Sets the status of an invoice. Never sends an email. Status changes trigger the matching webhook event.", "operationId": "updateInvoiceStatus", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The new status.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_number": { "type": "string" }, "invoice_status": { "$ref": "#/components/schemas/InvoiceStatus" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/InvoiceStatus" } } }, "example": { "status": "paid" } } } } } }, "/api/invoices/external/{id}/archive": { "put": { "tags": [ "Invoices" ], "summary": "Archive or unarchive an invoice", "description": "Archives or restores an invoice.", "operationId": "archiveInvoice", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The archive state.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_number": { "type": "string" }, "is_archived": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_archived" ], "properties": { "is_archived": { "type": "boolean" } } }, "example": { "is_archived": true } } } } } }, "/api/invoices/external/{id}/pdf": { "post": { "tags": [ "Invoices" ], "summary": "Get or regenerate the PDF", "description": "Returns the PDF URL, regenerating the file when it is missing or when `force` is true.", "operationId": "getInvoicePdf", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The PDF location.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "generated": { "type": "boolean", "description": "`true` when the file was (re)generated by this call." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "default": false } } }, "example": { "force": false } } } } } }, "/api/invoices/external/recurring": { "get": { "tags": [ "Recurring" ], "summary": "List recurring series", "description": "Lists the recurring series of the workspace, newest first.", "operationId": "listRecurringSeries", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "A page of series (without occurrences).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringSeries" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "draft" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ] } }, "/api/invoices/external/recurring/{id}": { "get": { "tags": [ "Recurring" ], "summary": "Get a recurring series", "description": "Returns one series with all its occurrences.", "operationId": "getRecurringSeries", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The series.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecurringSeries" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/SeriesId" } ] } }, "/api/invoices/external/recurring/{id}/status": { "put": { "tags": [ "Recurring" ], "summary": "Pause or resume a series", "description": "Resuming requires a plan with recurring invoices.", "operationId": "setRecurringStatus", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The updated series.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecurringSeries" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/SeriesId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "example": { "status": "paused" } } } } } }, "/api/invoices/external/recurring/{id}/extend": { "put": { "tags": [ "Recurring" ], "summary": "Extend a series", "description": "Adds occurrences after the last one. Send `count` or `end_date`, not both.", "operationId": "extendRecurringSeries", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The updated series.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecurringSeries" }, "meta": { "type": "object", "properties": { "added": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/SeriesId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 120 }, "end_date": { "type": "string", "format": "date" } } }, "example": { "count": 3 } } } } } }, "/api/invoices/external/recurring/{id}/frequency": { "put": { "tags": [ "Recurring" ], "summary": "Change how often a series repeats", "description": "Replaces the upcoming occurrences that have not been generated yet; generated ones are kept. `start_date` must be in the future. Send `count` or `end_date`, not both.", "operationId": "changeRecurringFrequency", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The updated series.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecurringSeries" }, "meta": { "type": "object", "properties": { "replaced": { "type": "integer" }, "added": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/SeriesId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "frequency", "start_date" ], "properties": { "frequency": { "$ref": "#/components/schemas/RecurringInterval" }, "start_date": { "type": "string", "format": "date" }, "count": { "type": "integer", "minimum": 1, "maximum": 120 }, "end_date": { "type": "string", "format": "date" } } }, "example": { "frequency": "monthly", "start_date": "2027-01-01", "count": 6 } } } } } }, "/api/invoices/external/recurring/{id}/skip": { "post": { "tags": [ "Recurring" ], "summary": "Skip an upcoming occurrence", "description": "Removes one upcoming occurrence. Occurrences that already produced an invoice cannot be removed.", "operationId": "skipRecurringOccurrence", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The updated series.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RecurringSeries" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "$ref": "#/components/parameters/SeriesId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date" } } }, "example": { "date": "2027-01-01" } } } } } } }, "webhooks": { "invoiceEvent": { "post": { "summary": "Invoice event", "description": "Invosend sends a `POST` with a JSON body to every endpoint registered at https://app.invosend.com/settings/webhooks (workspace owner, plan with API access, up to 5 endpoints) that subscribed to the event.\n\n**Headers:** `Invosend-Event` (event type), `Invosend-Delivery` (event id), `Invosend-Signature` (`t=,v1=`).\n\n**Verify** by computing HMAC-SHA256 over `{t}.{raw body}` with the endpoint's signing secret (`whsec_...`) and comparing it with `v1`; reject if `t` is older than 5 minutes.\n\n**Reply** with any `2xx` within 10 seconds. Otherwise the delivery is retried up to 7 more times (after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h). An event can arrive more than once or out of order: dedupe on the event `id`.", "operationId": "invoiceEvent", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_9f2c1b7a4e3d5c6b8a1f0e2d", "object": "event", "type": "invoice.paid", "created": "2026-10-01T09:30:12.000Z", "data": { "object": { "id": "cjld2cjxh0000qzrmn831i7rn", "invoice_number": "INV-1-202610-0007", "customer_name": "Acme Corp", "customer_email": "billing@acme.com", "currency": "USD", "subtotal": 500, "discount_total": 0, "tax_rate": 0, "tax_amount": 0, "amount": 500, "invoice_status": "paid", "is_archived": false, "is_recurring": false, "recurring_interval": "none", "issue_date": "2026-10-01T02:15:40.000Z", "due_date": "2026-10-15", "paid_at": "2026-10-01T09:30:11.000Z", "pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202610_0007_PAID.pdf", "pdf_status": "ready" }, "previous_status": "unpaid" } } } } }, "responses": { "2XX": { "description": "Event accepted." } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "isk_live_...", "description": "Create a key at https://app.invosend.com/settings/api-keys (paid plan, workspace owner). Send it as `Authorization: Bearer isk_live_...`." } }, "parameters": { "InvoiceId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "description": "Invoice `id` returned by the generate call." }, "SeriesId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "description": "Recurring series id (`recurring.schedule_id`)." }, "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x21-\\x7E]+$" }, "description": "1-255 printable characters, for example a UUID per invoice. A retry with the same key and body returns the first response (header `Idempotent-Replayed: true`) without creating another invoice or using another credit. Kept for 24 hours per workspace; only successful responses are stored." } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute for the workspace." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current window." } }, "responses": { "BadRequest": { "description": "Missing or invalid fields, or the request cannot be applied (see `error.message`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key is missing, malformed, invalid or revoked, or the workspace plan does not include API access (or the feature requested).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The invoice or series does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Item": { "type": "object", "required": [ "quantity", "price" ], "properties": { "description": { "type": "string", "description": "Product or service name. Defaults to `Item` when empty.", "example": "Consulting Services" }, "quantity": { "type": "number", "minimum": 0.01, "maximum": 999999, "description": "Number of units, with up to 2 decimals (for example `1.5` hours).", "example": 2 }, "price": { "type": "number", "minimum": 0, "description": "Price per unit.", "example": 500 }, "discount": { "type": "number", "minimum": 0, "default": 0, "description": "Discount amount for this line." }, "unit": { "type": "string", "description": "Unit label shown next to the quantity, such as `pcs` or `hour`.", "example": "hour" }, "tax_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Per-item tax percentage override. Omit to use the invoice-level `tax_rate`." } } }, "GenerateInvoiceRequest": { "type": "object", "required": [ "customer_name", "items" ], "properties": { "customer_name": { "type": "string", "description": "Client or invoice recipient name.", "example": "Acme Corp" }, "customer_email": { "type": "string", "format": "email", "description": "The invoice created by this call is not emailed. Required when the invoice is recurring: each invoice generated afterwards is emailed to this address.", "example": "billing@acme.com" }, "customer_tax_id": { "type": "string", "maxLength": 40, "description": "Tax registration number of the client (NPWP in Indonesia). Printed under the client's address on the invoice.", "example": "01.234.567.8-901.000" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Item" }, "description": "At least one valid item (`quantity > 0`, `price >= 0`)." }, "currency": { "type": "string", "default": "IDR", "description": "Currency code, such as `IDR` or `USD`.", "example": "USD" }, "tax_rate": { "type": "number", "minimum": 0, "maximum": 100, "default": 0, "description": "Tax percentage calculated from the subtotal after discount." }, "discount_total": { "type": "number", "minimum": 0, "default": 0, "description": "Invoice-level discount. It is taken off before tax, so tax is calculated on the discounted amount (shared across the items in proportion to their value)." }, "due_date": { "type": "string", "format": "date", "description": "Defaults to 14 days after generation." }, "notes": { "type": "string", "description": "Additional notes shown on the invoice." }, "custom_payment_notes": { "type": "string", "description": "Extra payment instructions shown on the PDF." }, "footer_text": { "type": "string", "description": "Short text shown at the bottom of the PDF." }, "is_recurring": { "type": "boolean", "description": "Creates a recurring series; this invoice is the first one. Requires a plan with recurring invoices, plus `recurring_interval` and `customer_email`." }, "recurring_interval": { "$ref": "#/components/schemas/RecurringInterval" }, "recurring_count": { "type": "integer", "minimum": 2, "maximum": 121, "default": 4, "description": "Total number of invoices in the series, including the first one. Use this or `recurring_end_date`, not both." }, "recurring_end_date": { "type": "string", "format": "date", "description": "Date after which no more invoices are generated; must be in the future. Use this or `recurring_count`, not both." }, "payment_gateway": { "type": "string", "enum": [ "midtrans", "xendit", "stripe", "paypal", "razorpay", "mollie" ], "description": "The gateway must already be connected in the workspace." }, "payment_account": { "type": "string", "description": "ID of an existing payment account (bank details) to attach to the invoice." }, "template": { "type": "string", "description": "ID of the invoice template to use (see GET /api/invoices/external/templates). Without it, the default template chosen in Settings is used, then Invosend's default.", "example": "k3p9x2m7c0000abcd1234efgh" } }, "example": { "customer_name": "Acme Corp", "customer_email": "billing@acme.com", "items": [ { "description": "Consulting Services", "quantity": 2, "price": 500, "tax_rate": 11 } ], "discount_total": 50, "currency": "USD", "notes": "Thank you for your business." } }, "RecurringInterval": { "type": "string", "enum": [ "weekly", "fortnightly", "monthly", "quarterly", "semi-annually", "yearly" ], "description": "How often a recurring series repeats." }, "GenerateInvoiceResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "invoice_number", "pdf_url", "is_recurring" ], "properties": { "id": { "type": "string", "description": "Identifies this invoice in the other endpoints." }, "invoice_number": { "type": "string", "example": "INV-1-202610-0007" }, "pdf_url": { "type": "string", "format": "uri" }, "credits_remaining": { "type": [ "integer", "null" ], "description": "`null` when the workspace has unlimited quota." }, "is_recurring": { "type": "boolean" }, "recurring": { "type": "object", "description": "Present when a recurring series was created.", "properties": { "schedule_id": { "type": "string", "description": "The series id used by the `/recurring` endpoints." }, "interval": { "$ref": "#/components/schemas/RecurringInterval" }, "occurrences": { "type": "integer" }, "next_issue_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" } } }, "template": { "type": [ "object", "null" ], "description": "The template the invoice was made with (null when the plain built-in layout was used).", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "requested", "company_default", "system_default", "fallback" ] } } } } } } }, "InvoiceStatus": { "type": "string", "enum": [ "unpaid", "paid", "overdue", "cancelled" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_number": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": [ "string", "null" ], "format": "email" }, "currency": { "type": [ "string", "null" ] }, "subtotal": { "type": [ "number", "null" ] }, "discount_total": { "type": [ "number", "null" ] }, "tax_rate": { "type": [ "number", "null" ] }, "tax_amount": { "type": [ "number", "null" ] }, "amount": { "type": [ "number", "null" ], "description": "Total, in the invoice currency." }, "invoice_status": { "$ref": "#/components/schemas/InvoiceStatus" }, "is_archived": { "type": "boolean" }, "is_recurring": { "type": "boolean" }, "recurring_interval": { "type": "string", "enum": [ "none", "weekly", "fortnightly", "monthly", "quarterly", "semi-annually", "yearly" ] }, "issue_date": { "type": "string", "format": "date-time" }, "due_date": { "type": "string", "format": "date" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "pdf_url": { "type": [ "string", "null" ], "format": "uri" }, "pdf_status": { "type": "string", "enum": [ "idle", "processing", "ready", "failed" ] } }, "example": { "id": "cjld2cjxh0000qzrmn831i7rn", "invoice_number": "INV-1-202610-0007", "customer_name": "Acme Corp", "customer_email": "billing@acme.com", "currency": "USD", "subtotal": 500, "discount_total": 0, "tax_rate": 0, "tax_amount": 0, "amount": 500, "invoice_status": "paid", "is_archived": false, "is_recurring": false, "recurring_interval": "none", "issue_date": "2026-10-01T02:15:40.000Z", "due_date": "2026-10-15", "paid_at": "2026-10-01T09:30:11.000Z", "pdf_url": "https://cdn.invosend.com/company/1/pdf/Invoice_INV_1_202610_0007_PAID.pdf", "pdf_status": "ready" } }, "InvoiceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "invoice_number": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": [ "string", "null" ], "format": "email" }, "currency": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "invoice_status": { "$ref": "#/components/schemas/InvoiceStatus" }, "is_recurring": { "type": "boolean" }, "due_date": { "type": "string", "format": "date" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" } } }, "RecurringOccurrence": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "`pending` until it is generated, then `sent`; `failed` when generation failed (it is retried)." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "invoice_id": { "type": [ "string", "null" ], "description": "The invoice this occurrence produced, once generated." } } }, "RecurringSeries": { "type": "object", "properties": { "id": { "type": "string", "description": "Series id (`recurring.schedule_id` from the generate call)." }, "status": { "type": "string", "enum": [ "active", "paused", "completed", "draft" ] }, "paused_reason": { "type": [ "string", "null" ], "enum": [ "plan_ended", "plan_downgrade", null ], "description": "Set when the series was paused automatically because of the plan." }, "frequency": { "$ref": "#/components/schemas/RecurringInterval" }, "start_date": { "type": [ "string", "null" ], "format": "date-time" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_date": { "type": [ "string", "null" ], "format": "date-time" }, "last_run_date": { "type": [ "string", "null" ], "format": "date-time" }, "invoice_number": { "type": [ "string", "null" ], "description": "Number of the series template." }, "customer_name": { "type": [ "string", "null" ] }, "customer_email": { "type": [ "string", "null" ], "format": "email" }, "currency": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] }, "generated_count": { "type": "integer" }, "remaining_count": { "type": "integer" }, "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringOccurrence" }, "description": "Only in the single-series response." } }, "example": { "id": "qtajeroagcrw5nea7i093cv9", "status": "active", "paused_reason": null, "frequency": "weekly", "start_date": "2026-09-26T18:16:00.000Z", "end_date": "2026-10-17T18:16:00.000Z", "next_run_date": "2026-10-03T18:16:00.000Z", "last_run_date": null, "invoice_number": "SCH-1-202609-0001", "customer_name": "Acme Corp", "customer_email": "billing@acme.com", "currency": "USD", "amount": 50, "generated_count": 1, "remaining_count": 3, "occurrences": [ { "date": "2026-09-26T18:16:00.000Z", "due_date": "2026-10-02T00:00:00.000Z", "status": "sent", "sent_at": "2026-09-26T18:17:02.000Z", "invoice_id": "cjld2cjxh0000qzrmn831i7rn" }, { "date": "2026-10-03T18:16:00.000Z", "due_date": "2026-10-09T00:00:00.000Z", "status": "pending", "sent_at": null, "invoice_id": null } ] } }, "Error": { "type": "object", "properties": { "data": { "type": "null" }, "error": { "type": "object", "properties": { "status": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "message" ] } } }, "WebhookEvent": { "type": "object", "required": [ "id", "object", "type", "created", "data" ], "properties": { "id": { "type": "string", "description": "Unique per event. Use it to ignore duplicate deliveries.", "example": "evt_9f2c1b7a4e3d5c6b8a1f0e2d" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.paid", "invoice.overdue", "invoice.cancelled" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Invoice" }, "previous_status": { "type": "string", "description": "Only on status events (`paid`, `overdue`, `cancelled`)." } } } } } } } }