Automatically send a carbon footprint report when an order comes through Xero

This guide walks you through connecting Xero → Zapier → Zilch, so that whenever you raise a sales invoice in Xero, your customer automatically receives the carbon footprint report for everything they ordered. No code required.

What you'll end up with

   Xero                       Zapier                        Zilch
┌───────────┐          ┌──────────────────┐          ┌──────────────────┐
│ You raise │          │ Zap notices the  │          │ Looks up each    │
│ a sales   │  ─────►  │ new invoice and  │  ─────►  │ SKU, adds up the │
│ invoice   │          │ passes the       │          │ footprint, emails│
│           │          │ customer + lines │          │ the customer     │
└───────────┘          └──────────────────┘          └──────────────────┘
                                                              │
                                                              ▼
                                                   Customer receives the
                                                   same branded report you
                                                   send by hand today

The email your customer receives is identicalto the Customer Footprint Report you'd send manually from Zilch → Settings → Reports — same design, same numbers, same per-product breakdown. It also gets saved into Settings → Reports, so you have a record of every report that went out and can resend it if needed.

If an order has three products on it, the customer gets one email covering all three, with a line for each and a combined total — not three separate emails.

Before you start

Work through this checklist first. Every item is a hard requirement, and missing one is by far the most common reason setup stalls halfway through.

Step 1 — Make sure your products are ready in Zilch

Reports are built from products in your catalogue, which means either:

• products you own (you created and assessed them yourself), or
• products you've linked from a supplier via the shared catalogue.

Both work exactly the same way here.

Do this:

1. Go to Zilch → Products.
2. For every product you expect to appear on Xero invoices, confirm:
   • It has a SKU filled in (the “Code” field).
   • It shows a completed footprint— a total in kg CO₂e, not “Not assessed” or a draft in progress.
3. Make a note of the SKUs. You'll need them in the next step.

Products missing either a SKU or a completed footprint will be silently skipped when a report is sent. The report still goes out with whatever did match, so it's worth getting this right — otherwise customers receive a report that's quietly missing a product.

Step 2 — Match your Xero item codes to your Zilch SKUs

This is the single most important step. Zilch identifies products by SKU, and Xero identifies them by Item Code. If those two don't line up, nothing will match.

How the matching works

• Matching is on the Item Code of each invoice line in Xero, compared against the SKU (Code) of each product in Zilch.
• Matching is not case sensitive, and leading/trailing spaces are ignored. So btm-500, BTM-500 and BTM-500 all match a Zilch SKU of BTM-500.
• Matching is otherwise exact. BTM500 will not match BTM-500, and BTM-500-BLU will not match BTM-500.

What to do in Xero

1. In Xero, go to Business → Products and services.
2. For each product you sell that's assessed in Zilch, open it and check the Item code field matches the Zilch SKU exactly.
3. If an item doesn't exist yet in Xero, create it — with the Zilch SKU as its item code.

The critical part: use items on your invoices, not free text

When you raise an invoice in Xero, each line can either be:

• linked to an item — the line carries an item code, and Zilch can match it, or
• typed as free text — the line has no item code, and Zilch has nothing to match on.

If your team types product descriptions straight into invoices instead of picking the item from the dropdown, this integration will not find anything. Make sure whoever raises invoices selects products from the item list.

What about shipping, discounts and other non-product lines?

You don't need to do anything about these. Lines with no item code, or with a code Zilch doesn't recognise (freight, handling, discounts, notes), are automatically ignored.

They're reported back to you in the Zap's Skipped SKUsoutput field, so if a report ever looks short a product, that's the first place to check.

The only case that fails outright is when nothingon the invoice matches — you'll get the error None of the line items matched a product with a completed footprint in your catalogue. See Troubleshooting.

Step 3 — Generate your Zilch secret API key

Zapier authenticates to Zilch with a secret API key.

1. Log in to Zilch and go to Settings → Profile.
2. Scroll to the API Access section.
3. Find the Secret API Key panel and click Generate secret key.
4. Click the copy icon to copy the key. It starts with zlch_sk_.
5. Keep it somewhere safe for the next step (a password manager is ideal).

Don't confuse the two keys

The API Access section shows two different keys, and they're not interchangeable:

If you paste the publishable key into Zapier, the connection test will fail with a message telling you to use the secret key instead.

Treat the secret key like a password. It can send email to your customers on your behalf. Never put it in a web page, a public spreadsheet, or an email.

Step 4 — Add the Zilch integration to your Zapier account

The Zilch integration is currently a private Zapier integration, which means you won't find it by searching in Zapier. You need to accept an invite link first — you only ever do this once.

1. Make sure you're logged in to Zapier.
2. Open this link: zapier.com/developer/public-invite/244356
3. Click Accept Invite & Build a Zap.

Zilch will now appear in your app search inside Zapier like any other app.

Step 5 — Connect your accounts in Zapier

You can do this up front, which makes building the Zap smoother.

Connect Zilch

1. In Zapier, go to Apps in the left sidebar.
2. Click Add connection and search for Zilch.
3. Paste your secret API key (zlch_sk_…) from Step 3.
4. Click Yes, Continue.

If the key is valid, the connection appears named after your organisation and account type, e.g. Acme Promotions (Distributor). That's a good sign — it means Zilch recognised the key and knows who you are.

Connect Xero

1. Still on the Apps page, click Add connection and search for Xero.
2. You'll be redirected to Xero to log in.
3. Select the Xero organisationyou want to connect. If you manage several organisations, take care here — picking the wrong one is easy and the Zap will silently watch the wrong company's invoices.
4. Click Allow access.

Step 6 — Create the Zap and set the trigger

1. In Zapier, click Create → Zaps (or + Create Zap).
2. Give it a clear name, e.g. Xero invoice → send Zilch footprint report.

Configure the trigger

1. For the trigger app, search for and select Xero.
2. For the Event, choose New Sales Invoice.
3. Click Continue.
4. For Account, choose the Xero connection you made in Step 5. Click Continue.
5. On the Trigger / configuration screen, if you're offered an Organisation or Tenant dropdown, select the correct Xero organisation.
6. Click Continue, then Test trigger.

Zapier will pull in a recent sales invoice from Xero as sample data.

Read the sample data carefully

This is worth two minutes of your attention, because it tells you exactly what you'll have to work with:

• Find the customer's email address. Look for a field like Contact Email Address. If it's present and populated, great — you'll map it in Step 9. If it's blank or missing, your Xero contacts don't have email addresses saved, and you'll need the optional step in Step 8.
• Find the line items. You should see a repeating group of line items, each with an item code, a description, and a quantity. If the item codes are empty, go back to Step 2 — your invoices aren't using Xero items.
• Find the invoice number, e.g. Invoice Number or Reference. You'll use this as the order reference.

Which trigger should I use?

New Sales Invoice is the right default: it fires when the invoice is raised, so the customer gets their report along with the invoice.

Alternatives, depending on when you'd rather the report go out:

Step 7 — (Recommended) Add a Filter so you only send when you should

Without a filter, every sales invoice triggers a report — including invoices to internal accounts, test invoices, or invoices with nothing assessed on them. A filter prevents awkward emails.

1. Click + below the trigger and choose Filter by Zapier.
2. Add one or more conditions. Useful ones:

Multiple conditions on the same filter are combined with AND — all must pass.

Click Continue. Zapier tells you whether your sample invoice would have passed. If it says the Zap would have stopped, check your conditions against the actual sample values.

Step 8 — (Only if needed) Look up the customer's email address

Skip this step if the trigger's sample data already contained a populated Contact Email Address.

If it didn't, add a lookup step:

1. Click + and choose Xero again.
2. Event: Find Contact. Click Continue.
3. Choose your Xero account. Click Continue.
4. In the search field, map the Contact Name (or Contact ID) from the trigger.
5. Click Continue, then Test step.
6. Check the result contains an email address. You'll map thisstep's email field in Step 9 instead of the trigger's.

Step 9 — Add the Zilch action and map the fields

This is where the report actually gets sent.

1. Click + at the bottom of your Zap.
2. Search for and select Zilch.
3. For Event, choose Send Product Report to Customer. Click Continue.
4. For Account, choose your Zilch connection from Step 5. Click Continue.

Now fill in the fields. Click into each one and pick the matching value from the Xero trigger step (Zapier shows a dropdown of available data).

Mapping the line items

Order Line Items is a repeating group with two sub-fields — Product SKU and Quantity. You need to map Xero's invoice lines onto it so that every product on the invoice ends up in one report.

1. Click into the Product SKU field under Order Line Items.
2. From the Xero trigger data, select the line item Item Code field — the one that represents the item codes for all lines on the invoice, usually shown as a line-item group rather than a single value.
3. Click into the Quantity field.
4. Select the corresponding line item Quantity field from the same group.

Order Line Items
  ├─ Product SKU  →  1. Line Items Item Code
  └─ Quantity     →  1. Line Items Quantity

The key thing is that both fields come from the same line-item group in the Xero data, so that codes and quantities stay paired up correctly. If you map an item code from one group and a quantity from another, quantities will attach to the wrong products.

Why Order Reference matters

Zilch de-duplicates sends. If the same customer + same order reference + same line items comes through again within 24 hours, Zilch recognises it as a repeat and returns already_sent instead of emailing the customer a second time.

This protects you against Zapier retries, an invoice being edited and re-saved, or someone accidentally turning the Zap off and on again. Map the invoice number here— it's the single best safeguard against double-emailing a customer.

Step 10 — Test the whole thing end to end

Click Continue, then Test step.

Zapier sends a real report to a real email address — the one in your sample data. So before you click test:

A successful test returns:

{
  "status": "sent",
  "report_id": "11111111-2222-3333-4444-555555555555",
  "customer_email": "you@yourcompany.com",
  "order_reference": "INV-0042",
  "total_emissions_kg": 246.8,
  "product_count": 2,
  "skipped_skus": ["FREIGHT"]
}

Check these three things:

• product_count matches the number of assessed products on the invoice.
• skipped_skusonly contains things you'd expect to be skipped (freight, discounts). If a real product is in there, its SKU doesn't match or it has no completed assessment.
• The email arrives, looks right, and the numbers are correct.

Also confirm the report was recorded: go to Zilch → Settings → Reports. Your test report should be listed there, exactly like one sent by hand.

Step 11 — Turn the Zap on

1. Click Publish (top right).
2. Toggle the Zap On.

From now on, every new sales invoice in Xero that passes your filter will automatically send your customer their carbon footprint report.

For the first week, keep an eye on it:

• Zapier → Zap History shows every run, whether it succeeded, and the exact data that was sent. This is the first place to look when something seems off.
• Zilch → Settings → Reports shows every report that went out.

Troubleshooting

Errors from Zilch

Other common problems

The report is missing a product.

Check skipped_skusin the Zap History for that run. A SKU appears there when it doesn't match anything in your catalogue, or when the product has no completed footprint. Fix the item code in Xero or finish the assessment in Zilch.

Quantities are wrong or attached to the wrong products.

Your SKU and Quantity fields are mapped from different line-item groups. Re-do the line item mapping in Step 9, taking both fields from the same group.

A customer got the report twice.

Check that Order Referenceis mapped (Step 9). Without it, Zilch's de-duplication has much less to work with. With the invoice number mapped, repeat sends within 24 hours are blocked automatically.

The Zap doesn't fire when I raise an invoice.

• Make sure the invoice is approved, not left as a draft, and has a contact attached.
• Check your Filter step isn't stopping it — Zap History shows filtered-out runs.
• Confirm the Zap is toggled On.
• Confirm the Xero connection points at the right organisation.

Xero requires a premium Zapier plan.

Xero is classified as a premium app by Zapier and needs a paid Zapier plan.

Xero rate limits.

Xero allows 60 API calls per minute and 5,000 per day per organisation, shared across everything connected to it. High invoice volumes combined with other Xero integrations can hit this. Zapier will retry.

Limits and built-in safeguards

Variations worth knowing about

Send on payment instead of on invoice

Use the New Payment trigger instead of New Sales Invoice in Step 6. Note it only picks up payments from the last 7 days.

Only send for orders above a certain value

Add a Filter (Step 7) on Invoice Total → (Number) Greater than → your threshold.

Check a product's footprint before doing something else

The Zilch integration also provides a Find Product by SKUsearch step. Given a SKU it returns the product name, total kg CO₂e, the breakdown by materials/packaging/decoration/transport/manufacturing, a link to the results page, and a PDF link. It returns nothing when no completed assessment exists, which makes it useful as a filter — for example, to notify your team on Slack when someone sells a product that hasn't been assessed yet.

Use a different system instead of Xero

Nothing here is Xero-specific past Step 6. The same Zilch action works with QuickBooks, Shopify, HubSpot, WooCommerce, or any other Zapier app that exposes order line items — map the SKU and quantity fields the same way. See the Zapier integration guide for the full list of steps and example Zaps.

Need help?

• Zapier-side issues (connections, triggers, mapping): check Zap History first — it shows the exact data at every step.
• Zilch-side issues (SKUs, assessments, plans, reports): contact us at info@tryzilch.com, and include the report_id or the Zap History run if you have one.

For direct API access without Zapier, see the Partner API guide.