{ "openapi": "3.0.3", "info": { "title": "Piriod API", "version": "1.0.0", "description": "Piriod API for billing, payments, procurement and collections.\n\nAll requests require:\n- `Authorization: Token ` header.\n- `x-simple-workspace: ` header (the account/workspace identifier).\n- Optionally `x-piriod-test-mode: true` to operate against test-mode data.\n\nSee the Documentation tab for getting started, integration flows, authentication,\nerror handling and pagination/filtering guides.\n" }, "servers": [ { "url": "https://api.piriod.com", "description": "Production" } ], "security": [ { "TokenAuth": [] } ], "components": { "securitySchemes": { "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use header `Authorization: Token `.\nAPI tokens are obtained from the Piriod dashboard.\n" } }, "parameters": { "WorkspaceHeader": { "name": "x-simple-workspace", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Workspace (account) identifier. Required for every request.", "example": "acc_01H8XYZ123ABC" }, "TestModeHeader": { "name": "x-piriod-test-mode", "in": "header", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to operate against test-mode data. Defaults to `false`." }, "PageQuery": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number to retrieve (1-indexed)." }, "PageSizeQuery": { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page." }, "OrderingQuery": { "name": "ordering", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Field to sort results by. Prefix with `-` for descending order\n(e.g. `-created`).\n" }, "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier." }, "SearchQuery": { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across configured searchable fields." } }, "schemas": { "Paginated": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "description": "Total number of items matching the filter.", "example": 142 }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the next page, or `null` if last page." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the previous page, or `null` if first page." }, "results": { "type": "array", "items": {}, "description": "The items in the current page." } } }, "Error": { "type": "object", "properties": { "detail": { "type": "string", "description": "Human-readable error message." } }, "example": { "detail": "Authentication credentials were not provided." } }, "ValidationError": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field-keyed error map. The special key `non_field_errors` carries\nerrors that are not bound to a specific field.\n", "example": { "name": [ "This field is required." ], "non_field_errors": [ "x-simple-workspace header is required." ] } }, "Country": { "type": "object", "properties": { "id": { "type": "string", "example": "CL" }, "name": { "type": "string", "example": "Chile" }, "code": { "type": "string", "example": "+56" }, "has_regulation": { "type": "boolean" }, "currencies": { "type": "array", "items": { "type": "string", "example": "CLP" } } } }, "State": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "country": { "type": "string", "example": "CL" } } }, "Aggregations": { "type": "object", "properties": { "sales": { "type": "number", "format": "decimal", "description": "Total finalized + paid sales for the customer." }, "sales_current_period": { "type": "number", "format": "decimal", "description": "Sales finalized within the current calendar month." }, "balance": { "type": "number", "format": "decimal", "description": "Outstanding balance across non-succeeded payments on finalized/pending invoices." } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "con_01H8XYZ123ABC" }, "customer": { "type": "string", "nullable": true, "description": "Customer ID this contact belongs to." }, "orgunit": { "type": "string", "nullable": true, "description": "Organisation unit ID. Optional sub-grouping inside a customer." }, "name": { "type": "string", "maxLength": 64 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 12, "nullable": true }, "invoicing": { "type": "boolean", "default": true, "description": "Whether this contact receives invoice emails." }, "collections": { "type": "boolean", "default": true, "description": "Whether this contact receives collection reminders." }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "email" ] }, "ContactWrite": { "type": "object", "properties": { "customer": { "type": "string", "nullable": true }, "orgunit": { "type": "string", "nullable": true }, "name": { "type": "string", "maxLength": 64 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 12, "nullable": true }, "invoicing": { "type": "boolean", "default": true }, "collections": { "type": "boolean", "default": true } }, "required": [ "name", "email" ] }, "CreditNoteLine": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 512, "nullable": true }, "amount": { "type": "number" }, "quantity": { "type": "number" }, "exempt": { "type": "boolean" }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "number", "readOnly": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "code": { "type": "string", "maxLength": 32, "nullable": true }, "code_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "retention": { "type": "number", "nullable": true }, "retention_percent": { "type": "number", "default": 0 }, "retention_scheme": { "type": "string", "enum": [ "subtotal", "tax" ], "default": "subtotal" } }, "required": [ "name", "amount", "quantity", "exempt" ] }, "CreditNote": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "invoice": { "type": "string", "description": "Invoice ID this credit note adjusts." }, "document": { "type": "integer", "nullable": true, "description": "Credit-note document type. Optional; the biller may assign one at finalize." }, "number": { "type": "integer", "readOnly": true }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "maxLength": 64, "nullable": true }, "internal_note": { "type": "string", "maxLength": 1024, "nullable": true }, "amount": { "type": "number", "nullable": true }, "exempt": { "type": "number", "nullable": true }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "subtotal": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "retention": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "status": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteLine" } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "invoice", "date" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "cus_01H8XYZ123ABC" }, "name": { "type": "string", "maxLength": 100 }, "address": { "type": "string", "maxLength": 64 }, "country": { "$ref": "#/components/schemas/Country" }, "state": { "$ref": "#/components/schemas/State" }, "currency": { "type": "string", "description": "ISO currency code (e.g. CLP, USD).", "example": "CLP" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true, "maxLength": 16 }, "website": { "type": "string", "format": "uri", "nullable": true }, "zip_code": { "type": "string", "nullable": true, "maxLength": 16 }, "manager": { "type": "string", "nullable": true, "maxLength": 64, "description": "Account manager name (free text)." }, "reference": { "type": "string", "nullable": true, "maxLength": 64, "description": "External reference for the customer." }, "tax_id": { "type": "string", "nullable": true, "maxLength": 32, "description": "Tax identifier. Required when the customer's country has tax regulation\n(e.g. Chile RUT, Mexico RFC, Colombia NIT) and matches the account's country.\n" }, "tax_settings": { "type": "object", "description": "Country-specific tax configuration. Schema and required keys depend on the\ntax agency of the customer's country.\n" }, "metadata": { "type": "object", "description": "Arbitrary key/value metadata. Filterable via `?metadata__key=value`." }, "send_invoices": { "type": "boolean", "default": true, "description": "Whether to email invoices to the customer." }, "send_collections": { "type": "boolean", "default": true, "description": "Whether to email collection reminders to the customer." }, "send_vouchers": { "type": "boolean", "default": true, "description": "Whether to email payment receipts to the customer." }, "status": { "type": "string", "enum": [ "active", "archived", "pending" ], "default": "active" }, "contacts": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/Contact" } }, "sources": { "type": "array", "readOnly": true, "items": { "type": "string" }, "description": "IDs of reusable payment sources currently chargeable or pending." }, "aggregations": { "allOf": [ { "$ref": "#/components/schemas/Aggregations" } ], "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "address", "country", "state" ] }, "CustomerWrite": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "address": { "type": "string", "maxLength": 64 }, "country": { "type": "string", "description": "Country ID (e.g. `CL`, `MX`, `CO`)." }, "state": { "type": "integer", "description": "State ID. Must belong to the chosen country." }, "currency": { "type": "string", "description": "ISO currency code. Defaults from the country if omitted." }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "maxLength": 16, "nullable": true }, "website": { "type": "string", "format": "uri", "nullable": true }, "zip_code": { "type": "string", "maxLength": 16, "nullable": true }, "manager": { "type": "string", "maxLength": 64, "nullable": true }, "reference": { "type": "string", "maxLength": 64, "nullable": true }, "tax_id": { "type": "string", "maxLength": 32, "nullable": true }, "tax_settings": { "type": "object" }, "metadata": { "type": "object" }, "send_invoices": { "type": "boolean", "default": true }, "send_collections": { "type": "boolean", "default": true }, "send_vouchers": { "type": "boolean", "default": true } }, "required": [ "name", "address", "country", "state" ] }, "CustomerStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "archived", "pending" ] }, "sales": { "type": "number", "format": "decimal" }, "sales_current_period": { "type": "number", "format": "decimal" }, "balance": { "type": "number", "format": "decimal" }, "has_valuable_sources": { "type": "boolean", "description": "True if the customer has reusable sources that should be preserved on archive." }, "has_archivable_abandoned_sources": { "type": "boolean", "description": "True if the customer has abandoned reusable sources linked to payments." } } }, "DebitNote": { "type": "object", "description": "Debit notes adjust a previously issued credit note (raising the amount\nagain). They mirror the credit note's line structure and totals.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "credit_note": { "type": "integer", "description": "Credit-note ID this debit note adjusts." }, "document": { "type": "integer", "description": "Debit-note document type." }, "number": { "type": "integer", "readOnly": true }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "maxLength": 64, "nullable": true }, "internal_note": { "type": "string", "maxLength": 1024, "nullable": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "credit_note", "document", "date" ] }, "InvoiceLine": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 512, "nullable": true }, "amount": { "type": "number", "description": "Unit price." }, "quantity": { "type": "number" }, "total": { "type": "number", "readOnly": true }, "exempt": { "type": "boolean", "default": false }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "code": { "type": "string", "maxLength": 32, "nullable": true }, "code_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "plan": { "type": "integer", "nullable": true, "description": "Linked plan ID when this line bills a subscription plan." }, "retention": { "type": "number", "nullable": true }, "retention_percent": { "type": "number", "default": 0 }, "retention_scheme": { "type": "string", "enum": [ "subtotal", "tax" ], "default": "subtotal" }, "unit_label": { "type": "string", "maxLength": 4, "nullable": true } }, "required": [ "name", "amount", "quantity" ] }, "InvoiceReference": { "type": "object", "description": "Reference to another fiscal document (typically used for credit notes,\ndebit notes or modifying documents).\n", "properties": { "date": { "type": "string", "format": "date" }, "document": { "type": "string", "description": "Document reference type (country-specific)." }, "description": { "type": "string", "maxLength": 64, "nullable": true }, "serial": { "type": "string", "maxLength": 32 } }, "required": [ "date", "document", "serial" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "inv_01H8XYZ123ABC" }, "customer": { "type": "string", "description": "Customer ID." }, "document": { "type": "integer", "description": "Document type ID (fiscal document; depends on country)." }, "number": { "type": "integer", "readOnly": true, "description": "Sequence number assigned at finalize time." }, "currency": { "type": "string", "readOnly": true, "description": "Currency code from the customer's currency." }, "date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "period_start": { "type": "string", "format": "date", "nullable": true }, "period_end": { "type": "string", "format": "date", "nullable": true }, "collection_method": { "type": "string", "enum": [ "deferred", "deferred_dues", "automatically" ] }, "note": { "type": "string", "maxLength": 256, "nullable": true }, "amount": { "type": "number", "nullable": true, "description": "Subtotal of taxable lines (computed)." }, "exempt": { "type": "number", "nullable": true, "description": "Subtotal of tax-exempt lines (computed)." }, "tax": { "type": "number", "nullable": true, "description": "Total tax (computed)." }, "tax_percent": { "type": "number", "nullable": true }, "subtotal": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true, "description": "Final amount (computed)." }, "total_adjusted": { "type": "number", "readOnly": true, "nullable": true }, "retention": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "custom_change": { "type": "number", "nullable": true, "minimum": 1, "description": "Custom currency conversion factor." }, "status": { "type": "string", "enum": [ "draft", "finalized", "paid", "cancelled", "uncollectible", "pending" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true, "enum": [ "pending", "queued", "succeeded", "failed", "processing" ] }, "tax_agency": { "type": "object", "readOnly": true, "description": "Tax-agency response payload (country-specific)." }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true, "description": "Signed URL to the fiscal PDF/XML when applicable." }, "subscription": { "type": "integer", "nullable": true, "description": "Linked subscription ID when generated by a subscription cycle." }, "imported": { "type": "boolean", "readOnly": true }, "uncollectible": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLine" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceReference" } }, "payments": { "type": "array", "readOnly": true, "items": { "type": "object", "description": "Linked payment objects (see Payments section)." } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "document", "date", "collection_method", "lines" ] }, "InvoiceFilter": { "type": "object", "description": "Stub schema (not used directly)." }, "Orgunit": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID this org unit belongs to." }, "name": { "type": "string", "maxLength": 64 }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "name" ] }, "OrgunitWrite": { "type": "object", "properties": { "customer": { "type": "string" }, "name": { "type": "string", "maxLength": 64 } }, "required": [ "customer", "name" ] }, "PaymentReceipt": { "type": "object", "description": "A fiscal payment receipt (e.g. Mexican REP / \"complemento de pago\"). It\ngroups one or more payment sources that completed payment of an invoice.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "sources": { "type": "array", "description": "IDs of payment sources covered by this receipt. All sources must\nbelong to invoices for the same customer and document type, and\ncannot already have a payment receipt.\n", "items": { "type": "string" } }, "document": { "type": "string", "enum": [ "MX22" ], "readOnly": true, "nullable": true, "description": "Fiscal document type (set automatically by the biller)." }, "number": { "type": "integer", "readOnly": true }, "date": { "type": "string", "format": "date", "nullable": true }, "custom_change": { "type": "number", "minimum": 1, "nullable": true, "description": "Custom currency conversion factor." }, "metadata": { "type": "object" }, "tax_settings": { "type": "object", "description": "Country-specific tax-agency settings (validated at create/update)." }, "status": { "type": "string", "enum": [ "draft", "finalized" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "sources" ] }, "Frequency": { "type": "object", "description": "Built-in billing frequencies (daily, monthly, yearly).", "properties": { "id": { "type": "string", "example": "monthly" }, "name": { "type": "string" }, "scheme": { "type": "string", "enum": [ "D", "M", "Y" ] }, "quantity": { "type": "integer", "default": 1 } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "unit_label": { "type": "string", "maxLength": 12 }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "plans": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/Plan" } }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "unit_label" ] }, "PlanTier": { "type": "object", "properties": { "amount": { "type": "number" }, "amount_scheme": { "type": "string", "enum": [ "flat", "per_unit" ], "default": "flat" }, "quantity_from": { "type": "integer" }, "quantity_to": { "type": "integer", "nullable": true }, "unit_scheme": { "type": "string", "enum": [ "all_units", "tier_units", "overage" ], "nullable": true } }, "required": [ "amount", "quantity_from" ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "product": { "type": "string", "description": "Product ID." }, "sku": { "type": "string", "maxLength": 32, "nullable": true }, "name": { "type": "string", "maxLength": 56 }, "description": { "type": "string", "maxLength": 200 }, "frequency": { "type": "string", "description": "Frequency ID (e.g. `monthly`)." }, "currency": { "type": "string", "description": "ISO currency code." }, "amount": { "type": "number" }, "exempt": { "type": "boolean", "default": false }, "usage_scheme": { "type": "string", "enum": [ "licensed", "metered" ], "default": "licensed" }, "usage_aggregation": { "type": "string", "enum": [ "last_record", "max", "sum" ], "nullable": true }, "tiers_mode": { "type": "string", "enum": [ "package", "volume", "graduated", "package_overage", "unit", "range" ], "nullable": true, "description": "Pricing mode for tiered plans. `unit` and `range` are deprecated\naliases of `volume` and `package` respectively.\n" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/PlanTier" } }, "unit_label": { "type": "string", "maxLength": 4, "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "product", "name", "description", "frequency", "currency", "amount" ] }, "PlanUpdate": { "type": "object", "description": "Schema for `PATCH/PUT /plans/{id}/` (only mutable fields).", "properties": { "name": { "type": "string", "maxLength": 56 }, "description": { "type": "string", "maxLength": 200 }, "sku": { "type": "string", "maxLength": 32, "nullable": true }, "unit_label": { "type": "string", "maxLength": 4, "nullable": true }, "metadata": { "type": "object" } } }, "Addon": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "maxLength": 56 }, "description": { "type": "string", "maxLength": 256 }, "sku": { "type": "string", "maxLength": 32, "nullable": true }, "currency": { "type": "string" }, "amount": { "type": "number" }, "apply_scheme": { "type": "string", "enum": [ "one_time", "recurring" ], "default": "one_time" }, "duration_times": { "type": "integer", "nullable": true }, "unit_label": { "type": "string", "maxLength": 4, "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "description", "currency", "amount" ] }, "Coupon": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string", "maxLength": 56 }, "amount": { "type": "number" }, "currency": { "type": "string" }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "default": "%" }, "duration_scheme": { "type": "string", "enum": [ "one_time", "forever", "limited" ], "default": "one_time" }, "duration_times": { "type": "integer", "nullable": true, "description": "Required when `duration_scheme=limited`. Number of billing cycles." }, "valid_until": { "type": "string", "format": "date", "nullable": true }, "apply_on": { "type": "string", "enum": [ "line", "invoice" ], "default": "invoice" }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "amount", "currency" ] }, "SubscriptionLine": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "plan": { "type": "string", "description": "Plan ID. Read responses include the full plan inline." }, "quantity": { "type": "integer", "minimum": 1 }, "coupon": { "type": "string", "nullable": true, "description": "Coupon ID applied to this line." }, "coupon_redemptions": { "type": "integer", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "plan", "quantity" ] }, "SubscriptionAddonRate": { "type": "object", "properties": { "billing_cycle": { "type": "integer", "description": "Billing cycle this rate applies to." }, "percentage": { "type": "number", "description": "Discount/markup percentage applied to the addon for the cycle." }, "description": { "type": "string", "nullable": true } } }, "SubscriptionAddon": { "type": "object", "properties": { "addon": { "type": "string", "description": "Addon ID." }, "quantity": { "type": "integer", "minimum": 1 }, "addon_redemptions": { "type": "integer", "readOnly": true }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAddonRate" } } } }, "SubscriptionReference": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "date_end": { "type": "string", "format": "date", "nullable": true }, "document": { "type": "string", "description": "Document reference type." }, "description": { "type": "string", "nullable": true }, "serial": { "type": "string" } }, "required": [ "date", "document", "serial" ] }, "SubscriptionEvent": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancelled", "created", "needs_attention", "paused", "reactivated", "updated" ] }, "user": { "type": "integer", "nullable": true }, "details": { "type": "object" }, "created": { "type": "string", "format": "date-time" } } }, "Subscription": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID." }, "document": { "type": "integer", "description": "Document type ID used to issue invoices." }, "date_start": { "type": "string", "format": "date" }, "next_billing": { "type": "string", "format": "date" }, "previous_billing": { "type": "string", "format": "date", "nullable": true }, "billing_cycles": { "type": "integer", "nullable": true, "description": "Total cycles or null for indefinite." }, "next_billing_cycle": { "type": "integer", "default": 1, "readOnly": true }, "expiration_days": { "type": "integer", "default": 10, "description": "Days until invoices generated by this subscription expire." }, "collection_scheme": { "type": "string", "enum": [ "send_invoice", "charge_payment" ], "default": "send_invoice" }, "default_source": { "type": "string", "nullable": true, "description": "Default payment source ID. Required when `collection_scheme=charge_payment`." }, "custom_change": { "type": "number", "minimum": 1, "nullable": true, "description": "Custom currency conversion factor for issued invoices." }, "coupon": { "type": "string", "nullable": true, "description": "Coupon ID applied at the subscription (invoice-level) scope." }, "coupon_redemptions": { "type": "integer", "readOnly": true }, "require_reference": { "type": "boolean", "default": false }, "note": { "type": "string", "maxLength": 100, "nullable": true }, "orgunit": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "cancelled", "finalized", "needs_attention" ], "readOnly": true }, "status_description": { "type": "string", "maxLength": 512, "nullable": true }, "needs_attention": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "needs_attention_reason": { "type": "string", "enum": [ "biller_issue", "gateway_issue", "reference_expired", "without_usage_records", "processing_issue", "without_reference" ], "nullable": true, "readOnly": true }, "cancel_reason": { "type": "string", "enum": [ "custom", "fraud_review_failed", "insolvency", "no_card", "non_compliant_customer", "not_paid", "not_specified", "shutdown_ops" ], "nullable": true, "readOnly": true }, "cancelled": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "paused": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "paused_reason": { "type": "string", "enum": [ "not_specified", "non_compliant_customer", "custom" ], "nullable": true, "readOnly": true }, "pause_until": { "type": "string", "format": "date", "nullable": true, "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionLine" } }, "addons": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAddon" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionReference" } }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "document", "date_start", "next_billing", "lines" ] }, "SubscriptionPause": { "type": "object", "description": "Body for `POST /subscriptions/{id}/pause/`.", "properties": { "paused_reason": { "type": "string", "enum": [ "not_specified", "non_compliant_customer", "custom" ] }, "pause_until": { "type": "string", "format": "date", "nullable": true } }, "required": [ "paused_reason" ] }, "SubscriptionResume": { "type": "object", "description": "Body for `POST /subscriptions/{id}/resume/`.", "properties": { "next_billing": { "type": "string", "format": "date" } } }, "SupportingDocumentRule": { "type": "object", "description": "Rule that controls when supporting documents (e.g. purchase orders) are\nautomatically requested for a customer's subscriptions.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID. One rule per customer." }, "auto_request": { "type": "boolean", "default": false }, "days_before": { "type": "integer", "default": 15, "description": "Days before the next billing date to send the request." }, "use_document": { "type": "boolean", "default": false }, "use_hes": { "type": "boolean", "default": false } }, "required": [ "customer" ] }, "SubmissionRequest": { "type": "object", "description": "Request sent to a customer asking for required documentation (purchase\norder, HES) before billing can proceed.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID." }, "submission_type": { "type": "string", "enum": [ "order", "hes" ], "description": "`order` = Purchase Order. `hes` = Service Entry Sheet." }, "status": { "type": "string", "enum": [ "pending", "sent", "overdue", "fulfilled", "cancelled" ], "default": "pending" }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 8 }, "subscriptions": { "type": "array", "items": { "type": "string" }, "description": "IDs of subscriptions this request is tied to. Must belong to the customer." }, "due_date": { "type": "string", "format": "date", "nullable": true }, "is_automatic": { "type": "boolean", "default": false }, "billing_cycle": { "type": "integer", "nullable": true }, "email_subject": { "type": "string", "maxLength": 255 }, "email_message": { "type": "string" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "fulfilled_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "submission_type" ] }, "SupportingDocument": { "type": "object", "description": "A supporting document submitted by a customer (purchase order or\ncontract). Documents are linked to subscriptions and consumed by\ninvoices over time.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID." }, "document_type": { "type": "string", "enum": [ "801", "802" ], "description": "`801` = Purchase Order. `802` = Contract." }, "serial": { "type": "string", "maxLength": 32 }, "description": { "type": "string", "maxLength": 64, "nullable": true }, "date_issued": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date" }, "file": { "type": "string", "format": "binary", "description": "PDF/image file uploaded as multipart on create." }, "subscriptions": { "type": "array", "items": { "type": "string" } }, "submission_request": { "type": "integer", "nullable": true, "description": "Linked submission request (when delivered as response to one)." }, "used": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "active", "consumed", "expired", "archived" ], "default": "active" }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "document_type", "serial", "date_issued", "valid_until", "file" ] }, "ServiceEntry": { "type": "object", "description": "Service Entry Sheet (HES) associated with a purchase order. Required by\nsome customers before an invoice can be issued for a billing cycle.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "supporting_document": { "type": "integer", "description": "Supporting-document ID (the parent purchase order)." }, "subscription": { "type": "string", "description": "Subscription ID." }, "invoice": { "type": "string", "nullable": true }, "number": { "type": "string", "maxLength": 50 }, "date_issued": { "type": "string", "format": "date" }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "supporting_document", "subscription", "number", "date_issued" ] }, "SupportingDocumentBoard": { "type": "object", "description": "Kanban board grouping submission requests and supporting documents by\nstatus. Each key is a status column.\n", "additionalProperties": { "type": "array", "items": { "type": "object", "description": "A board card (either a submission request or a supporting document)." } } }, "Usage": { "type": "object", "description": "A usage record posted against a metered subscription line. The line's\nplan must have `usage_scheme=metered`.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "subscription_line": { "type": "integer", "description": "Subscription line ID this usage belongs to." }, "date_time": { "type": "string", "format": "date-time", "description": "Timestamp the usage was recorded for." }, "quantity": { "type": "number" }, "creation_scheme": { "type": "string", "enum": [ "api", "file", "panel" ], "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "subscription_line", "date_time", "quantity" ] }, "Intent": { "type": "object", "description": "Operational intent surfaced when a subscription needs attention (e.g.\ngateway issue, missing reference). Read-only for integrators.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "subscription": { "type": "string", "description": "Subscription ID." }, "description": { "type": "string", "maxLength": 512 }, "needs_attention_reason": { "type": "string", "enum": [ "biller_issue", "gateway_issue", "reference_expired", "without_usage_records", "processing_issue", "without_reference" ] }, "created": { "type": "string", "format": "date-time", "readOnly": true } } }, "AchTransfer": { "type": "object", "description": "A bank movement (incoming/outgoing transfer) reconciled against\ninvoices via payment sources.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "bank": { "type": "string", "description": "Bank account ID." }, "amount": { "type": "number" }, "balance": { "type": "number", "readOnly": true, "description": "Remaining unallocated balance." }, "currency": { "type": "string" }, "date": { "type": "string", "format": "date-time", "nullable": true }, "description": { "type": "string", "maxLength": 256 }, "comment": { "type": "string", "maxLength": 256, "nullable": true }, "number": { "type": "string", "maxLength": 256, "nullable": true }, "transfer_type": { "type": "string", "maxLength": 256, "nullable": true }, "auto_match": { "type": "boolean", "default": false }, "origin_bank": { "type": "integer", "nullable": true }, "origin_id": { "type": "string", "maxLength": 256, "nullable": true }, "origin_holder_id": { "type": "string", "maxLength": 256, "nullable": true }, "origin_holder_name": { "type": "string", "maxLength": 256, "nullable": true }, "origin_number": { "type": "string", "maxLength": 256, "nullable": true }, "status": { "type": "string", "enum": [ "archived", "finalized", "incomplete", "pending" ], "default": "pending" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "bank", "amount", "currency", "description" ] }, "AchAdjustment": { "type": "object", "description": "Manual adjustment applied to an ACH transfer (e.g. to balance fees).", "properties": { "id": { "type": "integer", "readOnly": true }, "transfer": { "type": "integer", "description": "ACH transfer ID." }, "amount": { "type": "number" }, "operation": { "type": "string", "enum": [ "add", "sub", "exchange" ] }, "currency": { "type": "string", "nullable": true }, "base_amount": { "type": "number", "nullable": true }, "base_currency": { "type": "string", "nullable": true }, "comment": { "type": "string", "maxLength": 256, "nullable": true }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "transfer", "amount", "operation" ] }, "Bank": { "type": "object", "description": "Workspace-level bank account configured for receiving payments.", "properties": { "id": { "type": "string", "readOnly": true }, "bank": { "type": "integer", "description": "Reference to the underlying bank entity (`/generals/banks/`)." }, "name": { "type": "string", "maxLength": 64, "nullable": true }, "number": { "type": "string", "maxLength": 24, "nullable": true }, "holder_id": { "type": "string", "maxLength": 32, "nullable": true }, "holder_name": { "type": "string", "maxLength": 64, "nullable": true }, "account_type": { "type": "string", "enum": [ "checking_account", "savings_account", "sight_account", "rut_account", "line_of_credit" ], "nullable": true }, "auto_match": { "type": "boolean", "default": false }, "extra_data": { "type": "object" }, "last_sync": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "active", "authentication_failed", "unknown_error", "archived" ], "default": "active" }, "archived": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "bank" ] }, "BankSync": { "type": "object", "description": "Body for `POST /banks/{id}/sync/`.", "properties": { "from_date": { "type": "string", "format": "date" }, "to_date": { "type": "string", "format": "date" } } }, "Boleto": { "type": "object", "description": "Brazilian boleto bancário associated to a payment. Stores the bar code,\nbill ID and a PDF artifact.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "payment": { "type": "integer", "description": "Payment ID." }, "bill_id": { "type": "string", "maxLength": 128 }, "barcode": { "type": "string" }, "qr_code": { "type": "string" }, "pdf": { "type": "string", "format": "uri", "nullable": true, "description": "Signed URL to the rendered boleto PDF." }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "payment", "bill_id", "barcode", "qr_code" ] }, "PaymentLink": { "type": "object", "description": "Sharable payment link rendered by Piriod (`/publishable/payment_links/links/{publishable_key}/hosted/`).\n", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 56 }, "publishable_key": { "type": "string", "readOnly": true, "description": "Use this key on the publishable endpoints to fetch and pay the link." }, "cta": { "type": "string", "enum": [ "book", "donate", "pay" ], "default": "pay" }, "amount": { "type": "number", "nullable": true }, "amount_min": { "type": "number", "nullable": true }, "amount_max": { "type": "number", "nullable": true }, "amount_preset": { "type": "number", "nullable": true }, "amount_scheme": { "type": "string", "enum": [ "custom", "fixed" ], "default": "fixed" }, "currency": { "type": "string", "description": "ISO currency code." }, "customer_type": { "type": "string", "enum": [ "individual", "business", "both" ], "default": "both" }, "description": { "type": "string", "nullable": true }, "end_description": { "type": "string", "nullable": true, "description": "Markdown shown after a successful payment." }, "hosted_page_title": { "type": "string", "maxLength": 32, "nullable": true }, "hosted_page_description": { "type": "string", "nullable": true }, "hosted_page_layout": { "type": "string", "enum": [ "vertical", "horizontal" ], "default": "vertical" }, "image": { "type": "string", "format": "uri", "nullable": true }, "return_url": { "type": "string", "format": "uri", "nullable": true }, "create_invoice": { "type": "boolean", "default": false, "description": "When true, completed payments generate an invoice with `document`." }, "document": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "active", "archived" ], "default": "active" }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "currency" ] }, "PaymentLinkPublic": { "allOf": [ { "$ref": "#/components/schemas/PaymentLink" } ], "description": "Read-only view returned by publishable endpoints (no internal-only fields)." }, "PaymentLinkHosted": { "type": "object", "description": "Hosted-page payload used by Piriod's checkout UI.", "properties": { "link": { "$ref": "#/components/schemas/PaymentLinkPublic" }, "providers": { "type": "array", "items": { "type": "object" } }, "exchange": { "type": "number", "nullable": true, "description": "Exchange rate to the account currency, when applicable." } } }, "PaymentIntent": { "type": "object", "description": "Customer's intent to pay against a `PaymentLink`. Drives the checkout\nflow (authorize → capture → finalize).\n", "properties": { "publishable_key": { "type": "string", "readOnly": true }, "amount": { "type": "number" }, "gateway": { "type": "string", "description": "Gateway ID." }, "link": { "type": "integer", "description": "Payment-link ID." }, "customer": { "type": "object", "description": "Free-form customer data captured during checkout." }, "metadata": { "type": "object" }, "return_url": { "type": "string", "format": "uri", "nullable": true }, "authorization_url": { "type": "string", "format": "uri", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "failed", "pending", "succeeded" ], "readOnly": true }, "status_description": { "type": "string", "nullable": true, "readOnly": true }, "status_reason": { "type": "string", "nullable": true, "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "amount", "gateway", "link" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "invoice": { "type": "string", "nullable": true, "description": "Invoice ID this payment applies to." }, "subscription": { "type": "string", "nullable": true, "description": "Subscription ID when generated by a subscription cycle." }, "customer": { "type": "string", "nullable": true }, "amount": { "type": "number" }, "balance": { "type": "number", "readOnly": true, "description": "Remaining balance to charge against this payment." }, "currency": { "type": "string", "description": "ISO currency code." }, "date": { "type": "string", "format": "date" }, "payment_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Effective date the payment was completed." }, "description": { "type": "string", "maxLength": 256 }, "source": { "type": "integer", "nullable": true, "description": "Primary source ID. (Legacy single source link.)" }, "sources": { "type": "array", "items": { "type": "integer" }, "description": "All source IDs linked to this payment (multi-source support)." }, "status": { "type": "string", "enum": [ "cancelled", "failed", "incomplete", "processing", "requires_payment_method", "succeeded" ], "default": "requires_payment_method" }, "failed_reason": { "type": "string", "nullable": true, "readOnly": true, "description": "Reason code when `status=failed`." }, "return_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL the payer is sent back to after a redirect-flow checkout." }, "enable_checkout": { "type": "boolean", "default": true, "description": "Whether the publishable checkout `/pay/` is reachable for this payment." }, "metadata": { "type": "object" }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "amount", "currency", "date", "description" ] }, "PaymentAuthorize": { "type": "object", "description": "Body for `POST /payments/{id}/authorize/`.", "properties": { "source": { "type": "integer", "description": "Source ID to authorize this payment against." } }, "required": [ "source" ] }, "PaymentCapture": { "type": "object", "description": "Body for `POST /payments/{id}/capture/`.", "properties": { "gateway_data": { "type": "object", "description": "Raw gateway callback payload." } } }, "Provider": { "type": "object", "description": "Account-level configuration that connects a payment gateway to the\nworkspace (e.g. credentials, commerce code).\n", "properties": { "gateway": { "type": "string", "description": "Gateway ID (e.g. `transbank`, `getnet`, `stripe`, `mercadopago`, ...)." }, "commerce_code": { "type": "string", "maxLength": 254 }, "extra_data": { "type": "object", "description": "Gateway-specific configuration payload." }, "created": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "gateway", "commerce_code" ] }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "payment": { "type": "integer", "description": "Payment ID being refunded." }, "amount": { "type": "number" }, "balance": { "type": "number", "readOnly": true, "description": "Remaining refundable balance after this refund." }, "reason": { "type": "string", "enum": [ "duplicate", "fraudulent", "requested_by_customer" ] }, "note": { "type": "string", "maxLength": 64, "nullable": true }, "receipt": { "type": "string", "maxLength": 256 }, "status": { "type": "string", "enum": [ "failed", "succeeded" ], "readOnly": true }, "metadata": { "type": "object" }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "payment", "amount", "reason", "receipt" ] }, "SourceCard": { "type": "object", "description": "Card details when the source represents a tokenized card.", "properties": { "brand": { "type": "string" }, "last4": { "type": "string", "maxLength": 4 }, "exp_month": { "type": "integer", "nullable": true }, "exp_year": { "type": "integer", "nullable": true } } }, "Source": { "type": "object", "description": "A payment source: either a single-use intent (e.g. one-off bank transfer)\nor a reusable tokenization (e.g. saved card).\n", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "nullable": true, "description": "Customer ID. Required for reusable sources." }, "gateway": { "type": "string", "description": "Gateway ID (e.g. `transbank`, `stripe`, `ach_transfer`)." }, "usage": { "type": "string", "enum": [ "single", "reusable" ], "default": "single" }, "status": { "type": "string", "enum": [ "failed", "pending", "requires_authorization", "waiting_authorization", "consumed", "chargeable", "finalized" ], "readOnly": true }, "amount": { "type": "number", "nullable": true }, "description": { "type": "string", "maxLength": 256, "nullable": true }, "return_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL the payer is sent to after a redirect-flow tokenization." }, "gateway_data": { "type": "object", "readOnly": true, "description": "Gateway-specific payload (e.g. redirect form fields, token)." }, "client": { "type": "object", "description": "Client metadata captured at creation time (IP, user agent, etc.)." }, "metadata": { "type": "object" }, "card": { "allOf": [ { "$ref": "#/components/schemas/SourceCard" } ], "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "gateway" ] }, "Cancellation": { "type": "object", "description": "Cancellation document issued against a previously finalized retention.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "retention": { "type": "integer", "description": "Retention ID being cancelled." }, "document": { "type": "integer", "description": "Cancellation document type." }, "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "maxLength": 64, "nullable": true }, "internal_note": { "type": "string", "maxLength": 1024, "nullable": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "retention", "document", "number", "date" ] }, "OrderLine": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 200, "nullable": true }, "amount": { "type": "integer" }, "quantity": { "type": "number" }, "exempt": { "type": "boolean", "default": false }, "tax": { "type": "integer", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "integer", "readOnly": true } }, "required": [ "name", "amount", "quantity" ] }, "OrderReference": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "document": { "type": "string" }, "description": { "type": "string", "nullable": true }, "serial": { "type": "string" } }, "required": [ "date", "document", "serial" ] }, "Order": { "type": "object", "description": "Sales / shipping order (e.g. Chilean \"guía de despacho\"). Documents goods\nmovements that may or may not constitute a sale.\n", "properties": { "id": { "type": "integer", "readOnly": true }, "customer": { "type": "string", "description": "Customer ID." }, "document": { "type": "integer", "description": "Order document type." }, "number": { "type": "integer", "nullable": true }, "date": { "type": "string", "format": "date" }, "shipping_type": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9" ], "description": "Shipping classification:\n`1` venta, `2` ventas por efectuar, `3` consignaciones,\n`4` entrega gratuita, `5` traslados internos, `6` otros traslados,\n`7` guía de devolución, `8` traslado para exportación, `9` venta para exportación.\n" }, "address": { "type": "string", "maxLength": 70, "nullable": true }, "state": { "type": "integer", "nullable": true }, "carrier_id": { "type": "string", "maxLength": 10, "nullable": true }, "carrier_name": { "type": "string", "maxLength": 30, "nullable": true }, "licence_plate": { "type": "string", "maxLength": 7, "nullable": true }, "note": { "type": "string", "maxLength": 100, "nullable": true }, "amount": { "type": "integer", "nullable": true }, "exempt": { "type": "integer", "nullable": true }, "tax": { "type": "integer", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ], "default": "draft", "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/OrderReference" } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "customer", "document", "date", "shipping_type", "lines" ] }, "PurchaseCreditNoteLine": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 200, "nullable": true }, "amount": { "type": "number" }, "quantity": { "type": "number" }, "exempt": { "type": "boolean", "default": false }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "number", "readOnly": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "code": { "type": "string", "maxLength": 32, "nullable": true }, "retention": { "type": "number", "nullable": true }, "retention_percent": { "type": "number", "default": 0 } }, "required": [ "name", "amount", "quantity" ] }, "PurchaseCreditNote": { "type": "object", "description": "Credit note that adjusts (or fully cancels) a purchase.", "properties": { "id": { "type": "integer", "readOnly": true }, "purchase": { "type": "integer", "description": "Purchase ID being adjusted." }, "document": { "type": "integer", "description": "Credit-note document type." }, "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "note": { "type": "string", "maxLength": 64, "nullable": true }, "internal_note": { "type": "string", "maxLength": 1024, "nullable": true }, "amount": { "type": "number", "nullable": true }, "exempt": { "type": "number", "nullable": true }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "subtotal": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "retention": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "status": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCreditNoteLine" } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "purchase", "document", "number", "date", "lines" ] }, "PurchaseLine": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 200, "nullable": true }, "amount": { "type": "number" }, "quantity": { "type": "number" }, "exempt": { "type": "boolean", "default": false }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "number", "readOnly": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "code": { "type": "string", "maxLength": 32, "nullable": true }, "code_scheme": { "type": "string", "maxLength": 10, "nullable": true }, "retention": { "type": "number", "nullable": true }, "retention_percent": { "type": "number", "default": 0 } }, "required": [ "name", "amount", "quantity" ] }, "Purchase": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "supplier": { "type": "string", "description": "Supplier ID." }, "document": { "type": "integer", "description": "Purchase-document type ID." }, "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "note": { "type": "string", "maxLength": 100, "nullable": true }, "amount": { "type": "number", "nullable": true }, "exempt": { "type": "number", "nullable": true }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "subtotal": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "total_adjusted": { "type": "number", "nullable": true, "readOnly": true }, "retention": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "tax_settings": { "type": "object", "description": "Country-specific tax-agency configuration." }, "status": { "type": "string", "enum": [ "draft", "finalized" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "metadata": { "type": "object" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseLine" } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "supplier", "document", "number", "date", "lines" ] }, "RetentionLine": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 80 }, "description": { "type": "string", "maxLength": 200, "nullable": true }, "amount": { "type": "number" }, "quantity": { "type": "number" }, "exempt": { "type": "boolean", "default": false }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "total": { "type": "number", "readOnly": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true } }, "required": [ "name", "amount", "quantity" ] }, "Retention": { "type": "object", "description": "Withholding-tax document issued against a supplier.", "properties": { "id": { "type": "integer", "readOnly": true }, "supplier": { "type": "string", "description": "Supplier ID." }, "document": { "type": "integer", "description": "Retention document type." }, "number": { "type": "integer" }, "date": { "type": "string", "format": "date" }, "amount": { "type": "number", "nullable": true }, "exempt": { "type": "number", "nullable": true }, "tax": { "type": "number", "nullable": true }, "tax_percent": { "type": "number", "nullable": true }, "subtotal": { "type": "number", "nullable": true }, "total": { "type": "number", "nullable": true }, "discount": { "type": "number", "nullable": true }, "discount_scheme": { "type": "string", "enum": [ "%", "$" ], "nullable": true }, "status": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ], "readOnly": true }, "biller_status": { "type": "string", "readOnly": true }, "tax_agency": { "type": "object", "readOnly": true }, "local_file": { "type": "string", "format": "uri", "readOnly": true, "nullable": true }, "imported": { "type": "boolean", "readOnly": true }, "test_mode": { "type": "boolean", "readOnly": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/RetentionLine" } }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "supplier", "document", "number", "date", "lines" ] }, "Supplier": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 64 }, "tax_id": { "type": "string", "maxLength": 32, "nullable": true }, "country": { "type": "string", "description": "Country ID." }, "state": { "type": "integer", "nullable": true }, "currency": { "type": "string", "default": "USD", "description": "ISO currency code." }, "address": { "type": "string", "maxLength": 64, "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "maxLength": 16, "nullable": true }, "website": { "type": "string", "format": "uri", "nullable": true }, "tax_settings": { "type": "object", "description": "Country-specific tax-agency configuration." }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "name", "country" ] }, "GeneralCountry": { "type": "object", "properties": { "id": { "type": "string", "example": "CL", "description": "ISO-3166-1 alpha-2 code." }, "name": { "type": "string" }, "name_default": { "type": "string" }, "phone_code": { "type": "string", "example": "+56" }, "three_code": { "type": "string", "nullable": true, "example": "CHL" }, "has_regulation": { "type": "boolean" }, "tax_percent": { "type": "number" }, "locale": { "type": "string", "nullable": true } } }, "GeneralState": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "code": { "type": "string", "maxLength": 12 }, "name": { "type": "string", "maxLength": 64 }, "country": { "type": "string", "description": "Country ID." } } }, "GeneralBank": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "maxLength": 40 }, "country": { "type": "string" }, "connection": { "type": "boolean", "description": "Whether automated bank connection is supported." }, "is_active": { "type": "boolean" }, "api_name": { "type": "string", "maxLength": 24 } } }, "GeneralDocument": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "CL33" }, "country": { "type": "string" }, "code": { "type": "integer" }, "name": { "type": "string", "maxLength": 64 }, "currencies": { "type": "array", "items": { "type": "string" } }, "is_sale": { "type": "boolean" }, "is_purshase": { "type": "boolean" }, "is_order": { "type": "boolean" }, "is_foreign": { "type": "boolean" }, "has_taxes": { "type": "boolean" }, "has_taxes_detail": { "type": "boolean" }, "has_lines_total": { "type": "boolean" }, "has_local_format": { "type": "boolean" }, "hold_taxes": { "type": "boolean" }, "allow_partial_credit": { "type": "boolean" }, "allow_retention": { "type": "boolean" }, "send": { "type": "boolean" }, "given": { "type": "boolean" } } }, "GeneralCurrency": { "type": "object", "properties": { "id": { "type": "string", "example": "CLP", "description": "ISO-4217 code." }, "name": { "type": "string" }, "name_en": { "type": "string" }, "country": { "type": "string" }, "default": { "type": "boolean" }, "is_chargeable": { "type": "boolean" }, "available": { "type": "boolean" }, "rounded": { "type": "boolean" } } }, "GeneralExchangeRate": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "currency_from": { "type": "string" }, "currency_to": { "type": "string" }, "amount": { "type": "number" }, "date": { "type": "string", "format": "date" }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "updated": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "currency_from", "currency_to", "amount", "date" ] }, "GeneralDocumentReference": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "code": { "type": "string", "maxLength": 6 }, "country": { "type": "string" }, "name": { "type": "string", "maxLength": 64 }, "is_numeric": { "type": "boolean" } } } }, "responses": { "Unauthorized": { "description": "Authentication credentials missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The caller is authenticated but not allowed to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Request body or query parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } }, "paths": { "/contacts/": { "get": { "tags": [ "Billing" ], "summary": "List contacts", "description": "Returns a paginated list of contacts. A customer is limited to seven\ncontacts per organisation unit (or seven without an org unit).\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "orgunit", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "invoicing", "in": "query", "schema": { "type": "boolean" } }, { "name": "collections", "in": "query", "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Pass `orgunit` to expand the orgunit relation inline." } ], "responses": { "200": { "description": "Paginated contact list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Billing" ], "summary": "Create contact", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } } } }, "responses": { "201": { "description": "Contact created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/contacts/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve contact", "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } } } }, "responses": { "200": { "description": "Updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update contact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } } } }, "responses": { "200": { "description": "Updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete contact", "responses": { "204": { "description": "Deleted." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/creditnotes/": { "get": { "tags": [ "Billing" ], "summary": "List credit notes", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "invoice", "in": "query", "schema": { "type": "string" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ] } }, { "name": "note", "in": "query", "schema": { "type": "string" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma list. Supported: `invoice`, `document`." } ], "responses": { "200": { "description": "Paginated credit-note list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CreditNote" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Billing" ], "summary": "Create credit note (draft)", "description": "Creates a credit note. If the related invoice or chosen document allows\npartial credit, the line totals are computed from the request; otherwise\nthe lines mirror the invoice.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "responses": { "201": { "description": "Credit note created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/creditnotes/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve credit note", "responses": { "200": { "description": "The credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace credit note (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "responses": { "200": { "description": "Updated credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update credit note (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "responses": { "200": { "description": "Updated credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete credit note (draft only)", "responses": { "204": { "description": "Deleted." }, "400": { "description": "Credit note is not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/creditnotes/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Finalize credit note", "description": "Submits the credit note to the tax agency (when applicable) and locks the document.", "responses": { "200": { "description": "Finalized credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/creditnotes/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Render credit-note PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Credit note is in draft status." } } } }, "/creditnotes/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/customers/": { "get": { "tags": [ "Billing" ], "summary": "List customers", "description": "Returns a paginated list of customers in the workspace.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Filter by country ID." }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "tax_id", "in": "query", "schema": { "type": "string" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Use lookups: `created__gte`, `created__lte`." }, { "name": "subscriptions", "in": "query", "schema": { "type": "string" }, "description": "Filter by linked subscription ID." }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Filter by linked source ID." } ], "responses": { "200": { "description": "Paginated customer list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Billing" ], "summary": "Create customer", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWrite" } } } }, "responses": { "201": { "description": "Customer created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customers/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve customer", "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace customer", "description": "Updates a customer. When the country has tax regulation, `tax_id` is read-only.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWrite" } } } }, "responses": { "200": { "description": "Updated customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWrite" } } } }, "responses": { "200": { "description": "Updated customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete customer", "description": "Soft-archives the customer (sets `status=archived`) when there are non-draft invoices,\nterminal subscriptions, valuable sources, or abandoned sources with payments.\nOtherwise hard-deletes the customer and any draft invoices.\n", "responses": { "204": { "description": "Deleted or archived." }, "400": { "description": "Customer has active subscriptions; cancel them first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{id}/status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Customer status snapshot", "description": "Returns a financial summary for the customer: status, total finalized sales,\nsales in the current month, outstanding balance and source flags.\n", "responses": { "200": { "description": "Customer status snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerStatus" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/debitnotes/": { "get": { "tags": [ "Billing" ], "summary": "List debit notes", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "credit_note", "in": "query", "schema": { "type": "integer" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "note", "in": "query", "schema": { "type": "string" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated debit-note list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/DebitNote" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create debit note", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "responses": { "201": { "description": "Debit note created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/debitnotes/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve debit note", "responses": { "200": { "description": "The debit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace debit note", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "responses": { "200": { "description": "Updated debit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update debit note", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "responses": { "200": { "description": "Updated debit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete debit note", "responses": { "204": { "description": "Deleted." } } } }, "/debitnotes/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Render debit-note PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/debitnotes/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed debit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DebitNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices/": { "get": { "tags": [ "Billing" ], "summary": "List invoices", "description": "Returns a paginated list of invoices. The list excludes draft invoices\nthat belong to a subscription, and (unless filtered by `bulk`) invoices\nattached to a bulk in `pending`, `processing` or `failed` status.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Use lookups: `date__gte`, `date__lte`." }, { "name": "due_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "collection_method", "in": "query", "schema": { "type": "string", "enum": [ "deferred", "deferred_dues", "automatically" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalized", "paid", "cancelled", "uncollectible", "pending" ] } }, { "name": "subscription", "in": "query", "schema": { "type": "integer" } }, { "name": "bulk", "in": "query", "schema": { "type": "integer" } }, { "name": "imported", "in": "query", "schema": { "type": "boolean" } }, { "name": "tax_agency", "in": "query", "schema": { "type": "string" } }, { "name": "total", "in": "query", "schema": { "type": "number" } }, { "name": "total_adjusted", "in": "query", "schema": { "type": "number" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated invoice list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Billing" ], "summary": "Create invoice (draft)", "description": "Creates an invoice in `draft` status. Totals (`amount`, `tax`,\n`subtotal`, `total`) are computed server-side from the lines.\nCall `finalize` to issue the invoice to the tax agency and lock it.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "responses": { "201": { "description": "Invoice created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve invoice", "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace invoice (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "responses": { "200": { "description": "Updated invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update invoice (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "responses": { "200": { "description": "Updated invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete invoice (draft only)", "description": "Only invoices in `draft` status can be deleted. Linked payments are unlinked.", "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invoice is not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/invoices/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Finalize invoice", "description": "Submits the invoice to the tax agency (when applicable) and locks the\ndocument. Requires status `draft` or `pending`. When status is `pending`\nall linked payments must be `succeeded`.\n", "responses": { "200": { "description": "Finalized invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices/{id}/uncollectible/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Toggle uncollectible", "description": "Toggles the invoice between `finalized` and `uncollectible`. Sets or\nclears the `uncollectible` timestamp accordingly.\n", "responses": { "200": { "description": "Updated invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/invoices/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Render invoice PDF", "description": "Returns the invoice PDF. Uses the fiscal format when the document type\nhas a local biller; otherwise renders a plain HTML-to-PDF template.\n", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invoice is in draft status." } } } }, "/invoices/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Refresh tax-agency status", "description": "Polls the configured tax agency for the document status and updates\n`biller_status` and `tax_agency`. Only applicable when the document\ntype has a local biller and the invoice is not imported.\n", "responses": { "200": { "description": "Refreshed invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/orgunits/": { "get": { "tags": [ "Billing" ], "summary": "List organisation units", "description": "Returns a paginated list of organisation units. A customer can have at\nmost twelve org units; org units are an optional sub-grouping for contacts\nand subscriptions.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated org-unit list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Orgunit" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Billing" ], "summary": "Create org unit", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgunitWrite" } } } }, "responses": { "201": { "description": "Org unit created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Orgunit" } } } }, "400": { "description": "Reached the 12 org units per customer limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/orgunits/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve org unit", "responses": { "200": { "description": "The org unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Orgunit" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace org unit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgunitWrite" } } } }, "responses": { "200": { "description": "Updated org unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Orgunit" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update org unit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgunitWrite" } } } }, "responses": { "200": { "description": "Updated org unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Orgunit" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete org unit", "description": "Refuses to delete when there are linked contacts or subscriptions; remove\nthem first.\n", "responses": { "204": { "description": "Deleted." }, "400": { "description": "Org unit linked to contacts or subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payment-receipts/": { "get": { "tags": [ "Billing" ], "summary": "List payment receipts", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "sources", "in": "query", "schema": { "type": "string" }, "description": "Filter by linked source ID." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalized" ] } }, { "name": "biller_status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated payment-receipt list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentReceipt" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create payment receipt (draft)", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "responses": { "201": { "description": "Payment receipt created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payment-receipts/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve payment receipt", "responses": { "200": { "description": "The payment receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace payment receipt (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "responses": { "200": { "description": "Updated payment receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update payment receipt (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "responses": { "200": { "description": "Updated payment receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete payment receipt (draft only)", "responses": { "204": { "description": "Deleted." }, "400": { "description": "Payment receipt is not in draft status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/payment-receipts/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Finalize payment receipt", "responses": { "200": { "description": "Finalized payment receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payment-receipts/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Render payment-receipt PDF", "responses": { "200": { "description": "PDF binary.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Receipt is in draft status, has no payments, or biller does not support receipts." } } } }, "/payment-receipts/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed payment receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" } } } } } } }, "/frequencies/": { "get": { "tags": [ "Billing" ], "summary": "List frequencies", "description": "Returns the catalogue of built-in billing frequencies (daily, monthly,\nyearly with quantity multipliers). Read-only.\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" } ], "responses": { "200": { "description": "Paginated frequency list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Frequency" } } } } ] } } } } } } }, "/frequencies/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve frequency", "responses": { "200": { "description": "The frequency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Frequency" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products/": { "get": { "tags": [ "Billing" ], "summary": "List products", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "plans", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated product list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create product", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "201": { "description": "Product created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/products/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve product", "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace product", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "200": { "description": "Updated product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update product", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "200": { "description": "Updated product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Archive product", "description": "Soft-deletes the product (sets `status=archived`). Cannot be reused after archive.", "responses": { "204": { "description": "Archived." } } } }, "/plans/": { "get": { "tags": [ "Billing" ], "summary": "List plans", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "product", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived" ] } } ], "responses": { "200": { "description": "Paginated plan list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create plan", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "responses": { "201": { "description": "Plan created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/plans/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve plan", "responses": { "200": { "description": "The plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Update plan (mutable fields)", "description": "Only `name`, `description`, `sku`, `unit_label` and `metadata` are\nmutable. To change pricing, archive the plan and create a new one.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdate" } } } }, "responses": { "200": { "description": "Updated plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update plan (mutable fields)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanUpdate" } } } }, "responses": { "200": { "description": "Updated plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Archive plan", "responses": { "204": { "description": "Archived." } } } }, "/addons/": { "get": { "tags": [ "Billing" ], "summary": "List addons", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "apply_scheme", "in": "query", "schema": { "type": "string", "enum": [ "one_time", "recurring" ] } }, { "name": "amount", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated addon list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Addon" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create addon", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } }, "responses": { "201": { "description": "Addon created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/addons/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve addon", "responses": { "200": { "description": "The addon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace addon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } }, "responses": { "200": { "description": "Updated addon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update addon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } }, "responses": { "200": { "description": "Updated addon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Addon" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Archive addon", "responses": { "204": { "description": "Archived." } } } }, "/coupons/": { "get": { "tags": [ "Billing" ], "summary": "List coupons", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "apply_on", "in": "query", "schema": { "type": "string", "enum": [ "line", "invoice" ] } }, { "name": "duration_scheme", "in": "query", "schema": { "type": "string", "enum": [ "one_time", "forever", "limited" ] } }, { "name": "amount", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated coupon list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create coupon", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "responses": { "201": { "description": "Coupon created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/coupons/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve coupon", "responses": { "200": { "description": "The coupon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace coupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "responses": { "200": { "description": "Updated coupon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update coupon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "responses": { "200": { "description": "Updated coupon.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Archive coupon", "responses": { "204": { "description": "Archived." } } } }, "/subscriptions/": { "get": { "tags": [ "Billing" ], "summary": "List subscriptions", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "cancelled", "finalized", "needs_attention" ] } }, { "name": "next_billing", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "lines", "in": "query", "schema": { "type": "string" }, "description": "Filter by linked line ID." }, { "name": "addons", "in": "query", "schema": { "type": "integer" } }, { "name": "coupon", "in": "query", "schema": { "type": "string" } }, { "name": "cancelled", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cancel_reason", "in": "query", "schema": { "type": "string" } }, { "name": "paused", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "paused_reason", "in": "query", "schema": { "type": "string" } }, { "name": "needs_attention", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "needs_attention_reason", "in": "query", "schema": { "type": "string" } }, { "name": "instant", "in": "query", "schema": { "type": "boolean" }, "description": "Compute on-the-fly billing for the response." } ], "responses": { "200": { "description": "Paginated subscription list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create subscription", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "responses": { "201": { "description": "Subscription created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/subscriptions/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve subscription", "responses": { "200": { "description": "The subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "responses": { "200": { "description": "Updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "responses": { "200": { "description": "Updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Cancel subscription", "description": "If the subscription has no non-draft invoices it is hard-deleted; otherwise\nit is cancelled (`status=cancelled`, `cancelled` timestamp set) and a\n`cancel_reason` is recorded (defaults to `not_specified`).\n", "parameters": [ { "name": "cancel_reason_description", "in": "query", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancelled or deleted." } } } }, "/subscriptions/{id}/process/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Process next billing cycle", "description": "Generates the next invoice (or charge) for the subscription according to\nits `collection_scheme` and advances `next_billing`.\n", "responses": { "200": { "description": "Updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/subscriptions/{id}/pause/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Billing" ], "summary": "Pause subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPause" } } } }, "responses": { "200": { "description": "Paused subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } } }, "/subscriptions/{id}/resume/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Billing" ], "summary": "Resume subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResume" } } } }, "responses": { "200": { "description": "Resumed subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } } } } }, "/subscriptions/{id}/events/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "List subscription events", "description": "Audit trail for the subscription (created, paused, reactivated, cancelled, ...).", "responses": { "200": { "description": "Event list.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionEvent" } } } } } } } }, "/subscriptions/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Render the next-invoice PDF", "description": "Renders a preview of the next invoice that would be generated for this subscription.", "responses": { "200": { "description": "PDF binary.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/supporting-documents/rules/": { "get": { "tags": [ "Billing" ], "summary": "List rules", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" } ], "responses": { "200": { "description": "Paginated rule list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create rule", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } }, "responses": { "201": { "description": "Rule created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } } } } }, "/supporting-documents/rules/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve rule", "responses": { "200": { "description": "The rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } }, "responses": { "200": { "description": "Updated rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } }, "responses": { "200": { "description": "Updated rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentRule" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete rule", "responses": { "204": { "description": "Deleted." } } } }, "/supporting-documents/documents/": { "get": { "tags": [ "Billing" ], "summary": "List supporting documents", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "document_type", "in": "query", "schema": { "type": "string", "enum": [ "801", "802" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "consumed", "expired", "archived" ] } }, { "name": "subscriptions", "in": "query", "schema": { "type": "string" } }, { "name": "submission_request", "in": "query", "schema": { "type": "integer" } }, { "name": "used", "in": "query", "schema": { "type": "boolean" } }, { "name": "valid_until", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_issued", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated supporting-document list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SupportingDocument" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Upload supporting document", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } }, "responses": { "201": { "description": "Document uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/supporting-documents/documents/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve supporting document", "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace supporting document", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } }, "responses": { "200": { "description": "Updated document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update supporting document", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } }, "responses": { "200": { "description": "Updated document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete supporting document", "responses": { "204": { "description": "Deleted." } } } }, "/supporting-documents/documents/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Get document file (base64)", "description": "Returns the uploaded file encoded as base64 in `{ \"file\": \"...\" }`.", "responses": { "200": { "description": "Base64-encoded file payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "byte" } } } } } }, "400": { "description": "Document has no file attached." } } } }, "/supporting-documents/documents/{id}/archive/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Billing" ], "summary": "Archive supporting document", "responses": { "200": { "description": "Archived document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocument" } } } } } } }, "/supporting-documents/service-entries/": { "get": { "tags": [ "Billing" ], "summary": "List service entries", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" } ], "responses": { "200": { "description": "Paginated service-entry list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceEntry" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create service entry", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } }, "responses": { "201": { "description": "Service entry created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } } } } }, "/supporting-documents/service-entries/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve service entry", "responses": { "200": { "description": "The service entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace service entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } }, "responses": { "200": { "description": "Updated service entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update service entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } }, "responses": { "200": { "description": "Updated service entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceEntry" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete service entry", "responses": { "204": { "description": "Deleted." } } } }, "/supporting-documents/submission-requests/": { "get": { "tags": [ "Billing" ], "summary": "List submission requests", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "overdue", "fulfilled", "cancelled" ] } }, { "name": "submission_type", "in": "query", "schema": { "type": "string", "enum": [ "order", "hes" ] } }, { "name": "is_automatic", "in": "query", "schema": { "type": "boolean" } }, { "name": "due_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated submission-request list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionRequest" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create submission request", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "responses": { "201": { "description": "Submission request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } } } } }, "/supporting-documents/submission-requests/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Billing" ], "summary": "Retrieve submission request", "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Billing" ], "summary": "Replace submission request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "responses": { "200": { "description": "Updated request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } } } }, "patch": { "tags": [ "Billing" ], "summary": "Partial update submission request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "responses": { "200": { "description": "Updated request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Delete submission request", "responses": { "204": { "description": "Deleted." } } } }, "/supporting-documents/submission-requests/{id}/send/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Billing" ], "summary": "Send submission-request email", "description": "Sends the request email to `recipients` and marks the request as\n`sent`. Fails if the request is already `fulfilled` or `cancelled`,\nif `recipients` is empty, or if SMTP delivery fails.\n", "responses": { "200": { "description": "Sent submission request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/supporting-documents/submission-requests/{id}/cancel/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Billing" ], "summary": "Cancel submission request", "responses": { "200": { "description": "Cancelled submission request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionRequest" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/supporting-documents/board/": { "get": { "tags": [ "Billing" ], "summary": "Supporting-documents Kanban board", "description": "Returns submission requests and supporting documents grouped by status,\nsuitable for a Kanban-style UI. Optionally filter by `customer`.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "name": "customer", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Kanban board (object keyed by status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentBoard" } } } } } } }, "/usages/": { "get": { "tags": [ "Billing" ], "summary": "List usages", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "subscription_line", "in": "query", "schema": { "type": "integer" } }, { "name": "date_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "quantity", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Paginated usage list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Usage" } } } } ] } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Record usage", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "responses": { "201": { "description": "Usage recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/intents/": { "get": { "tags": [ "Billing" ], "summary": "List intents", "description": "Operational intents associated with subscriptions that need attention.\nRead-only.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "subscription", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated intent list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Intent" } } } } ] } } } } } } }, "/ach_transfers/": { "get": { "tags": [ "Payments" ], "summary": "List ACH transfers", "description": "Lists ACH transfers. By default, archived transfers are excluded; pass\n`status=archived` to include them.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "archived", "finalized", "incomplete", "pending" ] } }, { "name": "amount", "in": "query", "schema": { "type": "number" } }, { "name": "balance", "in": "query", "schema": { "type": "number" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "description", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated ACH-transfer list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AchTransfer" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create ACH transfer", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } }, "responses": { "201": { "description": "Transfer created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } } } } }, "/ach_transfers/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve ACH transfer", "responses": { "200": { "description": "The transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Payments" ], "summary": "Replace ACH transfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } }, "responses": { "200": { "description": "Updated transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } } } }, "patch": { "tags": [ "Payments" ], "summary": "Partial update ACH transfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } }, "responses": { "200": { "description": "Updated transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchTransfer" } } } } } }, "delete": { "tags": [ "Payments" ], "summary": "Archive ACH transfer", "description": "Archives the transfer (status `pending` only). Sets `status=archived` and an `archived` timestamp.", "responses": { "204": { "description": "Archived." }, "400": { "description": "Transfer status must be `pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/ach_transfers/adjustments/": { "get": { "tags": [ "Payments" ], "summary": "List ACH adjustments", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "transfer", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated adjustment list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/AchAdjustment" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create ACH adjustment", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchAdjustment" } } } }, "responses": { "201": { "description": "Adjustment created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AchAdjustment" } } } } } } }, "/ach_transfers/adjustments/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "delete": { "tags": [ "Payments" ], "summary": "Delete ACH adjustment", "description": "Reverses the adjustment on the parent transfer. The transfer must be `pending`.", "responses": { "204": { "description": "Reversed." }, "400": { "description": "Parent transfer is not pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/banks/": { "get": { "tags": [ "Payments" ], "summary": "List banks", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "authentication_failed", "unknown_error", "archived" ] } } ], "responses": { "200": { "description": "Paginated bank list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Bank" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create bank account", "description": "Creates a bank account. When `?external=true&provider=fintoc` is passed\nthe request is treated as a Fintoc callback and uses the third-party\nserializer instead.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "name": "external", "in": "query", "schema": { "type": "boolean" } }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "bankops", "fintoc", "floid", "plaid" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } }, "responses": { "201": { "description": "Bank created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/banks/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "put": { "tags": [ "Payments" ], "summary": "Replace bank", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } }, "responses": { "200": { "description": "Updated bank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } } } }, "patch": { "tags": [ "Payments" ], "summary": "Partial update bank", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } }, "responses": { "200": { "description": "Updated bank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } } } } }, "/banks/{id}/sync/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "post": { "tags": [ "Payments" ], "summary": "Sync bank movements", "description": "Fetches bank-side movements from the configured provider for the given window.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankSync" } } } }, "responses": { "201": { "description": "Sync triggered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankSync" } } } } } } }, "/boletos/": { "get": { "tags": [ "Payments" ], "summary": "List boletos", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "payment", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated boleto list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Boleto" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create boleto", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } }, "responses": { "201": { "description": "Boleto created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } } } } }, "/boletos/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve boleto", "responses": { "200": { "description": "The boleto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Payments" ], "summary": "Replace boleto", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } }, "responses": { "200": { "description": "Updated boleto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } } } }, "patch": { "tags": [ "Payments" ], "summary": "Partial update boleto", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } }, "responses": { "200": { "description": "Updated boleto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Boleto" } } } } } }, "delete": { "tags": [ "Payments" ], "summary": "Delete boleto", "responses": { "204": { "description": "Deleted." } } } }, "/payment_links/links/": { "get": { "tags": [ "Payments" ], "summary": "List payment links", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" } ], "responses": { "200": { "description": "Paginated payment-link list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create payment link", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payment_links/links/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve payment link", "responses": { "200": { "description": "The payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Payments" ], "summary": "Replace payment link", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "responses": { "200": { "description": "Updated payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "patch": { "tags": [ "Payments" ], "summary": "Partial update payment link", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "responses": { "200": { "description": "Updated payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } } } }, "delete": { "tags": [ "Payments" ], "summary": "Archive payment link", "responses": { "204": { "description": "Archived." } } } }, "/publishable/payment_links/links/{publishable_key}/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve payment link (publishable)", "description": "Public read of a payment link by its `publishable_key`. No authentication required.", "responses": { "200": { "description": "The payment link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkPublic" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/publishable/payment_links/links/{publishable_key}/hosted/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve hosted-page payload (publishable)", "description": "Returns the data needed to render the Piriod-hosted checkout UI.", "responses": { "200": { "description": "Hosted-page payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkHosted" } } } } } } }, "/publishable/payment_links/intents/": { "post": { "tags": [ "Payments" ], "summary": "Create payment intent (publishable)", "description": "Creates a payment intent against a payment link. Returns the intent's\n`publishable_key` to drive the rest of the checkout flow.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "responses": { "201": { "description": "Intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/publishable/payment_links/intents/{publishable_key}/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve payment intent (publishable)", "responses": { "200": { "description": "The intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/publishable/payment_links/intents/{publishable_key}/authorize/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Render authorize form (publishable)", "description": "Renders the gateway's hosted authorization form (HTML).", "responses": { "200": { "description": "HTML form.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/publishable/payment_links/intents/{publishable_key}/capture/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Capture intent (publishable, GET)", "responses": { "200": { "description": "HTML success/error page.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Capture intent (publishable)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway_data": { "type": "object" } } } } } }, "responses": { "200": { "description": "HTML success/error page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/publishable/payment_links/intents/{publishable_key}/finalize/": { "parameters": [ { "name": "publishable_key", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Payments" ], "summary": "Finalize intent (publishable, GET)", "responses": { "200": { "description": "HTML success page.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Finalize intent (publishable)", "responses": { "200": { "description": "HTML success page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/payments/": { "get": { "tags": [ "Payments" ], "summary": "List payments", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "invoice", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "integer" } }, { "name": "sources", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "cancelled", "failed", "incomplete", "processing", "requires_payment_method", "succeeded" ] } }, { "name": "amount", "in": "query", "schema": { "type": "number" } }, { "name": "balance", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "description", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated payment list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create payment", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "responses": { "201": { "description": "Payment created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payments/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve payment", "responses": { "200": { "description": "The payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Payments" ], "summary": "Replace payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "responses": { "200": { "description": "Updated payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } }, "patch": { "tags": [ "Payments" ], "summary": "Partial update payment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "responses": { "200": { "description": "Updated payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } }, "delete": { "tags": [ "Payments" ], "summary": "Delete payment", "description": "Refuses to delete payments in `succeeded` or `processing` status, or\npayments linked to an invoice.\n", "responses": { "204": { "description": "Deleted." }, "400": { "description": "Payment cannot be deleted (linked to an invoice or in non-cancellable status).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/payments/{id}/authorize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "Payments" ], "summary": "Authorize payment (publishable)", "description": "Public endpoint used during a checkout flow. Attaches a `source` to the\npayment and authorizes the gateway transaction. Does **not** require\nauthentication; the payment is found by its ID alone, so its\n`enable_checkout` flag must be `true`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAuthorize" } } } }, "responses": { "200": { "description": "Payment authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payments/{id}/capture/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Payments" ], "summary": "Capture payment (publishable, GET)", "description": "Used by gateway redirect flows: the payer is bounced back here and\nPiriod renders an HTML page reflecting success or failure. Does not\nrequire authentication.\n", "responses": { "200": { "description": "HTML page or JSON payload.", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Capture payment (publishable)", "description": "Confirms the gateway transaction. Used by hosted checkouts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCapture" } } } }, "responses": { "200": { "description": "Captured payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/payments/{id}/process/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Payments" ], "summary": "Render redirect form (publishable)", "description": "Renders the gateway's HTML form to redirect the payer (only for\ngateways with `flow=redirect`). The attached source must be in\n`chargeable` status.\n", "responses": { "200": { "description": "HTML form.", "content": { "text/html": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/payments/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Payments" ], "summary": "Render success page (publishable)", "responses": { "200": { "description": "HTML success page.", "content": { "text/html": { "schema": { "type": "string" } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Render success page (publishable)", "responses": { "200": { "description": "HTML success page.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/providers/": { "get": { "tags": [ "Payments" ], "summary": "List payment providers", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "gateway", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated provider list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Add provider", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "responses": { "201": { "description": "Provider created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/providers/{gateway}/": { "parameters": [ { "name": "gateway", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve provider", "responses": { "200": { "description": "The provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Payments" ], "summary": "Remove provider", "responses": { "204": { "description": "Removed." } } } }, "/refunds/": { "post": { "tags": [ "Payments" ], "summary": "Create refund", "description": "Issues a refund against a payment. The total of refund amounts cannot\nexceed the payment's amount.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "responses": { "201": { "description": "Refund created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/sources/": { "get": { "tags": [ "Payments" ], "summary": "List sources", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "customer", "in": "query", "schema": { "type": "string" } }, { "name": "gateway", "in": "query", "schema": { "type": "string" } }, { "name": "usage", "in": "query", "schema": { "type": "string", "enum": [ "single", "reusable" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated source list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } } ] } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Create source (publishable)", "description": "Creates a payment source. This endpoint accepts unauthenticated calls\nfrom the browser (publishable flow), so the request is identified by the\ngateway/customer/payment context rather than a workspace header.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "responses": { "201": { "description": "Source created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/sources/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Payments" ], "summary": "Retrieve source", "responses": { "200": { "description": "The source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Payments" ], "summary": "Delete or finalize source", "description": "For reusable sources: detaches the tokenization at the gateway and\neither finalizes the source (when it has linked payments) or hard-\ndeletes it. For single-use sources tied to ACH transfers, releases the\nbalance back to the transfer. Refuses to delete other single-use sources.\n", "responses": { "204": { "description": "Detached or deleted." }, "400": { "description": "Source cannot be detached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/sources/{id}/authorize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Payments" ], "summary": "Render tokenization form (publishable)", "description": "Renders the gateway's tokenization form (HTML). The payer completes\nauthorization to convert the source to `chargeable` status.\n", "responses": { "200": { "description": "HTML form.", "content": { "text/html": { "schema": { "type": "string" } } } } } } }, "/sources/{id}/store/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Payments" ], "summary": "Store tokenized source (publishable, GET)", "description": "Confirmation callback used by gateway redirect flows.", "responses": { "200": { "description": "HTML success/error page or JSON payload.", "content": { "text/html": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } } } }, "post": { "tags": [ "Payments" ], "summary": "Store tokenized source (publishable)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway_data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Stored source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/sources/{id}/send_inscription_request/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "Payments" ], "summary": "Email tokenization request to customer", "description": "Sends an email to the customer with a link to authorize the source's tokenization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "recipients" ] } } } }, "responses": { "201": { "description": "Inscription request sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/cancellations/": { "get": { "tags": [ "Procurement" ], "summary": "List cancellations", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "retention", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated cancellation list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Cancellation" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create cancellation", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" } } } }, "responses": { "201": { "description": "Cancellation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/cancellations/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve cancellation", "responses": { "200": { "description": "The cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders/": { "get": { "tags": [ "Procurement" ], "summary": "List orders", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalized", "cancelled" ] } }, { "name": "tax_agency", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated order list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create order (draft)", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "201": { "description": "Order created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/orders/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve order", "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Procurement" ], "summary": "Replace order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "200": { "description": "Updated order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } }, "patch": { "tags": [ "Procurement" ], "summary": "Partial update order", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "200": { "description": "Updated order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } }, "delete": { "tags": [ "Procurement" ], "summary": "Delete order", "responses": { "204": { "description": "Deleted." } } } }, "/orders/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Finalize order", "responses": { "200": { "description": "Finalized order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/orders/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Render order PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/orders/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } } } } }, "/purchases/credit-notes/": { "get": { "tags": [ "Procurement" ], "summary": "List purchase credit notes", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "purchase", "in": "query", "schema": { "type": "integer" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "note", "in": "query", "schema": { "type": "string" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated purchase-credit-note list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create purchase credit note (draft)", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "responses": { "201": { "description": "Credit note created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/purchases/credit-notes/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve purchase credit note", "responses": { "200": { "description": "The credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Procurement" ], "summary": "Replace purchase credit note (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "responses": { "200": { "description": "Updated credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } } } }, "patch": { "tags": [ "Procurement" ], "summary": "Partial update purchase credit note (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "responses": { "200": { "description": "Updated credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } } } }, "delete": { "tags": [ "Procurement" ], "summary": "Delete purchase credit note (draft only)", "responses": { "204": { "description": "Deleted." } } } }, "/purchases/credit-notes/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Finalize purchase credit note", "responses": { "200": { "description": "Finalized credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/purchases/credit-notes/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Render purchase credit-note PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/purchases/credit-notes/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseCreditNote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/purchases/": { "get": { "tags": [ "Procurement" ], "summary": "List purchases", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "supplier", "in": "query", "schema": { "type": "string" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "finalized" ] } }, { "name": "total", "in": "query", "schema": { "type": "number" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated purchase list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Purchase" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create purchase (draft)", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "responses": { "201": { "description": "Purchase created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/purchases/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve purchase", "responses": { "200": { "description": "The purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Procurement" ], "summary": "Replace purchase (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "responses": { "200": { "description": "Updated purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } } } }, "patch": { "tags": [ "Procurement" ], "summary": "Partial update purchase (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "responses": { "200": { "description": "Updated purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } } } }, "delete": { "tags": [ "Procurement" ], "summary": "Delete purchase (draft only)", "responses": { "204": { "description": "Deleted." } } } }, "/purchases/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Finalize purchase", "description": "Submits the purchase to the tax agency (when applicable) and locks it.", "responses": { "200": { "description": "Finalized purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/purchases/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Render purchase PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/purchases/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed purchase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/retentions/": { "get": { "tags": [ "Procurement" ], "summary": "List retentions", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "supplier", "in": "query", "schema": { "type": "string" } }, { "name": "document", "in": "query", "schema": { "type": "integer" } }, { "name": "number", "in": "query", "schema": { "type": "integer" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "total", "in": "query", "schema": { "type": "number" } }, { "name": "bulk", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated retention list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Retention" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create retention (draft)", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "responses": { "201": { "description": "Retention created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/retentions/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve retention", "responses": { "200": { "description": "The retention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Procurement" ], "summary": "Replace retention (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "responses": { "200": { "description": "Updated retention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } } } }, "patch": { "tags": [ "Procurement" ], "summary": "Partial update retention (draft only)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "responses": { "200": { "description": "Updated retention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } } } }, "delete": { "tags": [ "Procurement" ], "summary": "Delete retention (draft only)", "responses": { "204": { "description": "Deleted." } } } }, "/retentions/{id}/finalize/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Finalize retention", "responses": { "200": { "description": "Finalized retention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/retentions/{id}/pdf/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Render retention PDF", "responses": { "200": { "description": "PDF binary or fiscal payload.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/retentions/{id}/tax_agency_status/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Refresh tax-agency status", "responses": { "200": { "description": "Refreshed retention.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Retention" } } } } } } }, "/suppliers/": { "get": { "tags": [ "Procurement" ], "summary": "List suppliers", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" }, { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "tax_id", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "created", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated supplier list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } } } } ] } } } } } }, "post": { "tags": [ "Procurement" ], "summary": "Create supplier", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "responses": { "201": { "description": "Supplier created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" } } } }, "/suppliers/{id}/": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/WorkspaceHeader" }, { "$ref": "#/components/parameters/TestModeHeader" } ], "get": { "tags": [ "Procurement" ], "summary": "Retrieve supplier", "responses": { "200": { "description": "The supplier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Procurement" ], "summary": "Replace supplier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "responses": { "200": { "description": "Updated supplier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } } } }, "patch": { "tags": [ "Procurement" ], "summary": "Partial update supplier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "responses": { "200": { "description": "Updated supplier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } } } }, "delete": { "tags": [ "Procurement" ], "summary": "Delete supplier", "responses": { "204": { "description": "Deleted." } } } }, "/generals/countries/": { "get": { "tags": [ "Collections" ], "summary": "List countries", "description": "Reference catalogue of supported countries.", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" } ], "responses": { "200": { "description": "Paginated country list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralCountry" } } } } ] } } } } } } }, "/generals/states/": { "get": { "tags": [ "Collections" ], "summary": "List states / provinces", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated state list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralState" } } } } ] } } } } } } }, "/generals/banks/": { "get": { "tags": [ "Collections" ], "summary": "List banks", "description": "Reference catalogue of banks per country.", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "connection", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated bank list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralBank" } } } } ] } } } } } } }, "/generals/documents/": { "get": { "tags": [ "Collections" ], "summary": "List document types", "description": "Reference catalogue of fiscal document types per country.", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "currencies", "in": "query", "schema": { "type": "string" } }, { "name": "is_sale", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_purshase", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_order", "in": "query", "schema": { "type": "boolean" } }, { "name": "hold_taxes", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated document list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralDocument" } } } } ] } } } } } } }, "/generals/currencies/": { "get": { "tags": [ "Collections" ], "summary": "List currencies", "description": "Reference catalogue of currencies. Public endpoint — does not require\nauthentication or workspace headers.\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "security": [], "responses": { "200": { "description": "Paginated currency list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralCurrency" } } } } ] } } } } } } }, "/generals/changes/": { "get": { "tags": [ "Collections" ], "summary": "List exchange rates", "description": "Historical exchange rates between currencies.", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "$ref": "#/components/parameters/OrderingQuery" }, { "name": "currency_from", "in": "query", "schema": { "type": "string" } }, { "name": "currency_to", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated exchange-rate list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralExchangeRate" } } } } ] } } } } } } }, "/generals/references/": { "get": { "tags": [ "Collections" ], "summary": "List document reference types", "description": "Reference catalogue of document-reference types (used to link an invoice\nto a previous document, e.g. credit notes).\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/PageSizeQuery" }, { "name": "country", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated reference list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/GeneralDocumentReference" } } } } ] } } } } } } } } }