Invoices (sales / purchase entries)

​

Definition

In the Accounting API, a sales entry is a customer invoice and a purchase entry is a supplier invoice recorded in the accounting system. If the accounting software supports invoices, Chift creates a native invoice object. Otherwise, Chift posts the equivalent journal entries. The accounting result is the same.

​

Purpose

• Book customer and supplier invoices with business fields, without building the journal entry lines yourself.
• Generate the receivable or payable line automatically from the partner.
• Get the same behavior across accounting software, whether or not they support invoices natively.

​

Structure

Each invoice has:

• An identifier (id) and an invoice number (invoice_number). If you do not send a number on creation, the accounting software generates it. Use it for idempotency
• A type (invoice_type):
  • customer_invoice, customer_refund: sales invoice and credit note
  • supplier_invoice, supplier_refund: purchase invoice and credit note
• A status (status): draft, posted, paid or cancelled. On creation, only draft or posted. The default is posted
• An approval status (approval_status): pending, approved, rejected or unknown (the status could not be determined)
• Dates: the accounting date (invoice_date), the due date (due_date, and due_dates for all due dates) and the delivery date (delivery_date). On creation only: the period covered (start_date, end_date) for accruals and deferrals
• A partner (partner_id) and a journal (journal_id)
• A currency (currency) and, on creation, an exchange rate (currency_exchange_rate). The rate is required when the currency differs from the folder currency
• Amounts: untaxed_amount, tax_amount and total (total = untaxed_amount + tax_amount). See Amounts validation
• References: reference (for a purchase invoice, often the supplier’s invoice number), payment_communication (payment reference, used for reconciliation) and customer_memo
• A payment term (payment_term_id) and a payment method (payment_method_id)
• An optional withholding tax (withholding_tax), mainly used in Spain
• An attachment status (attachments_info): yes, yes_to_request, no or unknown. On creation, send a PDF with pdf and pdf_name
• On read only: the last update (last_updated_on), the payments (payments) and the partner details (partner)
• Lines (lines). Each line has:
  • A ledger account (account_number): a general account (income or expense). See Accounts in invoices
  • A VAT code (tax_code) and a tax rate (tax_rate)
  • Amounts: unit_price, quantity, untaxed_amount, tax_amount and total
  • A description (description)
  • An optional analytic account (analytic_account)

​

Relationships

• Each invoice is linked to a partner (partner_id): a client for sales, a supplier for purchases. Chift books the receivable or payable line on the account of that partner. Some software cannot create partners by API. For these, send the partner with partner_info.
• Each invoice is recorded in a journal (journal_id). Use journal_ids to filter invoices. When you create an invoice without journal_id, Chift selects the journal automatically only if there is exactly one. Otherwise, it returns an error.
• Each line references a ledger account (account_number) and a VAT code (tax_code).
• An invoice generates journal entries in the accounting software.
• Open invoices appear in outstanding items. Use Match entries to match an invoice with financial entries or journal entries of the same partner.
• Lines can carry analytic accounts: analytic_account for the default plan, analytic_distribution for multiple plans.
• When attachments_info is yes_to_request, get the documents from the attachments endpoint with type=invoice.
• When you list invoices, use updated_after and last_updated_on for incremental synchronization. Use payment_status (all, paid, unpaid) and approval_status to filter. Lines, payments and partner details are returned only with include_invoice_lines, include_payments and include_partner_info when the software needs extra requests.

​

API endpoints

• Get invoices by type: list the invoices of one type, with the analytic accounts of the default analytic plan.
• Get invoices by type (multiple analytic plans): list the invoices of one type, with the analytic accounts of all analytic plans.
• Get one invoice: get one invoice by its ID.
• Get one invoice (multiple analytic plans): get one invoice by its ID, with the analytic accounts of all analytic plans.
• Get payment terms: list the payment terms.
• Get payment methods: list the payment methods.
• Create sale/purchase entry: create an invoice.
• Create sale/purchase entry (multiple plans): create an invoice with analytic accounts in several analytic plans.
• Create an invoice payment: record a payment on an invoice.

Not every accounting software supports every invoice endpoint. Payment terms, payment methods and invoice payments have limited support. Check the coverage matrix.