Navix Public API (v1-v2)

This walkthrough takes you from your first API call to reading a finished audit. It uses the curl command line tool, but any HTTP client works.

The flow is the one most integrations are built around:

1. Your system pushes an order to Navix.
2. Navix receives the vendor's invoice and audits it against the order.
3. Your system learns the invoice has been approved, and pulls the result.

If a term here is unfamiliar (tenant, vendor, approved, and so on), see the Glossary.

Your Navix customer success manager will give you:

• A tenant UUID. If you're building your own integration, you'll normally get two: one for your sandbox tenant and one for production. Use the sandbox tenant until your integration works.
• An API key.
• A user account for the Navix UI, which is handy for seeing what your API calls did.

All requests go to https://api.navix.io. The examples below read your credentials from environment variables:

export NAVIX_API_KEY="<your API key>"
export NAVIX_TENANT_UUID="<your sandbox tenant UUID>"

See Authentication for details on how credentials are sent.

Navix needs to know about an order before it can audit an invoice for it. Use the Create an order endpoint. This example includes only the required fields; the endpoint reference lists many more (stops, items, reference numbers, and so on).

curl -X POST https://api.navix.io/v2/orders \
  -H "X-Api-Key: $NAVIX_API_KEY" \
  -H "X-Tenant-Uuid: $NAVIX_TENANT_UUID" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "ORD-1001",
    "shipDate": "2026-10-20",
    "customer": {
      "externalId": "CUST-001",
      "name": "Example Shipper",
      "billingTerms": "Net30"
    },
    "vendors": [
      {
        "externalId": "CARRIER-001",
        "name": "Example Freight",
        "charges": [
          { "code": { "description": "Linehaul", "value": "LHL" }, "charge": 1250.00 }
        ]
      }
    ]
  }'

A successful call returns 202 Accepted with the order's external ID:

{ "externalId": "ORD-1001" }

202 means Navix has accepted the order and will import it shortly, not that it's visible yet. See Asynchronous Endpoints. If anything in the request is invalid you'll get a 400 that explains what to fix; see Errors and Conventions.

Because the externalId identifies the order (it defaults to orderNumber if you don't send one), sending the same order again updates it rather than creating a duplicate.

In most integrations your vendors send invoices to Navix directly, by EDI 210 or by email, so there's nothing for your system to call. When you're testing in the sandbox, ask your Navix contact to help you send a test invoice for the order you just pushed.

Navix then matches the invoice to the order and audits it. An auditor reviews it, or Navix approves it automatically. In the normal case the invoice ends up approved for payment. (An invoice can instead be terminated, which means it was rejected, for example as a duplicate. Most integrations don't need to track those.)

There are two ways to learn that an invoice has been approved. Pick whichever suits your system; many integrations use a webhook and also poll occasionally as a safety net.

Poll for approved invoices. List finalized invoices returns the invoices approved after StartTime, which is required and must be UTC. (Despite its name, this endpoint returns only approved invoices, not terminated ones.)

curl "https://api.navix.io/integration/v1/api/tenants/$NAVIX_TENANT_UUID/composite-vendor-invoices/finalized?StartTime=2026-10-20T00:00:00Z" \
  -H "X-Api-Key: $NAVIX_API_KEY"

{
  "currentPage": 0,
  "totalPages": 1,
  "pageSize": 20,
  "totalRecords": 1,
  "records": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "status": "Approved",
      "finalizationDate": "2026-10-21T14:03:22Z",
      "source": "Email"
    }
  ]
}

(The values above are illustrative.) Notice that the endpoint is under /integration/v1. That doesn't make it deprecated; it's the current way to poll for finalized invoices. See API Versions.

Or receive a webhook. Navix can call your system when an invoice is approved (INVOICE_APPROVED). See Webhooks. Webhooks must be enabled for your tenant by your Navix contact.

With an invoice UUID from step 3, call Get audit result:

curl "https://api.navix.io/integration/v2/api/tenants/$NAVIX_TENANT_UUID/composite-vendor-invoices/<invoice uuid>/result" \
  -H "X-Api-Key: $NAVIX_API_KEY"

The response contains the outcome of the audit, including the orders the invoice was matched to and the documents attached to them. A 404 means the invoice is still being audited, so try again later.

• Integration Guides walk through the common flows in more detail, including downloading supporting documents and pre-billing. Start with Common Flows.
• Webhooks lists every event Navix can send you.
• Errors and Conventions covers error handling, retries, idempotency and pagination.
• The API Reference sections document every endpoint in full.

Every request to the Navix API must be authenticated with your API key. Most requests must also say which tenant you're acting for.

Send your API key in the X-Api-Key header on every request:

X-Api-Key: <your API key>

Your Navix customer success manager issues your API key. Treat it like a password: keep it out of source control and client-side code, and contact Navix if you think it has been exposed.

How you identify your tenant depends on the endpoint:

• Most /v2/... endpoints require an X-Tenant-Uuid header containing your tenant UUID.
• /integration/v1/... and /integration/v2/... endpoints take your tenant UUID in the URL, as the tenantUuid path parameter. They don't use the X-Tenant-Uuid header.

The reference documentation for each endpoint shows exactly which it expects. Header names are case-insensitive.

You'll normally have two tenants, each with its own UUID: a sandbox tenant for development and testing, and a production tenant. Both use the same base URL, https://api.navix.io; the tenant UUID you send determines which one you're talking to.

• 401 Unauthorized: the API key or tenant is missing or wasn't recognized.
• 403 Forbidden: the credentials were recognized, but they aren't allowed to use that tenant or endpoint. A common cause is an X-Tenant-Uuid that doesn't belong to your API key.

See Errors and Conventions for the rest of the status codes.

These terms have specific meanings in Navix. Each is listed with synonyms commonly used in the industry.

• Tenant: You, a Navix customer; likely a broker or 3PL. You may have both a sandbox and a production tenant.
• Order: Load, shipment, movement.
• Invoice: Vendor bill, carrier invoice, AP invoice, vendor invoice.
• Vendor: Carrier, warehouse, anyone that you pay.
• Customer: Shipper, freight forwarder, anyone that pays you.
• Document: Anything sent from your vendor; could be an invoice, bill of lading, delivery receipt, packing slip, and so on.
• TMS: Transportation Management System. The guides use "TMS" for whatever system integrates with Navix, which could be a TMS or any other consumer of the API.

• Approved Invoice: An invoice that has been audited and approved for payment. These are the invoices your TMS usually needs back from Navix.
• Terminated Invoice: An invoice that has been rejected for payment, for example because it was a duplicate or was invalid in some way. Most integrations don't need these.
• Finalized Invoice: An invoice that has been audited and is either "approved" or "terminated". It's the general term for an invoice whose audit is over.

A note on "finalized": despite its name, the List finalized invoices endpoint returns only approved invoices. Terminated invoices aren't included, and you don't need to filter them out.

Navix can also approve an order or a document before an invoice has been received or audited. This is used for pre-billing: an approved order or approved document tells your TMS it can bill the customer. See the pre-billing guides.

• A UUID is an identifier assigned by Navix.
• An external ID is the identifier your own system uses for the same thing (for example, your TMS's order number). Orders, vendors and customers are matched using the external IDs you send.

The Navix API has one current version (v2), a set of legacy v1 endpoints that remain supported, and a small number of provisional endpoints. In the sidebar these are the API Reference (v2), Legacy API (v1) and Provisional Endpoints sections.

All new development happens on v2, and v2 is what you should build against. It supports multiple vendors and multiple invoices on a single order, and we're committed to its stability: we support these endpoints and won't make breaking changes to them.

v1 is the original version of our API. We plan to keep supporting it without breaking changes. Be aware that "v1" doesn't automatically mean "deprecated":

• Deprecated v1 endpoints have a v2 replacement and are marked deprecated in the reference. Today these are "Create a new order" (use Create an order) and the v1 "Get audit result" (use the v2 version).
• Current v1 endpoints have no v2 equivalent yet, so v1 is still the right choice. For example, List finalized invoices, Download invoice document and Terminate an invoice are used throughout the guides.

If a non-provisional endpoint isn't marked deprecated, it's safe to build on.

We want customers to have access to the latest features we're building. Provisional endpoints give you a glimpse of those features, but they aren't generally available.

⚠️ Provisional Endpoints Support

Do not use provisional endpoints unless you've been explicitly authorized to use them by your Navix account team. Outside of authorized, tenant-specific use cases, we will not provide support for these endpoints, and their use could have unintended side effects.

Changes to stable endpoints are limited to ones that well-behaved clients can absorb:

• Additive changes aren't breaking. For instance, adding a new property to a response isn't considered breaking, since API consumers should ignore unknown properties.
• Don't send undocumented data. Although we ignore unrecognized fields, sending an unsupported property could cause a conflict if we later add a property with that name.
• New enum values may be added over time. For instance, we regularly add support for new document types, so don't treat an unfamiliar value as an error.

Some Navix endpoints operate asynchronously and aren't instantaneous. There are a number of reasons for this. Usually, these operations are placed in a queue, which provides greater resiliency. Sometimes there's a multiple-step workflow that takes a bit of time to run. Either way, the endpoint validates your request and quickly returns a response telling you whether there were any errors.

Following RESTful best practices, asynchronous endpoints return 202 Accepted rather than 200 OK.

For example, when you create an order with POST /v2/orders, several validations are run:

• If any of them fail, a 400 Bad Request is returned with detail on which validations failed.
• If the data is valid, a 202 Accepted is returned. This means the order has been durably stored and will be imported; you can assume it will be ingested successfully.

• The result may not immediately appear in other API requests or in the Navix UI. Usually these operations complete within seconds. Occasionally, such as during usage spikes, they take longer, and some (like creating an invoice) can take several minutes.
• Don't assume the work is finished. Don't, for instance, request an order's invoices the instant you've pushed it. If you need to know when something is ready, use a webhook or poll.
• Results that depend on an audit aren't available until the audit finishes. For example, Get audit result returns 404 for an invoice that's still being audited.

This page collects behavior that applies across the whole API: how errors look, how to retry safely, how paging works, and how times are handled.

Navix uses standard HTTP status codes. The ones you'll see most often:

A 400 for a validation failure includes a JSON body that identifies each problem and the field it applies to:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "5eee0c1a-1656-462a-ab6c-a3ee502fbd4f",
  "errors": {
    "InvoiceNumber": [
      "The InvoiceNumber field must be less than or equal to 64 characters long."
    ]
  }
}

Not every error response has a JSON body. Some, such as certain 401 and 403 responses, return a short plain-text message instead, so check the status code before trying to parse the body.

If you contact Navix support about a failed request, include the traceId when the response has one, along with the time of the request.

Retrying failed requests

• Don't retry 400, 401, 403 or 404 responses without changing something. The same request will fail the same way.
• Do retry 500 and 503 responses, and requests that time out or fail to connect, using exponential backoff (for example, waiting 1, 2, 4, then 8 seconds) and a cap on the number of attempts.
• When you retry a request that creates or changes data, send an idempotency key so the retry can't be processed twice.

The endpoints that accept data from you (Create an order, Create invoice and Ingest documents) accept an optional X-Idempotency-Key header. It lets you retry a request safely, for example after a timeout, without risking the same operation happening twice.

• Generate a unique value (a UUID works well) for each logical request, and send the same value when you retry that request.
• Send the header only once per request.
• If you don't send one, Navix derives one from your tenant and the request body.

Creating or updating an order is also naturally repeatable: an order is identified by its externalId, so sending the same order again updates it.

Endpoints that can return a lot of records are paged. Currently these are List finalized invoices, Get List of Approved Documents and Get List of Approved Orders. Other list endpoints, such as the list of disputes on an invoice, return the complete list.

• You choose the page with PageNumber and the page size with PageSize. Page numbers start at 0. (For the two POST endpoints these are pageNumber and pageSize in the request body; for List finalized invoices they're query parameters.)
• For List finalized invoices the default page size is 20 and the maximum is 100.
• The List finalized invoices response includes currentPage, totalPages, pageSize, totalRecords and records. Keep requesting pages until you've reached totalPages; a single page may not contain everything.

• Timestamps are in UTC, in ISO 8601 format (for example, 2026-10-21T14:03:22Z). Time ranges you send, such as StartTime and EndTime, are interpreted as UTC.
• Some fields are date only, such as an order's shipDate (for example, 2026-10-20). The endpoint reference says which fields are which.
• For List finalized invoices, the range excludes StartTime and includes EndTime. The range applies to the time the invoice was finalized (approved): an invoice at exactly StartTime isn't returned, and one at exactly EndTime is. EndTime defaults to the present time.

Polling windows

When you poll with a time range, it's your system's responsibility to remember when it last polled, and to set StartTime (and EndTime) accordingly. If you miss a scheduled run, the next poll should simply use an earlier StartTime.

Plan for a small amount of clock drift: your server's clock might differ slightly from Navix's. If your job runs at 6:00:00 UTC, it's sensible to use an EndTime of 5:59:00 UTC, and to start your next window at that same moment.

The primary consumers of this API are tenant's TMS integrations (or the TMS itself). Throughout these guides, we refer to "TMS" (Transportation Management System) -- but this could be any consumer of the Navix API.

Navix's API is flexible, and there are multiple ways a TMS can integrate with it. These guides focus on the most common scenarios.

A simple TMS integration has two integration points with Navix:

• TMS pushes orders to Navix.
• TMS pulls completed audits from Navix.

A more complex integration may have several integration points with Navix:

• TMS pushes orders to Navix.
• TMS pushes invoices to Navix.
• TMS pushes supporting documents to Navix.
• Navix calls the TMS rating engine.
• TMS pulls completed audits from Navix.
• TMS pulls supporting documents from Navix.
• TMS pulls dispute data and communications from Navix.

It's worth noting that there may be data (usually invoices and supporting documents) that are being sent to Navix without going through the TMS. For instance, vendors (carriers) may be sending EDI 210 documents directly to Navix. Vendors may also be sending invoices and supporting documents via email.

Each of these guides covers one integration point in detail:

• TMS Pushes Orders to Navix
• TMS Pulls Completed Audits from Navix
• TMS Pulls Supporting Documents from Navix
• TMS Pulls Pre-Bill Approved Orders from Navix
• TMS Pulls Approved Documents from Navix

Navix can also call your system's rating engine during an audit. Other integration points, such as pushing invoices and documents or pulling disputes, are documented in the API Reference.

In order to audit an invoice in Navix, Navix needs to know what order the invoice is for.

Use the "Create an order" (V2) endpoint to push an order to Navix.

We recommend:

• The TMS should push order data to Navix regularly.
• This could happen on a scheduled basis (perhaps every 15 minutes or every hour).
• It can also happen in real-time (whenever a load/order is changed in the TMS).
• Only orders that have been changed should be pushed to Navix.
• Push orders to Navix after they have been tendered to a carrier, before the point in time when Navix may start receiving invoices.
• You can push an order to Navix multiple times. Navix will perform an upsert based on the externalId. That is, if you push an order to Navix, if there's an existing order with the same externalId, it will be updated instead of inserted.
• Send an externalId that correlates to the unique identifier for the order in the TMS. If you don't send one, it defaults to the orderNumber.

We recommend against:

• Sending all open orders on a scheduled basis. (For instance, sending all tendered orders every hour, regardless of whether or not anything has been changed on the order.)
• Storing or relying on order UUIDs. An order UUID refers to a specific version of the order data; subsequent updates/upserts will result in new order UUIDs.
• Assuming the order will be ingested immediately. Order ingestion generally occurs in near real-time. However, due to the resilient and distributed nature of our system, ingestion can occasionally take longer.

When an invoice has been audited and approved (either by a user or automatically by Navix), the TMS needs to know the results of the audit.

An invoice can end its audit in one of two ways: it is approved for payment, or it is terminated (rejected for payment, for example because it was a duplicate or was invalid). Most TMS integrations only care about approved invoices, because those are the ones that need to be returned to the TMS, so that is what this guide covers. Both are called "finalized" invoices; see the Glossary.

There are two ways to find out about approved invoices:

• Polling: On a scheduled basis, the TMS polls the Navix API for any invoices that have been approved since the last polling.
• Webhook: Whenever an invoice is approved, Navix will call a webhook callback on an API hosted by the TMS.

Either way, the only data the TMS gets from either polling or a webhook is the UUID of an invoice that's been approved. The next step is to get the audit results.

If you do want to know about terminated invoices too, use the INVOICE_TERMINATED webhook. Polling doesn't return them.

Use the "List finalized invoices" endpoint to get a list of invoices approved during a given time period.

Despite the name, this endpoint returns only approved invoices. Terminated invoices are not included, so there's nothing to filter out.

Notes:

• The results are paged. More than one page of results may be returned; be sure to check to see if there are additional pages.
• It's the responsibility of the TMS to keep track of the last time polling was run, and to set the StartTime and EndTime accordingly. If the TMS misses a scheduled run, the next poll request should adjust the StartTime accordingly.
• Note that the StartTime and EndTime are UTC, and are the times stored by Navix. We recommend planning for a small amount of "clock drift" -- that is, the time on your server might vary slightly from the times on Navix servers. So if you're running this process at 6:00:00 UTC, it might make sense to specify an EndTime of 5:59:00 UTC.
• You can poll with whatever frequency you want. Most tenants find that polling every 10-15 minutes strikes a good balance between returning results quickly and avoiding an overly "chatty" integration.

Use the INVOICE_APPROVED webhook to receive a webhook callback whenever an invoice is approved.

Notes:

• Webhooks are triggered in real-time. So as soon as an invoice is approved, your callback URL will be immediately hit.
• It's the responsibility of the TMS to handle the volume or fail in a prescribed fashion. Invoices are often approved in bulk, so there could be dozens, hundreds, or even thousands of webhook callbacks triggered in a very short period of time. Review the section on webhook delivery guarantees for more details on how Navix will retry webhooks.
• Depending on the reliability of the TMS, it may be beneficial to supplement webhooks with occasional polling. That is, if there's a chance that the callback may fail or the TMS may miss some webhooks, the polling endpoint can be used to verify if any webhooks failed.

Once you've received the UUID of an approved invoice, either by polling or webhook, use the "Get audit result" endpoint to get the results of an audit.

Notes:

• Make sure to use the latest (v2) version of the "Get audit result" endpoint.
• If you're pulling approved documents for pre-billing (in addition to getting audit results), you may end up with duplicate documents. That is, the documents you receive from the "Get List of Approved Documents" endpoint or the DOCUMENT_APPROVED webhook will also appear in the "Get audit result" endpoint. However, you can specify includeApprovedDocuments=false in the call to the "Get audit result" endpoint to filter out approved documents from the list of documents that appears in orders[n].documents.

After the TMS has pulled audit results for an invoice, it can retrieve the supporting documents for the invoice. Use the "Download invoice document" endpoint to download the raw file.

Notes:

• The endpoint requires an invoice UUID and a document UUID. Document UUIDs are returned in the "Get audit result" endpoint, under orders.documents.uuid.
• Additional information about the document is available from the "Get audit result" endpoint, such as the type of document ("Invoice", "Bill of Lading", etc.).
• The endpoint returns the raw binary file.
• Currently, all returned files will be in PDF format. However, this may change in the future, and API consumers should not assume that the returned files will always be PDFs.

Pre-billing sends "approved" orders to the TMS before receiving or completing the audit of an invoice. This indicates that the TMS can generate a customer invoice for the order. Usually, the approval occurs when a proof of delivery is received and approved by an auditor.

There are two ways to implement this:

• Polling: On a scheduled basis, the TMS polls the Navix API for any approved orders.
• Webhook: Whenever an order is approved, Navix will call a webhook callback on an API hosted by the TMS.

Either way, the only data the TMS gets from either polling or a webhook is the external ID of the order.

To get a list of approved orders, call the Get List of Approved Orders endpoint. This endpoint lets you pass in a time range, and returns the external IDs of all orders approved during that period. Note that this endpoint is currently provisional; see API Versions.

Use the ORDER_APPROVED webhook to receive a webhook callback whenever an order is approved.

Once an order has been approved (and the TMS learns about it from either polling or a webhook callback), it can retrieve additional information about the documents on the order:

• You can retrieve a list of all the documents on the order with the Get Document Uuids endpoint. This returns a list of document UUIDs.
• Alternatively, you can retrieve a list of documents with additional metadata, such as document type, by calling the Get Document Metadata endpoint.
• You can download the binary file of a document using the Get One Attachment endpoint. Currently, all returned files are in PDF format. However, this may change in the future, so API consumers should not assume that all returned files will always be PDFs.

When a document is approved, it indicates that the TMS can send the document to the customer/shipper. This can occur before the invoice is received or audited.

There are two ways to implement this:

• Polling: On a scheduled basis, the TMS polls the Navix API for any approved documents.
• Webhook: Whenever a document is approved, Navix will call a webhook callback on an API hosted by the TMS.

Either way, the only data the TMS gets from either polling or a webhook is the external ID of the order and the document UUID.

To get a list of approved documents, call the Get List of Approved Documents endpoint. This endpoint lets you pass in a time range, and returns the external order ID and document UUID of all documents approved during that period.

Use the DOCUMENT_APPROVED webhook to receive a webhook callback whenever a document is approved.

Once a document has been approved (and the TMS learns about it from either polling or a webhook callback), you can get the binary file with the Get One Attachment endpoint. Currently, all returned files are in PDF format. However, this may change in the future, so API consumers should not assume that all returned files will always be PDFs.

Notes:

• An approved document will also match to an invoice once the invoice for the order has been received. This means approved documents will also be returned in the "Get audit result" endpoint. To filter approved documents out from that endpoint, include the includeApprovedDocuments=false parameter when calling "Get audit result".

A webhook is a callback mechanism that causes Navix to make an API request to a consumer system when events occur within Navix.

Our webhooks are "thin". That is, they're lightweight and usually contain IDs that can be used to retrieve additional data via API.

All webhooks have the same payload structure as this example:

{
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "DISPUTE_CREATED",
    "time": "2025-01-01T12:00:00.000000",
    "data": "{ \"invoiceUuid\": \"<uuid>\" }"
}

• id is a unique identifier for the event. Note that this is not the identifier for the object (invoice, dispute, etc.) which triggered the event.
• type is the specific type of event that triggered the webhook. Possible values include:
  • INVOICE_CREATED
  • INVOICE_APPROVED
  • INVOICE_TERMINATED
  • INVOICE_MATCHED
  • INVOICE_UNMATCHED
  • INVOICE_EXCEPTIONS_UPDATED
  • DISPUTE_CREATED
  • DISPUTE_UPDATED
  • DISPUTE_COMMUNICATION_CREATED
  • ORDER_APPROVED
  • DOCUMENT_APPROVED
• time is the UTC time of when the event occurred.
• data contains a JSON object with details for the event. The specific data varies depending on the type of event that occurred. Note that the JSON has been escaped.

The webhook consumer should return a status code between 200 and 299 (inclusive) within about 20 seconds. Later retry attempts allow up to 60 seconds.

If the consumer is unreachable, doesn't respond promptly, or returns a status code less than 200 or greater than 299, we will consider the delivery attempt failed and will make another attempt.

We use an exponential backoff algorithm to determine the time between delivery attempts, starting at a few seconds and increasing to a maximum of 1 hour. We will continue to attempt delivery for 8 hours beyond the initial attempt, after which the message will be discarded.

Webhook requests are sent with a User-Agent of Navix/1.0.

We aim for at-least-once delivery, so a single event may hit the webhook receiver multiple times. When that occurs, the id will be the same across the multiple requests, so it can be used as an idempotency key by consumers.

We cannot guarantee that webhooks will arrive in order. That is, if a dispute is updated twice, the webhook for the second update could arrive before the first. If that's likely to cause issues, we recommend recording the time field on the webhook and comparing that stored time to the time on any received webhook.

INVOICE_CREATED

This event is raised whenever an invoice is created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice which was created.

INVOICE_APPROVED

This event is raised whenever an invoice is approved. Note that this is only raised for approvals; terminated invoices raise INVOICE_TERMINATED instead.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice which was approved.

INVOICE_TERMINATED

This event is raised whenever an invoice is terminated, whether a user terminated it in Navix, it was terminated through the API, or Navix terminated it automatically (for example, when resolving a duplicate).

The Get invoice endpoint works for terminated invoices, so you can use it to retrieve the invoice number and reference numbers you originally sent us and correlate the invoice back to your own system.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice which was terminated.

INVOICE_MATCHED

This event is raised whenever an invoice is matched to an order. It is raised in both directions: when an invoice arrives and matches an existing order, and when an order arrives and matches an existing invoice.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "orderExternalId": "ORD_123"
}

• invoiceUuid is the identifier for the matched invoice.
• orderExternalId is the order Id as stored in the tenant system outside of Navix. If the order has no external Id, this defaults to the order number.

INVOICE_UNMATCHED

This event is raised whenever an invoice is unmatched from an order — either because it was fully unmatched, or because it was re-matched to a different order (in which case a corresponding INVOICE_MATCHED for the new order follows). Re-matching an invoice to the same order it was already matched to does not raise this event.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "orderExternalId": "ORD_123"
}

• invoiceUuid is the identifier for the unmatched invoice.
• orderExternalId is the order Id as stored in the tenant system outside of Navix. If the order has no external Id, this defaults to the order number.

INVOICE_EXCEPTIONS_UPDATED

This event is raised whenever the exceptions or work instructions on an invoice change.

The event carries only the invoice identifier. Use the Get invoice exceptions endpoint to retrieve the exceptions and work instructions currently open on the invoice. Only open items are returned, so an exception you received previously and no longer see in the response has been resolved.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice whose exceptions may have changed.

DISPUTE_CREATED

This event is raised whenever a new dispute is created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice on which the dispute was created.
• disputeUuid is the identifier for the newly created dispute.

DISPUTE_UPDATED

This event is raised whenever a dispute is updated. Note that creating and updating are separate events, so this event isn't raised when the dispute is initially created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice associated with the dispute that was updated.
• disputeUuid is the identifier for the updated dispute.

DISPUTE_COMMUNICATION_CREATED

This event is raised whenever a new communication is created on a dispute.

Communications are immutable, so there's no corresponding webhook for updates to a communication.

Note that whenever a dispute is created, an initial communication is usually created at the same time. It's possible the DISPUTE_COMMUNICATION_CREATED webhook will arrive before the DISPUTE_CREATED webhook.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000",
  "communicationUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice associated with the dispute.
• disputeUuid is the identifier for the dispute.
• communicationUuid is the identifier for the created communication.

ORDER_APPROVED

This event is raised whenever an order is approved.

data object

{
  "orderExternalId": "ORD_123"
}

• orderExternalId is the order Id as stored in the tenant system outside of Navix.

DOCUMENT_APPROVED

This event is raised whenever a document is approved.

data object

{
  "orderExternalId": "ORD_123",
  "documentUuid": "00000000-0000-0000-0000-000000000000"
}

• documentUuid is the identifier for the document as stored in Navix.
• orderExternalId is the order Id as stored in the tenant system outside of Navix.

Navix provides the ability to call out to an endpoint in your system that can utilize your rating engine. Our system will allow an auditor to send an updated invoice from our system to your rating engine endpoint to get rated.

This is a webhook in the Navix system but it does not have the same guarantees as the other webhooks. (This is because rating engine calls run synchronously, while other webhooks are asynchronous.)

We will call your rating engine endpoint, and each attempt times out after 60 seconds. If the call fails because of a network error or timeout, or your endpoint returns 408, 500, 502, 503 or 504, we will retry once. Any other non-2xx response, including 400 and 422, is not retried.

In other words, calls to your rating engine webhook are managed in a different manner than other tenant provided webhooks. The mechanism, manner and guarantees of this webhook are different from the Webhooks tab mentioned earlier in the documentation.

It is important that performance is taken into account inside of rating engines. An auditor in the UI can call the rating engine with the press of a button. If a rating engine takes 15 seconds to complete, each audit will take an additional 15 seconds to complete with each rating engine call.

Getting started is straight forward. Our team and your team have a few tasks that need to be accomplished so you use this feature.

Implementation Responsibilities

Our system will make a call out to an endpoint url that you specify. That endpoint will need to handle the payload that we send, rate the payload and then return a response. You can view request payload and response structure in the Rating Engine Payload and Rating Engine Response sections below respectively. We do into more detail in the Endpoint Contract section

Here are the tasks for your team:

1. Create an endpoint that satisfies the information found in the Endpoint Contract section
2. Provide the url to that endpoint to the Navix team
3. Contact your account manager so our team can generate a unique api key for you. This api key is the one all our requests will use so you can be sure that the requests are coming from our system. How it is used is covered in the Endpoint Contract section.

Here are the tasks for the Navix team:

1. Provide you with a unique api key so you can be sure the requests are coming from us.
2. Add your endpoint url to our system so we can contact you.
3. Support you.

In order for the Navix system to contact your rating engine we need an endpoint that meets the following requirements:

1. The endpoint must be able to handle a POST request.
2. The endpoint must handle an apikey query string argument. The apikey value is one that our team has generated for you. You can get this by contacting your account manager. Your endpoint should validate that the apikey value is the same that we provided you. If it is not, you should return a 401 Unauthorized status code.
3. The endpoint must handle the request payload. The request payload is an invoice from our system that needs to be rated. You can learn more about the payload and what each field means in the Rating Engine Payload section below.
4. The endpoint must map your system's raw rating response to the rating engine response that we are expecting. You can view that structure in the Rating Engine Response section below.
5. The endpoint must return a 2xx response along with the structure provided in the Rating Engine Response section below. Please note that we are expecting a single rating engine response from your endpoint. You might have a rating engine that rate shops multiple vendors, please trim down your response to only include the selected vendor response. If your rating engine throws an exception, it is beneficial to the auditor to return a 2xx response and populate the RawResponse field with the exception. These exceptions provides feedback to the auditors so they can make corrections or let them know that a system is temporarily down.

If the endpoint returns a 2xx response we mark that as a success. All other responses are treated as failures, and are retried only as described in Delivery Guarantees.

We can visualize the contract the following way:

Rating Engine Payload

Our payload is an invoice from our system. We have provided an example below to show the structure and a sample of data. An explanation of the fields is below the example.

{
  "Uuid": "e4c3b17a-d207-43f9-ba2d-f61d068c7808",
  "ExternalOrderId": "MyOrderId",
  "FreightChargeTerms": "Prepaid",
  "DeliveryDate": "2024-04-11T12:34:56Z",
  "ShipDate": "2024-04-01T08:00:00Z",
  "Vendor": {
    "ExternalId": "147-888",
    "SCAC": "SAIA"
  },
  "Customer": {
    "ExternalId": "6594HH4"
  },
  "Stops": [
    {
      "Type": "Origin",
      "City": "Beverly Hills",
      "Zip": "90210",
      "CountryCode": "USA",
      "StateCode": "CA"
    },
    {
      "Type": "Destination",
      "City": "Dallas",
      "Zip": "75080",
      "CountryCode": "USA",
      "StateCode": "TX"
    }
  ],
  "LineItems": [
    {
      "Description": "Navix branded shoes",
      "HandlingUnit": "Pallet",
      "HandlingUnitCode": "PLT",
      "HandlingUnitCount": 4,
      "Weight": 231.10,
      "WeightUnit": "LBS",
      "Class": 100.00,
      "Height": 50.00,
      "Width": 40.00,
      "Length": 48.00,
      "Stackable": true
    }
  ],
  "VendorCharges": [
    {
      "Code": "ACH",
      "PostMapped": {
        "ChargeTypeUuid": "74473142-1439-48CD-ACA0-15507658CAE3",
        "ChargeType": "Limited Access Delivery"
      }
    }
  ],
  "OrderMetadata": {
    "AnyValue": {
      "ForInstanceATrackingNumber": "123-789",
      "OrAnything": "2026-06-01"
    },
    "SomeOtherValue": {
      "sample1": "value1"
    }
  }
}

• Uuid is a unique identifier for the invoice in the Navix system.
• ExternalOrderId is the order id in your system that this invoice is for.
• FreightChargeTerms is how the freight is paid. Possible values include: Collect, Prepaid, Prepaid & Add and Third Party
• DeliveryDate is the UTC datetime of when the shipment was delivered.
• ShipDate is the UTC datetime of when the shipment was shipped.
• Vendor
  • ExternalId is the id in your system that this vendor is known as.
  • SCAC is the SCAC code for this vendor.
• Customer
  • ExternalId is the id in your system that this customer is known as.
• Stops
  • Stops.Type is what type of stop this is. Possible values include: Origin, Destination and BillTo.
  • Stops.City is city for this stop.
  • Stops.Zip is the zip code for this stop.
  • Stops.CountryCode is the country code for this stop. Possible values include: USA, CAN and MEX.
  • Stops.StateCode is the state code for this stop.
• LineItems
  • LineItems.Description is the description for this line item.
  • LineItems.HandlingUnit is the container for this line item. Possible values include: Pallet, Drum, Bag, Barrels, Crates, Bundles, Pieces, Loose, Boxes, Cases, Carton and Totes.
  • LineItems.HandlingUnitCode is the alias for the HandlingUnit above.
  • LineItems.HandlingUnitCount is how many containers are used for this line item
  • LineItems.Weight is the weight for this line item.
  • LineItems.WeightUnit is the weight unit used for this line item. Possible values include: LBS and KG
  • LineItems.Class is the shipping class.
  • LineItems.Height is the height for this line item.
  • LineItems.Width is the width for this line item.
  • LineItems.Length is the length for this line item.
  • LineItems.Stackable indicates whether line item is stackable.
• VendorCharges
  • Code the charge code in your system for this charge.
  • PostMapped is the Navix charge type this charge is currently classified as. Because Code can vary by carrier and is not guaranteed to be one of your codes, PostMapped is the reliable way to identify what a charge is.
    • PostMapped.ChargeTypeUuid is the unique identifier of the Navix charge type.
    • PostMapped.ChargeType is the description of the Navix charge type.
• OrderMetadata is a set of metadata associated with the order this invoice was matched to. It is an object whose keys are metadata group names and whose values are objects of string key/value pairs. This is only present when the invoice is matched to an order; it will be null or omitted for orderless invoices.

Rating Engine Response

Once the invoice has been rated, we need the results mapped in a format our system can understand. Please note that we are expecting a single rating engine response from your endpoint. You might have a rating engine that rate shops multiple vendors, please trim down your response to only include the selected vendor response.

We have provided an example below to show the structure and a sample of data. An explanation of the fields is below the example.

{
  "RawResponse": "...",
  "RawResponseType": "JSON",
  "VendorCharges": [
    {
      "Code": "ACH",
      "Description": "LIMITED ACCESS DELIVERY",
      "PostMapped": {
        "ChargeTypeUuid": "74473142-1439-48CD-ACA0-15507658CAE3",
        "ChargeType": "Limited Access Delivery"
      },
      "Amount": 83.2500,
      "Rate": 55.5000,
      "Quantity": 1.5000,
      "Qualifier": "PerMile"
    },
    {
      "Code": "NFY",
      "Description": "NOTIFICATION FEE",
      "Amount": 106.52
    }
  ],
  "CustomerCharges": [
    {
      "Code": "ACH",
      "Description": "LIMITED ACCESS DELIVERY",
      "Amount": 59.35
    }
  ] 
}

• RawResponse is a raw response from your rating engine. This can be the response when a rate was returned or in the case where there was an exception from the rating engine. Providing this can be beneficial to auditors. Auditors will have the visibility to see this response in the UI.
• RawResponseType is format of the RawResponse field. Possible values are JSON, XML and TEXT.
• VendorCharges
  • Code the charge code in your system for this charge.
  • Description is a description of the charge.
  • PostMapped (optional) lets you return a charge already mapped to a Navix charge type, in addition to the Code/Description. When provided, we use it to identify the charge: PostMapped.ChargeTypeUuid is matched first, then PostMapped.ChargeType (description) as a fallback, before falling back to Code/Description. See How We Identify Returned Charges below.
    • PostMapped.ChargeTypeUuid is the unique identifier of the Navix charge type.
    • PostMapped.ChargeType is the description of the Navix charge type.
  • Amount is the amount for this charge.
  • Rate represents the price per unit as defined by Qualifier.
  • Quantity is the number of units that the Rate applies to, aligned to the Qualifier’s unit.
  • Qualifier indicates the unit type for Rate and Quantity calculations. Supported values: PerPound, PerHundredweight, PerTon, PerMile, PerKilometer, PerHour, PerCase, PerPallet, PerUnit, Percent.
• CustomerCharges does not accept PostMapped. Customer charges are always identified by Code and Description (see How We Identify Returned Charges below).
  • Code is the same as VendorCharges.Code above.
  • Description is the same as VendorCharges.Description above.
  • Amount is the same as VendorCharges.Amount above but relevant to a customer.
  • Rate is the same as VendorCharges.Rate above.
  • Quantity is the same as VendorCharges.Quantity above.
  • Qualifier is the same as VendorCharges.Qualifier above.

How We Identify Returned Charges

Each charge you return is assigned to a Navix charge type. That charge type determines which line of the charges grid the amount is shown on and which invoice charge it is compared against.

Vendor charges with PostMapped

1. PostMapped.ChargeTypeUuid is matched against the Navix charge types.
2. If there is no match, PostMapped.ChargeType is used, but only when it matches exactly one Navix charge type description (case-insensitive).
3. If neither matches, we fall back to Code/Description as described below. No error is returned, so an incorrect ChargeTypeUuid is not reported back to you.

The simplest way to keep your rating aligned with the invoice is to copy the PostMapped we sent on a vendor charge in the Rating Engine Payload onto the vendor charge you return for it. This works regardless of the codes your rating engine uses internally.

Customer charges, and vendor charges without a usable PostMapped

Code and Description are matched against your tenant charge codes:

1. If only one of your tenant charge codes uses that Code, the charge is assigned to it and Description is not considered.
2. If more than one of your tenant charge codes uses that Code, Description must match one of them (case-insensitive).
3. Otherwise the charge is classified as Unknown. Unknown rated amounts are left out of the variance comparison and automated audit decisions for that line.

Only return codes that exist in your tenant charge codes. If a single code covers several kinds of charge, for example a generic accessorial code, add a tenant charge code for each Code + Description combination your rating engine returns. Once a code has more than one tenant charge code, any description without its own tenant charge code is classified as Unknown.

Important Rate Qualifier Validation Rules

If any of these validations fail, we'll display the validation message results to auditors through the button next to the Audit column in the charges grid within the Navix App, similar to how validation messages are currently shown when we receive a 400 Bad Request response.

• Rate qualifier properties (Rate, Quantity, Qualifier) must be used as a complete set - either all three must be provided together, or all three must be null/omitted
• When all three are provided, the system validates that Amount equals Rate × Quantity (with 4 decimal places precision)
• Qualifier values are strictly validated against our supported enumeration

Dispute reasons in Navix are organized into Dispute Reason Groups, configured per tenant. The Disputes API (GET /v2/invoices/{invoiceUuid}/disputes and GET /v2/invoices/{invoiceUuid}/disputes/{disputeUuid}) identifies the group each reason belongs to, so you can route or categorize disputes by group in your own systems.

Each entry in a dispute's reasons[] collection includes two group fields:

{
  "description": "Rate discrepancy",
  "createdAt": "2026-08-01T14:03:22Z",
  "resolvedAt": null,
  "disputeReasonGroupUuid": "3f2a9c1e-7b44-4a1d-9c5e-2f8d6b1a4e07",
  "disputeReasonGroupDescription": "Carrier Rates"
}

Behavior notes

Please read these before building routing or reporting logic on these fields:

• Both fields are always present, and always null together. You will never receive a group UUID without its description, or vice versa.
• Values reflect current configuration, not point-in-time history. Reason groups are reassignable in Navix. A dispute resolved months ago reports whatever group its reason belongs to today. Do not treat these fields as a historical record for reporting.
• null is an expected value, returned when the reason cannot be resolved to a group:
  • the reason was created via the API with free text that does not match your tenant's configured dispute reasons (dispute creation does not validate reasons against configuration);
  • the reason belongs to a dispute created before reason identifiers were persisted and its configured reason was since renamed or deleted (a fixed, shrinking population);
  • the configured reason is not assigned to any group.
• Availability is fail-soft. If group configuration is temporarily unavailable, the endpoints still return disputes successfully with these two fields as null.

Routing guidance

Route on disputeReasonGroupUuid rather than the description — the UUID is stable across group renames. Treat null as an "unrouted" or default bucket.