Sending Purchase Orders

A purchase order only does its job when it lands in the vendor’s system, in the shape that vendor expects. ILLUMA sends POs by email — either as a formatted order email or as a filled PDF attached to a ticket — using the submission method you configure on each vendor.

What has to be in place first

A PO can only be sent when all three of these are true:

Requirement	Where it lives
The vendor has a submission method and a working destination address	Purchasing → Vendors → the vendor → Integration tab
The PO has at least one line item and a vendor	Purchasing → Purchase Orders → the PO
The PO status is Draft, Pending Approval, or Approved	The PO’s status badge

Purchasing is its own top-level section in the sidebar, with Vendors and Purchase Orders beneath it.

ℹ️ Note: Sending a PO does not touch your stock or your ledger. It transmits the document, stamps the PO as sent, and — for a drop-ship PO — moves the linked customer order to awaiting vendor.

Choosing a submission method

Open Purchasing → Vendors → the vendor → Integration. The first panel, PO Submission Method, has one control: Integration Type.

📷 Screenshot: The vendor Integration tab with the Integration Type dropdown open, showing None (Manual), Email, Freshdesk Ticketing, and the four greyed-out “not available yet” options (placeholder — replace with /docs-images/vendors/purchase-orders-integration-type-dropdown.png)

Integration Type	What happens when you send	Where the PO goes
None (Manual)	A standard HTML purchase order email	The vendor’s drop-ship email address
Email	A standard HTML purchase order email	Submission Email, falling back to the vendor’s drop-ship email address
Freshdesk Ticketing	A filled PDF of the vendor’s own order form is attached to the email. On a drop-ship PO the email body shrinks to a one-line pointer at the PDF and carries your routing subject line; on any other PO the body is the standard purchase order email with the PDF attached	Submission Email, falling back to the vendor’s drop-ship email address
EDI	Not available yet	—
API	Not available yet	—
FTP/SFTP	Not available yet	—
Vendor Portal	Not available yet	—

The four unbuilt methods are deliberately unpickable in the dropdown. They only appear selectable if a vendor is already set to one, so an existing record still renders.

⚠️ Warning: If a vendor is set to EDI, API, FTP/SFTP, or Vendor Portal, sending a PO fails with an error and the PO stays in your queue. It does not quietly fall back to email. That is on purpose — a silent downgrade would tell you the PO transmitted by EDI when the vendor’s system never received it, and nobody would find out until the order was late. Switch the vendor to Email or Freshdesk Ticketing to send today.

ℹ️ Note: None (Manual) is not a broken configuration. It is a real, implemented delivery path: the PO goes out as the standard HTML purchase order email to the vendor’s drop-ship email address. A vendor left on the default sends fine, as long as it has a drop-ship email address on the Overview tab.

ℹ️ Note: This setting is only about sending orders to the vendor. Pulling catalog and inventory files from them is the Products, Inventory, and Connections panels further down the same tab — those are available now, are configured separately, and are covered in Product Feeds, Inventory Feeds, and Vendor Connections.

Email

Choosing Email opens an Email Settings panel.

Field	What it does
Submission Email	The address POs are sent to. This overrides the vendor’s drop-ship email address.
Format	Has no effect on what is sent today. Email POs always go out as the standard HTML purchase order email.

If both the Submission Email and the vendor’s drop-ship email address are empty, the send fails with vendor has no submission or dropship email configured and nothing is transmitted.

Freshdesk ticketing

Freshdesk is how vendors that run their sales desk on a ticketing system take orders: you email their intake address, the subject line routes the ticket to the right queue, and their team works from the attached order form.

Choosing Freshdesk Ticketing opens two panels.

Freshdesk Settings

Field	What it does
Freshdesk Email	The vendor’s ticketing intake address (for example [email protected]).
Format	Has no effect on what is sent today. Whether a PDF is attached is decided by the PO Form Template field below.
Subject Line Template	The ticket subject. Supports {{po_number}}, {{category}}, and {{dealer.name}}.
PO Form Template (PDF)	A public URL to the vendor’s fillable PDF order form. ILLUMA downloads it, fills it, and attaches it.

Category Routing maps your own product categories to the keyword the vendor’s help desk routes on. Each row is Your Category (the category’s slug) → Vendor Keyword (for example Lift). At send time ILLUMA looks at the products on the PO, finds a mapped category — including every subcategory beneath it, at any depth — and substitutes the matching keyword into {{category}}.

⚠️ Warning: The Your Category box must hold the category’s slug (inground-lifts), not its display name, even though the field’s placeholder text reads like a name. A row whose left-hand value is not a real category slug is silently skipped and {{category}} resolves to an empty string.

📷 Screenshot: The Freshdesk Settings panel filled in, with the Subject Line Template, PO Form Template URL, and two Category Routing rows below it (placeholder — replace with /docs-images/vendors/purchase-orders-freshdesk-settings.png)

⚠️ Warning: PO Form Template is the switch that turns the whole Freshdesk path on. Leave it empty and three things silently do not happen: no PDF is built or attached, your Subject Line Template is never applied (the email goes out with the stock subject Purchase Order {number}), and Category Routing is never consulted. On a drop-ship PO the result is an email that says “Please see attached purchase order” with no attachment and no line items — the drop-ship Freshdesk body is deliberately minimal because the PDF is meant to be the actual order. Always set the template URL for a Freshdesk vendor.

💡 Tip: {{is_dropship}} is listed as a subject variable in the form hint but is not substituted — it would print literally in the subject. Use {{po_number}}, {{category}}, and {{dealer.name}} only. Drop-ship POs are already flagged inside the PDF’s comments box.

ℹ️ Note: If a single PO contains products from more than one mapped category, which keyword wins is not guaranteed. Keep one PO to one category family when the vendor routes tickets by keyword.

How the PDF gets filled

The PDF filler writes into a fixed set of form field names — the ones on the Challenger Lifts sales order form. A fillable PDF whose internal field names differ will download and attach, but come back blank.

Section of the form	Filled from
Customer No	The vendor’s Account Number (Overview tab)
Purchase No, Required Date, date	The PO number, expected date, and order date
Ordered By, Bill To, phone, email	Your store’s contact name, store name, phone, email, and street address from Settings
Ship To	The customer’s shipping address on a drop-ship PO; otherwise the PO’s own ship-to address, if it has one
Line rows	The PO’s line items — quantity, vendor SKU, description, unit price, line total
Subtotal / tax / shipping / total	The PO totals
Comments or Special Instructions	The PO’s Notes field, prefixed with *** DROP SHIP ORDER *** on drop-ship POs
Signature line	A cursive rendering of your contact name, or your store name if no contact name is set

ℹ️ Note: The PDF is attached to every PO sent to a Freshdesk vendor that has a PO Form Template — drop-ship or not. What changes between the two cases is the email wrapped around it, not the attachment.

⚠️ Warning: The form has 15 line rows. Items past the fifteenth are not printed on the PDF, even though they are counted in the totals. Split large orders across multiple POs.

⚠️ Warning: If the PDF cannot be built — the template URL is unreachable, or the file is not a fillable form — the email is still sent, without the attachment. Send yourself a test PO to a mailbox you control the first time you set a vendor up, and open the attachment.

Sending a purchase order

1. Open the PO — go to Purchasing → Purchase Orders and click the PO, or create one with Create PO. A drop-ship PO can be started straight from a customer order with Create Drop Ship PO in that order’s Fulfillment card, which pre-fills the vendor and lines.
2. Check the document — line items, quantities, unit costs, expected date, payment terms. Notes is sent to the vendor; Internal Notes is not.
3. Press Send to Vendor — the button sits in the PO header and only appears while the status is Draft, Pending Approval, or Approved. Confirm the prompt.
4. Watch the status — on success the badge flips to Sent and a toast confirms it.

📷 Screenshot: A purchase order detail header showing the PO number, an Approved status badge, and the Send to Vendor button (placeholder — replace with /docs-images/vendors/purchase-orders-send-to-vendor-button.png)

What the send stamps on the PO:

Field	Value
Status	Sent
Order Date	Today’s date
Sent Via / transmitted at	email and the current timestamp
Linked customer order	Moves to awaiting vendor when the PO came from a drop-ship conversion

ℹ️ Note: The email goes out first. If it fails, the PO is not marked sent — you get the error, the PO keeps its current status, and you can fix the vendor’s settings and try again. Nothing is ever marked sent on the strength of a failed transmission.

ℹ️ Note: “Sent Via” records email for every PO you send with the button, including Freshdesk vendors — it describes the transport, not the vendor’s integration type. POs dispatched by an automation record the vendor’s method instead.

Once a PO is Sent, the Send to Vendor button disappears from the header. That is intentional: a purchase order is money, and the dashboard is built so a person cannot re-fire the same PO at a vendor by reflex.

What the vendor actually receives

Three different emails exist. Which one is used depends on both the vendor’s integration type and whether the PO came from a drop-ship conversion.

Situation	Email	Contents
Any PO that is not a drop-ship conversion — vendor set to None, Email, or Freshdesk Ticketing	Purchase Order {number} from {your store}	Your logo, PO details, vendor block, ship-to block if the PO has one, a full line-item table, total, and notes. For a Freshdesk vendor with a PO Form Template, the filled PDF rides along as an attachment on this same email.
Drop-ship PO, vendor set to None or Email	DROP SHIP - Purchase Order {number} from {your store}	The same, plus a red DROP SHIP banner and a highlighted Ship Directly To Customer block with the customer’s name, address, and phone
Drop-ship PO, vendor set to Freshdesk Ticketing	Your Subject Line Template — or the stock Purchase Order {number} if no PO Form Template is set	One line pointing at the attached PDF, plus notes — the PDF is the order

⚠️ Warning: The minimal Freshdesk body is reserved for drop-ship POs. A hand-created PO to the same Freshdesk vendor goes out on the full purchase order template, line-item table and all, with the PDF attached. If you are testing a Freshdesk vendor’s routing, test with a real drop-ship PO — a manual test PO will not exercise the subject line the same way.

These are ordinary email templates. You can review or edit their wording under Settings → Notifications, where they appear as Purchase Order to Vendor, Drop Ship PO to Vendor, and Freshdesk PO Submission.

⚠️ Warning: Do not disable or delete those three notification rules. With no enabled rule for the event, the send completes without error and the PO is marked Sent — but no email leaves the building.

ℹ️ Note: Purchase orders created in the dashboard by hand carry no ship-to address, so the Ship To block is omitted from the email. Drop-ship POs always carry the customer’s address, which is the case that matters.

Sending POs automatically

Purchase order dispatch is available to flows as two actions, so drop-ship orders can reach the vendor without anyone opening the PO.

Action	What it does
Create dropship PO (dropship.create_po)	Turns an order’s drop-ship lines into one purchase order per drop-ship vendor, with line items and costs. Optionally sends each one immediately.
Send PO to vendor (vendor.submit_po)	Dispatches one existing PO using its vendor’s configured submission method.

Create dropship PO options:

Option	Meaning
Order	The order to convert. Normally filled automatically from the trigger.
Also send to vendor	Create and dispatch each PO in the same step.
Only this vendor	Restrict to a single drop-ship vendor. Leave blank to handle every drop-ship vendor on the order.
Create as status	approved (default), draft, or pending_approval.

The vendor for each line comes from the product: its drop-ship vendor, falling back to the product’s main vendor. The submission method comes from that vendor’s Integration tab. Nothing about the method is configured in the flow.

The ready-made recipe Dropship PO dispatch wires the common case — order paid → create a PO per drop-ship vendor → send each one:

on: order.paid
steps:
  - id: create-and-send
    action: dropship.create_po
    config:
      order_id: "{{ trigger.aggregate_id }}"
      submit: true
      status: approved

Want a human gate instead? Create the POs as pending_approval, then run a second flow on the purchase order approved trigger that calls Send PO to vendor.

Both actions are safe to re-run. A repeat never creates a second PO for the same order and vendor, and a PO already in Sent, Confirmed, Partially Received, Received, Closed, Cancelled, or in-flight status is skipped rather than sent again. If a dispatch fails, the PO is put back to the status it came from so it stays sendable.

ℹ️ Note: An automated dispatch records the vendor’s own integration type in Sent Via — freshdesk, email, or none — where the dashboard button always records email. Both describe the same send; only the label differs.

💡 Tip: Start any PO flow in shadow mode. Shadow reports what it would have created and sent without contacting a vendor.

The backstop

Every 10 minutes ILLUMA sweeps for drop-ship work that never reached a vendor:

• a drop-ship PO sitting in Approved or mid-send for more than 15 minutes without landing on Sent, and
• a paid order (paid more than 15 minutes ago and within the last 48 hours) that has drop-ship lines and no drop-ship PO at all.

Each anomaly raises a Dropship PO stuck event, at most one per item every 6 hours. It never re-sends on its own — a PO caught mid-dispatch might already be at the vendor, so it surfaces the problem and lets you decide. Pair it with the Dropship PO stuck → alert me recipe so a stalled PO reaches a person instead of a log file.

ℹ️ Note: The sweep watches Approved and in-flight POs. A drop-ship PO you deliberately parked in Draft or Pending Approval is not treated as stuck, because a human gate is a legitimate reason for it to sit there.

Confirming it went out

Go to Settings → Notifications → Activity. Every send is listed with its timestamp, event, recipient, template, channel, and status — plus the error text on anything that failed.

📷 Screenshot: The Notifications Activity table filtered to failures, with one purchase order row showing its recipient, template, and error text (placeholder — replace with /docs-images/vendors/purchase-orders-notifications-activity.png)

Common errors and what they mean:

Message	Meaning	Fix
vendor submission method has no delivery path yet	The vendor is set to EDI, API, FTP/SFTP, or Vendor Portal	Switch the vendor to Email or Freshdesk Ticketing
vendor has no submission or dropship email configured	No destination address for the vendor	Fill in Submission Email on the Integration tab, or a drop-ship email address on the Overview tab
purchase order has no vendor	The PO was saved without a vendor	Set the vendor on the PO
Cannot send a PO with status “…”	The PO is cancelled, closed, or already received	Nothing to send
Vendor received an email with no attachment	Freshdesk vendor with no PO Form Template, or the template could not be filled	Set or fix the template URL, then re-check with a test PO
Freshdesk vendor received a full line-item email instead of the short one	The PO was not a drop-ship conversion — expected behaviour, not a fault	Nothing to fix; the PDF was still attached

More vendor-side failure patterns — feeds, connections, and matching — are collected in Vendor Troubleshooting.

After the PO is sent

Record Vendor Shipment appears on drop-ship POs once they are Sent or Confirmed. Enter the carrier and tracking number the vendor gave you and ILLUMA creates the shipment on the customer’s order, marks every PO line received, and closes the PO in one step. The customer’s tracking email follows from your normal shipping notifications.

Cancel PO is available on any PO that is not already cancelled, closed, or received. A Draft PO is deleted outright along with its lines; anything further along is marked Cancelled and its open lines cancelled with it.

Next

Set a vendor’s submission method up from scratch in Adding a Vendor, wire the whole drop-ship path end to end with Flow Recipes, or see how sent POs move a customer order along in Managing Orders.