Flexport Core Workflow B: Invoices & Products Skill

Flexport Core Workflow B: Invoices & Products

Overview

Manage Flexport commercial invoices for customs clearance, maintain the product catalog for landed cost calculations, and handle freight billing. These APIs complement the booking/shipment workflow in flexport-core-workflow-a.

Prerequisites

Completed flexport-install-auth setup
Existing shipments or bookings (from workflow A)
Product SKUs defined in your system

Instructions

Step 1: Manage Product Catalog

const BASE = 'https://api.flexport.com';
const headers = {
  'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
  'Flexport-Version': '2',
  'Content-Type': 'application/json',
};

// POST /products — add products to the Flexport Product Library
const product = await fetch(`${BASE}/products`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Industrial Widget Type A',
    sku: 'WIDGET-A',
    hs_code: '8479.89',              // Harmonized System code for customs
    country_of_origin: 'CN',
    unit_cost: { amount: 12.50, currency: 'USD' },
    weight: { value: 2.5, unit: 'kg' },
    dimensions: { length: 30, width: 20, height: 15, unit: 'cm' },
  }),
}).then(r => r.json());

console.log(`Product: ${product.data.id} | SKU: ${product.data.sku}`);

Step 2: Create Commercial Invoices

// POST /commercial_invoices — required for customs clearance
const invoice = await fetch(`${BASE}/commercial_invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    shipment_id: 'shp_abc123',
    invoice_number: 'CI-2025-001',
    seller: { name: 'Shanghai Supplier Co.' },
    buyer: { name: 'Acme Corp' },
    line_items: [
      {
        product_id: product.data.id,
        quantity: 500,
        unit_price: { amount: 12.50, currency: 'USD' },
        total_price: { amount: 6250.00, currency: 'USD' },
      },
    ],
    total_value: { amount: 6250.00, currency: 'USD' },
    currency: 'USD',
    incoterm: 'FOB',
  }),
}).then(r => r.json());

console.log(`Invoice: ${invoice.data.id} | Total: $${invoice.data.total_value.amount}`);

Step 3: Retrieve Freight Invoices

// GET /freight_invoices — Flexport billing for freight services
const freightInvoices = await fetch(
  `${BASE}/freight_invoices?status=outstanding&per=10`, { headers }
).then(r => r.json());

freightInvoices.data.records.forEach((inv: any) => {
  console.log(`${inv.invoice_number} | ${inv.status} | $${inv.total.amount}`);
  inv.line_items?.forEach((li: any) => {
    console.log(`  ${li.description}: $${li.amount.amount}`);
  });
});

Step 4: Search Products by SKU

// GET /products — search and filter product catalog
const products = await fetch(
  `${BASE}/products?sku=WIDGET&per=25`, { headers }
).then(r => r.json());

products.data.records.forEach((p: any) => {
  console.log(`${p.sku} | ${p.name} | HS: ${p.hs_code} | Origin: ${p.country_of_origin}`);
});

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 422 invalid HS code | Malformed Harmonized System code | Use 6-10 digit HS codes (e.g., 8479.89) | | 404 shipment not found | Wrong shipment ID on invoice | Verify shipment exists first | | 400 missing line items | Invoice has no products | Add at least one line item | | 409 duplicate invoice | Invoice number reused | Use unique invoice numbers per shipment |

Examples

Update Product HS Code

await fetch(`${BASE}/products/${productId}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ hs_code: '8479.89.9599' }),  // More specific code
});

Bulk Product Import

const products = csvData.map(row => ({
  name: row.name, sku: row.sku, hs_code: row.hsCode,
  country_of_origin: row.origin,
  unit_cost: { amount: parseFloat(row.cost), currency: 'USD' },
}));

for (const product of products) {
  await fetch(`${BASE}/products`, { method: 'POST', headers, body: JSON.stringify(product) });
}

Resources

Next Steps

For common errors, see flexport-common-errors.

Agent Skills: Flexport Core Workflow B: Invoices & Products

Install this agent skill to your local

Skill Files