# Introduction Source: https://docs.nocotax.app/api-reference/introduction Example section for showcasing API endpoints See full Nocotax API documentation here # Invoices Lifecycle Source: https://docs.nocotax.app/billing-invoicing/invoices/lifecycle Understand invoice states and how to manage them from creation to payment. ## Invoice states ### DRAFT Invoice is being prepared. Can be modified or deleted. * No invoice number or date * Does not affect AP/AR balances * Can update amounts, line items, tax * Can be deleted ### FINALIZED Invoice is issued and official. Cannot be modified. * Has sequential invoice number * Has official invoice date * Due date calculated (if payment\_terms provided) * Affects AP/AR balances * Immutable - corrections require credit notes ### CANCELLED Invoice is voided (not yet implemented). ## State transitions ``` DRAFT → finalize() → FINALIZED ``` ### Creating an invoice All invoices start as DRAFT: ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "items": [ { "description": "Monthly Subscription", "quantity": 1, "unit_extratax_amount": 9900 } ] }' ``` ### Finalizing an invoice ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_123/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` What happens on finalization: 1. Invoice number assigned 2. Invoice date set to today 3. Due date calculated (from payment\_terms) 4. AP/AR balances updated 5. Invoice locked from changes Finalization is irreversible. Review carefully before finalizing. ## Payment status Finalized invoices track payment status: | Status | Description | | -------- | ---------------------------------------- | | **OPEN** | Due date not yet passed, unpaid | | **DUE** | Past due date, unpaid, or partially paid | | **PAID** | Fully paid | The `amount_remaining` field shows what's still owed. ## Working with finalized invoices ### Attaching payments ### Correcting errors Issue a credit note for finalized invoices: ```bash theme={null} curl https://api.nocotax.app/credit_notes \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "invoice_id": 'inv_123', "items": [ { "description": "Monthly Subscription", "quantity": 1, "unit_extratax_amount": 9900 } ] }' ``` ## Best practices * Review drafts carefully before finalizing * Finalize invoices promptly - don't leave in DRAFT * Use payment\_terms for automatic due date calculation * Issue credit notes for corrections, never modify finalized invoices * Track payment status for automated reminders # Invoices Overview Source: https://docs.nocotax.app/billing-invoicing/invoices/overview Understand how invoices work in Nocotax and how to use them for your platform's business transactions. ## What is an invoice? An invoice is a commercial document issued by a seller to a buyer that records a transaction between two parties. In Nocotax, invoices are the primary way to document: * Sales to customers (revenue) * Purchases from suppliers (costs) * Commission arrangements between platforms and merchants Every invoice in Nocotax represents a transaction between two organizations: a **supplier** (the party providing goods or services) and a **customer** (the party receiving them). ## Invoice flows Nocotax supports three invoice flows that determine the direction and purpose of the invoice: ### Sales flow The **sales flow** (`flow=sales`) represents invoices your platform issues to customers for goods or services you've sold. This is your outbound invoicing. ``` Your Platform (supplier) → Invoice → Customer ``` **Common use cases**: * SaaS subscription invoices * E-commerce order invoices * Service booking confirmations * Product sales **Key characteristics**: * Increases your accounts receivable (AR) * Represents revenue for your business * You are the supplier, customer is the buyer * You charge tax (if applicable) **Example**: Your platform sells a monthly subscription for €99 to a customer. ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "items": [ { "description": "Monthly Subscription", "quantity": 1, "unit_extratax_amount": 9900 } ] }' ``` ### Purchases flow The **purchases flow** (`flow=purchases`) represents invoices for goods or services you've purchased from suppliers. This is your inbound invoicing. ``` Supplier → Invoice → Your Platform (customer) ``` **Common use cases**: * Recording supplier invoices * Self-billing for marketplace payouts * Documenting costs and expenses * Tracking amounts owed to suppliers **Key characteristics**: * Increases your accounts payable (AP) * Represents costs for your business * Supplier is the issuer, you are the customer * You may be able to claim input tax **Example**: You receive an invoice from a hosting provider for €500. ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "purchases", "currency": "EUR", "supplier_id": "org_hosting_provider", "items": [ { "description": "Cloud Hosting - January", "quantity": 1, "unit_extratax_amount": 50000 } ] }' ``` ## Default vs explicit organization IDs When creating invoices, you can choose to specify organization IDs explicitly or let Nocotax use default values based on your account configuration. ### Default IDs (recommended) If you omit `supplier_id` or `customer_id`, Nocotax will use default values based on the flow: | Flow | Default supplier\_id | Default customer\_id | | ----------- | ------------------------ | ------------------------ | | `sales` | Your organization (self) | Must be specified | | `purchases` | Must be specified | Your organization (self) | ```bash theme={null} # Sales invoice - supplier_id defaults to your organization curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "items": [...] }' # Purchase invoice - customer_id defaults to your organization curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "purchases", "currency": "EUR", "supplier_id": "org_supplier_456", "items": [...] }' ``` ## Invoice structure Every invoice contains the following key components: ### Header information Basic invoice details: * **Flow**: Direction of the invoice (sales/purchases) * **Supplier**: Organization providing goods/services * **Customer**: Organization receiving goods/services * **document\_number**: Sequential invoice number (assigned when finalized) * **document\_date**: Invoice issue date (set when finalized) * **Currency**: Three-letter ISO currency code ### Line items Individual products or services on the invoice: * **description**: What's being sold * **quantity**: How many units * **unit\_extratax\_amount**: Price per unit excluding tax (in smallest currency unit) * **extratax\_amount**: Total line amount excluding tax (quantity × unit\_extratax\_amount) * **unit\_tax\_included\_amount**: Price per unit including tax * **tax\_included\_amount**: Total line amount including tax (quantity × unit\_tax\_included\_amount) * **taxes**: A breakdown of taxes at the line item level. ### Tax breakdown Detailed tax information per line and invoice: * **tax\_id**: Tax identifier * **percentage**: Tax rate applied * **jurisdiction**: Where the tax applies * **exemption**: Exemption reason if applicable ### Totals Calculated amounts: * **total\_extratax\_amount**: Sum of all line items before tax * **total\_tax\_amount**: Total tax across all line items * **total\_tax\_included\_amount**: Final amount including tax ### Payment information * **payment\_terms**: Payment terms configuration (type and days) * **due\_date**: When payment is expected * **payment\_status**: OPEN, DUE, PAID, PARTIALLY\_PAID * **amount\_due**: How much is still unpaid * **amount\_overpaid**: If a payment is recorded, the amount that exceeds the **amount\_remaining** at the time it is recorded * **amount\_paid**: How much is recorded as paid * **amount\_remaining**: How much is still unpaid See [Invoice Payments](/billing-invoicing/invoices/payments) for detailed payment management. ## Multi-currency support Nocotax supports invoices in multiple currencies. Each invoice must specify its currency: ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "USD", "customer_id": "org_customer_123", "items": [...] }' ``` **Important considerations**: * Currency is required when creating an invoice * All amounts on an invoice must be in the same currency * Currency cannot be changed after invoice creation ## Invoice numbering Invoice numbers are assigned automatically when you finalize an invoice. Nocotax ensures: * **Sequential numbering**: Each invoice gets the next available number * **Unique numbers**: No duplicates within your account * **Per-flow numbering**: Sales and purchases can have separate sequences * **Format customization**: Configure your numbering format in settings Example sequence: ``` INV-2025-001 INV-2025-002 INV-2025-003 ``` Draft invoices don't have document numbers. Numbers are assigned only when you finalize the invoice via the `document_number` field. ## Amounts in smallest currency unit All monetary values in Nocotax are specified in the smallest currency unit: | Currency | Smallest Unit | Example | | -------- | ---------------- | ------------- | | EUR, USD | Cents | €10.50 = 1050 | | GBP | Pence | £25.99 = 2599 | | JPY | Yen (no subunit) | ¥1,000 = 1000 | ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "EUR", "items": [ { "description": "Product", "quantity": 2, "unit_extratax_amount": 2950 } ] }' # total_extratax_amount: 5900 (€59.00) ``` This approach eliminates rounding errors and ensures precise calculations. ## Working with line items Invoices support up to 10 line items per invoice at creation: ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "Enterprise Plan - Annual", "quantity": 1, "unit_extratax_amount": 99000, "product": { "tax_code": "D10000000" // (Digital goods, SaaS) } }, { "description": "Additional Storage (100GB)", "quantity": 5, "unit_extratax_amount": 1000, "product": { "tax_code": "D10000000" // (Digital goods, SaaS) } }, { "description": "Premium Support", "quantity": 1, "unit_extratax_amount": 25000, "product": { "tax_code": "S10000000" // (Services) } } ] }' ``` ### Line item attributes Each line item includes: * `description` **(required)**: Text description of the item * `quantity` **(required)**: Number of units * `unit_extratax_amount` *(optional)*: Price per unit excluding tax. * `product.tax_code` *(optional)*: Tax category for automatic tax calculation **Calculated fields** (returned in response): * `extratax_amount`: quantity × unit\_extratax\_amount * `unit_tax_included_amount`: Unit price including tax * `tax_included_amount`: Total line amount including tax ## Tax information When automatic tax calculation is enabled, invoices include detailed tax breakdown: ```json theme={null} { "total_extratax_amount": 10000, "total_tax_amount": 2000, "total_tax_included_amount": 12000, "taxes": [ { "tax_id": "eu_vat", "percentage": 20.0, "jurisdiction": "FR", "taxable_amount": 10000, "tax_amount": 2000 } ] } ``` For cross-border transactions with exemptions: ```json theme={null} { "taxes": [ { "tax_id": "eu_vat", "percentage": 0.0, "jurisdiction": "ES", { "type": "REVERSE_CHARGE", "legal_notice": "Reverse Charge - Article 196 of Council Directive 2006/112/EC" }, "taxable_amount": 10000, "tax_amount": 0 } ] } ``` See [Managing Taxes](/billing-invoicing/invoices/taxes) for detailed tax configuration. ## Common patterns ### Pattern 1: Simple sales invoice ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "payment_terms": { "type": "NET", "days": 30 }, "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "Consulting Services - 10 hours", "quantity": 10, "unit_extratax_amount": 15000, "product": { "tax_code": "S10000000" } } ] }' # Then finalize curl https://api.nocotax.app/invoices/inv_123/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` ### Pattern 2: Recording a supplier invoice ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "purchases", "currency": "USD", "supplier_id": "org_supplier_789", "items": [ { "description": "Office Supplies", "quantity": 1, "unit_extratax_amount": 45000 } ] }' # Finalize and mark as paid curl https://api.nocotax.app/invoices/inv_456/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ curl https://api.nocotax.app/v1/invoices/inv_456/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ ``` You can use negative amounts in line items to represent deductions, credits, or refunds. If you need to manage documents for cancellations, refunds or chargebacks, use credit notes instead. ## Next steps Learn about invoice statuses and state transitions Configure tax calculations on invoices Track and reconcile invoice payments Explore the complete invoices API # Invoice Payments Source: https://docs.nocotax.app/billing-invoicing/invoices/payments Configure payment terms, track due dates, and reconcile payments on invoices. ## Overview Managing invoice payments involves three key aspects: * **Payment terms**: When payment is expected * **Payment tracking**: Monitoring what's been paid * **Payment reconciliation**: Matching payments to invoices ## Payment terms Payment terms define when an invoice must be paid. They consist of two components: a **type** and a **days** value. ### Payment term types #### NET Payment due a fixed number of days from the invoice date. ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "payment_terms": { "type": "NET", "days": 30 }, "items": [...] }' ``` **Examples**: * `NET 30`: Due 30 days from invoice date * `NET 15`: Due 15 days from invoice date * `NET 60`: Due 60 days from invoice date **Due date calculation**: ``` Invoice date: January 15, 2025 Payment terms: NET 30 Due date: February 14, 2025 ``` #### END\_OF\_MONTH Payment due a certain number of days after the end of the invoice month. ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "payment_terms": { "type": "END_OF_MONTH", "days": 30 }, "items": [...] }' ``` **Examples**: * `END_OF_MONTH 30`: Due the last day of the month of 30 days after * `END_OF_MONTH 0`: Due on the last day of the invoice month * `END_OF_MONTH 45`: Due the last day of the month of 45 days after **Due date calculation**: ``` Invoice date: January 15, 2025 Payment terms: END_OF_MONTH 30 +30 days: Feb 14, 2025 Due date: Feb 28, 2025 ``` ### Setting payment terms Payment terms can be set when creating an invoice: ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "payment_terms": { "type": "NET", "days": 45 }, "items": [ { "description": "Annual Subscription", "quantity": 1, "unit_extratax_amount": 120000 } ] }' ``` ### Due date calculation The `due_date` is automatically calculated when you finalize the invoice: ```bash theme={null} # Finalize the invoice curl https://api.nocotax.app/invoices/inv_123/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ # Response includes calculated due_date { "id": "inv_123", "status": "FINALIZED", "document_date": "2025-01-15", "due_date": "2025-02-28", "payment_terms": { "type": "NET", "days": 30 } } ``` If no payment terms are specified, the `due_date` is not calculated and payment tracking will be less meaningful. ## Payment status Once finalized, invoices track payment status automatically: ### OPEN Invoice is due but the due date hasn't passed yet. ```json theme={null} { "payment_status": "OPEN", "due_date": "2025-02-14", "total_tax_included_amount": 10000, "amount_remaining": 10000 } ``` ### DUE Invoice is past its due date and still unpaid. ```json theme={null} { "payment_status": "DUE", "due_date": "2025-01-10", "total_tax_included_amount": 10000, "amount_remaining": 10000 } ``` ### DUE (PARTIALLY PAID) Invoice has received partial payment, but is still due ```json theme={null} { "payment_status": "DUE", "total_tax_included_amount": 10000, "amount_paid": 6000, "amount_remaining": 4000 } ``` ### PAID Invoice is fully paid. ```json theme={null} { "payment_status": "PAID", "total_tax_included_amount": 10000, "amount_paid": 10000, "amount_remaining": 0 } ``` ## Attaching payments Record payments received or made on an invoice. ### Full payment Mark an invoice as fully paid: ```bash theme={null} curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{}' ``` This marks the invoice as paid with: * Amount: Full `amount_remaining` * Payment date: Current date * No external reference ### Partial payment or detailed record Record a partial payment with specific amount: ```bash theme={null} curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "transaction_data": { "amount": 5000, "currency": "EUR", "transaction_type": "payment", "reference": "PAYxPSP-ch_abc123" // Link to external payment system } }' ``` ### Payment parameters All these parameters must be nested into a `transaction_data` field. | Parameter | Type | Description | | ------------------ | ------- | ---------------------------------------------------------------------------------- | | `amount` | integer | Payment amount in smallest currency unit (optional, defaults to amount\_remaining) | | `currency` | string | Payment currency | | `reference` | string | External payment reference (e.g., Stripe charge ID, bank transfer reference) | | `transaction_type` | string | Payment, Transfer | ## Payment reconciliation Reconciliation is the process of matching payments to invoices and ensuring balances are accurate. ### Automatic reconciliation When you attach a payment, Nocotax automatically: 1. **Updates amount\_remaining**: Deducts payment amount 2. **Updates payment\_status**: Changes to PAID or PARTIALLY\_PAID 3. **Adjusts AP/AR balances**: Updates organization balances 4. **Records payment history**: Tracks all payments on the invoice ### Multiple payments An invoice can have multiple payments: ```bash theme={null} # First partial payment curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "transaction_data": { "amount": 3000, "currency": "EUR", "transaction_type": "payment", "reference": "PAYMENT_1" } }' # Second partial payment curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "transaction_data": { "amount": 7000, "currency": "EUR", "transaction_type": "payment", "reference": "PAYMENT_2" } }' ``` ## Credit notes and payment balance Credit notes affect the payment balance: ```bash theme={null} # Original invoice: €100 # Customer pays: €100 # Status: PAID # Issue credit note: -€20 curl https://api.nocotax.app/credit_notes \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "invoice_id": "inv_123", "items": [ { "description": "Correction", "quantity": 1, "unit_extratax_amount": -2000 } ] }' # After finalizing credit note: # amount_remaining: -€20 (credit balance) # Status: PAID (but with credit to refund or apply) ``` The credit note creates a credit balance that can be: * Refunded to the customer * Applied to future invoices * Tracked as credit owed See [Credit Notes](/billing-invoicing/invoices/credit-notes) for details. ## Best practices * Always set payment terms when creating invoices for accurate due date tracking * Use `NET` terms for fixed payment periods * Use `END_OF_MONTH` terms for B2B customers who process payments monthly * Include payment references to link to external payment systems * Record partial payments as they're received * Monitor `payment_status` to identify overdue invoices # Managing Taxes on Invoices Source: https://docs.nocotax.app/billing-invoicing/invoices/taxes Learn how to configure and calculate taxes on invoices, from automatic calculations to manual control. ## Overview Nocotax provides flexible tax management for invoices, allowing you to either let the system automatically calculate taxes based on registrations and rules, or manually specify tax rates for complete control. Proper tax configuration ensures: * Compliance with local tax regulations * Accurate tax collection and reporting * Correct input tax recovery on purchases * Simplified tax filing and reconciliation ## Tax calculation approaches Nocotax supports two approaches to tax calculation on invoices: ### Automatic tax calculation (recommended) The system automatically determines applicable tax rates and calculates tax amounts based on: * Your tax registrations * Customer/supplier tax registrations * Transaction type (B2B vs B2C) * Product tax codes * Applicable tax rules **When to use**: Most scenarios, especially for platforms selling across multiple jurisdictions. ### Manual tax calculation You specify exact tax rates and jurisdictions for each invoice, overriding automatic calculation. **When to use**: Special cases, legacy data migration, or when you have custom tax calculation logic. By default, taxes are not calculated automatically. You must explicitly enable automatic tax calculation or provide manual tax configuration. ## Automatic tax calculation Enable automatic tax calculation when creating an invoice: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "SaaS Subscription", "quantity": 1, "unit_extratax_amount": 9900, "product": { "tax_code": "D10000000" } } ] }' ``` ### How automatic calculation works When `automatic_tax_calculation.enabled: true`, Nocotax: 1. **Identifies the tax jurisdiction**: Based on supplier and customer locations 2. **Determines tax registration status**: Checks if you're registered where tax applies 3. **Applies tax rules**: Uses B2B vs B2C rules, reverse charge, exemptions, etc. 4. **Calculates rates**: Applies the correct tax rate for each line item 5. **Computes totals**: Calculates line-level and invoice-level tax amounts ### Tax codes Tax codes categorize your products or services for tax purposes. They help Nocotax apply the correct tax treatment: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "Software License", "quantity": 1, "unit_extratax_amount": 10000, "product": { "tax_code": "D10000000" } }, { "description": "General furniture", "quantity": 3, "unit_extratax_amount": 999, "product": { "tax_code": "P10000000" } }, { "description": "Consulting", "quantity": 1, "unit_extratax_amount": 50000, "product": { "tax_code": "S10000000" } } ] }' ``` **Standard tax codes**: * `D10000000`: Digital goods and services (SaaS, software, digital content) * `S10000000`: Services (consulting, professional services) * `P10000000`: Physical goods (products, merchandise) Tax codes are optional when automatic calculation is enabled. If omitted, Nocotax uses the default tax treatment for digital goods. ### Tax determination factors Automatic tax calculation considers multiple factors: #### 1. Supplier tax registrations Your tax registrations determine where you can charge tax: ``` You're registered for VAT in France and Germany Sales to French customers: Charge French VAT Sales to German customers: Charge German VAT Sales to Spanish customers: Depends on registration and thresholds ``` See [Tax Registrations Configuration](/tax-registrations) for setup details. #### 2. Customer tax registrations Customer tax status affects tax treatment: | Scenario | Tax Treatment | | ----------------------------------------- | ----------------------------- | | B2C (no VAT number) | Charge VAT at applicable rate | | B2B (valid VAT number, different country) | Reverse charge (0% VAT) | | B2B (valid VAT number, same country) | Usually charge VAT | | B2B (invalid VAT number) | Treat as B2C, charge VAT | #### 3. Transaction location Where the transaction is deemed to take place: * **Goods**: Usually where goods are delivered * **Services**: Depends on service type and recipient location * **Digital services**: Customer's location #### 4. Product type Different products may have different tax rates: * Standard rate (e.g., 20% in France) * Reduced rate (e.g., 5.5% for books in France) * Super-reduced rate (e.g., 2.1% for essentials in Spain) * Zero rate * Exempt ### Result of automatic calculation After automatic calculation, the invoice contains calculated tax data: ```bash Request theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "SaaS Subscription", "quantity": 1, "unit_extratax_amount": 9900, "product": { "tax_code": "D10000000" } } ] }' ``` ```json Response theme={null} { "id": "inv_123", "flow": "sales", "currency": "EUR", "total_extratax_amount": 9900, "total_tax_amount": 1980, "total_tax_included_amount": 11880, "taxes": [ { "tax_id": "eu-vat", "jurisdiction": "FR", "percentage": 20.0, "taxable_amount": 9900, "tax_amount": 1980 } ] } ``` ## Manual tax calculation For complete control over tax rates, disable automatic calculation and specify tax manually at the invoice level: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": false }, "items": [ { "description": "Product", "quantity": 1, "unit_extratax_amount": 10000, "taxes": [ { "jurisdiction": "FR", "percentage": 20, "tax_id": "eu-vat" } ], }, { "description": "Service", "quantity": 2, "unit_extratax_amount": 5000, "taxes": [ { "jurisdiction": "FR", "percentage": 20, "tax_id": "eu-vat" } ], } ] }' ``` The tax configuration applies to all line items on the invoice. Nocotax calculates the tax amounts based on the rates you provide. ### Explicit tax registration IDs When using manual tax calculation, you can specify which tax registration numbers to use: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "supplier_tax_registration_id": "taxreg_your_de_vat", "customer_tax_registration_id": "taxreg_customer_de", "automatic_tax_calculation": { "enabled": false }, "items": [...] }' ``` Explicit tax registration IDs only work with manual tax calculation. You cannot specify registration IDs when automatic calculation is enabled. ### When to use manual tax **Valid use cases**: * Importing historical invoices with known tax rates * Handling unusual tax situations not covered by rules * Applying custom tax calculations from external systems * Zero-rating or exempting specific transactions manually **Risks and considerations**: * You're responsible for tax accuracy * No automatic compliance with tax rules * Requires careful manual review * May complicate tax reporting Manual tax calculation bypasses Nocotax's compliance features. Use automatic calculation whenever possible to ensure accuracy and compliance. ### Example: Zero-rated transaction ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": false }, "items": [ { "description": "Export goods", "quantity": 1, "unit_extratax_amount": 50000, "taxes": [ { "jurisdiction": "FR", "percentage": 0, "tax_id": "eu-vat", "tax_exemption": { "type": "EXPORT" } } ], } ] }' ``` ## Tax on different invoice flows Tax treatment varies by invoice flow: ### Sales invoices (output tax) Tax you charge to customers on sales: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": true }, "items": [...] }' ``` * You collect tax from customers * Tax increases the invoice total * You must remit collected tax to authorities * Reported on your VAT return as "output tax" or "sales tax" ### Purchase invoices (input tax) Tax charged to you on purchases: ```bash theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "purchases", "currency": "EUR", "supplier_id": "org_supplier_456", "automatic_tax_calculation": { "enabled": true }, "items": [...] }' ``` * Supplier charges you tax * Tax increases what you pay * You may be able to reclaim this tax (input tax deduction) * Reported on your VAT return as "input tax" ## Common scenarios ### Scenario 1: EU B2B sale with reverse charge ```bash Request theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_german_business", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "Software License", "quantity": 1, "unit_extratax_amount": 10000, "product": { "tax_code": "D10000000" } } ] }' ``` ```json Response theme={null} { "id": "inv_123", "total_extratax_amount": 10000, "total_tax_amount": 0, "total_tax_included_amount": 10000, "taxes": [ { "tax_id": "eu-vat", "jurisdiction": "FR", "percentage": 0, "tax_exemption": { "type": "REVERSE_CHARGE" }, "taxable_amount": 10000, "tax_amount": 0 } ] } ``` ### Scenario 2: EU B2C sale via OSS ```bash Request theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_spanish_consumer", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "E-book", "quantity": 1, "unit_extratax_amount": 999, "product": { "tax_code": "D10000000" } } ] }' ``` ```json Response theme={null} { "id": "inv_456", "total_extratax_amount": 999, "total_tax_amount": 40, "total_tax_included_amount": 1039, "taxes": [ { "tax_id": "eu-vat", "jurisdiction": "ES", "percentage": 4.0, "taxable_amount": 999, "tax_amount": 40 } ] } ``` ### Scenario 3: Manual tax for specific rate ```bash Request theme={null} curl -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ https://api.nocotax.app/invoices \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "currency": "EUR", "customer_id": "org_customer_123", "automatic_tax_calculation": { "enabled": false }, "items": [ { "description": "Books", "quantity": 3, "unit_extratax_amount": 1500, "taxes": [ { "jurisdiction": "FR", "percentage": 5.5, "tax_id": "eu-vat" } ] } ] }' ``` ```json Response theme={null} { "id": "inv_789", "total_extratax_amount": 4500, "total_tax_amount": 248, "total_tax_included_amount": 4748, "taxes": [ { "tax_id": "eu-vat", "jurisdiction": "FR", "percentage": 5.5, "taxable_amount": 4500, "tax_amount": 248 } ] } ``` ## Best practices Unless you have a specific reason to manually control tax, enable automatic calculation. It ensures: * Accurate rates based on current tax rules * Proper B2B vs B2C treatment * Correct reverse charge application * Up-to-date compliance While optional, providing tax codes improves calculation accuracy, especially for products with reduced rates or special treatment: * `tax_code: 'ebooks'` may apply reduced rates * `tax_code: 'medical'` may apply exemptions * `tax_code: 'export'` may apply zero rates Ensure your tax registrations in Nocotax match your actual registrations with tax authorities. Update them immediately when: * You register in a new jurisdiction * Registration numbers change * Registration types change (e.g., standard to OSS) For B2B sales, ensure customers provide valid tax registration numbers. Invalid numbers can result in: * Incorrect reverse charge application * Charging VAT when not required * Compliance issues during audits Let Nocotax automatically select the appropriate tax registration numbers unless you have a specific reason to override. The default behavior is designed to ensure compliance. ## Frequently Asked Questions No, the tax calculation method is locked. You would need to create a new invoice with the desired method if you need to change this behaviour. If you enable automatic calculation but don't specify tax codes, Nocotax uses default tax treatment based on your business type and applicable rules. For manual calculation, omitting tax amounts means zero tax. Tax-exempt status is typically handled automatically when the customer has an appropriate tax registration number (e.g., charity VAT number). For special cases, you can use manual tax calculation with zero tax amounts. Yes. Invoices with automatic calculation include a `taxes` field showing jurisdictions, rates, taxable amounts, and tax amounts. This provides transparency into the calculation. First, verify your tax registrations, customer information, and tax codes are correct. If the calculation still seems wrong, contact support with details. You can temporarily use manual calculation as a workaround. No. Default behavior is recommended—Nocotax automatically selects the appropriate tax registrations. Only specify explicitly when you have multiple registrations and need precise control. # Organizations Overview Source: https://docs.nocotax.app/billing-invoicing/organizations/overview Learn about the core concept of organizations in Nocotax and how they represent business entities. ## What is an organization? An organization in Nocotax represents a business entity - either a company or an individual person. Every organization can participate in transactions as either a buyer or seller of goods and services. Organizations are the foundation of invoicing in Nocotax: * Every invoice has a **supplier** (seller) and **customer** (buyer) * Both are represented as organizations * Organizations track tax registrations, addresses, and balances ## Organization types: self vs external Every organization has an `ownership` field that determines its type: ### Your organizations (ownership=self) This are **your platform's business entities**. You currently have one self organization per mode (testmode and livemode). ```bash theme={null} # Your organization is automatically created during onboarding curl https://api.nocotax.app/organizations?ownership=self \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` **Characteristics**: * Represents your company * Only one per mode (for the moment) * Cannot be deleted * Where you configure your tax registrations * Your identity on invoices ### External organizations (ownership=external) These are **the entities you do business with** - your customers and suppliers. ```bash theme={null} # Create an external organization curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "roles": ["BUYER"], "name": "Acme Corp", "billing_address": { "country": "FR" } }' ``` **Characteristics**: * Represent customers, suppliers, partners * Unlimited number * Can be created, updated, deleted * Each has specific roles * Can have their own tax registrations ## Organization roles External organizations have roles that define their relationship with your platform: ### BUYER role Organizations you sell to. They buy from your platform. ```bash theme={null} curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "roles": ["BUYER"], "name": "Customer Inc", "billing_address": { "country": "FR" } }' ``` **Used for**: * Sales invoices (you invoice them) * Tracking accounts receivable (money owed to you) * Customer management ### MERCHANT role Organizations you buy from - your suppliers, vendors, or marketplace sellers. ```bash theme={null} curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "roles": ["MERCHANT"], "name": "Supplier Co", "billing_address": { "country": "FR" } }' ``` **Used for**: * Purchase invoices (they invoice you, or you self-bill) * Tracking accounts payable (money you owe them) * Supplier management * Marketplace seller payouts ### Both roles An organization can have both CUSTOMER and MERCHANT roles simultaneously: ```bash theme={null} curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "roles": ["CUSTOMER", "MERCHANT"], "name": "Partner Company", "billing_address": { "country": "FR" } }' ``` **Example**: A business partner where you both buy services from them and sell services to them. The role determines what the organization **can** do, not what they're actively doing. You can set the role even before any transactions occur. ## Organizations in invoicing Organizations play two positions on every invoice: supplier and customer. ### The supplier\_id The organization providing goods or services (the seller). **In sales invoices**: Usually your platform ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "customer_id": "org_customer_123", // Supplier ID is your platform "items": [...] }' ``` **In purchase invoices**: The external supplier ```bash theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "purchases", "supplier_id": "org_supplier_456", // Customer ID is your platform "items": [...] }' ``` ### The customer\_id The organization receiving goods or services (the buyer). **In sales invoices**: Your customer ```bash theme={null} # supplier_id = your platform # customer_id = your customer ``` **In purchase invoices**: Your platform ```bash theme={null} # supplier_id = external supplier # customer_id = your platform ``` ### Role vs position | Role | Can be supplier\_id? | Can be customer\_id? | | -------------------- | -------------------- | -------------------- | | Your platform (self) | ✓ Yes (sales) | ✓ Yes (purchases) | | BUYER | ✗ No\* | ✓ Yes | | MERCHANT | ✓ Yes | ✗ Yes\*\* | | Both roles | ✓ Yes | ✓ Yes | \*Unless the organization has both roles \*\* In commission model An organization must have the appropriate role for its position on the invoice: * To be a `supplier_id`: needs MERCHANT role (or be your platform) * To be a `customer_id`: needs BUYER or MERCHANT role (or be your platform) ## Organization hierarchy ``` Account ├── Mode: testmode │ ├── Organizations (ownership=self) - Your platform │ └── Organizations (ownership=external) │ ├── BUYER orgs │ ├── MERCHANT orgs │ └── Dual-role orgs │ └── Mode: livemode ├── Organizations (ownership=self) - Your platform └── Organizations (ownership=external) ├── BUYER orgs ├── MERCHANT orgs └── Dual-role orgs ``` Data is completely isolated between testmode and livemode. ## Common patterns ### E-commerce platform * Your platform: `ownership=self` * Customers: `ownership=external`, `role=BUYER` * Invoices: You → Customers (sales flow) ### Marketplace (commission agent) * Your platform: `ownership=self` * Sellers: `ownership=external`, `role=MERCHANT` * Buyers: `ownership=external`, `role=BUYER` * Commission invoices: Your platform → Sellers (commission flow) * Optional: Sellers → Buyers (white label invoicing) ### Buy and resell (undisclosed agent) * Your platform: `ownership=self` * Suppliers: `ownership=external`, `role=MERCHANT` * Customers: `ownership=external`, `role=CUSTOMER` * Purchase invoices: Suppliers → Your platform (purchases flow) * Sales invoices: Your platform → Customers (sales flow) ### Service platform with suppliers * Your platform: `ownership=self` * Service providers: `ownership=external`, `role=MERCHANT` * Customers: `ownership=external`, `role=CUSTOMER` * May need dual-role if providers also buy services from you ## Key attributes Every organization can have: | Attribute | Description | | --------------------- | ------------------------------------------- | | `name` | Full legal entity name (business or person) | | `billing_address` | Invoicing address | | `tax_registrations[]` | List of tax registrations | See [Tax Registrations](/billing-invoicing/organizations/tax-registrations) for detailed attribute information. ## Best practices * Set clear, descriptive names for easy identification * Assign roles when creating organizations, even before first transaction * Use dual roles for partners you both buy from and sell to * Keep tax numbers and addresses updated * Use metadata to link to external systems (Stripe, CRM, etc.) ## Next steps Configure tax registrations for organizations Organizations API documentation # Tax Registrations Source: https://docs.nocotax.app/billing-invoicing/organizations/tax-registrations Configure tax registrations for external organizations to enable accurate tax calculations. ## Overview External organizations can have their own tax registrations, just like your platform. These registrations are crucial for: * Determining B2B vs B2C tax treatment * Enabling reverse charge on cross-border transactions * Calculating input tax on purchases * Validating tax compliance ## When to add tax registrations ### For CUSTOMER organizations Add tax registrations when customers are businesses with VAT/tax numbers: ```bash theme={null} curl https://api.nocotax.app/organizations/org_customer_123/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "country": "DE", "number": "DE123456789", "type": "standard" }' ``` **Why this matters**: * Without tax registration → Treated as B2C, charged VAT * With valid tax registration → B2B treatment, often reverse charge (0% VAT) ### For MERCHANT organizations Add tax registrations for suppliers based on your platform model: **Undisclosed agents (buy/resell)**: Most transactions are B2B with reverse charge on cross-border purchases, and charge local tax on domestic transactions. Use `registration_type: standard`: ```bash theme={null} curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "country": "FR", "number": "FR98765432109", "type": "standard" }' ``` **Traditional marketplaces (commission agent)**: Depends on whether merchants sell B2C through your platform. They may need multiple registration types if selling across borders. See [Tax Registrations Configuration](/taxes/registrations/eu-types) for details on OSS and other schemes. ## Registration types for external organizations ### CUSTOMER role: Input tax only Customers don't bill through your platform - they only receive invoices from you. Use `standard` registration type: ```bash theme={null} # B2B customer curl https://api.nocotax.app/organizations/org_customer_123/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "IT", "number": "IT12345678901", "type": "standard" }' ``` This enables: * Reverse charge on eligible transactions * Input tax calculation (though not directly relevant for customers) * B2B invoice treatment ### MERCHANT role: Depends on business model Merchants may need different registration types based on how they operate: **Standard registration** (most common): ```bash theme={null} curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "ES", "number": "ES12345678Z", "type": "standard" }' ``` **OSS or other schemes**: If merchants on a traditional marketplace sell B2C across borders, they may have OSS registrations. See [Tax Registrations Configuration](/taxes/registrations/eu-types) for registration type details. For undisclosed agents, merchants typically only need standard registrations since transactions are B2B between your platform and the supplier. ## Listing organization tax registrations ```bash theme={null} # Get all registrations for an organization curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} # Get specific registration curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations/taxreg_abc123 \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` ## Updating tax registrations ```bash theme={null} curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations/taxreg_abc123 \ -X PATCH \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "number": "DE987654321" }' ``` ## Deleting tax registrations ```bash theme={null} curl https://api.nocotax.app/organizations/org_supplier_456/tax_registrations/taxreg_abc123 \ -X DELETE \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ ``` ## Common scenarios ### Scenario 1: B2B customer in EU ```bash theme={null} # Create organization curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "roles": ["BUYER"], "name": "German Business GmbH", "billing_address": {"country": "DE"} }' # Add tax registration curl https://api.nocotax.app/organizations/org_created_above/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "DE", "number": "DE123456789", "type": "standard" }' ``` Result: Cross-border sales to this customer will use reverse charge (0% VAT). ### Scenario 2: Marketplace seller (merchant) ```bash theme={null} # Create seller organization curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "roles": ["MERCHANT"], "name": "Seller Shop Ltd", "billing_address": {"country": "FR"} }' # Add standard VAT registration curl https://api.nocotax.app/organization/org_created_above/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "FR", "number": "FR98765432109", "type": "standard" }' # Add OSS VAT registration for cross-border EU B2C sales curl https://api.nocotax.app/organization/org_created_above/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "FR", "number": "FR98765432109", "type": "oss_eu" }' ``` ### Scenario 3: Buy/resell supplier ```bash theme={null} # Supplier organization curl https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "roles": ["MERCHANT"], "name": "Wholesale Supplier Inc", "billing_address": {"country": "NL"} }' # Add registration (B2B with your platform) curl https://api.nocotax.app/organization/org_supplier_created/tax_registrations \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -d '{ "country": "NL", "number": "NL123456789B01", "standard": "standard" }' ``` ## Impact on invoicing Tax registrations directly affect invoice tax calculations: ### With tax registration (B2B) ``` Your Platform (FR) → Invoice → Customer (DE, has VAT number) Result: Reverse charge, 0% VAT ``` ### Without tax registration (B2C) ``` Your Platform (FR) → Invoice → Customer (DE, no VAT number) Result: VAT charged at appropriate rate ``` See [Managing Taxes on Invoices](/invoices/taxes) for detailed tax calculation rules. ## Best practices * Always add tax registrations for B2B customers to enable reverse charge * Use `standard` registration type for CUSTOMER organizations * For MERCHANT organizations, registration type depends on your business model * Keep registrations up to date - invalid numbers affect tax treatment * Don't add registrations for B2C customers (individuals without tax numbers) ## Further reading For comprehensive information on registration types: * [Tax Registrations Configuration](/taxes/registrations/eu-types) - Detailed guide on registration types and schemes * [Platform Models](/platform-models) - Understand commission agent vs buy/resell * [Undisclosed Agent Flow](/undisclosed-agents/overview) - B2B dynamics in buy/resell model ## Next steps Complete guide on registration types How tax is calculated on invoices Managing customers and merchants Tax Registrations API # Start developing Source: https://docs.nocotax.app/development Get started with the Nocotax API ## Get started in three steps Get Nocotax API running locally and make your first API calls. ### Step 1: Create your Nocotax account and finish the setup process Follow the onboarding flow to enter your account details such as the default timezone and currency, the billing information of your own organization, and the tax configuration for your organization. Unsure of your current tax configuration setup? You can still add/remove tax registrations later on. ### Step 2: Send your first API request By default, all accounts have a total of three API credentials: | Type | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Account ID` | An unique ID referencing your account. It's used in the Basic Auth Scheme for API requests as the ID credential. | | `Test API Key` | Authenticate requests on your server when you’re testing in a sandbox. By default, you can use this key to perform any API request without restriction. Reserve this key for testing and development to make sure you don’t accidentally modify your live data. | | `Live API Key` | Authenticate requests on your server when in live mode. Don’t expose this key on a website or embed it in a mobile application. You can only use this key to perform any API request after subscribing to a paid plan | Your credentials are stored on the [Developers settings](https://app.nocotax.app/settings/developers/credentials) tab in the dashboard. Try changing the primary color to see an immediate difference! You can begin exploring Nocotax APIs using the HTTPs client of your choice (curl, postman...), along with your API keys (see below). Operating in sandbox environment, you don't have to worry about altering production data when doing the following tests. 1. To create an organization using the Nocotax API, send the following API request ```bash theme={null} curl -X POST https://api.nocotax.app/organizations \ -u ${ACCOUNT_ID}:${TEST_API_KEY} \ -d 'name=Test Customer' \ -d 'roles[]=BUYER' \ -d 'billing_address[country]=FR' ``` 2. If everything worked, you should see a response, with a JSON body embeded, containing the ID of the newly created organization: ```json theme={null} { "id": "org_xxxxxxxxxxxx", "object": "organization", // ... } ``` **Need help?** See our [full API documentation](https://app.nocotax.app/apidoc). # Overview Source: https://docs.nocotax.app/index Create an account and learn how to build with Nocotax. ## Create an account Set up a Nocotax account and immediately start building your integration. ## Configure your account Learn how to configure Nocotax properly to ensure accurate tax calculations Learn how to configure Nocotax properly to ensure accurate tax calculations ## Start building Learn about API authentication and send your first API request. Browse full API documentation ## Common use cases ### Undisclosed agent platforms (buy-resell models) Issue invoices to customers for goods or services sold through your platform as an undisclosed agent. Record purchases from suppliers using self-billing, where your platform issues purchase invoices on behalf of suppliers # Platform Models Source: https://docs.nocotax.app/platform-models Configure your platform's economic model to match how your business operates and handle invoicing automatically. ## Overview Nocotax supports multiple platform business models, allowing you to configure how your platform handles transactions between buyers, sellers and your platform. You can select one or both models depending on your business needs: * **Commission Agent**: Your platform facilitates transactions and earns commissions * **Buy and Resell (Undisclosed Agent)**: Your platform purchases goods/services and resells them Choosing the right platform model ensures accurate invoicing, tax calculations, and financial reporting that matches your business operations. ## Platform models explained ### Commission Agent In the commission agent model, your platform acts as an intermediary between buyers and sellers. You facilitate transactions but don't take ownership of the goods or services. **How it works**: * Sellers list products/services on your platform * Customers purchase from sellers through your platform * You earn a commission on each transaction * The seller remains the merchant of record (transparent model) **Key features**: * ✓ You take commissions upon sales and bill sellers periodically or at every sale * ✓ You can invoice customers on behalf of sellers (if enabled) * Ideal for: Marketplaces, booking platforms, service aggregators **Example**: A freelance marketplace where designers offer services. The platform takes a 15% commission on each project completed. ### Buy and Resell In the buy and resell model (also known as undisclosed agent), your platform purchases goods or services from suppliers and resells them to customers under your own name. The customer sees only your platform as the seller, not the original supplier. **How it works**: * You purchase inventory or services from suppliers * You set your own prices and markup * You invoice customers directly as the seller * Suppliers invoice you (or you use self-billing) **Key features**: * ✓ Total price and margin control * ✓ You directly invoice the buyer * ✓ You are billed by suppliers, but can automate through self-billing * Ideal for: E-commerce platforms, wholesale resellers, fulfillment services **Example**: An online electronics store that purchases devices from manufacturers and resells them with a markup to customers. #### Handling complex product relationships The buy and resell model doesn't require a one-to-one match between what you purchase and what you sell. Your platform can handle various product relationship scenarios: **One-to-many**: You purchase one item from a supplier and split it into multiple products sold separately. * *Example*: Buy wholesale fabric by the roll, sell it by the yard to multiple customers **Many-to-one**: You purchase multiple items from one or more suppliers and combine them into a single product offering. * *Example*: Purchase components from various suppliers and assemble them into a complete product kit **Assembly/bundling**: You purchase individual items and create bundles or assembled products. * *Example*: Buy a laptop, mouse, and bag from different suppliers and sell them as a "productivity bundle" **Value-added services**: You purchase goods and add services before reselling. * *Example*: Buy electronics, add warranty services and configuration, then sell as a package In these scenarios, Nocotax allows you to: * Create purchase invoices for each supplier transaction * Create sales invoices that may not directly correspond to a single purchase * Track costs and revenue independently * Calculate margins accurately across complex product relationships You can enable both models simultaneously if your platform operates in multiple ways. For instance, some products might be sold on commission while others are purchased and resold. ## Configuration process Setting up your platform models is a two-step process during onboarding: ### Step 1: Select platform models Choose which economic model(s) your platform uses. **During onboarding**: 1. Navigate to **Select Platform Models** (step 3 of onboarding) 2. Review the available models and their descriptions 3. Select **Commission Agent**, **Buy and Resell**, or both 4. Click **Continue** to proceed to configuration Adjust the caption and image of your Frame component here. ### Step 2: Configure billing settings Once you've selected your platform model(s), configure how invoicing works for each model. ## Commission Agent configuration Configure how and when you invoice sellers for commissions earned. Commission Agent ### Commission invoice frequency Choose how often you want to generate invoices for commissions: | Frequency | Description | Best For | | ------------------------ | --------------------------------------------------------------------------- | --------------------------------------------- | | **At transaction level** | Generates an invoice for each commission immediately | High-value transactions, low volume platforms | | **Daily** | Generates a single invoice aggregating all daily commissions per merchant | Platforms with steady daily activity | | **Weekly** | Generates a single invoice aggregating all weekly commissions per merchant | Medium-volume platforms with regular activity | | **Monthly** | Generates a single invoice aggregating all monthly commissions per merchant | High-volume platforms, established merchants | For most platforms, monthly invoicing provides the best balance between administrative overhead and cash flow management. ### Monthly invoice settings If you select **Monthly** frequency, you'll need to specify: **Day of month**: Choose which day invoices are generated (1st-28th of each month). Common choices: * **1st**: Invoice at the start of the month for previous month's activity * **5th**: Allow time for transaction disputes/refunds before invoicing * **15th**: Mid-month invoicing for better cash flow distribution ## Buy and Resell configuration Configure how you handle purchase invoices from suppliers (self-billing). Buy Resell ### Self-billing aggregation frequency Choose how often you want to generate purchase invoices for supplier payouts: | Frequency | Description | Best For | Availability | | ------------------------ | ------------------------------------------------------------------------- | ------------------------------------ | ------------ | | **At transaction level** | Generates a purchase invoice for each order/transaction | High-value items, low volume | ✓ Available | | **Daily** | Generates a single invoice aggregating all daily purchases per supplier | Fast-moving inventory, daily payouts | Coming soon | | **Weekly** | Generates a single invoice aggregating all weekly purchases per supplier | Regular payout schedules | Coming soon | | **Monthly** | Generates a single invoice aggregating all monthly purchases per supplier | Established supplier relationships | Coming soon | Currently, only **at transaction level** is available for buy and resell self-billing. Aggregated frequencies (daily, weekly, monthly) are coming soon. ## Combining both models If your platform operates using both models, you can enable them simultaneously: ### Example: Hybrid marketplace **Scenario**: Your platform sells some products on commission (from third-party sellers) and also stocks and resells other products directly. **Configuration**: 1. Enable both **Commission Agent** and **Buy and Resell** models 2. Configure commission invoicing for marketplace sellers (e.g., monthly) 3. Configure self-billing for direct purchases (e.g., transaction level) ## How invoicing works with each model ### Commission Agent invoicing flow 1. **Customer purchases** from a seller through your platform 2. **Transaction completes** and commission is calculated. Sync the commission to Nocotax through API. 3. **At the configured frequency** (daily, weekly, monthly, or per transaction): * Nocotax generates a commission invoice * Invoice shows commission owed by the seller to your platform * Invoice is marked with `flow=commissions`, and finalized ### Buy and Resell invoicing flow #### Customer invoicing (sales) 1. **Customer purchases** from your platform 2. **Immediately** or at your discretion: * You create a sales invoice * Invoice shows amount owed by customer to your platform * Invoice is marked with `flow=sales` 3. **You finalize** and record payment #### Supplier billing (purchases) 1. **You purchase** or facilitate a sale that requires supplier payout 2. **At the configured frequency** (currently transaction level): * You generate a self-billed purchase invoice * Invoice shows amount owed to the supplier by your platform * Invoice is marked with `flow=purchases` 3. **You finalize** and pay the supplier ## Best practices High-volume platforms benefit from less frequent invoicing (weekly/monthly) to reduce administrative overhead. Low-volume platforms or those with high-value transactions may prefer transaction-level invoicing for immediate visibility. If you select monthly invoicing, choose a day of month that aligns with when you actually pay sellers or suppliers. This creates a consistent, predictable cash flow cycle. Before going live, test your platform model configuration in testmode. Create sample transactions and review the generated invoices to ensure they match your expectations. Clearly communicate to sellers and suppliers which model you're using and when they can expect invoices. This reduces confusion and support requests. ## Common scenarios ### Scenario 1: New marketplace starting out **Situation**: You're launching a marketplace with a few sellers and low transaction volume. **Recommended configuration**: * Model: **Commission Agent** * Frequency: **At transaction level** or **Weekly** * Reasoning: Low volume means administrative overhead is manageable, and immediate invoicing provides clear visibility ### Scenario 2: Established e-commerce platform **Situation**: You've been operating for years with hundreds of suppliers and thousands of daily orders. **Recommended configuration**: * Model: **Buy and Resell** * Frequency: **Monthly** (when available; currently transaction level) * Reasoning: High volume requires aggregation to reduce invoice count and simplify reconciliation ### Scenario 3: Hybrid marketplace **Situation**: You have both third-party sellers (commission-based) and your own inventory (buy/resell). **Recommended configuration**: * Models: **Commission Agent** + **Buy and Resell** * Commission frequency: **Monthly** (for third-party sellers) * Self-billing frequency: **Transaction level** (for inventory purchases) * Reasoning: Each model operates independently with its own optimal frequency ### Scenario 4: Service booking platform **Situation**: You connect customers with service providers (hotels, tours, activities) and earn a commission. **Recommended configuration**: * Model: **Commission Agent** * Frequency: **Monthly** with invoicing on the 5th * Reasoning: Services may have cancellations/refunds, so waiting until the 5th allows time for adjustments before invoicing # Quickstart guides Source: https://docs.nocotax.app/quickstart Review a list of Nocotax integration quickstart guides This page contains a list of all Nocotax integration quickstart guides. These guides include: * Full end-to-end interactive code samples. * Step-by-step implementation instructions ### Undisclosed agent platforms | Quickstart | Description | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [Build customer invoicing for your platform](/undisclosed-agents/customer-invoicing) | Issue invoices to customers for goods or services sold through your platform as an undisclosed agent. | | [Build self billing for supplier invoices of your platform](/undisclosed-agents/self-billing) | Record purchases from suppliers using self-billing, where your platform issues purchase invoices on behalf of suppliers. | **Need help?** See our [full API documentation](https://app.nocotax.app/apidoc) # Tax Configuration Source: https://docs.nocotax.app/tax-configuration Configure where your organization is registered for tax purposes to ensure accurate tax calculations and compliance. ## Overview Tax registrations tell Nocotax where your organization is registered to collect and remit taxes (VAT, GST, sales tax, etc.). This configuration is critical for: * **Accurate tax calculations** on invoices based on your registration status * **Compliance** with local tax regulations * **Input tax recovery** on purchases where you're registered * **Proper tax reporting** across jurisdictions ## When to configure tax registrations You should configure your tax registrations: * **During initial onboarding** when setting up your Nocotax account * **When you register** in a new jurisdiction * **When your registration type changes** (e.g., moving from standard to OSS registration) * **When updating registration numbers** or details ## How to configure tax registrations ### During onboarding When you first set up your Nocotax account, you'll be prompted to add your tax registrations: 1. Navigate to the onboarding flow 2. Select the countries where you're tax registered 3. Choose the registration type (if applicable) 4. Enter your tax registration number (VAT ID, GST number, etc.) 5. Save your configuration Tax Onboarding ### After onboarding You can update your tax registrations anytime: 1. Go to **Profile Settings** → \*\*Organization \*\*→ **Tax Registrations** 2. Click **Add Tax Registration** 3. Select the country / jurisdiction 4. Choose the appropriate registration type 5. Enter your registration details 6. Save changes New Tax Registration Changes to tax registrations take effect immediately for new invoices only. Existing draft invoices may need to be recreated. ## Registration components Each tax registration consists of: ### Country/Jurisdiction The country or region where you're registered. This determines which tax rules apply to your transactions. ### Tax Registration Number Your official tax identification number: * **EU countries**: VAT number (e.g., DE123456789) * **UK**: VAT registration number * **Australia**: ABN (Australian Business Number) * **Canada**: GST/HST registration number * **US**: Sales tax permit numbers (varies by state) ### Registration Type Some jurisdictions require you to specify the type of registration. This is particularly important in the EU (see below). ## Common scenarios **Situation**: You're a German company selling software subscriptions to consumers across the EU. You have €50,000 in annual EU sales. **Configuration**: * **Germany**: Standard registration (your home country) * **EU-wide**: OSS for EU registration (for sales to other EU countries) **Why**: The standard registration covers your German operations. OSS for EU allows you to handle all other EU B2C sales through a single quarterly return. **Situation**: You're a Canadian SaaS company with customers in France, Netherlands, and Sweden. **Configuration**: * **EU**: OSS for Non-EU registration (register in one convenient EU country) **Why**: As a non-EU business, OSS for Non-EU lets you manage all EU VAT obligations through a single registration point. **Situation**: You operate a marketplace shipping low-value goods from China to EU consumers. **Configuration**: * **EU**: IOSS registration **Why**: IOSS allows you to collect VAT at checkout and clear customs faster, improving delivery times and customer experience. **Situation**: You're a Spanish business selling handmade goods online. You have €8,000 in annual sales to other EU countries. **Configuration**: * **Spain**: Standard registration only **Why**: Under the €10,000 EU threshold, you can charge Spanish VAT on all EU sales. No OSS needed. See the FAQ below for more details on the EU small seller scheme. ## Impact on tax calculations Your tax registrations directly affect how Nocotax calculates tax: ### For Sales Invoices (B2C) * **With registration in customer country**: Charge local VAT rate * **With OSS registration**: Charge destination country VAT rate * **No registration in customer country**: May need to charge your home country rate (depends on thresholds) ### For Sales Invoices (B2B) * **Customer has valid VAT number**: Typically reverse charge (0% VAT) * **Customer has no VAT number**: Treated as B2C ### For Purchase Invoices * **Registered in supplier country**: Can claim input VAT * **Not registered**: Cannot claim input VAT in that country Nocotax automatically determines the correct tax treatment based on your registrations, the customer's location, and the transaction type. ## Validation and compliance Nocotax validates tax registration numbers: * **EU VAT numbers**: Checked against VIES (VAT Information Exchange System) * **Format validation**: Ensures numbers match country-specific formats * **Warning indicators**: Flags potentially invalid numbers When automatic validation is enabled, Nocotax will warn you if: * A tax number format is incorrect * A VAT number cannot be verified in VIES * Registration details are missing for required jurisdictions ## Frequently Asked Questions The EU small seller scheme (also called the distance selling threshold) allows businesses with less than €10,000 in annual cross-border B2C sales within the EU to charge their home country VAT rate on all EU sales. **How to configure in Nocotax**: * Add only your local country's **standard registration** * Do NOT add OSS for EU registration * Nocotax will apply your home country VAT rate to all EU B2C sales **When to switch to OSS**: Once you exceed €10,000 in annual cross-border EU sales, you must register for OSS for EU and charge destination country rates. Update your Nocotax configuration at that point. Yes. For example, you can both have a standard registration and an OSS registration in Germany. The tax treatment depends on several factors: * **B2B sales**: Typically reverse charge applies (customer accounts for VAT) * **B2C sales**: You may need to charge your home country rate or register for VAT * **OSS users**: Can charge destination country rates without local registration Nocotax will calculate tax based on applicable rules, but you should monitor your sales volumes to ensure you register when required by local laws. Key decision points: 1. **Are you based in the EU?** * Yes → Use Standard for home country, consider OSS for EU for other countries * No → Use OSS for Non-EU 2. **What are you selling?** * Digital services/software → OSS (EU or Non-EU) * Low-value imported goods (≤€150) → IOSS * High-value or local goods → Standard registrations 3. **What's your annual EU B2C sales volume?** * Under €10,000 → Can use home country standard only * Over €10,000 → Need OSS or multiple standard registrations When in doubt, consult a tax advisor familiar with your specific situation. Yes, you can update your registrations at any time. If you need to update the type of registration, you'll need to recreate a new registration, as only the tax registration number for a given registration can be updated. It depends: * If you're registered for VAT in that country and want to claim input tax → Yes, add the registration * If you're not registered there → No need to add it Having purchase-only registrations configured allows Nocotax to calculate input VAT you can potentially recover. ## Best practices Always update your registration numbers in Nocotax immediately when they change. Incorrect numbers on invoices can cause compliance issues and delays in customer payments. Set a reminder to review your tax registrations every quarter. This ensures you're registered in all required jurisdictions and using the correct registration types as your business grows. Keep records of when each registration became effective. This helps with historical reporting and ensures you apply the correct tax treatment for different time periods. Track your sales volumes in different jurisdictions. Set up alerts when you're approaching registration thresholds so you can register before you're legally required to. When adding new registrations or changing types, test the tax calculation behavior in testmode before applying changes to your livemode environment. # Customer Invoicing Source: https://docs.nocotax.app/undisclosed-agents/customer-invoicing Issue invoices to customers for goods or services sold through your platform as an undisclosed agent. ## Overview Customer invoicing is the sales flow where your platform issues invoices to end customers. This guide covers the complete lifecycle from creating a draft invoice through payment reconciliation. ## Prerequisites Before you can issue customer invoices, ensure you have: 1. **Your organization set up** with `ownership=self` 2. **Customer organizations created** with `ownership=external` and role `BUYER` 3. **Tax registrations configured** for jurisdictions where you sell 4. **Product/service definitions** with appropriate tax categories ## Invoice lifecycle Every invoice follows this lifecycle: ``` DRAFT → FINALIZED → (CANCELLED) ``` * **DRAFT**: Invoice is being prepared, can be modified * **FINALIZED**: Invoice is issued, has a sequential number and date * **CANCELLED**: Invoice is voided (not yet implemented) ## Step 1: Create a draft invoice Create a sales invoice with up to 10 line items in a single API call. ```bash cURL theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "sales", "customer_id": "org_customer_123", "currency": "EUR", "automatic_tax_calculation": { "enabled": true }, "items": [ { "description": "Premium Subscription - Monthly", "quantity": 1, "unit_extratax_amount": 2900, "tax_code": "D10000000" }, { "description": "Additional User Seat", "quantity": 3, "unit_amount": 500, "tax_code": "D10000000" } ] }' ``` ### Key parameters | Parameter | Description | | ----------------------------------- | -------------------------------------------- | | `flow` | Must be `sales` for customer invoicing | | `customer_id` | The customer organization ID | | `currency` | Three-letter ISO currency code | | `automatic_tax_calculation.enabled` | Set to `true` to calculate tax automatically | | `items` | Array of up to 10 invoice line items | ### Amounts All monetary amounts are in the currency's smallest unit (cents for EUR/USD, etc.). Setting `automatic_tax_calculation.enabled: true` will calculate tax based on: * Supplier and customer tax registrations * Product tax categories * Applicable tax rules for the transaction ## Step 2: Review the draft The created invoice is in `DRAFT` status. You can: * Review the calculated tax amounts * Modify line items if needed * Add payment terms or due dates * Update billing addresses While in draft status, the invoice has no invoice number and does not affect AP/AR balances. ## Step 3: Finalize the invoice When ready to issue the invoice, finalize it: ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_123/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` Finalizing the invoice will: 1. Assign a sequential invoice number 2. Set the invoice date to the current date 3. Calculate `due_date` based on `payment_terms` (if provided) 4. Update the customer's accounts receivable (AR) balance 5. Lock the invoice from further modifications 6. Generate the PDF file representing the invoice Once finalized, an invoice cannot be modified. To correct a finalized invoice, issue a credit note instead. ## Step 4: Mark as paid When you receive payment from the customer, mark the invoice as paid: ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{}' ``` This marks the invoice as paid and updates the customer's AR balance. ### Recording partial or detailed payments To record specific payment details: ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_123/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "transaction_data": { "amount": 2500, "currency": "EUR", "transaction_type": "payment", "reference": "STRIPE_ch_abc123" } }' ``` This allows you to: * Record partial payments * Link to external payment references (Stripe, bank transfers, etc.) * Track payment dates separately from invoice dates ## Payment status Nocotax automatically tracks invoice payment status: | Status | Description | | ---------------- | --------------------------------------------- | | `OPEN` | Invoice is due but the due date hasn't passed | | `DUE` | Invoice is past its due date and unpaid | | `PAID` | Invoice has been fully paid | | `PARTIALLY_PAID` | Invoice has received partial payment | The `amount_remaining` field always shows how much is still owed. ## Handling corrections To correct a finalized invoice, issue a credit note: 1. Create a credit note referencing the original invoice 2. Finalize the credit note 3. The credit note automatically reduces the `amount_remaining` on the invoice 4. If needed, issue a new corrected invoice [Learn more about credit notes →](/credit-notes) ## Next steps Learn how to record supplier purchases Issue corrections and refunds Understand tax calculation logic View complete API documentation # Undisclosed Agent Flow overview Source: https://docs.nocotax.app/undisclosed-agents/overview Learn how to implement buy/resell mode for marketplace and platform businesses acting as undisclosed agents. ## What is an undisclosed agent? An undisclosed agent is a business model where a platform or marketplace purchases goods or services from suppliers and resells them to customers under its own name. Unlike a disclosed agent (where the supplier is visible to the customer), the platform acts as the principal in both transactions. This model is common in: * E-commerce marketplaces that purchase inventory and resell to customers * Booking platforms that buy services wholesale and resell retail * Fulfillment services that handle goods on behalf of multiple suppliers * Creator economy platforms that aggregate, repackage, or resell digital content, services, or merchandise from creators (e.g., NFT marketplaces, print-on-demand stores, or platforms bundling creator subscriptions). ## How it works The undisclosed agent flow involves two separate invoice flows: ### 1. Purchase flow (supplier → platform) The platform receives invoices from suppliers for goods or services purchased. These are inbound invoices that represent the platform's costs. To streamline integration and reduce administrative overhead, this process can be automated using self-billing. Under this model: * The platform generates supplier invoices on behalf of the supplier (self-billing). * The platform validates and records these invoices as accounts payable. ``` Supplier → Invoice → Platform (as customer) ``` ### 2. Sales flow (platform → customer) The platform issues invoices to end customers for the goods or services sold. These are outbound invoices that represent the platform's revenue. ``` Platform (as supplier) → Invoice → Customer ``` ## Tax considerations As an undisclosed agent, your platform is responsible for: * **VAT/GST collection**: Charging appropriate tax to customers based on their location * **Tax registration**: Maintaining tax registrations in relevant jurisdictions * **Input tax deduction**: Claiming back tax paid on purchases (where applicable) * **Tax reporting**: Filing returns that account for both purchase and sales tax Nocotax handles automatic tax calculation for both flows, ensuring compliance across jurisdictions. ## Key concepts ### Organizations In Nocotax, every business entity is represented as an Organization: * **Your platform** (`ownership=self`): Your business entity in the system * **Suppliers** (`ownership=external`, role=`MERCHANT`): Businesses you purchase from * **Customers** (`ownership=external`, role=`BUYER`): Businesses or individuals you sell to Learn more about [Organizations](/organizations). ### Invoice flows Nocotax supports two invoice flows for undisclosed agents: * **Purchases** (`flow=purchases`): For inbound invoices from suppliers * **Sales** (`flow=sales`): For outbound invoices to customers Each flow follows the same lifecycle: `DRAFT` → `FINALIZED` → (optionally) `CANCELLED`. ### Tax registrations Organizations can have multiple tax registrations representing where they're registered for VAT/GST. This determines: * Where you can claim input tax on purchases * Where you must charge tax on sales * Which tax rates apply to transactions Learn more about [Tax Registrations](/tax-registrations). ## Integration patterns There are two main integration patterns for undisclosed agents: ### Customer invoicing Issue invoices to customers for goods or services sold through your platform. This typically involves: 1. Creating a sales invoice with line items 2. (Optional) Enabling automatic tax calculation 3. Finalizing the invoice to generate a sequential number 4. Marking the invoice as paid when payment is received [View customer invoicing guide →](/undisclosed-agents/customer-invoicing) ### Self-billing for supplier payouts Record purchases from suppliers using self-billing, where your platform issues the invoice on behalf of the supplier. This is useful for: * Payout statements to sellers on your marketplace * Automated purchase recording * Simplified supplier onboarding [View self-billing guide →](/undisclosed-agents/self-billing) ## Next steps Learn how to invoice customers for sales Implement supplier payout statements Explore the full API documentation Understand automatic tax handling ## Common questions **Do I need separate accounts for test and production?** No. Each Nocotax account has two modes: `testmode` for sandbox testing and `livemode` for production. Data is isolated between modes. **Can I use the same organization as both supplier and customer?** Yes, but it's not a good practice. External organizations can have multiple roles simultaneously (`MERCHANT` and `BUYER`), allowing you to both buy from and sell to the same entity, but for testing purposes, it's easier to separate flows. **How do credit notes work in this model?** Credit notes work the same way in both flows. They reduce the amount remaining to pay on invoices and automatically adjust AP/AR balances. Learn more about [Credit Notes](/credit-notes). # Self-Billing for Supplier Payouts Source: https://docs.nocotax.app/undisclosed-agents/self-billing Record purchases from suppliers using self-billing, where your platform issues purchase invoices on behalf of suppliers. ## Overview Self-billing is a process where the buyer (your platform) creates the purchase invoice on behalf of the seller (supplier). This is common in marketplace platforms for: * Automated payout statements to sellers * Simplified supplier onboarding (no invoicing system required) * Consistent invoice formatting across all suppliers * Easier reconciliation of purchases ## What is self-billing? In traditional invoicing, the supplier creates and sends an invoice to the buyer. In self-billing: ``` Platform creates invoice → Supplier accepts → Platform pays ``` Your platform acts as both the invoice issuer and the customer, creating purchase invoices that represent amounts owed to suppliers. Self-billing requires prior agreement with suppliers and must comply with local tax regulations. Ensure suppliers consent to this arrangement and that it's permitted in your jurisdiction. ## Use cases Self-billing is ideal for: * **Marketplace platforms**: Record commissions and payouts to sellers * **Gig economy platforms**: Document contractor payments * **Wholesale platforms**: Automate purchase recording from multiple suppliers * **Dropshipping**: Track costs from fulfillment partners ## Prerequisites Before implementing self-billing, ensure you have: 1. **Your organization set up** with `ownership=self` 2. **Supplier organizations created** with `ownership=external` and role `MERCHANT` 3. **Tax registrations configured** for applicable jurisdictions ## Invoice lifecycle Self-billed invoices follow the same lifecycle as regular invoices: ``` DRAFT → FINALIZED → (CANCELLED) ``` The key difference is that `flow=purchases` and your platform's organization ID is the `customer_id` while the supplier organization ID is the `supplier_id`. ## Step 1: Create a purchase invoice Create a purchase invoice with the supplier as the issuer and your platform as the customer. ```bash cURL theme={null} curl https://api.nocotax.app/invoices \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "flow": "purchases", "supplier_id": "org_supplier_456", "currency": "EUR", "issuer": { "type": "CUSTOMER" // In order to tag the invoice as a selfbilling document }, "automatic_tax_calculation": { "enabled": true }, "items": [ { "title": "Payouts on sales - Order #12345", "quantity": 1, "unit_extratax_amount": 15000, "product": { "tax_code": "D10000000" } }, { "description": "Tipping", "quantity": 1, "unit_extratax_amount": 8500, "product": { "tax_code": "D00000000" } } ] }' ``` ### Key parameters | Parameter | Description | | ----------------------------------- | --------------------------------------------------------- | | `flow` | Must be `purchases` for self-billing | | `supplier_id` | The supplier/seller organization ID | | `currency` | Three-letter ISO currency code | | `automatic_tax_calculation.enabled` | Set to `true` to calculate input tax | | `items` | Array of up to 10 line items for services/goods purchased | The `supplier_id` and `customer_id` are reversed compared to sales invoices. For purchases, your platform is always the customer. ## Step 2: Review and adjust While in `DRAFT` status, you can: * Review calculated tax amounts (potential input VAT to claim) * Add or modify line items * Update amounts or descriptions * Set payment terms The draft does not yet affect accounts payable (AP) balances. ## Step 3: Finalize the purchase invoice When ready to issue the payout statement, finalize the invoice: ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_456/finalize \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} ``` Finalizing will: 1. Assign a sequential invoice number 2. Set the invoice date to the current date 3. Calculate `due_date` if `payment_terms` were provided 4. Update the supplier's accounts payable (AP) balance 5. Lock the invoice from modifications 6. Generate the PDF file for the invoice. ## Step 4: Record the payout When you pay the supplier, record the payment: ```bash cURL theme={null} curl https://api.nocotax.app/invoices/inv_456/attach_payment \ -X POST \ -u ${ACCOUNT_ID}:${YOUR_API_KEY} \ -H "Content-Type: application/json" \ -d '{ "transaction_data": { "amount": 23500, "currency": "EUR", "transaction_type": "transfer", "reference": "WISE_TRANSFER_789", } }' ``` This updates the supplier's AP balance and marks the invoice as paid. ## Tax considerations Self-billing has important tax implications: ### Input VAT recovery When `automatic_tax_calculation` is enabled, Nocotax calculates the input VAT you can potentially claim back on purchases, based on: * Your platform's tax registrations * The supplier's tax registrations * The nature of the goods/services purchased ### Reverse charge mechanism In some jurisdictions, B2B services may be subject to reverse charge, where the buyer (your platform) accounts for VAT instead of the supplier. Nocotax handles this automatically when: * Both parties have valid tax registrations * The transaction qualifies for reverse charge ### Record keeping Maintain records of: * Self-billing agreements with suppliers * Supplier consent to self-billing arrangements * Invoice copies provided to suppliers * Proof of payment ## Best practices Always have signed self-billing agreements in place before issuing purchase invoices on behalf of suppliers. This is often a legal requirement. Send suppliers copies of self-billed invoices for their records. They'll need these for their accounting and tax compliance. Let Nocotax handle invoice numbering automatically when finalizing. This ensures sequential, compliant numbering. Make line item descriptions clear and specific. Include order numbers, date ranges, or other references that help suppliers reconcile. Match Nocotax invoices with your internal sales/order data regularly to catch discrepancies early. If you operate in multiple currencies, ensure each invoice uses the correct currency for the supplier. ## Credit notes for purchases To correct a self-billed purchase invoice, create a credit note: ```javascript theme={null} const creditNote = await nocotax.creditNotes.create({ flow: 'purchases', supplier_id: 'org_supplier_456', currency: 'EUR', invoice_id: 'inv_456', // Original invoice to credit items: [ { description: 'Correction: Order #12345 was cancelled', quantity: 1, unit_extratax_amount: 1500, // Credit the original amount tax_code: 'D10000000' } ] }); await nocotax.creditNotes.finalize(creditNote.id); ``` The credit note will reduce the AP balance and the `amount_remaining` on the original invoice. ## Next steps Learn about the sales side of the flow Handle corrections and refunds Manage suppliers and customers Explore the complete API