DEV Community

choong
choong

Posted on

4 APIs to Build an Export-Ready Invoice Generation Workflow in Xero

#tooling #api #automation

The average invoicing softwares are designed for domestic billing.

While they handle tax, formatting, and payment terms well; they lack support for cross border trade functions like custom compliance: no HS code lookup, no destination country logic, no audit trail for where the code came from.

You end up doing these part manually every time.

Here's how to automate it.

The workflow

Pull product and order data from Xero → classify each product line with HS Ping → write the HS codes back into the Xero invoice.

API #1 — Xero (your system of record)

Xero is where your order and product data lives.

You're pulling two things:

  • the line items on a draft invoice (product description, quantity, unit price)
  • the buyer's details. 
GET https://api.xero.com/api.xro/2.0/Invoices/{InvoiceID}
Enter fullscreen mode Exit fullscreen mode

The response gives you the full invoice object including LineItems, each with a Description field.

That description is what you'll feed into HS Ping.

Tips: You'll need OAuth 2.0 with the accounting.transactions scope. Xero has a sandbox environment with the rate limits of 5,000 calls/day per org.

API #2 — HS Ping (HS classification)

HS Ping looks up the correct HS code for a product term against official tariff data, sourced directly from official government sources.

The /find endpoint works best with a concise commodity term rather than a full product title.

"Ceramic mug" works well.

"Hand-painted 12oz artisan mug with gift box" will likely return nothing useful.

GET https://api.hsping.com/api/v1/find?q=ceramic+mug&country=US
Enter fullscreen mode Exit fullscreen mode

The response returns the HS code, description, source, and version, everything you need to cite on a compliant commercial invoice.

{
  "query": "ceramic mug",
  "country": "US",
  "results": [
    {
      "hscode": "6912000000",
      "description_en": "Ceramic tableware, kitchenware...",
      "source": "HTSUS",
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Tips: This is where a lightweight LLM call earns its keep. Pass your full Xero line item description in, get a clean 2–3 word commodity term out, then feed that into HS Ping. It removes the last manual step without overcomplicating the stack.

API #3 — Xero again (write HS code back to invoice)

Once you have the HS code, you update each line item on the draft invoice in Xero.

The Description field is the natural place to append the code. Most commercial invoice formats expect it there or in an adjacent field.

POST https://api.xero.com/api.xro/2.0/Invoices/{InvoiceID}
Enter fullscreen mode Exit fullscreen mode 
{
  "LineItems": [
    {
      "LineItemID": "<existing_line_item_id>",
      "Description": "Ceramic mug — HS 6912.00.0000",
      "Quantity": 200,
      "UnitAmount": 4.50
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Once updated, you can set the invoice status to SUBMITTED or APPROVED to lock it before delivery.

Putting Everything Together

Your app fetches the draft invoice from Xero, calls HS Ping per line item to retrieve the HS code, then writes it back to the Xero invoice.

Note

Xero handles the invoice, HS Ping handles the classification; but duty calculation, denied party screening, and filing the actual customs declaration are downstream problems this workflow doesn't solve.

With the completed invoice ready, your freight forwarder can easily take it from here.

Top comments (0)