AR Records: Tai → Third Party

What this is for

Every customer invoice generated inside Tai — whether printed, factored, revised, or held for review — is a receivable that needs to hit your accounting system so aging reports, collection queues, and cash-flow forecasts stay accurate. This flow is how each Tai invoice gets in front of your AR team the moment it exists, and how you make sure none of them fall through the cracks even if your integration briefly goes offline.

Common downstream uses: posting to a GL (Accounts Receivable + Freight Revenue), triggering a customer statement run, updating a factor's ledger, or feeding a business-intelligence pipeline for revenue reporting.

Delivery — Webhooks (live)

Two webhook variants are available. Register whichever matches how much shipment context your downstream system needs.

InvoiceCreateUrl — invoice alone. Lightest payload; use when you only need the accounting fields.
InvoiceCreateWithShipmentUrl — invoice plus the full shipment (origin/destination stops, commodities, equipment). Use when you want to attach shipment metadata to the accounting entry without a second lookup.

HOOK  InvoiceCreateUrl              → POST {your-registered-url}
HOOK  InvoiceCreateWithShipmentUrl  → POST {your-registered-url}

Register the URL(s) in Tai as an IntegrationSourceParameter. Tai POSTs to your endpoint on every invoice create; you respond 2xx to acknowledge.

Example payload (InvoiceCreateUrl) — real shape returned by the API

{
  "invoiceId": 14041027,
  "billingOrganization": {
    "organizationId": 40750,
    "name": "Acme Brokerage LLC",
    "address": {
      "streetAddress": "111 Broker Way",
      "streetAddressTwo": "",
      "city": "LONG BEACH",
      "state": "CA",
      "zipCode": "90802",
      "country": "USA"
    },
    "billToAddress": {
      "streetAddress": "111 Broker Way",
      "streetAddressTwo": "",
      "city": "LONG BEACH",
      "state": "CA",
      "zipCode": "90802",
      "country": "USA"
    },
    "phone": "",
    "mobile": "",
    "fax": "+15625550100",
    "parentIds": ",30843,",
    "referenceNumber": "",
    "modifiedById": 774705,
    "modifiedByName": "Broker Admin",
    "organizationType": "LSP",
    "modifiedDate": "2017-09-27T20:58:13.697+00:00",
    "createdDate": "2017-09-27T20:58:13.697+00:00"
  },
  "payerOrganization": {
    "organizationId": 660295,
    "name": "Apple Logistics",
    "address": {
      "country": "USA"
    },
    "billToAddress": {
      "streetAddress": "",
      "streetAddressTwo": "",
      "city": "",
      "zipCode": "",
      "country": "USA"
    },
    "parentIds": ",30843,40750,660433,",
    "referenceNumber": "APPLE23",
    "modifiedById": 778848,
    "modifiedByName": "AR Clerk",
    "organizationType": "Customer",
    "modifiedDate": "2024-02-27T16:27:51.967+00:00",
    "createdDate": "2024-02-27T16:27:51.967+00:00"
  },
  "invoiceAccountingProfile": {
    "paymentPreference": "Credit Approved",
    "paymentTerms": 31,
    "preferredInvoicingMethod": "Email",
    "podRequiredWithInvoice": false,
    "bolRequiredWithInvoice": false
  },
  "invoiceDate": "2026-09-04T08:00:00+00:00",
  "invoiceNumber": "121396145",
  "invoiceDueDate": "2026-10-05T08:00:00+00:00",
  "isRevision": false,
  "totalAmount": 2431.75,
  "totalAmountApplied": 0.00,
  "paymentStatus": "Unpaid",
  "externalSync": {
    "date": "2026-09-04T20:00:51.397+00:00",
    "status": "None",
    "referenceNumber": null
  },
  "lineItems": [
    {
      "invoiceLineItemId": 34980566,
      "quantity": 1.0,
      "description": "Linehaul",
      "amount": 2175.00,
      "externalSync": { "status": "None" },
      "account": {
        "generalLedgerAccountId": 0,
        "accountCode": "Linehaul Income",
        "accountType": "Accounts Receivable",
        "creditAccount": false
      },
      "calculationType": "Flat"
    },
    {
      "invoiceLineItemId": 34980567,
      "quantity": 1.0,
      "description": "Fuel Surcharge",
      "amount": 256.75,
      "externalSync": { "status": "None" },
      "account": {
        "generalLedgerAccountId": 0,
        "accountCode": "Sales Revenue",
        "accountType": "Accounts Receivable",
        "creditAccount": false
      },
      "calculationType": "Flat"
    },
    {
      "invoiceLineItemId": 34980568,
      "quantity": 1.0,
      "description": "Liftgate at Delivery",
      "accessorialCode": "LFTD",
      "amount": 0.00,
      "externalSync": { "status": "None" },
      "account": {
        "generalLedgerAccountId": 0,
        "accountCode": "Sales Revenue",
        "accountType": "Accounts Receivable",
        "creditAccount": false
      },
      "calculationType": "Flat"
    }
  ]
}

InvoiceCreateWithShipmentUrl returns the same body wrapped alongside a shipment object with origin/destination stops, commodities, and equipment — useful when the third party wants to attach shipment metadata to the accounting entry without a second lookup.

Key fields

Field	Type	Notes
`invoiceId`	int	Tai's primary key for the invoice. Use this in the sync callback.
`billingOrganization`	object	The broker org issuing the invoice — your Tai accounting org.
`payerOrganization`	object	The customer being invoiced. `payerOrganization.referenceNumber` is round-trippable — if you set it via the Customer inbound flow, your ERP's customer ID lands here on every invoice.
`invoiceAccountingProfile`	object	Payer's payment terms, invoicing preferences, and PoD/BoL requirements at the time of invoicing.
`invoiceNumber`	string	Human-readable invoice number generated by Tai (often mirrors the shipment number by default).
`paymentStatus`	enum	`Unpaid`, `Partial Paid` (note the space), `Fully Paid`, `Over Paid`, `Open`.
`externalSync.status`	enum	`None` on new records — flips to `Complete` or `Failed` after your `PUT /Sync` call.
`externalSync.referenceNumber`	string	Your target system's ID once you've synced. `null` when unsynced.
`lineItems[]`	array	Charge breakdown (linehaul, fuel, accessorials, etc.) each with its own GL `account` block.

Delivery — Batch (backup or primary)

Anything the webhook didn't deliver still carries externalSync.status = "None". Poll this endpoint on your schedule to pick up the strays. Returns an array of the same invoice shape as above.

GET  /PublicApi/Accounting/v2/Invoices?SyncStatus=None

View in API Reference →

Parameter	Values	Purpose
`SyncStatus`	`None`, `Complete`, `Failed`, `AlreadySynced`, `Updated`	Filter to unsynced records for the batch backup.

Sample response — array of invoice objects, each with the full shape shown above.

Integration notes

Field casing: all Tai Public API responses use camelCase. Requests are case-insensitive on parse but the responses will be camelCase.
Cadence: if you're using webhook + batch, an hourly or nightly batch is usually enough — the webhook covers the common path, the batch covers outages. Batch-only integrations typically run every 5-15 minutes.
Cross-referencing to your GL — two options:
- Option A — Store the mapping on your side: save Tai's payerOrganization.organizationId alongside your ERP's customer key in a mapping table. Works with any integration, but you're responsible for keeping the mapping in sync as customers get renamed, merged, or archived.
- Option B (recommended) — Use payerOrganization.referenceNumber: set your ERP's exact customer ID or code as the referenceNumber on the customer's Organization record in Tai. Set it when you create the customer via the Customer inbound flow or via a follow-up PUT /Customer/v2/Customers on any existing customer. Once set, the value round-trips inline on every invoice payload — no mapping table needed.
Revisions: an invoice can be reissued (isRevision: true). Treat these as updates in your system, not new invoices — same invoiceId, new totals.
Zero-dollar invoices: valid in Tai (e.g. a corrected-to-zero credit). Don't reject them; some target systems require explicit handling.
Line-item GL accounts: each lineItems[].account carries the GL account Tai wants the line posted to (e.g. Linehaul Income, Sales Revenue). Use this to drive GL posting on your side, or override with your ERP's chart of accounts if your rules differ.

Close the loop

After you've attempted the push to your target system — success or failure — you must call sync status back to Tai. Skip this and Tai will re-serve the invoice on every batch pull, forever.

PUT  /PublicApi/Accounting/v2/Invoices/Sync

View in API Reference →

Full details, enum values, and retry semantics: Sync Status Updates.

When something goes wrong

Post the error text on the shipment so a Tai user can act on it inside the shipment view — no waiting on Slack, no ticket, no email chain. See Shipment Activity Logs for the payload shape and error-writing conventions.