> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.staple.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.staple.ai/_mcp/server. # Accounts Receivable ## Business flow Accounts Receivable (AR) covers the flow of *issuing* e-invoices from your business to your customers. With Staple, your accounting or ERP system does not need to integrate directly with each country's tax authority or with the Peppol network — Staple handles all the country-specific format conversion, validation, and transport on your behalf. ### One format, every country: STAR Every country defines its own e-invoice format. Singapore uses Peppol UBL. Malaysia uses MyInvois UBL 2.1. India uses IRP JSON. Poland uses KSeF XML. Mexico uses CFDI XML. Each format has its own field names, structure, and validation rules. If your business operates in more than one country, integrating directly with each format multiplies the engineering work with every country added. To remove this burden, Staple defines a single unified schema called **STAR** — *Staple Transactional API Records*. STAR is a country-agnostic representation of an invoice. You map your ERP data to STAR once, and Staple takes responsibility for converting STAR into the format each tax authority expects. The full STAR schema reference is documented in [Schema Objects](/e-invoice/reference/schema-objects). ![One STAR format, every country](https://files.buildwithfern.com/staple.docs.buildwithfern.com/afd26f0207fb073b8e9b2a21e53743d6c902718f9bdc8075c707f7b86c3f6828/docs/assets/einvoice/new_AR_flow_1.png) ### How the AR flow works The flow works as follows: 1. **Your system produces a STAR invoice.** Your accounting or ERP system constructs an invoice in STAR format using the data fields documented in the Schema Objects reference. 2. **Submit the invoice to Staple.** Your system calls the **Submit** endpoint with the STAR payload. Staple acknowledges receipt and queues the invoice for processing. The acknowledgement returns a `docId` you will use in subsequent steps. 3. **Staple validates and clears the invoice.** Behind the scenes, Staple performs two distinct steps: * **Validation** — Staple converts the STAR payload into the destination country's e-invoice format and validates it against the schema and the relevant tax authority's rules. * **Clearance** — Once validation passes, Staple submits the converted invoice to the tax authority portal or the Peppol network. The tax authority returns a clearance reference (such as a MyInvois UUID, SDI IdentificativoSdI, KSeF number, or IRN) that legally identifies the issued invoice. 4. **Your system learns the outcome.** You can learn the outcome in two ways: * **Push** — subscribe to webhook events and Staple notifies your server when each step completes. * **Pull** — call the Get invoice status endpoint at any time with the `docId` to retrieve the current validation status and clearance evidence. 5. **Your buyer may accept, reject, or pay the invoice.** Days or weeks later, the buyer at the receiving end may take action on the invoice you issued. If you want to be notified of buyer actions — particularly rejections — you can subscribe to the relevant webhook event. ### Country support Staple's AR flow supports all 12 countries: 🇸🇬 Singapore · 🇨🇳 China · 🇲🇾 Malaysia · 🇵🇱 Poland · 🇫🇷 France · 🇧🇪 Belgium · 🇮🇹 Italy · 🇩🇪 Germany · 🇪🇸 Spain · 🇧🇷 Brazil · 🇲🇽 Mexico · 🇮🇳 India. Country-specific behaviour, required fields, and validation rules are documented inside each schema object and on the per-country payload pages. ## Submit API `POST https://api.staple.io/v2/einvoice/submit/queue/:queueId` Submit a STAR e-invoice to Staple for conversion, validation, and submission to the destination country's tax authority or the Peppol network. Compliance processing runs asynchronously — this endpoint acknowledges receipt of the payload and returns identifiers you can use to track the outcome. The queue ID the document should land in. Bearer token, e.g. `Authorization: Bearer `. The full STAR invoice payload. See [Schema Objects](/e-invoice/reference/schema-objects) for the complete schema reference. ```http title="Request" POST https://api.staple.io/v2/einvoice/submit/queue/4173 Authorization: Bearer Content-Type: application/json { "Country": "DE", "ComplianceStandards": ["eu-en16931-v2017", "de-xrechnung-v3"], "DocNumber": "INV-0001", "IssueDate": "2026-05-09", "Currency": "EUR", "Supplier": { "Name": "Mustermann GmbH", "TaxID": { "Country": "DE", "Code": "111111125" } }, "Customer": { "Name": "Buyer GmbH", "TaxID": { "Country": "DE", "Code": "222222229" } }, "Lines": [ { "Quantity": "1.00", "Item": { "Name": "Consulting service", "Price": "1000.00" }, "Taxes": [{ "Cat": "VAT", "Rate": "standard" }] } ] } ``` ```json title="Response" { "status": "ACCEPTED", "message": "E-invoice request accepted for processing", "docId": 9021, "docNumber": "INV-0001", "queueId": 4173 } ``` The example above shows a minimum payload for Germany. The required fields and country-specific extensions differ for each supported country. See the [Request Payloads](/e-invoice/reference/payloads) section for the minimum payload example per country. ### Response fields | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The acknowledgement status from Staple. `ACCEPTED` indicates the payload was received and queued for processing. Validation and clearance run asynchronously. | | `message` | Human-readable confirmation message. | | `docId` | The Staple-assigned identifier for the document. Use this with the Get invoice status endpoint and the Search documents endpoint. | | `docNumber` | The invoice number provided in the submitted payload. | | `queueId` | The queue the document was placed into. | After submission, validation and clearance run asynchronously. To learn the outcome, either subscribe to the webhook events described in [Webhook notifications](#webhook-notifications) below, or pull the current status using the Get invoice status endpoint. ## Get invoice status `GET https://api.staple.io/v1/documents/{identifier}` Retrieve the current validation and clearance status of an e-invoice you previously submitted. Use this endpoint when you need to check the outcome on demand — for example, when reconciling with your accounting system or troubleshooting a specific invoice. The response is country-agnostic. Country-specific clearance evidence (such as MyInvois UUID, SDI IdentificativoSdI, or KSeF number) is returned inside the `clearance` block. Either the Staple `docId` (integer) returned by the Submit endpoint, or the `taxAuthorityReference` (string) such as a MyInvois UUID or KSeF number. The endpoint detects the type automatically. Bearer token, e.g. `Authorization: Bearer `. ```http title="Request — by Staple docId" GET https://api.staple.io/v1/documents/9021 Authorization: Bearer ``` ```http title="Request — by tax authority reference" GET https://api.staple.io/v1/documents/DE-XR-2026-AB12C345 Authorization: Bearer ``` ```json title="Response" { "docId": 9021, "docNumber": "INV-0001", "country": "DE", "validation": { "status": "passed", "completedAt": "2026-05-09T09:18:42Z", "faults": [] }, "clearance": { "status": "cleared", "completedAt": "2026-05-09T09:21:00Z", "source": "tax_authority", "reference": "DE-XR-2026-AB12C345", "validationLink": "https://example-tax-authority/invoices/DE-XR-2026-AB12C345" } } ``` ### `validation` block The validation block describes whether the submitted invoice passed Staple's internal validation and the tax authority's schema-level rules. | Field | Type | Description | | ------------- | ----------------- | ---------------------------------------------------------------------------------------- | | `status` | string | Validation outcome. One of `pending`, `passed`, or `failed`. | | `completedAt` | string (datetime) | ISO 8601 timestamp of when validation completed. `null` if still pending. | | `faults` | string\[] | List of validation faults when `status` is `failed`. Empty array when validation passed. | ### `clearance` block The clearance block describes whether the tax authority or the Peppol network has accepted the invoice and what evidence has been issued. | Field | Type | Description | | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | string | Clearance outcome. One of `pending`, `cleared`, or `failed`. `pending` means validation passed and Staple is currently submitting to the tax authority. | | `completedAt` | string (datetime) | ISO 8601 timestamp of when clearance completed. `null` if still pending. | | `source` | string | The system that performed the clearance. One of `tax_authority` or `peppol`. | | `reference` | string | The clearance reference issued by the source system — for example, the MyInvois UUID, SDI IdentificativoSdI, KSeF number, IRN, or Peppol Message ID. | | `validationLink` | string | A URL to a tax authority page that displays the cleared invoice, where applicable. `null` if the source system does not provide a public link. | ## Search documents `POST https://api.staple.io/v2/search/documents` Search for e-invoices you have issued. Filter by Staple document ID, your own invoice number, tax authority reference, status, or date range. This endpoint returns a paginated list of summary results — for full validation and clearance details on a specific invoice, use the Get invoice status endpoint. Bearer token, e.g. `Authorization: Bearer `. Filter criteria. See the fields below. Pagination control. See the fields below. ### `filter` object fields | Field | Type | Required | Description | | ------------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `documentIds` | integer\[] | Optional | Array of Staple document IDs to look up directly. | | `docNumbers` | string\[] | Optional | Array of seller invoice numbers (the `DocNumber` field from the submitted STAR payload). | | `taxAuthorityReferences` | string\[] | Optional | Array of tax authority references to look up directly (MyInvois UUID, SDI IdentificativoSdI, KSeF number, IRN, or Peppol Message ID). | | `queue` | integer\[] | Optional | Array of queue IDs to search within. | | `tab` | string\[] | Optional | Document state(s) to include. Allowed values: `RECEIVED`, `COMPLETED`, `REJECTED`, `EXPORTED`, `EXPORT_FAILED`. | | `uploadedAt` | object | Optional | Filter by upload date. Object with `from` and `to` fields, each formatted as `dd/mm/yyyy`. | | `completedAt` | object | Optional | Filter by completion date. Object with `from` and `to` fields, each formatted as `dd/mm/yyyy`. | | `rejectedAt` | object | Optional | Filter by rejection date. Object with `from` and `to` fields, each formatted as `dd/mm/yyyy`. | | `exportedAt` | object | Optional | Filter by export date. Object with `from` and `to` fields, each formatted as `dd/mm/yyyy`. | ### `pagination` object fields | Field | Type | Required | Description | | ------ | ------- | -------- | --------------------------------------- | | `skip` | integer | Required | Current page number (zero-indexed). | | `take` | integer | Required | Number of documents to return per page. | ```http title="Request — search by date range" POST https://api.staple.io/v2/search/documents Authorization: Bearer Content-Type: application/json { "filter": { "queue": [4173], "tab": ["COMPLETED"], "uploadedAt": { "from": "01/05/2026", "to": "31/05/2026" } }, "pagination": { "skip": 0, "take": 50 } } ``` ```http title="Request — look up by seller invoice number" POST https://api.staple.io/v2/search/documents Authorization: Bearer Content-Type: application/json { "filter": { "docNumbers": ["INV-0001", "INV-0002"] }, "pagination": { "skip": 0, "take": 50 } } ``` The underlying endpoint supports additional filters used elsewhere in the Staple platform (such as filename and content search) — those filters are omitted here as they are not commonly used in e-invoice workflows. ## Webhook notifications Subscribe to webhook events so your system is notified when Staple completes asynchronous processing of an e-invoice you submitted — without polling. Configure your webhook URL in **User Profile → Webhooks**. You will need the **Manage webhooks** permission to do this. Three e-invoice events are available: | Event | Fired when | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `document.validation_completed` | Staple's internal validation step completes. The payload indicates whether validation passed or failed. | | `document.cleared` | The tax authority or Peppol network confirms acceptance of the invoice and issues a clearance reference. | | `document.rejected_by_buyer` | The buyer has rejected an invoice you previously issued. Useful for AR teams to react to disputes or duplicate-invoice issues raised by buyers. | ### Webhook payload — `document.validation_completed` ```json { "event": "document.validation_completed", "payload": { "docId": 9021, "docNumber": "INV-0001", "country": "DE", "validation": { "status": "passed", "completedAt": "2026-05-09T09:18:42Z", "faults": [] } } } ``` When validation fails, the `faults` array contains the validation errors: ```json { "event": "document.validation_completed", "payload": { "docId": 9021, "docNumber": "INV-0001", "country": "DE", "validation": { "status": "failed", "completedAt": "2026-05-09T09:18:42Z", "faults": [ "Tax code mismatch for line 1", "Missing buyer reference for DE XRechnung" ] } } } ``` ### Webhook payload — `document.cleared` ```json { "event": "document.cleared", "payload": { "docId": 9021, "docNumber": "INV-0001", "country": "DE", "clearance": { "status": "cleared", "completedAt": "2026-05-09T09:21:00Z", "source": "tax_authority", "reference": "DE-XR-2026-AB12C345", "validationLink": "https://example-tax-authority/invoices/DE-XR-2026-AB12C345" } } } ``` ### Webhook payload — `document.rejected_by_buyer` ```json { "event": "document.rejected_by_buyer", "payload": { "docId": 9021, "docNumber": "INV-0001", "country": "DE", "rejection": { "rejectedAt": "2026-05-12T14:05:00Z", "reasons": ["duplicate", "incorrect_amount"] } } } ```