Sales flow

In the platform, the Sales domain encompasses the entire journey of a transaction, from the initial contact with a buyer to the final paid bill. It includes everything from drafting proposals and confirming orders, to sending invoices and attaching relevant files. A modern business needs to track what is being sold, to whom, and at what stage the deal is in. By structuring sales into different document types (quotes, orders, and invoices) the platform automatically handles the underlying accounting rules, so your integration can move data effortlessly between these stages.

This guide covers the key concepts, the business logic behind the sales lifecycle, how documents connect to the API, and key rules to keep in mind when building your integration.

A note on naming: In the platform, these are called Sales invoices. In the API, the same concept is referred to as Customer invoices. You'll see this reflected in endpoint names like /customerinvoices and /customerinvoicedrafts. The terms refer to the same thing, the naming difference is a legacy of how the API was originally built.

Key concepts

These are key concepts covered in this guide:

• Customers: The buyers purchasing the offerings.
• Quote drafts and quotes: A preliminary offer to a buyer that can be edited and finalised before becoming an official quote.
• Orders: A confirmed request for offerings to be delivered. Note that Orders don’t have drafts; they are created directly.
• Sales invoice drafts: Preliminary invoices that can be edited safely before they are finalised and posted to the accounting.
• Sales invoices: The final billing document sent to the buyer for provided offerings.
• Sales document attachments: Files or documents (like PDFs or images) that can be linked to records such as customer invoices, quotes, and orders.

Business rules & logic

A fundamental rule in the platform is the strict lifecycle of sales documents to protect accounting integrity.
Documents like Quotes and Invoices usually start as Drafts. At this stage, they’re safe to edit freely or even delete completely because they haven’t yet impacted the bookkeeping.

Once a draft is finalised into a Sales invoice, it’s locked in. If a finalised invoice is incorrect, you can’t delete it; it must instead be voided to leave a proper audit trail. Orders are an exception to this rule. Since there are no order drafts, an order can actually be deleted entirely if needed before it is invoiced.

Common workflows

From a business perspective, the typical sales cycle follows these steps:

1. Set up the buyer: The user ensures the customer exists with the correct terms.
2. Make an offer and confirm: The user creates a Quote, and once accepted, it becomes an Order.
3. Draft the bill: The user creates a Sales invoice draft.
4. Finalise and send: The draft is converted into a Sales invoice and sent via email or e-invoice.
5. Print or Save as PDF: If the user or the buyer needs a physical copy, the invoice can be extracted as a PDF or printed directly.
6. Attach documents: Additional files, like terms and conditions, are attached to the invoice or order.

Connection to the API

Your integration handles these workflows smoothly using the API's endpoints. Here is the conceptual mapping for the flows:

• Working with Drafts: Start by POSTing to /customerinvoicedrafts or /quotedrafts. You can update them with PUT or remove them entirely using DELETE.
• Working with Orders: There are no order drafts. You either create an order directly via POST /orders, or push an accepted Quote to an Order using POST /quotes/{id}/converttoorder. If something went wrong, you can cleanly remove the order using DELETE /orders/{id}.
• Finalising invoices: When ready, convert the draft to a real invoice via POST /customerinvoicedrafts/{customerInvoiceDraftId}/convert.
• Sending and voiding: Use endpoints like POST /customerinvoices/{invoiceId}/email or /einvoice to send the bill. If something went wrong with an invoice, protect the history by using POST /customerinvoices/{invoiceId}/void.
• Retrieving PDFs: Fetch a PDF version of an invoice using GET /customerinvoices/{invoiceId}/pdf or trigger a print using GET /customerinvoices/{invoiceId}/print.

Relations to other domains

Sales documents don't exist in isolation, but are deeply connected to other parts of the platform:

• Articles: Articles are the primary line items added to Quotes (/quotes), Orders (/orders), and Sales invoices (/customerinvoices). Make sure articles exist before creating sales documents.
• Customers: Every sales document must be linked to a Customer (/customers). Verify the customer exists and has the correct payment terms before creating documents.
• Accounting: Finalising a Sales invoice directly impacts the general ledger. VAT and sales categories tied to the articles determine how the transaction is posted.

Important things to consider

Keep these tips in mind to build a robust integration:

• The delete rule: Remember that Drafts (/customerinvoicedrafts, quotedrafts) and Orders (/orders) have a DELETE endpoint. Finalised Invoices (/customerinvoices), however, do not have a DELETE endpoint and must be handled via /void.
• Check the subscription: Basic invoice functionality works across almost all subscriptions. Features like Orders and Quotes require the sales_standard (Order & Quotes) module.

Good luck with your coding!