DEV Community: choong

How to Build a Multi-Step HS Classification Workflow with 3 APIs

choong — Fri, 27 Mar 2026 01:38:45 +0000

A wrong HS code on a commercial invoice can mean your shipment gets held at customs, you get hit with unexpected duties, or you trigger a compliance flag that takes days to resolve.

Most businesses still handle this manually. Someone Googles the product, cross-references a tariff schedule, makes their best guess, and types it in.

It works, until it doesn't.

And even when it does, a single misclassification on a high-value shipment is the kind of mistake that reminds you why experienced customs brokers exist.

Here's how to build a workflow that classifies your products systematically, with a human review step built in for anything the system isn't confident about.

The workflow

Product data in (photo, spec, or text) → Gemini normalises it into a clean commodity term → HS Ping classifies it and returns the HS code → low-confidence results are flagged for human review → approved codes written back to your system.

The multi-step part is deliberate. Full automation without a human review gate is how classification errors get baked silently into your operations.

API #1 — Gemini (product normalisation)

Gemini is Google's multimodal AI API.

It handles the messiest part of the workflow: turning whatever product data you have (example: a photo, a spec sheet excerpt, or a raw product title) into a clean 2–3 word commodity term that the HS code lookup API, HS Ping can work with reliably.

This is the step most HS classification workflows skip, and it's the reason they produce poor results. "Hand-painted 12oz ceramic mug with bamboo lid — gift box included" is not a useful input for a tariff lookup. "Ceramic mug" is.

For a product photo or spec upload, you pass the image as base64:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent

Headers:
  x-goog-api-key: YOUR_API_KEY
  Content-Type: application/json

{
  "contents": [{
    "parts": [
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "<base64_encoded_image>"
        }
      },
      {
        "text": "Identify the product in this image. Return only a short 2-3 word commodity term suitable for customs classification. No explanation."
      }
    ]
  }]
}

For a plain text product title or spec, drop the inline_data block and pass the description directly in the text field. Same endpoint, same model.

Tips: Be explicit in your prompt that you want only the commodity term returned — no explanation, no preamble. Gemini will otherwise return a full sentence. gemini-3-flash-preview has a free tier, making it practical for prototyping without upfront cost.

API #2 — HS Ping (classification)

HS Ping looks up the HS code for your cleaned commodity term against official tariff data, sourced directly official government sites.

You pass the term and the destination country, and it returns the HS code, description, source publication, and version.

For a single product:

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

Headers:
  Authorization: Bearer YOUR_API_KEY

For bulk classification like a product catalog or CSV import, you can use the batch endpoint instead:

POST https://api.hsping.com/api/v1/find

Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

[
  { "query": "ceramic mug", "country": "US" },
  { "query": "polycarbonate sheet", "country": "US" },
  { "query": "leather wallet", "country": "US" }
]

Both endpoints return the same response structure per query item.

The batch endpoint means you don't need to loop and fire individual requests for large catalogs, which keeps processing time and rate limit usage manageable.

API #3 — Your ERP or system of record (write-back)

Once a code is approved (automatically or by a reviewer), you write it back to wherever your product data lives. The exact endpoint depends on your system.

For a generic REST-based ERP or PIM:

PATCH https://your-erp.com/api/products/{product_id}

Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

{
  "hs_code": "6912000000",
  "hs_source": "HTSUS",
  "hs_classified_at": "2026-03-17T10:00:00Z"
}

If your system doesn't have a write-back API, export the approved results as a CSV and import manually.

Not glamorous, but it keeps the classification logic automated even if the final sync isn't.

How Everything Works Together

Your app accepts the product input, calls Gemini to normalise it, calls HS Ping to classify it, evaluates the result against your confidence rules, and writes back approved codes.

Flagged items wait in a review queue.

Nothing gets written back without either a clean automated match or a human sign-off.

What this doesn't cover

Duty rate calculation and denied party screening are downstream steps this workflow doesn't solve.

If you need a customs-ready commercial invoice at the end of the process rather than just classified product records, pairing this workflow with an invoice generation layer is the natural next step.

4 APIs to Automate Expense Reporting: Receipt Scan Slack Approval Payout

choong — Wed, 25 Mar 2026 02:18:29 +0000

Every finance manager has a folder they don't talk about.

A quiet accumulation of receipt photos, Slack forwards, and email attachments with subjects like "pls reimburse ty." It grows a little every week, an it never shrinks on its own.

Here's how to stop feeding that folder, with a scan to bank transfer automated workflow.

The workflow

Employee submits a receipt → Veryfi extracts the data → Slack sends the manager an approve/reject message → QuickBooks logs the expense → Wise transfers the reimbursement.

API #1 — Veryfi (receipt OCR)

Veryfi takes a receipt image or PDF and returns structured JSON in seconds: vendor name, date, total amount, line items, currency, and tax.

It's pre-trained on hundreds of millions of receipts and works across 38 languages and 91 currencies.

No model training required on your end.

POST https://api.veryfi.com/api/v8/partner/documents/

Headers:
  CLIENT-ID: your_client_id
  AUTHORIZATION: apikey your_username:your_api_key
  Content-Type: application/json

{
  "file_url": "https://your-storage.com/receipts/receipt-001.jpg",
  "tags": ["expense", "reimbursement"],
  "categories": ["Meals", "Travel", "Office Supplies"]
}

The response gives you total, vendor.name, date, currency_code, and a full line_items array. All of that feeds into the Slack message in the next step.

API #2 — Slack (manager approval)

Rather than routing approvals through email, you send the manager an interactive Slack message using Block Kit - Slack's UI framework for composing messages with buttons and structured data.

The manager sees the receipt details and clicks Approve or Reject directly in Slack.

POST https://slack.com/api/chat.postMessage

Headers:
  Authorization: Bearer xoxb-your-bot-token
  Content-Type: application/json

{
  "channel": "manager-slack-user-id",
  "text": "New expense reimbursement request",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*New expense request*\n*Employee:* John Doe\n*Vendor:* Marriott\n*Amount:* USD 189.00\n*Date:* 2025-03-10"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "Approve" },
          "style": "primary",
          "action_id": "approve_expense",
          "value": "expense_id_123"
        },
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "Reject" },
          "style": "danger",
          "action_id": "reject_expense",
          "value": "expense_id_123"
        }
      ]
    }
  ]
}

When the manager clicks a button, Slack sends an interaction payload to your app's endpoint with the action_id and value. You use that to trigger the next step.

Tips: You'll need to enable Interactivity in your Slack app settings and provide a Request URL — that's the endpoint your app exposes to receive button click payloads. Test this locally first using a tunnel like ngrok before deploying.

API #3 — QuickBooks (accounting sync)

Once approved, you log the expense in QuickBooks Online via the Purchase endpoint. This creates a record in the books against the right account and employee.

POST https://quickbooks.api.intuit.com/v3/company/{realmId}/purchase

Headers:
  Authorization: Bearer your_oauth2_access_token
  Content-Type: application/json
  Accept: application/json

{
  "PaymentType": "Cash",
  "AccountRef": { "value": "35", "name": "Checking" },
  "EntityRef": { "value": "employee_id", "type": "Employee" },
  "TotalAmt": 189.00,
  "Line": [
    {
      "Amount": 189.00,
      "DetailType": "AccountBasedExpenseLineDetail",
      "AccountBasedExpenseLineDetail": {
        "AccountRef": { "value": "7", "name": "Travel" }
      }
    }
  ]
}

API #4 — Wise (reimbursement payout)

Wise handles the actual bank transfer to the employee.

It's API-first, uses the mid-market exchange rate with a flat transparent fee, and works for both domestic and international payouts across 40+ currencies.

The payout flow is three calls: create a quote, create the transfer, then fund it.

# Step 1 — Create a quote
POST https://api.wise.com/v3/profiles/{profileId}/quotes

{
  "sourceCurrency": "USD",
  "targetCurrency": "USD",
  "sourceAmount": 189.00,
  "targetAccount": "<recipient_account_id>"
}

# Step 2 — Create the transfer
POST https://api.wise.com/v1/transfers

{
  "targetAccount": "<recipient_account_id>",
  "quoteUuid": "<quote_id_from_step_1>",
  "customerTransactionId": "expense_id_123",
  "details": { "reference": "Expense reimbursement — March 2025" }
}

# Step 3 — Fund the transfer
POST https://api.wise.com/v3/profiles/{profileId}/transfers/{transferId}/payments

{
  "type": "BALANCE"
}

Piecing things together

Your app receives the receipt, calls Veryfi to extract the data, formats it into a Slack Block Kit message, and waits for the manager's response.

On approval, it logs the expense in QuickBooks and triggers the Wise payout.

The whole chain from submission to transfer initiation runs without anyone opening a spreadsheet.

Final note: What this doesn't cover

Receipt policy enforcement: flagging expenses that exceed per-category limits, and multi-level approval chains are not covered here.

Those are logic layers you can add on top of the Slack interaction step, no additional APIs needed.

Automate Your HR Recruitment Pipeline with These 4 APIs

choong — Mon, 23 Mar 2026 14:05:36 +0000

Most HR recruitment pipelines share the same bottleneck, it goes something like this:

The recruiter manually opens each application, downloads the resume, reads through it, copies details into a spreadsheet, emails the candidate to book a call, and chases the background check days later.

It's fine when you're hiring once a quarter.

When you're running multiple roles at once, it falls apart - fast.

Here's how to automate the screening half of that pipeline: from application received to interview scheduled.

The workflow

Candidate applies via Greenhouse → resume parsed automatically by APILayer → background check triggered via Checkr → interview booked via SavvyCal.

The recruiter's job goes from processing paperwork to reviewing a structured shortlist.

API #1 — Greenhouse (your system of record)

Greenhouse is where candidates apply and where their records live throughout the hiring process.

Rather than polling for new applications, you subscribe to the application_submitted webhook topic, which fires the moment a candidate completes their application.

POST https://{your-domain}.greenhouse.io/webhooks

{
  "webhook": {
    "name": "New application trigger",
    "url": "https://your-app.com/webhooks/application",
    "event": "application_submitted",
    "secret_key": "your_secret_key"
  }
}

The payload includes the candidate's name, email, application ID, and a URL to their attached resume.

That resume URL is what feeds into the next step.

Tips: Greenhouse's Harvest API v1 and v2 are being deprecated after August 2026 — build against v3 from the start. API keys are managed under Configure → Dev Center → API Credential Management, and permissions are scoped per endpoint.

API #2 — APILayer Resume Parser (resume parsing)

APILayer's Resume Parser takes a resume in PDF or Word format and returns structured JSON: name, email, skills, work history, education.

Free tier is available with no credit card required, paid plans start at $9.99/month for higher volumes.

You pass the resume URL from the Greenhouse webhook payload directly:

POST https://api.apilayer.com/resume_parser/url

Headers:
  apikey: YOUR_API_KEY

{
  "url": "<resume_url_from_greenhouse_payload>"
}

The response gives you structured candidate data you can write back to Greenhouse or use to score the application against your job requirements.

Tips: The parser handles PDF and DOCX well but can struggle with heavily designed or image-based resumes. Plain text CVs get the most accurate results.

API #3 — Checkr (background check)

Checkr is an API-first background check platform.

You trigger a check programmatically once a candidate clears the initial resume screen, without follow-up emails, or chasing providers.

POST https://api.checkr.com/v1/invitations

{
  "package": "tasker_standard",
  "candidate_id": "<checkr_candidate_id>",
  "work_locations": [{ "country": "US" }]
}

Checkr sends the candidate an email to complete their consent form. When the check completes, a webhook fires back to your app with the result, which you can use to gate the next step.

API #4 — SavvyCal (interview scheduling)

Once the background check clears, you automatically send the candidate an interview slot.

SavvyCal has a clean REST API that lets you query available slots and book one programmatically.

It's a two-call pattern. First, get available slots for the interviewer's scheduling link:

GET https://savvycal.com/api/v1/scheduling_links/{link_slug}/slots

Headers:
  Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Then book the first available slot on the candidate's behalf:

POST https://savvycal.com/api/v1/events

{
  "scheduling_link_slug": "<link_slug>",
  "start_at": "<slot_start_at_from_previous_call>",
  "attendees": [
    {
      "name": "<candidate_name>",
      "email": "<candidate_email>"
    }
  ]
}

This sends a calendar invite to the candidate, while the interviewer's calendar updates automatically.

How Everything Works Together

Your app listens on a webhook endpoint. Greenhouse fires when an application comes in, you parse the resume, trigger the background check, and — once it clears — automatically book the interview.

The recruiter steps in at the review stage with a structured candidate profile already waiting in Greenhouse.

Compare to doing this manually in Greenhoue

Greenhouse does have built-in stages and scorecards for managing candidates.

However, it doesn't automatically move candidate between stages. From "applied" to "screened" to "interview scheduled", you still require someone to manually trigger each step.

At low volume that's fine. When you're handling dozens of applications a week across multiple roles, the manual overhead adds up quickly.

Final note: What this doesn't cover

This workflow handles the screening pipeline:

Application in
Interview scheduled.

The interview itself, feedback collection, and offer letter are outside the scope here.

If you want to close the loop on the offer side, pairing this with a transactional email API like Resend to programmatically send offer letters is a natural next step.

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

choong — Wed, 18 Mar 2026 14:03:17 +0000

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}

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

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",
    }
  ]
}

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}

{
  "LineItems": [
    {
      "LineItemID": "<existing_line_item_id>",
      "Description": "Ceramic mug — HS 6912.00.0000",
      "Quantity": 200,
      "UnitAmount": 4.50
    }
  ]
}

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.

Build an Automated Order Fulfilment Workflow in Shopify with These 3 APIs

choong — Mon, 16 Mar 2026 05:48:43 +0000

(Fulfilment? Fulfillment?)

Anyways, since I started with Shopify clients, I have observed many of them fulfill orders the same way:

They log into the dashboard
Check the order
Manually copy the address into a separate shipping portal like Shippo
Generate a shipping label
Download it
Print it
Finally, manually send a confirmation email to the customer

Repeat for every order.

It works, until it doesn't. When you're doing 50 orders a day, one person can't keep up, and mistakes start to cost you real money.

Here's how you can automate the whole thing with 3 APIs.

The workflow

Order placed on Shopify → Shippo generates the shipping label automatically → Resend sends the customer a confirmation email with tracking info.

API #1 — Shopify (your system of record)

Shopify is where the order lives.

Rather than polling for new orders, you subscribe to the orders/create webhook topic, which fires a POST to your endpoint the moment a customer checks out.

POST https://{shop}.myshopify.com/admin/api/2025-01/webhooks.json

{
  "webhook": {
    "topic": "orders/create",
    "address": "https://your-app.com/webhooks/orders",
    "format": "json"
  }
}

The payload gives you everything: customer name, shipping address, line items, order ID.

That's the input for the next step.

Tips: As of April 2025, Shopify requires new public apps to use the GraphQL Admin API. If you're building a private or custom app, the REST endpoint above still works fine.

API #2 — Shippo (shipping label generation)

Shippo connects to 85+ carriers and gives you a single API to generate labels across all of them.

Pricing is pay-as-you-go, labels start at around $0.05 per label fee on top of the carrier rate.

You call it in two steps: create a shipment object (which returns available rates), then purchase the label against your chosen rate.

Step 1 — Create shipment, get rates

POST https://api.goshippo.com/shipments/

{
  "address_from": { ...from Shopify store settings },
  "address_to": { ...from Shopify order payload },
  "parcels": [{ "length": "10", "width": "8", "height": "4",
                "distance_unit": "in", "weight": "2", "mass_unit": "lb" }]
}

Step 2 — Purchase label

POST https://api.goshippo.com/transactions/

{
  "rate": "<rate_object_id from step 1>",
  "label_file_type": "PDF",
  "async": false
}

The response gives you label_url (the printable PDF) and tracking_number. Both go into the next step.

API #3 — Resend (customer notification)

Resend is a developer-first transactional email API. Free tier covers 3,000 emails/month, no daily cap on paid plans, and the API is genuinely one of the cleanest out there right now.

You fire a single POST once you have the tracking number from Shippo:

POST https://api.resend.com/emails

{
  "from": "orders@yourstore.com",
  "to": ["customer@email.com"],
  "subject": "Your order is on its way 📦",
  "html": "<p>Hi [name], your order has shipped. Track it here: [tracking_url]</p>"
}

Tips: Using the same endpoint, you can fire a second email asking for a review 48–72 hours later.

How Everything Works Together

Your app listens on a webhook endpoint.

When a customer creates a new order, Shopify fires orders/create, where you extract the shipping address, call Shippo to generate a label, then call Resend with the tracking number.

The whole chain runs in a few seconds.

A quick note on LLMs: if your catalog has inconsistent product weights or dimensions (common with handmade or variable goods), an LLM can sit between Shopify and Shippo to infer parcel specs from product descriptions — removing the last bit of manual input. Worth knowing, but not required to get started.

How about Shopify's built-in tools?

Shopify does have native shipping and email notification features, they work fine for the average merchants who are just getting started.

Once your order volume hits a certain threshold, you will need to customize the logic, rate-shop across carriers programmatically, or plug in your own notification timing and content.

All of these cannot be done easily without an app or a paid plan upgrade.

Building it yourself with these three APIs gives you full control and costs less at volume.

Final note: What this doesn't cover

Admittedly, inventory sync, returns, and international customs are separate problems that are not covered here.