Shipment Activity Logs
The human-readable audit trail. Post sync outcomes — success confirmations, target-system errors, or unresolved problems — to a shipment so Tai users can see and act on them inline in the shipment view.
What this is for
The human-readable audit trail. Every sync outcome — success or failure, either direction — should also land as an activity log entry on the shipment. This is the message that shows up inline in Tai's shipment view, where operators, AR clerks, and AP folks actually spend their day. Without this, a failed sync is invisible until someone digs into the Accounting Sync History page — and by then, the customer's already called asking why their invoice hasn't arrived.
The rule: sync status handles the machine-readable state; the activity log handles the human-readable "why." Both together, every time.
When to write one
- On every successful sync — a short "synced to SAP as DOC-XXX" note lets a Tai user confirm at a glance that the record made it.
- On every failed sync — include the exact error text from the target system, and if possible a hint at what to fix. The Tai user reading it should be able to act without leaving the shipment.
- From the Activity Log fallback flows (AP inbound, AR inbound) — when your integration hits a problem no API call can resolve (vendor missing, ambiguous match, needs manager approval), post the situation as an activity log to get a Tai user's attention.
Endpoint
POST /PublicApi/Shipping/v2/ShipmentActivityLogsRequest payload
{
"shipmentId": 131382699,
"type": "Receivable",
"privacy": "Private",
"description": "Invoice 121396145 synced to SAP — TransactionId SAP-INV-9900341882"
}Response (200) — returns the created log record with its Tai-assigned ID:
{
"shipmentActivityLogId": 1073937516,
"shipmentId": 131382699,
"type": "Receivable",
"privacy": "Private",
"description": "Invoice 121396145 synced to SAP — TransactionId SAP-INV-9900341882"
}Fields
| Field | Values | Notes |
|---|---|---|
shipmentId | int | The shipment the log entry attaches to. |
type | enum | All, Receivable, Payable, Pricing, Operations, General, StatusChange, Audit, Claims, Email, TextMessage, ExternalCommunications. Use Receivable for invoice/AR events, Payable for bill/AP events, Pricing when you're logging a ShipmentCharges/CarrierCharges update, General when nothing else fits. |
privacy | Public, Private | Private hides the entry from customer-portal users — the default for internal accounting activity. Use Public only when the message is something the customer should see. |
description | string, required | The human-readable message. On success, include the target-system transactionId. On failure, include the exact error text and a hint at what to fix. |
Writing good descriptions
Bad description (unactionable):
Invoice sync failed.
Better (specific but incomplete):
Invoice 121396145 sync failed — SAP validation error.
Best (specific + actionable):
Invoice 121396145 REJECTED by SAP: Bill-To address line 1 is required. Customer 660295 has no billing address on file — please add one and move the invoice back to Pending in Accounting Sync History to retry.
The Tai user reading the third version can act right now. The first two send them digging.
Example: success confirmation
{
"shipmentId": 131382699,
"type": "Payable",
"privacy": "Private",
"description": "Bill B-2026-091043 synced to SAP as PAY-DOC-4400218994."
}Example: failure with actionable error
{
"shipmentId": 131382699,
"type": "Receivable",
"privacy": "Private",
"description": "Invoice 121396145 REJECTED by SAP: Bill-To address line 1 is required. Customer 660295 has no billing address on file — please add one and move the invoice back to Pending in Accounting Sync History to retry."
}Example: activity-log-only fallback (no sync call)
Used when your integration can't proceed and needs a Tai user to act before you can try again. No sync status changes — the record stays where it is until the user resolves the underlying issue.
{
"shipmentId": 131382699,
"type": "Payable",
"privacy": "Private",
"description": "Cannot approve bill for shipment 131382699 — vendor 'Estes Express Lines' not found in target ERP's vendor master. Please add the vendor in [ERP name] and notify integration to retry."
}Convention: pair every sync with a log
Pair every Sync Status Update with a matching activity log on the same shipment. Sync tells Tai's batch queue what happened; the log tells the Tai user what happened. Tai users will look at the activity log first when a sync fails, so make the description specific and actionable.
Updated 23 days ago