{ "openapi": "3.1.0", "info": { "title": "Convertavo Invoicing API", "version": "1.0.0", "description": "Create, issue and track invoices, quotes and credit notes; manage clients; record payments; download PDFs and EN 16931-aligned XML; get webhooks when things happen.\n\nAuthenticate with an API key from your dashboard: `Authorization: Bearer `. The invoicing API comes with paid plans. Issuing a document spends one credit, as on the website; requests a minute follow your plan.\n\nAmounts are sent as decimal strings in the document's currency (\"1250.50\") and returned twice: as decimal strings (`amounts`) and as integers in minor units (`amounts_minor`) — use the integers for arithmetic. The server works out every total; totals sent in a request are ignored.\n\nEvery POST, PATCH and DELETE accepts an `Idempotency-Key` header: the same key with the same body within 24 hours returns the first answer again (marked `Idempotent-Replayed: true`) instead of doing the work twice.\n\nLists use cursor pagination: pass `meta.next_cursor` back as `cursor`." }, "servers": [ { "url": "https://convertavo.com/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Invoices" }, { "name": "Clients" }, { "name": "Businesses" }, { "name": "Payments" }, { "name": "Structured data" } ], "paths": { "/businesses": { "get": { "operationId": "businesses", "summary": "List your businesses (the sellers you invoice as).", "tags": [ "Businesses" ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessList" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients": { "get": { "operationId": "clientsIndex", "summary": "List clients.", "tags": [ "Clients" ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 500 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientList" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "clientsStore", "summary": "Create a client.", "tags": [ "Clients" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "country": { "type": [ "string", "null" ], "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW", null ] }, "currency": { "type": [ "string", "null" ], "enum": [ "AED", "AFN", "ARS", "AUD", "BDT", "BGN", "BHD", "BIF", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "CZK", "DJF", "DKK", "DZD", "EGP", "EUR", "GBP", "GHS", "GNF", "HKD", "HUF", "IDR", "ILS", "INR", "IQD", "ISK", "JOD", "JPY", "KES", "KMF", "KRW", "KWD", "KZT", "LKR", "LYD", "MAD", "MXN", "MYR", "NGN", "NOK", "NPR", "NZD", "OMR", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RUB", "RWF", "SAR", "SEK", "SGD", "THB", "TND", "TRY", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "XAF", "XOF", "XPF", "ZAR", null ] }, "language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "archived": { "type": [ "boolean", "null" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/clients/{id}": { "get": { "operationId": "clientsShow", "summary": "Retrieve a client.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "clientsUpdate", "summary": "Update a client. Only the fields sent change; null clears a field; \"archived\" archives or restores.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "integer", "null" ] }, "name": { "type": "string", "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "country": { "type": [ "string", "null" ], "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW", null ] }, "currency": { "type": [ "string", "null" ], "enum": [ "AED", "AFN", "ARS", "AUD", "BDT", "BGN", "BHD", "BIF", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "CZK", "DJF", "DKK", "DZD", "EGP", "EUR", "GBP", "GHS", "GNF", "HKD", "HUF", "IDR", "ILS", "INR", "IQD", "ISK", "JOD", "JPY", "KES", "KMF", "KRW", "KWD", "KZT", "LKR", "LYD", "MAD", "MXN", "MYR", "NGN", "NOK", "NPR", "NZD", "OMR", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RUB", "RWF", "SAR", "SEK", "SGD", "THB", "TND", "TRY", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "XAF", "XOF", "XPF", "ZAR", null ] }, "language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "payment_terms_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "archived": { "type": [ "boolean", "null" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "clientsDestroy", "summary": "Delete a client that has no documents (archive one that has).", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "responses": { "204": { "description": "Done." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices": { "get": { "operationId": "index", "summary": "List documents, newest first.", "tags": [ "Invoices" ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ] } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "enum": [ "invoice", "credit_note", "proforma", "quote", "receipt", "delivery_note", null ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "enum": [ "draft", "issued", "sent", "partially_paid", "paid", "cancelled", "credited", "accepted", "declined", "converted", null ] } }, { "name": "issued_from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "issued_to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "maxLength": 500 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "store", "summary": "Create a draft — or issue it at once with \"issue\": true, and get its pdf_url back.", "tags": [ "Invoices" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "invoice", "credit_note", "proforma", "quote", "receipt", "delivery_note", null ] }, "currency": { "type": "string", "enum": [ "AED", "AFN", "ARS", "AUD", "BDT", "BGN", "BHD", "BIF", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "CZK", "DJF", "DKK", "DZD", "EGP", "EUR", "GBP", "GHS", "GNF", "HKD", "HUF", "IDR", "ILS", "INR", "IQD", "ISK", "JOD", "JPY", "KES", "KMF", "KRW", "KWD", "KZT", "LKR", "LYD", "MAD", "MXN", "MYR", "NGN", "NOK", "NPR", "NZD", "OMR", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RUB", "RWF", "SAR", "SEK", "SGD", "THB", "TND", "TRY", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "XAF", "XOF", "XPF", "ZAR" ] }, "language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "number": { "type": [ "string", "null" ], "maxLength": 64 }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "On or after issue_date." }, "supply_date": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ], "maxLength": 120 }, "po_number": { "type": [ "string", "null" ], "maxLength": 120 }, "project_name": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_mode": { "type": [ "string", "null" ], "enum": [ "exclusive", "inclusive", "none", null ] }, "rounding_scope": { "type": [ "string", "null" ], "enum": [ "per_line", "per_tax_group", null ] }, "rounding_mode": { "type": [ "string", "null" ], "enum": [ "half_up", "half_even", "half_down", null ] }, "withholding_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "cash_rounding": { "type": [ "string", "null" ], "enum": [ "none", "whole", "0.05", "0.10", null ] }, "discount": { "type": [ "object", "null" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "percent", "fixed", null ] }, "value": { "type": [ "string", "null" ], "maxLength": 24 } } }, "shipping": { "type": [ "object", "null" ], "properties": { "amount": { "type": [ "string", "null" ], "maxLength": 24 }, "tax_category": { "type": [ "string", "null" ], "enum": [ "standard", "reduced", "zero", "exempt", "reverse_charge", null ] }, "tax_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "in_discount_base": { "type": [ "boolean", "null" ] } } }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "item", "service", "time", "expense", "text_only", "subtotal_marker", null ] }, "description": { "type": "string", "maxLength": 500 }, "long_description": { "type": [ "string", "null" ], "maxLength": 2000 }, "item_code": { "type": [ "string", "null" ], "maxLength": 64 }, "hsn_sac_code": { "type": [ "string", "null" ], "maxLength": 16 }, "quantity": { "type": [ "string", "null" ], "maxLength": 24 }, "unit": { "type": [ "string", "null" ], "maxLength": 20 }, "unit_price": { "type": [ "string", "null" ], "maxLength": 24 }, "discount_type": { "type": [ "string", "null" ], "enum": [ "percent", "fixed", null ] }, "discount_value": { "type": [ "string", "null" ], "maxLength": 24 }, "tax_category": { "type": [ "string", "null" ], "enum": [ "standard", "reduced", "zero", "exempt", "reverse_charge", null ] }, "tax_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "source": { "type": [ "string", "null" ], "enum": [ "ocr", "file", null ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "description" ] } }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "terms": { "type": [ "string", "null" ], "maxLength": 2000 }, "footer": { "type": [ "string", "null" ], "maxLength": 500 }, "template": { "type": [ "string", "null" ], "enum": [ "classic", "modern", "minimal", "compact", "bold", "executive", "corporate", "elegant", "creative", "split", "ledger", "gradient", "clean", "receipt", "geometric", "mono", "boutique", null ] }, "page_size": { "type": [ "string", "null" ], "enum": [ "A4", "Letter", null ] }, "accent": { "type": [ "string", "null" ], "pattern": "^#[0-9A-Fa-f]{6}$" }, "logo": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "font": { "type": [ "string", "null" ], "enum": [ "inter", "noto_sans", "noto_serif", "space_grotesk", "ibm_plex", null ] }, "region": { "type": [ "string", "null" ], "enum": [ "none", "sa", "ae", "in", "pk", "eu", null ] }, "second_language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "place_of_supply": { "type": [ "string", "null" ], "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "26", "27", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "97", null ] }, "seller": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "website": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "secondary_tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "secondary_tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "bank_details": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "buyer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "website": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "secondary_tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "secondary_tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "bank_details": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "business_id": { "type": [ "integer", "null" ] }, "client_id": { "type": [ "integer", "null" ] }, "issue": { "type": [ "boolean", "null" ] } }, "required": [ "currency", "lines" ] }, "example": { "issue": true, "currency": "USD", "issue_date": "2026-10-20", "due_date": "2026-11-03", "buyer": { "name": "Northwind Studio", "email": "accounts@northwind.example" }, "lines": [ { "description": "Logo design", "quantity": "1", "unit_price": "450.00", "tax_rate": "0", "tax_category": "zero" }, { "description": "Brand guidelines (hours)", "quantity": "6", "unit_price": "65.00", "tax_rate": "0", "tax_category": "zero" } ], "notes": "Thank you for your business." } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}": { "get": { "operationId": "show", "summary": "Retrieve a document, with its lines and payments.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "update", "summary": "Replace a draft. Issued documents cannot change: issue a credit note.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "invoice", "credit_note", "proforma", "quote", "receipt", "delivery_note", null ] }, "currency": { "type": "string", "enum": [ "AED", "AFN", "ARS", "AUD", "BDT", "BGN", "BHD", "BIF", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "CZK", "DJF", "DKK", "DZD", "EGP", "EUR", "GBP", "GHS", "GNF", "HKD", "HUF", "IDR", "ILS", "INR", "IQD", "ISK", "JOD", "JPY", "KES", "KMF", "KRW", "KWD", "KZT", "LKR", "LYD", "MAD", "MXN", "MYR", "NGN", "NOK", "NPR", "NZD", "OMR", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RUB", "RWF", "SAR", "SEK", "SGD", "THB", "TND", "TRY", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VND", "VUV", "XAF", "XOF", "XPF", "ZAR" ] }, "language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "number": { "type": [ "string", "null" ], "maxLength": 64 }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date", "description": "On or after issue_date." }, "supply_date": { "type": [ "string", "null" ], "format": "date" }, "reference": { "type": [ "string", "null" ], "maxLength": 120 }, "po_number": { "type": [ "string", "null" ], "maxLength": 120 }, "project_name": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_mode": { "type": [ "string", "null" ], "enum": [ "exclusive", "inclusive", "none", null ] }, "rounding_scope": { "type": [ "string", "null" ], "enum": [ "per_line", "per_tax_group", null ] }, "rounding_mode": { "type": [ "string", "null" ], "enum": [ "half_up", "half_even", "half_down", null ] }, "withholding_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "cash_rounding": { "type": [ "string", "null" ], "enum": [ "none", "whole", "0.05", "0.10", null ] }, "discount": { "type": [ "object", "null" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "percent", "fixed", null ] }, "value": { "type": [ "string", "null" ], "maxLength": 24 } } }, "shipping": { "type": [ "object", "null" ], "properties": { "amount": { "type": [ "string", "null" ], "maxLength": 24 }, "tax_category": { "type": [ "string", "null" ], "enum": [ "standard", "reduced", "zero", "exempt", "reverse_charge", null ] }, "tax_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "in_discount_base": { "type": [ "boolean", "null" ] } } }, "lines": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "enum": [ "item", "service", "time", "expense", "text_only", "subtotal_marker", null ] }, "description": { "type": "string", "maxLength": 500 }, "long_description": { "type": [ "string", "null" ], "maxLength": 2000 }, "item_code": { "type": [ "string", "null" ], "maxLength": 64 }, "hsn_sac_code": { "type": [ "string", "null" ], "maxLength": 16 }, "quantity": { "type": [ "string", "null" ], "maxLength": 24 }, "unit": { "type": [ "string", "null" ], "maxLength": 20 }, "unit_price": { "type": [ "string", "null" ], "maxLength": 24 }, "discount_type": { "type": [ "string", "null" ], "enum": [ "percent", "fixed", null ] }, "discount_value": { "type": [ "string", "null" ], "maxLength": 24 }, "tax_category": { "type": [ "string", "null" ], "enum": [ "standard", "reduced", "zero", "exempt", "reverse_charge", null ] }, "tax_rate": { "type": [ "string", "null" ], "maxLength": 12 }, "source": { "type": [ "string", "null" ], "enum": [ "ocr", "file", null ] }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 } }, "required": [ "description" ] } }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 }, "terms": { "type": [ "string", "null" ], "maxLength": 2000 }, "footer": { "type": [ "string", "null" ], "maxLength": 500 }, "template": { "type": [ "string", "null" ], "enum": [ "classic", "modern", "minimal", "compact", "bold", "executive", "corporate", "elegant", "creative", "split", "ledger", "gradient", "clean", "receipt", "geometric", "mono", "boutique", null ] }, "page_size": { "type": [ "string", "null" ], "enum": [ "A4", "Letter", null ] }, "accent": { "type": [ "string", "null" ], "pattern": "^#[0-9A-Fa-f]{6}$" }, "logo": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "font": { "type": [ "string", "null" ], "enum": [ "inter", "noto_sans", "noto_serif", "space_grotesk", "ibm_plex", null ] }, "region": { "type": [ "string", "null" ], "enum": [ "none", "sa", "ae", "in", "pk", "eu", null ] }, "second_language": { "type": [ "string", "null" ], "enum": [ "en", "ur", "ar", "es", "fr", "de", "hi", "zh", "ru", "pt", "tr", "it", null ] }, "place_of_supply": { "type": [ "string", "null" ], "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "26", "27", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "97", null ] }, "seller": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "website": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "secondary_tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "secondary_tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "bank_details": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "buyer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 200 }, "legal_name": { "type": [ "string", "null" ], "maxLength": 200 }, "address": { "type": [ "string", "null" ], "maxLength": 600 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 }, "phone": { "type": [ "string", "null" ], "maxLength": 60 }, "website": { "type": [ "string", "null" ], "maxLength": 200 }, "tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "secondary_tax_number": { "type": [ "string", "null" ], "maxLength": 64 }, "secondary_tax_label": { "type": [ "string", "null" ], "maxLength": 40 }, "bank_details": { "type": [ "string", "null" ], "maxLength": 1000 } } }, "business_id": { "type": [ "integer", "null" ] }, "client_id": { "type": [ "integer", "null" ] }, "issue": { "type": [ "boolean", "null" ] } }, "required": [ "currency", "lines" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "destroy", "summary": "Delete a draft.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "responses": { "204": { "description": "Done." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/cancel": { "post": { "operationId": "cancel", "summary": "Cancel an issued document that has no payments or credits.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/issue": { "post": { "operationId": "issue", "summary": "Issue a draft: assigns the number and spends one credit. Calling it again returns the same document.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/payments": { "post": { "operationId": "payments", "summary": "Record a payment. An external_id records the same payment once, however often it is sent.", "tags": [ "Payments" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": [ "string", "null" ], "maxLength": 24, "description": "Required unless amount_minor is given." }, "amount_minor": { "type": [ "integer", "null" ], "minimum": 1, "description": "Required unless amount is given." }, "paid_on": { "type": [ "string", "null" ], "format": "date", "description": "On or before today." }, "method": { "type": [ "string", "null" ], "enum": [ "bank_transfer", "cash", "card", "cheque", "online", "other", null ] }, "reference": { "type": [ "string", "null" ], "maxLength": 120 }, "external_id": { "type": [ "string", "null" ], "maxLength": 100 } } } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/pdf": { "get": { "operationId": "pdf", "summary": "Download the PDF of an issued document.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The file.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/pdf-a3": { "get": { "operationId": "pdfa", "summary": "Download the PDF/A-3 copy with the CII XML embedded (EN 16931-aligned; invoices and credit notes).", "tags": [ "Structured data" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The file.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/send": { "post": { "operationId": "send", "summary": "Email the document to the client, with its PDF and a private link.", "tags": [ "Invoices" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Makes the call safe to repeat." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": [ "string", "null" ], "format": "email", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{uuid}/xml/{format}": { "get": { "operationId": "xml", "summary": "Download the document as UBL 2.1 or CII XML (EN 16931-aligned; invoices and credit notes).", "tags": [ "Structured data" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "ubl", "cii" ] } } ], "responses": { "200": { "description": "The file.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "invoice.issued": { "post": { "summary": "Sent to your endpoint on invoice.issued.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.issued" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.sent": { "post": { "summary": "Sent to your endpoint on invoice.sent.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.sent" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.viewed": { "post": { "summary": "Sent to your endpoint on invoice.viewed.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.viewed" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.reminder_sent": { "post": { "summary": "Sent to your endpoint on invoice.reminder_sent.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.reminder_sent" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.overdue": { "post": { "summary": "Sent to your endpoint on invoice.overdue.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.overdue" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.paid": { "post": { "summary": "Sent to your endpoint on invoice.paid.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.paid" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.cancelled": { "post": { "summary": "Sent to your endpoint on invoice.cancelled.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.cancelled" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "invoice.credited": { "post": { "summary": "Sent to your endpoint on invoice.credited.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "invoice.credited" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "payment.recorded": { "post": { "summary": "Sent to your endpoint on payment.recorded.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "payment.recorded" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "payment.refunded": { "post": { "summary": "Sent to your endpoint on payment.refunded.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "payment.refunded" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "quote.accepted": { "post": { "summary": "Sent to your endpoint on quote.accepted.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.accepted" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } }, "quote.declined": { "post": { "summary": "Sent to your endpoint on quote.declined.", "description": "Signed: the Convertavo-Signature header is \"t=,v1=.' with your signing secret>\". Recompute it, compare in constant time, and refuse times more than five minutes off. Convertavo-Delivery is the same on every retry of one delivery — use it to drop repeats. Answer 2xx within 10 seconds; anything else is retried for about nine hours.", "parameters": [ { "name": "Convertavo-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Convertavo-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "quote.declined" ] } }, { "name": "Convertavo-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx answer marks the delivery done." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your API key." } }, "schemas": { "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "business_id": { "type": "integer" }, "client_id": { "type": [ "integer", "null" ] }, "client_name": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "language": { "type": "string" }, "issue_date": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "po_number": { "type": [ "string", "null" ] }, "related_invoice_id": { "type": [ "string", "null" ] }, "amounts": { "type": "object", "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "shipping": { "type": "string" }, "tax": { "type": "string" }, "withholding": { "type": "string" }, "rounding": { "type": "string" }, "total": { "type": "string" }, "payable": { "type": "string" }, "paid": { "type": "string" }, "credited": { "type": "string" }, "balance": { "type": "string" } } }, "amounts_minor": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "discount": { "type": "integer" }, "shipping": { "type": "integer" }, "tax": { "type": "integer" }, "withholding": { "type": "integer" }, "rounding": { "type": "integer" }, "total": { "type": "integer" }, "payable": { "type": "integer" }, "paid": { "type": "integer" }, "credited": { "type": "integer" }, "balance": { "type": "integer" } } }, "issued_at": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "viewed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "pdf_url": { "type": [ "string", "null" ] }, "pdf_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "example": { "id": "0199a2b4-7a10-71d4-8c3b-1a2b3c4d5e6f", "object": "invoice", "type": "invoice", "status": "partially_paid", "number": "INV-2026-0042", "business_id": 12, "client_id": 34, "client_name": "Northwind Studio", "currency": "USD", "language": "en", "issue_date": "2026-10-20", "due_date": "2026-11-03", "reference": "Project Kite", "po_number": "PO-77", "related_invoice_id": "0199a2b4-5d00-7e2f-a1b2-c3d4e5f60718", "amounts": { "subtotal": "840.00", "discount": "0.00", "shipping": "0.00", "tax": "0.00", "withholding": "0.00", "rounding": "0.00", "total": "840.00", "payable": "840.00", "paid": "400.00", "credited": "0.00", "balance": "440.00" }, "amounts_minor": { "subtotal": 84000, "discount": 0, "shipping": 0, "tax": 0, "withholding": 0, "rounding": 0, "total": 84000, "payable": 84000, "paid": 40000, "credited": 0, "balance": 44000 }, "issued_at": "2026-10-20T09:05:00+00:00", "sent_at": "2026-10-20T09:06:00+00:00", "viewed_at": "2026-10-20T11:30:00+00:00", "paid_at": "2026-10-21T10:00:00+00:00", "cancelled_at": "2026-10-21T10:00:00+00:00", "pdf_url": "https://convertavo.com/api/v1/invoices/0199a2b4-7a10-71d4-8c3b-1a2b3c4d5e6f/pdf", "pdf_sha256": "abababababababababababababababababababababababababababababababab", "created_at": "2026-10-20T09:00:00+00:00", "updated_at": "2026-10-21T10:00:00+00:00" } }, "InvoiceFull": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "business_id": { "type": "integer" }, "client_id": { "type": [ "integer", "null" ] }, "client_name": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "language": { "type": "string" }, "issue_date": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "po_number": { "type": [ "string", "null" ] }, "related_invoice_id": { "type": [ "string", "null" ] }, "amounts": { "type": "object", "properties": { "subtotal": { "type": "string" }, "discount": { "type": "string" }, "shipping": { "type": "string" }, "tax": { "type": "string" }, "withholding": { "type": "string" }, "rounding": { "type": "string" }, "total": { "type": "string" }, "payable": { "type": "string" }, "paid": { "type": "string" }, "credited": { "type": "string" }, "balance": { "type": "string" } } }, "amounts_minor": { "type": "object", "properties": { "subtotal": { "type": "integer" }, "discount": { "type": "integer" }, "shipping": { "type": "integer" }, "tax": { "type": "integer" }, "withholding": { "type": "integer" }, "rounding": { "type": "integer" }, "total": { "type": "integer" }, "payable": { "type": "integer" }, "paid": { "type": "integer" }, "credited": { "type": "integer" }, "balance": { "type": "integer" } } }, "issued_at": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "viewed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "pdf_url": { "type": [ "string", "null" ] }, "pdf_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "lines": { "type": [ "object", "array" ], "items": { "type": "object", "properties": { "position": { "type": "integer" }, "type": { "type": "string" }, "description": { "type": "string" }, "item_code": { "type": [ "string", "null" ] }, "quantity": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "unit_price_minor": { "type": "integer" }, "tax_category": { "type": "string" }, "tax_rate_bp": { "type": "integer" }, "net_minor": { "type": "integer" }, "tax_minor": { "type": "integer" }, "total_minor": { "type": "integer" } } } }, "payments": { "type": [ "object", "array" ], "items": { "type": "object", "properties": { "id": { "type": "integer" }, "object": { "type": "string" }, "amount_minor": { "type": "integer" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paid_on": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": [ "string", "null" ] } } } }, "draft": { "type": [ "object", "null" ], "description": "A draft's own input, in the request's shape: read it, change it, send it back with PATCH." } } }, "InvoiceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceFull" } } }, "InvoiceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } } } } }, "Client": { "type": "object", "properties": { "id": { "type": "integer" }, "object": { "type": "string" }, "business_id": { "type": "integer" }, "name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "tax_number": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } } }, "ClientResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } }, "ClientList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "meta": { "type": "object", "properties": { "per_page": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] } } } } }, "Business": { "type": "object", "properties": { "id": { "type": "integer" }, "object": { "type": "string" }, "name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "tax_number": { "type": [ "string", "null" ] } } }, "BusinessList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Business" } } } }, "Payment": { "type": "object", "properties": { "id": { "type": "integer" }, "object": { "type": "string" }, "amount_minor": { "type": "integer" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paid_on": { "type": "string" }, "method": { "type": "string" }, "reference": { "type": "string" } } }, "PaymentResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The delivery id (also the Convertavo-Delivery header)." }, "type": { "type": "string", "enum": [ "invoice.issued", "invoice.sent", "invoice.viewed", "invoice.reminder_sent", "invoice.overdue", "invoice.paid", "invoice.cancelled", "invoice.credited", "payment.recorded", "payment.refunded", "quote.accepted", "quote.declined", "ping" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Invoice" }, "payment": { "$ref": "#/components/schemas/Payment", "description": "On payment.* events." } } } } }, "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ValidationError": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "responses": { "Error": { "description": "The request could not be carried out; the message says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Something in the request is wrong; errors are keyed by field path (e.g. lines.0.unit_price).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }