# About Pay Periods
Source: https://docs.alvys.com/en/help/accounting-settlements/about-pay-periods

How to manage pay periods for driver settlements.

#### Getting Started

Navigate to settings and select pay periods. This is where you'll create a schedule to pay your company drivers and owner operators.

<img alt="Screenshot" />

\*\*These pay periods will show in driver settlements \*\*allowing you to create more organized statements for drivers and which allow our system to better understand *"time worked"* for time-based pay.

#### Pay Period Setup

<img alt="Screenshot" />

* How often do you pay your drivers?
* Does this apply to all or a specific group?

Using the form, build a schedule that works best for you! We have found it's most common to select "all" drivers and pay them "weekly", but you may split this out by driver type, subsidiary or even have a custom list.

#### Managing a Pay Period

<img alt="Screenshot" />

You can edit a pay period by selecting and clicking edit on the table row.

* **I need to add or remove drivers:** Edit the pay period and select the correct driver type or use "custom" to build a list. *PLEASE NOTE: Removing a driver means you will need to add them to a different pay period to run payroll.*

* \*\*I need to change the dates for a pay period: \*\*Simply update the pay frequency to a different recurring schedule or move the "day of the week" to match the day you'd like to start pay period every cycle.

### Using pay periods while running payroll

Pay periods are a consistent way to organize driver statements and a common accounting practice. You'll find pay periods will apply once you start to build a draft statement.

1. In the open tab select transactions you'd like to build a statement with.
2. Select the pay period they belong on.
3. Click approve to move them to a draft statement (on the drafts tab).
4. Click the drafts tab to view statements ready to be generated.

<img alt="Screenshot" />


# Batch Invoicing
Source: https://docs.alvys.com/en/help/accounting-settlements/batch-invoicing

Move loads through the five invoice statuses in the Alvys batch invoicing queue, release loads to billing in bulk, and track billing progress.

<Note>
  Batch Invoicing is the central invoicing queue in Alvys where loads move through five statuses from Incomplete to Invoiced; use it to track, manage, and release multiple loads for billing in one action.
</Note>

Batch Invoicing is the main invoicing workflow in Alvys. It shows all loads across five invoice statuses and lets you move multiple loads to Released in one action.

## Overview

Batch Invoicing (also called the invoicing queue or billing queue) is the central place where your team tracks each load through the invoice lifecycle. Loads move through five statuses: from **Incomplete** (missing requirements) through **Invoiced** (sent). You can act on multiple loads at once from the Accounting > Invoicing page.

## Where to Find It

Navigate to Accounting in the left menu, then select Invoicing. The page opens to the **Incomplete** tab by default. Use the tab bar at the top to switch between statuses.

<Note>
  <img alt="Batch Invoicing page showing the five status tabs and the load list with checkboxes." />

  * Batch Invoicing page showing the five status tabs and the load list with checkboxes.\*
</Note>

## Key Concepts

**Incomplete:** The load has been delivered or marked **TONU** but is missing required documents or information. Check the Reason Incomplete column to see exactly what is outstanding before moving the load forward.

**Released:** All required documents are present and the load is ready to invoice. From **Released** you can create an invoice (moves the load to **Queued**) or create and send in one step (moves the load directly to **Invoiced**).

**Queued:** An invoice has been created but not yet sent to the customer. Select multiple loads in this status and use Send Invoice to dispatch them.

**Invoiced:** The invoice has been sent to the customer. From this status you can resend the invoice or send a payment reminder.

**Payment Discrepancies:** A payment has been applied but an outstanding balance or credit remains. Review and resolve the discrepancy before the load is fully settled.

## How to Use It

The most common bulk action is moving multiple loads from **Incomplete** to **Released** at once.

1. Open Accounting > Invoicing and select the Incomplete tab.
2. Check the boxes next to the loads you want to move.
3. Select Move to Released. A confirmation modal appears before the move is finalized.
4. After loads reach **Released**, select them and use Create Invoice or Create & Send to advance them toward payment.

<Note>
  <img alt="Screenshot of the multi-select checkbox flow and Move to Released modal." />

  \*Screenshot of the multi-select checkbox flow and Move to Released modal. \*
</Note>

## Settings & Permissions

Access to Accounting > Invoicing requires both the **"Billing"** and **"Invoice"** permissions on the user profile.

## Limits & Behavior

Loads must reach a Delivered or **TONU** status before they appear in the **Incomplete** tab or can be moved to **Released**.

A load cannot be moved to **Released** if any documents required by the customer's invoicing settings are missing.

## FAQs

**Q: Why does a load show as Incomplete even though it was delivered?**

**A:** The load is missing one or more required documents or fields. Check the Reason Incomplete column on the Incomplete tab to see exactly what is outstanding.

**Q: What is the difference between Create Invoice and Create & Send?**

**A:** Create Invoice moves the load to **Queued**, where the invoice is staged but not yet sent. Create & Send creates the invoice and delivers it to the customer in one step, moving the load directly to **Invoiced**.

**Q: Can I move loads from statuses other than Incomplete to Released?**

**A:** No. Only loads in **Incomplete** status can be moved to **Released** in bulk. Loads already in **Queued**, **Invoiced**, or **Payment Discrepancies** require individual action.

**Q: Who can access Batch Invoicing?**

**A:** Users with both the **"Billing"** and **"Invoice"** permissions. Drivers cannot access this page.

## Go Deeper

* [Invoicing Settings](/en/help/accounting-settlements/invoicing-settings)


# Billing Status Definitions
Source: https://docs.alvys.com/en/help/accounting-settlements/billing-status-definitions

Understand every Alvys load billing status from Released to Paid, learn the invoicing lifecycle, and filter loads by billing stage to spot bottlenecks.

<Note>
  Every load that moves through Alvys billing carries one of these statuses, which tells your team exactly where the load stands in the invoicing lifecycle, from dispatcher release through final payment.
</Note>

## Overview

In Alvys, every load in the billing workflow is assigned a status that reflects its current position in the invoicing lifecycle. These statuses appear on the Invoice tab under Accounting and update automatically as your team takes action on each load. Understanding what each status means helps dispatchers, billers, and accounting staff coordinate handoffs and track outstanding invoices without confusion.

Billing status is also referred to as load billing status or invoice status in Alvys.

## Where to Find It

Select **Accounting** from the left navigation menu, then select **Invoice**. Each load row in the list displays its current billing status. You can filter the list by status to focus on a specific stage of the billing process.

## Key Concepts

### The billing lifecycle

Loads move through billing statuses in this order as your team invoices and receives payment:

**Released** → **Queued** → **Invoiced** → **Financed** (if applicable) → **Completed** → **Paid**

Loads that were canceled before delivery but still require invoicing follow a separate path and appear with a **TONU** status.

## How to Use It

For step-by-step instructions on moving a load through the billing workflow, see the following articles:

* Releasing a Load to Billing
* Batch Invoicing

## Settings and Permissions

Viewing and acting on loads in the Invoice tab requires the **"Billing"** and **"Invoice"** permissions. Users without these permissions do not see the Invoice option under Accounting.

## Limits and Behavior

### Released

A load moves to **Released** when a dispatcher releases it to the billing team. The load has been delivered and is ready for invoicing. No invoice has been created yet.

### Queued

A load moves to **Queued** after an invoice has been created but before that invoice has been submitted to the customer. The invoice exists in Alvys but has not yet been sent.

### Invoiced

A load moves to **Invoiced** once the invoice has been submitted to the customer. The invoice is in the customer's hands and payment is pending.

### Financed

A load moves to **Financed** when the invoice has been purchased by a factoring company. The factoring company now owns the receivable, and payment will come from the factor rather than directly from the customer.

### Completed

A load moves to **Completed** once it has been paid in full. For factored loads, this status is set when the factoring company confirms the transaction is settled.

### Paid

A load moves to **Paid** after the Completed step when final payment processing is confirmed. This is the terminal status in the billing lifecycle.

### TONU (Truck Order Not Used)

A load receives a **TONU** status when the truck was dispatched but the shipment did not take place (for example, the customer canceled after the driver was already en route). TONU loads are invoiceable and appear in the billing queue so that a cancellation fee can be invoiced to the customer. TONU is also written as "truck order not used" or "truck ordered not used."

## FAQs

**Q: Why does a load show as Released but my billing team says it is not in their queue?**

**A:** The **"Billing"** and **"Invoice"** permissions must both be enabled. If **"Billing"** is not checked, no billing pages will be visible. Confirm both permissions are enabled on the user's profile. If permissions are correct and the load still does not appear, contact Alvys support with the load number.

**Q: Can a load go back to a previous billing status?**

**A:** Billing statuses generally move forward through the lifecycle. Reversing a billing status requires specific actions such as voiding a transaction or rolling back an invoice; these actions require the **"VoidTransaction"** or **"RollBackTransaction"** permissions. If you have those permissions and are still unable to reverse a status, contact Alvys support with the load number.

**Q: What is the difference between Completed and Paid?**

**A:** **Completed** means the invoice has been paid in full and the billing cycle for the load is closed. **Paid** is the terminal status that follows Completed once final payment processing is confirmed at the system level.

**Q: Does a TONU load follow the same billing steps as a normal delivered load?**

**A:** A **TONU** load enters the billing queue at **Released** (after the dispatcher releases it) and can then be invoiced using the same steps as a delivered load. The difference is that TONU loads are invoiced for a cancellation or dry-run fee rather than a freight charge.

## Go Deeper

* [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing)
* [Understanding Load Statuses and How to Revert Them](/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them)
* [Understanding Factoring in Alvys](/en/help/integrations/how-to-set-up-and-use-factoring-in-alvys)
* [Billing Permissions](/en/help/administration/billing-permissions)


# Carrier Settlements
Source: https://docs.alvys.com/en/help/accounting-settlements/carrier-settlements

Approve carrier payable items, generate carrier settlement statements, email statements to carriers, and sync carrier pay to QuickBooks or NetSuite.

## Overview

Carrier Settlements (also called carrier pay, carrier payables, or carrier statements) in Alvys allows brokers to manage carrier payables, generate carrier payment statements, and sync settlement data to external accounting systems including QuickBooks, Business Central, and NetSuite.

If you are a broker or a hybrid who pays carriers for delivered, released, or invoiced trips, Carrier Settlements is where you handle statements in bulk. You can view all your unpaid trips across carriers in one place, review documents, and generate statements that sync to your accounting system. The module also includes Super Settle View for consolidated payable item review, statement status tracking, and automatic trip status updates on statement generation.

## Getting Started

**1. Check your external accounting (if applicable).** If you sync payment data with QuickBooks Online, QuickBooks Desktop, Business Central, or NetSuite:

* Enable **Carrier Settlements**.
* Disable **Generate Carrier Invoice Separately**.
  <img alt="Accounting integration settings with Carrier Settlements enabled and Generate Carrier Invoice Separately disabled" />
  *Accounting integration settings with Carrier Settlements enabled and Generate Carrier Invoice Separately disabled*

**2. Verify you have trips to settle.** Navigate to the Carrier Settlements module in Accounting to view any unpaid carriers. Selecting a carrier shows their unpaid trips in the **Open** tab.

<img alt="Carrier Settlements module listing unpaid carriers with unpaid trips in the Open tab" />

*Carrier Settlements module listing unpaid carriers with unpaid trips in the Open tab*

**3. Test generating a statement.** Select a carrier with an unpaid trip, walk through the process below to generate a statement, then verify it synced to your accounting system correctly. You will know it worked when:

* The statement has a **Processed** badge.
* Accounting sync says **Successful**.
  <img alt="Generated statement showing the Processed badge and Successful accounting sync status" />
  *Generated statement showing the Processed badge and Successful accounting sync status*

## Where to Find It

Go to **Accounting > Carrier Settlements** to view carrier payables. The module includes four tabs:

* **Open** — Unpaid trips and transactions.
* **Drafts** — Approved transactions pending statement generation.
* **Statements** — Generated statements with paid trips.
* **Errors** — Any failed emails, PDFs, or transactions that did not sync.
  <img alt="Carrier Settlements module with the Open, Drafts, Statements, and Errors tabs" />
  *Carrier Settlements module with the Open, Drafts, Statements, and Errors tabs*

## Key Concepts

### Payable items

Payable items are the individual line items associated with a carrier's trip. Within Carrier Settlements, each item can be in one of three states: **Open** (pending review), **Approved** (approved for payment), or **Disputed** (flagged for review).

### Carrier settlement statements

A carrier settlement statement consolidates one or more approved payable items into a single payment record for a carrier. Statements can be downloaded as PDFs or emailed directly to the carrier from within Alvys.

### Statement statuses

Statements move through four statuses: **Queued** (being processed), **Processed** (generation complete), **Paid** (marked as paid), and **Failed** (an error occurred during processing).

## How to Generate a Carrier Statement

### Select an unpaid carrier

From the carrier view you can see all trips and settlements related to a specific carrier, which makes it easy to review open trips and approve them onto a draft statement. From here you can:

* Select a trip to review payables.
* Manage documents uploaded to the trip.
* Edit the carrier's linehaul amount.
* Dispute the rate.

<Warning>
  Marking an open item as **Disputed** blocks that trip from being approved until the dispute is marked as **Resolved**.
</Warning>

<img alt="Carrier view showing open trips, document management, linehaul edit, and dispute actions" />

*Carrier view showing open trips, document management, linehaul edit, and dispute actions*

### Review approved trips in Drafts

Any transactions or trips you have approved land in **Drafts**. This lets you keep track of trips that are ready to be paid. You can also use internal notes on the trip to record why something is disputed, so you can unapprove any trips with issues.

<img alt="Drafts tab showing approved trips ready for statement generation" />

*Drafts tab showing approved trips ready for statement generation*

### Finalize and generate the settlement

Once you are ready to create a statement, select **Generate**, set the remittance date, and select a carrier email to share it with if needed. This kicks off the process to sync your statement with your accounting system (if enabled).

<img alt="Finalizing And Generating A Carrier Settlement" />

*Generating a carrier settlement statement with remittance date and carrier email selection*

### Reviewing payable items with Super Settle View

Super Settle View provides an expanded view for reviewing, approving, and disputing all payable items for a single trip in one place, alongside the trip's documents.

1. From the **Open** or **Drafts** tab, select a trip.
2. Click **View All** to open Super Settle View.
3. Review attached documents in the Document Management section.
4. Review payable items grouped by status (Open, Approved, Disputed).
5. Click **Approve** on any item to approve it, or click **Dispute** to flag it for review.

<img alt="Super Settle View with payable items, document management, and the approval and dispute action buttons" />

*Image showing Super Settle View with payable items, document management, and the approval and dispute action buttons.*

## Advanced Workflows

### Remittance dates and payment terms

Remittance dates reflect when the carrier will be paid — the "term date". To change the defaults, update the payment terms on the carrier's profile. You can also set a custom remittance date while generating a statement.

<img alt="Setting a custom remittance date while generating a carrier statement" />

*Setting a custom remittance date while generating a carrier statement*

### View carrier settlement status from the load

For brokered trips already on a carrier settlement statement, open the trip's **Load Detail Page** and look for the **Carrier Settlement** panel. It shows the statement's status, statement number, payment provider, date, **Total / Paid / Remaining**, the full list of **Trips on this Statement** (with the current trip highlighted), and the **Payments** ledger — all inline. Click the statement number to jump straight to that statement in Carrier Settlements.

<img alt="Carrier Settlement panel on the Load Detail Page showing statement status and payments" />

*Carrier Settlement panel on the Load Detail Page showing statement status and payments*

<Note>
  Once a trip is added to a statement, the old per-trip Payments table and **Add Carrier Payments** option are hidden, since payment is now managed at the statement level. The Carrier Invoice # still displays on the Load Detail Page.
</Note>

### Marking a statement as paid

Statements are normally marked paid automatically when the matching carrier bill is paid in your accounting system. To update a carrier settlement statement manually:

1. Go to **Accounting > Carrier Settlements** and open the **Statements** tab.
2. Locate the statement you want to update.
3. Click the **Mark as Paid** action in the sidebar.
   <img alt="Statements tab with the Mark as Paid action open in the sidebar" />
   *Statements tab with the Mark as Paid action open in the sidebar*

## Settings & Permissions

Carrier Settlements access is enabled or disabled per user from the **Billing** column in the user's profile.

| Permission                   | What it allows                             | Roles         |
| ---------------------------- | ------------------------------------------ | ------------- |
| **Approve Payable Items**    | Approve or dispute payable items on a trip | Admin, Biller |
| **Create Carrier Statement** | Generate carrier settlement statements     | Admin, Biller |
| **Revert Carrier Statement** | Revert a generated statement               | Admin only    |
| **Edit Carrier Rate**        | Modify carrier linehaul charges            | Admin, Biller |

<Note>
  💡 View Carrier Rate and View Payable Amount permissions are not yet supported in Carrier Settlements. These are on the roadmap.
</Note>

## Limits & Behavior

### Trip status updates on statement generation

When a carrier settlement statement is generated, trip statuses update automatically:

A trip in **Delivered** or **Released** status moves to **Invoiced** when a statement is generated. It moves to **Completed** once the statement is marked paid. This only applies when every transaction on the trip is included in the statement.

### Carrier bill paid status syncs from accounting

When a carrier bill is marked paid in your accounting system (QuickBooks Online, and so on), the matching carrier statement in Alvys updates to paid automatically — you no longer need to manually mark statements as paid in Carrier Settlements to track it. This applies to carrier settlements only; customer invoicing is unchanged.

### Syncing with external accounting systems

**Option 1: Turn on Carrier Settlements**, which integrates with QuickBooks, Business Central, and NetSuite through your existing accounting integration settings. When both Carrier Settlements and **Generate Carrier Invoice Separately** are enabled, the Carrier Settlements setting takes precedence.

**\[Legacy] Option 2: "Generate Carrier Invoice Separately"** is a legacy option that creates a bill in your accounting system when a carrier invoice is uploaded to the trip. When using this option, disable the Carrier Settlements setting so that payments recorded in your accounting system flow back into Alvys.

<img alt="Screenshot of the Accounting Integration settings" />

*Screenshot of the Accounting Integration settings*

## FAQs

**Q: Can I use Carrier Settlements if Generate Carrier Invoice Separately is also enabled?**

**A:** Yes, but the Carrier Settlements setting takes precedence. When both settings are active, carrier settlement statements are used rather than separate carrier invoices.

**Q: Do payments I record in my accounting system appear in Alvys?**

**A:** Yes. When a carrier bill is marked paid in your accounting system, the matching carrier statement in Alvys updates to paid automatically. You can still mark a statement paid manually from **Accounting > Carrier Settlements > Statements** using **Mark as Paid** if you need to record it in Alvys first. This applies to carrier settlements only; customer invoicing is unchanged.

**Q: Which roles can revert a carrier settlement statement?**

**A:** Only users with the Admin role and the **"RevertCarrierStatement"** permission can revert a carrier settlement statement. Biller users cannot revert statements.

**Q: What happens to a payable item in Disputed status?**

**A:** Disputed items are flagged for review and are not included in the next statement generation until resolved. They remain visible in Super Settle View and can be approved or left in Disputed status.

**Q: What does it mean when a statement shows a Failed status?**

**A:** A Failed status means an error occurred during statement processing. Contact Alvys support with the statement details so the team can investigate the cause and help you regenerate it.

**Q: How do carrier statements work?**

**A:** Carrier settlement statements consolidate one or more approved payable items into a single payment record for a carrier. Statements can be downloaded as PDFs or emailed directly to the carrier.

**Q: What does the status column track on the Statements tab?**

**A:** Statement statuses track a statement from creation to payment: Queued (processing) → Processed (generation complete) → Paid (marked as paid) — or Failed if an error occurred.


# Custom Payment Terms for Customers
Source: https://docs.alvys.com/en/help/accounting-settlements/custom-payment-terms-for-customers

Set any payment term from 0 to 365 days on a customer instead of choosing from the preset dropdown, and understand the change to Net 0 behavior.

You can now set **custom Payment Terms** for any customer, from **0 to 365 days**, instead of being limited to a preset dropdown list.

<img alt="Notion Image" />

Previously, if a specific term wasn’t available in the dropdown, users either left the field blank or picked something that didn’t match their actual agreement, not ideal.

This update allows for more accurate and flexible billing, and cleaner customer records.

## How to Use It

1. Go to any **Customer** page.
2. Click the **Payment Terms** field.
3. Type in any number between **0 and 365**.
   <img alt="Notion Image" />

## Net 0 Behavior Is Changing

Historically, Alvys didn’t officially support **Net 0**. If you requested it, our devs manually set it in the backend, but technically, those were still treated as **Net 30** terms in the system.

With this update:

* We’re **cleaning up the customers** who were incorrectly set to “Net 0”, they’ll now reflect the actual 30-day terms they were using all along. If you have customers who fall into this bucket, we'll be reaching out to you directly regarding this change.
* If you **really do want Net 0**, you can now set that manually using the new input field.
  If you’ve ever wished you could just type in the exact payment terms your customer agreed to, now you can.
  Questions? Reach out to Support or Customer Success and we’ll help you get things set up.


# Customer Credit Limits Explained
Source: https://docs.alvys.com/en/help/accounting-settlements/customer-credit-limits-explained

Set a credit limit on a customer and see their outstanding balance against it on the customer profile and Load Details Page.

## Overview

Customer Credit Limits give you passive awareness of a customer's credit standing right where you work. You can set an optional credit limit on any customer, and Alvys shows their current outstanding balance — both on the customer profile and directly on the Load Details Page — so dispatchers and account managers can see credit exposure at the moment it matters most.

This is a visibility feature. Alvys does not block, warn, or require approvals based on the limit; it simply surfaces the information so your team can make informed decisions.

## Required permissions

Access to the Credit Limits feature is controlled by two permissions. You can assign them to any role under your permission settings, giving you control over who can see credit information and who can change it.

**View Credit Limits**

This permission gives a user read-only access to customer credit information. Users with only this permission can monitor credit standing but cannot set or change any limits.

**Manage Credit Limits**

This is the full-access permission. In addition to everything included in View, it lets a user:

* Set a credit limit on an individual customer profile
* Add a subsidiary-wide default limit in the settings area
* Edit or update existing limits

<img alt="Screenshot" />

## Two ways to set a credit limit

<img alt="Screenshot" />

\*\*Global and subsidiary limits: \*\*From the settings area you can select credit limits and apply a limit across all customers within a subsidiary.

<img alt="Screenshot" />

\*\*Customer limits: \*\*Open the customer's profile and enter a dollar amount in the **Credit Limit** field. The field is editable inline by any user with the Edit Customer permission. A credit limit is optional. If you don't set one, Alvys still shows the customer's outstanding balance as a standalone figure — you just won't see a progress bar or percentage.

## Reading the Outstanding Balance

<img alt="Screenshot" />

The outstanding balance reflects a customer's true credit exposure — not just what has been formally billed. It combines:

* **Overdue unpaid invoices** — the remaining balance on invoices that are past their due date and not yet paid. Alvys displays this plain-language description next to the visualization: "Outstanding balance includes all overdue unpaid invoices (past due date based on net payment terms) plus the current revenue on any open, in-transit, or delivered loads not yet invoiced."
* **Revenue on un-invoiced loads** — the current revenue (linehaul plus customer accessorials) on any open, in-transit, or delivered loads that have not been invoiced yet.

The balance recalculates automatically. If an accessorial is added to an open load, the outstanding balance updates to reflect the new load revenue. Once a load is invoiced, it moves out of the un-invoiced revenue calculation and is tracked through its invoice instead — so amounts are never double-counted.

## Where You'll See It

### Customer Profile

The credit limit field and the outstanding balance visualization appear on the customer profile, alongside payment terms in the credit section.

<img alt="Screenshot" />

### Load Details Page

The same visualization appears — read-only — directly below the customer name on the Load Details Page, so dispatchers see credit standing in context while working a load. No navigation required. A credit limit of \$0 is treated as unconfigured. Alvys will show the standalone outstanding balance with no bar. Set a positive dollar amount to see the progress bar and thresholds.

<img alt="Screenshot" />

<img alt="Screenshot" />

### Custom reporting

build reports and dashboards on two customer financial fields — **Credit Limit** and **Outstanding Balance** — directly in Custom Reporting. These are the same values shown in the Credit section of a customer's profile, now available as reportable fields so you can analyze credit standing across your customer base. To use them, open Custom Reporting and add the **Credit Limit** or **Outstanding Balance** field from the customer dataset to your report or dashboard, just as you would any other metric. Credit Limit reflects each customer's effective limit (a company-specific override if one is set, otherwise your company's default limit), and both fields are formatted as currency. Customers with no credit limit set will appear blank rather than showing 0. As with all Custom Reporting data, these fields respect your tenant's data isolation, so each report only shows your own customers' figures.

## FAQs

**Does Alvys stop me from adding a load if a customer is over their limit?**

No. This is a visibility-only feature. There is no blocking, warning, or approval workflow — the information is shown so your team can decide how to act.

**What if a customer has no payment terms set?**

All unpaid invoices are treated as immediately due and count toward the overdue portion of the balance from their invoice date.

**Why did the balance change after I added an accessorial?**

The balance uses the current total revenue on un-invoiced loads. Adding or modifying an accessorial on an open load recalculates the outstanding balance automatically.

**What happens once a load is invoiced?**

The load moves out of the un-invoiced revenue calculation and is tracked through its invoice instead, so the amount is never counted twice.


# Driver Rates, Rules & Plans: The Complete Guide
Source: https://docs.alvys.com/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex

Reference for Alvys driver rate types, rate policies, rules, and driver rate plans, with the calculation logic used when trips deliver on statements.

**Audience:** Payroll managers, settlements managers, implementation specialists, anyone configuring rates.

### Mental model in three layers

```text theme={null}
Driver<br>  -&gt; Rate Policies (named buckets, one or more per driver)<br>        -&gt; Rates (the actual line items the policy generates)<br>        -&gt; Rules (conditions, optional, decide WHEN the policy fires)        
```

* A **Rate** is a single calculation rule that produces one line item on a statement. Example: "\$0.55 per loaded mile."
* A **Rate Policy** is a named bucket that groups one or more rates that should always fire together, with optional **Rules** that gate when the policy applies. Example: a policy called "California Hourly" containing a Per Hour rate and a Daily Per Diem rate, with a rule "Trip Subsidiary = California."
* A **Driver** can have multiple policies. They are evaluated independently, and every policy whose rules match contributes line items to the statement.

The most important invariant: **Statement rates cannot share a policy with Trip or Time-based pay rates.** Trip and Time-based pay rates *can* coexist in the same policy except **Daily Pay, which cannot coexist with any other type of rate.** So a single policy can hold any mix of Trip + Time-based pay rates (e.g. Loaded Miles + Daily Per Diem), but a Statement rate (Minimum Pay, Bonus) and Daily Pay must live alone in its own policy.

***

### Rate categories

Every rate belongs to exactly one of three categories. The category controls when the rate fires.

| Category           | When it applies                                                          | Examples                                                          |
| ------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Trip**           | One line item per trip leg                                               | Loaded Miles, Per Stop, % Line Haul, % of Trip Value, Service Fee |
| **Time-based pay** | Per hour, per day, or per mile (per diem) — depends on the specific rate | Hourly Pay, Overtime, Daily Pay, Daily Per Diem, Mileage Per Diem |
| **Statement**      | Once per statement, after all Trip and Time-based pay rates are computed | Minimum Pay, Bonus                                                |

**Time-based pay rates** include Hourly Pay, Overtime (an extension of Hourly Pay), Daily Pay, Daily Per Diem, and Mileage Per Diem. Their mechanics vary: Hourly Pay and Mileage Per Diem read trip-level data (Hours Worked, trip miles) and produce one line item per trip leg; Daily Pay and Daily Per Diem read selected calendar days from Manage Calendar and produce one line item per day; Overtime extends Hourly Pay with a threshold.

***

### Every supported rate type, in depth

The next several sections cover each rate type Alvys supports today. Each entry has a definition, the precise inputs you set, when the rate fires, the calculation logic, two realistic use cases, and things to watch out for.

***

## Trip rates

Trip rates produce **one line item per trip leg**. A driver with the same trip rate policy across 10 trips ends up with 10 line items (one per trip).

Trip rate line items are **continuously recalculated** against the current rate configuration. The line item is rebuilt whenever the trip, load, or driver's rate policies change. So adding or editing a rate on a driver after a trip has already been delivered still updates that driver's pay for the trip, as long as the trip is not yet on a processed statement. (See "When rules are evaluated" in the Rules section for the precise rebuild triggers and the rules around processed statements being locked.)

Trip rates can be combined freely with other Trip rates and with Time-based pay rates in the same policy. They cannot share a policy with Statement rates.

***

### Per Trip

**What it is:** A flat dollar amount the driver earns per trip leg. Simplest in the catalog, but also supports mileage tiers plus the Use Highest Tier checkbox when you want the trip rate to vary by trip length.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: dollar amount per trip. Single flat number (e.g. \$150 per trip) or a tiered set of (mileage threshold, rate) pairs.
* **Mileage Type** (only used with tiers): Loaded, Empty, or Total. Determines which mileage value picks the tier.
* **Tiers** (optional): a set of mileage bands each mapping to a flat trip dollar amount.
* **Use Highest Tier checkbox**: off = stepped (rare for Per Trip), on (typical) = the trip pays the flat dollar amount of the band it falls in.

**How it calculates:**

Single-tier (the default):

```text theme={null}
Driver pay = Rate
```

Tiered with Use Highest Tier on (typical for Per Trip):

```text theme={null}
Tiers:<br>  up to 100 mi: $100<br>  up to 300 mi: $200<br>  300+ mi: $350<br><br>A 250-mile trip: $200 (the band that 250 falls in)
```

**Use cases:**

* Owner operator paid a flat \$400 per trip regardless of miles.
* Local shuttle driver paid $75 per short-haul trip, $125 if the trip crosses a mileage threshold (tiered with Use Highest Tier on).

**Gotchas:**

* Per Trip applies once per trip leg, not once per load. A 2-leg load generates 2 line items.
* The Mileage Type only matters when tiers are configured; the field is ignored on a single flat rate.
* Stepped mode (Use Highest Tier off) makes little sense for Per Trip since it would pay across bands; in practice you almost always want Use Highest Tier on.

<img alt="" />

<img alt="" />

***

### Per Load

**What it is:** A flat amount paid once per load, regardless of how many trip legs that load has.

**When it applies:** One line item per load, attached to the driver's **last trip** of the load. If the same driver runs three legs of a load, the Per Load rate generates exactly one line item, on the third leg.

**Inputs:**

* **Rate**: flat dollar amount per load.

**How it calculates:**

```text theme={null}
Driver pay = Rate (on the last trip only)
```

**Use cases:**

* "We pay drivers a $50 loading bonus per load." Use Per Load $50 instead of trying to identify "the first stop."
* OO paid a flat \$500 per completed load on a dedicated lane.

**Gotchas:**

* If a load is split between two drivers, only the driver doing the last leg of that load gets the Per Load amount. To split it, use a percentage rate instead.
* The Per Load line item appears on the leg where the load is fully delivered, not on the first pickup.

<img alt="" />

***

### Loaded Miles

**What it is:** Per-mile rate locked to **loaded miles only**. Shows up on the statement as its own "Loaded Miles" line. Supports tiers and the Use Highest Tier checkbox.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: per-mile amount. Single flat number, or a tiered set of (mileage threshold, rate) pairs.
* **Tiers** (optional): add multiple bands like "up to 100 mi: $1.50 / up to 300 mi: $1.20 / 300+ mi: \$1.00". Thresholds must be unique.
* **Use Highest Tier checkbox**: when **off** (default), tiers are **stepped** like a tax bracket; when **on**, the system picks the **single tier matching the trip's total mileage** and applies that flat rate to all loaded miles. See the Mileage tiers section for worked math.

**How it calculates:**

Single-tier:

```text theme={null}
Driver pay = Rate x Loaded Miles
```

Multi-tier stepped (Use Highest Tier = off):

```text theme={null}
500 loaded miles with tiers [100mi @ $1.50, 300mi @ $1.20, 300+ @ $1.00] = 100 x $1.50 + 200 x $1.20 + 200 x $1.00 = $590
```

Multi-tier flat by band (Use Highest Tier = on):

```text theme={null}
Same 500 mi, same tiers = 500 x $1.00 = $500 (the band 500 mi falls in)
```

**Use cases:**

* Tenant who wants drivers to see loaded vs empty separately on every statement.
* OO paid a higher rate on loaded miles ($0.85) and a lower rate on empty miles ($0.55), so the driver can see what each contributed.
* Mileage progression where long hauls pay more per loaded mile (stepped tiers) or short hauls fall into a different flat rate band (Use Highest Tier on).

**Gotchas:**

* Loaded Miles + Empty Miles in the same policy is the standard way to split. They generate two line items per trip.
* If you want a "no empty pay" structure, configure Loaded Miles only. Empty miles will not pay.
* The mileage value comes from the trip's calculated miles, not a manual field. Miles are locked once the trip is on a processed statement.

<img alt="" />

<img alt="" />

***

### Empty Miles

**What it is:** Per-mile rate locked to **empty (deadhead) miles only**. Supports tiers and the Use Highest Tier checkbox. Shows up as its own "Empty Miles" line on the statement.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: per-mile amount, flat or tiered.
* **Tiers** (optional): same shape as Loaded Miles.
* **Use Highest Tier checkbox**: off = stepped tiers, on = flat rate for the band the trip's mileage falls in.

**How it calculates:**

```text theme={null}
Driver pay = Rate x Empty Miles
```

Tiered math works exactly like Loaded Miles. See that section or the Mileage tiers section for worked examples.

**Use cases:**

* "We pay $0.30 for deadhead." Use Empty Miles $0.30 alongside Loaded Miles \$0.55.
* Compensating drivers for repositioning trips where empty miles dominate.
* Different deadhead pay below vs above a mileage threshold (use tiers).

**Gotchas:**

* If you do not include an Empty Miles rate, the driver is not paid for empty mileage at all (unless the policy is using Total Miles).

***

### Total Miles

**What it is:** Per-mile rate that pays on loaded + empty combined as one number. Supports tiers and the Use Highest Tier checkbox.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: per-mile amount, flat or tiered.
* **Tiers** (optional): same shape as Loaded / Empty Miles.
* **Use Highest Tier checkbox**: off = stepped tiers, on = flat rate for the matched band.

**How it calculates:**

```text theme={null}
Driver pay = Rate x (Loaded Miles + Empty Miles)
```

Tiered math identical to Loaded Miles, just summed across both loaded and empty.

**Use cases:**

* Simple per-mile contract that does not distinguish loaded from empty.
* Mileage progression where the driver earns more per total mile on longer runs (stepped tiers).
* Short-haul vs long-haul flat rates by mileage band (Use Highest Tier on).

**Gotchas:**

* The driver cannot see the loaded vs empty breakdown on a Total Miles statement. If you need that visibility, use Loaded Miles + Empty Miles instead.

***

### Mileage Deduction

**What it is:** A per-mile rate applied as a **negative** line item. Used for charge-backs that scale with mileage. Supports tiers and the Use Highest Tier checkbox just like the earnings mileage rates.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: per-mile deduction amount. Flat or tiered.
* **Mileage Type**: Loaded, Empty, or Total. Determines which mileage value gets multiplied.
* **Tiers** (optional): for graduated charge-backs (e.g. lower fee per mile on long hauls).
* **Use Highest Tier checkbox**: off = stepped tiers, on = flat rate for the band the trip's mileage falls in.

**How it calculates:**

```text theme={null}
Driver pay (negative) = -1 x Rate x Miles (of the chosen type)
```

Tiered math mirrors Loaded Miles, just with a negative sign.

**Use cases:**

* OO equipment lease charged at $0.10/mile. Configure Per Mile Deduction $0.10, Mileage Type = Loaded.
* Insurance pass-through charged at \$0.05/mile across all miles (Mileage Type = Total).
* Graduated lease where the per-mile charge drops on long hauls (use tiers).

**Gotchas:**

* Per Mile Deduction is a true negative line item, separate from accessorial-based deductions. It applies inside the rate engine, not via the statement's deduction section.
* If the OO's per-mile earnings are $0.55 and you add a $0.10 Per Mile Deduction, net effect is $0.45/mile. Both line items appear on the statement (positive $0.55 and negative \$0.10).

<img alt="" />

***

### Per Stop

**What it is:** A per-stop pay rate scoped to the current trip leg. Supports a free-stop threshold and an optional flat bonus.

**When it applies:** One line item per trip leg. The amount is built from all stops on that trip.

**Inputs:**

* **Threshold**: number of stops that are NOT paid (typically 1, to exclude the pickup or delivery).
* **Rate**: dollar amount per stop beyond the threshold.
* **Flat Bonus**: optional flat amount added on top once the threshold is crossed.

**How it calculates:**

```text theme={null}
If StopsOnTrip &gt; Threshold:<br>  Driver pay = (StopsOnTrip - Threshold) x Rate + FlatBonus<br>Else:<br>  Driver pay = 0
```

**Use cases:**

* "Pay $25 per extra stop after the first." Set Threshold = 1, Rate = $25.
* "Pay $30 per stop plus a $50 multi-stop bonus when there are more than 2 stops." Set Threshold = 2, Rate = $30, Flat Bonus = $50.

**Gotchas:**

* The threshold is per **trip leg**, not per load. A two-leg load with two stops each fires Per Trip Stop separately on each leg.
* If the same driver covers multiple legs of a load and you want a per-load count instead, use Per Customer Stop.

<img alt="" />

***

### Per Customer Stop

**What it is:** Per-stop pay counted across the **whole load**, not just one trip leg. Pays only on the driver's last trip of that load.

**When it applies:** One line item per load, attached to the driver's last trip of the load.

**Inputs:**

* **Threshold**: number of customer stops not paid (e.g. 1 to exclude the first customer).
* **Rate**: dollar amount per customer stop beyond the threshold.
* **Flat Bonus**: optional flat amount layered on top.

**How it calculates:**

```text theme={null}
If CustomerStopsOnLoad &gt; Threshold:<br>  Driver pay = (CustomerStopsOnLoad - Threshold) x Rate + FlatBonus<br>Else:<br>  Driver pay = 0
```

**Use cases:**

* "Pay $25 per extra customer stop on a multi-stop load." Threshold = 1, Rate = $25.
* OOs paid for multi-drop runs where the load may span multiple legs but the customer stops are what matters.

**Gotchas:**

* Customer stops only. Yard moves, fuel stops, and relay stops are not counted.
* If a load has two drivers, only the driver running the last leg gets the Per Customer Stop pay. To split, configure each driver's policy differently or use Per Trip Stop on each leg.

<img alt="" />

***

### % of Trip Value

**What it is:** Percentage paid against the trip's share of the load's customer rate. "Trip value" = the load's **Line Haul + Fuel Surcharge** (the only two components the load's rate captures on the FE), prorated to each trip by **total miles**. Accessorials are NOT included.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Percentage**: 0 to 100.

**What "trip value" actually is:**

When a load is created in Alvys, the FE only lets you enter the customer's **line haul** and **fuel surcharge**. Together they make up the load's `Rate` field. Accessorials (detention, lumper, layover, etc) live on separate fields entirely.

* **Components:** customer Line Haul + customer Fuel Surcharge. Nothing else.
* **NOT included:** detention, lumper, layover, TONU, and every other customer accessorial.
* **Proration:** `Trip Value = (Line Haul + Fuel Surcharge) x (this trip's total miles / load's total miles)`. Proration uses **total miles** (loaded + empty), not loaded miles. A single-trip load = the full (line haul + FSC).
* **Override:** users can manually override a trip's value on the load. If overridden, the system uses the override and stops auto-proration for that trip.

**How it calculates:**

Single-trip load:

```text theme={null}
Driver pay = (Percentage / 100) x (Line Haul + Fuel Surcharge)
```

Multi-trip load:

```text theme={null}
Trip Value = (Line Haul + Fuel Surcharge) x (this trip's total miles / load's total miles) Driver pay = (Percentage / 100) x Trip Value
```

**Worked example:**

A load has $1,800 customer line haul and $200 customer fuel surcharge (Load.Rate = $2,000), plus $150 detention as a separate accessorial. The load runs as two trips: Trip A = 600 total mi, Trip B = 400 total mi.

* Trip value for A = ($1,800 + $200) x (600 / 1,000) = **\$1,200**
* Trip value for B = ($1,800 + $200) x (400 / 1,000) = **\$800**
* The \$150 detention is excluded entirely. To pay the driver for detention, configure it through accessorial settings or add a manual line item to the statement.

At a 70% rate: Driver on Trip A gets $840, Driver on Trip B gets $560.

**Use cases:**

* Owner operator paid a single percentage that covers both line haul and fuel surcharge in one line item.
* Tenants who do not want to expose two separate "% of Line Haul" and "% of FSC" lines on the driver statement.

**Gotchas:**

* **Proration is by total miles**, not loaded miles. % of Line Haul and % of Fuel Surcharge both prorate by loaded miles. Same load can therefore yield slightly different splits depending on which rate type you use, when loaded and empty miles are unevenly distributed across trips.
* Tenants who want **different** percentages on line haul vs fuel surcharge (e.g. 75% of line haul, 100% of FSC) should use **% of Line Haul + % of Fuel Surcharge** as two separate rates. % of Trip Value bundles the two and applies a single percentage.
* Trip value can be manually overridden on a load via Edit Trip. Once overridden, automatic proration is bypassed for that trip.
* Trip Value visibility on driver statements is configurable at the driver or tenant level.

<img alt="" />

***

### % of Trip Value Deduction

**What it is:** Same calculation as % of Trip Value, but applied as a **negative** line item. Used for charge-backs expressed as a percentage of the trip's customer rate (line haul + fuel surcharge), prorated by total miles. Accessorials are NOT included.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Percentage**: 0 to 100.

**How it calculates:**

Single-trip load:

```text theme={null}
Driver pay (negative) = -1 x (Percentage / 100) x (Line Haul + Fuel Surcharge)
```

Multi-trip load:

```text theme={null}
Trip Value = (Line Haul + Fuel Surcharge) x (this trip's total miles / load's total miles) Driver pay (negative) = -1 x (Percentage / 100) x Trip Value
```

**Use cases:**

* Management or admin fee charged as a flat percentage of the customer rate per trip.
* Factoring fee structured as a percentage of trip value rather than line haul alone.
* Negative percentage charge-backs where the deduction should scale with both line haul and fuel surcharge together.

**Gotchas:**

* Mirrors % of Trip Value's quirks: prorated by **total miles** (loaded + empty), not loaded miles. Same as the earnings counterpart.
* If you want to deduct against line haul only (not fuel surcharge), use **% of Line Haul Deduction** instead.
* Trip Value can be manually overridden on a load; the deduction will calculate against the overridden value if one is set.

***

### % of Line Haul

**What it is:** Percentage paid against the customer **line haul** amount on the load, prorated by loaded miles when multiple drivers share the load.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Percentage**: 0 to 100.

**How it calculates:**

For a single-driver load:

```text theme={null}
Driver pay = (Percentage / 100) x Line Haul
```

For a multi-driver load (proration):

```text theme={null}
Driver pay = (Percentage / 100) x Line Haul x (this driver's loaded miles / total loaded miles)
```

**Use cases:**

* OO paid 75% of line haul.
* Team driver split: each driver gets 50% of line haul, automatic via proration.

**Gotchas:**

* Line haul is the customer-billed line haul number on the load, not the driver's calculated revenue.
* Proration is by **loaded miles**. A driver who covered 60% of the loaded miles gets 60% of the line haul share.
* Combine with % of Fuel Surcharge if you also want to pass through fuel.

<img alt="" />

***

### % of Line Haul Deduction

**What it is:** Same calculation as % of Line Haul, but applied as a **negative** line item.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Percentage**: 0 to 100.

**How it calculates:**

```text theme={null}
Driver pay (negative) = -1 x (Percentage / 100) x Line Haul (prorated)
```

**Use cases:**

* OO charged a 3% factoring fee on every load.
* Equipment lease structured as a percentage of revenue.

**Gotchas:**

* Functionally similar to a Service Fee but tied specifically to line haul, not the driver's running subtotal.

***

### % of Fuel Surcharge

**What it is:** Percentage of the customer fuel surcharge on the load, prorated by loaded miles.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Percentage**: 0 to 100.

**How it calculates:**

```text theme={null}
Driver pay = (Percentage / 100) x Fuel Surcharge x (driver loaded miles / total loaded miles)
```

**Use cases:**

* OO paid 100% of fuel surcharge as a fuel pass-through.
* Company driver paid 50% of fuel surcharge as a partial pass-through.

**Gotchas:**

* If the customer rate confirmation has $0 fuel surcharge, this rate pays $0. It does not invent a value.
* Combine with % of Line Haul for the classic OO structure.

<img alt="" />

***

### Service Fee

**What it is:** A **derived** negative rate computed against the driver's running line haul subtotal. The Service Fee runs **last**, after every other rate has computed. Only applicable for Owner Operator driver types.

**When it applies:** One line item per trip leg, computed after all other trip rates on the same trip.

**Inputs:**

* **Percentage**: 0 to 100 (the % of the driver's gross to deduct).
* **Flat Fee**: optional flat amount added on top of the percentage.

**How it calculates:**

```text theme={null}
Driver pay (negative) = -1 x ((Percentage / 100) x DriverLineHaulSubtotal + FlatFee)
```

Where `DriverLineHaulSubtotal` is the sum of all other rate amounts on the trip BEFORE the service fee.

**Use cases:**

* "We charge OOs 5% of their gross plus a $10 admin fee per trip." Percentage = 5, Flat Fee = $10.
* Carriers that pass internal dispatch costs to OOs as a percentage of pay.

**Gotchas:**

* Service Fee is the **only rate that is computed against output of other rates**, not against load or trip fields. This is why it must run last.
* If you add Service Fee twice, both fees stack and the second one is computed against the subtotal that already had the first one applied. Avoid this unless intentional.
* This is NOT the same as a % of Line Haul Deduction. Service Fee uses the driver's running subtotal (which may include per-mile pay, stop pay, etc.); % of Line Haul Deduction uses the load's line haul directly.

<img alt="" />

***

## Time-based pay rates

Time-based pay is the full category of rates that pay by time (hours, days) or by mile-per-diem. It includes:

* **Hourly Pay** (documented above): pays per Hours Worked on each trip.
* **Overtime Threshold and OT Rate** (documented above): extends Hourly Pay with a threshold and OT rate.
* **Mileage Per Diem** (documented above): per-mile per diem on each trip.
* **Daily Pay** and **Daily Per Diem** (below): fire per calendar day selected via Manage Calendar.

The Daily Pay and Daily Per Diem rates below do not auto-attach to trips; the user must select days for the rate to apply.

***

### Daily Pay

**What it is:** Rate per day, generated for every non-per-diem day the user selects on Manage Calendar.

**When it applies:** One line item per selected calendar day.

**Inputs:**

* **Rate**: dollar amount per day.

**How it calculates:**

```text theme={null}
Driver pay = Rate (per day selected)
```

**Use cases:**

* Salary-style drivers paid a daily rate. "\$200/day, 5 days/week."
* OTR drivers on a "guaranteed daily pay" structure during long runs.

**Gotchas:**

* Days must be selected manually via Manage Calendar in Driver Settlements. There is no auto-generation.
* If you forget to mark days, Daily Pay does not fire.
* If you select 7 days but the driver only worked 5, you pay for 7. Pay attention to the calendar.

<img alt="" />

<img alt="" />

<img alt="" />

***

### Daily Per Diem

**What it is:** Same as Daily Pay but only applies on days the user flags as **per diem**, and labels the line item as per diem for tax purposes.

**When it applies:** One line item per selected per-diem day.

**Inputs:**

* **Rate**: dollar amount per per-diem day.

**How it calculates:**

```text theme={null}
Driver pay (per diem) = Rate (per per-diem day selected)
```

**Use cases:**

* OTR driver paid a \$50/day per diem for every day on the road.
* Layover day pay structured as per diem for tax handling.

**Gotchas:**

* Marking a day as per diem versus regular is done on Manage Calendar at selection time.
* As with Daily Pay, the user must manually select days. Per Diem does not auto-trigger from trip events.

***

### Hourly Pay

**What it is:** Rate times Hours Worked on the trip.

**When it applies:** One line item per trip leg. Hours come from the Hours Worked field on the trip record.

**Inputs:**

* **Base Rate**: dollar amount per hour.

**How it calculates:**

```text theme={null}
Driver pay = Base Rate x Hours Worked
```

**Use cases:**

* Local / hourly drivers who do not have a per-mile structure.
* Drivers on a yard or shuttle assignment paid hourly regardless of mileage.

**Gotchas:**

* Hours Worked is a per-trip field on the trip itself, accessed via Open the trip > Edit Trip > Hours Worked. It accepts hours and minutes (e.g. "5 hours 25 minutes").
* If Hours Worked is empty, the line item is $0. The trip will be hidden from the Open list unless **Allow $0 line items on driver statements\*\* is on at the company level.
* Hourly Pay does NOT integrate with HOS / ELD data. The dispatcher (or driver via the app) enters hours manually.

<img alt="" />

<img alt="" />

***

### Overtime Threshold and OT Rate

**What it is:** An extension of Hourly Pay that pays a different (higher) rate once the driver's hours cross a threshold. Used in jurisdictions where state OT law requires daily or weekly OT premiums.

**Inputs:**

* **Base Rate**: dollar amount per hour (the standard Hourly Pay rate).
* **Overtime Threshold**: the hour count at which OT kicks in. Common values: 40 hrs/week, 8 hrs/day, 10 hrs/day, 12 hrs/day.
* **Overtime Rate**: dollar amount per OT hour. Common configurations: `1.5 x Base Rate`, `2 x Base Rate`.
* **Threshold Basis**: per-trip, per-day, or per-statement.

**How it calculates:**

```text theme={null}
If HoursWorked &lt;= Threshold:<br>  Pay = HoursWorked x BaseRate<br>Else:<br>  RegularHours = Threshold<br>  OvertimeHours = HoursWorked - Threshold<br>  Pay = (RegularHours x BaseRate) + (OvertimeHours x OvertimeRate)
```

**Use cases:**

* California hourly driver: $22/hr base, then 1.5x to $33 after 8 hrs/day, then 2x to \$44 beyond 12 hrs/day.
* Federal FLSA: 40 hrs/week at base, then 1.5x beyond.
* Local drivers paid hourly with daily OT premiums for long shifts.

**Gotchas:**

* For multi-tier OT (1.5x then 2x at a second threshold), configure two separate OT rules.
* Threshold Basis determines when OT triggers. Picking the wrong basis (e.g. per-statement when state law requires per-day) results in underpayment.
* Hours Worked must be entered on the trip for OT to compute. See the Hourly Pay section for the Hours Worked field.

<img alt="" />

***

### Mileage Per Diem

**What it is:** Rate times trip miles, labeled as Per Diem on the statement so it can be flagged as non-taxable income in your accounting export. Supports tiers and the Use Highest Tier checkbox like the other mileage rates.

**When it applies:** One line item per trip leg.

**Inputs:**

* **Rate**: per-mile per diem amount. Flat or tiered.
* **Mileage Type**: Loaded, Empty, or Total.
* **Tiers** (optional): per-mileage-band per diem amounts.
* **Use Highest Tier checkbox**: off = stepped tiers, on = flat by band.

**How it calculates:**

```text theme={null}
Driver pay (per diem) = Rate x Miles (of the chosen type)
```

Tiered math mirrors Loaded Miles.

**Use cases:**

* "Pay drivers \$0.12/loaded mile as a non-taxable per diem on top of their loaded-mile pay."
* Tax-advantaged structures where part of the driver's pay is structured as a per-mile per diem.
* Higher per diem on long hauls (tiered with Use Highest Tier on).

**Gotchas:**

* Mileage Per Diem reads trip mileage directly; it does NOT require Manage Calendar selections like Daily Pay and Daily Per Diem do.
* Tax treatment of per diem is your accountant's call, not the system's. The system labels it as per diem and the accounting integration handles the rest.

<img alt="" />

***

## Statement rates

Statement rates fire **once per statement**, after all Trip and Time-based pay rates have computed. They cannot be combined with Trip or Time-based pay rates in the same policy: a policy containing a Statement rate must contain only Statement rates.

***

### Minimum Pay

**What it is:** Guarantees the driver's statement total is at least a minimum. If the computed total is below the minimum, a shortfall line item is added to bring it up.

**When it applies:** One shortfall line item per statement, computed after all other rates on the statement.

**Inputs:**

* **Minimum Amount**: dollar floor for the statement.
* **Basis**: selector with two options.

  * **Flat** (default): the minimum is a fixed amount per statement regardless of how much of the pay period the driver worked.
  * **Prorated**: prorates the minimum across the pay period. Only selectable when the driver's pay period is **7 days**.

**How it calculates:**

Flat basis:

```text theme={null}
If StatementSubtotal &lt; MinimumAmount:<br>  Driver pay (shortfall) = MinimumAmount - StatementSubtotal<br>Else:<br>  Driver pay = 0Prorated basis:
```

```text theme={null}
DaysWorked = number of days in the pay period the driver was active<br>ProratedMinimum = MinimumAmount x (DaysWorked / 7)<br><br>If StatementSubtotal &lt; ProratedMinimum:<br>  Driver pay (shortfall) = ProratedMinimum - StatementSubtotal<br>Else:<br>  Driver pay = 0
```

**Use cases:**

* **Flat:** "Guarantee every driver $1,200 per pay period." Minimum Pay $1,200.
* **Flat:** New-hire training period with a guaranteed weekly minimum.
* **Prorated:** Driver started midweek (e.g. Wednesday on a Sun-Sat pay period); a flat $1,200 guarantee would overpay for a partial week. Prorated minimum scales the floor to 5/7 of $1,200 = \$857.14.
* **Prorated:** Driver took 2 unpaid days. The minimum scales down so they are not paid the full floor for a partial week.

**Gotchas:**

* Prorated basis is **only valid for 7-day pay periods**. If the driver's pay period is biweekly, monthly, or any other length, the Basis selector is disabled with the helper text "Only choose if your pay period is every 7 days."
* Minimum Pay does NOT cap pay. It only adds a shortfall line; high earners are unaffected.
* If the driver has deductions that push their net below the minimum, the shortfall is added BEFORE deductions are applied, so the floor is on gross pay, not net pay.
* Once a statement is processed, the shortfall amount is locked. Changing the Minimum Amount on the rate does NOT retroactively recalculate processed statements.
* **Flat is the default**. Switch to Prorated explicitly when you want partial-week scaling.

<img alt="" />

***

### Statement Bonus

**What it is:** A flat dollar bonus added unconditionally to every statement.

**When it applies:** One line item per statement.

**Inputs:**

* **Amount**: flat dollar bonus.

**How it calculates:**

```text theme={null}
Driver pay = Amount
```

**Use cases:**

* "Pay drivers an extra $50 per week as a retention bonus." Statement Bonus $50.
* Holiday or sign-on weekly bonus tied to a date range (combine with a rule to scope to weeks).

**Gotchas:**

* Statement Bonus is unconditional unless gated by a Statement Total Amount rule. If you want "bonus only when the driver clears \$2,000," add a rule like Statement Total Amount >= 2000.
* For one-time bonuses, use a manual New Transaction on the statement, not a recurring Statement Bonus rate.
* Statement Bonus is taxable income. If you need a non-taxable per-statement payment, use **Statement Per Diem** instead.

<img alt="" />

***

### Statement Per Diem

**What it is:** A flat dollar per diem added unconditionally to every statement, labeled as per diem on the statement so it can be flagged as non-taxable income in your accounting export. Functionally similar to Statement Bonus but with per-diem tax handling.

**When it applies:** One line item per statement.

**Inputs:**

* **Amount**: flat dollar per diem.

**How it calculates:**

```text theme={null}
Driver pay (per diem) = Amount
```

**Use cases:**

* Weekly per diem allowance paid every pay period regardless of trips run (e.g. \$100/week per diem for OTR drivers).
* Per diem tied to a specific pay period via a Statement Total Amount rule, e.g. only pay the per diem when the driver actually earned something on the statement (Statement Total Amount > 0).

**Gotchas:**

* Tax treatment is your accountant's call, not the system's. The system labels the line item as per diem and the accounting integration handles it from there.
* For per-day or per-mile per diems (rather than a flat per-statement amount), use **Daily Per Diem** or **Mileage Per Diem** instead.
* Statement Per Diem fires unconditionally per statement by default. Gate with a Statement Total Amount rule if you only want it to apply on statements above a threshold.

<img alt="" />

***

### Quick reference rate tables

For a one-screen scan, the three tables below summarize the same rates.

#### Trip rates

| UI name                   | Fires                | Key inputs                                                       |
| ------------------------- | -------------------- | ---------------------------------------------------------------- |
| Per Trip                  | Per trip             | Rate, tiers, Mileage Type (for tiers), Use Highest Tier checkbox |
| Per Load                  | On last trip of load | Rate                                                             |
| Loaded Miles              | Per trip             | Rate, tiers, Use Highest Tier checkbox                           |
| Empty Miles               | Per trip             | Rate, tiers, Use Highest Tier checkbox                           |
| Total Miles               | Per trip             | Rate, tiers, Use Highest Tier checkbox                           |
| Per Mile Deduction        | Per trip             | Rate, Mileage Type, tiers, Use Highest Tier checkbox             |
| Per Trip Stop             | Per trip             | Threshold, Rate, Flat Bonus                                      |
| Per Customer Stop         | On last trip of load | Threshold, Rate, Flat Bonus                                      |
| % of Trip Value           | Per trip             | Percentage                                                       |
| % of Line Haul            | Per trip             | Percentage                                                       |
| % of Trip Value Deduction | Per trip             | Percentage                                                       |
| % of Line Haul Deduction  | Per trip             | Percentage                                                       |
| % of Fuel Surcharge       | Per trip             | Percentage                                                       |
| Service Fee               | Per trip, last       | Percentage, Flat Fee                                             |

#### Statement rates

| UI name            | Fires         | Key inputs     |
| ------------------ | ------------- | -------------- |
| Minimum Pay        | Per statement | Minimum Amount |
| Statement Bonus    | Per statement | Amount         |
| Statement Per Diem | Per statement | Amount         |

#### Time-based pay rates

| UI name                        | Fires                                                  | Key inputs                                                    |
| ------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------- |
| Hourly Pay                     | Per trip leg                                           | Base Rate (uses Hours Worked field)                           |
| Overtime Threshold and OT Rate | Per trip leg, per day, or per statement (configurable) | Base Rate, Overtime Threshold, Overtime Rate, Threshold Basis |
| Mileage Per Diem               | Per trip leg                                           | Rate, Mileage Type, tiers, Use Highest Tier checkbox          |
| Daily Pay                      | Per selected day                                       | Rate                                                          |
| Daily Per Diem                 | Per selected per-diem day                              | Rate                                                          |

***

## Rules: deciding when a policy applies

Rules are optional. A policy with no rules always fires for every trip. Once you add rules, the policy only fires when the trip matches the conditions set.

### Rule structure

```text theme={null}
Policy   <br>-&gt; Rule Group A (rules joined by AND)      <br>   -&gt; Rule 1      <br>   -&gt; Rule 2      <br>   OR   <br>-&gt; Rule Group B (rules joined by AND)      <br>   -&gt; Rule 3
```

The groups are OR'd together. The rules inside a group are AND'd. So in the example above, the policy fires when **(Rule 1 AND Rule 2) OR (Rule 3)**.

<img alt="" />

<img alt="" />

### Operators

| Symbol     | Meaning                                                 |
| ---------- | ------------------------------------------------------- |
| =          | equals (for multi-select, "any selected value matches") |
| not equals | for multi-select, "none of the selected values match"   |
| >          | greater than                                            |
| >=         | greater than or equal                                   |
| \<         | less than                                               |
| \<=        | less than or equal                                      |

Most rules support = and not equals only. Statement Total Amount supports all six.

### Available rule subjects

| Subject                   | Entity              | Notes                                                                             |
| ------------------------- | ------------------- | --------------------------------------------------------------------------------- |
| Customer                  | Load                | Multi-select customers                                                            |
| Fleet                     | Load                | Multi-select fleets                                                               |
| Contract                  | Load                | Multi-select lane contracts                                                       |
| Load Custom References    | Load                | Tenant-defined custom references on the load (text, date, select, checkbox, etc.) |
| Tender As                 | Trip                | Multi-select subsidiaries                                                         |
| Equipment Type            | Trip                | Multi-select equipment types                                                      |
| Number of Drivers         | Trip                | Equal to 1 or 2                                                                   |
| Truck                     | Trip                | Multi-select trucks                                                               |
| Trip Custom References    | Trip                | Tenant-defined custom references on the trip                                      |
| Driver Attributes         | Trip                | Is Owner Operator, OO Driving Self, OO Using Own Trailer                          |
| Stop State                | Stop                | Multi-select states                                                               |
| Stop Zip                  | Stop                | Multi-select zip codes                                                            |
| Stop Custom References    | Stop                | Tenant-defined custom references on stops                                         |
| First Customer Stop State | First customer stop | Multi-select states                                                               |
| First Customer Stop Zip   | First customer stop | Multi-select zip codes                                                            |
| Last Customer Stop State  | Last customer stop  | Multi-select states                                                               |
| Last Customer Stop Zip    | Last customer stop  | Multi-select zip codes                                                            |
| Statement Total Amount    | Statement           | Dollar amount, all 6 operators                                                    |

### When rules are evaluated

Rule evaluation happens at the moment a driver payable is rebuilt for a trip. That happens when:

* The trip is created with a driver assigned.
* The driver is reassigned on the trip.
* The trip's miles, stops, equipment type, or any rule input changes.
* A rate policy on the driver is added, edited, or removed.
* A trip is reopened from a draft or reverted from a processed statement (the rate is re-evaluated against current rules and rate config).

**Forward-only behavior:** Rule changes apply to future evaluations only. Editing a rule on a policy does NOT retroactively re-compute payables that are already on **processed** statements. Payables in the Open list or on a Draft statement WILL re-compute on the next rebuild trigger

**Override precedence:** A trip-scoped policy on a load (set from the LDP) wins over the driver's profile policies for that specific trip. Rules on profile policies are skipped when a trip-scoped override has been finalized.

### What each rule actually means

Each rule looks at one specific piece of data on the trip, load, stop, driver, or statement, and decides whether the policy should fire. Each entry below covers: what it inspects, the data source, what happens when the field is empty, a realistic use case, and common pitfalls.

### Load-level rules

#### **Customer**

* **What it inspects:** the customer on the load (the company who tendered the freight, `Load.CustomerId` resolved to the customer name).
* **Null/empty behavior:** if the load has no customer (rare; most loads do), `=` never matches; `not equals` matches against every selected value.
* **Use case:** "Pay drivers an extra \$0.05 per loaded mile when running for Walmart." Customer = Walmart + a Loaded Miles rate at the bonus amount.
* **Common pitfalls:** the rule reads the customer on the LOAD, not the customer the driver was last dispatched to. Reassigning a load to a different customer re-fires evaluation and may flip which policies match. Also: the dropdown shows the customer's current name, not the name at the time the load was created. Customer renames propagate automatically.

#### **Fleet**

* **What it inspects:** the fleet the load was assigned to (the load-level Fleet field), NOT the driver's home fleet.
* **Null/empty behavior:** if the load has no fleet, an `=` rule never matches.
* **Use case:** "Drivers running our Dedicated Northeast fleet get a different per-mile rate." Fleet = Dedicated Northeast.
* **Common pitfalls:** confusing this with the driver's fleet. To gate on the driver's fleet instead, use the Driver Rate Plans driver segment (see below). The trip-level Fleet rule is for load-bound dispatch decisions, not driver characteristics.

#### **Contract**

* **What it inspects:** the lane contract on the load (the `Load.LaneContractId`). Only relevant if your tenant uses lane contracts.
* **Null/empty behavior:** loads with no contract never match an `=` rule.
* **Use case:** "Loads on the Acme Beverage contract pay 80% of line haul to the OO; everything else pays 75%." Gate the 80% policy on Contract = Acme Beverage. The 75% policy needs to also be gated on Contract `not equals` Acme Beverage, otherwise it stacks on top of the 80% policy (additive).
* **Common pitfalls:** policies stack additively, so the "everything else" companion policy needs an explicit `not equals` rule. Forgetting this is the #1 source of double-paying tenants who configured an exception policy and a default policy without making them mutually exclusive.

#### **Load Custom Reference**

* **What it inspects:** the value of a tenant-defined custom reference on the load. Custom references you have configured on loads (text, date, select, checkbox, multi-select) show up in the rule's dropdown.
* **Null/empty behavior:** loads without a value set never match an `=` rule; they match a `not equals` rule.
* **Use case:** Tenant has a "Customer Tier" custom reference on loads with values Gold / Silver / Bronze. Pay a percentage bonus on Gold tier loads.
* **Common pitfalls:** changing the custom reference value on a load re-fires evaluation of any rules that reference it. Plan ahead if you back-fill custom references on historical loads — only open and draft payables recompute; processed statements stay locked.

### Trip-level rules

#### **Tender As (Subsidiary)**

* **What it inspects:** which subsidiary tendered the trip (`Trip.TenderAsSubsidiaryId`). Set per trip leg, since different legs of the same load can bill under different LLCs.
* **Null/empty behavior:** trips without a Tender As never match an `=` rule. Almost every active trip in production has Tender As set.
* **Use case:** "Our California subsidiary pays $24/hr; the Texas subsidiary pays $20/hr." Two policies, each gated on Tender As.
* **Common pitfalls:** Tender As is per trip leg, not per load. A two-leg load can tender as different subsidiaries on each leg. If your driver is paid the same regardless of who tenders, do not add this rule — it adds maintenance overhead without changing pay.

#### **Equipment Type**

* **What it inspects:** the equipment type configured on the trip (Reefer, Dry Van, Flatbed, Tanker, etc.), from the trip's Equipment Type field.
* **Null/empty behavior:** trips without an equipment type fall through.
* **Use case:** "$0.60/mile when running reefer, $0.50/mile on dry van." Two policies, each gated on Equipment Type.
* **Common pitfalls:** the system does NOT know whether a reefer unit was actually running vs. idle. You can pay "reefer rate" for a trip where the reefer was off if the trip's equipment type is set to Reefer. If you need finer control ("reefer on vs off"), today the workaround is to change the trip's equipment type at assignment time or pay the higher rate and adjust manually.

#### **Number of Drivers**

* **What it inspects:** the count of drivers assigned to the trip: 1 (solo) or 2 (team). Only `=` is supported.
* **Null/empty behavior:** trips without an assigned driver are not evaluated for any rate at all (they have no payable yet).
* **Use case:** "Team drivers each get $0.30/mile instead of the solo $0.55." Solo policy gated on Number of Drivers = 1; team policy gated on Number of Drivers = 2.
* **Common pitfalls:** the team driver each gets the full rate value (it does not auto-split). If you want a true split, configure the team rate at half the solo amount.

#### **Truck**

* **What it inspects:** the truck (`Trip.TruckId`) assigned to the trip.
* **Null/empty behavior:** trips without a truck do not match. Rare in production.
* **Use case:** a tenant who pays a different rate when a specific premium truck is used (e.g. a tanker truck with bonus pay). Truck = the specific truck IDs.
* **Common pitfalls:** truck-level rules are brittle. Adding a new premium truck means updating every policy that references the truck list. Most tenants are better off using Equipment Type or a Driver Rate Plan segment based on Fleet or Truck Type instead.

#### **Driver Attributes on a Trip**

* **What it inspects:** properties on the driver record. The three checkable values are:

  * **Is Owner Operator**: the driver is an OO, not a company driver. Reads `Driver.IsOwnerOperator`.
  * **OO Driving Self**: the OO is the one driving the truck (vs an OO who owns the truck but assigns a different driver). Reads `Driver.OOIsDrivingSelf`.
  * **OO Using Own Trailer**: the OO is hauling their own trailer, not a company trailer. Reads `Driver.OOIsUsingOwnTrailer`.
* **Null/empty behavior:** unset boolean defaults to false. An `=` rule selecting "Is Owner Operator = true" never matches company drivers (who have IsOwnerOperator = false or unset).
* **Use case 1:** "Owner operators get % of line haul; company drivers get per mile." OO policy gated on Driver Attributes = Is Owner Operator.
* **Use case 2:** "If the OO is using their own trailer, they get an extra 5% of line haul." Stack a second OO policy with Driver Attributes = OO Using Own Trailer on top of the base OO policy. Both policies will fire and contribute additive line items.
* **Common pitfalls:** Driver Attributes is the only **driver-side** rule on policies (vs all the others which look at the trip/load). For more driver-side filtering options (Fleet, Subsidiary, Tenure, Type, custom references), use **Driver Rate Plans** with a Driver Segment (see the Driver Rate Plans section below).

#### **Trip Custom Reference**

* **What it inspects:** the value of a tenant-defined custom reference on the trip. Whatever custom references you have set up on trips (text, date, select, checkbox, multi-select) show up in the rule's dropdown.
* **Null/empty behavior:** trips that do not have the custom reference set never match an `=` rule against a specific value; they match a `not equals` rule (the value isn't in the selected set).
* **Use case:** Tenant uses a "Service Level" custom reference on trips with values like Premium / Standard / Economy. Pay drivers a bonus rate when Service Level = Premium.
* **Common pitfalls:** the rule reads the trip's current value of the custom reference. Editing the value after the trip has delivered triggers re-evaluation (open and draft items recompute; processed statements are locked).
* **Note:** trip custom references are distinct from driver custom references (which power Driver Rate Plan segments). Both can be defined per tenant; they apply to different entities.

### Stop-level rules

These look at the stops on the trip. They are useful for state-specific or zip-specific premiums.

#### **Stop State**

* **What it inspects:** at least one stop on the trip has a state matching one of the selected states. "Any stop" includes pickup, delivery, intermediate, fuel, and yard stops.
* **Null/empty behavior:** trips with no stops match no `=` rule and match every `not equals` rule.
* **Use case:** "Pay $50 extra anytime the trip touches NY or NJ." Per Trip $50 rate gated on Stop State = NY, NJ.
* **Common pitfalls:** the rule fires if ANY stop is in the state, not just customer stops. A fuel stop in NY would also trigger it. Use **First Customer Stop State** or **Last Customer Stop State** if you want to scope to origin/destination only.

#### **Stop Zip**

* **What it inspects:** at least one stop on the trip has a zip code matching one of the selected zips. Same scope as Stop State (all stop types).
* **Null/empty behavior:** stops without zips do not match. Some EDI-tendered loads may have zip-less stops.
* **Use case:** "Pay \$100 extra for stops in NYC five-boroughs zip codes" with a zip list.
* **Common pitfalls:** zips are matched exactly. "10001" and "10001-0001" are different strings; if your zips include +4 extensions you need to enumerate or use a different mechanism.

#### **Stop Custom Reference**

* **What it inspects:** the value of a tenant-defined custom reference on any stop of the trip. Like the standard Stop State / Stop Zip rules, the match fires if ANY stop on the trip has a matching value.
* **Null/empty behavior:** stops without the custom reference set are skipped during evaluation. Trips with no matching stop do not satisfy an `=` rule.
* **Use case:** Tenant tags stops with a "Stop Type" custom reference (Drop Trailer / Live Unload / Hook & Drop). Pay an extra per-stop bonus when at least one stop is Live Unload.
* **Common pitfalls:** Stop Custom Reference behaves like Stop State — it scans every stop on the trip, including yard moves and fuel stops, not just customer stops. If you only care about customer stops, today there is no first/last-customer-stop variant of this rule. Set the custom reference on the right stop types at dispatch time.

#### **First Customer Stop State** and **First Customer Stop Zip**

* **What they inspect:** the very first **customer** stop on the load (origin pickup). Customer stops are stops typed as a customer pickup/delivery, not yard moves or fuel stops.
* **Scope:** load-level, not trip-level. On a multi-trip load, the same first-stop value applies to every trip.
* **Null/empty behavior:** loads with no customer stops do not match.
* **Use case:** "Loads originating in California get a different rate" to cover higher idle / fuel cost. First Customer Stop State = CA.
* **Common pitfalls:** if a load is restructured (stops reordered, a new first customer stop added), the rule re-evaluates. Avoid baking last-mile detail into rules that may change post-dispatch.

#### **Last Customer Stop State** and **Last Customer Stop Zip**

* **What they inspect:** the very last **customer** stop on the load (final delivery).
* **Scope:** load-level. Same value across all trips of the load.
* **Null/empty behavior:** loads with no customer stops do not match.
* **Use case:** "Loads delivering into the Northeast get a \$200 layover bonus." Last Customer Stop State = NY, NJ, PA, CT, MA, RI.
* **Common pitfalls:** confusing this with Stop State (any stop). Stop State fires on intermediate stops too; First/Last Customer is locked to origin and destination of the whole load.

The First / Last variants differ from the generic Stop State / Stop Zip in two important ways:

1. They only look at **customer** stops (not yard moves, fuel stops, or relays).
2. They only look at the **single first or last** stop on the load, not at every stop.

If you want "the load ever passes through CA," use Stop State. If you want "the load originated in CA," use First Customer Stop State. If you want "the load delivers in CA," use Last Customer Stop State.

### Statement-level rule

#### **Statement Total Amount**

* **What it inspects:** the running statement subtotal in dollars, after Trip and Time-based pay rates have computed but before this Statement-category rate fires. This is the only rule whose input is **derived** from other rate output, not from the trip/load.
* **Operators:** all six (`=`, `not equals`, `>`, `>=`, `&lt;`, `&lt;=`). The only rule that supports the full numeric comparison set.
* **Null/empty behavior:** an empty statement has a subtotal of 0; rules like `&lt; 1000` will match.
* **Use case 1:** "Give a $200 weekly bonus if the driver clears $2,000 in a week." Statement-category policy with Statement Total Amount >= 2000 and a Bonus rate of \$200.
* **Use case 2:** Conditional minimum pay: "Pay a flat $50 supplement only if the statement is under $800." Statement Total Amount \< 800 with a \$50 Bonus. Note: the Minimum Pay rate type is usually a cleaner choice for floor logic.
* **Common pitfalls:**

  * This rule only applies to Statement-category rates (Bonus, Minimum Pay), since a Statement rate's own policy cannot contain Trip or Time-based pay rates anyway.
  * The threshold is checked **once per statement** at the moment Statement-category rates fire. It does not iterate or apply tiers — the rule passes or fails, and the rate runs or doesn't.
  * If you stack multiple Statement-category policies with overlapping Statement Total Amount rules, the order of evaluation can affect the result. Test before relying on stacked bonuses.

***

## Driver Rate Plans

A **Driver Rate Plan** is a reusable template that bundles rates, optional trip-level rules, and a driver segment together. Plans let you define a pay structure once and assign it to a group of drivers automatically based on driver attributes, instead of editing every driver's profile by hand.

### Plans vs profile policies

A driver can be paid through two complementary mechanisms:

* **Profile policies**: rate policies set directly on a single driver profile. Best for one-off customizations.
* **Rate plans**: workspace-level templates that apply to many drivers via a driver segment. Best for shared pay structures (e.g. "all owner operators in the Northeast," "all company drivers past 90 days of tenure").

Both coexist. A driver may receive rates from profile policies, from one or more plans, or from any combination. All matching rates contribute additively to each statement.

### Anatomy of a plan

A plan has four pieces:

1. **Plan details:** Name (required, unique across plans and policies) and Description.
2. **Driver segment** (required): one or more rules that decide which drivers this plan applies to. The segment is the answer to "who gets this plan?"
3. **Rates** (required): one or more rate types, same as profile policies. Same category constraint applies: Statement rates cannot share a plan with Trip or Time-based pay rates. Trip and Time-based pay rates can coexist in one plan.
4. **Rules** (optional): trip-level rules that decide WHEN the rates apply for a matched driver. Same rule subjects as profile policies (Customer, Fleet, Equipment Type, Stop State, etc.). Optional because some plans should always apply to any trip the matched drivers run.

The right-side sidebar of the plan editor shows the live count of drivers the segment currently matches ("X out of Y drivers") so you can verify before saving.

<img alt="" />

<img alt="" />

### Driver segment: who gets the plan

The segment is the new piece. It uses **driver-attribute** filters (not trip/load fields like the regular rules). Each segment attribute reads a field on the driver record.

### Segment attributes

| Attribute                    | Reads                                                | Operators                                     | Notes                                                                                                                            |
| ---------------------------- | ---------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Fleet**                    | Driver's home fleet                                  | `=`, `not equals`                             | Multi-select                                                                                                                     |
| **Subsidiary**               | Driver's home subsidiary                             | `=`, `not equals`                             | Multi-select                                                                                                                     |
| **Tenure (days)**            | Days since driver's hire date                        | `=`, `not equals`, `>`, `>=`, `&lt;`, `&lt;=` | Computed from `Driver.HireDate`. Re-evaluated daily so drivers automatically pick up or lose plans as tenure crosses thresholds. |
| **Type**                     | Driver type (Company Driver, Owner Operator, etc.)   | `=`, `not equals`                             | Multi-select                                                                                                                     |
| **Custom driver references** | Custom fields you have defined on the driver profile | `=`, `not equals`                             | All driver custom references show up in the dropdown (text, date, select, checkbox, color, etc.).                                |

<img alt="" />

### Segment groups: include / exclude with AND / OR

The segment uses the same group structure as trip rules: rules inside a group are joined with **AND**, groups are joined with **OR**.

Example: "all OO drivers in the Northeast fleet who have been with us for at least 90 days, OR all OO drivers in the Texas subsidiary regardless of tenure":

```text theme={null}
Include Group 1:   Type = Owner Operator AND   Fleet = Northeast AND   Tenure (days) &gt;= 90  Include Group 2:   Type = Owner Operator AND   Subsidiary = Texas LLC
```

The "Include" / "Exclude" wording on the segment maps to `=` and `not equals` semantically.

**At least one rule is required.** A plan cannot be saved with an empty segment, since that would apply to every driver.

### Stacking and additive evaluation

Drivers can match multiple plans. Every matching plan's rates fire for every trip that matches that plan's rules. There is **no de-duplication and no priority**.

Example. A driver matches three plans:

* Plan A (matched by Type = Owner Operator): % of Line Haul 75%.
* Plan B (matched by Fleet = Northeast): Per Trip Stop \$25.
* Plan C (matched by Tenure (days) >= 365): Bonus \$50 per statement.

For every trip that driver delivers, the line haul percentage fires (Plan A), the per-stop fires (Plan B), and each statement gets the bonus (Plan C). If two plans both define a 75% line haul rate, the driver gets 150% of line haul. Design segments so plans complement each other rather than duplicate.

### Forward-looking application

Rate Plan changes do not retroactively recompute statements that have already been processed. Open and draft trips re-evaluate on their next rebuild; processed statements are locked.

This means:

* Editing a plan does not change historical payouts.
* A driver gaining a plan via segment match does not generate back pay for prior trips.
* A driver losing a plan (e.g. via fleet change) does not claw back already-processed pay.

### Daily re-evaluation for silent attribute changes

Some driver attributes change without an explicit event — the most important being **Tenure (days)**, which silently increments every day at midnight. A daily job re-evaluates plan segment matches for every driver, so a driver crossing the 90-day tenure threshold automatically picks up the plan that gates on tenure.

Manual events (driver edits, plan edits, fleet / subsidiary / type changes) also trigger immediate re-evaluation.

### Driver Profile: Assigned Plans

On the driver profile, the Rates section shows an **Assigned Plans** list of every plan currently applied to this driver, with:

* The plan name and brief description.
* The reason it applies (which segment rule matched).
* A deep link to the plan settings page (permission-gated).

This is the canonical place to answer "why is this driver getting this rate?"

### Permissions

* **Partner Admin, Admin, Biller**: can view, create, edit, archive plans, and edit a driver's assigned plan settings.
* All other roles: read-only or hidden, depending on the View Driver Rate / Edit Driver Rate permissions.

### How plans interact with profile policies

**There is no precedence between plans and profile policies.** If a driver has a profile policy AND a matching plan that both define a 75% line haul rate, both fire and the driver gets 150%. Keep each pay component defined in exactly one place — either on the profile or in a plan, not both.

***

## Trip-scoped overrides

A user can edit a rate on a specific trip from the Load Detail Page (LDP). This creates a **trip-scoped policy** that overrides the driver's profile policy for that one trip.

State a trip-scoped policy can be in:

| State         | Meaning                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Draft**     | The override is on a draft statement. Profile policies cannot replace it until the draft is reverted.                                             |
| **Finalized** | The override has shipped on a processed statement. The trip's rates are locked. No further rate changes are allowed on that driver for that trip. |

If a trip has any finalized scoped policy, the driver's profile policies for that trip are completely ignored. Only the scoped policies show.

Trip-scoped policies can also be **custom** (named "Custom Rate"), with no underlying profile policy. These are ad hoc one-time rates for a single trip.


# Driver settlements
Source: https://docs.alvys.com/en/help/accounting-settlements/driver-settlements

Set up pay periods and driver rates, generate statements, and resolve the questions that come up on the first settlement run.

Driver settlements (also called driver pay, driver payroll, paystubs, or pay statements) turns delivered trips, rates, and deductions into a pay statement you can review, share, and sync to your accounting system. Statements are built from the **driver rates** configured on each driver's profile and are scoped by **pay periods**. The module supports statement drafts, bulk approval and generation, and direct integration with external accounting systems.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="Alvys Driver Settlements training" />

[Open the recording](https://drive.google.com/file/d/1Wl7I0bXBad3bUs0Dx8IGkaI9F8ZRwMih/view)

## Where to find it

Go to **Accounting → Driver Settlements**. The module has three tabs:

| Tab            | What it shows                                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Open**       | Unpaid transactions for all drivers. Use the **Show All Drivers** toggle to include drivers without current activity. |
| **Drafts**     | Drivers with at least one approved payable item sitting in a draft statement.                                         |
| **Statements** | Completed statements, synced to your accounting system.                                                               |

<Warning>
  **Driver not appearing in settlements?** Confirm the driver's profile was created as a **Company Driver** or **Owner Operator** — not as an **External Carrier**. Drivers created as External Carriers never appear in Driver Settlements. Then confirm the driver has been assigned to a pay period in **Settings → Pay Periods**.
</Warning>

## First-time setup checklist

If you are new to Driver Settlements, complete these in order before generating your first statement. Each step is covered in detail below.

1. **Create a pay period** in **Settings → Pay Periods**, set the frequency, and assign the drivers paid on that schedule.
2. **Configure driver rates** on each driver's profile, or assign a rate plan.
3. **Check the Open tab.** Delivered trips appear once a driver has both a pay period and a rate.
4. **Approve payable items** to move the driver into Drafts.
5. **Review the draft** — preview amounts, add notes, share with the driver.
6. **Generate the statement.** It moves to the Statements tab and is emailed to the driver if email delivery is configured.

## Key concepts

**Pay period** — the time window and frequency for a driver pay run. Every driver must be assigned to a pay period before a statement can be generated for them.

**Driver rates** — the policies that determine how a driver is compensated. Rates live on the driver's profile and can carry optional rules that restrict when they apply.

**Statement draft** — a working statement you can edit, preview, annotate, and share with the driver before finalizing. Drafts let you review pay across many drivers before committing.

## Set up a pay period

1. Go to **Settings → Pay Periods**.
2. Click **+ New Pay Period**.
3. Enter a name for the pay period.
4. Assign it to specific drivers, a fleet, or **All Drivers**.
5. Select the frequency: **Daily** or **Weekly**.
6. For **Weekly**, select the starting day of the week.
7. Save the pay period.

<Note>
  Drivers do not see the pay period name. Their statement shows only the **Statement Date**.
</Note>

## Configure driver rates

Driver rates are managed from the individual driver's profile.

1. Open the driver's profile from **Drivers**.
2. Scroll to the **Rates** section. Existing rates are listed here and can be edited or deleted from the three-dot menu on each rate row.
3. Click **+ Add Rates**.
4. Enter a name for the rate and select a rate type.
5. Enter the rate amount.
6. Optionally add a rule to restrict when the rate applies.
7. Click **Save**.

Supported rate types include Empty Mileage, Loaded Mileage, Total Mileage, Per Stop, Per Trip, % Of Trip Value, Statement Bonus, Minimum Pay, and the time-based rates (Hourly Pay, Daily Pay, Daily Per Diem, Mileage Per Diem).

### Rate rules

Rules restrict when a rate applies:

* **Load-level rules** restrict by customer — the rate applies only when the trip is for that customer.
* **Trip-level rules** restrict by conditions such as **Number of Drivers** or **Equipment Type**.
* **Rule groups** combine conditions with OR logic, so the rate applies when any one condition in the group is met.

<Tip>
  For the full catalogue of rate types, every rule subject and operator, and worked examples, see [Driver rates, rules, and plans](/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex).
</Tip>

## Rate plans: the current model

**Driver Rate Plans** are reusable templates that bundle rates, optional trip rules, and a driver segment. They replace the older per-driver-only approach where every pay structure had to be re-entered on each driver profile. Plans and profile rates coexist — a driver can be paid from profile rates, from one or more plans, or from any combination, and all matching rates contribute additively to the statement.

To create a rate plan:

1. Click your account name in the bottom-left corner and select **Settings**.
2. Under **General**, open **Driver Settlements** settings.
3. Go to the **Rate Plans** section and click **New Rate Plan**.
4. **Define the driver segment** — the rules that decide which drivers receive the plan. Segments can key off driver attributes such as fleet, subsidiary, terminal, driver type, tenure, or individually selected drivers, depending on what is enabled in your account.
5. **Review the matching drivers** in the preview list to confirm the plan hits the right population before saving.
6. Click **Save**.
7. **Confirm the plan applied.** Matching drivers pick the plan up automatically; open a driver profile and check the **Rates** section to see the assigned plan.

<Warning>
  Plans stack with no de-duplication and no priority. If two plans both grant a 75% line haul rate to the same driver, that driver is paid 150% of line haul. Design segments so plans complement rather than duplicate each other.
</Warning>

<Note>
  Rate plan changes are forward-looking. Editing a plan does not recompute statements that have already been processed, and a driver newly matching a plan does not receive back pay for prior trips.
</Note>

## Generate a statement

### 1. Approve payable items

1. Go to **Accounting → Driver Settlements**.
2. In the **Open** tab, click a driver's name to open their transaction view.
3. Review the listed transactions. Click any trip to expand its line-item breakdown.
4. Select the items to include using the checkboxes.
5. Choose the **Pay Period** for this statement.
6. Click **Approve**. The driver now appears in the **Drafts** tab.

### 2. Add deductions, cash advances, and other transactions

For anything not generated automatically from a trip:

1. Click **New Transaction** on the driver's settlement view.
2. Select the transaction types to add (deductions, reimbursements, bonuses, and so on).
3. Enter the amount. Enter `$0.00` as a placeholder for a transaction you will fill in later.
4. Save.

### 3. Review the draft

From the **Drafts** tab, select a driver and open their draft. Use the **Pay Period** selector to scope which transactions appear. From the draft you can:

* Add transactions.
* Add **Statement Notes**, which appear on the generated statement.
* Add **Internal Notes**, which are internal only and never visible to the driver.
* Set the **Statement Date**.
* Preview the statement.
* Share the draft with the driver by email.

### 4. Generate

1. From the draft, click **Generate Statement**.
2. The completed statement moves to the **Statements** tab.
3. From there you can download it as a PDF or email it to the driver.

<Warning>
  Generating a statement does not move funds. Alvys creates the pay record; the driver receives it by email (if configured) and can view it in the Alvys Driver App. Payment itself happens in your accounting system or payroll provider.
</Warning>

Once generated, a statement is locked. Click **Revert Statement** to return it to draft status for editing. Reverting requires the **Revert Driver Statement** permission — see [Who can revert a statement](#who-can-revert-a-statement).

<Tip>
  The layout of amounts and line items on the generated statement comes from the **Statements Layout** setting in your company profile. See [Paystub layout templates](/en/help/accounting-settlements/paystub-layout-templates).
</Tip>

## Who can revert a statement

Reverting a generated statement back to draft is controlled by its own permission, **Revert Driver Statement**, set per user profile. It is enabled by default for the **Admin**, **Partner Admin**, and **Biller** roles.

If you do not have the permission, the **Revert statement** button appears disabled, and hovering over it shows a **Permission required** tooltip. Ask an administrator to grant the permission if you need it.

To change who can revert statements:

<Steps>
  <Step title="Open User Settings">
    Go to **User Settings**.
  </Step>

  <Step title="Select the profile">
    Select the user profile you want to change.
  </Step>

  <Step title="Set the permission">
    Select or clear **Revert Driver Statement**, then save. Clearing it leaves the rest of that user's settlement access untouched — they can still open and review statements, they just cannot revert one.
  </Step>
</Steps>

## Bulk workflows

**Bulk generate** — select multiple drivers in the **Drafts** tab and generate all their statements in one action.

**Bulk share** — in the **Statements** tab, select the statements you want to send and click **Share**. Each statement is emailed to that driver's configured email address.

## Paying owner operators

1. In the **Open** tab, open the entity dropdown and select **Owner Operator**.
2. The **Drivers** column shows the drivers associated with each owner operator.
3. Separate **Owner Operator Linehaul** and **Driver Linehaul** columns let you review each side independently.

To pay an owner operator at the truck rather than the driver, see [Truck statements for owner-operators](/en/help/accounting-settlements/how-to-generate-truck-statements-for-owner-operators).

## Permissions

Driver Settlements is available to users with the **Admin** or **Payroll Clerk** role. Permissions are assigned per user in **Settings → Organization → Users**.

| Permission                  | Grants                                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| **Pay Driver**              | Access to the Driver Settlements module and the ability to process driver pay.                     |
| **Edit Paystubs**           | Generating, editing, and reverting statements.                                                     |
| **Revert Driver Statement** | Returning a generated statement to draft. Enabled by default for Admin, Partner Admin, and Biller. |
| **View Pay Plans**          | Viewing driver and owner operator rate plans.                                                      |
| **Edit Pay Plans**          | Creating, modifying, and deleting rate plan templates.                                             |

Pay period configuration lives in **Settings → Pay Periods**. Driver rate configuration lives on each driver's profile under **Drivers**. Taxes are hidden from the settlements view unless the driver is configured as a W-2 employee.

## Troubleshooting

**A load is not showing up in Driver Settlements.** Work through these in order:

* It is already in a draft or a statement — check the **Drafts** and **Statements** tabs.
* The driver is not assigned to a pay period, or the pay period date range does not include the load's delivery date.
* The entity filter is set to **Driver** when the load sits under an **Owner Operator**, or the reverse.
* The load is classified as **Brokerage**. Brokerage loads do not generate driver payables; change the classification to trigger the Money Box.
* No rate applied to the load — open the driver profile and confirm a rate or rate plan is in place.

If you can see a bill in QuickBooks for the load but nothing appears in Driver Settlements, the driver rate likely did not apply. Contact Alvys Support and share the load number.

**The Revert statement button is disabled and shows "Permission required".** Your user profile does not have the **Revert Driver Statement** permission. An administrator can grant it in **User Settings**. See [Who can revert a statement](#who-can-revert-a-statement).

**A statement is stuck in Queued status.** Queued means Alvys is still generating it, and while queued it is locked — you cannot download, share, or revert it. Wait a few minutes and refresh; it should move to Processed. If it stays Queued for more than 30–45 minutes, contact Alvys Support with the statement number.

**A driver is missing from the Drafts tab.** Drivers only reach Drafts after you approve their payable items in the **Open** tab. If a statement was generated and then reverted all the way to Open rather than to Draft, every item returns to the **Open** tab — look there.

**An inactive driver still appears in Driver Settlements.** Inactive drivers show up while they have outstanding payables. Clear the payables to remove them. To make inactive drivers visible on purpose, go to **Settings → Company Profile**, find the Driver Settlements / Driver Statement Settings section, enable **Show inactive drivers with open payables**, then refresh **Accounting → Driver Settlements → Open**.

## FAQ

<AccordionGroup>
  <Accordion title="Can I generate a statement for a driver with no pay period assigned?">
    No. Every driver must be assigned to a pay period first.
  </Accordion>

  <Accordion title="Why do a driver's $0 trips not appear on the statement?">
    Two settings in **Settings → Company Profile** control this: **Enable Trips with \$0 Payables to display in settlements** and **Enable Trips with no Payables to display in settlements**. Toggle them to control whether zero-pay and no-pay trips flow onto driver statements.
  </Accordion>

  <Accordion title="How do I correct miles if the dispatcher entered them wrong?">
    Click directly on the miles cell for the trip in the Driver Settlements table and edit the value. The statement recalculates automatically.
  </Accordion>

  <Accordion title="How do I edit the trip value?">
    Use the three-dot menu on the right side of the trips table and select the edit option, or click the trip value cell and edit it inline. Percentage-based driver pay recalculates from the updated value.
  </Accordion>

  <Accordion title="How do I filter trips by date?">
    In the **Open** tab, set the **Cutoff Date**. Trips delivered after that date are hidden from the view.
  </Accordion>

  <Accordion title="Can I pin or hide columns?">
    Yes. Right-click any column header and choose **Pin column to the left** or **Pin column to the right**. Choose **Configure Columns** to show or hide columns. Column layouts save per user.
  </Accordion>

  <Accordion title="Why is the Revert statement button greyed out for me?">
    Your user profile does not have the **Revert Driver Statement** permission. Hovering over the button shows a **Permission required** tooltip. An administrator can grant the permission in **User Settings**.
  </Accordion>

  <Accordion title="I reverted a statement by mistake — can I recover it?">
    Reverted statements are not retained after reversal. Use **Revert to Draft** rather than reverting to Open; that keeps the statement intact so you can regenerate it.
  </Accordion>

  <Accordion title="What happens if I revert a statement already sent to my accounting system?">
    The behaviour differs by accounting platform. Contact Alvys Support with your platform for the exact result.
  </Accordion>

  <Accordion title="Do statements sync to QuickBooks?">
    Owner operator statements sync to QuickBooks. Company driver statements require a QuickBooks Payroll integration, which is not currently supported.
  </Accordion>

  <Accordion title="How do I show a company name instead of the driver's personal name on the statement?">
    Open the driver's profile and go to **Tax Information**. Enter the Tax Identification Number, then set **Tax Category** to **1099**. Once both are filled in, the **Company Name** field becomes available — enter the company name and save. The company name then appears as the payee with the driver's name below it. If the statement is already generated, click **Revert Statement** first, then regenerate.
  </Accordion>

  <Accordion title="Is Driver Settlements a paid add-on?">
    No. Driver Settlements is included in your existing Alvys subscription at no additional cost.
  </Accordion>
</AccordionGroup>

## Related articles

<CardGroup>
  <Card title="Driver rates, rules, and plans" icon="calculator" href="/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex">
    How rates, policies, and rules produce line items on a statement.
  </Card>

  <Card title="Driver Settlements FAQ" icon="circle-question" href="/en/help/accounting-settlements/driver-settlements-faq">
    Pay periods, deductions, reversals, and the first-run questions from the settlements webinar.
  </Card>

  <Card title="Time-based pay" icon="clock" href="/en/help/accounting-settlements/time-based-pay-in-driver-settlements">
    Hourly, daily, and per diem pay inside Driver Settlements.
  </Card>

  <Card title="Truck statements for owner-operators" icon="file-invoice" href="/en/help/accounting-settlements/how-to-generate-truck-statements-for-owner-operators">
    Generate a statement at the truck when you pay an owner-operator that way.
  </Card>

  <Card title="Balance-based deductions" icon="minus" href="/en/help/accounting-settlements/how-to-set-up-balance-based-deductions">
    Recurring deductions that draw down a balance across statements.
  </Card>

  <Card title="Escrow accounts" icon="vault" href="/en/help/accounting-settlements/escrow-accounts">
    Hold and release escrow as part of driver pay.
  </Card>

  <Card title="Paystub layout templates" icon="table" href="/en/help/accounting-settlements/paystub-layout-templates">
    Control what appears on the statement you send the driver.
  </Card>
</CardGroup>


# Driver Settlements FAQ
Source: https://docs.alvys.com/en/help/accounting-settlements/driver-settlements-faq

Answers to common driver settlements questions from the Alvys webinar, covering pay periods, rates, deductions, statement generation, and reversals.

Consolidated answers to the most common questions (FAQ, common issues) from the Driver Settlements webinar, organized by topic. Covers pay periods, driver rates, deductions, trips, statement generation, reversals, accounting integration, and more.

## Overview

This article consolidates the most common questions received during the [Get Started with Driver Settlements: From First Pay Period to Truck-Based Statements](https://youtu.be/lD1Vqpuq15o) webinar, organized by topic so you can jump to what you need. If you do not find your answer here, reach out to [support@alvys.com](mailto:support@alvys.com).

<Tip>
  For the full setup walkthrough — pay periods, driver rates, rate plans, the approve-to-generate workflow, permissions, and troubleshooting — see [Driver settlements](/en/help/accounting-settlements/driver-settlements). This page covers the questions that come up around that workflow.
</Tip>

## Before you generate statements

Before creating a settlement run, confirm:

* The driver is assigned to a pay period.
* The driver has the correct active rate configured.
* Trips are in **Delivered** status.
* Mileage, trip value, and delivery dates are correct.
* Any one-time or recurring deductions have been added before generating the statement.
* If using truck-based statements, the deduction or transaction is tied to the correct truck.
* The user has the required **Pay Driver** or **Pay Owner Operator** permission.

## FAQs

### Pay periods

**Q: How do I set up a pay period?**

**A:** Go to **Settings → Pay Periods** and create or edit your schedule. If you choose **Weekly** with a start day (for example, Monday), the period runs from that day at 00:00 through the following Sunday at 23:59. The default **Statement Date** is the last day of the period. When you generate a statement, you can override the **Statement Date** for that run, so you can pay every Friday for the prior Monday to Sunday period. See [Driver settlements](/en/help/accounting-settlements/driver-settlements) for full setup steps.

**Q: Why does the pay period default to the current week instead of the previous week?**

**A:** The pay period selector currently defaults to the current week. Defaulting to the previous week is on the roadmap. For now, manually select the prior week when generating each settlement run.

**Q: Can I bulk-select pay periods or pay dates when generating statements?**

**A:** Not yet. Today you select a pay period per run. Bulk selection is on the roadmap.

**Q: Can drivers see the pay period on their statement?**

**A:** No. Drivers only see the **Statement Date** on their statement, not the pay period name.

**Q: Can I reuse or duplicate an existing pay period for one driver?**

**A:** No. Existing pay periods cannot be reused or duplicated for a single driver. If one driver needs a separate version of a pay period, create a new pay period with the same dates or schedule details, then assign only that driver to the new pay period.

Use this workaround when a driver needs to be settled separately without changing the pay period assigned to other drivers.

**Q: Can I generate a statement for a driver without assigning them to a pay period?**

**A:** No. Every driver must be assigned to a pay period before a statement can be generated for them.

### Driver rates

**Q: Can I set tiered rates based on miles driven per pay period?**

**A:** Tiered rates that apply per pay period (for example, one rate for the first 2,000 miles in a statement, a different rate over 2,000) are on the roadmap. Today, tiered rates can only be applied per trip.

**Q: Can I set tiered rates based on miles driven per trip?**

**A:** Yes. Create a driver rate of type **Per Mile**, enable tiers, and configure each tier with its own rate (for example, 0 to 2,999 miles at one rate; 3,000 or more miles at another). See [Driver settlements](/en/help/accounting-settlements/driver-settlements) for rate setup steps.

**Q: Can I pay a mileage bonus on tiers?**

**A:** Yes. Create a driver rate of type **Per Mile**, enable tiers, and name it "Mileage Bonus." Each tier can have its own rate.

**Q: Can I set different rates for different contracts?**

**A:** Yes. When creating a driver rate, click **Add Rule**, choose **Load → Contract**, and multi-select the contracts the rate should apply to. Multiple contract-specific rules can be stacked on the same driver.

**Q: Are pay tiers based on years of employment supported?**

**A:** Tenure-based pay tiers (for example, one rate for years 1 to 3 and a higher rate for years 4 to 6) are on the roadmap.

**Q: Can I pay a recurring bonus based on revenue generated?**

**A:** Driver rates based on revenue thresholds are not supported today. This has been logged as a feature request.

**Q: Why is a trip, load, or item missing from Driver Settlements?**

**A:** Use this table to narrow down the cause.

| Issue                       | Most likely causes                                                          | What to check                                                      |
| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Driver is missing           | No pay period, inactive driver, no eligible delivered trips                 | Driver status, pay period assignment, Open tab, delivered trips    |
| Trip is missing             | Trip not delivered, outside cutoff/pay period, \$0/no-pay settings disabled | Trip status, delivery date, cutoff date, company profile settings  |
| Deduction is missing        | Added after generation, wrong entity, recurring max reached                 | Statement status, driver/truck assignment, deduction max           |
| Per-stop pay is missing     | Driver does not have per-stop/extra-stop rate                               | **Driver Profile → Driver Rates**                                  |
| \$0 trips are missing       | \$0/no-pay settings disabled                                                | **Settings → Company Profile** and accounting integration settings |
| Statement will not generate | Missing pay period or setup requirements                                    | Pay period assignment, driver rates, eligible trips                |

### Deductions

**Q: How do I add a deduction?**

**A:** There are two ways. From the driver's profile: create a one-time or recurring deduction and choose whether to deduct from escrow. From Driver Settlements: click **New Transaction** or **Add Deduction** on the driver's current settlement.

**Q: How do I add a deduction tied to a specific truck?**

**A:** There are two ways. From the truck's profile: create a one-time or recurring deduction and choose whether to deduct from escrow. From Driver Settlements with truck statements enabled: select the truck you want to deduct from, then click **New Transaction** or **Add Deduction**. The deduction is tied to that truck.

**Q: Will recurring deductions stop automatically when the maximum amount is reached?**

**A:** Yes. Once a recurring deduction reaches its configured maximum, the system stops applying it automatically.

**Q: Can I split a deduction across multiple statements?**

**A:** Yes. Open the deduction table, find the deduction row, and click the three-dot menu on the right. Select **Split** to divide the deduction across statements. If the three-dot menu only shows **Edit** and **Delete** with no **Split** option, contact [support@alvys.com](mailto:support@alvys.com) to check whether the split feature is enabled on your account.

**Q: Can I add custom deduction categories?**

**A:** Custom deduction category names are not supported today, but this is on the roadmap. In the meantime, send the categories you need to [support@alvys.com](mailto:support@alvys.com) and the team will help get you configured.

**Q: Can I bulk-add a deduction across multiple drivers?**

**A:** Not today. This has been logged as a feature request. For now, add deductions per driver from the driver or truck profile, or from Driver Settlements.

**Q: I picked the wrong transaction type (for example, Deduction instead of Reimbursement). How do I fix it?**

**A:** Delete the line item and recreate it with the correct type. An in-place edit option is being evaluated for a future release.

**Q: Why are fuel deductions not on the trip?**

**A:** Fuel deductions are intentionally separated from trips. They appear as line items in their own section near the bottom of Driver Settlements once a driver is selected. Fuel transactions are not associated with a specific trip.

**Q: Why isn't my deduction showing on the statement?**

**A:** Work through these checks in order:

1. **Deduction type and assignment:** Confirm the deduction is attached to the correct entity — a driver deduction should be on the driver's profile, not on a truck profile. If using truck-based statements, the deduction must be added from the truck.
2. **Statement status:** If the statement has already been Generated, the deduction will not appear on that statement. Revert the statement to Draft (using **Revert Statement**), then add the deduction and regenerate.
3. **Deduction maximum reached:** Recurring deductions stop automatically once they hit their configured maximum amount. Check whether the maximum has been reached by reviewing the deduction row in the driver's profile.
4. **Pay period cutoff:** If the deduction was added after the statement's pay period end date, it may not appear in that run. Add it before generating the next period's statement.

### Trips, trip values, and miles

**Q: Why isn't a trip showing in Driver Settlements?**

**A:** Only trips in **Delivered** status appear in Driver Settlements. If a trip is missing, first confirm the trip has been delivered. Then check the trip's delivery date, the selected pay period, the **Cutoff Date**, and whether \$0/no-pay trip settings are enabled.

**Q: Why did the pay rate disappear for a TONU load?**

**A:** If a TONU load is not included in the rule for the driver's pay rate, the rate may not apply to that load. Review the driver's rate setup and confirm the rate rule includes TONU loads for that specific rate.

To fix this:

1. Open the driver's profile.
2. Go to **Driver Rates**.
3. Edit the affected rate.
4. Review the rate rules.
5. Make sure TONU loads are included in the rule criteria.
6. Save the rate and review the settlement again.

**Q: How do I correct miles if the dispatcher made a mistake?**

**A:** In the Driver Settlements table, click directly on the miles cell for the trip and edit the value. The statement recalculates automatically.

**Q: How do I edit the trip value (load value)?**

**A:** There are two options. Click the three-dot menu on the right side of the trips table and select the edit option. Or click directly on the trip value cell in the trips table and update it inline. Driver percentage pay recalculates based on the updated trip value.

**Q: Why are already-paid loads reappearing in Driver Settlements?**

**A:** Already-paid loads can reappear if duplicate driver pay was created on the load. This can happen when a driver's pay rate is recreated, but the duplicate pay is not corrected in the load's money box.

To troubleshoot:

1. Open the affected load.
2. Review the driver pay in the money box.
3. Check whether duplicate driver pay lines exist.
4. Remove or correct the duplicate pay entry.
5. Return to Driver Settlements and confirm the load no longer appears incorrectly.

If the load still appears after correcting duplicate pay, contact [support@alvys.com](mailto:support@alvys.com) with the load number and driver name.

**Q: Can I pay two drivers from the same load with different gross amounts?**

**A:** This is not directly supported through a single trip today. As a workaround, adjust each driver's pay manually on their respective statements. Contact [support@alvys.com](mailto:support@alvys.com) if you would like help working through your specific setup.

**Q: How do I set up pay for a team driver load (two drivers on the same trip)?**

**A:** Each driver needs their own rate configured on their profile. For team loads:

1. Create a separate rate on each driver's profile using the appropriate rate type (per mile, per trip, or percentage of trip value).
2. To apply a rate only to team loads, add a rule to that rate restricting it by **Number of Drivers** (set to 2 or more). This prevents the team rate from applying to solo trips.
3. In Driver Settlements, each driver's statement will show their portion of the trip value independently. Verify the amounts in the **Open** tab before approving.

For complex team pay scenarios involving split gross amounts or multiple legs, contact [support@alvys.com](mailto:support@alvys.com) for a tailored setup review.

**Q: Why does the per-stop or extra-stop line item not show on my statement?**

**A:** Per-stop and extra-stop charges only appear on the statement when the driver has a per-stop or extra-stop rate configured on their profile. Add the rate under **Driver Profile → Driver Rates** and it will populate automatically on future statements.

**Q: Why does a driver have \$0 trips that are not pulling onto the statement?**

**A:** This is controlled by two settings under **Settings → Company Profile**: Enable Trips with \$0 Payables to display in settlements, and Enable Trips with no Payables to display in settlements. Toggle these to control whether \$0 or no-pay trips flow to driver statements. Your accounting integration settings have a similar checkbox to control whether \$0 payables sync to your accounting system.

**Q: Why does an Owner Operator show \$0 in the Open status?**

**A:** Check the two checkboxes under **Settings → Company Profile** (Enable Trips with \$0 Payables and Enable Trips with no Payables) and the corresponding setting on your accounting integration.

**Q: Can I change the order in which loads appear on the statement?**

**A:** You can sort the trips list inside Driver Settlements by clicking the **Date** column header. Clicking it toggles the sort order between ascending and descending. Trips are automatically ordered chronologically by delivery date (oldest at the top, newest at the bottom) by default. Customizing the load order on the generated PDF is not supported today, but the PDF order follows the delivery date. If trips appear out of order on the statement or PDF, verify and correct delivery dates in the system. Once corrected, the trips will reorder themselves automatically in both the interface and the PDF.

**Q: Why are trips appearing out of order on my statement or PDF?**

**A:** Trips in Driver Settlements are ordered by delivery date. If trips appear out of order, verify and correct the delivery dates in the system. Once corrected, the trips will automatically reorder themselves in both the user interface and the generated PDF.

**Q: Why is my driver's pay calculating incorrectly or showing unexpected amounts?**

**A:** Work through these checks in order:

1. **Rate type:** Confirm the rate type on the driver's profile matches how they should be paid (per mile, per trip, % of trip value, and so on).
2. **Mile source:** If using a mileage-based rate, check whether the rate targets **Loaded Miles**, **Empty Miles**, or **Total Miles**, and confirm the trip has the correct mileage recorded in Driver Settlements.
3. **Rate rules:** If you have added rules to restrict when a rate applies (by customer, equipment type, or number of drivers), confirm the trip meets those criteria. A rate with rules that do not match the trip will not apply.
4. **Multiple active rate plans:** If the driver has more than one active rate that could apply to the same trip type, the system may be applying the wrong one. Review all rates on the driver's profile and deactivate any that conflict with the intended rate.
5. **Trip status:** Only trips in **Delivered** status appear in Driver Settlements. Confirm the trip has been delivered before expecting it to show pay amounts.

<Warning>
  Rate plans stack additively with no de-duplication and no priority order. If two plans both grant the same rate to one driver, that driver is paid twice. See [Driver settlements](/en/help/accounting-settlements/driver-settlements) for how plans and profile rates combine.
</Warning>

### Statements: generation, format, and customization

**Q: What happens when I generate a statement?**

**A:** Generating a statement finalizes the settlement record for that driver or owner operator. Depending on your setup, the driver can receive the statement by email, view it in the Alvys Driver App, and the statement may sync to your accounting system. Generating a statement does **not** move money or pay the driver directly.

**Q: What is the difference between Pay Period and Statement Date?**

**A:** The **Pay Period** controls which eligible trips, deductions, and transactions are included in the settlement run. The **Statement Date** is the date shown on the driver's statement. Drivers see the Statement Date, not the pay period name.

**Q: Can I download all statements in bulk as PDFs before final generation?**

**A:** Bulk PDF download during the preview phase is on the roadmap.

**Q: Can I create a custom statement template?**

**A:** Custom templates beyond the built-in layout options are not supported today. This has been logged as a feature request.

**Q: Can I hide load rates (trip values) from the driver-facing statement?**

**A:** Hiding the trip value on driver-facing statements is on the roadmap.

**Q: Can I split a single load's linehaul amount across statements by dollar amount?**

**A:** Manually keying split dollar amounts on a linehaul is not supported today. However, you can split a trip across statements at the line-item level: click the trip row and use the checkboxes to select which line items go on which statement.

**Q: Can I show total empty miles and total loaded miles on the statement?**

**A:** Not today. This has been added to the roadmap.

**Q: The company logo looks shrunk on the statement preview. Is that a bug?**

**A:** This is a known visual issue. Send a screenshot to [support@alvys.com](mailto:support@alvys.com) so the team can investigate your account. A fix is coming in an upcoming statement template update.

### Reverting and reopening statements

**Q: What happens if I revert a statement that has already been sent to my accounting system?**

**A:** The behavior depends on your accounting platform (QuickBooks Online, QuickBooks Desktop, Sage, Business Central, NetSuite). Each platform behaves differently when statements are reverted. Contact [support@alvys.com](mailto:support@alvys.com) with your specific platform and the team will send you the exact behavior.

**Q: I reverted a statement by mistake. Is there a way to recover it?**

**A:** Today, reverted statements are not stored or surfaced anywhere after they are reverted. As a workaround, if you need to undo a statement without losing context, use **Revert to Draft** instead of reverting to Open: that keeps the statement intact so you can regenerate it. Surfacing reverted statements is on the roadmap.

### Truck statements (for owner operators)

**Q: Can I generate a statement per truck for an owner operator?**

**A:** Yes. Truck statements let you break down activity per truck for owner operators with multiple trucks. See [Truck Statements for Owner Operators](/en/help/accounting-settlements/how-to-generate-truck-statements-for-owner-operators) for setup steps.

**Q: Why does an owner operator need at least 2 trucks for a truck statement?**

**A:** With one truck, the individual driver statement and the truck statement contain the same information, so splitting them adds no value. Once an owner operator has 2 or more trucks, separate truck statements are needed to break down activity per truck.

**Q: My owner operator has one truck and a driver who needs to be paid. How do I handle that?**

**A:** The standard owner operator statement covers both the owner and the truck in one statement. If your scenario is more complex, contact [support@alvys.com](mailto:support@alvys.com) so the team can review your specific case.

### Accounting integration

**Q: Does Driver Settlements affect my existing QuickBooks integration?**

**A:** No. The Driver Settlements module does not change your existing QuickBooks integration behavior. The statement built within Driver Settlements is what syncs to QuickBooks and other accounting systems, using the same integration settings you had before.

**Q: Will company driver statements flow to QuickBooks?**

**A:** Today, only owner operator statements sync to QuickBooks. Company driver statements require a QuickBooks Payroll integration, which is not currently supported. In the meantime, company driver pay must be entered manually in QuickBooks.

**Q: Is the QuickBooks integration only for bookkeeping, or can it run payroll?**

**A:** The QuickBooks integration is for bookkeeping today. Payroll-style payouts to drivers from Alvys via QuickBooks are not supported.

**Q: Can I issue payments to drivers directly from Alvys?**

**A:** Not in the current roadmap. Alvys produces the statement; the actual funds movement happens in your accounting or payroll system.

**Q: Does generating a statement actually pay the driver?**

**A:** No. Alvys does not move funds. A statement is a record of what the driver is owed. When you generate a statement, three things happen: the driver receives the statement by email (if email delivery is configured); the driver can view the statement in the Alvys Driver App; and for applicable driver types, the data syncs to your accounting system, where you run payroll or issue payment.

### Permissions and users

**Q: Can I set role-based permissions on Driver Settlements (for example, draft-only vs. view-only vs. approve)?**

**A:** Granular role-based permissions on Driver Settlements are not supported today. This has been logged as a feature request.

<Note>
  Access to Driver Settlements is controlled by the **Pay Driver** and **Pay Owner Operator** permissions in the Billing category. Permissions are assigned per user in **Settings → Organization → Users**. See [Billing permissions](/en/help/administration/billing-permissions) for which roles have these by default and how to grant them.
</Note>

### Tables, columns, and search

**Q: Can I pin specific columns so they do not shift around?**

**A:** Yes. Right-click any column header and choose **Pin column to the left** or **Pin column to the right**. You can also right-click and select **Configure Columns** to control which columns are visible and in what order. Column layouts save per user.

**Q: Can I hide columns in the Open and Draft tabs?**

**A:** Yes. Right-click any column header in the Open or Draft tab and select **Configure Columns** to show or hide columns. Selections save per user.

**Q: How do I filter trips by date in Driver Settlements?**

**A:** In the Open tab, set the **Cutoff Date**. Any trips delivered after that date will be hidden from the view. This is useful when migrating to Driver Settlements or when excluding newer items from a settlement run.

**Q: Search is not returning what I expect. Is it broken?**

**A:** Search in Driver Settlements currently supports searching by **Trip Number** only. Broader search (by driver, deduction, or other fields) is on the roadmap.

### Driver reactivation

**Q: Why does an inactive driver still have active items that need to be settled?**

**A:** Inactive drivers can still have trips, deductions, reimbursements, or other open settlement items from before they were deactivated. If you need to settle those items, enable the **Settle Inactive Driver** setting in Driver Settlements. Once enabled, inactive drivers with eligible unsettled items can appear in the settlement workflow. After settling the remaining items, review the driver again to confirm there are no additional open settlement items.

**Q: When I reactivate an inactive driver, do I need to do anything in Settings to make them appear in Driver Settlements?**

**A:** No extra action is required. Once reactivated, the driver should appear in the Open tab as soon as they have eligible trips for the current pay period. If they are not appearing, contact [support@alvys.com](mailto:support@alvys.com).

### Pricing

**Q: Is Driver Settlements an extra add-on?**

**A:** No. Driver Settlements is included in your existing Alvys subscription at no additional cost.

## Common setup paths

### Company driver paid by mileage

1. Create or confirm the pay period.
2. Open the driver profile.
3. Add a **Per Mile** rate.
4. Confirm whether the rate uses loaded, empty, or total miles.
5. Confirm trips are delivered before generating the statement.

### Owner operator with multiple trucks

1. Confirm the owner operator has 2 or more trucks.
2. Enable or use truck statements.
3. Add truck-specific deductions from the truck profile or truck statement view.
4. Generate statements by truck.

### Team driver load

1. Add a rate to each driver profile.
2. Use a **Number of Drivers** rule if the rate should only apply to team loads.
3. Review each driver's statement independently before approving.

## Go Deeper

* [Driver settlements](/en/help/accounting-settlements/driver-settlements)
* [Driver rates, rules, and plans](/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex)
* [Truck Statements for Owner Operators](/en/help/accounting-settlements/how-to-generate-truck-statements-for-owner-operators)
* [How to set up time-based pay in Driver Settlements](/en/help/accounting-settlements/time-based-pay-in-driver-settlements)
* [Billing permissions](/en/help/administration/billing-permissions)


# Fuel Surcharge Contracts
Source: https://docs.alvys.com/en/help/accounting-settlements/fuel-surcharge-contracts

Set up per-customer fuel surcharge contracts with flat, distance, or percentage matrices, link them to lane rates, and let Alvys apply the surcharge automatically.

## Overview

When you dispatch a load, the cost of fuel fluctuates. Fuel Surcharge Contracts allow you to define rules for how fuel surcharges are calculated and applied to loads, so you don't have to manually adjust rates every time fuel prices change.

Fuel surcharge contracts are set up **per customer** and can be linked to lane rate contracts. When a load matches a lane with a fuel surcharge contract, the surcharge is automatically calculated based on the current week's fuel prices.

**Navigation:** Companies > Select a Customer > Lane Rates tab > Fuel Surcharge Contracts

***

## Fuel Surcharge Types

Alvys supports three types of fuel surcharge calculations:

| **Type**       | **How It Works**                                                                                                                                                                         | **Best For**                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Fixed**      | A flat dollar amount per load OR a rate per mile. Does not change with fuel prices.                                                                                                      | Simple contracts where the surcharge is a set amount regardless of fuel cost.         |
| **Distance**   | A matrix of fuel price ranges mapped to dollar-per-mile rates. The system looks up the current fuel price, finds the matching tier, and multiplies the rate by the load's billing miles. | Contracts where the surcharge varies by fuel price and is calculated per mile.        |
| **Percentage** | A matrix of fuel price ranges mapped to percentage rates. The system looks up the current fuel price, finds the matching tier, and applies the percentage to the load's linehaul rate.   | Contracts where the surcharge is a percentage of the linehaul, varying by fuel price. |

***

## Creating a Fuel Surcharge Contract

## Step 1: Navigate to Fuel Surcharge Contracts

1. Go to **Companies** > **Customers** in the left sidebar
2. Select the **Customer** you want to set up the contract for to open **Customer Profile**
3. Click **Contracted Lanes & Fuel Surcharges** button in top right corner of the page.
4. Click the **Fuel Surcharge Contracts** tab
5. Click **Add New Contract**

## Step 2: Configure Contract Details

Fill in the following fields on the **Details** tab:

| **Field**                 | **Description**                                                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contract Name**         | A descriptive name for this contract (e.g., "Customer ABC - FSC 2026").                                                                           |
| **Type**                  | Select **Fixed**, **Distance**, or **Percentage** (see above).                                                                                    |
| **Sub-Type** (Fixed only) | Choose **Flat** (one amount per load) or **Rate Per Mile** (amount multiplied by miles).                                                          |
| **Amount** (Fixed only)   | Enter the dollar amount for the surcharge.                                                                                                        |
| **Load Date**             | Which date on the load determines the fuel price lookup: **Scheduled Pickup**, **Actual Pickup**, **Scheduled Delivery**, or **Actual Delivery**. |
| **Date Offset**           | Which week's EIA fuel prices to use: **Current Week**, **Previous Week**, **Begin of Month**, or **Custom Range**.                                |
| **Custom Day Offset**     | If using Custom Range, enter a day adjustment from -9 to +9 days relative to the load date.                                                       |
| **Region**                | The geographic region for the EIA fuel price lookup (e.g., "U.S.").                                                                               |
| **Rounding**              | How to round the calculated rate: Whole Penny, Tenth of a Penny, Hundredth of a Penny — Rounded or Truncated.                                     |

## Step 3: Set Up the Matrix (Distance and Percentage Only)

If you selected **Distance** or **Percentage** as the type, click the **Matrix** tab to define your fuel price tiers.

Each row in the matrix represents a fuel price range and the corresponding surcharge rate:

| **Column**      | **Description**                                                                                     | **Example**       |
| --------------- | --------------------------------------------------------------------------------------------------- | ----------------- |
| **Start Price** | The lower bound of the fuel price range (per gallon).                                               | \$3.00            |
| **End Price**   | The upper bound of the fuel price range (per gallon).                                               | \$3.49            |
| **Rate**        | For **Distance**: the dollar rate per mile. For **Percentage**: the decimal rate (e.g., 0.05 = 5%). | \$0.08/mi or 0.05 |

**Tips for the matrix:**

* Click **Add Row** to add tiers one at a time
* Click **Import CSV** to bulk-import tiers from a spreadsheet (click **Download Template** first to get the correct format)
* Tiers must not overlap — each fuel price should fall into exactly one range
* Values support up to **4 decimal places** for precision
* For Percentage type, enter rates as decimals (0.05 = 5%), not as whole percentages

## Step 4: Enable and Save

1. Click **Save**

***

## Linking a Fuel Surcharge Contract to a Lane Rate

Once you've created a fuel surcharge contract, you need to link it to one or more lane rate contracts for it to take effect on loads.

1. Go to **Companies** > **Customers** in the left sidebar
2. Select the **Customer** you want to set up the contract for to open **Customer Profile**
3. Click **Contracted Lanes & Fuel Surcharges** button in top right corner of the page.
4. Open or **Create** **Contract**
5. In the contract details, select the **Fuel Surcharge Contract** from the dropdown
6. Save the lane rate contract

When a load matches this lane, the fuel surcharge will be automatically calculated and applied.

***

## How the Calculation Works

When a load is created or updated with a lane rate contract that has a fuel surcharge:

1. The system determines the **load date** (based on the contract's Load Date setting)
2. It applies the **date offset** to determine which week's fuel prices to use
3. It looks up the **EIA weekly fuel price** for the configured region
4. Based on the contract type:
   * **Fixed (Flat):** Surcharge = the configured amount
   * **Fixed (Per Mile):** Surcharge = amount x billing miles
   * **Distance:** Finds the matrix tier matching the fuel price, then: Surcharge = tier rate x billing miles
   * **Percentage:** Finds the matrix tier matching the fuel price, then: Surcharge = tier rate x linehaul rate
5. The result is **rounded** per the contract's rounding setting
6. The surcharge appears as a separate line item on the load

⚠️ **Note:** If the load's dates are in the future and fuel prices aren't available yet, the system will flag the surcharge for recalculation once actual dates and prices are available.

***

## Example: Setting Up a Distance-Based Fuel Surcharge

Let's say your customer contract states: "Fuel surcharge is $0.02 per mile for every $0.05 increase in fuel price above \$3.00/gallon."

Here's how you'd set it up:

1. Create a new Fuel Surcharge Contract
2. Set **Type** to **Distance**
3. Set **Load Date** to **Scheduled Pickup**
4. Set **Date Offset** to **Previous Week** (most common)
5. Set **Region** to **U.S.**
6. On the **Matrix** tab, add rows:

| **Start Price** | **End Price** | **Rate (\$/mile)** |
| --------------- | ------------- | ------------------ |
| \$3.00          | \$3.049       | \$0.02             |
| \$3.05          | \$3.099       | \$0.04             |
| \$3.10          | \$3.149       | \$0.06             |
| \$3.15          | \$3.199       | \$0.08             |

If the EIA fuel price for the load's week is $3.12/gallon and the load is 500 miles, the surcharge would be: **$0.06 x 500 = \$30.00\*\*

***

## Example: Setting Up a Percentage-Based Fuel Surcharge

If your customer contract states: "Fuel surcharge is a percentage of the linehaul rate based on current fuel prices."

1. Create a new Fuel Surcharge Contract
2. Set **Type** to **Percentage**
3. Configure Load Date, Date Offset, Region, and Rounding as needed
4. On the **Matrix** tab, add rows:

| **Start Price** | **End Price** | **Rate (decimal)** |
| --------------- | ------------- | ------------------ |
| \$3.00          | \$3.49        | 0.05               |
| \$3.50          | \$3.99        | 0.08               |
| \$4.00          | \$4.49        | 0.11               |

💡 **Percentage rates are entered as decimals:** 0.05 = 5%, 0.08 = 8%, 0.1234 = 12.34%. Do not enter "5" for 5%. If the fuel price is $3.75 and the linehaul is $2,000, the surcharge would be: **0.08 x $2,000 = $160.00**

***

## Frequently Asked Questions

* **Where does Alvys get the fuel prices?**
  Alvys uses the **U.S. Energy Information Administration (EIA)** weekly retail diesel fuel prices, published every Monday. The prices are region-specific and updated automatically.
* **Can I have multiple fuel surcharge contracts for the same customer?**
  Yes. You can create multiple contracts and assign different ones to different lane rate contracts for the same customer.
* **What happens if the fuel price falls outside my matrix tiers?**
  If the current fuel price doesn't match any tier in the matrix, no surcharge will be applied. Make sure your tiers cover the expected range of fuel prices.
* **Can I import my matrix from a spreadsheet?**
  Yes. On the Matrix tab, click **Download Template** to get a CSV template, fill in your tiers, then click **Import CSV** to upload it.
* **How precise can the matrix values be?**
  All matrix values support up to **4 decimal places**. This applies to Start Price, End Price, and Amount.
* **What is the Date Offset for?**
  Fuel prices are published weekly. The Date Offset lets you control which week's prices to use relative to the load date. Most customers use **Previous Week** since the current week's prices may not be published yet at the time of dispatch.


# How to Generate Truck Statements for Owner Operators
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-generate-truck-statements-for-owner-operators

Generate per-truck statements for owner operator drivers in Alvys to review consolidated truck earnings and deductions before finalizing driver paystubs.

### Overview

Truck statements (truck-level statements, per-truck statements) are an optional view available for Owner Operator drivers. They consolidate all trips run by the same truck into a single statement view, allowing companies to review total truck earnings and deductions before processing individual driver statements. When enabled, Alvys generates a statement grouped by truck rather than by individual driver. This is useful for companies that pay Owner Operators on a per-truck basis or want to review total truck-level earnings before finalizing driver payouts.

Truck statements do not replace driver paystubs. They are a separate aggregation view. Driver paystubs are still generated individually per driver.

<Info>
  💡 Generating a statement does not pay the driver. It creates a finalized record for the pay period. Payment is handled separately through your accounting or payroll system.
</Info>

### Before You Start

You need the **"EditAsset"** permission to enable or disable the Truck Statements setting on a driver profile. Contact your Alvys Admin if this setting is unavailable.

Confirm the following before starting:

* The driver is set up as an Owner Operator in Alvys.
* The driver has completed trips that fall within the statement period you want to generate.

### Steps

1. Open the driver's profile. Navigate to **Assets > Drivers**, find the Owner Operator driver, and open their profile.
2. Enable Truck Statements. In the driver's profile, locate the **Truck Statements** toggle and turn it on. You must have the **"EditAsset"** permission to toggle this setting. If the toggle is not visible or not editable, contact your Alvys Admin to confirm your permissions.

   <img alt="Driver profile showing the Truck Statements toggle in the enabled position." />

   \*Driver profile showing the Truck Statements toggle in the enabled position. \*
3. Open the driver's settlements. With the driver's profile open, navigate to the **Settlements** tab. The settlements view shows all statement periods for this driver.

   <img alt="Driver Settlements tab showing payable items in “Open Status”" />

   \*Driver Settlements tab showing payable items in “Open Status” \*
4. Select the statement period and generate the truck statement. Find the statement period you want to generate and click **Generate** next to that period. Alvys creates the truck statement and groups all qualifying trips by truck for that period.

   <img alt="Driver Settlements tab showing the Generate button next to a statement period." />

   \*Driver Settlements tab showing the Generate button next to a statement period. \*

## FAQs

**What happens if I already have a draft open when I switch between owner-operator and truck statements?**

The system will notify you that switching back to owner-operator pay will convert your existing drafts back to open items. You will be prompted to confirm before the change takes effect.

**What happens if I revert an owner operator statement but they recently switched over to being paid by truck?**

This statement will be deleted and all transactions will be reverted back to an open status. You can resolve this conflict yourself by enabling truck statements for this driver, then coming back here to revert to a statement draft.

**What happens if I revert a truck statement but they recently switched over to being paid as a single owner-operator statement?**

This statement will be deleted and all transactions will be reverted back to an open status. You can resolve this conflict yourself by disabling truck statements for this driver, then coming back here to revert to a statement draft.

**Why are my open and draft tabs disabled while viewing an owner operator?**

If you’ve enable truck statements for an owner operator, you’ll need to select a truck to view open and draft transactions. This ensures any changes you make will always apply to a specific truck given you’re now generating statements by truck, not as a single owner-operator statement.

**How do I split a deduction between the driver’s pay and an escrow account?**

Simply add the deduction to the statement then add a new transaction for an escrow withdrawal to split the escrow amount onto - you can also add a description on the transaction to help clarify why it’s applied to the statement. By creating two separate transactions, this ensures a more accurate accounting sync to 3rd party platforms and follows better accounting practices. Previously, in driver pay there was a way to split to an escrow account by editing a deduction but to ensure safer accounting this is now handled as a separate escrow withdrawal.

**Why does an owner operator need at least 2 trucks for a truck statement?**

This is intentional. With one truck, the individual driver statement and the truck statement contain the same information — splitting them adds no value. Once an owner operator has 2 or more trucks, separate truck statements are required to break down activity per truck.

**My owner has one truck and a driver who needs to be paid. How do I handle that?**

The standard owner operator statement covers both the owner operator and the truck in one. If your scenario is more complex, reach out to [support@alvys.com](mailto:support@alvys.com) so we can review your specific case.

**How do I add a deduction tied to a specific truck?**

There are two ways:

* **From the truck’s profile**: create a one-time or recurring deduction. You can choose whether to deduct from escrow.
* **From Driver Settlements**: with truck statements enabled, select the truck you want to deduct from, then click **New Transaction** or **Add Deduction**. The deduction is tied to the truck.

## Go Deeper

Check out these related articles to learn more:

* [Driver Settlements Overview](/en/help/accounting-settlements/driver-settlements-faq)
* [Time-based Pay](/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex)


# How to Handle Short Payments and Write Off Bad Debt
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-handle-short-payments-and-write-off-bad-debt

Handle customer short payments and bad debt write-offs in Alvys by deleting the payment, adding a negative accessorial, and regenerating the invoice.

<Note>
  When a customer pays less than the full invoice amount (a short payment or write-off), you must follow a specific sequence to zero out the balance correctly: delete the partial payment, add a negative customer accessorial for the unpaid amount, regenerate the invoice, then re-record the payment. Skipping any step will prevent the invoice from regenerating or syncing to your accounting integration.
</Note>

## Overview

When a customer short-pays an invoice, meaning they pay less than the invoiced total, you need to reduce the invoice balance to match the actual payment received. The correct way to do this in Alvys is to add a negative customer accessorial (sometimes called a write-off or adjustment) that offsets the unpaid amount.

This approach matters because Alvys blocks invoice regeneration whenever a payment is recorded on that invoice. The Regenerate Invoice button becomes inactive as long as any payment exists. If you add the negative accessorial without first deleting the payment, the button stays inactive and the adjusted invoice cannot sync to your accounting system.

This article covers the complete workaround for short payments, underpayments, and bad debt write-offs.

Synonyms: short pay, short payment, underpayment, bad debt, write-off, debt forgiveness, balance adjustment, negative accessorial.

## Before You Start

Before following these steps, confirm:

* The invoice has already been generated for the load (the load is not in **Draft** billing status).
* You have the **"Billing"** permission, which is required to record and delete customer payments.
* You have the **"Accessorials"** permission, which is required to add a customer accessorial to the load.
* You know the exact short-paid amount: the difference between the invoice total and the payment actually received.

If you do not have either permission, contact your account administrator.

## Steps

1. Open the load and confirm the invoice exists.
2. Navigate to the load.
3. Confirm the invoice has been generated. The load must not be in **Draft** billing status before proceeding.
4. Delete the existing partial payment. If you have already recorded a partial payment on this invoice, delete it before making any other changes.
5. On the load, locate the Payments section.
6. Find the partial payment you recorded.
7. Select the option to delete or remove that payment.

   Deleting the payment is required because Alvys prevents invoice regeneration whenever any payment record exists on the invoice. Removing the payment allows the invoice total to be edited and regenerated.
8. Add a negative customer accessorial to the load with a negative amount equal to the unpaid balance.
9. On the load, go to the Accessorials section.
10. Click **Add Accessorial**.
11. Set the entity to **Customer**.
12. Select the appropriate accessorial type (for example, a write-off or adjustment type configured in Settings).
13. Enter the amount as a negative value equal to the short-paid amount (for example, if the invoice is $1,000 and the customer paid $950, enter -\$50).
14. Save the accessorial.
15. Regenerate the invoice.
16. On the load, click **Regenerate Invoice**.

    The Regenerate Invoice button is now active because no payment record exists on the invoice and the invoice total has changed as a result of the negative accessorial. Both conditions must be true for the button to become active.
17. Re-record the payment.
18. Re-enter the short payment for the amount actually received.
19. Save the payment.

The payment now matches the new (reduced) invoice total. The invoice and payment will sync correctly to your connected accounting integration.

## Result

After completing these steps, the invoice total reflects the actual amount the customer paid, the recorded payment matches the invoice total, and the invoice syncs to your third-party accounting platform (QuickBooks Online, QuickBooks Desktop, Business Central, Sage Intacct, NetSuite, or other connected system).

## Variations

**Writing off the full balance (bad debt):** If the customer will not pay anything at all, follow the same sequence. In step 2, delete any payments. In step 3, add a negative accessorial equal to the full invoice total. In steps 4 and 5, regenerate the invoice and optionally record a \$0 payment or leave the balance at zero.

**Accessorial type not available:** If no write-off or adjustment accessorial type exists in your account, an Admin or Partner Admin must first create one in Settings > Accessorials.

## Troubleshooting

### Regenerate Invoice button is not active after adding the negative accessorial

This occurs when a payment record still exists on the invoice.

1. Return to the load's Payments section and confirm no payment is recorded. If a payment is present, delete it.
2. Once the payment is removed, attempt to click Regenerate Invoice again.

### Invoice is not syncing to accounting integration after regeneration

This occurs when the invoice was not regenerated after the accessorial was added, or when the payment was re-recorded before regeneration completed.

1. Confirm you regenerated the invoice before re-recording the payment.
2. If you re-recorded the payment before regenerating, delete the payment again, regenerate the invoice, then re-record the payment.
3. If the invoice still does not sync, check the Error Transactions page in Alvys for a sync error on this load. If no error appears and the invoice has not synced, contact Alvys support with the load number.

### Negative accessorial type is not available in the dropdown

1. Contact your account administrator and ask them to create an appropriate accessorial type in Settings > Accessorials. Only Admins and Partner Admins can create new accessorial types.

## FAQs

**Q: Why does Alvys block invoice regeneration when a payment is already recorded?**

**A:** Alvys requires that no payment record exists before an invoice can be regenerated. This ensures the invoice total and payment amounts stay in sync. Deleting the payment first removes this constraint and allows the invoice total to be updated.

**Q: Do I need to delete the payment even if the negative accessorial already reduces the balance to zero?**

**A:** Yes. The Regenerate Invoice button checks for the presence of any payment record, regardless of the balance. As long as any payment exists, the button remains inactive.

**Q: What accessorial type should I use for a write-off or short payment?**

**A:** Alvys does not include a dedicated write-off accessorial type by default. Your Admin needs to create one in Settings > Accessorials with a name such as "Write-Off" or "Balance Adjustment." The type should be mapped to your accounting integration if applicable.

**Q: Can I use this workaround for batch invoicing?**

**A:** This workaround applies to individual load invoices. For batch (summary) invoices, the workflow may differ. Consult your accounting team before applying adjustments to summary invoices.

## Go Deeper

* [Custom Accessorials](/en/help/loads-trips/how-to-create-and-add-accessorials)


# How to Request Detention Payment by Email
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-request-detention-payment-by-email

Send a customer detention payment request email straight from a load stop in Alvys, using pre-filled stop details and your configured billing contacts.

<Note>
  Send a detention payment request email directly from a stop on a load. The email is pre-filled with stop details and uses your company's configured detention email settings for the From, To, and CC addresses.
</Note>

## Overview

When a driver is delayed at a pickup or delivery stop beyond the scheduled appointment time, you can request detention payment from the customer without leaving the load. Alvys generates the email automatically using the stop's details and your company's Email Management settings.

Detention request email is also called: detention billing email, stop detention email, driver detention request.

## Before You Start

* The stop must be checked out. The **Request Detention** button appears only when the stop status is **PickedUp** (pickup stops) or **Empty** (delivery stops).
* Stops that were auto-completed, where arrival and departure were stamped at the same time with zero dwell time, are not eligible for detention billing and do not show the **Request Detention** button.
* An Admin or Partner Admin must configure detention email defaults in Company Profile before anyone on the team can send detention requests. If no defaults are configured, the To and CC fields in the email draft will be empty.

## Steps

1. Configure detention email defaults. This step is completed by an Admin or Partner Admin only.
2. Select your username in the upper-right corner and choose **Company Profile**.
3. Select the **Subsidiaries** tab and click the subsidiary you want to configure.
4. Click the **Email Management** tab.
5. Scroll to the **Detention** section and set the following fields:

   * **From:** Choose one of three options. **Default** sends from [no-reply@alvys.com](mailto:no-reply@alvys.com). **User** sends from the logged-in user's email address. **Custom** lets you enter a specific outbound email address for detention requests.
   * **To:** Enter the default recipient email for detention requests (typically the customer's operations or billing contact).
   * **CC:** Enter any email addresses to be copied on every detention request.
6. Click **Save**.

   <img alt="Screenshot of the Email Management tab showing the Detention section with From, To, and CC fields" />

   *Screenshot of the Email Management tab showing the Detention section with From, To, and CC fields*
7. Send a detention request from a stop.
8. Open the load and scroll to the **Stops** section on the load details page.
9. Locate the stop where detention occurred. The **Request Detention** button appears only when the stop status is **PickedUp** or **Empty**.
10. Click **Request Detention**.

    <img alt="Screenshot of the Email Management tab showing the Detention section with From, To, and CC fields." />

    \*Screenshot of the Email Management tab showing the Detention section with From, To, and CC fields. \*
11. Review the pre-filled email draft. The subject line and body are generated automatically and include the load number, stop company name, original appointment date and time, and driver check-in and check-out times.

    * The From address reflects the Email Management setting for your subsidiary.
    * The To field is pre-filled with the customer's operations email and the Detention To address from Email Management.
    * The CC field uses the Detention CC address from Email Management.
12. Edit the draft as needed, then click **Send**.

## Result

The detention request email is sent to the customer. The load record reflects that a detention request was submitted for that stop.

## Troubleshooting

### Request Detention button is not visible

1. Confirm the stop has been checked out. The button appears only when the stop status is **PickedUp** or **Empty**. If the stop has not yet been checked out, the button does not appear.
2. Check whether the stop was auto-completed. Stops where arrival and departure were stamped at the same time (zero dwell time) are not eligible for detention billing.
3. If the stop is checked out, was not auto-completed, and the button still does not appear, contact Alvys support.

### Email draft is missing To or CC addresses

1. Confirm that the Detention To and CC fields are configured in Email Management for your subsidiary. Go to your username > **Company Profile** > **Subsidiaries** > select your subsidiary > **Email Management** > **Detention**.
2. Confirm the load's **Invoice As** subsidiary matches the subsidiary where you configured the settings. Each subsidiary has its own Email Management configuration.

## FAQs

**Q: Can I send a detention request before the driver checks out?**

**A:** No. The Request Detention button only appears after the driver has checked out of the stop, when the stop status is **PickedUp** or **Empty**.

**Q: What email address does the detention request come from?**

**A:** This depends on the From setting in Email Management for your subsidiary. **Default** sends from [no-reply@alvys.com](mailto:no-reply@alvys.com), **User** sends from the logged-in user's email address, and **Custom** sends from the address your admin configured.

**Q: Why is a stop not eligible for detention billing?**

**A:** Stops that were auto-completed have the same arrival and departure timestamp, meaning the actual dwell time at the stop is unknown. These stops cannot be used for detention billing.


# How to use Summary Invoicing
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-use-summary-invoicing

Consolidate multiple released loads into one grouped customer invoice with Alvys Summary Invoicing, using Amendment mode and per-customer setup.

Summary Invoicing consolidates multiple loads into a single invoice per customer. Use it for customers who prefer one periodic invoice rather than a separate invoice per load.

## Overview

Summary Invoicing, also called consolidated or grouped invoicing, groups loads for a single customer into one invoice document, reducing invoice volume and simplifying reconciliation for high-volume customers. Loads must be in **Released** or **TONU** status before they appear in a summary invoice draft. Unlike Individual invoicing, Summary Invoicing uses the Amendment update mode only; Supplemental mode is not supported.

## Before You Start

You must have both the **"Billing"** and **"ViewPaystubs"** permissions to access Summary Invoicing. Summary Invoicing must also be enabled for your account — contact Alvys support to have it turned on.

Configure the customer profile for Summary Invoicing (steps 1 through 4 below) before attempting to generate any invoices. Loads for customers not configured for Summary type will not appear on the Loads Not Invoiced tab.

## Steps

1. **Configure the customer profile.** Open the customer or broker profile and navigate to Invoicing Settings. Set the following fields:

   * Invoice Update Mode: set to Amendment
   * Invoice Type: set to Summary
   * Required Documents: select any document types the customer requires before invoicing
   * Auto Merge: on by default; leave enabled unless the customer requires manual grouping control
   * Delivery Method: select Email or EDI only; Factoring Company and other delivery methods are not supported for Summary Invoicing
2. **Verify load configuration.** On each load you intend to include, confirm:

   * The Customer field matches the customer configured in step 1
   * Invoice As is set to the correct subsidiary
   * All required documents specified in the customer's Invoicing Settings are attached
3. **Move loads to Released.** Loads must be in **Released** or **TONU** status before they appear on the Summary Invoicing page. Use Batch Invoicing (Accounting > Invoicing) to release loads from the Incomplete tab.
4. **Open Summary Invoicing.** Navigate to Accounting > Summary Invoicing. The page contains three tabs: Loads Not Invoiced, Drafts, and All Invoices.
5. **Review the Loads Not Invoiced tab.** This tab lists all **Released** and **TONU** loads eligible for summary invoicing, grouped by customer. Loads appear here only when the customer profile is set to Invoice Type: Summary.

   <Note>
     🖼️ Image placeholder: Screenshot of the Loads Not Invoiced tab showing loads grouped by customer with Released/TONU status indicators. Upload from IC:12159947.
   </Note>
6. **Generate a summary invoice draft.** Two paths are available:

   * Option 1, from the Drafts tab: One active draft exists per customer. Select the customer draft and click Generate to create the summary invoice document.
   * Option 2, from the Loads Not Invoiced tab: Select the loads you want to include using the checkboxes, then click Generate Invoice directly from this tab.

     <Note>
       🖼️ Image placeholder: Screenshot of the Drafts tab showing one draft per customer with Remove, Preview, and Generate actions. Upload from IC:12159947.
     </Note>
7. **Review and submit the invoice.** Open the All Invoices tab to see all summary invoices. New invoices appear in **Pending** status. From **Pending** you can:

   * Preview the invoice document before sending
   * Revert the invoice back to draft (only available while the invoice is in **Pending** status)
   * Submit: click Send Invoice to send the invoice to the customer; status changes to **Invoiced**

Payments on summary invoices are applied at the summary invoice level, not at the individual load level.

## Result

Once submitted, the invoice status is **Invoiced**. All loads included are now associated with the summary invoice record and no longer appear on the Loads Not Invoiced tab.

## Variations

To remove a load from an existing draft before generating: open the Drafts tab, select the draft, and use the checkboxes next to individual load rows to remove them. The Remove action is only available within the draft view, not after the invoice is generated.

## Troubleshooting

### Load not appearing on the Loads Not Invoiced tab

1. Confirm the load is in **Released** or **TONU** status. If the load is still **Incomplete**, complete any outstanding requirements in Batch Invoicing first.
2. Confirm the load's customer has Invoice Type set to Summary in their profile. If the customer is configured for Individual type, the load will not appear on this tab.

### Summary invoice draft not generating

Check the total size of all documents attached to the loads in the draft. The combined file size must not exceed 20 MB. Remove some loads from the draft or reduce document file sizes, then retry.

### Invoice submitted but customer did not receive it

Verify the customer's Delivery Method in their Invoicing Settings. Only Email and EDI are supported for Summary Invoicing. If the delivery method is set to Factoring Company, Online System, or Originals, the invoice will not be delivered automatically.

### Settings change not reflected on generated invoice

1. Remove the affected loads from the draft.
2. Confirm the loads have returned to **Released** status.
3. Save the updated settings.
4. Regenerate the invoice.

## FAQs

**Q: Can I use Summary Invoicing for a customer configured for Individual invoice type?**

**A:** No. The customer must have Invoice Type set to Summary in their profile before their loads appear on the Summary Invoicing page.

**Q: Does Summary Invoicing support Supplemental mode?**

**A:** No. Summary Invoicing supports only the Amendment update mode. Supplemental mode is not supported.

**Q: Can I apply a payment to an individual load within a summary invoice?**

**A:** No. Payments are applied at the summary invoice level, not at the individual load level.

**Q: Is there a file size limit for summary invoices?**

**A:** Yes. The total size of all attached documents included in a single summary invoice must not exceed 20 MB. An error appears if the limit is exceeded.

**Q: Can I include TONU loads in a summary invoice?**

**A:** Yes. Loads in both **Released** and **TONU** status are eligible and appear on the Loads Not Invoiced tab when the customer is configured for Summary type.

**Q: What is Auto Merge and should I leave it on?**

**A:** Auto Merge automatically consolidates all eligible loads for a customer into a single draft. Leave it on unless the customer requires manual control over which loads are grouped together.

**Q: Can I revert a submitted invoice?**

**A:** No. Once an invoice has been submitted (status **Invoiced**), it cannot be reverted. Only invoices in **Pending** status can be reverted to draft.

**Q: Who can access Summary Invoicing?**

**A:** Users with the **"Billing"** and **"ViewPaystubs"** permissions, on accounts where Summary Invoicing is enabled. If you expect access but the menu item is not visible after verifying your permissions, contact Alvys support.

**Q: What delivery methods are supported for Summary Invoicing?**

**A:** Email and EDI only. Factoring Company, Online System, and Originals are not supported.

**Q: What happens if I change a customer's invoicing settings while a draft already exists?**

**A:** Changes do not automatically update existing drafts. Remove the affected loads, confirm they are back in **Released** status, save the updated settings, and regenerate the invoice.

## Go Deeper

* [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing)


# Invoicing Settings
Source: https://docs.alvys.com/en/help/accounting-settlements/invoicing-settings

Configure how Alvys generates and delivers invoices with delivery methods, document requirements, invoice type, AutoMerge, and customer overrides.

Invoicing Settings control how Alvys generates, delivers, and validates invoices across your company. Global defaults are set in Company Profile and can be overridden at the individual customer level.

## Overview

Invoicing Settings (also called billing settings or invoice configuration) give Admins and Partner Admins control over how invoices are generated and delivered. Company-level defaults apply to all customers unless a customer profile overrides them. Five configuration areas are available: Delivery Methods, Document Requirements, Invoice Type, AutoMerge, and the global Invoicing Settings toggle.

## Where to Find It

Navigate to Management > Company Profile > Invoicing Settings ([https://app.alvys.com/#/manage/company-profile](https://app.alvys.com/#/manage/company-profile)) for company-wide defaults.

<Note>
  <img alt="Image of the Invoicing Settings section in Company Profile showing the five configuration areas" />

  *Image of the Invoicing Settings section in Company Profile showing the five configuration areas*
</Note>

To set overrides for a specific customer, open the customer or broker profile and scroll to the Invoicing Settings section.

<Note>
  <img alt="Image of the Invoicing Settings section in Customer/ Broker Profile showing the five configuration areas" />

  *Image of the Invoicing Settings section in Customer/ Broker Profile showing the five configuration areas*
</Note>

## Key Concepts

**Delivery Methods:** Controls how invoices reach the customer. Options are EDI, Email, Factoring Company, Online System, and Originals. Each method determines which integration or address Alvys uses when the invoice is sent.

**Document Requirements:** Specifies which documents must be present on a load before an invoice can be generated. Requirements are set separately for the Released action and the Invoiced action. When **Proof of Delivery** is required, you can also allow a **Bill of Lading** to stand in for a missing POD by turning on **Use BOL if there is no POD** (see [Proof of Delivery and Bill of Lading](#proof-of-delivery-and-bill-of-lading) below).

**Invoice Type:** Sets whether invoices are generated per load (Individual) or grouped into one periodic invoice per customer (Summary). See [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing) for the full workflow when using the Summary type.

**AutoMerge:** Automatically consolidates all loads for a customer into one invoice draft. AutoMerge is required when the customer's Delivery Method is set to Factoring Company; it must be enabled for factoring customers to invoice correctly.

**Invoicing Settings toggle:** When enabled at the company level, these settings apply as the default for all customers. Customer-level settings override the company default for that specific customer only.

## How to Use It

For invoice generation workflows using these settings, see [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing). For the Summary Invoicing workflow, see [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing).

## Proof of Delivery and Bill of Lading

By default, when a subsidiary requires **Proof of Delivery**, only an actual POD document satisfies that requirement. If your operation historically accepted the Bill of Lading in place of the POD (for example, because your BOL carries the delivery signatures), you can opt in per subsidiary.

<Steps>
  <Step title="Open Invoicing Settings for the subsidiary">
    Go to the subsidiary's Invoicing Settings and find the **Required Documents** section.
  </Step>

  <Step title="Require Proof of Delivery">
    Under **Documents Required**, check **Proof of Delivery**.
  </Step>

  <Step title="Allow Bill of Lading as a fallback">
    Check the indented sub-option **Use BOL if there is no POD**. This lets an uploaded Bill of Lading satisfy the POD requirement when no POD is present on the load. Turning this on when Proof of Delivery is not yet required will automatically require Proof of Delivery for you.
  </Step>

  <Step title="Save">
    Your changes save with the rest of the subsidiary's invoicing settings.
  </Step>
</Steps>

<Tip>
  When both a POD and a BOL are uploaded on the same load, the POD always takes priority — the Bill of Lading fallback only applies when there is no POD.
</Tip>

The **Use BOL if there is no POD** setting also controls AutoMerge behavior for the same subsidiary: when it is on and AutoMerge is enabled for Proof of Delivery, a Bill of Lading is merged into the invoice packet as the POD if no POD document is available.

Clearing **Proof of Delivery** also clears **Use BOL if there is no POD** automatically, since there is no POD requirement for it to fall back on.

<Note>
  This behavior is rolling out gradually. Existing subsidiaries keep their prior behavior on day one, so nothing changes for your loads until you turn the setting on. If you don't see **Use BOL if there is no POD** yet, it hasn't been enabled for your workspace — contact Alvys support.
</Note>

## Settings & Permissions

Only Admins and Partner Admins can modify Invoicing Settings in Company Profile. This is controlled by the Company Profile Manager access level.

## Limits & Behavior

Changing invoicing settings after an invoice has already been generated does not update that invoice automatically. To apply updated settings: revert the load to **Released**, update the settings, then regenerate the invoice.

AutoMerge must be enabled for any customer whose Delivery Method is set to Factoring Company.

## FAQs

**Q:** Can I set different invoicing settings for different customers?

**A:** Yes. Set company-wide defaults in Company Profile, then override any setting in the individual customer profile. The customer-level setting takes precedence over the company default.

**Q:** What happens if I change document requirements after an invoice is already generated?

**A:** The change applies to new invoices only. For an existing load, revert it to **Released**, update the requirements, and regenerate the invoice.

**Q:** Is AutoMerge required for all customers?

**A:** AutoMerge is required only when the customer's Delivery Method is set to Factoring Company. For other delivery methods it is optional.

**Q:** Can a Bill of Lading count as the Proof of Delivery on a load?

**A:** Only if the subsidiary has opted in. In the subsidiary's Invoicing Settings, require **Proof of Delivery** and turn on **Use BOL if there is no POD**. With this setting off, a Bill of Lading no longer satisfies a POD requirement — you must upload an actual POD to release or invoice the load. When both are uploaded, the POD always wins.

**Q:** Who can change Invoicing Settings?

**A:** Only Admins and Partner Admins can modify Invoicing Settings in Company Profile.

## Go Deeper

* [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing)
* [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)


# Invoice your customer
Source: https://docs.alvys.com/en/help/accounting-settlements/invoicing-your-customer

Generate and send a customer invoice by email, through a factoring integration, or via an online system or originals.

How an invoice leaves Alvys is set on the customer (and the company default): **Email**, **Factoring Company**, **Online System**, or **Originals**. Set the delivery method first, then generate the invoice. Use the recording that matches how you bill.

## Before you invoice

<CardGroup>
  <Card title="Invoicing settings" icon="gear" href="/en/help/accounting-settlements/invoicing-settings">
    Company and customer defaults: delivery method, document requirements, invoice type, and AutoMerge.
  </Card>

  <Card title="Release a load to billing" icon="file-export" href="/en/help/loads-trips/how-to-release-a-load-to-billing">
    A load has to be released before you can generate an invoice.
  </Card>

  <Card title="Why a load will not invoice" icon="triangle-exclamation" href="/en/help/accounting-settlements/why-can-t-i-release-or-invoice-a-load-in-alvys-and-how-can-i-resolve-it">
    Missing documents, delivery-method mismatches, and other blocks.
  </Card>

  <Card title="Billing status definitions" icon="list" href="/en/help/accounting-settlements/billing-status-definitions">
    What each billing status on a load means.
  </Card>
</CardGroup>

## Invoice by email

<Note>
  If a screen in the video looks different, follow the written steps on this page.
</Note>

<iframe title="Invoicing your customer via email" />

[Open the recording](https://drive.google.com/file/d/1oSrLCafX6VoqaxtnSl7LffOZscBh4XKR/view)

If the email send fails, see [Email submit invoice fails](/en/help/accounting-settlements/email-submit-invoice-fails).

## Invoice through a factoring integration

Set the customer's delivery method to **Factoring Company** and turn on **AutoMerge** — factoring customers require it. Then connect the provider and submit batches.

<CardGroup>
  <Card title="Set up and use factoring" icon="building-columns" href="/en/help/integrations/how-to-set-up-and-use-factoring-in-alvys">
    Notice of Assignment, provider connection, invoice generation, and batch submission.
  </Card>
</CardGroup>

<Note>
  This recording is the same as the email walkthrough. Use the factoring article for provider-specific steps.
</Note>

<iframe title="Invoicing your customer via factoring" />

[Open the recording](https://drive.google.com/file/d/1oSrLCafX6VoqaxtnSl7LffOZscBh4XKR/view)

## Invoice via an online system or originals

Use this when the customer pulls invoices from a portal or still requires paper originals. Set the delivery method on the customer to **Online System** or **Originals**, then generate the invoice the same way.

<iframe title="Invoicing your customer via online system or originals" />

[Open the recording](https://drive.google.com/file/d/1GpA666pusFBUjgwgLJy_1bK94miaKvpb/view)

## Related invoicing

* [Summary invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing) — one periodic invoice per customer
* [Batch invoicing](/en/help/accounting-settlements/batch-invoicing) — generate many invoices at once


# Linehaul Rate Types
Source: https://docs.alvys.com/en/help/accounting-settlements/linehaul-rate-types

Compare Alvys linehaul rate types Flat, Distance, Weight, and Volume, and choose the right load Money Box rate to calculate customer freight charges.

## Overview

Linehaul rate types control how Alvys calculates the line haul amount (also called the linehaul charge or freight rate) on a\*\* load\*\*. Every load in Alvys has a line haul charge in the Money Box, and the rate type you select determines how that charge is calculated. Alvys supports four rate types: Flat, Distance, Weight, and Volume.

The rate type is selected in the Money Box on the load. The Money Box is also where accessorial charges, fuel surcharges, and other customer-facing amounts are configured.

## Where to Find It

Navigate to the load detail page and open the **Money Box**. The rate type selector appears on the Line Haul row.

## Key Concepts

### Flat

A fixed dollar amount for the entire load. Alvys does not multiply the amount by any distance, weight, or volume value. Use Flat when the rate is negotiated as a total lump sum.

<Note>
  <img alt="Money Box showing the Flat rate type selected with a fixed dollar amount entered." />

  *Money Box showing the Flat rate type selected with a fixed dollar amount entered.*
</Note>

### Distance

A rate per mile multiplied by the distance Alvys calculates for the load. Alvys pulls the calculated mileage from the load's routing. If you need to override the mileage, enter the mileage manually on the load before saving the Money Box.

<Note>
  <img alt="Money Box showing the Distance rate type selected, with the rate-per-mile field and the calculated mileage displayed." />

  * Money Box showing the Distance rate type selected, with the rate-per-mile field and the calculated mileage displayed.\*
</Note>

### Weight

A rate per unit of weight multiplied by the weight entered on the load. Weight must be entered on the load for this rate type to calculate.

<Note>
  <img alt="Image showing load weight field on load details page" />

  *Image showing load weight field on load details page*
</Note>

If weight is missing, the line haul amount shows as \$0.00.

<Note>
  <img alt="Money Box showing the Weight rate type selected with the rate-per-unit field and the weight field." />

  \*Money Box showing the Weight rate type selected with the rate-per-unit field and the weight field. \*
</Note>

### Volume

A rate per unit of volume multiplied by the volume entered on the load. Volume must be entered on the load for this rate type to calculate.

<Note>
  <img alt="Image showing load volume field on load details page" />

  *Image showing load volume field on load details page*
</Note>

If volume is missing, the line haul amount shows as \$0.00.

<Note>
  <img alt="Money Box showing the Volume rate type selected with the rate-per-unit field and the volume field." />

  \*Money Box showing the Volume rate type selected with the rate-per-unit field and the volume field. \*
</Note>

### Rate contracts

If the load is linked to a customer contract, Alvys can pull the line haul rate from the contract automatically. The contract rate populates the Money Box rate field. You can override it manually if needed. The rate type set on the contract determines which rate type appears on the load.

See the [Contracted Rates Help Center Article](/en/help/loads-trips/contracted-rates) for more details on configuring contracted rates.

<Note>
  <img alt="Money Box showing a contract rate dropdown" />

  *Money Box showing a contract rate dropdown*
</Note>

## How to Use It

To set or change the line haul rate type on a load, open the load, navigate to the **Money Box**, and select the rate type on the Line Haul row. Enter the rate and any required input (mileage, weight, or volume) and save.

<Note>
  <img alt="Money Box with a rate type selected" />

  \*Money Box with a rate type selected \*
</Note>

For contract-driven loads, the rate type and amount populate automatically from the linked contract. You can override either value.

## Settings & Permissions

* **"EditCustomerRate"**: required to add or change the rate type and rate amount in the Money Box. Users without this permission can view the Money Box but cannot change rate types or amounts.

<Note>
  <img alt="User profile - Edit Customer Rate permissions." />

  *User profile - Edit Customer Rate permissions.*
</Note>

## Limits & Behavior

* Changing the rate type on an existing load recalculates the line haul amount immediately. If the load has already been released to billing, confirm that the billing team is aware of any amount change before saving.
* If the load uses a contract rate and you manually override the amount, the override applies to that load only. The contract rate is not changed.
* Distance rate types use the mileage Alvys calculates from the load's routing by default. Manually entered mileage takes precedence over calculated mileage.
* Weight and Volume rate types require the corresponding input to be non-zero. If the input is missing or zero, the line haul amount will be \$0.00. Enter the weight or volume on the load before finalizing the Money Box.

## FAQs

**Q: What happens to the line haul amount if I change the rate type after the load has been dispatched?**

**A:** The amount recalculates immediately based on the new rate type and the current input values. If the load is already released to billing, notify your billing team of the change before saving.

**Q: Why is my Distance rate showing \$0.00?**

**A:** The calculated mileage on the load may be zero or missing. Check the load's routing and confirm that stops have been entered so Alvys can calculate mileage. If mileage needs to be entered manually, add it to the load before saving the Money Box.

**Q: Why is my Weight or Volume rate showing \$0.00?**

**A:** Weight or volume has not been entered on the load, or the value is zero. Enter the correct weight or volume on the load and then save the Money Box.

**Q: Can I use a different rate type for different trips on the same load?**

**A:** No. The rate type is set at the load level in the Money Box. All trips on the load share the same line haul rate type.

**Q: Who can change the rate type on a load?**

**A:** Users with the **"EditCustomerRate"** permission can change the rate type and amount in the Money Box. Contact your Alvys Admin if you need this permission enabled.

## Go Deeper

* [Contracted Rates](/en/help/loads-trips/contracted-rates)
* [Rates Permissions](/en/help/administration/rates-permissions)


# Managing and Troubleshooting IFTA Reporting in Alvys
Source: https://docs.alvys.com/en/help/accounting-settlements/managing-and-troubleshooting-ifta-reporting-in-alvys

This guide provides step-by-step instructions for generating reports, resolving common issues, and managing truck assignments and fuel transactions.

## Overview of IFTA Reporting in Alvys

The IFTA (International Fuel Tax Agreement) reporting module in Alvys allows users to generate, manage, and troubleshoot fuel tax reports for their fleet. This guide provides step-by-step instructions for generating reports, resolving common issues, and managing truck assignments and fuel transactions.

## Steps to Generate IFTA Reports

To generate an IFTA report in Alvys:

1. **Access the IFTA Reporting Section**: - Navigate to **Reports** in Alvys and select **IFTA**. This opens the IFTA dashboard where you can filter by quarter, year, status, and subsidiary.
2. **Select the Desired Quarter and Truck**: - Choose the quarter you want to view and select the specific truck.
3. **Generate and Download the Report**: - Scroll down, click on **Generate Report**, and download the report. Ensure all required data (fuel and miles) is available for the selected truck.

## Troubleshooting Common Issues

### 1. Inactive Generate Button

* Ensure all trucks in the selected fleet are marked as "Ready." Unselect any trucks that aren’t ready or update their status to "Ready" before generating the report.
* Verify that a fuel source is selected and required data (fuel and miles) is displayed.

### 2. Missing Trucks in the Report

* If a truck is missing, check if it has been assigned or activated for the specific report. Update the truck’s assignment or profile in the system, then sync the IFTA report.

### 3. No Fuel Transactions

* If fuel transactions are missing, ensure they are assigned to the correct truck. Transactions assigned to a different truck will not appear in the intended truck’s records.
* Confirm that the required fuel purchase data has been uploaded for the selected quarter and year.

### 4. Report Not Generating for a Quarter

* If no report is generated, verify that fuel transactions exist for the selected quarter. For example, if loads or transactions start in April, they will fall under Q2 instead of Q1.

## Managing Truck Assignments and Profiles

### Adding a Truck to the IFTA Report

1. Open the truck’s profile in Alvys.
2. Go to **Truck Details** and add a **Start Date** for the truck.
3. Save or update the truck.
4. Sync the IFTA report to pull in the updated truck record.
5. Set the truck’s source to "Manual" and upload its miles in the IFTA report.

### Syncing Truck Profiles

* Open the truck’s profile and click the **Sync** button. After syncing, re-generate or view the IFTA report for the desired quarter.

## Handling Fuel Transactions

### Viewing Fuel Transactions by Truck

* Fuel uploaded through the IFTA module appears only within the IFTA module. To view transactions by truck, open the IFTA report and click on the specific truck number.

### Adding Fuel Transactions

* Fuel transactions can only be added at the truck level. Ensure the truck is displayed for the quarter by adjusting its start date if necessary. Add the fuel to the truck, then revert the start date afterward if needed.

## FAQs

### Why can’t I generate an IFTA report for my fleet?

Ensure all trucks are marked as "Ready" and that required data (fuel and miles) is available.

### Why is a truck missing from the IFTA report?

Check the truck’s assignment and activation status. Update and sync the truck’s profile if necessary.

### What should I do if fuel transactions are missing?

Verify that transactions are assigned to the correct truck and that fuel purchase data has been uploaded.


# Pay Dispatchers
Source: https://docs.alvys.com/en/help/accounting-settlements/pay-dispatchers

Run dispatcher commission statements in the Pay Dispatchers module: assign dispatchers to trips, set the global statement and cutoff dates, and process pay.

<Note>
  📋 **Module:** Accounting > Pay Dispatchers
</Note>

<Warning>
  ⚠️ Pay Dispatchers is an optional module that is not enabled by default. Contact Alvys support to request activation at the account level.
</Warning>

## Overview

The Pay Dispatchers module (dispatcher pay, dispatcher commissions, dispatcher payouts) manages dispatcher commission calculations and payment statements directly within Alvys. Once enabled, it appears under **Accounting** and lets you assign dispatchers to trips, configure commission rates, generate pay statements, and track payment status.

## Where to Find It

Go to **Accounting > Pay Dispatchers** after the module has been enabled for your account. The module has two primary areas: the **Unassigned** tab for trips without a dispatcher assigned, and individual dispatcher tabs showing each dispatcher's trips, commissions, and statement history. The **Statements** tab shows all generated statements.

## Key Concepts

### Statement statuses

Dispatcher pay statements move through four statuses:

**Unpaid** is the initial state. Trips and accessorials are available but no statement has been created.

**Draft** is the editing phase. A draft is created by selecting trips and accessorials and clicking **Save as Draft**. Drafts can be edited, emailed, downloaded, or reverted. A draft can be downloaded immediately after creation or from the Statements tab.

**Processed** means the statement has been finalized. Processed statements cannot be edited. They can be reverted, emailed, or downloaded. A statement moves to Processed by clicking **Generate Statement** from a draft, or directly from unpaid trips.

**Paid** is set manually. To mark a statement as paid, open the dispatcher profile, go to the **Statements** tab, open the dropdown next to the statement, select **Paid**, complete the **Change Paystub Status to Paid** dialog, and click **Save**.

### Global Statement Date and local statement date

The **Global Statement Date** applies to all dispatchers in a payment run unless overridden. A **local statement date** set on an individual dispatcher's tab applies only to that dispatcher's statement and overrides the global date for them.

### Cutoff Date

The Cutoff Date filters which trips appear for payment. Only trips with a delivery date on or before the Cutoff Date are included in the current run.

## How to Use It

### Assigning a dispatcher to unassigned trips

Trips that have no dispatcher assigned appear in the **Unassigned** tab. These trips can carry any of the following statuses: **TONU**, **Delivered**, **Released**, **Queued**, **Invoiced**, **Financed**, or **Completed**.

1. Select the trips you want to assign using the checkboxes.
   <img alt="Image showing trip rows selected via checkboxes in the Unassigned tab." />
   *Image showing trip rows selected via checkboxes in the Unassigned tab.*
2. Click **Assign Dispatcher**.
3. Select a dispatcher from the dropdown.
4. Click **Save**.

<Note>
  <img alt="Image showing the Assign Dispatcher dropdown with a dispatcher selected and the Save button." />

  *Image showing the Assign Dispatcher dropdown with a dispatcher selected and the Save button.*
</Note>

A success message confirms the assignment. The trips move from the Unassigned tab to the assigned dispatcher's tab.

<Note>
  <img alt="Image showing the success confirmation message after assigning a dispatcher to trips." />

  *Image showing the success confirmation message after assigning a dispatcher to trips.*
</Note>

### Setting the Global Statement Date and Cutoff Date

1. Enter a date in the **Global Statement Date** field at the top of the module. Tooltips explain the effect of each date field.
2. Enter a date in the **Cutoff Date** field. Only trips delivered on or before this date are included in the run.

<Note>
  <img alt="Image showing the Global Statement Date and Cutoff Date fields with tooltips visible." />

  *Image showing the Global Statement Date and Cutoff Date fields with tooltips visible.*
</Note>

### Filtering dispatchers

Use the dispatcher filter to navigate when working with a large number of dispatchers.

<Note>
  <img alt="Image showing the dispatcher filter in use." />

  *Image showing the dispatcher filter in use.*
</Note>

### Configuring commission rates for a dispatcher

A dispatcher tab appears for each user who meets all three conditions: active account, Dispatcher role, and payment details configured on their profile.

1. Open the dispatcher's tab.
2. Set the **trip commission**: either a fixed amount per trip or a percentage of the trip value.
3. Set the **accessorial commission**: percentage of accessorial value only.
4. Select the accessorials to include using the checkboxes.
5. Click **Save**.

<Note>
  <img alt="Image showing the trip commission field, accessorial commission field, and accessorial checkboxes." />

  *Image showing the trip commission field, accessorial commission field, and accessorial checkboxes.*
</Note>

### Setting a local statement date

Enter a date in the **local statement date** field on the individual dispatcher's tab. This overrides the Global Statement Date for that dispatcher's statement only.

<Note>
  <img alt="Image showing the local statement date field on an individual dispatcher tab." />

  *Image showing the local statement date field on an individual dispatcher tab.*
</Note>

### Creating a draft statement

1. From a dispatcher's tab, select the trips and accessorials to include.
2. Click **Save as Draft**.

<Note>
  <img alt="Image showing selected trips and accessorials with the Save as Draft button." />

  *Image showing selected trips and accessorials with the Save as Draft button.*
</Note>

The draft appears in the Statements tab and can be edited, emailed, or downloaded immediately.

<Note>
  <img alt="Image showing a draft statement in the Statements tab with Edit, Email, Download, and Revert actions." />

  *Image showing a draft statement in the Statements tab with Edit, Email, Download, and Revert actions.*
</Note>

### Generating a processed statement

To generate from a draft, open the draft and click **Generate Statement**. To generate from unpaid trips directly, select trips and accessorials and click **Generate Statement** without saving a draft first.

The statement moves to **Processed** status and can be emailed or downloaded. Use **Revert** to move it back to Draft if changes are needed.

### Marking a statement as paid

1. Open the dispatcher profile and go to the **Statements** tab.
2. Open the dropdown next to the statement and select **Paid**.
3. Complete the **Change Paystub Status to Paid** dialog.
4. Click **Save**.

<Note>
  <img alt="Change Paystub Status to Paid dialog" />

  *Change Paystub Status to Paid dialog*
</Note>

## Settings & Permissions

Pay Dispatchers is enabled at the account level upon request. Contact Alvys support to request activation. Once enabled, generating and managing dispatcher pay statements requires the relevant pay permissions: **"PayDriver"** and **"EditPaystubs"** to create and edit statements, and **"ViewPaystubs"** to view them. Contact your Alvys Admin if any action is unavailable.

## Limits & Behavior

A dispatcher tab only appears for users who meet all three conditions: active account, Dispatcher role, and payment details configured on their profile.

Accessorial commissions are percentage-based only. Trip commissions can be set as either a fixed amount per trip or a percentage of the trip value.

A draft statement can be downloaded immediately after creation without navigating to the Statements tab.

A Processed statement cannot be edited. Click **Revert** to move it back to Draft status, make changes, and generate it again.

## FAQs

**Q:** How do I get Pay Dispatchers enabled for my account?

**A:** Contact Alvys support to request activation. Pay Dispatchers is not enabled by default and is activated at the account level upon request.

**Q:** Why is a dispatcher not appearing in the Pay Dispatchers module?

**A:** A dispatcher only appears when all three conditions are met: their account is active, their user role is set to Dispatcher, and payment details are configured on their profile. Check each of these if a dispatcher is missing.

**Q:** Can I set different commission rates for different dispatchers?

**A:** Yes. Commission rates are configured per dispatcher from each dispatcher's individual tab within the module.

**Q:** What is the difference between the Global Statement Date and the local statement date?

**A:** The Global Statement Date applies to all dispatchers in a payment run. A local statement date set on an individual dispatcher's tab applies only to that dispatcher and overrides the global date for their statement.

**Q:** Can I revert a statement that has already been sent to a dispatcher?

**A:** Yes. A Processed statement can be reverted to Draft status using the **Revert** action. After reverting, you can edit the draft and generate a new statement.


# Paystub Layout Templates
Source: https://docs.alvys.com/en/help/accounting-settlements/paystub-layout-templates

Preview and switch the active Alvys paystub layout template used for driver, owner operator, and truck statements from your Company Profile settings.

Alvys offers multiple paystub layout template options (paystub designs, statement layouts) for driver statements. Admins and PartnerAdmins can preview and switch the active layout at any time from Company Profile.

## Overview

Alvys offers several layout options for the design of driver paystubs, owner operator paystubs, and truck paystubs. The active layout is applied whenever a paystub is generated. The preferred layout can be changed at any time.

## How It Works

The active paystub layout is stored at the company level and applied automatically whenever a paystub is generated. The process of generating paystubs remains unchanged; the system checks the active layout in the background. Changing the layout takes effect for paystubs generated after the change and does not alter paystubs that were already produced. The same active layout applies to all Driver, Owner Operator, and Truck paystubs across the company.

## How to Use It

You must have the **Admin** or **PartnerAdmin** role to access Company Profile settings.

1. Click your user profile icon in the bottom left corner of Alvys.
2. Select **Company Profile** from the menu.
3. On the Company Profile page, click the **General Info** tab.
4. Scroll to the bottom of the tab to find the **Driver Paystub Templates** section.

   <img alt="Image showing the Driver Paystub Templates section in Company Profile > General Info, with layout cards visible" />

   *Image showing the Driver Paystub Templates section in Company Profile > General Info, with layout cards visible*
5. To preview a layout before selecting it, click the **eye icon** on any layout card.
6. To select a layout, click the **tick icon** on the layout card you want to activate.
7. Click **Yes** on the confirmation screen to confirm your selection.

   <img alt="Image showing the confirmation screen after clicking the tick icon to select a paystub layout" />

   *Image showing the confirmation screen after clicking the tick icon to select a paystub layout*

After confirming, the active layout is indicated by a green card and a green eye icon in the Driver Paystub Templates section. The selected layout is applied to all Driver, Owner Operator, and Truck paystubs going forward.

To change the layout later, return to **Management > Company Profile > General Info > Driver Paystub Templates** and repeat these steps to select a different layout.

## Troubleshooting

### Layout change does not appear on a recently generated paystub

Confirm the new layout was set to active before the paystub was generated. A layout change only applies to paystubs generated after the change was made. Regenerate the paystub to apply the updated layout.

### Driver Paystub Templates section is not visible

Confirm you are on the **General Info** tab in Company Profile, not a different tab. Scroll to the very bottom of the General Info tab, where the section appears at the end of the page. Contact Alvys support if the section is still not visible after scrolling to the bottom.

### Tick icon is not responding

Confirm you have the **Admin** or **PartnerAdmin** role. Users without these roles cannot change the paystub layout template. Refresh the page and try again. Contact Alvys support if the issue persists.

## FAQs

**Q: Does changing the layout affect paystubs that have already been generated?**

**A:** No. The layout change only applies to paystubs generated after the change is made. Paystubs that were already generated retain the layout that was active at the time they were created.

**Q: Can different drivers use different paystub layouts?**

**A:** No. The selected layout applies to all paystubs across the company, including Driver, Owner Operator, and Truck paystubs.

**Q: How do I know which layout is currently active?**

**A:** The active layout is indicated by a green card with a green eye icon in the Driver Paystub Templates section.

## Go Deeper

* [Driver Settlements](/en/help/accounting-settlements/driver-settlements-faq)


# Time Based Pay in Driver Settlements
Source: https://docs.alvys.com/en/help/accounting-settlements/time-based-pay-in-driver-settlements

Pay drivers by hours worked or by day in driver settlements, combine time based pay with mileage and per diem rate types, and surface the Hours Worked column.

<Note>
  📋 **Module:** Accounting > Driver Settlements
</Note>

<Tip>
  💡 If you are new to Driver Settlements, read the [Driver Settlements](/en/help/accounting-settlements/driver-settlements) article before starting this one.
</Tip>

## Overview

Time-based pay (time-based compensation, hourly and per-diem pay) in Driver Settlements lets you compensate drivers using hourly, daily, or per-diem rates instead of, or alongside, trip-based pay. Driver Settlements supports four time-based rate types: **Hourly Pay**, **Daily Pay**, **Daily Per Diem**, and **Mileage Per Diem**.

Hourly Pay is entered per trip through the Hours Worked column in the Trips table. Daily Pay and Daily Per Diem are added per calendar day from within Driver Settlements. Mileage Per Diem calculates automatically based on miles driven.

## Before You Start

To add driver rates and access Driver Settlements you need the relevant pay permissions. Adding and editing pay plans requires the **"ViewPayPlans"** and **"EditPayPlans"** permissions, and generating or editing settlements requires the **"PayDriver"** and **"EditPaystubs"** permissions. Contact your Alvys Admin if any action is unavailable.

The driver must have at least one rate of type **Hourly Pay**, **Daily Pay**, **Daily Per Diem**, or **Mileage Per Diem** configured on their profile before time-based payables appear in Driver Settlements.

## Steps

1. Open the driver record.
2. Go to **Drivers** and select the driver you want to configure.
3. Scroll to the **Rates** section on the driver profile.
   <img alt="Image showing the Rates section on a driver profile." />
   *Image showing the Rates section on a driver profile.*
4. Add a time-based rate.
5. Click **Add Rate**.
6. Choose one of the four time-based rate types: **Hourly Pay**, **Daily Pay**, **Daily Per Diem**, or **Mileage Per Diem**.
7. Enter the pay amount for the selected rate type.
8. For **Mileage Per Diem** only, select the mileage type to use as the basis for calculation (**Total Miles**, **Loaded Miles**, or **Empty Miles**).
9. Click **Save**. The rate appears immediately in the Rates section and is available in Driver Settlements.
   <img alt="Image showing the Add Rate dialog with time-based rate type options selected." />
   *Image showing the Add Rate dialog with time-based rate type options selected.*
10. Add daily pay or per diem days in Driver Settlements. This applies to **Daily Pay** and **Daily Per Diem** rate types only. For Hourly Pay and Mileage Per Diem, continue to the next step.
11. Go to **Accounting > Driver Settlements** and select the driver.
12. Locate the **Daily Pay** or **Per Diem** section in the driver's settlement view.
13. Click **Manage Calendar**.
14. Select the days to apply the daily pay or per diem.
15. Click **Save**. Each selected day generates a separate payable row in the driver's settlement.
    <img alt="Image showing the Manage Calendar view with days selected for Daily Pay or Per Diem." />
    *Image showing the Manage Calendar view with days selected for Daily Pay or Per Diem.*
16. Enter hours worked on a trip. This applies to **Hourly Pay** rate types.
17. In the Trips table within Driver Settlements, locate the **Hours Worked** column. If the column is not visible, drag the column separator to expand it into view.
18. Click on the trip to open the **Edit Trip** modal.
19. Enter the hours and minutes worked on that trip.
20. Click **Save**. The system converts the time entry automatically and calculates the hourly payable based on the driver's configured Hourly Pay rate.
    <img alt="Image showing the Hours Worked column in the Trips table and the Edit Trip modal with hours and minutes fields." />
    *Image showing the Hours Worked column in the Trips table and the Edit Trip modal with hours and minutes fields.*
21. Review generated payables.
22. Open the trip in Driver Settlements.
23. Review the generated payable rows. Hourly Pay produces a per-hour pay row calculated from the hours entered in the previous step. Mileage Per Diem produces a mileage-based row calculated from the mileage type selected when the rate was added.
24. Select the payables you want to include.
25. Add them to a pay period, a draft, or a bulk statement.

## Result

Time-based payable rows appear in the driver's settlement alongside trip-based payables. They can be included in any pay period, draft, or bulk statement using the same workflow as standard payables.

## Variations

### Using Mileage Per Diem instead of Daily Per Diem

Mileage Per Diem calculates automatically from trip mileage and does not require calendar day selection. Configure the mileage type (Total, Loaded, or Empty Miles) on the rate when adding it, and payable rows appear automatically based on trips in the settlement.

### Combining rate types

A single driver can have multiple time-based rates configured simultaneously. For example, a driver can have both Hourly Pay and Daily Per Diem active at the same time. Each rate generates its own payable rows in Driver Settlements.

## Troubleshooting

### Hours Worked column is not visible in the Trips table

1. Scroll horizontally across the Trips table. The Hours Worked column may be positioned to the right of the visible columns.
2. If the column is collapsed, drag the column separator toward the right to expand it into view.
3. Right-click any column header and select **Configure Columns** to confirm that Hours Worked is enabled. If it is not listed, contact Alvys support.

### Daily Pay or Per Diem section is not visible in the driver's settlement

1. Confirm the driver has a **Daily Pay** or **Daily Per Diem** rate configured on their profile. The section only appears when at least one of these rate types is active.
2. Verify the rate was saved correctly by returning to **Drivers > \[Driver Name] > Rates**.
3. Contact Alvys support if the section is still not visible after confirming the rate is configured.

### Payable rows are not appearing after saving calendar days

1. Confirm you clicked **Save** in the Manage Calendar view. Changes are not applied until saved.
2. Refresh the Driver Settlements page and check the driver's settlement again.
3. Contact Alvys support if the payable rows are still missing after saving and refreshing.

## FAQs

**Q:** Can I add a layover pay rate or a per-hour detention rate?

**A:** Layover pay and per-hour detention rates are not available as native time-based rate types today. As a workaround, add them as manual line items using **New Transaction** on the driver's settlement. Native rate type support for layover and detention is on the roadmap.

**Q:** Can I apply a time-based rate to only certain trips and not others?

**A:** Mileage Per Diem applies automatically to all trips that match the selected mileage type. Hourly Pay applies only to trips where you manually enter hours in the Hours Worked column. Daily Pay and Daily Per Diem apply to the calendar days you select in Manage Calendar, independent of specific trips.

## Go Deeper

* [Driver Settlements](/en/help/accounting-settlements/driver-settlements)


# Asset Map
Source: https://docs.alvys.com/en/help/assets-fleet/asset-map

Track every truck and trailer on one live map in Assets > Map. Filter by status, toggle traffic and weather layers, and speed up dispatch decisions.

## Overview

The Asset Map (also called the fleet map, live map, asset tracking map, or truck map) gives you a real-time, bird's-eye view of your entire fleet: every truck and trailer on a single interactive map. Use it to locate assets instantly, check statuses without switching screens, and make faster dispatch and routing decisions.

To open the Asset Map, go to Assets > Map in the side navigation. The map loads automatically with all fleet assets plotted.

The Asset Map is included for all Alvys accounts at no additional cost. There is nothing to enable or purchase. Users need either the **"ViewTrucks"** or **"ViewTrailers"** permission to access the map; users with only one of the two permissions can still access it and will see the asset types covered by their permission. Asset positions are populated automatically once a tracking integration is connected to Alvys.

## How it works

### Asset icons

Each asset type appears as a distinct icon on the map:

* Trucks appear as blue squares.
* Trailers appear as red dots.
* Trips (trucks on an active trip) appear as green triangles.

When a truck and trailer share an active trip, only the truck icon appears on the map. The trailer is hidden to avoid duplicate markers for the same moving rig.

### Clustering

When you are zoomed out and many assets are close together, the map automatically groups them into numbered circle clusters. Click a cluster or zoom in to expand it and see individual assets. You can turn clustering off in the Map layers menu.

### Last Modified timestamp

The asset sidebar shows a Last Modified timestamp: the moment the asset's location was last received from the connected tracking provider. Use this to assess how current the position data is.

## How to use

### Filtering

The controls at the top of the map let you narrow what is displayed:

* Asset type: All, Trucks, or Trailers, shown as a segmented control with live counts.
* Status (via the Filters button): All, Active, or Inactive, which filters by the asset's record-level active status.

### Map layers

Open the Map layers menu to toggle:

* Clustering: group nearby assets into numbered circles when zoomed out.
* Traffic: overlay real-time road traffic conditions.
* Weather (Beta): overlay weather radar and road conditions. Available when enabled for your account.
* Events (Beta): overlay severe weather event markers on the map. Available when enabled for your account.
* Map style: switch between Default (street map) and Satellite views.

### Search

Use the search bar at the top of the map to jump directly to a truck number, trailer ID, driver name, trip number, or address.

### Right-click tools

Right-click anywhere on the map to access:

* Copy coordinates: copies the latitude and longitude of the clicked point to your clipboard.
* Center here: re-centers the map on the clicked point.
* Measure driving distance: calculates the driving distance between two points you select on the map.
* Open in Google Maps: opens that location in Google Maps in a new tab.

### Truck sidebar

Click a truck on the map to open a sidebar showing the truck ID, current status, source, operating status, fuel level, odometer, ELD ID, current address, last modified timestamp, assignment preference, notes, and recent events. Click Edit in the sidebar to open the full truck profile.

### Trailer sidebar

Click a trailer on the map to open a sidebar showing the trailer name and ID, current status, source, operating status, power status, ambient temperature, ELD ID, current address, last modified timestamp, notes, and recent events. Click Edit in the sidebar to open the full trailer profile.

### Trip route

When you click a truck that is on an active trip, the sidebar shows a View Trip button. Click it to render the trip route on the map and see trip details in a panel on the right side of the screen.

The Load Details page also displays a map showing the route for a specific load. That view is display-only. The full interactive experience, including filters, search, right-click tools, and clustering, is available only in Assets > Map.

### Related how-to articles

* How to navigate and filter the Asset Map
* How to view asset and trip details on the Asset Map

## Troubleshooting

### Asset shows a stale or old location

Asset positions are updated from your connected tracking provider. If an asset shows a stale location, check that the tracking device on that asset is connected and transmitting. The Last Modified timestamp in the sidebar tells you when the last position update was received. If the device appears connected but the position is still not updating, contact Alvys support.

### Weather or Events overlays are missing from the Map layers menu

Weather and severe weather event overlays are available as Beta features. If you do not see the Weather or Events options in the Map layers menu, contact Alvys support to ask about enabling them for your account.

## FAQs

**Q:** How do I access the Asset Map?

**A:** Go to Assets > Map in the side navigation. The map loads automatically with all fleet assets plotted.

**Q:** Is the Asset Map an add-on? Do I need to pay extra?

**A:** No. The Asset Map is included for all Alvys accounts at no additional cost. There is nothing to purchase or enable.

**Q:** What do the different icons mean?

**A:** Blue squares are trucks, red dots are trailers, and green triangles are trucks on an active trip. Trailers that are hitched to a truck on the same active trip are hidden; the truck icon represents the rig.

**Q:** Why do I see numbered circles instead of individual assets?

**A:** Those are clusters. The map groups nearby assets together when you are zoomed out. Zoom in or click a cluster to see individual assets. You can also turn clustering off in the Map layers menu.

**Q:** Why does an asset show an old location?

**A:** Asset positions depend on data received from the connected tracking provider. Check the Last Modified timestamp in the asset sidebar. If the timestamp is stale, verify that the tracking device on that asset is connected and transmitting. If the device appears connected but the position is still not updating, contact Alvys support.

**Q:** Can I filter to see only active trucks?

**A:** Yes. Use the asset type segmented control to select Trucks, then open the Filters menu and set Status to Active.

**Q:** Can I see the route for a trip?

**A:** Yes. Click a truck that is on an active trip, then click View Trip to render the route on the map.

**Q:** Is weather available on the map?

**A:** Weather and severe weather event overlays are available as Beta features. If you do not see the Weather or Events options in the Map layers menu, contact Alvys support to ask about enabling them for your account.


# Default Equipment
Source: https://docs.alvys.com/en/help/assets-fleet/default-equipment

Pre-select a default trailer type at the subsidiary or customer level so new loads auto-fill equipment and dispatchers skip repeat data entry.

## Overview

Default Equipment lets you pre-select a trailer type at the subsidiary level or on an individual customer profile so that loads are created with the correct equipment type automatically, reducing manual entry.

Default Equipment is a trailer type pre-selection that Alvys applies automatically when a new load is created. You can configure it in two places: on a subsidiary (which applies to all loads created under that subsidiary) and on a customer profile (which applies to loads created for that specific customer). A customer-level default takes precedence over the subsidiary-level default. If a default has been set at both levels, the customer-level value is used. If neither level has a default set, the equipment type field is left blank on the load entry form and the dispatcher fills it in manually. Equipment length is not required when completing load entry.

## Where to Find It

**Subsidiary-level default**

Open the navigation menu and go to Management > Company Profile. Select the subsidiary you want to configure. The Default Equipment field appears in the subsidiary settings.

<img alt="Screenshot showing the Default Equipment Type dropdown open with trailer type options" />

*Screenshot showing the Default Equipment Type dropdown open with trailer type options*

**Customer-level default**

Open the navigation menu and go to Companies. Find and open the customer record. Edit the customer profile. The Default Equipment field appears in the customer details section.

<img alt="Screenshot showing the Default Equipment field on a customer profile" />

*Screenshot showing the Default Equipment field on a customer profile*

<img alt="Screenshot showing the Default Equipment selection dropdown on a customer profile with trailer type options" />

*Screenshot showing the Default Equipment selection dropdown on a customer profile with trailer type options*

## Key Concepts

**Subsidiary-level default:** A trailer type assigned to a subsidiary that pre-fills the equipment type on all new loads created under that subsidiary. This is useful when a company primarily ships on one trailer type.

**Customer-level default:** A trailer type assigned to a specific customer profile that pre-fills the equipment type on loads created for that customer. This setting takes precedence over the subsidiary-level default.

**Load-level override:** A dispatcher can always change the equipment type on an individual load at the time of entry, regardless of any subsidiary or customer default. The hierarchy is load-level, then customer-level, then subsidiary-level.

**Blank equipment:** If no default is configured at either level, the equipment type field is left blank on load entry and must be filled in manually. This is the expected behavior; Alvys does not force a selection.

## How to Use It

For step-by-step instructions on setting or removing the equipment type default on a subsidiary or customer profile, refer to the relevant configuration guide for your role.

## Settings and Permissions

Access to configure the subsidiary-level default is restricted to users with the **"Admin"** or **"Partner Admin"** role. These users reach the setting through Management > Company Profile.

Access to configure the customer-level default is available to all users except Drivers. These users reach the setting through Companies, then open the customer, then edit the profile.

## Limits and Behavior

Equipment length is not a required field on load entry.

If both a customer-level and a subsidiary-level default are defined, the customer-level default applies to loads created for that customer.

If neither a customer-level nor a subsidiary-level default is defined for a load, the equipment type field is left blank. The dispatcher must select an equipment type manually on load entry.

The default equipment type is applied at the time the load is created, whether the load is created by manual entry or by accepting an EDI tender. The dispatcher can override the pre-filled value before saving the load.

## FAQs

**Q:** Will changing the default equipment on a subsidiary update existing loads?

**A:** No. The default only applies to new loads created after the change. Existing loads are not affected.

**Q:** Can I set different defaults for different customers?

**A:** Yes. Each customer profile has its own Default Equipment field. Set the field on each customer record individually. Customers without a customer-level default will use the subsidiary-level default, if one is configured.

**Q:** What happens if the equipment type on an EDI tender does not match the default?

**A:** The equipment type sent in the EDI tender takes precedence over both the subsidiary and customer defaults when Alvys creates a load from the tender. Contact Alvys support if the tender equipment type is not appearing correctly on the created load.


# Driver Companion Mobile App
Source: https://docs.alvys.com/en/help/assets-fleet/driver-companion-mobile-app

Install the Alvys Driver Companion app to log in by phone, view trips, check in at facilities, upload BOL and POD, and submit eChecks on the go.

<Note>
  The Driver Companion mobile app lets drivers log in by phone number, set their availability, view assigned trips, check in and out at facilities, upload documents, and submit eChecks from their phone.
</Note>

## Overview

The Driver Companion mobile app (also called the Alvys driver app, the mobile app, or the driver companion app) is the driver-facing mobile app for Alvys. It is built for a mobile phone and gives drivers everything they need on the road: setting online or offline availability, viewing assigned and upcoming trips, opening load details, uploading documents such as Bill of Lading and Proof of Delivery, checking in and out at facilities, viewing paystubs, and generating eChecks.

Before you log in, your company's designated admin must have set up a driver profile for you. Your cell phone number is your login credential and identifies the account your admin created in Alvys.

<iframe title="YouTube video" />

Are you ready to take your driving experience to the next level? Whether you're a seasoned driver or just getting started, our mobile app is designed to streamline your journey, providing convenience, efficiency, and safety every step of the way.

**Before you login, it's important to ensure that your company’s designated admin has set up a driver profile for you.**

In this guide, we'll walk you through the ins and outs of our driver mobile app, from installation to advanced features. By the end, you'll be equipped with the knowledge and tools to make the most out of your driving experience.

Let's dive in!

## Getting logged in:

**Step 1: Installation**

First things first, let's get the app installed on your device. Use the QR codes below, or head over to your app store (Google Play Store for Android or the App Store for iOS) and search for "Alvys." Once you find it, simply tap on the "Install" button and wait for the download to complete.

[Click here or scan below to open Alvys in the Google Play Store](https://play.google.com/store/apps/details?id=io.alvys.alvys)

<img alt="Notion Image" />

<img alt="Notion Image" />

Open Alvys in the Apple App Store: [https://apps.apple.com/us/app/alvys-driver-companion/id1532778131](https://apps.apple.com/us/app/alvys-driver-companion/id1532778131)

<img alt="Notion Image" />

<img alt="Notion Image" />

<Note>
  <img alt="Notion Image" />
</Note>

### Logging in with your phone number

Your cell phone number serves as your login credential and identifies your account created in Alvys by your company's admin. Enter your cell phone number to log in. If your account has not been set up by the admin, you will not be able to proceed.

Be sure to accept any and all permissions from the app upon logging in.

<img alt="Phone number login screen." />

\*Phone number login screen. \*

### Online or offline availability

In the top left-hand corner of the app, there is a toggle button to set yourself either online or offline. This feature indicates your current availability to dispatchers and admins.

When you set yourself as **Online**, you are actively working and available for assignments. Dispatchers and admins will see your status as available and can assign trips accordingly.

<img alt="Online status toggle" />

*Online status toggle*

When you set yourself as **Offline**, you are taking a break or refreshing on hours. During this time you will not receive trip assignments, and your status will display as unavailable to dispatchers and admins.

<img alt="Offline status toggle." />

*Offline status toggle.*

Using this feature lets you manage your work hours and availability for a balanced and efficient workflow.

### Load visibility on the home screen

Staying on top of your assigned and upcoming trips is key to a smooth journey. The app gives you access to the information you need right from the home screen.

Upon logging in, the home screen provides a snapshot of your current workload. You will find a list of assigned and upcoming trips displayed for quick access.

<img alt="Home screen trip list." />

*Home screen trip list.*

Each trip listed on the home screen contains essential details such as pickup and delivery locations, scheduled times, and any specific instructions.

<img alt="Trip details preview." />

*Trip details preview.*

* **Accessing Load Details and Uploading Documents**

  With a simple tap on any trip from the home screen, you can access comprehensive load details and manage important documents seamlessly.
* **Load Details**: Dive deeper into each trip to view essential information such as pickup/delivery locations, scheduled times, and load specifics.
* **Document Upload**: Need to upload crucial documents like accessorial receipts, Bill of Lading (BOL), or Proof of Delivery (POD)? Our app allows you to upload and store these documents securely, ensuring compliance and transparency every step of the way.

  For detailed instructions on how to upload documents, check out our guide [here](https://alvys.com/help/mobile-application/driver-app-how-to-upload-multiple-documents/).
* **Facility Check-In/Out**
* **Check-In:** Once you are within 10 miles of the facility, you can update your status to notify dispatchers and administrators of your arrival. If you attempt to check in outside of this radius, the app will prompt you to move closer to the facility.
* **Check-Out:** There is no radius requirement for Check-Out. Drivers can update their status regardless of location once work at the facility is completed.

  <img alt="Facility check-in and check-out screen." />

  *Facility check-in and check-out screen.*

## How to Use It

1. **Log in with your phone number.** Open the app and enter the cell phone number your admin used to set up your driver profile. Accept any and all permissions the app requests so features such as availability status and tracking work correctly.
2. **Set your availability.** Use the toggle in the top left-hand corner to set yourself **Online** when you are available for assignments, or **Offline** when you are on a break or refreshing on hours.
3. **Review your trips.** From the home screen, review your assigned and upcoming trips, including pickup and delivery locations, scheduled times, and any specific instructions.
4. **Open load details.** Tap any trip from the home screen to open Load Details and view essential information such as pickup and delivery locations, scheduled times, and load specifics.
5. **Upload documents.** From a load, upload and store files such as accessorial receipts, Bill of Lading (BOL), and Proof of Delivery (POD) securely, supporting compliance and transparency. For detailed instructions on uploading documents, see the document upload guide at [https://alvys.com/help/mobile-application/driver-app-how-to-upload-multiple-documents/](https://alvys.com/help/mobile-application/driver-app-how-to-upload-multiple-documents/).
6. **Check in at a facility.** When you reach the facility, update your status to notify dispatchers and administrators of your arrival. The app uses your location to confirm you are at the facility; if you are too far away, it will prompt you to move closer before you can check in.
7. **Check out at a facility.** When your work at the facility is complete, update your status to checked out. There is no location requirement for check-out, so you can do this regardless of where you are.

<Info>
  💡 Access to the Driver Companion mobile app is limited to users with the **"Driver"** role. Your company's designated admin sets up your driver profile before you can log in.
</Info>

## Troubleshooting

### "This app won't work for your device." message

The mobile app is designed for a mobile phone device, but can be used on some tablets. The lowest supported platform versions (as of September 10, 2025) are Android 8 and iOS 15. If you see the message "This app won't work for your device.", the app is unable to run on that device due to compatibility restrictions. This typically happens for one or more of the following reasons:

* The device is too old and no longer supported.
* The device is running an unsupported operating system (OS) version.
* The device has been modified or compromised, such as rooted Android devices or jailbroken devices (iOS or Android equivalents).

### Cannot log in

Your cell phone number is your login credential, and your account must exist before you can log in.

1. Confirm your company's designated admin has set up a driver profile for you in Alvys.
2. Enter the exact cell phone number your admin used for your profile, then try again.

### Check-in is blocked

Check-in confirms you are at the facility before it updates your status.

1. Make sure you have arrived at the facility and have accepted the app's location permissions.
2. If the app prompts you to move closer, move toward the facility and try the check-in again. Check-out has no location requirement.

## FAQs

**Q:** Are all mobile devices supported?

**A:** The mobile app is designed for a mobile phone device, but can be used on some tablets. The lowest supported platform versions (as of September 10, 2025) are Android 8 and iOS 15.

**Q:** What do I use to log in?

**A:** Your cell phone number is your login credential. It identifies the account your company's admin created for you in Alvys. If your profile has not been set up yet, you will not be able to proceed.

**Q:** Who can use the Driver Companion mobile app?

**A:** Access is limited to users with the **"Driver"** role, and your company's designated admin sets up your driver profile before you can log in.


# Driver List
Source: https://docs.alvys.com/en/help/assets-fleet/driver-list

View and filter external carrier drivers with the Employment Type column in Assets > Drivers so your fleet and partner drivers stay in one searchable list.

## Viewing and Filtering External Drivers in Assets > Drivers

The Assets > Drivers table now shows an Employment Type column so you can tell at a glance which drivers are your own and which are external drivers that come from carriers you work with. You can also filter the table by this column to narrow the list to just external drivers.

**Where You'll See It**: Open the Assets menu and select Drivers. The Employment Type column appears in the drivers table alongside the existing columns. External drivers are labeled in the Employment Type column.

## Filtering by Employment Type

Use the Employment Type column filter to show only external drivers (or to exclude them).

**How To Use It**:

1. Go to Assets > Drivers.
2. Open the filter on the Employment Type column.
3. Select External to show only external drivers.

<Note>
  💡 **Please Note**: External drivers originate from carriers you work with rather than being drivers you employ directly. This column helps you keep external drivers visible and searchable in the same place as the rest of your fleet.
</Note>


# How to add a trailer
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-add-a-trailer

Create a trailer record in Assets > Trailers by entering equipment type, size, trailer number, and subsidiary so it's ready for driver and load assignment.

## Overview

Before a trailer (also called equipment or a unit) can be assigned to a driver or a load, it must exist as a record in Alvys. This article walks you through creating a trailer record manually. You can also create multiple trailer records at once using the trailer import tool; the valid equipment type values for that tool are listed in the Variations section below.

## Prerequisites

You must have the **"EditAsset"** permission assigned to your user role. Without it, the New Trailer button does not appear on the Trailers page and the trailer form is read-only.

Navigate to Assets > Trailers to confirm you can see the New Trailer button before beginning.

## Steps

1. Open the Trailers page. In the left navigation bar, expand the Assets section and select Trailers.

   <img alt="Notion Image" />
2. Open the new trailer form. Click **New Trailer** in the top right corner of the Trailers page.

   <img alt="Notion Image" />
3. Fill in the trailer details. Complete the required fields. All four of the following are required before the trailer can be saved:
4. Equipment Type — the trailer category (for example, Van, Reefer, Flatbed).
5. Equipment Size — the length or size of the trailer.
6. Trailer Number — your internal identifier for this trailer.
7. Subsidiary — the subsidiary this trailer is associated with.

   Then fill in any additional fields that apply to this trailer:

   * License section: License number, license state, license country, and license expiration date.
   * Insurance section: Insurance company name, policy number, insurance value, and insurance expiration date.
   * Inspection section: Inspection expiration date.
   * Leasing section: Leased-from company and leased-to company details, including lease start and end dates.
   * Capacity: Pallets and weight.
   * Fleet: Assign this trailer to a fleet.
   * Year and Make.
   * Tire size.
8. Save the trailer. Click **Add Trailer** at the bottom right of the form.

The trailer is saved and appears in the Trailers list. It is now available for assignment to loads and drivers in dispatch.

## Variations

### Importing multiple trailers at once

If you need to add many trailers, use the **Import trailers** option from the more-options menu (three-dot icon) on the Trailers page. This option is also controlled by the **"EditAsset"** permission and will not appear without it.

When using the import tool, the Equipment Type values in your import file must match the following list exactly: Van, Reefer, VanorReefer, Flatbed, Auto Carrier, Double Drop, Dump Trailer, FlatbedReefer, Flatbed/Van, Flatbed w/ Pallet Exchange, Flatbed/Step Deck, Flatbed w/ Sides, Flatbed/Reefer/Van, Flatbed - Hazardous, Hotshot, Intermodal, Lowboy, Maxi, Power Only, Removable Goosenec, Reefer/Van, Reefer - Hazardous, Reefer w/ Pallet Exchange, Step Deck, Tanker, Van w/ Curtains, Van w/ Pallet Exchange, Van - Vented, Van - Hazardous, Van - Air-Ride.

## Troubleshooting

### New Trailer button is not visible

1. Confirm that you are on the Assets > Trailers page (not the Trucks or Assignments page).
2. Check that your user account has the **"EditAsset"** permission. This permission is required to see the New Trailer button and to access the trailer form. If you do not have it, contact your Alvys administrator to request it be added to your role.

### Add Trailer button is greyed out or the form cannot be submitted

1. Check that all four required fields are filled in: Equipment Type, Equipment Size, Trailer Number, and Subsidiary. The form cannot be submitted if any required field is blank.
2. Check the Trailer Number field. If a VIN number was entered elsewhere that is already in use by another trailer record, the form will display a validation error on that field. Each VIN must be unique.

## FAQs

**Q: Can I add notes, documents, or asset events to a trailer when I create it?**

**A:** Yes. After saving the trailer, open the trailer record and use the Notes, Documents, and Asset Events tabs to add supporting information.

**Q: Can I assign a trailer to an owner-operator instead of a subsidiary?**

**A:** Yes. On the trailer form, select the owner-operator option to associate the trailer with a specific owner-operator rather than a company subsidiary.

**Q: What happens if the Equipment Type I enter does not match the import list?**

**A:** When using the import tool, the import will not process trailers with Equipment Type values that do not exactly match the accepted list. Correct the values in your import file to match the list in the Variations section above, then re-import.

**Q: Who can see and edit trailer records?**

**A:** Any user with the **"EditAsset"** permission can create and edit trailers. Users with the **"ViewTrailers"** permission can view trailer records but cannot make changes.

## Go Deeper

* [Adding Trucks](/en/help/assets-fleet/how-to-add-a-truck-in-alvys)


# How to add a truck in Alvys
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-add-a-truck-in-alvys

Add a truck record in Assets > Trucks with license, insurance, and ELD details so dispatch can assign it to drivers, trips, and fleets right away.

## Overview

Adding a truck (also called creating a truck record, adding a vehicle, or registering a tractor) to Alvys creates a record your team can assign to drivers, trips, and fleets. Each truck record holds identification details, license and registration information, insurance data, ELD provider settings, and optional notes, documents, and asset events.

To add a truck in Alvys, navigate to Assets > Trucks, click New Truck, fill in the required fields, and click Add Truck. Once saved, the truck is available for dispatch assignment and trip planning. You must have the **"EditAsset"** permission to add or edit trucks.

## Before You Start

You must have the **"EditAsset"** permission assigned to your user account. Without it, the New Truck button does not appear on the Trucks list page.

You need to know which subsidiary the truck operates under. Subsidiary is a required field and cannot be left blank.

Have the truck number ready. Truck numbers must be unique within your company.

## Steps

1. Open the Trucks list.

   * In the left navigation bar, select Assets.
   * From the Assets menu, click Trucks.

     <img alt="Shows the Assets menu in the left navigation bar with Trucks highlighted beneath Drivers." />

     *Shows the Assets menu in the left navigation bar with Trucks highlighted beneath Drivers.*
2. Open the new truck form.

   * In the top-right corner of the Trucks list, click **New Truck**.

     <img alt="Shows the Trucks list page with the New Truck button highlighted in the top-right corner" />

     *Shows the Trucks list page with the New Truck button highlighted in the top-right corner*
3. Fill in the required fields. The form requires two fields before you can save.

   * Truck Number: a unique identifier for this truck within your company.
   * Subsidiary: the subsidiary this truck operates under.
   * You can also fill in any of the optional fields at this stage or return to add them later: License details (license number, license state, license country, plate expiration date, and license expiration date); Vehicle details (year, make, model, VIN number, color, number of axles, gross weight, empty weight, fuel type, and MPG); Insurance details (insurance company, policy number, insurance expiration date, and inspection expiration date); ELD settings (ELD provider and provider-specific identifiers for real-time tracking); Additional identifiers (registered name, loss payee, lease details, and custom warnings).

     <img alt="Shows the new truck form with the Truck Number and Subsidiary fields visible, along with the optional fields sections" />

     *Shows the new truck form with the Truck Number and Subsidiary fields visible, along with the optional fields sections*
4. Add notes, documents, or asset events (optional). While still on the new truck form, you can attach Notes (free-text notes about this truck), Documents (supporting files such as registration certificates or insurance cards), and Asset events (scheduled or completed events such as maintenance or inspections).

   <img alt="Shows the notes, documents, and asset events tabs at the bottom of the new truck form." />

   *Shows the notes, documents, and asset events tabs at the bottom of the new truck form.*
5. Save the truck.

   * Click **Add Truck** to save the record.

<Note>
  <img alt="Shows the Add Truck button at the bottom of the new truck form" />

  *Shows the Add Truck button at the bottom of the new truck form*
</Note>

## Result

The truck is created and appears in the Trucks list. It is now available for assignment to drivers, trips, and fleets from anywhere in Alvys that references truck assets.

## Variations

### Bulk import trucks from a file

If you need to add many trucks at once, use the import option instead of creating them one at a time:

1. On the Trucks list page, click the overflow menu (the three-dot menu icon at the top right).
2. Click **Import trucks**.
3. Follow the import dialog to upload your file. The import supports CSV format and validates each row before saving.

Users need the **"EditAsset"** permission to access the import option.

## Troubleshooting

### Why is the New Truck button not visible?

The New Truck button only appears for users who have the **"EditAsset"** permission. If the button is missing, your user account does not have this permission. Contact your company administrator to have the **"EditAsset"** permission added to your role. If the permission has already been granted and the button still does not appear, contact Alvys support.

### Why is the truck number already in use?

Truck numbers must be unique within your company. If you receive an error stating the truck number is already taken, check the Trucks list for an existing record with that number. If the existing record is inactive or a duplicate, contact your administrator to resolve it before creating the new truck.

### Why is the Subsidiary field missing or empty?

The Subsidiary field is required and must be selected from the list of subsidiaries configured for your company. If no subsidiaries appear in the dropdown, your company profile may not have any subsidiaries set up. Contact your company administrator to confirm at least one subsidiary exists before adding trucks.

## FAQs

**Q:** Can I add a truck without an ELD provider?

**A:** Yes. ELD provider details are optional. You can add a truck with only the Truck Number and Subsidiary fields and configure ELD settings later by editing the truck record.

**Q:** Can I edit a truck's details after saving?

**A:** Yes. Open the truck from the Trucks list and update any field. You need the **"EditAsset"** permission to save changes.

**Q:** Who can add trucks in Alvys?

**A:** Any user with the **"EditAsset"** permission can add trucks. If you need this permission, contact your company administrator.

**Q:** What is the Subsidiary field used for?

**A:** The Subsidiary field links the truck to a specific operating entity within your company. This affects how the truck appears in reporting, dispatch, and driver settlements. Each truck must be assigned to exactly one subsidiary.

## Go Deeper

* [Adding Trailers](/en/help/accounting-settlements/billing-status-definitions)


# How to Add and Manage Fleets in Alvys
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys

Create, edit, and delete fleets from Management > Fleets to group trucks by region, division, or trailer type for cleaner dispatch and reporting filters.

<Note>
  Create and manage fleets, also called truck groups or asset groups, to organize assets by region, division, or trailer type for use in dispatch planning and reporting.
</Note>

## Overview

A fleet (also called a truck group, asset group, or vehicle group) is a named grouping of trucks. Fleets help you organize your assets by region, division, trailer type, or any other category that fits your operation. Once a fleet is created, you can assign trucks to it and use fleet filters in the Dispatch Planner and reporting tools.

Use this article to create a new fleet, assign trucks to it, and update or delete fleets as your operations change. Fleets are managed from Management > Fleets. Access to this section requires the Admin, Partner Admin, or Support role. Dispatchers and other roles do not have access to the Management section.

## Prerequisites

* You must have the Admin, Partner Admin, or Support role. If the Management menu is not visible in your left navigation, your role does not include access to this area. Contact your company administrator to verify your role.
* Have the fleet name ready before you begin. Each fleet name must be unique within your company.
* To assign trucks to a fleet, those truck records must already exist in Alvys. If trucks have not been added yet, create them first under Assets > Trucks.

## Steps

**Navigate to Fleets:**

* Select your username in the bottom left corner
* Select Fleets from the Management submenu. The Fleets list opens and shows all fleets currently configured for your company.

<Note>
  <img alt="Image showing navigation to the fleets page" />

  *Image showing navigation to the fleets page*
</Note>

**Create a new fleet:**

* Click **Add Fleet** in the upper right corner of the Fleets page.
* In the dialog that appears, enter the Fleet Name.
* Click **Add Fleet** to confirm. The new fleet is created and appears in the Fleets list.

<Note>
  <img alt="Image displaying “Add Fleet” form with fleet input details and add fleet buttons" />

  *Image displaying “Add Fleet” form with fleet input details and add fleet buttons*
</Note>

### Delete a fleet

<Warning>
  ⚠️ You can only delete a fleet that has no trucks, trailers, companies, drivers, or automations linked or assigned to it. These must be removed prior to deleting the fleet.
</Warning>

1. Navigate to the Fleets List ([https://app.alvys.com/#/manage/fleets](https://app.alvys.com/#/manage/fleets)).
2. Click the **Delete icon (🗑) for the specific fleet**.
3. Confirm the deletion in the dialog.

## Invoice Prefix

Each fleet can have an optional invoice prefix. An invoice prefix is a short code that appears at the start of the invoice number for any load assigned to that fleet. This makes it easier to identify fleet-specific invoices in Alvys and in external accounting systems such as QuickBooks, Sage Intacct etc.

\*\*Steps: \*\*

1. Navigate to the Fleets List ([https://app.alvys.com/#/manage/fleets](https://app.alvys.com/#/manage/fleets)).
2. \*\*Add or Edit Fleet: \*\*You can either click **"Add Fleet"** to create a new one, or select an existing fleet from the list to **modify** it by clicking the row.
3. \*\*Enter Invoice Prefix: \*\*In the fleet details form (for adding or editing), locate the **"Invoice Prefix"** field.
4. Fill out your chosen prefix (e.g., "RF-" for a Reefer Fleet).
5. Click **"Submit"** to apply the prefix to the fleet

<Note>
  <img alt="Image displaying “Edit Fleet” form with editable “Invoice Prefix” input field." />

  *Image displaying “Edit Fleet” form with editable “Invoice Prefix” input field.*
</Note>

<Warning>
  ⚠️ Invoices generated prior to the fleet prefix being added are not updated.
</Warning>

## Assigning drivers and trailers to a fleet

To assign a driver to a fleet, open the driver record from the Drivers list in Assets ([https://app.alvys.com/assets/drivers](https://app.alvys.com/assets/drivers)), locate the Fleet field, select the desired fleet, and click Save.

<Note>
  <img alt="Image showing sample driver profile with “Fleet” input field." />

  *Image showing sample driver profile with “Fleet” input field.*
</Note>

To assign a trailer to a fleet, open the trailer record from the Trailers list in Assets ([https://app.alvys.com/assets/trailers](https://app.alvys.com/assets/trailers)), locate the Fleet field, select the desired fleet, and click Update Trailer.

<Note>
  <img alt="Image showing sample truck profile with “Fleet” input field" />

  *Image showing sample truck profile with “Fleet” input field*
</Note>

## Assigning a load to a fleet

* To assign a fleet to a new load, locate the Fleet field in the new load form during load creation and select the desired fleet.

<Note>
  <img alt="Image Displaying New load form with Fleet field" />

  \*Image Displaying New load form with Fleet field \*
</Note>

* To assign a fleet to an existing load, open the load from the Loads Board, click the Assign Fleet button, select the fleet, and click Update.

<Note>
  <img alt="Image showing “Assign Fleet” button on load details page" />

  *Image showing “Assign Fleet” button on load details page*
</Note>

## Where Does Fleet Information Appear?

Once a fleet is assigned to a load or an asset, the fleet name appears in several places across Alvys. This section shows where to find it.

### Loads Board

The fleet assigned to a load appears as a column on the Loads Board, letting you quickly see which fleet each load belongs to without opening the load.

<Note>
  <img alt="Image showing Fleet columns on Alvys load board." />

  *Image showing Fleet columns on Alvys load board.*
</Note>

### Load Summary

The fleet assigned to a load is shown in the Load Summary section when you open a load from the Loads Board.

<Note>
  <img alt="Image displaying load summary" />

  \*Image displaying load summary \*
</Note>

### Load Details Page

The fleet assignment appears in the load details alongside other dispatch information such as driver and truck assignments.

<Note>
  <img alt="Image showing fleet details on the load details page for a sample load." />

  *Image showing fleet details on the load details page for a sample load.*
</Note>

### Asset Profiles

Fleet assignments are visible on Driver, Truck, and Trailer profile pages. The Fleet field on each asset profile shows which fleet that asset belongs to.

<Note>
  <img alt="Image showing sample driver profile with fleet assigned." />

  *Image showing sample driver profile with fleet assigned.*
</Note>

## Frequently Asked Questions (FAQ)

**Q: Can I change a fleet's Invoice Prefix after it's been set?** A: Yes, you can modify a fleet's Invoice Prefix at any time by editing the fleet details in the Fleets section. However, please note that changing a prefix will only affect newly generated invoices, not invoices that were already created with the old prefix.

**Q: If I don't assign a fleet to a load, will it still get an Invoice Prefix?** A: If a load is not assigned to a fleet, it will not use a fleet-specific Invoice Prefix. It will follow your system's default invoice numbering conventions. To ensure an invoice prefix is applied, the load must be explicitly assigned to a fleet that has a prefix configured.


# How to add Driver and Asset Events
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-add-driver-and-asset-events

Schedule vacation, hometime, restart, and repair events on drivers, trucks, or trailers to protect compliance and prevent surprise maintenance downtime.

<Note>
  Driver and Asset Events are reminders or scheduled actions you can set on drivers, trucks, and trailers in Alvys. Use them to stay on top of maintenance, time off, compliance resets, and documentation renewals.
</Note>

## Overview

Driver and Asset Events in Alvys help you track, monitor, and manage critical actions and timelines tied to drivers, trucks, and trailers. Adding events (also called driver events, asset events, availability events, scheduled events, or reminders) for your assets and drivers lets you streamline operations and stay promptly informed of any required maintenance, documentation renewal, time off, compliance reset, or other key update. Event types include vacation, sick or emergency, restart, hometime, and repair. You can add events from a driver or asset profile, and you can also add, edit, or delete driver events directly from either Dispatch Planner.

## Before You Start

Before adding an event, make sure of the following:

* You are signed in to your Alvys account.
* To add a driver event, you need the **"View Drivers"** permission so you can open the Drivers list and profiles.
* To add a truck event, you need the **"View Trucks"** permission so you can open the Trucks list and profiles.
* To add a trailer event, you need the **"View Trailers"** permission so you can open the Trailers list and profiles.
* Decide which driver, truck, or trailer the event applies to, and have the event date, location, and any notes ready.

## Steps

1. **Open the driver or asset profile.** Go to the Drivers, Trucks, or Trailers list under Assets, then click the asset to open its profile.
2. **Find the Events section.** In the asset's profile, look for the Events section. This is typically located in the sidebar or as a tab within the profile view.

   <img alt="Asset Events in profile" />

   *Asset Events in profile*
3. **Add a new event.** Click the Add Event button. A form appears where you enter the event details; complete it, then select Add Event:

   * Driver Event Type: Vacation (scheduled paid time off); Sick or Emergency (urgent, unplanned time off due to illness or a medical appointment); Restart (mandatory **34-hour HOS reset period**, used to confirm compliance); Hometime (scheduled home visit or specific personal event, for example a graduation); Other (a catch-all for miscellaneous events).
   * Truck or Trailer Event Type: Repair (maintenance); Other (a catch-all for miscellaneous events).
   * Date: set the date and time for the event.
   * Description: enter any specific details or notes related to the event.
   * Address: if the event takes place at a specific location, you can include the address.

## Result

The event is saved to the driver, truck, or trailer profile and appears in that asset's Events section. You and your team can now see the scheduled event and use it to stay ahead of maintenance, time off, compliance resets, and other key updates.

## Variations

You can also add, edit, or delete Driver Events directly from both Dispatch Planners.

### Add a driver event from Dispatch Planner v1

Click into any driver row, then click Create Primary Driver Event to create the event.

<img alt="Notion Image" />

### Add a driver event from Dispatch Planner v2

Click the calendar icon on any driver row to open the side panel with Driver Activity, then click Add Event.

<img alt="Notion Image" />

## Troubleshooting

### Drivers, Trucks, or Trailers list is not visible

Confirm you have the **"View Drivers"** permission to open driver profiles, **"View Trucks"** for truck profiles, or **"View Trailers"** for trailer profiles. Ask an administrator to grant the missing permission, then reopen the Drivers, Trucks, or Trailers list under Assets.

### Add Event button does not save the event

The event will not save until the required fields are complete. Confirm you selected an Event Type and set the Date. Re-enter the Description and, if applicable, the Address, then select Add Event again.

## FAQs

**Q: What types of driver events can I add?**

**A:** You can add Vacation (scheduled paid time off), Sick or Emergency (urgent, unplanned time off due to illness or a medical appointment), Restart (mandatory 34-hour HOS reset period used to confirm compliance), Hometime (a scheduled home visit or specific personal event such as a graduation), and Other (a catch-all for miscellaneous events).

**Q: What types of truck or trailer events can I add?**

**A:** You can add Repair (maintenance) and Other (a catch-all for miscellaneous events).

**Q: Can I add or edit driver events without opening the asset profile?**

**A:** Yes. You can add, edit, or delete Driver Events directly from both Dispatch Planners. In Dispatch Planner v1, click into any driver row and click Create Primary Driver Event. In Dispatch Planner v2, click the calendar icon on any driver row to open the Driver Activity side panel, then click Add Event.


# How to Create a Driver
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-create-a-driver

Add a new driver in Assets > Drivers with CDL details, employment type, fleet, and pay setup so they're ready for trip assignment, settlements, and compliance.

<Note>
  Creating a driver (adding a driver, setting up a driver record) in Alvys sets up the driver record used for trip assignment, pay calculations, compliance tracking, and integrations. This article walks through the full driver creation process step by step.
</Note>

## Overview

A driver record in Alvys stores the driver's personal information, license details, employment type, fleet assignment, pay configuration, and integration settings. Once created, the driver can be assigned to trips, tracked for compliance, and included in settlements.

Driver records can be created manually from the Drivers list or imported in bulk. This article covers manual creation.

## Prerequisites

You need the **"EditAsset"** permission to create a new driver. The New Driver button in the Drivers list is visible and active only for users with this permission.

Prepare the following information before starting:

* Driver's full legal name and contact details.
* Driver's CDL number, license class, and state of issue.
* Employment type (Company Driver or Owner Operator).
* Fleet assignment (if applicable).

## Steps

* Open the Drivers list. Navigate to **Assets > Drivers**. The Drivers list shows all existing drivers in your workspace.

<Note>
  <img alt="Drivers list page showing existing drivers with the New Driver button visible in the top-right area." />

  *Drivers list page showing existing drivers with the New Driver button visible in the top-right area.*
</Note>

* Click **New Driver**. In the top-right area of the Drivers list, click **New Driver** to open the driver creation form. The New Driver button is only visible to users with the **"EditAsset"** permission. If the button is not visible, contact your Alvys Admin to confirm your permissions.

<Note>
  <img alt="Drivers Page showing drivers table and “New Driver” button" />

  \*Drivers Page showing drivers table and “**New Driver**” button \*
</Note>

* Enter driver information. Fill in the required fields on the driver creation form. Required fields include the driver's first name, last name, and employment type (**Company Driver or Owner Operato**r).

<Note>
  <img alt="Driver creation form showing the required fields for name, employment type, and contact details." />

  \*Driver creation form showing the required fields for name, employment type, and contact details. \*
</Note>

**Enter the following information as available:**

* **Employment type:** Company Driver, Owner Operator or Contractor.
* **Driver Personal information:** First name, last name, phone number, email address, etc
* **Fleet:** Assign the driver to a fleet if your company uses fleet segmentation.
* **Driver Physical Address**
* **License information:** CDL number, license class, state of issue, expiration date.
* **Tax Information**
* **Hire date:** The date the driver started. Used for Driver Rate Plan tenure calculations.
* Save the driver record. Click the “Create” button to create the driver record. The driver now appears in the Drivers list and is available for trip assignment.

<Note>
  <img alt="Image displaying the New Driver form with the “Create” button" />

  *Image displaying the New Driver form with the “Create” button*
</Note>

After saving, the driver record is active in Alvys. You can now:

* Assign the driver to trips from the Loads and Trips module.
* View the driver in the Drivers list with their employment type and fleet assignment.
* Add rate policies to the driver's profile under **Rates**.
* Track the driver's compliance documents under **Documents**.

<Note>
  <img alt="Saved driver profile showing the completed driver record with fields populated." />

  \*Saved driver profile showing the completed driver record with fields populated. \*
</Note>

## Troubleshooting

### New Driver button is not visible

Confirm you have the **"EditAsset"** permission. The New Driver button is only shown to users with this permission. If you have the permission but the button is still not visible, try refreshing the page. If the issue persists, contact Alvys support.

### Driver does not appear in the Drivers list after saving

Check whether a filter is active on the Drivers list. Active filters may be hiding newly created drivers. Clear all filters and search for the driver by name. If the driver still does not appear after clearing filters, contact Alvys support.

## FAQs

**Q: Can I import multiple drivers at once instead of creating them one at a time?**

**A:** Yes. Alvys supports bulk driver import. Contact your Alvys Admin or Alvys support for the import template and instructions.

**Q: What is the difference between a Company Driver and an Owner Operator?**

**A:** Company Drivers are employees whose truck is owned by your company. Owner Operators own or lease their own truck. The employment type affects available pay settings, including the Truck Statements feature and the Service Fee rate type.

**Q: Can I edit a driver's information after creating the record?**

**A:** Yes. Open the driver's profile from **Assets > Drivers** and edit any field. You need the **"EditAsset"** permission to save changes.

## Go Deeper

* [Driver Rates, Rules & Plans: The Complete Guide](/en/help/accounting-settlements/driver-rates-rules-plans-the-complete-guidex)
* [Driver Settlements FAQ](/en/help/accounting-settlements/driver-settlements-faq)
* [User Permissions Glossary](/en/help/administration/user-permissions-glossary)


# How to set up Assignment Preferences for drivers
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers

Pair drivers with a specific truck and dispatcher in advance so Alvys can suggest or auto-apply the right combination when loads are assigned.

## Overview

Assignment Preferences, also called dispatch preferences or driver-truck pairings, let you link a driver (or a driver team) to a specific truck and a dispatcher ahead of time. When a load needs to be assigned, Alvys checks these pairings and can suggest or automatically apply the right combination, saving dispatchers from re-entering the same information on every trip.

Each preference has a status: it is Planned before its start time, Active during the window you set, and Archived after it ends or when you manually archive it.

## Prerequisites

* You must have the **"ViewDrivers"** and **"ViewTrucks"** permissions to access the Assignment Preferences page. These permissions are required for the page to appear in the left navigation.
* You must have at least one driver and one truck already created in Alvys before you can set up a preference.
* If you need to add drivers or trucks first, do that in Assets > Drivers and Assets > Trucks before returning here.

## Steps

1. Open Assignment Preferences.

In the left navigation, select Assets.

Select Assignment Preferences from the Assets submenu.

<Note>
  <img alt="Screenshot of Assignment Preferences list view." />

  \*Screenshot of Assignment Preferences list view. \*
</Note>

1. Open the new assignment form.

On the Assignment Preferences page, click **New assignment** in the top right.

<Note>
  <img alt="Screenshot of the New Assignment Preference modal." />

  *Screenshot of the New Assignment Preference modal.*
</Note>

1. Fill in the preference details.
2. In the Primary Driver field, type the driver's name and select them from the results.
3. If this is a team assignment, toggle on Driver team and then fill in the Secondary Driver field.
4. In the Truck field, type the truck number and select it from the results.
5. Optionally, select one or more values in the Equipment field to record the trailer equipment type for this pairing.
6. In the Dispatcher field, type a name to associate a dispatcher with this preference.
7. Set a Starts at date and time for when this preference becomes active.
8. Optionally, set an Ends at date and time. If left blank, the preference remains active until you archive it manually.

<Note>
  <img alt="Screenshot of the Assignment Preferences table with columns visible" />

  *Screenshot of the Assignment Preferences table with columns visible*
</Note>

1. Save the preference.

Click **Save**. The new preference appears in the Assignment Preferences list. Its status is Planned until the Starts at time is reached, at which point it becomes Active.

<Note>
  <img alt="Screenshot of the Details sidebar with Edit button visible." />

  \*Screenshot of the Details sidebar with Edit button visible. \*
</Note>

After saving, the preference is visible in the Assignment Preferences list. When a load is assigned from the Dispatch Planner and the driver in the preference is selected, Alvys checks for a matching preference and can apply the saved truck and dispatcher automatically.

### Editing an existing preference

Select a preference from the list. If its status is Active or Planned, an Edit button appears. Click Edit to open the form with the existing values prefilled, make your changes, then click Save.

### Archiving an active preference

Select an Active preference from the list and click Archive. The preference moves to archived status and is no longer suggested during dispatch assignment.

### Deleting a planned preference

Select a Planned preference from the list and click Delete. This permanently removes the preference before it becomes active.

## Troubleshooting

### Assignment Preferences page is not visible in the navigation

The Assignment Preferences page only appears for users who have both the **"ViewDrivers"** and **"ViewTrucks"** permissions. If either permission is missing, the menu item does not display. Contact your account administrator to review your permission settings.

### Preference is not suggested during dispatch assignment

Alvys checks Assignment Preferences when assigning a driver to a trip in the Dispatch Planner. The preference must be Active at the time of assignment. A preference with Planned status or one that has been Archived is not evaluated. Verify the preference status and adjust the Starts at date if needed.

### Driver or truck does not appear in the search results

The driver or truck must be active in Alvys before it can be added to a preference. If the record is inactive or has not yet been created, it will not appear. Check Assets > Drivers or Assets > Trucks to confirm the record exists and is active.

## FAQs

**Q:** Can I assign a driver to more than one truck at the same time?

**A:** Yes. A driver can appear in multiple preferences with different trucks, as long as the active date ranges do not overlap for the same pairing. If overlapping preferences exist for the same driver and truck combination, Alvys will surface a similar-assignments warning when you create the second preference.

**Q:** Can I set a preference without an end date?

**A:** Yes. Leaving the Ends at field blank means the preference stays Active until you manually archive it.

**Q:** What happened to Dispatch Preferences?

**A:** Dispatch Preferences was renamed to Assignment Preferences in December 2025. The feature works the same way; only the name changed.

**Q:** Does setting up an Assignment Preference automatically dispatch the driver?

**A:** No. An Assignment Preference saves a standing pairing so the Dispatch Planner can suggest or apply it when you assign a load. The actual dispatch action is a separate step performed from the Dispatch Planner.

## Go Deeper

* Dispatch Assist


# How to verify a motor carrier in Alvys
Source: https://docs.alvys.com/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys

Confirm a carrier rep is authorized by the FMCSA owner by sending a 6-digit code from the carrier packet, profile, rate confirmation, or onboarding packet.

## Overview

Carrier verification (also called MC verification or FMCSA check) confirms that a carrier representative is authorized to act on behalf of the FMCSA-registered owner. Carrier verification lets your brokerage confirm that the person representing a motor carrier is authorized by the owner registered with the FMCSA. Alvys sends a 6-digit code to the FMCSA owner's email address and/or mobile number. Once the code is entered and accepted, the carrier's status updates to **"Verified"**.

You can trigger verification from four locations in Alvys: Carrier Packet, Carrier Profile, Rate Confirmation, and Carrier Onboarding Packet.

Before verifying, Alvys requires at least one of the carrier's MC number or USDOT number, and at least one delivery method (email or phone). The FMCSA owner must have an email address or mobile number on file with the FMCSA.

You can check the current verification status of any carrier in three places:

* The Carriers list (Verified Status column)
* The carrier's profile page
* The Carrier details section of any load

The status displays as a badge: **"Verified"** (green) or **"Not verified"** (orange).

## Prerequisites

No special permission is required to trigger carrier verification. Any user logged in to Alvys (all users) can initiate and complete verification.

You will need:

* The carrier's MC number or USDOT number (at least one is required)
* Access to the carrier's FMCSA-registered email address or mobile phone, OR the ability to contact the carrier owner to obtain the code

Verification codes expire after a set period. If the code expires before it is entered, you can request a new one.

## Steps

1. Open the carrier verification form. Verification can be triggered from four locations. Navigate to whichever is most convenient for your current workflow.

Option A, Carrier Packet: Navigate to Carriers in the left sidebar and open or create the carrier packet for the carrier you want to verify. Locate the Motor Carrier Validation section within the packet.

<Note>
  <img alt="Initiating a Motor Carrier Validation via Carrier packet. Shows the Carrier Packet interface with the Motor Carrier Validation section visible and the verification options displayed." />

  *Initiating a Motor Carrier Validation via Carrier packet. Shows the Carrier Packet interface with the Motor Carrier Validation section visible and the verification options displayed.*
</Note>

Option B, Carrier Profile: Navigate to Carriers in the left sidebar and search for the carrier. Open the carrier's profile. Locate the Motor Carrier Validation section on the profile page.

<Note>
  <img alt="Initiating a Motor Carrier Validation via Carrier profile. Shows the carrier profile page with the Motor Carrier Validation section and the verification trigger button." />

  *Initiating a Motor Carrier Validation via Carrier profile. Shows the carrier profile page with the Motor Carrier Validation section and the verification trigger button.*
</Note>

1. Select a verification method. Once the Motor Carrier Validation form is open, choose how the 6-digit code will be sent to the FMCSA owner.
2. Email and SMS: Sends the code to both the FMCSA-registered email and mobile number simultaneously.
3. Email only: Sends the code to the FMCSA-registered email address only.
4. SMS only: Sends the code to the FMCSA-registered mobile number only.
5. Select your preferred option and confirm to send the code.
6. Retrieve the verification code. After sending, the code is delivered to the FMCSA owner. Retrieve it using one of these two methods.
7. Method A, code via email or SMS: If you or the carrier owner has access to the FMCSA-registered email or phone, retrieve the 6-digit code from the message received.

<Note>
  <img alt="Verification code sent to FMCSA email. Shows an example of the email containing the 6-digit validation code." />

  *Verification code sent to FMCSA email. Shows an example of the email containing the 6-digit validation code.*
</Note>

<Note>
  <img alt="Verification code sent to FMCSA mobile phone. Shows an example of the SMS containing the 6-digit validation code." />

  *Verification code sent to FMCSA mobile phone. Shows an example of the SMS containing the 6-digit validation code.*
</Note>

1. Method B, contact the carrier owner directly: If you do not have access to the FMCSA-registered email or phone, contact the carrier owner and ask them to read you the code from the message they received. Enter the code once they provide it.
2. Enter the code in the validation form. Enter the 6-digit code in the Motor Carrier Validation form and submit.

<Note>
  <img alt="Motor Carrier Validation form showing the 6-digit code entry field and submit button." />

  *Motor Carrier Validation form showing the 6-digit code entry field and submit button.*
</Note>

<Note>
  <img alt="Motor Carrier Validation form with an alternate view of the code entry step." />

  * Motor Carrier Validation form with an alternate view of the code entry step.\*
</Note>

1. Confirm the result. After submitting, the system validates the code.
2. If the code matches and has not expired, a success message appears and the carrier's status updates to **"Verified"**.
3. If the code does not match or has expired, an error message appears. You can request a new code and try again.

<Note>
  <img alt="Successful Motor Carrier Validation message. Shows the success confirmation screen after a valid code is entered." />

  *Successful Motor Carrier Validation message. Shows the success confirmation screen after a valid code is entered.*
</Note>

<Note>
  <img alt="Motor Carrier Validation error message. Shows the error screen displayed when an invalid or expired code is submitted." />

  *Motor Carrier Validation error message. Shows the error screen displayed when an invalid or expired code is submitted.*
</Note>

After successful verification, the carrier's status badge updates to **"Verified"** (green) in the Carriers list (Verified Status column), the carrier's profile page, and the Carrier details section on any load where this carrier is assigned.

<Note>
  <img alt="Carrier list showing the Verified Status column with a Verified badge for a carrier." />

  *Carrier list showing the Verified Status column with a Verified badge for a carrier.*
</Note>

<Note>
  <img alt="Carrier details in the Load details view showing the verified carrier status." />

  *Carrier details in the Load details view showing the verified carrier status.*
</Note>

<Note>
  <img alt="Carrier details in the Carrier profile showing the verified status." />

  *Carrier details in the Carrier profile showing the verified status.*
</Note>

### Verifying via the FMCSA email link

If Email is selected as a delivery method and you have access to the FMCSA-registered email inbox, you can verify without entering a code manually:

1. Open the verification email sent to the FMCSA owner's email address.
2. Click the verification link in the email.
3. The confirmation page opens in a browser. Confirm the carrier on that page.

If the link has expired or an error occurs, a separate error screen appears. Request a new verification from Alvys to generate a fresh link.

<Note>
  <img alt="Motor Carrier Validation error via FMCSA email link. Shows the error page displayed when the email link is invalid or expired." />

  *Motor Carrier Validation error via FMCSA email link. Shows the error page displayed when the email link is invalid or expired.*
</Note>

<Note>
  <img alt="Motor Carrier Validation completed request via FMCSA email link. Shows the success state after confirmation via the email link." />

  *Motor Carrier Validation completed request via FMCSA email link. Shows the success state after confirmation via the email link.*
</Note>

### Pending verification

If a code has already been sent and is still within its valid period, the form shows a pending state rather than offering a new code. Wait for the pending code to be used or expire before requesting a new one.

<Note>
  <img alt="Motor Carrier Validation pending request. Shows the pending state indicator in the validation form while a code is still active." />

  *Motor Carrier Validation pending request. Shows the pending state indicator in the validation form while a code is still active.*
</Note>

## Troubleshooting

### Verification code not received

1. Confirm the carrier has an email address or mobile number registered with the FMCSA that matches what is on file in Alvys.
2. Check whether a verification is already pending. If a previous code was sent and has not expired, the form will show a pending state. Wait for it to expire before requesting a new one.
3. If the carrier owner has not received the code after a few minutes, ask them to check their spam or junk folder (for email) or verify the mobile number registered with the FMCSA is correct.
4. If none of the above resolves the issue, contact Alvys support.

### Error message appears after entering the code

1. Confirm the code was entered exactly as received, including all 6 digits with no extra spaces.
2. Check whether the code has expired. Codes are valid for a limited time after being sent. If expired, request a new code.
3. If you continue to receive an error after requesting and entering a new code, contact Alvys support.

### Verification status shows Not verified after successful entry

1. Refresh the page to reload the carrier's current status.
2. Check whether the confirmation message appeared after submission. A success message confirms the status was updated. If no message appeared, the verification may not have completed.
3. If the status still shows **"Not verified"** after refreshing and the success message did appear, contact Alvys support.

## FAQs

**Q:** What happens if the verification code expires before I enter it?

**A:** Request a new verification code from the Motor Carrier Validation form. A new 6-digit code will be sent to the selected delivery method.

**Q:** Can I send the code to both email and SMS at the same time?

**A:** Yes. Select the "Email and SMS" option when choosing a delivery method. The code will be sent to both the FMCSA-registered email address and mobile number simultaneously.

**Q:** Where can I see the verification status for all my carriers?

**A:** The verification status is visible in the Carriers list under the Verified Status column, on each carrier's profile page, and in the Carrier details section of any load.

**Q:** What if I do not have access to the FMCSA email or mobile phone?

**A:** Contact the carrier owner directly. They will receive the code at the FMCSA-registered contact and can read it to you. Enter the code in the Motor Carrier Validation form once you have it.

**Q:** Does carrier verification expire over time?

**A:** The **"Verified"** status on the carrier profile does not expire automatically once set. The verification code sent during the process expires if not used within a limited period, but the resulting verified status on the carrier record persists.

**Q:** Can I verify a carrier if I only have their USDOT number and not their MC number?

**A:** Yes. The validation form accepts either an MC number or a USDOT number. At least one must be present to initiate verification.

## Go Deeper

* [MyCarrierPackets (MCP)](/en/help/integrations/mycarrierpackets-mcp-integration)


# Safety and maintenance overview
Source: https://docs.alvys.com/en/help/assets-fleet/safety-and-maintenance-overview

Where safety and maintenance records live in Alvys: the Asset Safety Report, carrier verification, and maintenance on trucks and trailers.

Safety and maintenance in Alvys is the work of keeping driver and equipment documents current so the fleet can operate. The Asset Safety Report is the list view; driver and asset profiles hold the records themselves.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="Safety and Maintenance Records Overview" />

[Open the recording](https://www.loom.com/share/4042fa9c028d4a0497667fffdce6c5dd)

## Where to work

**Asset Safety Report** — **Reports > Safety** (`app.alvys.com/#/reports/safety`). This is the page the **"View Asset Safety Report"** permission opens. It shows documents that have expired or are about to expire:

* **Drivers:** license, medical certification, last motor vehicle record, Clearinghouse dates
* **Trucks and trailers:** assigned driver, plate expiration, inspection expiration, lease start and end

You need the **"View Asset Safety Report"** permission. Safety, Admin, Partner Admin, Operation Manager, Dispatcher, and Office Admin have it by default. See [Report permissions](/en/help/administration/report-permissions).

**Driver and asset profiles** — open a driver, truck, or trailer to add or update the records the report reads. Create the asset first if it does not exist yet.

<CardGroup>
  <Card title="Create a driver" icon="id-card" href="/en/help/assets-fleet/how-to-create-a-driver">
    Add the driver profile that holds license and medical records.
  </Card>

  <Card title="Add a truck" icon="truck" href="/en/help/assets-fleet/how-to-add-a-truck-in-alvys">
    Add the truck profile that holds plate, inspection, and lease dates.
  </Card>

  <Card title="Verify a motor carrier" icon="shield-check" href="/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys">
    Confirm a carrier representative is authorized by the FMCSA owner.
  </Card>

  <Card title="Fleetrock maintenance" icon="wrench" href="/en/help/integrations/fleetrock-maintenance-integration">
    Sync shop and maintenance work from Fleetrock when that integration is on.
  </Card>

  <Card title="IFTA reports" icon="gas-pump" href="/en/reporting/reports/overview">
    Fuel-tax reporting that Safety and Accounting often run together.
  </Card>
</CardGroup>


# Adding New Users & Signing In
Source: https://docs.alvys.com/en/help/getting-started/adding-new-users-signing-in

Set up new Alvys user accounts, sign in, manage your profile, reset a forgotten password, and accept the required Terms of Service agreement.

## Overview

This article covers the updated user management and sign-in experience in Alvys, including how administrators create and manage users (also called accounts, logins, or team members), the new sign-in flow, the one-time Terms and Conditions agreement, the forgot-password flow, and how multi-tenant users switch between organizations.

What applies to whom:

* All Alvys users experience the new sign-in flow (login, password reset, organization selection) and the one-time Terms and Conditions agreement.
* Admin, Partner Admin, and Support roles use the user creation and management flows.
* Alvys Implementation and Support are involved in initial tenant creation.

## Prerequisites

* To create or manage users, you must have the **"Add User"** permission and an Admin, Partner Admin, or Support role. The **"Set Permission"** permission lets you configure which permissions each user receives.
* To sign in, reset a password, or switch organizations, no special permission is required; these flows apply to all users.
* Administrators can send a password reset from **Settings → Organization → Users** — Alvys emails the user a secure link to set a new password. Users can also self-service using **Forgot Password** on the sign-in page.

## Steps

### Creating a new user

1. Log in to Alvys at [app.alvys.com](http://app.alvys.com/).
2. Navigate to **Settings → Organization → Users**.
3. Click the **Add User** button.
4. Enter the user's **Name**.
5. Enter their **Email address** (this is also their username).
6. Enter the user's **Phone Number** (optional).
7. A randomized password is automatically generated for the new user.
8. Choose the user's **Role**.
9. Select their associated **Office**.
10. Review and configure any other settings, such as e-check settings or permissions for the user.
11. Scroll down to the bottom of the page and click **Add User**.
12. The new user receives an email notification (ask them to check the spam folder if it is not immediately visible).
13. The email contains a link to the sign-in page so they can log in with their username (email) and the temporary password.

<Frame>
  <img alt="Image" />
</Frame>

### Managing user profiles

Administrators can edit user details and send a password reset from a user's profile.

1. Navigate to **Settings → Organization → Users**.
2. Open the user profile. Double-click any row in the users list to open that user's profile for editing.
3. Update phone number (optional). Click the **"Phone"** field to type in a phone number, then click save.
4. Update primary email / username:
   * Click the **"Primary Email / Username"** field.
   * Type in the new email address.
   * Click **Save** to apply the change, or **Cancel** to discard.
5. Send a password reset if needed. From the user's profile, use the **Reset Password** option — Alvys emails the user a secure link to set a new password. Alternatively, the user can self-service using **Forgot Password** on the sign-in page.

<Frame>
  <img alt="Image" />
</Frame>

### The new sign-in experience

1. Access the sign-in page. Navigate to the Alvys login page at [app.alvys.com](http://app.alvys.com/).
2. Enter credentials:
   * Enter your **Username** (your email address).
   * Enter your **Password** (the temporary one for new users, or your established one).
3. Log in. Click **Log In**.
4. Select organization (if applicable). If you are associated with more than one organization or tenant, you are directed to a **Select Organization** screen.
5. Note: there is currently no search box on this Select Organization page. Scroll through the list to find your desired tenant.
6. Access the home screen. Select the tenant you wish to work in.
7. You are logged in and taken directly to the Alvys home screen.

<Note>
  👋 Alvys updated its Terms of Service and Privacy Policy as of July 11, 2025. Users are now required to agree to the Terms and Conditions when logging in.
</Note>

Prompt displayed to users the first time they log in: To use our services, both new and existing users must accept our Terms and Conditions and Privacy Policy. Please review the terms, which apply to all users, and agree to continue or maintain access.

The user must click the checkbox next to "I have read and agree to the Terms and Conditions and Privacy Policy" and then click the Continue button.

Why it changed: To ensure a secure and compliant experience for all users. A formal agreement to the Terms of Service and Privacy Policy enhances the protection of your data and ensures clarity on how the platform can be used. This helps Alvys maintain a reliable and trustworthy service as it continues to grow.

Key points:

* One-time prompt for users to accept Terms and Conditions.
* No impact to existing workflows or functionality.

<Tip>
  For security, Alvys may periodically ask you to sign in again. If you are logged out, use your normal login steps to access your account.
</Tip>

### Forgot password flow

If you forget your password, you can reset it yourself.

1. Access the sign-in page. Go to the Alvys login page.
2. Click **Forgot password**.
3. Enter your **username** (your email address).
4. Click **Continue**.
5. Instructions to reset your password are sent to your email address.
6. Click the URL in the email to complete the password change process.

<Tip>
  Admins can send a password reset from a user's profile in **Settings → Organization → Users** — Alvys emails the user a secure link. Users can also self-service using the **Forgot Password** link on the sign-in page.
</Tip>

### Switching organizations (multi-tenant users)

For users with access to multiple organizations or tenants, you can switch between them without logging out and back in.

1. Locate the tenant selector. From any page in Alvys, go to the upper left corner of the screen. You will see the currently active tenant's name and ID.
2. Open the tenant list. Click the small up and down arrows next to the tenant name. This reveals a list of all organizations you have access to.
3. Search for the tenant. A search box is available at the top of this list. Type the name of the tenant you wish to switch to.
4. Switch tenant. Select the desired tenant from the filtered list.
5. Alvys switches you to that tenant's context without requiring a full logout and login.

## Troubleshooting

### New user did not receive the credentials email

The new user receives an email containing a sign-in link and temporary password. Ask them to check their spam or junk folder. Confirm the email address entered on the user profile is correct; if it is wrong, an administrator can update the Primary Email / Username field on the user profile.

### Cannot see the Add User button

Creating and managing users requires the **"Add User"** permission and an Admin, Partner Admin, or Support role. If the button does not appear, confirm your role and permissions with your account administrator.

### Resetting a user's password

An Admin can send a password reset from the user's profile in **Settings → Organization → Users** — Alvys emails the user a secure link to set a new password. Users can also reset their own password using the **Forgot Password** link on the sign-in page.

### Cannot find a tenant on the Select Organization screen

The Select Organization screen shown at login does not have a search box. Scroll through the list to find your tenant. Once logged in, you can switch organizations using the tenant selector in the upper left corner, which does include a search box.

## FAQs

**Q: Why am I being asked to agree to new terms?**

**A:** Alvys added a prompt so all users formally accept the Terms and Conditions, ensuring a secure and compliant experience. A formal agreement to the Terms of Service and Privacy Policy enhances data protection and clarifies how the platform can be used.

**Q: Has anything in the Terms and Conditions changed?**

**A:** This is simply a formal acknowledgment process. The content remains consistent with the standard policies. All users should read the linked Terms of Service and Privacy Policy documentation.

**Q: Do I have to agree to keep using the platform?**

**A:** Yes. Agreeing to the Terms and Conditions is required to access and use the platform going forward.

**Q: Will this affect how I use the platform?**

**A:** No. It is a quick one-time confirmation. Everything else works the same.


# Admin setup
Source: https://docs.alvys.com/en/help/getting-started/admin-setup

Set up users and roles, offices, fleets, and the permissions each person needs before anyone creates a load.

Create the people who will use Alvys, put them in the right office, give them a role, and stand up the fleets those people will dispatch against. There is no single admin setup screen — complete the articles below in order.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="Alvys Admin Setup training" />

[Open the recording](https://drive.google.com/file/d/1PUthJhjCMB_LDfr7PGQVJOTtyiE4qcu3/view)

## Written steps

Work these in order. Each one is a full how-to.

<CardGroup>
  <Card title="Add users and sign in" icon="right-to-bracket" href="/en/help/getting-started/adding-new-users-signing-in">
    Create accounts, send people to the sign-in page, and reset a password.
  </Card>

  <Card title="Add and manage users" icon="user-plus" href="/en/help/administration/how-to-add-and-manage-users-in-alvys">
    Edit, deactivate, and assign a role from Company Profile.
  </Card>

  <Card title="User roles" icon="id-badge" href="/en/help/administration/user-roles-in-alvys">
    What Admin, Dispatcher, Biller, Sales, and Safety can do.
  </Card>

  <Card title="User permissions" icon="user-lock" href="/en/help/administration/overview-of-user-permissions">
    The toggles that gate rates, dispatch, billing, and reports.
  </Card>

  <Card title="Set up offices" icon="building" href="/en/help/administration/how-to-set-up-offices-in-alvys">
    Offices (subsidiaries) group users, loads, and customers, and control data sharing.
  </Card>

  <Card title="Add and manage fleets" icon="layer-group" href="/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys">
    Group trucks by region, division, or equipment type.
  </Card>

  <Card title="Set up MFA" icon="shield-halved" href="/en/help/getting-started/how-to-set-up-multi-factor-authentication-mfa-in-alvys">
    Turn on multi-factor authentication for Alvys logins.
  </Card>
</CardGroup>

## After admin setup

Once users can sign in and fleets exist, create the first load and dispatch it. Start at [Start here](/en/help/getting-started/start-here).


# How to Clear Cache, Cookies, and Troubleshoot Common Issues
Source: https://docs.alvys.com/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues

Learn how to clear cache, cookies, and apply other simple fixes to resolve common issues like login problems and slow performance.

If Alvys is loading slowly, displaying incorrectly, or not letting you log in, clearing your browser cache and cookies is the first fix to try. This article walks through each step and provides additional browser and system troubleshooting options.

## Overview

Temporary bugs and glitches in Alvys, also called display issues or rendering problems, are often caused by outdated or corrupted data stored in your browser, not by a problem with the Alvys platform itself. Before escalating an issue, run through the steps below — they resolve the majority of common problems, including login failures, slow page loads, and missing or incorrectly rendered content. These steps are available to all users.

## Prerequisites

No special role or permission is required. Any Alvys user can perform all steps in this article.

You will need access to your browser settings and, for DNS steps, your operating system's command line or terminal.

## Steps

1. Clear your browser cache and cookies. Cached data can become outdated or corrupted. Clearing it resolves issues like improper page rendering, slow performance, and login problems.
2. **Chrome:** Click the three dots in the top-right corner, then select More Tools, then Clear Browsing Data. Check Cached images and files and Cookies and other site data. Set the time range to All time and click Clear Data.
3. **Firefox:** Click the three horizontal bars in the top-right corner, then select Settings. Under Privacy & Security, find Cookies and Site Data and click Clear Data. Check Cached Web Content and Cookies, then click Clear.
4. **Safari:** Go to Safari, then Preferences, then Advanced, and check Show Develop menu in menu bar. Click Develop in the top menu and select Empty Caches. For cookies, go to Privacy, then Manage Website Data, and click Remove All.
5. Log out and log back in. Logging out and logging back in refreshes your session with Alvys. This resolves minor errors such as incorrect user data or failure to load updated content.
6. Restart your browser or device. If clearing cache and logging in/out does not resolve the issue, close and reopen your browser entirely, or restart your device. A fresh session resets temporary glitches affecting performance.
7. Update your browser. Outdated browsers may not work correctly with Alvys. Confirm you are running the latest version:
8. **Chrome:** Go to Help, then About Google Chrome, to check for and install updates.
9. **Firefox:** Go to Help, then About Firefox.
10. **Safari:** Safari updates are bundled with macOS — check the App Store for system updates.
11. To confirm whether your browser is up to date, visit: [https://www.whatismybrowser.com/](https://www.whatismybrowser.com/)
12. Disable browser extensions. Ad blockers and privacy-focused extensions can interfere with Alvys functionality. Try disabling your extensions to see whether the issue persists.
13. In Chrome and Firefox, access extensions from the browser menu and toggle them off.
14. In Safari, go to Preferences, then Extensions, to manage them.
15. Try a different browser. If you are still experiencing issues, access Alvys in a different browser. Different browsers handle cookies, cache, and JavaScript differently — this helps determine whether the issue is browser-specific.
16. Check your internet connection. A slow or intermittent internet connection can produce symptoms that look like app bugs. Confirm your connection is stable, or try switching to a different network (for example, from Wi-Fi to mobile data).
17. Clear your system DNS cache. Your device stores DNS information to speed up website loading. Occasionally this data becomes outdated. If you are having trouble reaching Alvys specifically, try flushing your DNS cache.
18. **Windows:** Open Command Prompt and run: `ipconfig /flushdns`
19. **Mac:** Open Terminal and run: `sudo killall -HUP mDNSResponder`
20. Clear your browser's DNS and connection caches. If the previous step does not resolve the issue, your browser may be holding onto its own cached DNS and connection data. This is especially common after a network outage or service disruption.
21. **Chrome:** Open a new tab, type `chrome://net-internals/#dns` in the address bar, and press Enter. Click Clear host cache. Type `chrome://net-internals/#sockets` in the address bar, press Enter, and click Flush socket pools. Close and reopen Chrome.
22. **Edge:** Open a new tab, type `edge://net-internals/#dns` in the address bar, and press Enter. Click Clear host cache. Type `edge://net-internals/#sockets` in the address bar, press Enter, and click Flush socket pools. Close and reopen Edge.
23. **Firefox:** Open a new tab, type `about:networking#dns` in the address bar, and press Enter. Click Clear DNS Cache. If that option is not available, close Firefox completely and reopen it — restarting clears its DNS and connection caches automatically.
24. **Safari (macOS):** Safari uses the system DNS cache, so completing the system DNS step above covers Safari. You can also clear Safari's browser cache by going to Develop, then Empty Caches. To enable the Develop menu, go to Safari, then Settings, then Advanced.
25. Check for system and app updates. Confirm both your operating system and browser are fully up to date. Software updates often include bug fixes and performance improvements that resolve known issues.
26. Use incognito or private browsing mode. Incognito and private browsing modes do not store cache or cookies. If Alvys works correctly in incognito mode, the issue is related to your browser's stored data. Clear it using the cache and cookies step above.

After completing the applicable steps, Alvys should load correctly and your login issues or display problems should be resolved. If your browser-level data was the root cause, clearing cache and cookies is typically sufficient.

## Troubleshooting

### Page still not loading after clearing cache

1. Confirm you cleared cache with the All time time range — partial clears (such as "last hour") may not remove the affected data.
2. Try incognito mode to confirm whether stored data is the cause.
3. Check for service outages. Visit [https://alvys.statuspage.io/](https://alvys.statuspage.io/) for real-time status updates. If no outage is listed and the issue persists, contact Alvys Support through the Help button in the bottom-left corner of Alvys.

### Login fails after clearing cache

1. Clear cookies specifically (not just cache) — cookies store session tokens that can become corrupted.
2. Try a different browser to determine whether the issue is browser-specific.
3. If login continues to fail on all browsers, check the Alvys status page at [https://alvys.statuspage.io/](https://alvys.statuspage.io/) for any ongoing incidents. If none are listed, contact Alvys Support through the Help button in the bottom-left corner of Alvys.

### DNS errors when accessing Alvys

1. Flush the system DNS cache.
2. Clear your browser's own DNS cache.
3. Try a different network connection to rule out a network-level DNS issue.

### The issue is specific to an Alvys feature, not your browser

Some problems in Alvys are caused by product-level issues or permission settings, not stored browser data. Browser troubleshooting will not resolve these — check the relevant article instead.

<Warning>
  **Load Board columns appearing very wide and unable to resize:** This was a known platform-wide issue resolved on July 6, 2026. A page refresh typically fixes it immediately. If the problem recurs, see the [Alvys Load Board](/en/help/loads-trips/alvys-load-board) Troubleshooting section for full steps. Clearing your browser cache will not resolve this.
</Warning>

<Note>
  **Specific buttons or features grayed out or unavailable:** If a button, menu, or section in Alvys is inaccessible (and the rest of the page loads normally), this is a permissions issue — not a browser or cache problem. See [Billing Permissions](/en/help/administration/billing-permissions) or [Dispatch Permissions](/en/help/administration/dispatch-permissions) to check and update access.
</Note>

### If the issue persists — before contacting support

If none of the steps in this article resolve your issue, gather the following before reaching out to Alvys Support. Providing this upfront helps the team diagnose your problem without going back and forth:

1. **Browser and version:** Visit [whatismybrowser.com](https://www.whatismybrowser.com/) for the exact name and version number.
2. **Operating system:** Windows or Mac, and which version (for example, Windows 11 or macOS Sequoia).
3. **Exact error message:** Copy the full error text, or take a screenshot. Vague descriptions like "it doesn't work" make diagnosis difficult.
4. **Steps already tried:** List which steps from this article you completed so Support does not ask you to repeat them.
5. **Incognito / private browsing result:** Does the problem occur in incognito mode? If not, stored browser data is the cause and cache clearing should fix it. If yes, it may be a platform-level issue.
6. **Other browser test:** Does the problem occur in a different browser (for example, Chrome if you normally use Firefox)? If not, the issue is browser-specific. If yes, it is likely a platform or account issue.

## FAQs

**Q: How often should I clear my cache?**

**A:** There is no required cadence. Clear your cache and cookies whenever you notice display issues, login problems, or slow performance in Alvys. Routine clearing is not necessary.

**Q: Will clearing cookies log me out of other websites?**

**A:** Yes. Clearing all cookies will sign you out of any website where your session is stored in the browser. If you want to clear cookies only for Alvys, use your browser's per-site cookie management tools.

**Q: What is the difference between clearing the browser DNS cache and the system DNS cache?**

**A:** The system DNS cache is managed by your operating system and affects all applications. The browser DNS cache is maintained separately by your browser and only affects browser traffic. Both may need to be cleared if you are experiencing DNS-related access issues.

**Q: Does Alvys support all browsers?**

**A:** Alvys works best on up-to-date versions of Chrome, Firefox, Edge, and Safari. If you are using a browser version that is significantly out of date, some features may not behave as expected. Confirm your browser is current.

## Go Deeper

* [How to Contact Alvys Support](/en/help/getting-started/how-to-contact-alvys-support)
* [Alvys Load Board](/en/help/loads-trips/alvys-load-board)


# How to Contact Alvys Support
Source: https://docs.alvys.com/en/help/getting-started/how-to-contact-alvys-support

Reach the Alvys Support team through in-app chat, email, phone, or text, and check the status page for outages before you open a ticket.

Alvys Support is available by chat, email, phone, and text. This article lists every contact channel, hours of operation, and how to check for service outages before reaching out.

## Overview

If you need help with Alvys, the support team is available through multiple channels, also called contact methods or support options. You can reach out by chat (in-app messenger) directly inside Alvys, by email, by phone, or by text. The Alvys status page also lets you check for any ongoing service disruptions or outages before contacting support. Contacting support is available to all users.

## Prerequisites

No special role or permission is required. Any Alvys user can use all contact channels described in this article.

<Tip>
  **Before reaching out — check these articles first:** many common issues have a self-service fix that's faster than waiting for a response.

  * **Page loading slowly, displaying incorrectly, or login issues** → [Cache, Cookies & Browser Troubleshooting](/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues)
  * **A feature or button is grayed out or unavailable** → [Dispatch Permissions](/en/help/administration/dispatch-permissions) or [Billing Permissions](/en/help/administration/billing-permissions) (access issues are almost always a permissions problem, not a browser problem)
  * **Load Board columns appear very wide or won't resize** → [Alvys Load Board](/en/help/loads-trips/alvys-load-board) Troubleshooting section
  * **Can't revert a load status** → [Understanding Load Statuses and How to Revert Them](/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them)
  * **Driver Settlements questions** → [Driver Settlements FAQ](/en/help/accounting-settlements/driver-settlements-faq)
</Tip>

## Steps

1. Open the Help chat in Alvys.
2. Log in to Alvys.
3. Click the **Help** button in the bottom-left corner of the navigation sidebar.
4. The Alvys Support Messenger opens. Type your question or describe the issue to connect with a support agent.
5. Contact support by email.
6. Send your question or issue description to: [support@alvys.com](mailto:support@alvys.com)
7. Include your company name, the specific feature or page involved, and any steps you have already tried.
8. Contact support by phone.
9. Call the support team directly at: **(619) 782-0122**
10. Contact support by text.
11. You can also text the support team for quick assistance. Text the support number at: **(619) 782-0122**

After using any of the channels above, a support agent will respond during business hours. For non-urgent questions outside of business hours, email is recommended so your request is queued for the next available agent.

## Troubleshooting

### Check for service outages before contacting support

Before contacting support for an access issue or unexpected error, check whether there is an active Alvys service disruption:

1. Visit the Alvys Status page at: [https://alvys.statuspage.io/](https://alvys.statuspage.io/)
2. Review the current status of all Alvys services.
3. To receive automatic notifications for future incidents, enter your email address on the status page and subscribe.

If an outage is listed that matches your symptoms, no action is required on your end. The issue will be resolved as part of the incident response.

## FAQs

**Q: What are the Alvys Support hours of operation?**

**A:** Support is available Monday through Friday, 5:00 AM to 7:00 PM CST, and Saturday through Sunday, 7:00 AM to 4:00 PM CST.

**Q: Which contact method gets the fastest response?**

**A:** The in-app chat via the Help button in the bottom-left corner of Alvys typically connects you to an agent fastest during business hours. Email and phone are also monitored during operating hours.

**Q: Where can I check if Alvys is experiencing an outage?**

**A:** Visit [https://alvys.statuspage.io/](https://alvys.statuspage.io/) for real-time status updates on all Alvys services. You can also subscribe on that page to receive email notifications for future incidents.

**Q: Can I contact support outside of business hours?**

**A:** You can send a message via the in-app Help chat or email [support@alvys.com](mailto:support@alvys.com) outside of business hours. Messages are queued and a support agent will follow up when business hours resume.

## Go Deeper

* [How to Clear Cache, Cookies, and Troubleshoot Common Issues](/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues)


# How to navigate the catalogs
Source: https://docs.alvys.com/en/help/getting-started/how-to-navigate-the-catalogs

Explore the Analytics Catalog of metrics and attributes and the Visualizations catalog of saved charts to build Custom Reports dashboards fast.

Custom Reports is built on two catalogs: the Analytics Catalog of raw building blocks (metrics, facts, and attributes) and the Visualizations catalog of saved charts. This guide shows you how to find your way around both so you can build and assemble dashboards quickly.

## Overview

Custom Reports (also called the data catalog, analytics catalog, or reporting catalog) is built on two catalogs, and they are the starting point for everything you do here. The **Analytics Catalog** is the raw material: the metrics, facts, and attributes you combine to make a chart. The **Visualizations catalog** is your team's shared library of saved charts, KPIs, and tables, ready to drop onto a dashboard. Knowing which catalog holds what, and how to search each one, is the fastest way to go from a question to a finished dashboard tile.

## Before You Start

You need access to Custom Reports before the catalogs appear. You can open and use the catalogs if you are an Admin, Partner Admin, or Support user, or if a Partner Admin or Support user has assigned you a Reporting Access role of "analytic" or "viewer". The role is set from the **"Reporting Access"** dropdown in the User Info section of Manage Users. The **"analytic"** role lets you build and save dashboards and visualizations and see shared dashboards. The **"viewer"** role lets you see only the dashboards that have been explicitly shared with you. A user with no Reporting Access role assigned cannot open the catalogs. Building and saving new visualizations requires your company to be on the **Custom** reporting tier; on the **Free** tier, reporting is read-only. The Analytics Catalog lives in the left panel of the Report Designer; the Visualizations catalog appears in the left panel of the Dashboard editor and in the Designer's Open dialog.

## Steps

### Open the Analytics Catalog in the Report Designer

Open the Report Designer. The Analytics Catalog lives in the left panel. Every chart and KPI in Reports is built from items in this catalog: you drag them into the bucket drop zones in the Configuration panel, and the canvas renders the result.

<Note>
  <img alt="Report Designer with the Analytics Catalog in the left panel. Upload the image here" />

  *Report Designer with the Analytics Catalog in the left panel. Upload the image here*
</Note>

### Recognize the three kinds of catalog items

The Analytics Catalog has three kinds of items: metrics, facts, and attributes.

<Note>
  <img alt="The three item types in the Analytics Catalog (metrics, facts, attributes)." />

  *The three item types in the Analytics Catalog (metrics, facts, attributes).*
</Note>

**Metrics are already-computed numbers.** A metric is a formula that is already wired up for you. Drop one into the **Metrics** bucket and the canvas renders a number, a KPI, or a chart series. Most dashboard tiles only ever need a metric. Examples include Load Count, Trip Count, Trips Completed, Total Revenue, Total Carrier Cost, Active Drivers, On-Time Delivery %, On-Time Pickup %, Average Delivery Delay, Margin per Load, Gross Margin %, Loaded Miles, and Empty Miles.

**Facts are raw numeric columns.** A fact is the underlying numeric column from your data, the raw value before any formula wraps it. Facts are mainly used inside MAQL formulas, where you wrap them with an aggregation like SUM of a fact. If you are not writing MAQL, you will rarely touch facts directly.

**Attributes are the "by what" of a question.** An attribute is a category, the dimension you slice a number by, for example "Revenue by customer" or "load count by month". Drop attributes into the **View by**, **Rows**, **Columns**, or **Stack by** buckets, or onto the filter bar. Examples include Customer, Carrier, Driver, Lane, Subsidiary, Equipment Type, **Load Status**, Trip Picked Up At, Trip Created At, Trip Delivered At, and Load Invoiced At (date attributes). Date attributes can be grouped by Month, Quarter, Year, and so on using the **Group by** option on the bucket chip.

### Search the Analytics Catalog for what you need

Type a business word in the search box at the top of the Analytics Catalog panel, for example Revenue, Customer, Lane, On-Time, or Margin. The panel filters as you type. When two items share a similar name, for example Revenue and Total Revenue, prefer the simpler one and let dashboard filters do the slicing.

### Open the Visualizations catalog

The Visualizations catalog is your team's shared library of finished charts: KPIs, trends, tables, and breakdowns that someone has already built and saved. It is separate from the Analytics Catalog: instead of raw building blocks, it contains complete visualizations you drop straight onto a dashboard. You will meet it in two places: the **left panel of the Dashboard editor** (when assembling a dashboard, search here and drag finished tiles onto the grid), and the **Designer's Open dialog** (when you want to load and tweak an existing visualization).

<Note>
  <img alt="Visualizations catalog in the left panel of the Dashboard editor. Upload the image here" />

  *Visualizations catalog in the left panel of the Dashboard editor. Upload the image here*
</Note>

<Note>
  <img alt="The Designer's Open dialog showing saved visualizations. Upload the image here." />

  *The Designer's Open dialog showing saved visualizations. Upload the image here.*
</Note>

Your tenant ships with a rich library of Alvys-curated visualizations. A sample includes Total Revenue, Total Revenue Trend, Total Carrier Cost, Load Count Trend, Trips Completed, On-Time Delivery %, On-Time Pickup % Trend, Top 10 Customers by Revenue, Top 15 Lanes by Margin %, Top 15 Lanes by Total Gross Margin, Revenue by Equipment Type, Margin Heat Map, Margin per Load Trend, Profitability vs Volume, Loaded vs Empty Miles Weekly Trend, Stop Dwell Time Distribution, Late Trips Today, and Negative Margin Loads. When someone saves a new visualization, it lands in this catalog and becomes available to everyone with Reporting Access on your tenant.

### Search the Visualizations catalog for what you need

Type a business word in the search box. Search for what you are trying to show, not the underlying data field name: "Revenue" finds revenue tiles and trends; "On-Time" finds OTD and OTP variants; "Customer" finds customer breakdowns; "Margin" finds margin heat maps and trends; "Top" finds the Top-N tables and bar charts.

<Warning>
  ⚠️ Name new visualizations clearly. When you save a visualization, it lands in the Visualizations catalog for everyone on your tenant. A clear, business-word name (for example "Revenue YoY % by Customer") is much easier for your teammates to discover than a code-style name.
</Warning>

## Result

You can now move confidently between the two catalogs. You know that the Analytics Catalog holds the raw building blocks (metrics, facts, and attributes) you combine in the Report Designer, and that the Visualizations catalog holds the finished charts you drag straight onto a dashboard. You can search each catalog by business word and pick the right item for the question you want to answer.

## Variations

* Building a brand-new tile: work in the Analytics Catalog inside the Report Designer.
* Reusing something your team already made: work in the Visualizations catalog, from the Dashboard editor or the Designer's Open dialog.
* Working with dates: drop a date attribute, then use the Group by option on the bucket chip to group by Month, Quarter, or Year.
* Writing a custom metric: facts come into play only when you write MAQL formulas.

## Troubleshooting

### A teammate cannot see the catalogs at all

1. Confirm the user has a Reporting Access role. A user with no role assigned gets no catalog access.
2. Have a Partner Admin or Support user open Manage Users, find the user, and set the **"Reporting Access"** dropdown to "Analytic" or "Viewer".
3. Ask the user to sign out and sign back in so the new access takes effect.

### Cannot save a new visualization

1. Confirm your company is on the **Custom** reporting tier. On the **Free** tier, reporting is read-only and saving new visualizations is blocked.
2. Confirm your Reporting Access role is "Analytic". The "Viewer" role can see shared dashboards but cannot author or save.

### A search returns nothing

1. Search by a business word rather than an internal field name, for example "Revenue", "On-Time", or "Margin".
2. Confirm you are searching the right catalog. The Analytics Catalog holds metrics, facts, and attributes; the Visualizations catalog holds finished charts.

## FAQs

**Q: What is the difference between the Analytics Catalog and the Visualizations catalog?**

**A:** The Analytics Catalog holds the raw building blocks (metrics, facts, and attributes) you combine to build a chart in the Report Designer. The Visualizations catalog holds complete, saved charts that you drop straight onto a dashboard.

**Q: Do I need to learn about facts to use Custom Reports?**

**A:** No. Facts are the raw numeric columns used inside MAQL formulas. If you are not writing custom metrics with MAQL, you will rarely touch facts. Most users work entirely with metrics and attributes.

**Q: When two items have similar names, such as Revenue and Total Revenue, which should I use?**

**A:** Prefer the simpler one and let dashboard filters do the slicing.

**Q: A teammate saved a visualization. Why can I see it?**

**A:** When anyone on your team saves a new visualization, it lands in the Visualizations catalog and becomes available to everyone with Reporting Access on your tenant.

**Q: How do I group a date attribute by month or quarter?**

**A:** Drop the date attribute into a bucket, then use the **Group by** option on the bucket chip to choose Month, Quarter, Year, and so on.

## Go Deeper

* [Get started with Custom Reports](/en/reporting/get-started/getting-started)
* [Build visualizations with drag-and-drop](/en/reporting/guides/creating-metrics)
* [Advanced: write custom metrics with MAQL](/en/reporting/guides/creating-metrics)
* [Share, export, schedule, alert](/en/reporting/build-custom-reports/share-export-schedule-alert)


# How to Set Up Multi-Factor Authentication (MFA) in Alvys
Source: https://docs.alvys.com/en/help/getting-started/how-to-set-up-multi-factor-authentication-mfa-in-alvys

Enable multi-factor authentication in Alvys using an authenticator app, SMS text codes, or a FIDO2 hardware security key like a YubiKey.

Alvys requires multi-factor authentication (MFA) for all users to protect your account with a second verification step beyond your password. This article explains how to set up and manage MFA using an authenticator app, SMS, or a hardware security key.

## Overview

Alvys uses multi-factor authentication (MFA), also called two-factor authentication or 2FA, to add a second layer of protection to your account. In addition to your password, MFA requires you to verify your identity using something you have: a code from an authenticator app, an SMS text message, or a hardware security key.

MFA is enforced for all users. You will be prompted to set it up when you sign in if it has not yet been configured on your account.

Setting up more than one method is strongly recommended so you always have a backup if one method becomes unavailable.

## Prerequisites

* You must have an active Alvys account.
* To use an authenticator app, download one before starting: Google Authenticator, Microsoft Authenticator, Authy, 1Password, or any TOTP-compatible app.
* To use SMS, confirm your country is in the supported list in the FAQs section below.
* To use a security key, have your FIDO2/WebAuthn hardware device (such as a YubiKey or Feitian key) ready.

## Steps

1. Go to the Alvys sign-in screen and enter your username and password.
2. After signing in, Alvys will prompt you to set up MFA if it has not been configured. You will be asked to choose at least one verification method. <img alt="MFA setup prompt screen shown after sign-in, displaying the three method options" /> *MFA setup prompt screen shown after sign-in, displaying the three method options*
3. Select one of the three available methods: **Authenticator App**, **Phone (SMS)**, or **Security Key**. <img alt="Screen showing the method selection step with Authenticator App, Phone (SMS), and Security Key options" /> *Screen showing the method selection step with Authenticator App, Phone (SMS), and Security Key options*
4. Follow the steps for your chosen method below.

### Option A — Authenticator app (recommended)

1. Select **Authenticator App** when prompted.
2. Open your authenticator app on your phone.
3. Scan the QR code displayed in Alvys. If your app does not support scanning, enter the code manually instead.
4. Your app will begin generating a 6-digit code that refreshes every 30 seconds.
5. Enter the current 6-digit code in Alvys to complete setup.
6. On future sign-ins, open your authenticator app and enter the current code when prompted. <img alt="QR code scan screen shown during authenticator app setup in Alvys." /> *QR code scan screen shown during authenticator app setup in Alvys.*

### Option B — Phone (SMS)

1. Select **Phone (SMS)** when prompted.
2. Enter your mobile phone number including the country code.
3. Alvys will send a 6-digit code to that number via text message.
4. Enter the code in Alvys to complete setup.

<Warning>
  SMS is less secure than an authenticator app. Use it as a backup method rather than your primary. SMS is only available in supported countries — see the full list in the FAQs below.
</Warning>

### Option C — Security key

1. Select **Security Key** when prompted.
2. Insert or tap your FIDO2/WebAuthn hardware key (such as a YubiKey or Feitian device).
3. Follow the on-screen instructions to register the key.
4. On future sign-ins, insert or tap your key when prompted to verify your identity.

Once setup is complete, MFA is active on your account. On future sign-ins from unrecognized devices, new locations, or flagged IP addresses, Alvys will prompt you to verify using your configured method. Trusted devices and recognized locations may not require a prompt on every sign-in.

After completing initial setup, you can add additional verification methods from your profile so you can still access your account if one method becomes unavailable. Password managers such as 1Password and Keeper that support TOTP codes can serve as your authenticator app: add your Alvys MFA setup code to the password manager during the QR code step, and it will generate codes just like a dedicated authenticator app. MFA is designed for individual user logins; service accounts used exclusively for integrations and automations should be secured with a third-party credential management tool that supports 2FA codes, such as Keeper or 1Password, and all individual users must configure MFA with their own credentials.

## Locked out? Lost or changed your phone or device

If you can no longer sign in because you lost your phone, switched to a new device, or can no longer access the number that receives your SMS codes, ask an Admin to reset your MFA from Settings → Organization → Users. If you are a Partner Admin, contact Alvys Support instead.

1. Contact an Admin on your account and ask them to reset your MFA.
2. The Admin opens Settings → Organization → Users, finds your account, and clicks Reset MFA.
3. Once the Admin confirms the reset, sign in with your username and password.
4. When prompted, set up a new MFA method (Authenticator App recommended). See Steps above.

<Tip>
  If you continue to have trouble signing in after the Admin has completed the reset, contact Alvys Support through the in-app Help messenger or at [support@alvys.com](mailto:support@alvys.com) for further assistance.
</Tip>

<Tip>
  To avoid this in the future, set up two methods (for example an authenticator app and SMS). If one becomes unavailable, you can sign in with the other and update your methods yourself — no reset needed.
</Tip>

<Warning>
  A Partner Admin cannot reset another Partner Admin's MFA. Those requests must go through Alvys Support (in-app Help messenger or [support@alvys.com](mailto:support@alvys.com)).
</Warning>

## Troubleshooting

### SMS code not received

1. Confirm your country is in the supported list (see FAQs below). SMS is not available in all countries.
2. Verify you have mobile coverage and that the phone number you entered is correct.
3. Click Resend Code on the Alvys screen to request a new code.
4. If the issue continues after resending, some carriers delay delivery. Switch to an authenticator app instead, as it does not rely on mobile coverage.

### Authenticator app code not accepted

1. Check that your phone's date and time are set to automatic. Authenticator apps require accurate time synchronization; a time drift of more than 30 seconds will produce codes that fail.
2. If the time is correct and codes still fail, remove your Alvys account from the authenticator app and add it again using a new QR code from Alvys.

### Cannot sign in after losing phone or key

1. Try any other MFA method you have configured on your account.
2. If you cannot access any configured method, contact an Admin on your account — they can reset your MFA from Settings → Organization → Users. If the reset doesn't resolve the issue, or if you are a Partner Admin, contact Alvys Support at [support@alvys.com](mailto:support@alvys.com).

## FAQs

**Q: Is MFA required for all users?**

**A:** Yes. MFA is required for all Alvys users. You will be prompted to set it up on your first sign-in if it has not been configured.

**Q: What happens if I skip MFA setup?**

**A:** You will not be able to access your Alvys account until MFA is configured. Setup is required before the account becomes fully accessible.

**Q: How often will I be prompted for MFA?**

**A:** Alvys uses adaptive MFA, which means you are prompted based on risk signals detected at sign-in: a new or unrecognized device, a new location, an unusual location (such as impossible travel between two sign-ins), or an untrusted IP address. If you sign in regularly from a recognized device and location, you may not be prompted on every sign-in. Risk signals will always trigger a prompt regardless of device history.

**Q: Can I add more than one MFA method?**

**A:** Yes. You can configure multiple methods on your account. Having at least two methods (for example, an authenticator app plus SMS) is recommended so you have a backup if one method becomes unavailable.

**Q: What do I do if I lose my phone or security key?**

**A:** Use another MFA method you have configured. If you have no other method available, contact an Admin on your account to reset your MFA from Settings → Organization → Users. If you are a Partner Admin, contact Alvys Support at [support@alvys.com](mailto:support@alvys.com).

**Q: Which countries support SMS verification?**

**A:** SMS-based MFA is available in the following countries: Afghanistan, Australia, Bosnia and Herzegovina, Bulgaria, Canada, Colombia, Egypt, Germany, India, Ireland, Jamaica, Lithuania, Mexico, Moldova, Morocco, Netherlands, North Macedonia, Norway, Philippines, Poland, Serbia, Spain, Turkey, Ukraine, United Kingdom, United States, and Uzbekistan.

**Q: Can I use a TOTP password manager instead of a dedicated authenticator app?**

**A:** Yes. Any TOTP-compatible app or password manager works, including 1Password, Keeper, Bitwarden, and similar tools. During setup, add the Alvys MFA key to your password manager the same way you would in a dedicated authenticator app.

**Q: What is adaptive MFA?**

**A:** Adaptive MFA is an AI-driven risk detection system that analyzes each sign-in attempt and determines whether a verification prompt is necessary. It evaluates signals such as device recognition, location history, and IP address reputation. When risk signals are present, a prompt is required. When no risk signals are detected, sign-in may proceed without a prompt on recognized trusted devices.

**Q: What if I travel frequently? Will MFA block me from signing in?**

**A:** No. MFA will not prevent you from signing in. If you sign in from a new location, the adaptive system may detect it as unusual and prompt you for verification. As long as you have an MFA method configured, you can complete verification and access your account normally.

**Q: Can service accounts use MFA?**

**A:** MFA is designed for individual user logins. Shared or service accounts used only for integrations and automations cannot use interactive MFA. Secure those credentials with a credential management tool that supports 2FA codes, such as 1Password or Keeper. All individual users must use their own credentials and configure MFA.

**Q: Can I reset my own MFA if I'm locked out?**

**A:** If you have lost access to all of your configured MFA methods, contact an Admin on your account — they can reset your MFA from Settings → Organization → Users. If the reset doesn't resolve the issue, or if you are a Partner Admin, contact Alvys Support (in-app Help messenger or [support@alvys.com](mailto:support@alvys.com)). Keeping a second method configured lets you avoid needing a reset.

**Q: Does Alvys give me backup or recovery codes?**

**A:** No. Alvys does not issue one-time backup codes. Instead, set up more than one MFA method so you always have a backup. If you lose access to all methods, ask an Admin on your account to reset your MFA from Settings → Organization → Users.

**Q: I can sign in on my computer but not on my phone — why?**

**A:** Alvys is optimized for desktop. When you sign in on a new device (including your phone), the adaptive system may prompt you for MFA verification. Enter the code from your configured method to continue.

## Go Deeper

* [Signing in to Alvys and account access](/en/help/getting-started/adding-new-users-signing-in)


# My Profile in Alvys
Source: https://docs.alvys.com/en/help/getting-started/my-profile-in-alvys

How every Alvys user manages their personal settings — name, password, integrations, notifications, locale, and tenant access — from the My Profile page.

<Note>
  Manage your personal account settings independently — no Admin required.
</Note>

## Overview

My Profile is your personal settings page in Alvys. It is separate from the Users page that Admins manage — everything here is self-service. You can update your name and contact details, connect personal integrations, set your notification preferences, configure your locale, and switch between tenants. Password resets are handled separately — see the note below.

## Personal details

Update your name, contact information, and profile avatar. These details appear in activity logs, load records, and anywhere your name is displayed throughout Alvys.

<Note>
  🔑 Password resets are not self-service from My Profile. To reset a user’s password, an Admin can trigger a reset from **Settings → Organization → Users** — the same page used for MFA resets. If you are locked out and cannot reach an Admin, use the **Forgot Password** link on the Alvys sign-in screen to receive a reset email.
</Note>

## User integrations

Connect and manage integrations tied to your individual account. These are personal integrations — separate from the company-wide integrations configured by an Admin in the Integrations settings.

## Subsidiary emails

Manage the email addresses associated with different subsidiaries on your account. This is useful when your company operates multiple subsidiary entities and you need distinct contact addresses for each.

## Favorites & quick actions

Pin the actions and pages you use most often to build a personalized shortcut list. Pinned items appear in your navigation for faster access — useful for dispatchers and billers who run the same workflows repeatedly throughout the day.

## Notification & email preferences

Control which Alvys notifications you receive and how they are delivered. You can choose between in-app notifications, email alerts, or both, depending on how you prefer to stay informed about load updates, assignments, and other events.

## Locale

Set your preferred language and regional settings. Locale controls how dates, times, and numbers are displayed throughout your Alvys session.

## Tenant switching

If you have access to more than one Alvys tenant — for example, if your company operates under multiple organizations — you can switch between them from My Profile without signing out and back in.

## FAQs

**Q: Do I need Admin permissions to change my profile settings?**

**A:** No. My Profile is fully self-service for every user. You can update your personal details, manage integrations, and adjust your preferences without any Admin involvement. Password resets require either an Admin or the Forgot Password flow on the sign-in screen.

**Q: Can I reset my own MFA from My Profile?**

**A:** No. If you are locked out and need your existing methods cleared, contact an Admin — they can reset your MFA from Settings → Organization → Users. If you are a Partner Admin, contact Alvys Support.

**Q: What is the difference between My Profile and the Users page?**

**A:** My Profile controls your own personal settings — name, preferences, and integrations. The Users page (Settings → Organization → Users) is for Admins to manage the accounts of everyone on the team.

**Q: Where did the personal settings that used to be in Company Profile go?**

**A:** Personal settings have moved to the dedicated My Profile page. Company Profile continues to hold company-wide settings such as subsidiary configuration, offices, and invoicing — those are unchanged.

## Go Deeper

* [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys)
* [How to Set Up Multi-Factor Authentication (MFA) in Alvys](/en/help/getting-started/how-to-set-up-multi-factor-authentication-mfa-in-alvys)
* [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)


# Product Walkthroughs
Source: https://docs.alvys.com/en/help/getting-started/product-walkthrough

Short videos for the core Alvys workflows, each paired with a written how-to.

Watch a walkthrough, then follow the written article for the current steps. If a screen in the video looks different, trust the article.

<CardGroup>
  <Card title="Admin setup" icon="screwdriver-wrench" href="/en/help/getting-started/admin-setup">
    Users, offices, fleets, and permissions — the account you need before the first load.
  </Card>

  <Card title="Create a load" icon="plus" href="/en/help/loads-trips/how-to-create-a-load">
    New Load form walkthrough, including automated data entry from a rate confirmation.
  </Card>

  <Card title="Dispatch as a carrier" icon="truck" href="/en/help/loads-trips/dispatching-as-a-carrier">
    Assign a driver, truck, and trailer and cover the trip.
  </Card>

  <Card title="Dispatch as a broker" icon="handshake" href="/en/help/loads-trips/dispatching-as-a-broker">
    Cover a load with a carrier, send the rate confirmation, and track the move.
  </Card>

  <Card title="Invoice your customer" icon="file-invoice-dollar" href="/en/help/accounting-settlements/invoicing-your-customer">
    Email, factoring, and online or originals — pick the delivery method you use.
  </Card>

  <Card title="Driver settlements" icon="money-check-dollar" href="/en/help/accounting-settlements/driver-settlements">
    Pay periods, rates, deductions, and generating driver statements.
  </Card>

  <Card title="Safety and maintenance" icon="shield-check" href="/en/help/assets-fleet/safety-and-maintenance-overview">
    Safety records, the Asset Safety Report, and maintenance on trucks and trailers.
  </Card>

  <Card title="Accounting reporting" icon="chart-column" href="/en/reporting/reports/overview">
    Built-in operational and financial reports — and when Custom Reports is a separate add-on.
  </Card>
</CardGroup>


# Start here
Source: https://docs.alvys.com/en/help/getting-started/start-here

The first-week path on Alvys: sign in, set up users and permissions, add your fleet, create a load, and know how to get help.

This is the short path from a new account to a dispatched load. Work the sections in order. Each card opens the full how-to — this page does not replace those articles.

## 1. Set up your account

Sign-in and user access are the first things new teams ask about. An admin creates users and assigns a role; every user then signs in, accepts the terms, and can turn on MFA.

<CardGroup>
  <Card title="Add users and sign in" icon="right-to-bracket" href="/en/help/getting-started/adding-new-users-signing-in">
    Create accounts, sign in, reset a password, and switch organizations.
  </Card>

  <Card title="Add and manage users" icon="user-plus" href="/en/help/administration/how-to-add-and-manage-users-in-alvys">
    Edit, deactivate, and assign roles from Company Profile.
  </Card>

  <Card title="User roles" icon="id-badge" href="/en/help/administration/user-roles-in-alvys">
    What Admin, Dispatcher, Biller, Sales, and Safety can do.
  </Card>

  <Card title="User permissions" icon="user-lock" href="/en/help/administration/overview-of-user-permissions">
    The permission toggles that gate rates, dispatch, billing, and reports.
  </Card>

  <Card title="Set up MFA" icon="shield-halved" href="/en/help/getting-started/how-to-set-up-multi-factor-authentication-mfa-in-alvys">
    Turn on multi-factor authentication for your Alvys login.
  </Card>
</CardGroup>

## 2. Add your fleet

Loads need drivers and trucks. Set these up before you create the first shipment, and get drivers onto the mobile app so they can accept work.

<CardGroup>
  <Card title="Create a driver" icon="id-card" href="/en/help/assets-fleet/how-to-create-a-driver">
    Add a driver profile and the details dispatch needs to assign them.
  </Card>

  <Card title="Add a truck" icon="truck" href="/en/help/assets-fleet/how-to-add-a-truck-in-alvys">
    Create a truck record and attach it to a fleet.
  </Card>

  <Card title="Add and manage fleets" icon="layer-group" href="/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys">
    Group trucks by region, division, or equipment type.
  </Card>

  <Card title="Driver Companion app" icon="mobile-screen" href="/en/help/assets-fleet/driver-companion-mobile-app">
    How drivers sign in, accept loads, and send updates from the phone.
  </Card>
</CardGroup>

## 3. Run your first load

A load is the core record in Alvys. Create it, put it on the board or dispatch it, and know what each status means.

<CardGroup>
  <Card title="Create a load" icon="plus" href="/en/help/loads-trips/how-to-create-a-load">
    Enter the customer, stops, and rates for a new shipment.
  </Card>

  <Card title="Alvys Load Board" icon="table" href="/en/help/loads-trips/alvys-load-board">
    Find available loads and filter the board the way your team works.
  </Card>

  <Card title="Dispatch a load" icon="truck-fast" href="/en/help/loads-trips/how-to-dispatch-a-load">
    Assign a driver or carrier and release the load to the road.
  </Card>

  <Card title="Dispatch Planner" icon="map" href="/en/help/loads-trips/dispatch-planner">
    Plan assignments across drivers, trucks, and the day's work.
  </Card>

  <Card title="Load statuses" icon="signal" href="/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them">
    What each status means and how to move a load back a step.
  </Card>
</CardGroup>

## 4. Get help

<CardGroup>
  <Card title="Contact Alvys Support" icon="headset" href="/en/help/getting-started/how-to-contact-alvys-support">
    How to reach the support team and what to include in a request.
  </Card>

  <Card title="Clear cache and common issues" icon="rotate" href="/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues">
    Fix stale screens, login loops, and other browser issues.
  </Card>

  <Card title="Navigate the catalogs" icon="book" href="/en/help/getting-started/how-to-navigate-the-catalogs">
    Find customers, carriers, locations, and other records from the catalogs.
  </Card>
</CardGroup>

## Product Walkthroughs

Watch a walkthrough, then open the written article. Start at [Product Walkthroughs](/en/help/getting-started/product-walkthrough) or jump to one:

<CardGroup>
  <Card title="Admin setup" icon="screwdriver-wrench" href="/en/help/getting-started/admin-setup">
    Users, offices, fleets, and permissions.
  </Card>

  <Card title="Dispatch as a carrier" icon="truck" href="/en/help/loads-trips/dispatching-as-a-carrier">
    Cover a load with your own driver and truck.
  </Card>

  <Card title="Dispatch as a broker" icon="handshake" href="/en/help/loads-trips/dispatching-as-a-broker">
    Cover a load with an outside carrier.
  </Card>

  <Card title="Invoice your customer" icon="file-invoice-dollar" href="/en/help/accounting-settlements/invoicing-your-customer">
    Email, factoring, or online / originals.
  </Card>

  <Card title="Driver settlements" icon="money-check-dollar" href="/en/help/accounting-settlements/driver-settlements">
    Pay periods, rates, and statements.
  </Card>

  <Card title="Safety and maintenance" icon="shield-check" href="/en/help/assets-fleet/safety-and-maintenance-overview">
    Safety records and the Asset Safety Report.
  </Card>

  <Card title="Accounting reporting" icon="chart-column" href="/en/reporting/reports/overview">
    Built-in reports — Custom Reports is a separate add-on.
  </Card>
</CardGroup>

## After your first week

Once loads are moving, the next questions are usually invoicing, driver pay, and changing a released load. Those live in their own sections — start with [Managing a load](/en/help/loads-trips/managing-a-load) and the Accounting & Settlements guides.


# Troubleshooting PDF Display Issues in Alvys
Source: https://docs.alvys.com/en/help/getting-started/troubleshooting-pdf-display-issues-in-alvys

Troubleshoot PDF display issues, including garbled text, formatting errors, and blank pages. Follow quick fixes or contact us for help.

<Note>
  This article covers common PDF display problems in Alvys, including garbled text, incorrect layout, and blank pages, and provides browser and file-level steps to resolve each issue.
</Note>

This article covers common PDF display problems in Alvys, including garbled or unreadable text, incorrect layout or formatting, and blank or empty pages when opening a PDF. Follow the steps below to identify and resolve the issue.

<Note>
  <img alt="Thumbnail for the PDF display troubleshooting article" />

  *Thumbnail for the PDF display troubleshooting article*
</Note>

## Symptom

You are experiencing one or more of the following when opening a PDF in Alvys:

* Text appears corrupted, garbled, or contains missing characters
* The PDF layout is incorrect, with cut-off text, overlapping content, or formatting errors
* The PDF page is blank or the file fails to open entirely

## Cause

PDF display problems in Alvys are browser-side rendering issues. They are not caused by a specific role or permission setting and can affect any user. Common causes include:

* Missing or unsupported fonts on the user's device
* Encoding issues or an incompatible PDF format or version
* Display scaling problems in the browser-based document viewer
* A corrupted or incomplete PDF file
* Browser cache or temporary files interfering with how the PDF loads
* A file too large for the browser's built-in viewer

## Resolution

### Garbled, corrupted, or missing text in a PDF

1. Try opening the same PDF in a different browser (for example, if you are using Chrome, try Firefox or Edge) or on a different device. If the PDF displays correctly elsewhere, the issue is specific to your current browser or system font settings.
2. Download the PDF and open it using Adobe Acrobat Reader instead of the browser viewer. Acrobat provides broader font support and may render the document correctly even when the browser viewer cannot.
3. If the problem occurs across multiple browsers and devices, the PDF file itself may be corrupted. Contact the person who generated or uploaded the file and ask them to regenerate or re-upload it.

### Incorrect layout or formatting (cut-off text, overlapping content)

1. Use the **Rotate** or **Zoom** options in the Alvys document viewer to adjust how the document is displayed.
2. Download the PDF and open it in Adobe Acrobat Reader or another dedicated PDF viewer to confirm whether the layout issue is in the file or the viewer.
3. If the file was created from a scanned document, check the scan resolution. Low-resolution scans can cause readability and layout problems. If the scan quality is insufficient, ask for a higher-resolution rescan or a re-upload.

### Blank page or PDF fails to open

1. Refresh the page and try opening the file again.
2. Clear your browser cache and cookies, then attempt to open the PDF again. In most browsers this is found under Settings > Privacy > Clear browsing data (select Cached images and files and Cookies).
3. Download the PDF and open it using Adobe Acrobat or another PDF reader to confirm whether the file itself contains content.
4. If the downloaded file also shows a blank page or fails to open, try opening it on a different device. If the problem appears on all devices, the document may be corrupted, incomplete, or empty and will need to be re-uploaded or regenerated.

## If That Didn't Work

If you have completed all the steps above and the issue persists, contact Alvys Support with the following information:

* The file name and a screenshot showing the problem
* The browser name and version you are using (for example, Chrome 124, Firefox 125)
* The device type and operating system (for example, Windows 11, macOS 14)
* Any error messages displayed on screen

## Related

* [Common issue resolution](/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues)
* [Related help article](/en/help/getting-started/adding-new-users-signing-in)


# Alvys Help Center
Source: https://docs.alvys.com/en/help/index

How-to guides, tutorials, and troubleshooting for the Alvys platform — covering onboarding, administration, integrations, loads, accounting, and fleet management.

<div>
  <div>
    <div />

    <div />

    <div>
      <div>
        Guides & Troubleshooting
      </div>

      # Alvys Help Center

      <p>
        Get set up, connect your tools, and run your day-to-day operation on Alvys.
      </p>

      <div>
        <button type="button" aria-label="Search the Help Center">
          <svg>
            <path />

            <path />
          </svg>

          <span>Search for an article…</span>
          <kbd>⌘K</kbd>
        </button>
      </div>

      <div>
        <a href="/en/help/getting-started/start-here">
          Get Started

          <svg>
            <path />
          </svg>
        </a>

        <a href="/en/help/what-s-new">
          What's New
        </a>
      </div>
    </div>
  </div>
</div>

<div>
  <div>
    <h2>Start here</h2>
    <p>New to Alvys, or setting up your team for the first time. The full first-week path is on <a href="/en/help/getting-started/start-here">Start here</a>.</p>
  </div>

  <CardGroup>
    <Card title="Adding Users & Signing In" icon="rocket" href="/en/help/getting-started/adding-new-users-signing-in">
      Create accounts, sign in, and switch between organizations.
    </Card>

    <Card title="Create a Load" icon="plus" href="/en/help/loads-trips/how-to-create-a-load">
      Enter the customer, stops, and rates for a new shipment.
    </Card>

    <Card title="Product Walkthroughs" icon="chalkboard-user" href="/en/help/getting-started/product-walkthrough">
      Go-live recordings paired with the written articles.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>Run your operation</h2>
    <p>Day-to-day work, from tender to settlement.</p>
  </div>

  <CardGroup>
    <Card title="Loads & Trips" icon="truck-fast" href="/en/help/loads-trips/alvys-load-board">
      Create, dispatch, modify, and track loads and trips end to end.
    </Card>

    <Card title="Accounting & Settlements" icon="file-invoice-dollar" href="/en/help/accounting-settlements/how-to-issue-and-manage-e-checks-in-alvys">
      Invoicing, driver and carrier settlements, deductions, and e-checks.
    </Card>

    <Card title="Assets & Fleet" icon="truck" href="/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys">
      Add and manage drivers, trucks, trailers, and fleets.
    </Card>

    <Card title="Reporting" icon="chart-column" href="/en/reporting/">
      Metrics, dashboards, operational and financial reports, and the data model behind them.
    </Card>

    <Card title="Administration" icon="sliders" href="/en/help/administration/user-roles-in-alvys">
      Roles, permissions, offices, and subscription management.
    </Card>

    <Card title="Safety & Compliance" icon="shield-check" href="/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys">
      Verify motor carriers and keep your operation compliant.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>Connect your tools</h2>
    <p>Bring your ELD, load boards, accounting, fuel, and factoring providers into Alvys.</p>
  </div>

  <CardGroup>
    <Card title="ELD & Telematics" icon="satellite-dish" href="/en/help/integrations/connecting-roadstar-to-alvys">
      Connect your ELD provider for HOS, location, and asset tracking.
    </Card>

    <Card title="Accounting" icon="calculator" href="/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys">
      Sync invoices and payments with QuickBooks, Sage Intacct, or Business Central.
    </Card>

    <Card title="Load Boards" icon="clipboard-list" href="/en/help/integrations/post-loads-to-dat-load-board">
      Post and source freight on DAT, Truckstop, and other boards.
    </Card>

    <Card title="EDI & Visibility" icon="arrow-right-arrow-left" href="/en/help/integrations/how-to-configure-edi-auto-update-settings">
      Trade tenders and status updates with your customers.
    </Card>

    <Card title="Fuel & Tolls" icon="gas-pump" href="/en/help/integrations/bestpass-toll-integration">
      Import fuel and toll transactions for settlements and IFTA.
    </Card>

    <Card title="Factoring & Payments" icon="money-bill-transfer" href="/en/help/integrations/how-to-set-up-and-use-factoring-in-alvys">
      Set up factoring and move money against your invoices.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <div>
      <h2>Building on Alvys?</h2>
      <p>Developers can move to the Public API documentation for REST endpoints, webhooks, and the MCP server.</p>
    </div>

    <a href="/en/api">
      API Documentation

      <svg>
        <path />
      </svg>
    </a>
  </div>
</div>

<div>
  <div>
    <h2>Still need a hand?</h2>
    <p>Catch up on recent changes, or get in touch with the support team.</p>
  </div>

  <CardGroup>
    <Card title="What's New" icon="bullhorn" href="/en/help/what-s-new">
      Latest releases, enhancements, and product updates.
    </Card>

    <Card title="Troubleshooting" icon="circle-question" href="/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues">
      Clear cache and cookies, and fix the most common issues.
    </Card>

    <Card title="Contact Support" icon="envelope" href="/en/help/getting-started/how-to-contact-alvys-support">
      Reach the Alvys support team and track your request.
    </Card>
  </CardGroup>
</div>


# Alvys Load Board
Source: https://docs.alvys.com/en/help/loads-trips/alvys-load-board

Navigate the Alvys Load Board, customize columns and filters, and use the summary bar to view load totals and analytics for efficient dispatch.

<Note>
  **Scope:** This article covers Load Board navigation, column management, filtering, sorting, and right-click actions. For related topics see [Load statuses and how to revert them](/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them), [Dispatch permissions](/en/help/administration/dispatch-permissions), [Billing permissions](/en/help/administration/billing-permissions), [Driver settlements](/en/help/accounting-settlements/driver-settlements), and [Clear cache, cookies, and troubleshoot common issues](/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues).
</Note>

## Navigation & Setup

**Summary:** The Load Board provides a dynamic table view of all your loads. You can customize which columns are visible and their order, apply various filters to narrow down your data, and use the summary bar at the bottom to get real-time totals and analytics. This allows you to tailor your view for efficient load management and quick decision-making.

### The Steps to Navigate to the Load Board

There are several convenient ways to access the Alvys Load Board from anywhere in the application:

**From the Home Screen (Left Side Panel Navigation):**

* On the left-hand side navigation panel, click **"Loads and Trips."**
* Then, select the **"Loads"** option from the submenu.

<img alt="Loads and Trips submenu in the left side navigation panel" />

**Via Search:**

* From the home screen, click **"Search"** in the left side panel.
* Type in a **load number** (or other search query).
* Click **"Loads"** in the search results.
* If the results are not what you expected, click the link that says **"Not the results you expected? View load board."** This will take you directly to the Load Board.

<img alt="Search results panel with the View load board link" />

**Keyboard Shortcut:**

At any time, you can press `Command + L` **(Mac)** or `Ctrl + L` **(Windows/Linux)** on your keyboard. This will instantly take you to the Load Board.

**Double clicking a row in the table:**

Once you have navigated to the Load Board, any time you double click a row it will open the Load Details Page in a new browser tab.

### Adding, Removing, and Reordering Columns

The Load Board features a highly customizable table view. You can choose which data points (columns) you want to see, and how they are ordered and displayed. Ensure the **"Loads" tab** is selected on the board.

**Using the "Columns" Tab:**

* On the far right side of the table header, click the **"Columns" tab**.
* A panel will appear with a list of all available columns.
* To **show a column:** Ensure the **checkbox** next to its name is checked.
* To **hide a column:** Uncheck the checkbox.

<img alt="Columns panel with checkboxes for showing and hiding columns" />

* To **reorder columns:** Click and drag the **square dotted icon** next to a column name to change its position in the list. This will update its order on the table.

<img alt="Dragging the dotted handle to reorder a column" />

* You can also use the **search bar** at the top of this panel to quickly find a specific column name.

<img alt="Search bar at the top of the Columns panel" />

**Directly from the Table Header (Drag and Drop):**

* You can also click and hold down on any **column header** directly on the table.
* **Drag and drop** the column to your desired position in the table.

<img alt="Dragging a column header to a new position in the table" />

**Pinning Columns**

Pinning columns allows them to remain visible on your screen even when you scroll horizontally. This is useful for keeping key identifiers (like Load Number) always in view.

**Click the Hamburger Icon:** Hover over any column header until a **hamburger icon** (three horizontal lines) appears. Click this icon.

<img alt="Hamburger icon on a column header" />

**Select "Pin Column":** From the dropdown menu, select **"Pin Column."** Then choose a pin option:

* **"Pin Left":** The column will always be the leftmost column, staying in your viewport even with horizontal scrolling.
* **"Pin Right":** The column will always be the rightmost column, staying in your viewport even with horizontal scrolling.
* **"No Pin":** The column will not be pinned and will scroll horizontally with the rest of the table.

<img alt="Pin Column options in the column dropdown menu" />

**Auto-Sizing and Resetting Columns**

**Auto-Size This Column**

* Click the **hamburger icon** in a column header.
* Select **"Autosize this column"** to adjust the column width to fit its content, wrapping text as needed.

**Auto-Size All Columns**

* Click the **hamburger icon** in any column header.
* Select **"Autosize all columns"** to adjust all visible columns to fit their content.

**Reset Columns**

* Click the **hamburger icon** in any column header.
* Select **"Reset columns"** to revert all columns back to their default widths and order that you had previously set up.

<img alt="Autosize and Reset columns options in the column menu" />

### Filtering Columns

The Load Board offers powerful filtering and sorting capabilities to help you quickly find and organize the loads you need.

**Filtering Columns Individually**

**Access Filter Options:** Hover over any column header and click the **hamburger icon** (three horizontal lines).

**Click "Filter":** From the dropdown menu, click the **"Filter" icon**.

**Enter Search Criteria:** A search bar will appear. Type your desired text or value into this search bar.

**Choose Filter Method:** You can select different methods for how you're filtering your data:

* **"Contains":** Shows results that include your text anywhere.
* **"Does not contain":** Excludes results that include your text.
* **"Equals":** Shows exact matches.
* **"Does not equal":** Excludes exact matches.
* **"Begins with":** Shows results that start with your text.
* **"Ends with":** Shows results that end with your text.
* **"Blank":** Shows records where the field is empty.
* **"Not blank":** Shows records where the field is not empty.

**Apply Filter:** The table will dynamically update based on your selected criteria.

<img alt="Column filter menu with filter method options" />

<img alt="Filtered Load Board results" />

<Warning>
  Active column filters do not persist between sessions — only column visibility and order are saved. A filter you have forgotten about is the most common reason a load appears to be missing from the board. Look for the filter icon on a column header and clear it.
</Warning>

### Sorting Columns

You can sort most columns to organize your data ascending or descending.

**Click Column Header:** Click directly on the **header** of the column you wish to sort.

**Toggle Sort Order:**

* Clicking once will sort in one direction
* Clicking a second time will sort in the opposite direction

<Note>
  Only one column can be sorted at a time.
</Note>

<img alt="Sorted column on the Load Board" />

### Page-Wide Search

In addition to individual column filters, you can perform a search across the entire visible table.

**Click Page Search Button:** Locate and click the **"Page Search"** button in the header.

**Enter Search Term:** Type in a term to search across all displayed columns in the current view.

<img alt="Page Search button and input in the Load Board header" />

### Additional Load Board Filters

At the top of the Load Board, you may find additional quick filters:

* **"Loads/Trips"**: Ensure Loads is selected to display loads in the rows of the table. If you select Trips, it will display the trips in the rows.
* **"Loads Today" or "Trips Today":** Filters the table to only display loads scheduled for the current day. This means any load or trip that has a pickup or delivery date in the local timezone of the user.
* **"My Loads" or "My Trips":** Filters the table to show loads where you have a named role or responsibility. A load or trip appears under **My Loads** or **My Trips** if you are listed in any of the following capacities:
  * You invoiced the load
  * You created the load
  * You cancelled the load
  * You dispatched the load
  * The load was dispatched on your behalf
  * You released the load to billing
  * You are the assigned customer service rep
  * You are the assigned customer sales agent
  * You are the assigned customer sales manager
  * You are the assigned customer load planner
  * You are the assigned customer account manager
  * You are the assigned carrier sales agent

<img alt="Quick filters at the top of the Load Board" />

### Pagination

The Load Board is paginated to manage large datasets.

* **Page Size:** At the bottom right of the table, you can set the number of rows displayed per page (e.g., 20, 50, 100, 200, 500 rows).
* **Navigation Arrows:** Use the navigation arrows to move between pages (e.g., to page 2, page 3).
* **First/Last Page:** Click the far right or far left arrows to go directly to the first or last page of results.

<img alt="Pagination controls at the bottom of the Load Board" />

### Understanding the Summary Bar

At the bottom of the Load Board, a **summary bar** provides quick, aggregated insights into the data currently displayed in your table.

* **Total Number of Rows:** Shows the total count of loads matching your filters.
* **Selected Rows:** Displays how many loads you currently have selected.
* **Total Loaded Miles:** Sum of loaded miles for all displayed loads.
* **Total Customer Revenue:** Sum of customer revenue for all displayed loads.
* **Total Carrier Rate:** Sum of carrier rates for all displayed loads.
* **Gross Margin Percentage:** Calculated gross margin percentage.
* **Gross Margin:** Total gross margin amount.
* **Total Trip Value:** Overall value of trips displayed.
* **Average Loaded RPM (Revenue Per Mile):** Average revenue per loaded mile.
* **Average Total RPM:** Average revenue per total mile (loaded + empty).

<img alt="Summary bar showing aggregated totals for the displayed loads" />

## Side Panels

The Side Panel is designed to give you an at-a-glance overview of a load or trip without needing to navigate to the full Load Details Page immediately. Its content changes to display the most relevant information based on the load or trips status (e.g., "Open," "Dispatched," "Delivered"). The panel also provides quick actions and deep links to related profiles and reports.

### Accessing the Right Side Panel & General Features

**Navigate to the Load Board**

* **Click a Load Row:** Perform a single **click** anywhere on the row of the desired load.
* **Panel Appearance:** A side panel will appear on the right-hand side of your screen, displaying additional information about the selected load or trip.

<img alt="Right side panel open next to the Load Board" />

**General Features**

* **Copy to Clipboard Icon:** Throughout the side panel, you will see an icon that looks like two little boxes overlaid on top of each other. This allows you to quickly copy the adjacent information (e.g., load number, address) to your clipboard for easy pasting elsewhere.
* **Deep Links:** Many names (Customer, Carrier, Truck, Driver, Trailer) and links (Lane) are **hyperlinked**. Clicking these will typically open the related profile page or report in a new browser tab.

<img alt="Copy to clipboard icon and deep links in the side panel" />

### Side Panel Content

Content in this section varies by Load Status (Open, Covered, Dispatched, In Transit, Quoted, TONU, Delivered, Reserved).

* **Top-Level Company / Customer / Broker Info:**
  * Name (deep-linked to Company Page)
  * Address
  * Email
  * Phone Number
* **Load Info Section:**
  * Load Status
  * Load Number
  * Order Number
  * Sales Margin
  * Sales Difference
  * Rate
  * External Board Rate
  * Office
  * Fleet (Load Fleet)
  * Lane (to/from address, deep-linked to Lane Report)
  * Created (date/timestamp)
* **Rates Button:**
  * A "Rates" button that opens the Rates Modal
  * Lane addresses shown underneath Rates
* **Trip Breakdown Section:**
  * Breakdown of Trips
  * If split load, clickable to update panel context for stops section.
  * If not split load, shows original trip lane.
* **Carrier Section:**
  * Carrier Name (deep-linked to Carrier Profile)
  * MC Number
  * Email
  * Phone Number
* **Stops Section:**
  * Status of each stop
  * Address of the stop
  * Pick/Drop Location
  * Timestamp (pick/drop information)
* **Vehicle Info Section:**
  * Truck (deep-linked to Edit Truck page)
  * Primary Driver, shown as Driver 1 (deep-linked to Driver Profile)
  * Secondary Driver, shown as Driver 2 (deep-linked to Driver Profile)
  * Trailer (deep-linked to Edit Trailer page). The panel shows the trailer assigned to the trip you selected. On a split load, each trip keeps its own trailer, so selecting a different trip in the Trip Breakdown section shows that trip's trailer. When the trip has no trailer assigned, no trailer number is shown.
* **Additional Info Section:**
  * Trip Status
  * Temperature (if equipment type is Reefer)
  * Equipment Type

## Right Click Actions

Right click any row in the table to access a list of actions that can be taken. Actions available varies by Load Status (Open, Covered, Dispatched, In Transit, Quoted, TONU, Delivered, Reserved).

<img alt="Right-click context menu on a Load Board row" />

### Issue E-Check

Right click row. Select Issue E-Check.

A side panel will appear allowing you to Manage E-Check directly from the Load Board.

<img alt="Manage E-Check side panel" />

### Log Check Call

Right click row. Select Log Check Call.

A modal will appear allowing you to manage Check Calls directly from the Load Board.

<img alt="Log Check Call modal" />

### Lane Report

Right click row. Select Lane Report.

A new browser tab will open with the Lane Report.

<img alt="Lane Report opened in a new browser tab" />

### Pre-Assign Trailer

Right click row. Select Pre-Assign Trailer.

A modal will appear allowing you to Assign Trailer directly from the Load Board.

Once you save, the board and the side panel show the newly assigned trailer for that trip.

<img alt="Pre-Assign Trailer modal" />

### Manage Assets

Right click row. Select Manage Assets.

A modal will appear allowing you to manage Carrier and Asset Assignment directly from the Load Board.

<img alt="Manage Assets modal for carrier and asset assignment" />

### Set Priority

Right click row. Select Set Priority.

Select Caution, Important or Critical.

The row in the table will change color to correspond with the priority selection.

<img alt="Row color changing to match the selected priority" />

### Post Shipment

Right click row. Select Post Shipment.

This posts the load to DAT.

### Update Rate

Right click row. Select Update Rate.

A modal will appear allowing you to change the Rate directly from the Load Board.

<img alt="Update Rate modal" />

### View Notes

Right click row. Select View Notes.

A side panel will appear allowing you to manage Notes directly from the Load Board.

<img alt="Notes side panel" />

### View Docs

Right click row. Select View Docs.

A side panel will appear allowing you to manage Documents directly from the Load Board.

<img alt="Documents side panel" />

### View Logs

Right click row. Select View Logs.

A side panel will appear allowing you to view Logs directly from the Load Board.

<img alt="Logs side panel" />

### Export

Right click row. Select Export.

Select the file type (CSV or Excel).

<img alt="Export file type options" />

The file will export as a download to your browser. Click the file to open.

<img alt="Exported file downloaded in the browser" />

### Delete Load

Right click row. Select Delete Load.

A modal will appear allowing you to delete the load directly from the Load Board.

<Warning>
  Load deletion is restricted to protect data integrity. If the option is unavailable to you, contact Alvys Support with the load number and they will delete it for you.
</Warning>

<img alt="Delete Load confirmation modal" />

## Frequently Asked Questions (FAQ)

**Q: Can I view Trip data on the Load Board?**

A: Yes, the Load Board has tabs that allow you to switch between **"Loads"** (the Load Board) and **"Trips"** (the Trips Board). You can switch to the "Trips" tab to view trip-specific data.

**Q: What happens if I delete a load from the Load Board?**

A: You can click a load and select the option to delete it. Please note that load deletion typically requires specific user permissions, and it is often a support function to ensure data integrity.

**Q: Does the side panel update in real-time as a load's status changes?**

A: No, if a load's status changes while its row is selected and the side panel is open, the information displayed in the side panel will not dynamically update to reflect the new status and its associated details. However, it will update after you refresh the page.

**Q: Which trailer does the side panel show on a split load?**

A: The panel shows the trailer assigned to the trip you have selected. Each trip on a split load keeps its own trailer, so select a different trip in the Trip Breakdown section to see that trip's trailer. When a trip has no trailer assigned, no trailer number is shown for it.

**Q: Can I edit information directly from the Right Side Panel?**

A: The Right Side Panel is primarily designed for quick viewing and navigation (via deep links). While some elements may have inline editing capabilities, most major edits typically require you to open the full Load Details Page by double-clicking the row.

**Q: How do I save my customized column layout on the Load Board?**

A: Your customized column layouts (which columns are visible, their order, and whether they are pinned) are automatically saved to your user profile. The next time you log in or navigate to the Load Board, your preferred view should be retained. Note: only column visibility and order are saved — active column filters (applied via the column hamburger icon) do **not** persist between sessions and must be re-applied each time.

**Q: What's the difference between "Page-Wide Search" and filtering a column individually?**

A: Page-Wide Search (via the button in the header) searches for your entered term across all displayed columns in the entire visible table. Filtering a column individually (via the hamburger icon in a column header) applies a specific filter method (e.g., "contains," "equals," "begins with") to only that single column. Use page-wide search for a broad lookup, and individual column filters for precise data segmentation.

**Q: Why does the information in the right side panel change when I click on different loads?**

A: The Right Side Panel is designed to be contextual. Its content dynamically changes to display the most relevant information and actions based on the selected load's current operational status (e.g., "Open," "Dispatched," "Delivered"). This helps you quickly access the information critical for that load's stage.

**Q: How often does the data on the Load Board, including the summary bar, update?**

A: The Load Board's data and the summary bar are designed to update frequently, often in near real-time, as loads progress through their lifecycle or as new data comes into the system. For the absolute latest information, a full page refresh (F5 or browser reload) can be performed.

**Q: Do custom references show on the Load Board?**

A: Yes, the Load view shows Load Custom References and the Trip view shows Stop Custom References.

**Q: Why can't I see a specific load on the Load Board?**

A: Work through this checklist in order:

1. **Active column filters:** If a column has a filter applied, it shows a filter icon on the header. Click the hamburger icon on that column and clear the filter. Scroll horizontally to check all columns — a filter you have forgotten can hide loads that otherwise match.
2. **My Loads or Loads Today:** If either quick filter is active at the top of the board, only matching loads appear. Deselect the filter to view all loads.
3. **Loads vs. Trips tab:** Confirm the **Loads** tab is selected at the top — if **Trips** is selected, loads will not appear in the rows.
4. **Pagination:** The board is paginated. If your page size is small (for example, 20 rows), the load may be on a later page. Increase rows-per-page at the bottom right or use the page navigation arrows.
5. **Stale data:** Do a hard refresh (`Ctrl + Shift + R` on Windows, `Cmd + Shift + R` on Mac) to force the board to reload with the latest data.

**Q: My columns appear very wide and I cannot shrink or resize them.**

A: This was a confirmed platform-wide issue (resolved July 6, 2026) where columns in all Alvys tables became oversized and non-resizable. If you encounter this symptom:

1. Refresh the page (F5 or browser reload). In most cases this immediately restores normal column widths.
2. If the issue persists after a full browser restart, try opening Alvys in a new incognito/private window. If that resolves it, clear your browser cache and cookies. See [Clear cache, cookies, and troubleshoot common issues](/en/help/getting-started/how-to-clear-cache-cookies-and-troubleshoot-common-issues).
3. If columns are still stuck after clearing cache, contact Alvys Support — this may indicate a recurrence that engineering needs to investigate.

**Q: Are there any special permissions that I should know about?**

A: Yes. Some columns require a specific permission before they are visible to you.

**Trips Board**

* Requires **View Customer Rate**, a Billing permission, or the Biller role:
  * Customer Revenue
  * Customer Freight Charge
  * Carrier Rate
* Requires **OOP Rate**, a Billing permission, or the Biller role:
  * Trip Value
  * Dispatch Commissionable Amount
* Requires a Billing permission or the Biller role:
  * Factoring Payments
  * Factoring Fee
  * Factoring Escrow
  * Gross Margin
  * Carrier Advances
  * Carrier Detention
  * Carrier Lumper
  * Carrier Late Fee Reimbursement
  * Carrier Other Accessorials
  * Customer Detention
  * Customer Lumpers
  * Customer Late Fees
  * Customer Other Accessorials
  * Customer Linehaul
  * Customer Fuel Surcharge

**Loads Board**

* Requires **View Customer Rate**, a Billing permission, or the Biller role:
  * Customer Revenue
  * Customer Freight Charge
  * Commissionable Amount
  * Carrier Rate
  * Carrier All-in Rate
* Requires a Billing permission or the Biller role:
  * Factoring Payments
  * Factoring Fee
  * Factoring Escrow
  * Customer Payments
  * Gross Margin
  * Carrier Advances
  * Carrier Detention
  * Carrier Lumper
  * Carrier Late Fee Reimbursement
  * Carrier Other Accessorials
  * Customer Detention
  * Customer Lumpers
  * Customer Late Fees
  * Customer Other Accessorials
  * Customer Linehaul
  * Customer Fuel Surcharge

<Tip>
  Permissions are assigned per user in **Settings → Organization → Users**. See [Dispatch permissions](/en/help/administration/dispatch-permissions) and [Billing permissions](/en/help/administration/billing-permissions) for the full permission catalogue.
</Tip>


# Contracted Rates
Source: https://docs.alvys.com/en/help/loads-trips/contracted-rates

Set up contracted rates (contracted lanes) on customer profiles so Alvys automatically applies negotiated lane pricing to matching loads.

<Note>
  Contracted Rates, also called Contracted Lanes, are fixed-rate agreements tied to specific origin-destination pairs on a customer profile. When a load matches the contract's stops, equipment class, and active date range, Alvys can automatically apply the contracted rate to the load.
</Note>

## Overview

Contracted Rates let you pre-negotiate lane rates with customers and store them directly in Alvys. Instead of manually entering rates each time a load is created on a familiar lane, the contracted rate is applied automatically when the load matches the agreement.

Each contract specifies the origin, destination, equipment class, rate type, rate amount, optional minimum rate, and the contract period. Alvys checks all of these conditions before applying a contracted rate to a new load.

Synonyms: contracted lanes, lane rates, contract rates, rate agreements, lane agreements.

## Where to Find It

Contracted Rates are managed on the customer profile in the Companies module.

Navigate to **Companies**, open a customer profile, and select the **Contracted Lanes and Fuel Surcharges** tab. The Contracted Rates section lists all active and expired contracts for that customer.

<img alt="Customer profile showing the Contracted Lanes and Fuel Surcharges tab with a list of active contracts." />

*Customer profile showing the Contracted Lanes and Fuel Surcharges tab with a list of active contracts.*

## Key Concepts

### Rate Types

Each contract uses one of the following rate types.

**Flat**: A fixed dollar amount per load, regardless of miles, weight, or volume.

**Per Mile**: A dollar rate multiplied by the total miles on the load.

**Per Weight**: A dollar rate multiplied by the weight of the shipment.

**Per Volume**: A dollar rate multiplied by the volume of the shipment.

<img alt="Create Contract dialog showing the Rate Type dropdown with Flat, Per Mile, Per Weight, and Per Volume options." />

*Create Contract dialog showing the Rate Type dropdown with Flat, Per Mile, Per Weight, and Per Volume options.*

### Minimum Rates

For Per Mile, Per Weight, and Per Volume contracts, you can set a minimum rate floor.

**Min Rate**: The minimum dollar amount that will be billed, regardless of the calculated rate. If the calculation produces a value lower than Min Rate, the Min Rate value is used instead.

**Min Quantity**: The minimum unit count (miles, pounds, or volume) used in the calculation, even if the actual load quantity is lower.

Minimum rate fields are not available on Flat rate contracts because a Flat rate is already a fixed amount.

### Equipment Type Matching

Each contract specifies the equipment type it applies to. When Alvys checks whether a load matches a contract, the load's equipment type must match the contract's equipment type. If the load uses a different equipment type, the contract is not applied.

### Contract Period

Each contract has a start date and end date. Alvys only applies a contract if the load's pickup date falls within the contract period. Contracts with an end date in the past are expired and are not applied to new loads.

<img alt="Create Contract dialog showing Contract Name, Subsidiary, Contract Period, Equipment Type, and lane" />

*Create Contract dialog showing Contract Name, Subsidiary, Contract Period, Equipment Type, and lane*

### Miles

Enter the lane mileage for the contract. This is used when calculating per-mile rates and can support mileage values up to 10,000 mi.

### Lane Type

Select the lane classification for the contract. The lane type is used for reporting. In the form shown, the lane type is set to **Primary**.

### Fuel Surcharge

Select an FSC contract if the lane should use a fuel surcharge. If no FSC contract applies, leave this field unselected.

### Accessorial Rate

Add any accessorial charges that should apply to the contract, such as special handling, equipment, detention, or other additional fees.

Enter the dollar amount for the selected accessorial. Each accessorial added to the contract must have its own rate.

### Driver pay plans

If driver pay should be tied to the contract, add a pay plan from this section. If no pay plan is associated, the contract will not have contract-specific driver pay configured.

<img alt="Create Contract dialog showing Miles, Lane Type, Rate Type, Fuel Surcharge, driver pay plans" />

*Create Contract dialog showing Miles, Lane Type, Rate Type, Fuel Surcharge, driver pay plans*

## How to Use It

### Creating a Contract

Required permission: **"Update/Create Contracted Lanes"**

1. Go to **Companies** and open the customer profile.
2. Select the **Contracted Lanes and Fuel Surcharges** tab.
3. Click **Create Contract**.
4. Enter the contract details: origin, destination, equipment type, rate type, rate amount, minimum rate (if applicable), and contract start and end dates.
5. Save the contract.

<img alt="Contracted Lanes list showing the newly created contract." />

*Contracted Lanes list showing the newly created contract.*

### Editing a Contract

Required permission: **"Update/Create Contracted Lanes"**

Click the edit icon next to any contract in the Contracted Lanes list to open the edit dialog. Update the desired fields and save.

### Removing a Contract

Required permission: **"Delete Contracted Lanes"**

Click the delete icon next to a contract to remove it. Loads that were created before deletion are not affected.

<Warning>
  Deleting a contract is permanent.
</Warning>

### Bulk Importing Contracts

Required permission: **"Update/Create Contracted Lanes"**

Use the **Import Contracts** button to upload multiple contracts at once from a CSV file.

1. Click **Import Contracts** on the Contracted Lanes and Fuel Surcharges tab.
2. Select the subsidiary the contracts belong to, then click **Next**.
3. Download the sample CSV template to see the required format.
4. Fill in the template with your contract data. If a lane has multiple location options (for example, multiple valid pickup ZIP codes), each must be a separate row. All non-location fields (rate type, rate amount, equipment type, contract dates, miles) must be identical across all rows for the same lane.
5. Upload the completed file.
6. Review the validation results. Any rows with errors are flagged.
7. Click **Import** to confirm and create all valid contracts.

<img alt="Import Contracts dialog showing the subsidiary selection step and the CSV template download link." />

*Import Contracts dialog showing the subsidiary selection step and the CSV template download link.*

### Applying a Contract to a New Load

Required permission: **"Apply Contracted Lanes On New Load"**

When creating a new load, Alvys checks whether the load matches any active contracted rate for the selected customer. A contract matches when all of the following are true:

* The load's pickup and delivery stops match the contract's origin and destination.
* The load's equipment type matches the contract's equipment class.
* The load's pickup date falls within the contract's start and end dates.

When a match is found, Alvys prompts you to apply the contracted rate. You can accept or skip the suggestion.

<img alt="New Load form showing the contracted rate match prompt." />

*New Load form showing the contracted rate match prompt.*

## Settings and Permissions

* **"View Contracted Lanes"**: Required to see contracted rates on a customer profile.
* **"Update/Create Contracted Lanes"**: Required to create or edit contracted rates.
* **"Delete Contracted Lanes"**: Required to delete a contracted rate.
* **"Apply Contracted Lanes On New Load"**: Required to apply a contracted rate when creating a new load.

<img alt="Permissions panel showing the four Contracted Rates permissions." />

*Permissions panel showing the four Contracted Rates permissions.*

## Limits and Behavior

* Contracted rates are tied to a specific customer profile. They do not apply across customers.
* A contract is only applied to a new load, not to loads that already exist when the contract is created.
* When multiple contracts match a load, Alvys presents all matches and lets the user select which to apply.
* Expired contracts (end date in the past) remain visible in the Contracted Lanes list for reference but are not applied to new loads.
* For bulk import, all non-location fields across rows representing the same lane must be identical. Rows with conflicting non-location field values will fail validation.

## FAQs

**Q: Why is the contracted rate not being applied when I create a load?**

**A:** The load must match the contract on all three conditions: stops (origin and destination), equipment class, and pickup date within the contract period. Check that the load's equipment class matches the contract, the pickup date falls within the start and end dates, and the stops map to the correct origin and destination. If none of these conditions explain the issue, contact Alvys support.

**Q: Can I apply a contracted rate to a load after it has already been created?**

**A:** Contracted rates are applied at the time a new load is created. They cannot be applied automatically to an existing load after creation. You can manually update the billing rate on an existing load to match a contracted value.

**Q: What happens if two contracts match the same load?**

**A:** Alvys presents all matching contracts and asks you to choose which one to apply.

**Q: Do minimum rate settings apply to Flat rate contracts?**

**A:** No. Min Rate and Min Quantity fields are not available for Flat rate contracts. A Flat rate is already a fixed amount and does not require a floor.

**Q: Can I import contracts for multiple subsidiaries in a single CSV upload?**

**A:** No. The Import Contracts process asks you to select a subsidiary before uploading. Each import applies to one subsidiary at a time.


# Dispatch Assist
Source: https://docs.alvys.com/en/help/loads-trips/dispatch-assist

Use Dispatch Assist to score every eligible driver and truck against each open trip, rank network-wide assignment options, and keep the final call with the dispatcher.

<Note>
  📋 **Applies to:** Admin, Partner Admin, Office Admin, Dispatcher, Operation Manager

  **Module:** Dispatch Planner

  Dispatch Assist is a paid add-on that evaluates your entire fleet against every open trip, surfaces optimal driver and asset pairings, and shows clear reasoning for each suggestion directly in the Dispatch Planner.
</Note>

## Overview

Dispatch Assist is an AI-powered planning tool that continuously evaluates every open trip against your entire fleet to surface the best driver and asset pairings. Each suggestion includes transparent reasoning so dispatchers can dispatch with confidence, learn from trade-off data, and manage more assets without adding headcount.

Dispatch Assist applies to carrier subsidiary loads only. Brokerage subsidiary loads are excluded from both Dispatch Planner and Dispatch Assist.

Dispatch Assist runs automatically in the background; no manual trigger is needed. It continuously evaluates open trips and available assets, refreshing suggestions approximately every 15 minutes.

## Where to Find It

Dispatch Assist surfaces inside the Dispatch Planner. Once enabled, a Suggestions column becomes available in the trips table column configuration menu. The number displayed in that column for each trip represents the count of AI-generated suggestions for that trip.

## Key Concepts

### Optimization Factors

Every Dispatch Assist suggestion is evaluated against six factors:

* **Deadhead miles:** minimizing empty miles between the driver's current position and the trip pickup
* **Hours of service (HOS):** ensuring the driver has enough legal drive time remaining to complete the trip
* **Equipment compatibility:** matching the trip's trailer requirements against the asset's configured capabilities
* **Revenue:** maximizing rate per trip and protecting margin across the network
* **Driver availability:** calculating when a driver will be free based on current trips, scheduled events, and configured dwell time
* **Dispatch preferences:** honoring the rules and constraints configured for each asset in Assignment Preferences

### Network-Wide Optimization

Dispatch Assist optimizes across your entire fleet, not just individual trips. A suggestion for one trip factors in the downstream impact on every other open trip. Alvys will work with your team to fine-tune the agent in line with your existing planning process and standard operating procedures.

### Dispatcher Control

Dispatch Assist does not auto-assign drivers. Every suggestion must be reviewed and either accepted or overridden by a dispatcher.

### Eligibility

Suggestions appear only for trips in **Open** or **Planned** status that are tendered to a carrier subsidiary and have at least one eligible, available asset with a configured Assignment Preference.

## How to Use It

### Setting Up Dispatch Assist

Before Dispatch Assist can generate suggestions, three setup tasks are required.

1. Enable Dispatch Assist. Dispatch Assist is a paid add-on. Contact your Alvys account representative to enable it for your company.
2. Configure Assignment Preferences. Dispatch Assist relies on Assignment Preferences to know which drivers and trucks are eligible for each trip.
   * Navigate to **Assets > Assignment Preferences**.
   * Click the blue **+ New Assignment** button for each driver and truck combination you want Dispatch Assist to consider.
   * Assets without a configured Assignment Preference will not be considered by Dispatch Assist. The more complete your preferences, the better the suggestions. For full details on creating and managing Assignment Preferences, see [Assignment Preferences](/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers).
3. Configure Availability Settings (recommended). These settings control how Dispatch Assist determines when a driver is free and whether they have enough time to take a new trip.
   * Navigate to **Settings > Planning configuration**.
   * Under Driver availability, configure the following fields:
   * **Average dwell time:** the average time a driver spends at a delivery location before becoming available again. Default: 2 hours.
   * **"Available for" minimum:** the minimum free time a driver must have to be considered available for a new trip. Default: 4 hours.
   * Click **Save**.

### Viewing Suggestions in Dispatch Planner

1. Open **Dispatch Planner**.
2. Click the column configuration menu in the trips table.
3. Select the **Suggestions** column to enable it.
4. The column displays the number of AI suggestions available for each eligible trip.

Only **Open** and **Planned** trips tendered to a carrier subsidiary, with at least one eligible available asset, show suggestions. Trips in **Covered**, **Dispatched**, or **In Transit** status do not show suggestions by default. Contact Alvys support if you would like to customize your agent to consider **Covered** trips.

<Note>
  <img alt="Screenshot of the Suggestions column in the Dispatch Planner trips table." />

  *Screenshot of the Suggestions column in the Dispatch Planner trips table.*
</Note>

### Understanding a Suggestion

Each suggestion represents the AI's recommended driver and asset assignment for a specific trip. Clicking a suggestion opens a details panel that shows the reasoning behind the recommendation, including trade-offs across deadhead miles, HOS remaining, equipment match, and revenue impact.

The reasoning panel helps dispatchers dispatch with confidence, learn from the data, and scale operations: one dispatcher can manage more assets because the AI handles the analytical work.

<Note>
  <img alt="Screenshot of the Dispatch Assist reasoning panel showing suggestion details and KPIs." />

  *Screenshot of the Dispatch Assist reasoning panel showing suggestion details and KPIs.*
</Note>

Each suggestion displays four key metrics:

* **per total mile:** rate per total mile
* **Deadhead:** empty miles as a percentage of total miles
* **per total hour:** rate per total hour
* **Downtime**

### Accepting a Suggestion

1. Locate the trip in the Suggestions column of the trips table.
2. Click on the suggestion to open the recommended driver and asset pairing.
3. Choose your action:
   * **Assign:** assigns the driver and asset without dispatching the trip
   * **Assign and dispatch:** assigns the driver and asset and dispatches the trip in one step

You are never required to accept a suggestion. You can always manually assign a different driver using the standard assignment workflow in Dispatch Planner.

### Overriding a Suggestion

1. Select a trip from the trips table.
2. Choose a different driver from the assets table.
3. Complete the assignment as usual.

The next time Dispatch Assist runs, it will factor in the updated state of your fleet and generate new suggestions based on the current assignments.

## How Dispatch Assist Works

Dispatch Assist runs through a continuous three-step cycle:

1. **Data aggregation:** gathers open trips, available drivers, asset constraints, Assignment Preferences, hours-of-service data, and revenue information across your entire fleet.
2. **Optimization:** the AI model evaluates all possible assignments simultaneously, minimizing deadhead, respecting hours of service, maximizing revenue, and honoring dispatch preferences across the network.
3. **Suggestions delivered:** optimal assignments appear in the Suggestions column with clear reasoning for each recommendation.

Because Dispatch Assist optimizes across your entire network rather than trip by trip, a suggestion for one trip considers the downstream impact on all other open trips.

## Settings & Permissions

Access to Dispatch Assist requires the following:

* A role with planner access: Admin, Partner Admin, Office Admin, Dispatcher, or Operation Manager
* Dispatch Assist enabled at the company level (paid add-on; contact your Alvys account representative)
* At least one carrier subsidiary configured on the load
* Assignment Preferences configured for the assets you want included

Availability settings are configured at **Settings > Planning configuration**, under the Driver availability section. Fleet-level overrides can be set on individual fleet pages and take priority over company-wide defaults.

## Limits & Behavior

* Dispatch Assist applies to carrier subsidiary loads only. Brokerage subsidiary loads are excluded.
* Suggestions refresh approximately every 15 minutes.
* Dispatch Assist does not auto-assign; every suggestion requires dispatcher review and action.
* Trips in **Covered**, **Dispatched**, or **In Transit** status do not show suggestions by default.
* Assets without a configured Assignment Preference are not evaluated and will not appear in suggestions.
* Dispatch Assist has to be turned on for your company and needs an active integration; a standard Alvys subscription alone does not activate it. Contact your account team to have it enabled.

## FAQs

**Q: How often does Dispatch Assist update its suggestions?**

**A:** Dispatch Assist refreshes suggestions approximately every 15 minutes.

**Q: Why don't I see suggestions for some trips?**

**A:** Suggestions appear only for trips in **Open** or **Planned** status, tendered to a carrier subsidiary, with at least one eligible available asset that has a configured Assignment Preference.

**Q: Will Dispatch Assist auto-assign drivers for me?**

**A:** No. Every suggestion must be reviewed and accepted or overridden by a dispatcher.

**Q: Do I need to set up anything special for my drivers to appear in suggestions?**

**A:** Yes. Each driver and asset must have an Assignment Preference configured under **Assets > Assignment Preferences**.

**Q: What if Dispatch Assist suggests a driver who appears unavailable?**

**A:** Check your Average dwell time and "Available for" minimum settings under **Settings > Planning configuration**. Adjusting these values affects which drivers are considered available when Dispatch Assist evaluates the fleet.

**Q: Does Dispatch Assist work with brokered loads?**

**A:** No. Dispatch Assist works only with loads tendered to a carrier subsidiary. Brokerage subsidiary trips are excluded from both Dispatch Planner and Dispatch Assist.

## Go Deeper

* [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
* [Dispatching a Load](/en/help/loads-trips/how-to-dispatch-a-load)
* [Assignment Preferences](/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers)


# Dispatch Planner
Source: https://docs.alvys.com/en/help/loads-trips/dispatch-planner

Use Dispatch Planner v2 to match unassigned trips with available drivers and assets in one live workspace, with inline edits, chat, and DAT posting.

## Dispatch Planner

<Note>
  Dispatch Planner v2 is a real-time planning workspace that shows unassigned trips alongside available drivers and assets, so dispatchers can match and assign loads without switching between screens.
</Note>

### Overview

Dispatch Planner v2 gives your team a live, side-by-side view of trips waiting for assignment and the drivers and assets available to cover them. The planner surfaces availability windows, priority tinting, and smart assignment suggestions so you can dispatch faster and with more confidence.

The workspace has two main tables: a Trips table on the left showing **Open** and **Planned** loads, and a Drivers/Assets table on the right showing available assets. Selecting a trip or a driver filters the opposite table to show only compatible matches, turning a multi-step dispatch into a single workflow.

The planner also supports inline editing of key fields, driver notes, driver events, bulk actions, and in-app driver chat: all without leaving the planning screen.

### Where to Find It

Navigate to **Loads and Trips > Dispatch Planner v2** in the main navigation menu.

All authenticated users can access Dispatch Planner v2. Certain configuration options within the planner are restricted to specific roles; those restrictions are described in Settings & Permissions below.

### Key Concepts

#### Trip Eligibility

Only trips that meet both of the following conditions appear in the Trips table:

* The trip's load must be tendered as a carrier subsidiary. Loads tendered as a brokerage subsidiary are excluded from Dispatch Planner v2.
* The trip must be in **Open** status.

Trips in **Covered**, **Dispatched**, **In Transit**, or a completed status are visible in the sidebar but do not appear as assignable rows in the planning table.

#### Asset Eligibility

An asset (driver or truck) appears in the Drivers/Assets table only when it has an assignment preference configured. Assets without an assignment preference are not shown in the planner, regardless of their active status or availability. The more complete the configured preferences, the more accurate the dispatch suggestions the planner can surface.

Assignment preferences are set up in **Assets > Assignment Preferences**. See Settings & Permissions below for the setup steps.

#### Availability Calculation

The planner calculates driver availability using the following logic:

* Available at: the exact date and time the driver becomes available, calculated as last trip delivery time plus average dwell time
* Available for: the duration the driver will be free before their next planned trip
* Next planned at: the start time of the driver's next scheduled trip
* Available in: the location where the driver becomes available, which is where their current trip delivers

Availability is most accurate when driver events are kept up to date in the assets table.

#### Priority and Row Tinting

Each trip can be assigned one of four priority levels: None, Low, Medium, or High. The Trips table uses row tinting to reflect priority: no color for None, a light tint for Low, a medium tint for Medium, and a dark tint for High. Priority can be set inline directly from the grid.

Priority is a load-level value. Setting it from one trip applies it to every trip on that load, and the grid repaints those rows together.

#### Assignment Actions

Two assignment actions are available when pairing a trip with a driver:

* **Assign**: assigns the selected assets to the trip without dispatching. The trip moves to **Covered** status. Use this when you want to lock in assets but are not yet ready to dispatch.
* **Assign and dispatch**: assigns the selected assets and dispatches the trip in one step. The trip moves to **Dispatched** status. Use this to complete the dispatch in a single action.

<Note>
  **Covered** means assets are assigned but the trip has not been dispatched. **Dispatched** means the trip has been released to the driver and is ready to move.
</Note>

#### Bulk Actions

Bulk Actions lets planners select multiple trips in the Trips table and apply an operation to all of them at once, turning an hours-long one-by-one workflow into a two-click operation. Six operations are available:

* **Bulk Assign** — moves selected trips from Open to Covered.
* **Bulk Dispatch** — moves selected trips from Covered to Dispatched.
* **Bulk Assign & Dispatch** — moves selected trips from Open to Dispatched in a single step.
* **Bulk Unassign** — returns selected Covered or Dispatched trips to Open.
* **Bulk Change Dispatcher** — reassigns the dispatcher on selected trips without changing their status.
* **Bulk Set Priority** — sets the priority level on selected trips without changing their status.

See [How to Use Bulk Actions in Dispatch Planner](/en/help/loads-trips/how-to-use-bulk-actions-in-dispatch-planner) for full step-by-step instructions.

#### Three-Level Availability Settings Hierarchy

Availability settings follow a three-level hierarchy: Alvys platform defaults apply first, company-level settings override those defaults, and fleet-level settings override the company setting for individual fleets. This means a fleet can be configured differently from the rest of the company.

### How to Use It

Dispatch Planner v2 supports several interconnected workflows. Refer to the dedicated how-to articles for step-by-step instructions:

* Assigning and dispatching a trip (trip-first and driver-first flows)
* Configuring trip columns, sorts, and filters
* Configuring asset columns, sorts, and filters
* Adding and editing driver notes
* Adding and editing driver events
* Sending a driver chat message from the planner
* Using Bulk Actions (bulk assign, dispatch, unassign, change dispatcher, and set priority)

### Settings & Permissions

#### Set Tender As and Carrier on Trips

Before a trip appears in Dispatch Planner v2, its load must be tendered as a carrier subsidiary. To set this:

1. Open the load details page for the load you want to appear in the planner.
2. Locate the Carrier Details section in the top-right panel of the load details page.
3. Click the **Change Tender** button.
4. Set the **Tender As** field to the carrier subsidiary (not a brokerage subsidiary).
   <img alt="Screenshot showing the Carrier Details section on the load details page with the Change Tender button and Tender As field visible" />
   *Screenshot showing the Carrier Details section on the load details page with the Change Tender button and Tender As field visible*

Loads tendered as a brokerage subsidiary will not appear in Dispatch Planner v2, even if all other conditions are met.

#### Configure Availability Settings (Optional)

Availability settings control the thresholds the planner uses to calculate when a driver is eligible for a new trip. This is optional; the planner uses Alvys platform defaults if no company or fleet overrides are set.

Availability settings are reached at **Settings > Planning configuration**. Any authenticated user with access to the Settings area can view and edit them; no dedicated permission gates these fields.

1. Navigate to **Settings > Planning configuration**.
2. Locate the Driver Availability section on the page.
3. Set the **"Available for" minimum** field. This is the minimum free time a driver must have to be considered available. The Alvys default is 4 hours.
4. Set the **Average dwell time** field. This is the estimated time a driver spends at a delivery location before becoming available again. The Alvys default is 2 hours.
5. Click **Save**.

Fleet-level overrides: To set different thresholds for a specific fleet, navigate to that fleet's settings and apply the override there. The three-level hierarchy described in Key Concepts above determines which value takes effect for any given driver.

#### Set Up Assignment Preferences

Assets must have an assignment preference configured before they appear in Dispatch Planner v2. This is required for every driver and truck you want the planner to surface.

Viewing and managing assignment preferences requires the **"ViewDrivers"** and **"ViewTrucks"** permissions.

1. Navigate to **Assets > Assignment Preferences**.
2. Click the blue **+ New Assignment** button for the asset you want to configure.
3. Complete the preference fields for that asset and save.
   <img alt="GIF showing the Assignment Preferences setup flow: navigating to Assets > Assignment Preferences, clicking + New Assignment, and completing the preference fields." />
   *GIF showing the Assignment Preferences setup flow: navigating to Assets > Assignment Preferences, clicking + New Assignment, and completing the preference fields.*

Assets without a configured assignment preference will not appear in Dispatch Planner v2. The more complete the preferences, the better the dispatch suggestions the planner surfaces.

### Limits & Behavior

#### Trips Table

The Trips table supports configurable columns, sorts, and filters. Use the column configuration menu to show, hide, or reorder columns.

Three fleet columns are available in the column picker. None is shown by default, so add them from the column configuration menu when you want them:

* **Driver Fleet**: the fleet of the driver assigned to the trip. When two drivers are assigned as a team, the column shows Driver 1's fleet, matching how the Drivers table behaves. When no driver is assigned, the column shows a dash.
* **Truck Fleet**: the fleet of the truck assigned to the trip. When no truck is assigned, the column shows a dash.
* **Trailer Fleet**: the fleet of the trailer assigned to the trip. When no truck is assigned, the column shows a dash.

All three columns can be sorted, and all three can be filtered by selecting one or more fleets. They are separate from the existing **Fleet** column, which shows the load's own fleet rather than the fleet of the assigned driver, truck, or trailer. Like every other column, your show, hide, and reorder choices are remembered the next time you open the planner.

<img alt="GIF showing the Trips table column configuration: opening the column menu, toggling columns on and off, and reordering them" />

*GIF showing the Trips table column configuration: opening the column menu, toggling columns on and off, and reordering them*

#### Created Column

The **Created** column shows when each trip was created, so you can tell at a glance how long a trip has been sitting unassigned. The time is shown in your own local time zone, for example 08/25/2026 @ 09:22 CDT.

The column is hidden by default. Add it from the Trips table column configuration menu, the same way you add the fleet columns. Once it is showing, you can sort by it and filter it by date.

#### Appointments Column

The **Appointments** column shows how many of a trip's stops have a confirmed appointment, so you can tell which trips still need calls without opening each one.

The column reads as a count of confirmed stops against the total, with a colored dot:

* A green dot and **3/3 Confirmed** when every stop is confirmed.
* A yellow dot and **1/3 Confirmed** when some stops are confirmed.
* A gray dot and **0/3 Confirmed** when none are.

The column is hidden by default. Add it from the Trips grid column picker. Once it is showing, you can sort by it to bring the trips still needing calls to the top, or filter to Partial and Unconfirmed only.

Appointments are still confirmed on the load's details page. This column tells you where to go rather than replacing that step.

#### Carrier Sales Agent Column

The **Carrier Sales Agent** column shows the carrier sales agent on each trip, so you can see who owns the carrier relationship without opening the trip.

The column is hidden by default. Add it from the Trips table column configuration menu, the same way you add the fleet columns. Once it is showing, you can sort by it and filter it.

#### Load Planner Column

The Trips table has a column showing the load planner assigned to each trip, so you can see who planned a load without opening it.

The column is hidden by default. Add it from the Trips table column configuration menu, the same way you add the fleet columns. Once it is showing, you can sort by it and filter it, and the filter includes an option for trips with no load planner assigned, so you can bring unplanned work to the top of the grid.

Trips with no load planner assigned show a placeholder rather than an empty cell.

#### Carrier Rate Column

The Trips table also has a column showing the carrier rate on each trip, so you can compare rates across open trips without opening each load.

The column is hidden by default. Add it from the Trips table column configuration menu. Once it is showing, you can sort by it and filter it.

This column is permission-gated. Where your account does not allow you to see carrier rates, the column does not appear in the grid and is not offered in the column picker, so it cannot be sorted or filtered either. It is a visibility column only: adding it does not change who may edit a rate, and it does not restrict anything that was previously allowed.

#### Right-Click Menu on a Trip

Right-clicking a trip opens the Alvys menu. It is available on the main Trips grid and in the details view, including the Dispatch Assist suggestion rows pinned at the top.

The menu offers:

* **Open In New Tab** and **Open In New Window** — the load's details page.
* **Lane Report** — opens the lane in the lanes page.
* **Dispatch** — opens the dispatch dialog. It appears only on a trip that can be dispatched, meaning a Covered trip with a driver assigned.
* **Priority** — set Critical, Important, or Caution, or remove the priority. This asks you to confirm first, unlike the inline Priority cell, which applies the change straight away.
* **View Notes** — opens the trip sidebar on the Notes tab.
* **View Logs** — opens the load's history in a dialog over the grid.
* **Copy** and **Export**.

<Note>
  Priority set from the right-click menu is a load-level value, the same as the inline Priority cell. Setting it on one trip applies it to every trip on that load.
</Note>

#### View Logs

**View Logs** sits directly under **View Notes** on the trip right-click menu. It opens the load's history in a dialog over the grid, so you can see who changed what and when without leaving the planner or opening the load.

The dialog shows every log entry for the load and its customer, newest first. Where an entry names a document, the document name is a link: click it to open that document, such as the rate confirmation.

**View Logs** is available from Dispatch Planner v2. Open the load itself to review its history from anywhere else.

#### Inline Editing

Certain columns in the Trips table support inline editing. An editable cell displays a visual indicator when you hover over it. To edit inline:

1. Click the editable cell.
2. Make the change.
3. Press Enter or click away to save.
4. The change is reflected in the table immediately.

The following fields support inline editing from the Trips table:

* Dispatcher
* Priority (options: None, Low, Medium, High)
* Trip-Level Custom References (four reference types)

Note on the Dispatcher field: the Dispatcher field requires a value once it has been set. To clear a dispatcher back to empty, use the full trip edit screen rather than the inline grid.

The inline Dispatcher dropdown shows only active users who have dispatcher access. If the user you are looking for does not appear, confirm they have the correct role assigned in your account.

#### Trip Sidebar

Clicking any row in the Trips table opens the Trip Sidebar on the right side of the screen. The sidebar displays:

* Fixed Header: trip ID, status, and key metadata
* Static Map: origin and destination
* Stops Timeline
* Scorecard: rate metrics for the trip
* Details Section
* Customer and Carrier Sections
* Smart Footer: status-aware action buttons

The Smart Footer buttons change depending on the trip's current status:

* **Open** trips: a **Show Drivers** button and a **Dispatch** button are shown.
* **Covered** or **Dispatched** trips: an **Un-assign** button is shown.
* **In Transit** or completed trips: no action buttons are shown.

#### Assets Table

The Drivers/Assets table supports configurable columns, sorts, and filters. Use the column configuration menu to show, hide, or reorder columns.

<img alt="GIF showing the Assets table column configuration: opening the column menu, toggling columns on and off, and reordering them" />

*GIF showing the Assets table column configuration: opening the column menu, toggling columns on and off, and reordering them*

#### Contractor Type Column

The **Contractor Type** column on the Drivers/Assets table shows how each driver is engaged, so you can plan around company drivers and contracted drivers separately without opening each driver record.

The column is hidden by default. Add it from the Assets table column configuration menu. Once it is showing, you can sort by it and filter it.

#### Driver Notes

Driver notes are visible to dispatchers and are stored on the driver record. The planner shows the 10 most recent notes for each driver.

<img alt="GIF showing the Driver Notes modal: selecting a driver, opening the notes section, adding a note, and saving" />

*GIF showing the Driver Notes modal: selecting a driver, opening the notes section, adding a note, and saving*

#### Driver Events

Driver events record activity that affects a driver's availability and appear in the driver's activity timeline in chronological order.

To add a driver event:

1. Open the Driver Activity sidebar for the driver.
2. Click **Add Event**.
3. Enter the event details: type, date and time, and any notes.
4. Save. The event appears in the driver's chronological activity timeline.
   <img alt="GIF showing the Add Driver Event flow: opening the Driver Activity sidebar, clicking Add Event, completing the event details, and saving." />
   *GIF showing the Add Driver Event flow: opening the Driver Activity sidebar, clicking Add Event, completing the event details, and saving.*

#### Driver Chat

You can send a message to a driver directly from Dispatch Planner v2 without leaving the screen.

<img alt="GIF showing the Driver Chat flow: selecting a driver in the assets table, clicking the Chat button in the asset sidebar, typing a message, and sending" />

*GIF showing the Driver Chat flow: selecting a driver in the assets table, clicking the Chat button in the asset sidebar, typing a message, and sending*

#### Trip Assignment

Trip assignment can be initiated from either the trip side (trip-first) or the driver side (driver-first).

Trip-first: Select a trip row in the Trips table. The Assets table displays a pinned suggestion row at the top showing the recommended asset match. Click **Assign** or **Assign and dispatch** to complete the assignment.

Driver-first: Select a driver row in the Assets table. The Trips table updates to show only compatible **Open** trips for that driver. Select the trip you want to assign, then click **Assign** or **Assign and dispatch**.

<img alt="GIF showing the Trip Assignment flow: selecting a trip, reviewing the pinned suggestion in the assets table, and clicking Assign and dispatch" />

*GIF showing the Trip Assignment flow: selecting a trip, reviewing the pinned suggestion in the assets table, and clicking Assign and dispatch*

#### Availability Columns

The Assets table includes five availability columns that show at a glance when each driver is free:

* Available at: the exact date and time the driver becomes available
* Available for: how long the driver will be free before their next planned trip
* Next planned at: the start time of the driver's next scheduled trip
* Available in: the location where the driver becomes available, which is where their current trip delivers
* Next planned event: what the driver's next commitment actually is

**Next planned event** tells you whether the driver's next commitment is another trip or time away from the road, without opening the sidebar. The possible values are Trip, Hometime, Vacation, Restart, Sick or Emergency, Work order, Repair, and Other. A dash means the driver has no next commitment recorded. The column can be sorted and filtered.

This column reads from the same availability window as Next planned at and Available in, so all three always describe the same event. That makes it useful for planning around time off: a driver whose next planned event is Hometime can be loaded on a trip heading toward home rather than away from it.

Availability accuracy depends on driver events being kept current. Update driver events whenever a driver's schedule changes. A driver whose availability has not been recomputed since this column was added shows a dash until their next assignment or driver event is created or changed.

#### Where a Driver's Last Reported Position Comes From

A driver's last reported position comes from the truck the driver is currently assigned to. If that truck has not reported a position, the driver has no last reported position and the value is blank.

A blank value is normal and does not mean tracking is broken. The usual reasons are:

* The driver is not currently assigned to a truck.
* The truck the driver is assigned to has not reported a position yet.
* The truck is not set up to report positions at all.

To get a position for a driver showing a blank value, confirm the driver is assigned to the right truck, then confirm that truck reports positions.

The same position is used wherever the planner works from a driver's location, including filtering drivers by distance from a point and sorting drivers by how far they are from their last known location. A driver with no reported position does not match a distance filter.

#### Asset Sidebar

Clicking any row in the Assets table opens the Asset Sidebar. The sidebar includes two tabs:

* Overview Tab: driver and asset details, notes, and availability summary
* Activity Tab: chronological timeline of driver events

### FAQs

**Q: Why don't I see my trips in Dispatch Planner v2?**

**A:** Trips must be tendered as a carrier subsidiary to appear in the planner. Loads tendered as a brokerage subsidiary are excluded. The trip must also be in **Open** status. If the tender and status are correct, check whether any active column filters are hiding the rows.

**Q: My assets aren't showing in the planner. What should I check?**

**A:** Confirm that an assignment preference has been configured for the asset in Assets > Assignment Preferences. Assets without a configured preference are not shown in Dispatch Planner v2. Also check whether any active column filters are hiding the rows, and confirm the driver is active in your account.

**Q: Can I customize which columns appear in the tables?**

**A:** Yes. Use the column configuration menu in either the Trips table or the Assets table to show, hide, and reorder columns.

**Q: How do I see how many stops on a trip have a confirmed appointment?**

**A:** Add the **Appointments** column from the Trips grid column picker. It is hidden by default. The column shows a count such as 3/3 Confirmed with a colored dot, and it can be sorted and filtered so you can bring Partial and Unconfirmed trips to the top.

**Q: How do I see who changed a load, and when?**

**A:** Right-click the trip and choose **View Logs**. The dialog opens over the grid and lists every log entry for the load and its customer, newest first. Document names inside an entry are links, so you can open a document such as the rate confirmation without leaving the planner.

**Q: How do I see when a trip was created?**

**A:** Add the **Created** column from the Trips table column configuration menu. It is hidden by default. The date and time are shown in your own local time zone, and the column can be sorted and filtered by date.

**Q: How do I see which fleet a trip's trailer belongs to?**

**A:** Add the **Trailer Fleet** column from the Trips table column configuration menu. It is hidden by default. The column shows a dash when no truck is assigned to the trip.

**Q: How do I see who the carrier sales agent is on a trip?**

**A:** Add the **Carrier Sales Agent** column from the Trips table column configuration menu. It is hidden by default, and once it is showing you can sort and filter by it.

**Q: How do I see which load planner is on a trip?**

**A:** Add the load planner column from the Trips table column configuration menu. It is hidden by default. Once it is showing you can sort and filter by it, and the filter includes an option for trips with no load planner assigned.

**Q: How do I see the carrier rate on a trip from the grid?**

**A:** Add the carrier rate column from the Trips table column configuration menu. It is hidden by default. If your account does not allow you to see carrier rates, the column is not offered in the column picker and does not appear in the grid.

**Q: How do I see whether a driver is a company driver or a contractor?**

**A:** Add the **Contractor Type** column from the Assets table column configuration menu. It is hidden by default, and once it is showing you can sort and filter by it.

**Q: A driver has no last reported position. Why?**

**A:** A driver's last reported position comes from the truck they are currently assigned to. The value is blank when the driver is not assigned to a truck, when the assigned truck has not reported a position, or when that truck does not report positions at all. Confirm the driver is assigned to the right truck, then confirm that truck reports positions.

**Q: How do I save changes to driver notes?**

**A:** Notes save automatically when you click away or press Enter after editing.

**Q: Which fields can I edit directly from the grid?**

**A:** You can edit the Dispatcher, Priority, and Trip-Level Custom References fields inline from the Trips table.

**Q: Why can't I clear a dispatcher back to empty from the grid?**

**A:** The Dispatcher field requires a value once it has been set. To clear the dispatcher, open the full trip edit screen and remove the value there.

**Q: I can't find the dispatcher I want in the inline dropdown.**

**A:** The dropdown shows only active users who have dispatcher access. Confirm that the user has the correct role assigned in your account.

**Q: What do the colored rows in the Trips table mean?**

**A:** Row color indicates the trip's priority level: no color means None, a light tint means Low, a medium tint means Medium, and a dark tint means High.

**Q: I set priority on one trip and it changed on others. Why?**

**A:** Priority is a load-level value. Setting it on one trip applies it to every trip on that load, whether you set it from the inline cell or from the right-click menu.

**Q: Can I apply an action to multiple trips at once?**

**A:** Yes. Use Bulk Actions to select multiple trips via the checkbox column and apply an operation to all of them at once. Available operations include Bulk Assign, Bulk Dispatch, Bulk Assign & Dispatch, Bulk Unassign, Bulk Change Dispatcher, and Bulk Set Priority. See [How to Use Bulk Actions in Dispatch Planner](/en/help/loads-trips/how-to-use-bulk-actions-in-dispatch-planner) for full step-by-step instructions.

### Go Deeper

* [Assignment Preferences](/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers)
* [How to Use Bulk Actions in Dispatch Planner](/en/help/loads-trips/how-to-use-bulk-actions-in-dispatch-planner)


# Dispatch as a broker
Source: https://docs.alvys.com/en/help/loads-trips/dispatching-as-a-broker

Cover a load with an outside carrier, send the rate confirmation, and track the move.

When you broker a load, dispatching means assigning a carrier (not your own driver and truck), sending the rate confirmation, and tracking the move. Watch the walkthrough, then use the written how-tos for each step.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="How to complete dispatching as a Broker" />

[Open the recording](https://drive.google.com/file/d/1HbPLRUMLYG2o4xIK3q-6xJe6M1EiYBvu/view)

## Written steps

<CardGroup>
  <Card title="How to dispatch a load" icon="truck-fast" href="/en/help/loads-trips/how-to-dispatch-a-load">
    Cover the trip. On a brokered load you assign a carrier instead of a company driver.
  </Card>

  <Card title="Send the rate confirmation" icon="envelope" href="/en/help/loads-trips/how-to-send-the-rate-confirmation-to-a-carrier">
    Send the carrier their rate confirmation after you cover the load.
  </Card>

  <Card title="Verify a motor carrier" icon="shield-check" href="/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys">
    Confirm the person representing the carrier is authorized by the FMCSA owner.
  </Card>

  <Card title="Tenders" icon="file-contract" href="/en/help/loads-trips/tenders">
    Receive and work a customer tender when the load comes in over EDI.
  </Card>

  <Card title="Load statuses" icon="signal" href="/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them">
    What Covered, In Transit, and Delivered mean on a brokered load.
  </Card>
</CardGroup>

If you cover loads with your own drivers and trucks, use [Dispatch as a carrier](/en/help/loads-trips/dispatching-as-a-carrier).


# Dispatch as a carrier
Source: https://docs.alvys.com/en/help/loads-trips/dispatching-as-a-carrier

Cover a load with your own driver, truck, and trailer.

When you run your own trucks, dispatching means assigning a driver, truck, and trailer to a trip and moving it to **Covered**. Watch the walkthrough, then use the written how-tos for the screens in Dispatch Planner.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="How to complete dispatching as a Carrier" />

[Open the recording](https://drive.google.com/file/d/1CxuCti3wZ7TRomr4ylz4BDE4iyx4Zo3g/view)

## Written steps

<CardGroup>
  <Card title="How to dispatch a load" icon="truck-fast" href="/en/help/loads-trips/how-to-dispatch-a-load">
    Assign a driver, truck, and trailer and advance the trip to Covered.
  </Card>

  <Card title="Dispatch Planner" icon="map" href="/en/help/loads-trips/dispatch-planner">
    Plan the day's assignments across drivers and trucks.
  </Card>

  <Card title="Assignment preferences" icon="sliders" href="/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers">
    Suggest the usual driver, truck, or trailer when you open a trip.
  </Card>

  <Card title="Load statuses" icon="signal" href="/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them">
    What Covered, In Transit, and Delivered mean, and how to move a load back.
  </Card>
</CardGroup>

If you cover loads with an outside carrier instead of your own assets, use [Dispatch as a broker](/en/help/loads-trips/dispatching-as-a-broker).


# Error when recording arrival or departure time on a stop
Source: https://docs.alvys.com/en/help/loads-trips/error-when-recording-arrival-or-departure-time-on-a-stop

Resolve stop time validation errors when arrival or departure won't save, including "arrival must be before departure" and future-time blocks.

<Note>
  When you try to save an arrival or departure time on a stop and see an error, Alvys is enforcing one of two rules: the arrival time must not be later than the departure time, and neither time can be set in the future. Also known as: stop time error, arrival time won't save, departure time won't save, stop time validation.
</Note>

## Symptom

When saving arrived or departed times on a stop, one or more of the following error messages appears and the save is blocked:

* "Arrival/Departure: Arrival must be before departure."
* "Arrival should not be in future."
* "Departure should not be in future."

<Note>
  🖼️ Set Arrival/Departure Times modal showing the departure-before-arrival validation error.

  <img alt="Notion Image" />
</Note>

<Note>
  🖼️ Set Arrival/Departure Times modal showing the arrival-in-future validation error.

  <img alt="Notion Image" />
</Note>

## Cause

These errors occur because the system enforces two rules when recording actual arrived and departed times:

**Rule 1: Arrival must be before or equal to departure.**

A stop cannot show a departed time that is earlier than the arrived time. This prevents data entry errors where a driver appears to have left before arriving.

**Rule 2: Neither arrived nor departed time can be in the future.**

The system checks the entered time against the current real-world time in the stop's time zone. Times that have not yet occurred cannot be recorded as actual arrived or departed times.

These validations protect data accuracy and prevent errors in connected integrations such as EDI and visibility platforms.

## Resolution

### Error: "Arrival/Departure: Arrival must be before departure."

1. Review the Arrived time and the Departed time currently entered on the stop.
2. Confirm which value is incorrect. The arrival time must be earlier than or equal to the departure time.
3. Correct the Arrived time, the Departed time, or both so that arrival comes before departure.
4. Save the stop. The error will clear when the values are in the correct sequence.

### Error: "Arrival should not be in future."

1. Check the Arrived time you entered and compare it to the current date and time in the stop's time zone.
2. The entered time is later than the current moment. Enter a time that has already occurred.
3. Save the stop.

### Error: "Departure should not be in future."

1. Check the Departed time you entered and compare it to the current date and time in the stop's time zone.
2. The entered time is later than the current moment. Enter a time that has already occurred.
3. Save the stop.

## If That Didn't Work

If the error persists after correcting the times, check the following:

* Confirm the stop's time zone is set correctly. The system evaluates future-time violations based on the stop's assigned time zone. If the time zone is wrong, a valid time may still appear as a future time.
* Confirm you are not mixing 12-hour and 24-hour formats. An AM/PM entry error can cause the arrival to appear later than intended.

If the error still appears after verifying both of the above, contact Alvys support. Provide the load number, the stop in question, and the times you attempted to enter.

## FAQs

**Q: Can I record a departure time without first recording an arrival?**

**A:** No. A departure time requires an arrival time to be on record for the same stop. Enter the arrival time first, then record the departure.

**Q: Why does Alvys validate against the stop's time zone instead of my device's time?**

**A:** Stop times reflect when an event occurred at the stop location. Using the stop's time zone ensures accurate records and correct data for integrations such as EDI.

**Q: Who can record arrival and departure times on a stop?**

**A:** Users with the **"Dispatch"** permission can record arrival and departure times. If you do not see these fields on a stop, contact your account administrator to confirm your permissions.

## Related

* [Stop Dates and Times](/en/help/loads-trips/stop-dates-and-times): Learn how arrived and departed fields are shown based on stop status, and how schedule types (FCFS and APPT) work.


# How time zone standardization works in Alvys
Source: https://docs.alvys.com/en/help/loads-trips/how-time-zone-standardization-works-in-alvys

Alvys standardizes time zones for consistent transaction handling and display, converting UTC data to users' local time zones for clarity

<img alt="Notion Image" />

<Note>
  Alvys stores all fuel and toll transaction times in UTC and converts them to your local time zone for display; a transaction date in Alvys may differ by one day from the same transaction in your provider's portal.
</Note>

## Overview

Alvys stores all fuel and toll transaction timestamps in Coordinated Universal Time (UTC) and converts them to each user's local time zone at the point of display. This approach ensures that transaction data synced from multiple providers such as EFS, Comdata, Relay, and Loves is stored on a single consistent standard, regardless of the time zone each provider uses internally.

The result is that the time shown in Alvys for any given transaction reflects your local time, while the same transaction in your provider's portal may show a different time. In some cases, the UTC conversion can shift a transaction into a different calendar day, which matters when you are filtering by date.

**Synonyms:** UTC time, time zone conversion, transaction time discrepancy, date filter, time zone offset, fuel transaction date, toll transaction date.

## Where to Find It

Fuel and toll transactions are visible in Driver Settlements. Open the Driver Settlements module, locate the relevant driver or truck record, and navigate to the Fuel or Tolls tab to see transactions with their converted timestamps.

## Key Concepts

**UTC storage**

All transaction timestamps are stored in UTC when they arrive in Alvys, regardless of the time zone used by the originating provider.

**Local time display**

When you view a transaction, Alvys converts the stored UTC timestamp to your local time zone based on your browser or device settings. Two users in different time zones viewing the same transaction will each see a different local time.

**The one-day shift**

Because a UTC timestamp is always ahead of US time zones, a transaction that occurred late in the evening local time may be stored in Alvys with a UTC date that falls on the following calendar day. Conversely, a transaction stored at midnight UTC may display as the previous evening in your local time zone. This is expected behavior and is not a data error.

Example: a transaction timestamped 2024-12-10 at 02:14 UTC will display as:

* 2024-12-09 at 20:14 in Central Time (UTC-6)
* 2024-12-09 at 19:14 in Mountain Time (UTC-7)

**Provider time zone differences**

Different fuel and toll providers handle time data differently. EFS, for example, processes transactions in Mountain Time before sending them to Alvys. The timestamp in your EFS portal reflects EFS's local time; Alvys shows the time converted to your local time zone from UTC. This means the time displayed in Alvys and the time in your EFS portal will typically differ.

## How to Use It

For guidance on filtering fuel or toll transactions by date, see the fuel and toll articles in the Driver Settlements section of the help center.

## Limits and Behavior

When filtering fuel or toll transactions by date, the UTC conversion can cause transactions to fall outside a date filter by up to one day. If you expect to see a transaction on a given date but it does not appear, expand your date filter by one day in either direction to account for this offset.

This behavior applies to all fuel and toll providers integrated with Alvys, including EFS, Comdata, Relay, Loves, BestPass, IPass, and PrePass.

## FAQs

**Q: Why does a transaction in Alvys show a different date than the same transaction in my EFS portal?**

**A:** EFS displays transaction times in its own local time zone (Mountain Time). Alvys stores all transactions in UTC and converts them to your local time zone for display. Because these are different reference points, the displayed date and time will differ between the two systems. This is expected and does not indicate a data mismatch.

**Q: Why is a transaction not appearing when I filter by a specific date?**

**A:** The UTC-to-local conversion can shift a transaction into a neighboring calendar day. Expand your date filter by one day in either direction to locate the transaction. If it still does not appear after adjusting the filter, contact Alvys support.

**Q: Does this affect all providers, or only EFS?**

**A:** UTC storage applies to all fuel and toll providers integrated with Alvys, including EFS, Comdata, Relay, Loves, BestPass, IPass, and PrePass.

**Q: Does my time zone setting in Alvys affect what I see?**

**A:** Alvys uses the time zone reported by your browser or device. There is no separate time zone setting in the Alvys interface to configure. If your device is set to the wrong time zone, the transaction times displayed in Alvys will reflect that incorrect offset.


# How to Add and Manage Notes on a Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-add-and-manage-notes-on-a-load

Add and manage internal notes on a load from the Load Details page or Load Board, using General, Assignment, Safety, and Integration note types.

<Note>
  The Notes feature lets any logged-in user attach text notes to a load directly from the Load Details page or the Load Board. Notes are for internal team use and are not visible to drivers or external customers.
</Note>

## Overview

The Notes feature gives your team a simple way to record reminders, special instructions, and updates directly on a load. Notes stay with the load and are visible to any user in your organization who can view that load. Also known as: load notes, add a note, comments on a load.

Notes on a load can be one of five types: System, General, Assignment, Safety, or Integration. System notes are created automatically by Alvys when certain events occur. The other types can be added manually by any logged-in user.

You can add notes from two locations: the Load Details page (when you have the load open) or the Load Board (without opening the load).

## Before You Start

* You must be logged in to Alvys. No additional permission beyond standard login is required to add or edit notes.
* Notes are limited to 4,000 characters each.
* Notes are for internal use only: they are not shared with drivers via the mobile app or with external customers via public tracking links or documents.

## Add a Note from the Load Details Page

Use this method when you already have the load open.

1. Open the load you want to add a note to. This takes you to the Load Details page.
2. Locate the management ribbon. This ribbon runs along the bottom of the Stops section (toward the bottom right of the page on a desktop).
3. Click the **Notes** button in the management ribbon.
4. The notes panel opens on the right side of the screen. Any existing notes for this load are displayed here.

   <img alt="A user clicking the Notes button in the management ribbon on the Load Details page, the notes panel opening, typing a note, and clicking Add Note to save it" />

   *A user clicking the Notes button in the management ribbon on the Load Details page, the notes panel opening, typing a note, and clicking Add Note to save it*
5. Type your note in the text field.
6. Click **Add Note** to save. The note is attached to the load immediately.

## Add a Note from the Load Board

Use this method when you are working from the Load Board and do not want to open the full load details.

1. Navigate to the Load Board.
2. Find the load you want to add a note to.
3. Right-click anywhere on the load's row. A context menu appears.
4. Select **View Notes** from the menu. The notes panel opens.

   <img alt="A user right-clicking a load row on the Load Board, selecting View Notes from the context menu, typing a note in the panel, and clicking Add Note" />

   *A user right-clicking a load row on the Load Board, selecting View Notes from the context menu, typing a note in the panel, and clicking Add Note*

   ***
5. Type your note in the text field.
6. Click **Add Note** to save.

## Result

The note is saved to the load and visible to all users in your organization who can view that load. Notes appear in the notes panel in the order they were added.

## Troubleshooting

### Note is not saving

1. Check that your note is within the 4,000-character limit. Notes that exceed the limit cannot be saved.
2. Confirm you clicked **Add Note** and not just closed the panel. The note is only saved when you explicitly click **Add Note**.
3. If the issue persists after verifying both of the above, contact Alvys support.

### Notes panel is not opening from the Load Board right-click menu

1. Confirm you are right-clicking directly on the load row (not on a button or a linked cell within the row). The context menu only appears on a plain row area.
2. If the context menu appears but does not include **View Notes**, your organization may have a customized context menu configuration. Contact Alvys support.

## FAQs

**Q: Can I edit a note after I have saved it?**

**A:** Yes. Saved notes can be edited. Open the notes panel on the load, locate the note you want to change, and use the edit option that appears on the note. You can also delete a note and add a new one if preferred.

**Q: Are notes visible to drivers or external customers?**

**A:** No. Notes are designed for internal team communication. They are not shared with drivers via the mobile app or with external customers via public tracking links or documents.

**Q: What note types are available?**

**A:** There are five note types: System, General, Assignment, Safety, and Integration. System notes are created automatically by Alvys. The remaining types can be selected manually when adding a note.

**Q: Is there a character limit for notes?**

**A:** Yes. Each note is limited to 4,000 characters.

**Q: Can I add multiple notes to the same load?**

**A:** Yes. You can add as many notes as needed to a single load. All notes for a load are displayed in the notes panel in the order they were added.


# How to Add Roles to Loads and Trips
Source: https://docs.alvys.com/en/help/loads-trips/how-to-add-roles-to-loads-and-trips

Assign sales agents, service reps, load planners, and carrier sales agents to loads and trips, or preconfigure default roles on customer profiles.

<Note>
  Assign team members to specific roles on loads and trips, including Customer Sales Agent, Customer Service Representative, Sales Manager, Customer Account Manager, and Load Planner at the load level, and Carrier Sales Agent at the trip level. Roles can also be pre-configured in customer and carrier profiles to populate automatically on new loads.
</Note>

## How to Add Roles to Loads and Trips

### Overview

Roles on loads and trips let you designate which team members are responsible for specific tasks within each load. Assigning roles improves accountability and makes it easier to track who owns each part of the workflow, from sales through carrier coordination. Also known as: assign rep, assign agent, load roles, trip roles.

You can assign roles directly on a load or trip. You can also pre-configure default roles in a customer or carrier company profile so they are applied automatically to new loads.

Synonyms: sales agent, service rep, load planner, account manager, carrier sales agent, assign rep, assign agent.

### Before You Start

Any authenticated Alvys user can assign roles to loads and trips. No special permission is required.

### Steps

1. Open the Load Details Page. Navigate to the load you want to update and open the Load Details Page.
2. Assign load-level roles. In the load details section, locate the roles fields and assign any of the following:

   * **Customer Sales Agent** (formerly Sales Agent): the salesperson who sold this load to the customer.
   * **Customer Service Representative**: the team member managing customer communication for this load.
   * **Sales Manager**: the manager overseeing the sales relationship for this load.
   * **Customer Account Manager**: the account manager for the customer on this load.
   * **Load Planner**: the person responsible for planning the execution of this load.

     <img alt="Load Details Page showing the role assignment fields." />

     *Load Details Page showing the role assignment fields.*
3. Assign trip-level roles. Open the trip within the load. In the trip details, assign the following role:

   * **Carrier Sales Agent**: the team member who arranged the carrier for this trip.

If a Carrier Sales Agent is already set on the carrier's profile in Alvys, the field auto-populates when you add that carrier to the trip. You can update it manually at any time.

### Result

Assigned roles appear on the load and trip details and are visible to all users who can access the load. Changes take effect immediately.

### Variations

#### Pre-configure roles in a customer profile

To save time on new loads, you can assign default roles directly in a customer's company profile. The following roles can be pre-set there:

* Customer Sales Agent
* Customer Service Representative
* Sales Manager
* Customer Account Manager

When a new load is created for that customer, these roles are automatically copied to the load.

<img alt="Customer company profile showing role pre-assignment fields." />

*Customer company profile showing role pre-assignment fields.*

#### Pre-configure a Carrier Sales Agent in a carrier profile

You can assign a Carrier Sales Agent within a carrier's profile. Once set, that agent is automatically applied to any load or trip where that carrier is assigned.

<img alt="Carrier profile showing Carrier Sales Agent assignment field." />

*Carrier profile showing Carrier Sales Agent assignment field.*

### Troubleshooting

#### Role dropdown shows no users

The user you want to assign may not have an active account in Alvys. Confirm the user's account is active under Administration settings.

#### Carrier Sales Agent did not auto-populate on a new trip

Auto-population only occurs when the carrier profile had a Carrier Sales Agent assigned before the trip was created. If the carrier profile was updated after the trip was created, update the trip's Carrier Sales Agent manually.

### FAQs

**Q: Is Load Planner the same as Dispatcher?**

**A:** No. Dispatcher is a trip-level role assigned separately within the trip's details. Load Planner is a load-level role that identifies who is planning the load's execution. They are independent roles.

**Q: Can more than one person be assigned to the same role on a load?**

**A:** No. Each role field supports one assignee at a time. To change an assignee, select a different user from the role dropdown.

**Q: Do roles control what a user can see or do on the load?**

**A:** No. Roles are informational designations used for tracking and reporting purposes. They do not grant or restrict access to features on the load; access is controlled separately by user permissions.

### Go Deeper

* [User Roles on Alvys](/en/help/administration/user-roles-in-alvys)
* [Customer Account Manager Role on Loads](/en/help/administration/customer-account-manager-role-on-loads)
* [Overview of User Permissions](/en/help/administration/overview-of-user-permissions)


# How to Assign Two Carriers to the Same Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-assign-two-carriers-to-the-same-load

Split a load into separate trips to assign two carriers, each with its own rate confirmation, accessorials, and invoicing under one load record.

<Note>
  You can assign two carriers to the same load by splitting the load into separate trips and assigning a different carrier to each trip. Each trip is managed independently, with its own rate confirmation, accessorials, and invoicing.
</Note>

## Overview

When two carriers are involved in delivering a single load, you do not need to create separate loads. Instead, you split the load at the transfer point and assign a different carrier to each resulting trip. This is also referred to as a load split or trip split. Also known as: split a load, two carriers one load, multi-carrier load.

Common scenarios where this applies:

* You brokered a load to one carrier, but a second carrier completed the final leg of delivery.
* A load required an asset change (driver, truck, or trailer) at an intermediary location.
* A complex route needs to be divided into traceable segments for dispatching and billing purposes.

Each trip created by a split has its own carrier assignment, rate confirmation, accessorials, and invoicing, while all trips remain organized together under the same load.

## Before You Start

* You must be logged in to Alvys. No additional permission beyond standard login is required to split a trip or assign carriers.
* The load must exist in the system before splitting. You can split a trip at any point in the load lifecycle, including while the trip is **In Transit**.
* Have the address of the transfer point (the location where the carrier handoff occurs) ready before starting.

## Steps

1. Open the load.

   * Navigate to the Load Board.
   * Find the load that requires two carriers.
   * Click the load to open the Load Details page.
2. Open the Optimize modal.

   * In the Trips / Stops section of the Load Details page, locate the **Optimize** button. It appears above or below the list of stops.
   * Click **Optimize** to open the Optimize Trips modal.

<Note>
  <img alt="The Load Details page with the Optimize button visible in the Trips / Stops section of the management ribbon." />

  *The Load Details page with the Optimize button visible in the Trips / Stops section of the management ribbon.*
</Note>

1. Split the trip.

   * In the Optimize modal, click the **Split** option.
   * Enter the address where the trip will be split. This is the intermediary stop where the carrier handoff occurs.
   * Confirm the location on the map if needed.
   * Click **Save** to confirm the split point address.
   * Enter the date and time when the split will occur at that location.
   * Click **Add Location**. The system divides the original trip into two trips: the first ends at the split point, and the second begins there and continues to the original destination.
   * Scroll down and click **Save** to apply the changes.
2. Assign a carrier to each trip.

   * On the Load Details page, you now see two trips listed under the same load.
   * Open the first trip and assign the first carrier using the carrier assignment fields.
   * Open the second trip and assign the second carrier.

Each trip now has its own carrier, and you can manage rate confirmations, accessorials, and invoices for each trip independently.

## Result

The load is divided into two trips, each with a different carrier assigned. Both trips remain linked to the same load, so all activity is visible in one place. You can send separate rate confirmations, process separate carrier invoices, and track each trip independently.

## Variations

### Splitting a load more than once

You can repeat the split process up to 20 times on a single load, creating up to 20 separate trips. This is useful for loads with multiple handoff points or complex multi-leg routes.

### Rearranging stops after a split

If you need to change the sequence of pickups and deliveries within a trip after splitting:

1. Open the Optimize modal from the Load Details page.
2. Click **Re-Arrange**.
3. Drag and drop stops into the preferred order.
4. Click **Save** to confirm.

### Canceling a split

If you need to undo a split, you can cancel it from the load. The original trip is restored and the split trips are removed.

## Troubleshooting

### Split results in unexpected stop order

1. Open the Optimize modal and use the Re-Arrange option to reorder stops within each trip.
2. Click Save to apply the corrected sequence.

### Carrier assignment is not saving on a split trip

1. Confirm the trip was saved after the split. If the Save button was not clicked after adding the split point, the split may not have been applied.
2. Reload the load and attempt the carrier assignment again. If the issue persists, contact Alvys support.

## FAQs

**Q: Can I assign two carriers to a load without splitting it?**

**A:** No. Alvys uses separate trips to represent each carrier's segment of a load. To assign different carriers, you must split the load into multiple trips first.

**Q: Can I split a load that is already in transit?**

**A:** Yes. You can split a trip regardless of its current status, including when it is **In Transit**.

**Q: What happens to the original load when I split it?**

**A:** The original trip is divided into two or more trips, all linked to the same load. No load data is lost; all related information remains accessible from the Load Details page.

**Q: Can I handle billing separately for each carrier after a split?**

**A:** Yes. Each trip has its own carrier rate, rate confirmation, and invoicing after the split. You manage billing for each carrier independently.

**Q: Is there a limit to how many times I can split a load?**

**A:** Yes. You can split a single load's journey up to 20 times.

## Go Deeper

* [Optimize: Split Trips and Rearrange Stops](/en/help/loads-trips/optimize-split-trips-rearrange-stops)


# How to Block Unvetted Carriers from Load Assignment
Source: https://docs.alvys.com/en/help/loads-trips/how-to-block-unvetted-carriers-from-load-assignment

Choose which carrier statuses are blocked from being assigned to a load, so pending or do-not-load carriers cannot be dispatched even by mistake.

<Note>
  A company setting lets you pick the carrier statuses that cannot be assigned to a load — Pending, Do Not Load, Expired Insurance, and others. Carriers in a blocked status are refused outright, with no override. The setting is off until an admin turns it on.
</Note>

## Overview

Documenting a carrier or adding a carrier quote records that carrier in Alvys as **Pending**: captured, but not onboarded. Historically, assigning a Pending carrier to a load only raised a warning that anyone could click past — which meant brokers avoided documenting carriers at all, rather than risk an unvetted carrier ending up on a live load.

You can now turn that warning into a hard block. An admin chooses which carrier statuses are blocked, and carriers in those statuses cannot be assigned to a load at all. Carriers in any status you have not blocked keep the previous warn-and-continue behavior, so you decide how strict this is.

Also known as: block pending carriers, carrier status restriction, prevent unvetted carrier assignment, carrier vetting guardrail.

## Before You Start

* Turning this on is a company-level change, so you need an admin who can edit company settings. Individual dispatchers cannot enable or bypass it.
* Decide which statuses your operation should refuse. This is a business decision, not a technical one — a brokerage that quotes widely will treat **Pending** differently from one that only dispatches fully onboarded carriers.
* Nothing changes until the setting is turned on. Leaving it alone preserves today's behavior exactly.

## Steps

1. Open your company settings and find the blocked carrier statuses setting.
2. Select the carrier statuses that should be blocked from load assignment. You can choose any combination of:

   * **Pending**
   * **Do Not Load**
   * **Expired Insurance**
   * **Interested**
   * **Invited**
   * **Packet Sent**
3. Save the setting.

From that point on, assigning a carrier whose status is in your blocked list is refused. In the Dispatch Planner the assignment control is disabled, with a tooltip explaining why.

## Result

Carriers you have not vetted cannot reach a live load. You can document and quote carriers freely — which is what carrier quotes are for — without the risk of a rate confirmation going to a carrier who was never onboarded.

## What happens on a load that already has a blocked carrier

The block applies when a carrier is **newly assigned or changed**. It does not lock you out of a load that already carries one.

This matters when a carrier's status changes mid-trip — insurance lapsing while a load is in transit is the common case. In that situation:

* The carrier stays on the load. Nothing is unassigned automatically.
* Dispatchers can still edit and re-save the load — updating stop times, references, and so on — so tracking and status updates keep flowing. They see a warning rather than a block.
* Replacing the carrier does require choosing one in an allowed status.

## Where the block applies

| Where                                     | Behavior                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Assigning or changing a carrier on a load | Refused if the carrier's status is blocked.                                                                                           |
| Dispatch Planner                          | The assignment control is disabled, with a tooltip giving the reason.                                                                 |
| Bulk import                               | Rows assigning a blocked carrier are rejected during validation, and the annotated file is returned so you can see which rows failed. |
| Alvys API                                 | The same rule applies to carrier assignment through the API.                                                                          |
| Signing a rate confirmation               | Not affected. Signing is not treated as a new assignment.                                                                             |

## This is not the same as the compliance override error

Alvys has two separate reasons it can refuse a carrier, and they behave differently. If you are troubleshooting a blocked assignment, check which one you are seeing:

|                           | Blocked carrier status                                               | Compliance restriction                                                                       |
| ------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **What triggers it**      | The carrier's status in Alvys is in your blocked list                | The carrier's status with Highway, RMIS, or MyCarrierPackets does not meet your requirements |
| **Can it be overridden?** | No                                                                   | Yes, by a user with override permission                                                      |
| **How to resolve**        | Move the carrier to an allowed status, or choose a different carrier | Resolve the carrier's compliance status with the provider, or ask for an override            |

For the second, see [Override Authorization Error When Assigning a Carrier](/en/help/loads-trips/override-authorization-error-when-assigning-a-carrier).

## Troubleshooting

### A dispatcher cannot assign a carrier and there is no override option

1. Check the carrier's status in Alvys against your blocked list. If the status is blocked, this is the setting working as configured — not a fault.
2. To use that carrier, progress them to an allowed status by completing onboarding.
3. If the carrier should never have been blocked, have an admin review which statuses are selected in company settings.

### A bulk import failed on carrier rows

1. Open the annotated file returned by the import. The rejected rows are marked.
2. Check the status of the carriers on those rows. Rows assigning a blocked carrier are rejected during validation.
3. Correct the carrier or complete their onboarding, then re-import.

### A carrier on a live load has just become non-compliant

You do not need to do anything to keep working the load. Dispatchers can still edit and save it, and will see a warning rather than a block. Replace the carrier when you are ready, choosing one in an allowed status.

## FAQs

**Q: Is this on by default?**

**A:** No. Nothing changes until an admin turns it on and selects the statuses to block.

**Q: Can a manager override the block for one load?**

**A:** No. Unlike the compliance restriction, a blocked carrier status has no override. That is the point of it — the alternative was a warning people clicked past.

**Q: Will turning this on unassign carriers from loads that are already moving?**

**A:** No. It only applies when a carrier is newly assigned or changed. Existing assignments are left alone, and dispatchers can still edit those loads.

**Q: Does it stop us quoting or documenting a carrier?**

**A:** No. You can document and quote carriers as freely as before. The block applies only to assigning one to a load.

**Q: Which statuses can be assigned once this is on?**

**A:** Any status you have not blocked. Carriers who have completed onboarding remain assignable in every configuration.

## Go Deeper

* [Override Authorization Error When Assigning a Carrier](/en/help/loads-trips/override-authorization-error-when-assigning-a-carrier)
* [How to Verify a Motor Carrier in Alvys](/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys)


# How to Cancel Loads in Alvys
Source: https://docs.alvys.com/en/help/loads-trips/how-to-cancel-loads-in-alvys

Cancel loads in Alvys by status, from Open and Covered through Dispatched, In Transit, or Delivered, with troubleshooting tips for stuck loads.

## Summary

Canceling loads in Alvys depends on the load’s status and specific conditions. This guide walks through the cancellation steps by status, plus troubleshooting for common issues.

## General Prerequisites for Load Cancellation

Before attempting to cancel a load, ensure the following:

* You have the necessary permissions to manage and cancel loads.
* The load is in a cancellable status (e.g., **Open**, **Covered**, or **Dispatched**).
* Admin-level user approval (or Support assistance) may be required for certain statuses.

<Warning>
  ⚠️ Only **Open**, **Covered**, or **Dispatched** (pre-check-in) loads can be canceled directly. Every other status — including **Released**, **Queued**, **Invoiced**, **Delivered**, and **In Transit** — must first be walked back to one of these three statuses before **Cancel Load** becomes available. Reverting to an intermediate status like **Released** is not itself sufficient to cancel; it is only a step toward reaching a cancelable status.
</Warning>

## Step-by-Step Instructions by Load Status

### 1) Canceling Loads in Open or Covered Status

* Open the load in Alvys.
* Navigate to the **Manage** menu.
* Select **Cancel Load**.
* Confirm your action by clicking **Yes** in the pop-up window.
* Optionally, add a note explaining why you are canceling the load.

<Note>
  <img alt="Notion Image" />
</Note>

### 2) Canceling Loads in Dispatched Status

* Open the load and click **Manage**.
* If the driver has not checked in to the Pickup stop, the **Cancel Load** option will be available.

**Important:**

You **cannot** cancel loads that are in **Delivered** or **In Transit** status directly.

Loads can only be canceled if they are in one of the following statuses:

* **Open** (no asset assigned)
* **Covered**
* **Dispatched** (only if the driver has not yet checked in to the Pickup stop)

### 3) Canceling Loads in Delivered Status

If a load is **Delivered** but still needs to be canceled, you must work backward through statuses:

* Open the load and go to the Pickup stop.
* Change the Pickup stop status to **Open**.
* Refresh the load by marking the last stop as **Covered**.
* Return to the **Manage** menu and select **Cancel Load**.

### 4) Canceling Loads in In Transit Status

If a load is **In Transit** but still needs to be canceled:

* Open the load and locate the first stop.
* Unmark the first stop as **Picked Up** to revert the load to **Dispatched** status.
* Once in **Dispatched** status, the **Cancel Load** option will appear under **Manage**.

### Canceling Loads in Delivered or In-Transit Status (UI walk-through)

* Open the load and click the **downward arrow** next to the stop status, as shown below.
* Change the status to **Covered** to revert the load to **Dispatched** status.

  <img alt="Notion Image" />

**Why work backward?**

Load statuses follow this progression: **Dispatched → In Transit → Delivered**. To revert a delivered load to **Dispatched**, you must update the statuses starting with the final stop.

Once the load status is reverted to **Dispatched**, you can cancel it using the steps outlined above.

### 5) Canceling Loads in Queued or Invoiced Status

**Queued** and **Invoiced** are further along the workflow than **Released**, so canceling from these statuses takes two phases: first get back to **Released** with Support's help, then continue reverting yourself down to a cancelable status.

* Contact Support. They will revert the load status to **Released**. This step requires Support assistance and cannot be done by the user directly.
* **Released** is not itself a cancelable status. Once the load is back at **Released**, continue reverting it yourself the same way you would for a **Delivered** or **In Transit** load (see sections 3 and 4 above), working backward through the stop statuses until the load reaches **Open**, **Covered**, or **Dispatched** (pre-check-in).
* Once the load is in one of those three statuses, select **Cancel Load** from the **Manage** menu as usual.

### 6) Canceling Loads in a Batch

* Remove the load from its batch and set the load status to **Released**.
* Open the load and mark the last stop as **Covered** to continue reverting the load toward a cancelable status.
* The **Cancel Load** option will then appear under **Manage** once the load reaches **Open**, **Covered**, or **Dispatched** (pre-check-in).

### 7) Canceling Non-Revenue Loads

* Non-revenue loads cannot be canceled directly from **Released** status.
* Request Support assistance to handle the cancellation.

### 8) Canceling Loads Already Paid to Drivers

* Remove the payment from the driver’s paystub before attempting to cancel the load.

## Troubleshooting Common Issues

### Missing Cancel Option in the Manage Menu

* Confirm the load is currently in **Open**, **Covered**, or **Dispatched** (pre-check-in) status. **Cancel Load** will not appear in any other status, including **Released**.
* Ensure the Pickup stop is set to **Open**.
* Switch to the second or third tab in the load details before accessing the **Manage** menu.

### Unable to Cancel Loads in Completed Status

* Change the load status through admin actions to enable cancellation.

### Cancel Option Not Available for Delivered Loads

* Revert the load status to **Covered** or **Open** before attempting cancellation.

## FAQs

### Do I need to delete the shipper and consignee to cancel a load?

No, you don’t need to delete the shipper or consignee. Ensure all stop statuses are correctly updated before canceling the load.

### Can I cancel a load myself without support assistance?

Yes, as long as the load is in a cancellable status (e.g., **Open**, **Covered**, or **Dispatched**). For other statuses, Support assistance may be required to first revert the load back toward one of these three statuses.

### Can I cancel a load once it’s back in Released status?

No. **Released** is an intermediate stop on the way to a cancelable status, not a cancelable status itself. After a Support agent reverts an **Invoiced** or **Queued** load to **Released**, you still need to revert it further, the same way you would for a **Delivered** or **In Transit** load, until it reaches **Open**, **Covered**, or **Dispatched** (pre-check-in). Only then does **Cancel Load** appear in the **Manage** menu.

## Conclusion

Canceling loads in Alvys requires understanding the load’s current status and following the appropriate steps. Only **Open**, **Covered**, or **Dispatched** (pre-check-in) loads can be canceled directly, and every other status must be reverted back to one of these three first. For complex scenarios or when the cancel option is unavailable, refer to the troubleshooting tips or contact Support for assistance.


# How to clone a load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-clone-a-load

Clone or duplicate a load to reuse customer, stops, and shipment details on a new Open load without copying rates, carrier, or driver data.

<Note>
  Cloning a load (also called duplicating or copying a load) creates a new **Open** load with the same customer, stops, and shipment details as the original. Rates, carrier, driver, and document information are not carried over.
</Note>

## Overview

The Clone feature lets you duplicate an existing load without re-entering repeat shipment information. The cloned load opens in **Open** status with the same customer, office, stops, equipment requirements, and delivery details as the original. You then assign a carrier, enter rates, and complete any remaining details. Also known as: duplicate a load, copy a load.

Cloning is useful for recurring shipments on the same lane, or when you want to use an existing load as a starting point for a new booking. You can also use Load Templates for common recurring scenarios.

## Before You Start

* No additional role or permission is required to clone a load.
* The Clone option is not available on split loads. If the load has been split into multiple legs, Clone will not appear in the Manage menu.
* The customer on the load must be a Customer or Broker type. If the customer is missing or not a billing type, the clone will fail.

## Steps

1. Open the load you want to clone.
2. Go to **Loads** in the left navigation.
3. Find and open the load you want to duplicate.
4. Click **Manage** and select **Clone**.

   <img alt="GIF showing how to clone a load: opening a load, clicking the Manage dropdown, selecting Clone, and confirming to create a new Open load." />

   *GIF showing how to clone a load: opening a load, clicking the Manage dropdown, selecting Clone, and confirming to create a new Open load.*
5. On the open load, click the **Manage** dropdown.
6. Select **Clone**.

   If Clone does not appear in the Manage menu, the load is a split load and cannot be cloned. See the Troubleshooting section below.
7. Confirm.
8. A dialog appears: "A new load will be created with the same customer and stops. You will need to set the rates and dates."
9. Click **Yes** to confirm.

The new load opens automatically in **Open** status.

## Result

The cloned load is created in **Open** status and is unlocked. The following details are carried over from the original:

* Customer, office, and customer contact
* Delivery date
* General instructions
* Equipment type and length
* Load type, payment terms, and priority
* Load weight and volume
* Stops: pickup and delivery locations
* Temperature settings
* Hazmat and continuous move flags
* Customer team assignments: planner, sales agent, manager, service representative, and account manager
* Fleet
* Load board rate
* Trip references

  The following details are not carried over:
* Carrier, driver, truck, and trailer assignments
* Carrier rates, driver pay rates, and fuel surcharge
* Notes
* Documents and attachments
* Stop timestamps (actual pickup and delivery times)
* Pickup dates
* Paid miles and carrier invoice number

## Variations

**Recurring shipments on the same lane:** Clone the most recently completed load each time a new shipment is booked for the same customer and lane. Update the delivery date and any stop details that have changed, then assign a carrier.

**Exploring multiple carrier options:** Because a load can only have one carrier assigned, clone the load to create a separate record for each carrier option you want to evaluate. Delete the loads you do not use.

## Troubleshooting

### Clone option not visible in the Manage menu

1. Check whether the load has been split. Clone is hidden for every leg of a split load.
2. If the load is split and you need a new load with similar details, create a new load manually using the same customer, stops, and shipment information from the original.
3. If the load is not a split load and Clone still does not appear, contact Alvys support.

### Clone does not complete (customer error)

1. Open the original load and verify the customer field shows an active customer.
2. Confirm the customer is set to a Customer or Broker type. Non-billing customer types cannot be used on a cloned load.
3. If the customer appears correct and the clone still fails, contact Alvys support.

## FAQs

**Q: Does cloning a load copy the carrier and driver assignments?**

**A:** No. Carrier, driver, truck, and trailer assignments are not copied. You assign a carrier to the cloned load after it is created.

**Q: Does the cloned load carry over the rates from the original?**

**A:** No. Carrier rates, driver pay rates, and fuel surcharge are not copied. You enter rates on the cloned load separately.

**Q: Are notes and documents copied when I clone a load?**

**A:** No. Notes and documents are not copied. The cloned load starts without any notes or attachments.

**Q: Can I clone a split load?**

**A:** No. The Clone option does not appear for split loads. If you need a similar load, create a new load manually.

**Q: What status does the cloned load start in?**

**A:** The cloned load always starts in **Open** status, regardless of the status of the original load.

## Go Deeper

* [Dispatching a Load](/en/help/loads-trips/how-to-dispatch-a-load)
* [Creating Load Templates](/en/help/loads-trips/how-to-create-and-use-load-templates)


# How to Collapse and Expand Stops on a Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-collapse-and-expand-stops-on-a-load

Collapse and expand individual stop cards on the Load Details page to hide clutter on multi-stop loads while keeping status and location visible.

<Note>
  Collapse individual stop cards on the Load Details Page to reduce visual clutter and focus on essential information. Each stop can be independently collapsed or expanded at any time without affecting load data or driver visibility.
</Note>

## Overview

When a load has many stops, the Load Details Page can become long and difficult to navigate. Collapsible stops let you hide the detail fields for individual stops, leaving only the essential information visible: stop type, loading type, current status, and location. Expanding a stop restores all its details.

Synonyms: collapsible stops, hide stop details, minimize stop, stop toggle, shrink stop card.

Collapsing a stop does not change or delete any load data. It only adjusts what is shown on your screen during the current session.

## Before You Start

Any user with access to the Load Details Page can collapse and expand stops. No specific role or permission is required.

## Steps

**1.Open the Load Details Page**

Navigate to the load you want to work with and open the Load Details Page. All stops load in their fully expanded state by default.

**2.Collapse a stop**

Click anywhere on the header row of the stop you want to collapse. The stop card contracts and shows only the stop type (for example, Pickup or Delivery), loading type (for example, Live or Drop and Hook), current status (for example, **Open** or **Arrived**), and location.

*\[Video not supported]*

**3.Expand a stop**

Click the header row of the collapsed stop again. The stop card expands and shows all details, including appointment times, instructions, commodities, references, and notes.

## Result

Each stop can be independently collapsed or expanded. You can work through a long load by collapsing stops you have already reviewed and expanding only the ones you are actively working on.

## Troubleshooting

### Stop returned to expanded state after page reload

The collapsed or expanded state of each stop is stored in memory only for the current session. When you reload the Load Details Page, all stops return to their default expanded state.

## FAQs

**Q: Does collapsing a stop permanently hide or delete any information?**

**A:** No. Collapsing a stop only changes how the stop is displayed during your current browser session. No data is changed or deleted. Expanding the stop shows all details exactly as they were.

**Q: Does collapsing stops affect what drivers see in the Driver App?**

**A:** No. Collapsible stops only affect your view in the Alvys web application. Drivers see their trip and stop details in the Driver Companion App, which is unaffected by this feature.

**Q: Can I collapse all stops at once?**

**A:** No. Each stop must be collapsed individually by clicking its header row.

## Go Deeper

* [Stop Dates and Times](/en/help/loads-trips/stop-dates-and-times)
* [Stop Time Validations](/en/help/loads-trips/error-when-recording-arrival-or-departure-time-on-a-stop)
* [Optimize - Split Trips and Rearrange Stops](/en/help/loads-trips/optimize-split-trips-rearrange-stops)


# Configure geofences for driver check-in/out automation
Source: https://docs.alvys.com/en/help/loads-trips/how-to-configure-geofences-for-driver-check-in-out-automation

Configure per-subsidiary geofence arrival radius so the Alvys mobile app prompts drivers to check in and out automatically at each stop location.

<Note>
  Geofences are virtual boundaries around stop locations that automatically prompt drivers using the Alvys Mobile App to check in or out when they enter the configured area. Configuring an arrival radius per subsidiary lets your team capture more accurate arrival times without requiring dispatch to manually prompt drivers.
</Note>

## Overview

The Geofence Notification feature lets you define an arrival radius for each subsidiary. When a driver's device enters that radius, the Alvys Mobile App sends a push notification reminding them to check in.

Geofences are configured per subsidiary, so different parts of your company can use different radius sizes.

Synonyms: geofencing, arrival radius, location-based check-in, proximity notification, geofence alert.

## Before You Start

Before configuring geofences, confirm the following:

* You are logged in to Alvys.
* You have access to Management > Company Profile.
* Drivers you want to receive notifications are on the latest version of the Alvys Mobile App. Geofence notifications only work on the latest app version; there is no way to force a driver to update.

No specific permission is enforced on the geofence configuration endpoint. Any authenticated Alvys user who can access Management > Company Profile can enable or configure geofences for a subsidiary.

## Steps

1. **Navigate to Geofence Settings**
2. In the left navigation, go to **Management** and select **Company Profile**.
3. In the subsidiary panel on the left, select the subsidiary you want to configure.
4. Confirm you are on the **General Info** tab.
5. Scroll down to the **Geofence Notification** section.
6. To turn geofences on, click the **Geofence Notification** toggle to the on position. A configuration dialog opens automatically.
7. To turn geofences off, click the **Geofence Notification** toggle to the off position. The geofence configuration is removed for that subsidiary.

   <img alt="Geofence Notification section on the General Info tab showing the toggle and inactive state." />

   *Geofence Notification section on the General Info tab showing the toggle and inactive state.*
8. **Set the Arrival Radius**

   When you enable the toggle (or click the edit icon on an already-enabled subsidiary), the **Geofence Notification** dialog opens.
9. In the **Arrival Radius** field, enter the radius in feet. A recommended starting value is 500 ft.
10. Click **Activate** to save the configuration.

    <img alt="Geofence Notification dialog showing the Arrival Radius input field and Activate button." />

    *Geofence Notification dialog showing the Arrival Radius input field and Activate button.*
11. **Confirm Mobile Notifications Are Active**

After activating a geofence, drivers on the latest version of the Alvys Mobile App will receive push notifications based on their proximity to stop locations. To edit the radius at any time, click the pencil edit icon in the Geofence Notification section and enter a new value.

<img alt="Geofence Notification section after activation showing the configured Arrival Radius value and pencil edit icon." />

*Geofence Notification section after activation showing the configured Arrival Radius value and pencil edit icon.*

## Result

Once activated, the Alvys Mobile App monitors the driver's location relative to stop locations on their assigned trip. When the driver's device enters the configured arrival radius, they receive a push notification prompting them to check in.

<Info>
  💡 Since this is a mobile app feature, drivers must be on the latest version of the Alvys Mobile App to receive geofence notifications. There is no way to force a driver to perform this update.
</Info>

## Variations

**Editing an existing radius:** If a geofence is already enabled for a subsidiary, the Geofence Notification section shows the current arrival radius and a pencil edit icon. Click the pencil icon to open the dialog and update the value, then click **Activate**.

**Disabling geofences:** Toggle the **Geofence Notification** switch off to remove the geofence configuration for that subsidiary. Drivers will no longer receive location-based check-in prompts.

**Per-subsidiary configuration:** Each subsidiary maintains its own geofence radius. Configuring geofences for one subsidiary has no effect on other subsidiaries.

## Troubleshooting

### Geofence toggle has no effect

Reload the Company Profile page and try again. Confirm you have selected a specific subsidiary on the left panel before clicking the toggle, since the Geofence Notification section belongs to the selected subsidiary. If the configuration dialog does not open after enabling the toggle, check that your browser allows modals from the Alvys portal.

### Drivers are not receiving geofence notifications

Confirm the driver is on the latest version of the Alvys Mobile App. Confirm the driver has granted location permissions to the Alvys Mobile App on their device, and that push notifications are enabled for the Alvys Mobile App. Confirm the geofence radius is large enough for the locations the driver visits; a radius that is too small may not trigger reliably in areas with GPS accuracy limitations. If none of these conditions apply, contact Alvys support.

## FAQs

**Q: Does enabling geofences affect all subsidiaries at once?**

**A:** No. Geofences are configured per subsidiary. Enabling or editing the geofence for one subsidiary has no effect on any other subsidiary.

**Q: What unit is the arrival radius entered in?**

**A:** The arrival radius is entered in feet.

**Q: Can I configure geofences to only trigger check-in or only check-out?**

**A:** The Arrival Radius dialog currently exposes only the radius value. Trigger mode configuration (check-in only, check-out only, or both) is not available through the Company Profile UI.

**Q: What happens if a driver does not check in after entering the geofence area?**

**A:** The Alvys Mobile App sends an initial arrival notification when the driver enters the configured radius. The specific follow-up notification behavior is controlled by the mobile app and is not configurable from the Geofence Notification settings screen.


# How to Create a Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-create-a-load

Keeping track of all the info can be a daunting task. Luckily, we are here to make it easy to enter the information and keep it in one place

<Note>
  Creating a new load in Alvys sets up the shipment record, assigns the customer, and defines all pickup and delivery stops. Also called a shipment, order, or freight order.
</Note>

## Overview

A load is the core record in Alvys. It captures the customer, billing details, stop schedule, and equipment requirements for a single shipment. Every dispatched trip, invoice, and driver settlement traces back to a load. You can create a revenue load (billed to a customer) or a non-revenue load (an internal or deadhead move with no customer invoice).

This article walks through creating a load from start to finish using the New Load form. Synonyms: add a load, build a load, new shipment, create an order, enter freight.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="New Load Creation Workflow" />

[Open the recording](https://www.loom.com/share/a44e26ead29242079b913ee9d9481f46)

To create a load from a customer rate confirmation instead of typing the form, see [How to create a load using automated data entry](/en/help/loads-trips/how-to-create-a-load-using-automated-data-entry).

## Before You Start

All authenticated Alvys users can create a load; no additional permission is required.

Before beginning, confirm you have the following information on hand:

* The customer name (or be ready to create a new customer record)
* An order number (the customer's reference number for this shipment)
* Equipment type required for the load
* Pickup location, date, and time
* Delivery location, date, and time

For non-revenue loads, a customer is not required, but you still need at least one pickup stop and one delivery stop.

## Steps

### 1. Open the New Load form

In the left navigation, find the plus icon and click **New Load**.

<img alt="Left navigation expanded and 'New Load' option highlighted" />

*Left navigation expanded and "New Load" option highlighted*

### 2. Select the load entry method

1. **Select the creation method (top left):**
   * **New Load** — Standard single-load manual entry form.
   * **Bulk Upload** — Opens the file import tool (`.xlsx` format, up to **50 MB**; template download included).
   * **From Template** — Opens saved templates to quickly duplicate recurring loads.
2. **Set special parameters (top right):**
   * Check **Save as Template** if you want to store this load's setup for recurring routes.
   * Toggle **Non-Revenue Load** if this is an unbilled driver movement.
3. **Choose the data entry style (main screen):**
   * **AI Extraction (left side):** Upload your Rate Confirmation file (max **4 MB**) — Alvys AI parses the document and fills in the details automatically.
   * **Manual Entry (right side):** Enter all trip and rate parameters manually.

<img alt="New Load form header showing the load entry parameters, including the Non-Revenue toggle" />

*New Load form header showing the load entry parameters, including the Non-Revenue toggle*

### 3. Complete the Customer section under General details

1. In the **Customer** field, type the customer name and select it from the dropdown. If the customer does not exist yet, click **Add new customer** in the dropdown to create a new customer record without leaving the form.
2. In the **Invoice As** field, select the subsidiary that will invoice this customer. This field auto-populates the **Tender As** field to match. For non-revenue loads, the **Invoice As** field label changes to **Subsidiary**.
3. In the **Billing Rate** field, enter the agreed rate. Billing rate is optional; you can create the load without one and add it later.
4. In the **Order Number** field, enter the customer's reference number for this shipment. If the order number you enter already exists on another load, Alvys displays a duplicate load warning. Review the warning before continuing.
5. Optionally, click **Show more fields** to add optional parameters, including Customer Contact, Purchase Order (PO) Number, Commodity Description & Units, and Custom Customer References.

<img alt="Customer section under General Details showing the Customer field, Invoice As field, and Billing Rate field with the 'Add new customer' option visible" />

*Customer Form: the section under General Details*

<img alt="Order Number field with the duplicate load warning visible" />

*Order Number field with the duplicate load warning visible*

### 4. Complete the Tender section under General details

1. **Tender As:** Auto-populates based on your **Invoice As** selection.
2. **Fleet:** Select the appropriate fleet from the dropdown. This field is mandatory if fleets are configured in your system.
3. **Office:** Select the branch or representative office managing this load. For non-revenue loads, the Office field is optional and can be left blank.
4. **Equipment Type:** Select the trailer or equipment required for the shipment (for example, Dry Van, Reefer, Flatbed).
5. Optionally, click **Show more fields** to add optional parameters, including Customer Instructions, Customer Sales Agent, and Equipment Length.

<img alt="Tender section under General Details showing the Office field and the Show more fields toggle expanded" />

*Tender Form: the section under General Details*

### 5. Add the pickup stop

1. In the Stops section, click **Add Pickup**.
2. Fill in the pickup stop fields:
   * **Appointment Date:** Required. Enter the pickup date and time.
   * **Company:** Required. Enter or search for the pickup location. Select **Customer** to use the customer's physical address on file.
3. Fill in any additional stop details (reference numbers, notes) as needed.
4. Click **Add Stop**.

<img alt="Expanded pickup stop panel showing populated facility address and pickup date" />

*Expanded Pickup Stop Panel: showing populated facility address and pickup date*

### 6. Add the delivery stop

1. In the Stops section, click **Add Delivery**.
2. Fill in the delivery stop fields:
   * **Appointment Date:** Required. Enter the delivery date and time. The delivery date must be on or after the pickup date.
   * **Company:** Required. Enter or search for the delivery location.
3. Fill in any additional stop details as needed.
4. Click **Add Stop**.

<img alt="Expanded delivery stop panel showing populated facility address, delivery date and time window" />

*Expanded Delivery Stop Panel: showing populated facility address, delivery date and time window*

### 7. Create the load

1. **Editing stops:** Click any stop card to modify location, dates, or contact information.
2. **Adding and changing stop types:** Add additional stops as needed, or adjust a stop's type using the selector in the top-right corner of the stop card.
3. **Reordering stops:** Drag stop cards up or down to adjust multiple stops of the same type.
4. **Saving the load:** Click **Create Load** in the top-right corner. If the button cannot be selected, check the screen for red error flags or missing required fields.

<Warning>
  Sequenced stops must remain in valid chronological order.
</Warning>

<img alt="Stops section with an intermediate stop added between pickup and delivery" />

*Stops section with an intermediate stop added between pickup and delivery*

<img alt="Completed load form with all required fields filled out, enabling the Create Load button" />

*Completed Load Form: all required fields are filled out, enabling the Create Load button in the top-right corner*

<img alt="Newly created load in Open status, showing the load record page after creation" />

*Newly created load in Open status, showing the load record page after creation*

## Result

The load is created and saved in **Open** status. You can now assign a carrier, add documents, build a trip, and dispatch the load.

<img alt="Newly created load in Open status, showing the load record page after creation" />

*Newly created load in Open status, showing the load record page after creation*

## Variations

### Non-revenue load

A non-revenue load does not generate a customer invoice. To create one:

1. Turn on the **Non-Revenue** toggle at the top of the New Load form before clicking Next.
2. The **Customer** field is not required and may be left blank.
3. The **Office** field is optional for non-revenue loads.
4. The **Invoice As** field label changes to **Subsidiary** when Non-Revenue is on. Select the appropriate subsidiary if applicable.
5. Complete at least one pickup stop and one delivery stop, then click **Create Load**.

### Creating a new customer during load creation

If the customer does not yet exist in Alvys:

1. Type the new customer name in the **Customer** field.
2. Click **Add new customer** in the dropdown.
3. Complete the new customer form without leaving the New Load page.
4. The new customer populates the Customer field automatically after creation.

## Troubleshooting

### Create Load button remains inactive (greyed out)

The **Create Load** button does not become active until all required fields are complete. Confirm a **Customer** is selected (revenue loads only) and that the **Invoice As** field (or **Subsidiary** for non-revenue loads) has a selection. Confirm the **Office** field is filled in (required for revenue loads; optional for non-revenue loads), the **Order Number** field is not empty and does not contain only spaces, and an **Equipment Type** is selected. Confirm a pickup stop is present with both an **Appointment Date** and a **Company** filled in, and that a delivery stop is present with the same. Confirm the delivery date is on or after the pickup date, stops are in chronological order, and the first stop is a pickup type while the last stop is a delivery type. If all of these are complete and the button is still inactive, contact Alvys support.

### Duplicate load warning appears on the order number

The order number you entered already exists on another load in the system. Either confirm you intend to create a second load with the same order number, or go back and enter the correct order number before creating the load. If a duplicate load is created by mistake, use the in-app **Cancel** option to remove it. Duplicates can also occur from rate confirmation uploads, not just manual entry. For assistance with cancellation, contact Alvys support.

## FAQs

**Q: Do I need special permission to create a load?**

**A:** No. All authenticated Alvys users can create a load. No additional role or permission is required.

**Q: Can I save a load as a draft before it is complete?**

**A:** No. The New Load form does not have a draft or save-as-draft option. Either complete all required fields and click **Create Load**, or discard the form and start over.

**Q: What is the order number?**

**A:** The order number is the customer's reference number for this shipment; it is also called a customer reference number or customer PO number. It must not be blank and must contain at least one non-space character.

**Q: Can I create a load without a billing rate?**

**A:** Yes. The billing rate field is optional. You can create the load and add the billing rate later by editing the load.

**Q: What if I selected the wrong customer?**

**A:** After the load is created, open the load, click **Edit**, and update the Customer field. You cannot change the customer from within the New Load form after clicking **Create Load**.

**Q: What does the Non-Revenue toggle do?**

**A:** Turning on the Non-Revenue toggle marks the load as an internal or non-billable move. No customer invoice is generated. The Customer and Office fields become optional, and the Invoice As field label changes to **Subsidiary**.

**Q: Can I edit load details after the load is created?**

**A:** Most fields can be updated by opening the load and clicking **Edit**. Some fields become locked once the load advances to **Delivered** or later statuses — for example, stop locations cannot be changed after delivery. To change the customer on a **Released** load, see [How to Switch the Customer on a Released Load](/en/help/loads-trips/how-to-switch-the-customer-on-a-released-load). For stop changes after delivery, contact Alvys support.

**Q: Is there a way to save a load as a template for reuse?**

**A:** Yes — use **Clone Load**. Cloning a completed load creates a new load with the same customer, route, and equipment type, so you can reuse a common lane without re-entering all the details. See [How to clone a load](/en/help/loads-trips/how-to-clone-a-load) for steps. You can also check **Save as Template** on the New Load form and reuse it later via **From Template**.

**Q: What should I do if I accidentally created a duplicate load?**

**A:** If a duplicate load is created by mistake, use the in-app **Cancel** option to remove it. Deletion is generally restricted to training scenarios, but exceptions may be made in special cases. Contact Alvys support for further assistance if needed.

## Go Deeper

* [How to clone a load](/en/help/loads-trips/how-to-clone-a-load)
* [How to Create and Use Load Templates](/en/help/loads-trips/how-to-create-and-use-load-templates)
* [Managing a Load](/en/help/loads-trips/managing-a-load) — action buttons and Manage menu available after the load is created


# How to Create a Load Using Automated Data Entry
Source: https://docs.alvys.com/en/help/loads-trips/how-to-create-a-load-using-automated-data-entry

This feature is intended to shorten the time it takes to create a load in Alvys by extracting information from customer rate confirmations.

<Note>
  Automated Data Entry, also called rate con upload, lets you upload a customer rate confirmation PDF, JPEG, or PNG and have Alvys AI extract and prefill the New Load form, reducing manual data entry when creating a revenue load.
</Note>

## Overview

Automated Data Entry shortens the time it takes to create a load in Alvys by extracting information from a customer rate confirmation document and prefilling the New Load form. Once you upload the rate confirmation, Alvys AI reads the document and populates fields such as customer, billing rate, order number, equipment type, and stop details.

Because rate confirmation layouts vary across customers and brokers, extraction accuracy also varies. Some fields may not be populated and will require manual entry before you can submit the load.

<Warning>
  Screenshots on this page may show an older New Load layout. The steps are current: open **New Load**, choose **Revenue**, upload a PDF, JPEG, or PNG rate confirmation (4 MB max), then review the prefilled fields before you submit. For the current form, follow [How to create a load](/en/help/loads-trips/how-to-create-a-load).
</Warning>

Synonyms: rate con upload, automated load entry, AI load creation, ratecon prefill, document scan load entry.

## Before You Start

Prerequisites:

* You must have a customer rate confirmation document ready to upload. Accepted file types: PDF, JPEG, and PNG. Maximum file size: 4 MB.
* This feature is only available when creating a Revenue load. It is not available for Non-Revenue loads.

Required role: Any logged-in Alvys user can use this feature. No additional permission is required.

## Steps

1. **Open the New Load form**

   In the left navigation, click Loads and Trips, then select New Load.
2. **Select the Revenue load type**

   At the top of the form, select Revenue as the load type. The upload panel appears on the left side of the form. If you select Non-Revenue, the upload panel does not appear and Automated Data Entry is not available.
3. **Upload the rate confirmation**

In the upload panel, either drag and drop your rate confirmation file into the upload area, or click the upload area to browse and select the file. Accepted file types: PDF, JPEG, and PNG. Maximum file size: 4 MB.

<Info>
  💡 Only PDF, JPEG, and PNG files are accepted. Files larger than 4 MB will be rejected.
</Info>

<Note>
  <img alt="Load form showing the upload panel with drag-and-drop area." />

  * Load form showing the upload panel with drag-and-drop area. \*
</Note>

1. **Wait for Alvys AI to process the document**

After you select the file, the upload panel displays "**Uploading**" while the document is being processed. Extraction typically takes 10 to 30 seconds.

<Note>
  <img alt="Upload panel in processing state showing 'Uploading' indicator." />

  *Upload panel in processing state showing "Uploading" indicator.*
</Note>

1. **Review the prefilled form**

   When extraction is complete, the panel displays "Rate confirmation ready." The load details form on the right is prefilled with the extracted information. Review every field and correct any that are missing or inaccurate. Pay close attention to:

   * **Invoice As** must always be selected manually. Alvys AI cannot determine which subsidiary or division the load is booked under, so this field is never prefilled.
   * If the customer was not found in your Alvys account, you must search for or create the customer before submitting.
   * Any other required fields that were not extracted will be highlighted when you attempt to submit.

<Info>
  💡 The Invoice As field will always need to be selected manually because the software cannot determine which subsidiary the load is booked under beforehand.
</Info>

<Note>
  <img alt="New Load form with prefilled stop and customer details after successful extraction." />

  *New Load form with prefilled stop and customer details after successful extraction.*
</Note>

1. **Confirm and create the load**

After reviewing and completing all required fields, click Create Load. The load is created and the rate confirmation file is attached automatically.

## Result

A new Revenue load is created in Alvys with the extracted data applied. The rate confirmation file is attached to the load record. Any fields that were not extracted remain blank and can be edited after creation.

## Variations

### If extraction fails

If the document cannot be processed, the upload panel shows "Processing Failed." Select Retry to try again with the same file, or Clear to remove the file and start over. If the issue continues, create the load manually using the standard New Load form.

### If the customer is not found

If the extracted customer name does not match any customer in your Alvys account, the Customer field will show a "not found" indicator. Search for the correct customer manually or create a new customer record before submitting.

## Troubleshooting

### Invoice As field is empty after extraction

Alvys AI never prefills the Invoice As field. This is by design. Select the correct subsidiary from the Invoice As dropdown before submitting.

### Customer field is blank or shows a not-found indicator

The extracted customer name did not match any customer in your account. Search for the customer using the Customer field, or create a new customer record.

### File upload fails

Only PDF, JPEG, and PNG files are accepted, up to 4 MB. Convert the file to a supported format or reduce its size and try again. If the issue continues, create the load manually. If no other reason applies, contact Alvys support.

## FAQs

**Q: What file types does Automated Data Entry accept?**

**A:** PDF, JPEG, and PNG files are accepted, up to 4 MB each.

**Q: Can I use Automated Data Entry for Non-Revenue loads?**

**A:** No. The rate confirmation upload panel is only available when the load type is set to Revenue.

**Q: Which fields does Alvys AI extract from the rate confirmation?**

**A:** Alvys AI attempts to extract the customer, billing rate, order number, equipment type and length, stop details (pickup and delivery companies, addresses, and appointment dates and times), and reference numbers. The Invoice As field is never extracted and must always be selected manually.

**Q: Is reference number extraction required?**

**A:** No. Reference numbers are extracted when present but are not required.

**Q: Does the rate confirmation file get attached to the load automatically?**

**A:** Yes. The uploaded rate confirmation file is automatically attached to the load record when the load is created.

## Go Deeper

* [How to Create a Load](/en/help/loads-trips/how-to-create-a-load)


# How to create and add accessorials
Source: https://docs.alvys.com/en/help/loads-trips/how-to-create-and-add-accessorials

Create accessorial types in Settings and add charges like detention, lumper, fuel surcharge, and TONU to a load's Money Box for accurate billing.

<Note>
  Accessorials (also called accessorial charges or add-on fees) are extra charges added to a load beyond the base linehaul rate, such as detention, lumper fees, or fuel surcharges. Admins create accessorial types in Settings; users with the correct permission add them to individual loads in the Money Box.
</Note>

## Overview

Accessorials (also called accessorial charges or add-on fees) are line-item charges applied to loads to capture costs or revenue beyond the standard freight rate. Common types include detention, fuel surcharge, layover, lumper fees, and TONU (Truck Order Not Used; charged when a carrier is dispatched but the load is cancelled without delivery) charges.

Creating an accessorial type in Settings makes it available to select on any load. Adding it to a load records the charge against that load's financials.

An accessorial type created in **Settings > Accessorials** only defines the type, the allowed rate types, and some usage rules. It does not dictate who is charged or how much. Each time you add an accessorial charge to a load, you choose independently which party it applies to (Customer, Carrier, Driver, or Owner Operator) and the amount for that charge. The same type can be a \$50 customer charge on one load and a \$75 driver charge on another.

## Before You Start

Creating accessorial types requires Admin or Partner Admin role access. Adding accessorials to loads requires the **"Add Accessorials"** permission on the user profile.

## Steps

1. **Create an accessorial type (Admins only).** Navigate to **Settings > Accessorials**. Click the **Create Accessorial Type** button. Enter a type/name, choose which rate types are allowed, whether a stop is required, and whether it should also be available in the Driver App as an E-Check type, then save.

   <img alt="Create Accessorial Type button on the Settings > Accessorials page" />

   *Create Accessorial Type button on the Settings > Accessorials page*

   <img alt="New accessorial type form with name, allowed rate types, stop required, and E-Check options" />

   *New accessorial type form with name, allowed rate types, stop required, and E-Check options*

2. **Open the load.** Navigate to Loads and Trips and open the load to which you want to add a charge.

3. **Open the Money Box.** On the load details page, scroll to the Money Box section and expand it.

4. **Add the accessorial.** Click the **Add Accessorial** button in the Money Box. Select the accessorial type from the list. Choose which entity/party the charge applies to (**Customer**, **Carrier**, **Driver**, or **Owner Operator**) and enter the amount for that party. To split one charge across two parties (for example, billing the customer and deducting from the driver for the same event), check both and enter each amount independently; they are not linked. Enter any notes, then save.

   <img alt="Add Accessorial button in the Money Box on the load details page" />

   *Add Accessorial button in the Money Box on the load details page*

   <img alt="New Accessorial form with Customer, Carrier, and Driver party options and amount fields" />

   *New Accessorial form with Customer, Carrier, and Driver party options and amount fields*

5. **Confirm the charge appears.** The accessorial appears as a line item in the Money Box. Verify the amount and type are correct before invoicing.

<Warning>
  You do not set an amount or a customer/driver side on the accessorial type. Both are chosen each time the charge is added to a load, in Step 4 above.
</Warning>

## Result

The accessorial charge is recorded on the load. Where it flows depends on the party you selected when you added it: Customer-side charges flow into the customer-facing invoice, and Driver or Owner Operator charges flow into the corresponding pay settlement.

## Variations

**Editing an accessorial type (Settings):** In **Settings > Accessorials**, you can change which rate types are allowed, whether a stop is required, and the Driver App E-Check flag on an existing type. The type's name cannot be changed once created, and there is no default amount stored on the type to edit. Every load's accessorial amount is entered independently, so nothing you change here affects charges already recorded on existing loads.

<img alt="Edit icon next to an existing accessorial type on the Settings Accessorials page" />

*Edit icon next to an existing accessorial type on the Settings Accessorials page*

**Editing an existing accessorial on a load:** Click on the accessorial amount, then the pencil icon next to the accessorial line item in the Money Box to update the amount or notes. Changes apply only to this load.

<img alt="Accessorial amount expanded in the Money Box showing the pencil edit option" />

*Accessorial amount expanded in the Money Box showing the pencil edit option*

**Removing an accessorial:** Click on the accessorial amount, then the trash icon (remove accessorial button) next to the accessorial line item. Accessorials that have already been included in a processed settlement or sent invoice cannot be removed.

<img alt="Trash icon used to remove an accessorial line item from the Money Box" />

*Trash icon used to remove an accessorial line item from the Money Box*

**Applying, changing, or removing a customer lane contract on the load:** Manually added customer accessorials stay on the load. Alvys removes only the accessorial lines that came from the previous contract template. If the same charge type exists on both a manual line and a contract template, for example two Detention lines, both are kept. The same rules apply to a batch contract refresh that runs on loads after you edit a contract.

In the invoice and accessorial grid, a manually added line on a contracted load does not show **Source = Contract**. That label is reserved for lines that came from a template, so it is the quickest way to tell which lines a contract change can clear.

**Cancelling a load that has an active accessorial charge on it:** A load cannot be cancelled while it still has an active accessorial charge on it. This applies regardless of which entity/party the charge is on (Customer, Carrier, Driver, or Owner Operator).

<Warning>
  If you try to cancel a load that still has an active accessorial, you get a blocking message: *"Unable to cancel the load due to active accessorials. Please cancel them first or move them to another load and try again."* The cancel action stops there. Remove the accessorial from the load first (trash icon in the Money Box) or move it to another load, then cancel.
</Warning>

If the accessorial you need to remove is tied to a **used e-check** (one that has already been issued and used), you cannot delete it or cancel the e-check directly; the system blocks that too, the same way it blocks cancelling the load. Instead, move the e-check (and its linked accessorial) to another load for the **same driver**; either a past or a future load works. Double-check the destination load's driver yourself before moving it.

**EDI accessorial mapping:** To ensure accessorial charges export correctly in EDI files, each type must be mapped to your trading partner's codes. See [How to map accessorials for EDI](/en/help/administration/how-to-map-accessorials-for-edi) for the full EDI mapping setup.

## Troubleshooting

### Add Accessorial button is not visible in the Money Box

* Verify the **"Add Accessorials"** permission is enabled on your user profile. If it is not, contact your administrator to have it added.
* If the load has been split into multiple trips, the Add Accessorial button is intentionally hidden on the original/parent trip. Add the charge from the individual split trip instead.

  <img alt="Load split into multiple trips, where the accessorial is added from the split trip" />

  *Load split into multiple trips, where the accessorial is added from the split trip*

### An accessorial type is not in the list

* Confirm the accessorial type has been created in **Settings > Accessorials**. An Admin or Partner Admin must add it before it is available to select on loads.

### Accessorial cannot be removed from the load

* The accessorial has already been included in a processed driver pay statement or a sent invoice. Contact your accounting team if the charge needs to be corrected after processing.

### A manually added accessorial disappeared after a lane contract change

* Alvys keeps manually added customer accessorials when you apply, change, or remove a customer lane contract, and removes only the lines that came from the previous contract template. If a line was added before that behavior shipped, it may still be recorded as contract-owned and cleared with the template. Re-add the charge; new manual lines persist through later contract changes.

### I need to change which entity (Customer/Carrier/Driver/Owner Operator) an accessorial type applies to, and there is no option for it

* There isn't one, and that is expected: an accessorial type never stores a party/side at all. Which entity/party a charge applies to is chosen fresh every time you add it to a load (see Step 4, "Add the accessorial", above), not on the type. If a charge was added to the wrong entity, remove it and re-add it with the correct party selected. There is no "edit the type's side" path because there is no side stored on the type to begin with.

### An accessorial I added isn't showing up on a driver's statement

* If the driver's statement has already been **processed**, a newly added or changed accessorial will not automatically appear on it. Reopen the trip from draft, or revert the processed statement, to trigger a recompute that includes the new charge.

### "Input data is invalid" when adding an accessorial

* This usually means the party you selected does not match the trip's Brokerage/Carrier designation. For example, a Carrier charge on a non-brokerage trip, or a Driver/Owner Operator charge on a brokerage trip. Check the party you selected against the trip type, or correct the trip's brokerage/carrier designation if it is wrong.

### An unexpected charge appears in the customer Money Box after issuing an e-check

* Issuing an e-check automatically creates a matching customer-side charge so it can be invoiced. If you do not intend to bill the customer for it, remove it manually from the customer Money Box. There is currently no setting to suppress this automatic charge.

## FAQs

**Q: Can I set a default amount for an accessorial type?**

**A:** No. Accessorial types (Settings > Accessorials) do not store an amount. Every accessorial's amount is entered independently each time it is added to a load, so there is nothing to default.

**Q: Do accessorials appear on the customer invoice automatically?**

**A:** Accessorials added on the **Customer** side are included in the invoice when the load is invoiced. The side is chosen on the charge itself when you add it to the load, not on the accessorial type.

**Q: Will my manually added accessorials survive a lane contract change?**

**A:** Yes. Applying, changing, or removing a customer lane contract clears only the accessorial lines that came from the previous contract template. Manually added customer accessorials stay on the load, and a manual line and a template line of the same charge type are both kept.

**Q: Who can create accessorial types?**

**A:** Admins and Partner Admins can create and manage types in Settings > Accessorials. Operations Managers and Billers can add accessorials to loads using the **"Add Accessorials"** permission.

**Q: Can I deduct an amount from an owner-operator's or driver's pay using an accessorial?**

**A:** Yes. Add the charge as a Driver or Owner Operator accessorial and enter a **negative** amount. It will reduce that settlement by the amount entered.

**Q: How can I see who added, changed, or removed an accessorial on a load?**

**A:** Open the load and click **Logs**. Every accessorial action is logged individually, showing the accessorial type, the amount, who performed the action, and when.

**Q: Can I pay a driver a percentage of an accessorial charge instead of a flat amount?**

**A:** Yes. Set a percentage on the driver's profile under **Accessorial Rate** (configured per accessorial type), then check **Apply Driver Rate** when adding that accessorial to a load. This has to be set on each driver individually; there is currently no way to apply it across a group or your whole fleet at once. Accessorial payouts are also handled separately from a driver's general "% of Trip Value" pay rule, so this per-accessorial rate is the only way to make an accessorial payout proportional rather than a flat number.

**Q: If I add an accessorial to a load, does it automatically show up on a paired driver's or owner-operator's settlement too?**

**A:** No. Line-haul pay (like % of Trip Value, per-mile, or per-trip) automatically splits between a driver and their paired owner-operator, but accessorials do not work that way. A charge only lands on the settlement of whichever party you picked when you added it (see Step 4, "Add the accessorial", above). If you need the same charge reflected on someone else's settlement too, you have to add it there yourself, or handle it as a manual deduction.

**Q: Why doesn't "Freight Amount" change when I add an accessorial?**

**A:** That is expected. **Freight Amount** shows Line Haul + Fuel Surcharge only and never includes accessorials. **Total Billable**, shown separately in the Money Box, does include any Customer-side accessorials and updates as soon as you add one. If you are trying to confirm an accessorial was added correctly, check Total Billable (or the accessorial line item itself), not Freight Amount.

**Q: I paid for something out of pocket on behalf of a driver (like a lumper). Should I add it as an accessorial, or use a deduction/reimbursement?**

**A:** If the expense is already an accessorial-type charge on the load (a lumper fee, detention, and so on), add it as a **Driver** or **Owner Operator** accessorial (see Step 4, "Add the accessorial", above). That keeps it tied to the load, so it shows up correctly in the accessorial breakdown and any related reports. Use the **Deduction/Reimbursement** option for amounts that are *not* an accessorial charge on a specific load, such as general reimbursements and miscellaneous deductions. Do not run the same expense through both, or it will get counted twice.

**Q: Why don't fuel surcharge (FSC) or stop-off charges show up in the Carrier Rate or Carrier Payable?**

**A:** It comes down to whether carrier accessorials are even available on that load:

* **Brokered loads** (you are paying an outside carrier): carrier accessorials are available. Add one for FSC, a stop-off, or anything else to the carrier, and it automatically rolls into the Carrier Payable total right alongside the linehaul rate.
* **Carrier-managed loads** (your own carrier or subsidiary is hauling it, not a brokered relationship): carrier accessorials are not available at all. The Add Accessorial screen will not even list "Carrier" as an option; only Customer, Driver, and Owner Operator.

So if an FSC or Stop Off charge was added on a carrier-managed load, it landed on the Customer and/or Driver/Owner Operator side instead. It was never going to show up in the Carrier Payable, because there is no such thing as a carrier accessorial on that type of load, so there is nothing to "pull over." If the carrier still needs to be paid for that amount, it has to be included in their linehaul rate directly.

## Go Deeper

* [How to map accessorials for EDI](/en/help/administration/how-to-map-accessorials-for-edi)


# How to Create and Use Load Templates
Source: https://docs.alvys.com/en/help/loads-trips/how-to-create-and-use-load-templates

Build and manage load templates to reuse stops, equipment, and order details for recurring lanes, with view or manage permission controls.

<Note>
  Load templates let you save a reusable set of load details so you can build new loads faster. Users with view access can create loads from a template; users with manage access can also create, edit, duplicate, and delete templates.
</Note>

## Overview

Load templates let you define a standard set of load details once and reuse them every time you need to build a similar load. Instead of entering the same stops, equipment type, and order details from scratch each time, you select a template and fill in only what changes.

The Load Templates page now runs on the same look & feel used everywhere else in Alvys, so filtering, sorting, and column controls work the same way they do on your other pages — and you can save views to jump back to a setup instantly.

Templates are useful for recurring lanes, dedicated customers, or any load type you create frequently.

## Before You Start

You need one of the following permissions to access Load Templates:

* **"ViewLoadTemplates"** — lets you view the Load Templates tab, select a template, and initiate a new load from it.
* **"ManageLoadTemplates"** — lets you do everything **"ViewLoadTemplates"** allows, plus create, edit, duplicate, and delete templates.

<Frame>
  <img alt="Image Displaying Load Templates permissions on a sample user profile" />
</Frame>

*Image Displaying Load Templates permissions on a sample user profile*

If the Load Templates tab is not visible in your navigation, your user account does not have either of these permissions. Contact your administrator to request access.

To navigate to Load Templates: in the left navigation bar, go to **Loads and Trips**, then select **Load Templates**.

## Steps

### Open the Load Templates page and manage the grid

*Requires **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission.*

1. In the left navigation, go to **Loads and Trips** > **Load Templates**.
2. Work with the grid the same way you do everywhere else in Alvys — filter, sort, and manage columns from the column management sidebar.
3. By default the grid opens with an alert/issue indicator, **Customer**, **Template Name**, **Lane** (origin > destination), **Contract**, and **Equipment**. Add columns such as **Created By** or **Last Updated** from the column management sidebar.
   <Frame>
     <img alt="Notion Image" />
   </Frame>

### Saved Views

*Requires the Saved Views permission.*

1. Apply the filters and sorting you want on the Load Templates grid.
2. Save the configuration as a named view.
3. Recall any saved view at any time to return to that exact setup. Saved Views work the same way here as they do on other Alvys pages.
   <Frame>
     <img alt="Notion Image" />
   </Frame>

### Edit, duplicate, or delete a template

*Requires the **"ManageLoadTemplates"** permission.*

1. Go to **Loads and Trips** > **Load Templates**.
2. Find the template you want to change.
3. Click the **…** (more) menu on that template to **edit**, **duplicate**, or **delete** it.
   <Frame>
     <img alt="Notion Image" />
   </Frame>

When you edit a template, it opens in the load creation flow, where you have full visibility and editing capabilities. Modify the details as needed and save. Your changes apply to future loads built from the template — they do not change loads that were already created.

### Create a template from the Load Templates page

*Requires the **"ManageLoadTemplates"** permission.*

1. Go to **Loads and Trips** > **Load Templates**.
2. Click **New Template**.
3. Enter a name that clearly identifies the lane or load type so you can find it quickly later, then fill in the load details you want to save: customer, sales agent, office, billing rate, "Invoice As", stops, schedule type, equipment, order details, and any other fields relevant to your recurring load.
4. Save the template. It will now appear on the Load Templates page for any user with **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission.
   <Frame>
     <img alt="Notion Image" />
   </Frame>

### Create a template while building a load

*Requires the **"ManageLoadTemplates"** permission.*

Work through the manual load creation flow. When you are ready, choose **Save as Template** and **Create load** to create the load and save it as a reusable template. You can also click **Save as Template** at any point in the flow.

<Frame>
  <img alt="Notion Image" />
</Frame>

<Frame>
  <img alt="Notion Image" />
</Frame>

<Frame>
  <img alt="Notion Image" />
</Frame>

### Create loads from a template

*Requires **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission.*

1. Navigate to the manual load creation page and click **From Template** at the top of the page.
2. Select a pre-existing load template.
   <Frame>
     <img alt="Notion Image" />
   </Frame>
3. Review the template details shown in the left side panel.
   <Frame>
     <img alt="Notion Image" />
   </Frame>
4. In the Loads section, enter the pickup date and the quantity of loads to create. You can add additional dates, then click **Generate**.
   <Frame>
     <img alt="Notion Image" />
   </Frame>
5. Enter the **Order Number** for each load. You can also edit the stop start and end times, enter a PO Number, or add additional loads.
   <Frame>
     <img alt="Notion Image" />
   </Frame>
6. Click **Create Loads**. The loads are created and you are taken to the Load Board, filtered to show your new loads.
   <Frame>
     <img alt="Notion Image" />
   </Frame>

## Result

After completing these steps:

* A new or duplicated template is saved and available for all users with **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission to use.
* A saved view is stored so you can return to your preferred filter, sort, and column setup at any time.
* Loads created from a template open pre-filled with the template's details; after generating them you are taken to the Load Board, filtered to your new loads.
* An edited template reflects your changes on all future loads built from it (it does not change loads that were already created).
* A deleted template is removed from the list and can no longer be used to create new loads.

## Troubleshooting

### Load Templates tab is not visible

Confirm you are logged in to the correct account and company. Ask your administrator to verify that your user profile has either the **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission enabled; neither permission will show the tab if both are absent. If the permission is enabled but the tab still does not appear, contact Alvys support.

### Create, edit, duplicate, and delete options are not available

The create, edit, duplicate, and delete actions require the **"ManageLoadTemplates"** permission. If you only have **"ViewLoadTemplates"**, you can view the page and create loads from templates, but you cannot modify, duplicate, or delete templates. Ask your administrator to grant **"ManageLoadTemplates"** if you need full template management access.

## FAQs

**Q: Can I create a load template from an existing load?**

**A:** Yes. While working through the manual load creation flow, click **Save as Template** (or choose **Create load & make template**), enter a name, and confirm. You can also create a template directly from the Load Templates page using **New Template**, or from an existing template using the **…** menu's **Duplicate** option.

**Q: Do changes to a template affect loads that were already created from it?**

**A:** No. Editing a template updates only the template itself. Loads that were previously created from that template are not changed.

**Q: Who can see the Load Templates page?**

**A:** Any user with either the **"ViewLoadTemplates"** or **"ManageLoadTemplates"** permission can see and use the Load Templates page.

**Q: Can I duplicate an existing template instead of creating one from scratch?**

**A:** Yes. On the Load Templates page, open the **…** (more) menu on the template you want to copy and select **Duplicate**, then rename and adjust it as needed.

**Q: Can I save my filters and sorting on the Load Templates page?**

**A:** Yes. Apply the filters and sorting you want, then save them as a named view. Saved Views work the same way here as on other Alvys grids, so you can recall your preferred setup at any time.

## Go Deeper

* [Cloning a Load](/en/help/loads-trips/how-to-clone-a-load): Learn how to copy an existing load to create a new one quickly, which is an alternative approach to reusing load details.


# How to Dispatch a Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-dispatch-a-load

Dispatch a load by assigning a driver, truck, and trailer to advance the trip to Covered status, using the standard flow or preference dialog.

<Note>
  Dispatching a load assigns a driver, truck, and trailer to a trip and advances the trip to **Dispatched** status, signaling the load is ready to move.
</Note>

## Overview

Dispatching a load connects a trip to a driver and equipment so the load can move. Once dispatched, the trip advances to **Dispatched** status, which updates all parties that the load is assigned and ready.

There are two ways to dispatch: the standard flow, where you assign assets and then dispatch in separate steps, and the preference dialog flow, which appears when assignment preferences are configured and lets you assign and dispatch in a single action.

Synonyms: assign a load, cover a trip, send a load, book a driver, schedule a trip, undispatch a load, revert a dispatch, reassign driver after dispatch.

## Before You Start

Before dispatching a load, confirm the following:

* The trip you want to dispatch is in **Open**, **Planned**, or **Covered** status in the trips grid.
* You have a driver, truck, and trailer available to assign.
* All authenticated Alvys users can access Dispatch Planner v2, the Load board, or the load page.
* If you want the preference dialog flow to appear, dispatch preferences must be configured for the driver or carrier in advance.
* The driver you want to assign exists in Alvys under **Assets > Drivers**. If the driver does not appear in the **Manage Assets** assignment field, Alvys will not display an error: add the driver record under **Assets > Drivers** first, then return to dispatch.
* You have permission to access **Manage Assets**. To assign a driver from a load or trip, open the load, then click **Assign Carrier** or **Manage Assets** in the Carrier Details panel on the right side of the screen. If neither button appears, contact your administrator to confirm your account has the required view and assign permissions.

## Dispatch a load from different areas in Alvys

### Dispatch Planner v2

**Open the Dispatch Planner v2 module**

* In the left navigation menu, select the Loads and Trips icon.
* Click **Dispatch Planner v2** from the menu options.

<img alt="The Loads and Trips left navigation menu expanded, showing the 'Dispatch Planner v2' menu item highlighted." />

*The Loads and Trips left navigation menu expanded, showing the "Dispatch Planner v2" menu item highlighted.*

**Find and select the trip**

* In the trips grid, locate the load you want to dispatch. The trip must have a status of **Open** or **Covered** to be available for dispatch.
* Check the checkbox to the left of the trip row. When one or more rows are selected, action icons appear in the toolbar at the top right: **Unassign**, **Dispatcher**, **Priority**, **Find drivers**, and **Dispatch**.
* Click **Dispatch** in the toolbar. The trip advances to **Dispatched** status.

<img alt="The trips grid in Dispatch Planner v2 with an Open load row highlighted." />

*The trips grid in Dispatch Planner v2 with an Open load row highlighted.*

### Load board

**Open the Load board module**

1. In the left navigation menu, select the Loads and Trips icon.
2. Click **Loads** from the menu options.

**Find the load or trip you want to dispatch**

1. In the Loads table, locate the load you want to dispatch. The load must have **Open** or **Covered** status in order to be dispatched.
2. Right-click the selected load or trip row to open the menu and choose **Manage Assets**.

### Load page

Also known as: load screen.

**Find the load in order to open the load page**

1. Use **Global Search** to find the item quickly from anywhere in the system.
2. Alternatively, open it directly from **Dispatch Planner v2**, the **Load board**, **Driver Settlements**, or any **Report**.

**Open the asset assignment panel**

* In the Carrier Details panel on the right side of the screen, click **Assign Carrier** or **Manage Assets** in the bottom left of that panel.

<img alt="The Carrier Details panel with the 'Assign Carrier' button visible in the bottom left corner." />

*The Carrier Details panel with the "Assign Carrier" button visible in the bottom left corner.*

<img alt="The Carrier Details panel with the 'Manage Assets' button visible in the bottom left corner." />

*The Carrier Details panel with the "Manage Assets" button visible in the bottom left corner.*

**Add the driver, truck, and trailer**

* In the asset assignment fields, select the driver for this trip.
* Select the truck.
* Select the trailer.
* Select the Dispatcher.

<img alt="The asset assignment fields showing the driver, truck, and trailer selection dropdowns populated." />

*The asset assignment fields showing the driver, truck, and trailer selection dropdowns populated.*

If no trailer is available for this trip, see Variations below for how to dispatch without a trailer.

**Assign and dispatch the trip**

* Click **Assign** to assign the assets to the trip. The trip advances to **Covered** status, and is not yet dispatched.
* Or click **Assign and Dispatch** to assign and dispatch the trip in a single step.

<img alt="The Assign Carrier form showing the separate 'Assign and Dispatch' and 'Assign' buttons in the action area." />

*The Assign Carrier form showing the separate "Assign and Dispatch" and "Assign" buttons in the action area.*

## Result

After dispatching, the trip status updates to **Dispatched**. This status confirms that a driver and equipment have been assigned and the load is ready to move.

<img alt="The trip details page showing the dispatched load with 'Dispatched' status." />

*The trip details page showing the dispatched load with "Dispatched" status.*

## Variations

### Dispatch using assignment preferences (assign and dispatch in one step)

When assignment preferences are configured for a driver or carrier, Alvys may display an assignment preferences suggestion modal when you open the trip. This modal offers two actions:

* **Assign:** assigns the suggested assets to the trip without dispatching. The trip advances to **Covered** status but is not yet dispatched.
* **Assign and dispatch:** assigns the suggested assets and dispatches the trip in a single step. The trip advances to **Dispatched** status immediately.

<Tip>
  If assignment preferences are configured and a truck is paired with a driver, the truck auto-assigns when you select the driver. You do not need to select the truck separately.
</Tip>

### Dispatch without a trailer

If a trip does not require a trailer or no trailer is currently available:

1. Complete the steps above, leaving the trailer field empty.
2. Click **Assign and Dispatch** to assign and dispatch in a single step.

The trip can be dispatched without a trailer assigned. You can add the trailer to the trip later before the driver departs.

### Sequential Dispatch Enforcement

When Sequential Dispatch Enforcement is enabled for your tenant, Alvys blocks a dispatcher from assigning a driver or truck that already has a trip in **Dispatched** or **In Transit** status. A block message appears naming the conflicting driver or truck and the conflicting trip: the overlap must be resolved before the dispatch can proceed.

Sequential (back-to-back) trips are not affected. The block only fires when the earlier trip is still active. If the first trip is already **Delivered** before the second is dispatched, no conflict is raised.

<Note>
  **What is enforced:** Driver overlap and truck overlap. Both are controlled by a single toggle; there is no separate setting for each.

  **What is not blocked:** Trailer overlap. Trailers are commonly shared across trips (drop-and-hook operations), so a trailer conflict never stops the assignment. You are warned about it instead: see [Equipment conflict warnings](#equipment-conflict-warnings) below.
</Note>

**To enable:** Navigate to **Tenant Settings > Sequential Dispatching** and turn the toggle on. The setting is off by default and only affects tenants who explicitly enable it.

### Equipment conflict warnings

Whenever you assign a trailer or a truck that is already committed to another trip over the same period, Alvys tells you which trip it is on before the assignment goes through. This is a warning, not a block: you can read it and still continue. It appears wherever you assign equipment, including the **Manage Assets** wizard, the pre-assign trailer dialog, the loads board, and both versions of the Dispatch Planner.

Routine pre-planning does not trigger it. If a truck finishes one trip today and starts another tomorrow, that is not a conflict and you see no warning.

**When a warning appears:**

* Only trips in **Dispatched** or **In Transit** status can conflict. Once the earlier trip is marked delivered, it no longer raises a warning.
* Times are compared, not just dates. A delivery at 10:00 AM and a pickup at 2:00 PM the same day is a four-hour gap, and Alvys treats it as one.
* Where a stop actually happened, the real arrival or departure time is compared instead of the scheduled one.
* Boundaries count as an overlap. A trip delivering at 2:00 PM and another picking up at exactly 2:00 PM is flagged.
* An active trip is treated as holding its equipment until at least the present moment. If the earlier trip is still **Dispatched** or **In Transit** past its scheduled delivery, because nobody marked it delivered or it is running late, you get a warning even though the plan said the equipment was free.
* If either trip is missing a date, Alvys shows the warning rather than staying silent about an overlap it cannot rule out.

## Troubleshooting

### Assign and Dispatch buttons are not available

1. Confirm that a driver and truck have been selected in the asset assignment fields. The dispatch action requires at least a driver and truck before it becomes available.
2. Confirm the trip is in **Open** or **Planned** status. Trips in other statuses may not support dispatch from this panel.
3. Check whether another user is editing the same trip simultaneously. If so, wait a moment and refresh the page.
4. If none of the above apply, contact Alvys support with the trip ID and a description of what you are seeing.

### Load does not appear in the trips grid

1. Check whether any column filters are active in the trips grid. Active filters may be hiding trips: clear all filters and check again.
2. Confirm the trip's current status. Trips in statuses other than **Open** or **Planned** may be filtered out of the default grid view.
3. Confirm you are in the correct view within Dispatch Planner v2 and that the correct date range is selected.
4. If the trip still does not appear, contact Alvys support with the load number and the status you expect the trip to be in.

### Trip status did not update after dispatching

1. Refresh the page. Status updates occasionally require a page refresh to display.
2. Confirm you clicked **Dispatch** (not just **Assign**) in the standard flow, or **Assign and dispatch** in the preference dialog flow. Clicking **Assign** alone advances the trip to **Covered** status but does not advance it to **Dispatched** status.
3. Check for any error notification that appeared when you clicked. An error indicates the action did not complete.
4. If the status is still incorrect after refreshing and confirming the correct button was used, contact Alvys support with the trip ID.

### Load belongs to a Brokerage subsidiary and does not appear

Dispatch Planner v2 shows trips for **Carrier** subsidiaries only. Loads created under a **Brokerage** subsidiary, where your company acts as a broker and tenders the load to an external carrier, do not appear in the Dispatch Planner v2 trips grid, but may still be visible on the Loads/Trips board. To assign a carrier and advance the status on a brokerage load, open the load from the Loads/Trips board or the load page, and use the **Manage Assets** dropdown on the load record.

## FAQs

**Q: What is the difference between Assign and Assign and dispatch?**

**A:** **Assign** adds a driver and equipment to the trip and advances it to **Covered** status, but does not dispatch it. **Assign and dispatch** (available in the preference dialog flow) assigns assets and advances the trip to **Dispatched** status in a single step. In the standard flow, you click **Assign** first (trip moves to **Covered**) and then **Dispatch** separately (trip moves to **Dispatched**) to achieve the same result.

**Q: How do I undispatch a load, or change the driver after dispatching?**

**A:** You do not need to cancel the load or revert the dispatch. Alvys lets you reassign the driver, truck, or trailer directly on a dispatched trip without changing its status or load number. To reassign assets after dispatching: open the trip in **Dispatch Planner v2** or from the load page, click **Manage Assets**, update the driver, truck, or trailer fields as needed, then click **Assign and Dispatch** to save. The trip remains in **Dispatched** status and the load number is preserved throughout.

**Q: Can I assign a driver directly from the load screen?**

**A:** Yes. The load screen (also called the load page) supports driver and asset assignment directly. Open the load from the Loads/Trips board, Global Search, or any report, then click **Assign Carrier** or **Manage Assets** in the Carrier Details panel to assign or update the driver, truck, and trailer. See the **Load page** section above for the full steps.

**Q: Is a special role required to dispatch?**

**A:** No special role is required. All authenticated Alvys users have access to Dispatch Planner v2 and can dispatch loads.

**Q: What if the driver or truck is already assigned to another active trip?**

**A:** Whether you are stopped depends on **Sequential Dispatching**, but you are told either way.

If **Sequential Dispatching** is enabled for your tenant, Alvys blocks the dispatch and displays a message naming the conflicting driver or truck and the conflicting trip; you must resolve the overlap before proceeding. The block applies when the driver or truck already has a trip in **Dispatched** or **In Transit** status, and is managed under **Tenant Settings > Sequential Dispatching**.

If Sequential Dispatching is not enabled, the assignment still goes through, but Alvys warns you first and names the trip the truck or trailer is already on, so you can decide whether to continue. See [Equipment conflict warnings](#equipment-conflict-warnings) above. Sequential (back-to-back) trips where the first is fully delivered before the second is dispatched are not affected either way.

## Go Deeper

* [Dispatch Planner overview](/en/help/loads-trips/dispatch-planner)
* [How to Use Bulk Actions in Dispatch Planner](/en/help/loads-trips/how-to-use-bulk-actions-in-dispatch-planner)


# How to lock and unlock a load for editing
Source: https://docs.alvys.com/en/help/loads-trips/how-to-lock-and-unlock-a-load-for-editing

Lock a load to prevent other users from editing it and unlock it when done, or use the UnlockLoads permission to release someone else's lock.

<Note>
  The Lock Load feature lets you temporarily secure a load from other users' edits. Only you, or a user with the “**UnlockLoads**” permission, can release the lock.
</Note>

Locking a load (also called a load lock or locked for editing) prevents other users from making changes to it while you are editing; only the person who locked it, or a user with unlock permission, can release the lock.

## Overview

When you lock a load, all other users see it as read-only until you unlock it. A red **Locked for Editing** tag appears under the load status so your team knows the record is in use. This prevents accidental overwrites when multiple people access the same load at the same time.

\*\*Synonyms: \*\*load lock, lock load, locked for editing, unlock load, release lock.

## Before You Start

* You must have access to the load you want to lock.
* To unlock a load that someone else locked, your account needs the **"UnlockLoads"** permission. Contact your administrator if you need this.
* The lock does not clear when you log out or navigate away; you must unlock the load manually when you are done.

## How to lock a load

1. Open the load.

   * Go to **Loads** in the left navigation.
   * Find and open the load you want to lock.
2. Click the lock icon.

   * In the upper right corner of the load header, select the lock icon (🔒). A tooltip reading "Lock Load" appears when you hover over it.
   * A confirmation dialog appears: "Are you sure? Only you will be able to make changes to the load."
   * Click **Yes** to confirm.
3. Confirm the lock is active.

   * A red **Locked for Editing** tag now appears directly under the load status (for example, under "Open").
   * Other users who open this load will see the tag and will not be able to edit it.

<Note>
  <img alt="The load details page showing a red Locked for Editing tag displayed below the trip status badge in the load header. An arrow points to the tag to highlight its location. The load number, status, and toolbar buttons are visible in the header area." />

  *The load details page showing a red Locked for Editing tag displayed below the trip status badge in the load header. An arrow points to the tag to highlight its location. The load number, status, and toolbar buttons are visible in the header area.*
</Note>

## How to unlock a load

1. Open the locked load.

   * Go to **Loads** and open the load showing the red **Locked for Editing** tag.
2. Click the lock icon again.

   * Select the lock icon (🔒) in the upper right corner of the load header.
   * A confirmation dialog appears: "Are you sure? Other users can make changes to the load."
   * Click **Yes** to confirm.
3. Confirm the lock is released.

   * The red **Locked for Editing** tag is no longer displayed.
   * All users with access to the load can now edit it.

## Result

After locking: the load displays a red **Locked for Editing** tag and only you can make changes. After unlocking: the tag is removed and the load is open for editing by all users with access.

## Variations

**Unlocking a load locked by another user:** If your account has the **"UnlockLoads"** permission, you can unlock any load regardless of who locked it. Follow the same unlock steps above.

## Troubleshooting

### The lock icon is not visible or not available

The lock icon appears in the load header for all users who can open the load details page. If the icon is visible but clicking it does nothing, the load may already be locked by another user and you do not have the **"UnlockLoads"** permission required to override their lock. Contact your administrator to review your role settings.

### The Locked for Editing tag persists after I unlocked it

Refresh the page. If the tag persists, another user may have re-locked the load; check with your team.

## FAQs

**Q: Can another user unlock a load I locked?**

**A:** Only users with the **"UnlockLoads"** permission can unlock a load they did not lock themselves. Standard users cannot override your lock.

**Q: What happens if I try to edit a load that another user has locked?**

**A:** You will see the red Locked for Editing tag and editing fields will be disabled. You will not be able to make changes until the lock is released.

**Q: Does locking a load prevent anyone from viewing it?**

**A:** No. Other users can still open and view the load; they just cannot make changes while it is locked.

**Q: Does my lock stay active after I log out?**

**A:** Yes. The lock does not clear when you log out or close the browser. Return to the load and unlock it manually when you are ready.

## Go Deeper

* [Additional Load Permissions](/en/help/administration/additional-load-permissions)


# How to mark a load as TONU
Source: https://docs.alvys.com/en/help/loads-trips/how-to-mark-a-load-as-tonu

Mark a load as TONU (Truck Ordered, Not Used) to record carrier compensation for a cancelled dispatch and route the load through billing.

<Note>
  A **TONU** (Truck Ordered, Not Used) records carrier compensation when a truck is dispatched but the load is cancelled or the carrier is turned away, and moves the load through the billing process.
</Note>

## Overview

**TONU** stands for Truck Ordered, Not Used. It applies when a carrier is dispatched to a pickup location but the load is cancelled or the carrier is turned away after arrival. Marking a load as **TONU** in Alvys records the agreed compensation for the unused trip and routes the load to billing.

**Synonyms:** truck ordered not used, TONU charge, dry run, deadhead compensation, cancelled load fee.

## Before You Start

* You must have **Dispatcher** or **Billing** permissions to mark a load as **TONU**.
* The load must be in one of these statuses: **Open**, **Covered**, **Dispatched**, or **In Transit**.
* Confirm the **TONU** amount with the carrier before proceeding.

## Steps

**Find the load.**

* Use the **Global Search** bar in the upper right corner to locate the load. You can search by Alvys load number, trip number, or broker order number.
* Double-click the load from the search results to open it.

<Note>
  <img alt="Search bar for locating a load by number or customer name" />

  *Search bar for locating a load by number or customer name*
</Note>

**Mark the load as TONU.**

* Inside the load, click **Manage** in the top-right action bar, then select **TONU** from the dropdown.
* A confirmation dialog appears asking "Are you sure? This cannot be undone." Click **Yes** to confirm. The load status changes to **TONU**.

<Note>
  <img alt="Manage dropdown menu with TONU option highlighted" />

  *Manage dropdown menu with TONU option highlighted*
</Note>

\*\*Enter the TONU amount. \*\*Update the financial data in the Money Box before marking the load as **TONU**. Dispatchers without Billing permissions cannot edit the Carrier Line Haul once the load status changes to **TONU**, so confirm the rates with the carrier before proceeding.

* Select **Customer Freight Amount**, correct the amount the customer or broker pays you, then click **Save**.
* Select **Carrier Line Haul**, correct the amount owed to or from the carrier, then click **Save**.
* Select **Driver Trip Value** (for carriers), correct the amount accordingly, then click **Save**.

<Note>
  <img alt="Money Box panel showing the Customer Rate and Carrier Line haul amount entry field" />

  *Money Box panel showing the Customer Rate and Carrier Line haul amount entry field*
</Note>

**Adjust the stop status.** Alvys does not automatically update stop statuses when a load is marked as **TONU**. You must update the stop status manually so that your records accurately reflect what happened at the pickup location: this is required for accurate billing records and dispatcher reporting. Open the **Stops** section of the load and update the pickup stop status based on what actually happened:

* Change the stop status to **Arrived** if the driver reached the shipper location.
* Leave or change the stop status to **Covered** if the driver did not arrive at the shipper.

<Note>
  <img alt="The Stops section of a load with the pickup stop status field shown, where the status can be set to Arrived or Covered after a TONU." />

  *The Stops section of a load with the pickup stop status field shown, where the status can be set to Arrived or Covered after a TONU.*
</Note>

**Attach supporting documents (optional)**. Upload the revised rate confirmation and any supporting documents so that billing has the paperwork needed to process the load.

* Click **Docs** from the load management ribbon.
* Click the blue **Add a File** button to browse your computer, or drag and drop a file from your desktop into the documents area.
* Select the file type, then click the blue **Upload** button.
* Once the file is uploaded, close the documents panel.

<Note>
  <img alt="Document upload panel for attaching TONU confirmation files e.g. Rate confirmation" />

  *Document upload panel for attaching TONU confirmation files e.g. Rate confirmation*
</Note>

**Release to Billing.**

* Once the financial information is updated and the load status shows **TONU**, release the load. Click **Manage** in the load management ribbon, then select **Release**.
* This sends the load to your accounting and billing team for processing.

<Note>
  <img alt="The Manage dropdown on the load with the Release option, used to send a TONU load to billing." />

  *The Manage dropdown on the load with the Release option, used to send a TONU load to billing.*
</Note>

## Result

* The load is marked as **Released**. The carrier's compensation is saved, and the load moves to the billing queue for processing.

<Note>
  <img alt="The load showing a Released status after a TONU has been released to billing." />

  *The load showing a Released status after a TONU has been released to billing.*
</Note>

## Variations

* **Partial completion:** A **TONU** may not be appropriate if the carrier made a partial pickup. Contact your billing team to determine the correct charge type before proceeding.
* **TONU not available in the Manage menu:** See the Troubleshooting section of this article.

## Troubleshooting

### TONU option is not visible in the Manage menu

1. Check the current load status. **TONU** is only available when the load is in one of these statuses: **Open**, **Covered**, **Dispatched**, or **In Transit**.
2. Confirm you have **Dispatcher** or **Billing** permissions. If you are unsure, contact your administrator.
3. **TONU** is not available on trips that were created by splitting a load. If this trip is part of a split load, **TONU** will not appear in the Manage dropdown. If none of these conditions apply, contact Alvys support.

### TONU amount is incorrect after saving

1. Open the load and review the carrier rate in the Money Box panel.
2. If you have Billing permissions, update the carrier rate directly in the Money Box. If you do not have Billing permissions, contact your billing team to make the correction.

## FAQs

**Q: Can I mark a load as TONU after it has been delivered?**

**A:** No. **TONU** is only available when the load is in one of these statuses: **Open**, **Covered**, **Dispatched**, or **In Transit**. Once a load moves past these statuses, **TONU** is no longer available.

**Q: Does marking a load as TONU automatically notify the carrier?**

**A:** No. You must notify the carrier separately. Alvys records the **TONU** for internal billing purposes only.

**Q: Can a TONU load be reactivated?**

**A:** Yes. Open the **Manage** dropdown on the load and select **Revert Status** to return the load to its previous status. If Revert Status does not appear, billing has already progressed the load past the **TONU** stage. Contact Alvys support in that case.

## Go Deeper

* [How to Release a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)
* [Understanding Load Statuses and How to Revert Them](/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them)
* [Billing Permissions](/en/help/administration/billing-permissions)


# How to Release a Load to Billing
Source: https://docs.alvys.com/en/help/loads-trips/how-to-release-a-load-to-billing

Release a Delivered or TONU load to billing so accounting can generate invoices, one load at a time or in bulk, using the ReleaseLoads permission.

Releasing a load to billing hands off a **Delivered** or **TONU** load to your accounting team so they can generate the invoice and begin post-delivery processing.

## Overview

Once a load is marked as **Delivered**, it must be released to billing before your accounting team can generate the invoice, review charges, and process payment. This step moves the load from dispatch to accounting.

Synonyms: release to billing, release load, send to billing, release for invoicing, hand off to accounting.

## Before You Start

* The load must be in **Delivered** or **TONU** status.
* You must have the **"ReleaseLoads"** permission. Ask your administrator if you do not see the Release option.

## Steps

### Method 1 — Release a single load

1. Open the load.
2. Click **Manage** (top-right of the load).
3. Select **Release**.

   <img alt="Screen recording of opening a load, clicking Manage, and selecting Release" />

   *Screen recording of opening a load, clicking Manage, and selecting Release*

### Method 2 — Release multiple loads at once

1. Go to **Invoicing** in the left navigation.
2. Click the **Incomplete** tab — this shows all Delivered loads not yet released.
3. Select one or more loads.
4. Move the selected loads to the **Released** tab.

<Warning>
  ⚠️ Loads with missing required information cannot be moved to Released until the gaps are filled.
</Warning>

<img alt="Screen recording of bulk-selecting loads on the Invoicing > Incomplete tab and releasing them" />

*Screen recording of bulk-selecting loads on the Invoicing > Incomplete tab and releasing them*

## Result

Released loads appear in the **Released** tab under Invoicing. Your accounting team can immediately review charges, attach documents, and generate the invoice.

## Troubleshooting

### Release option is grayed out or missing

The load may not be in the correct status, or required fields may be incomplete. Confirm: (1) the load status is **Delivered** or **TONU**; (2) all required stops are marked complete; (3) any required documents are attached.

### Load is not showing in the Incomplete tab

Only **Delivered** loads appear here. Check the load status: if it is already released, it will appear in the **Released** tab instead.

### Release option is not visible

Your account does not have the **"ReleaseLoads"** permission. Ask your administrator to assign this permission to your account.

## FAQs

**Q: Can I release a load that isn't delivered yet?**

**A:** No. The load must be in **Delivered** status first.

**Q: Can I undo a release?**

**A:** Yes. Open the load, click **Manage**, and select **Revert Status**. The load returns to its previous status (**Delivered** or **TONU**). Reverting from **Released** also requires the **"ReleaseLoads"** permission.

**Q: Who can release loads to billing?**

**A:** Users with the **"ReleaseLoads"** permission. Ask your administrator to check your account settings if you cannot see the Release option.

## Go Deeper

* Billing Permissions — who can release and invoice loads
* Why Can't I Release or Invoice a Load? — troubleshooting guide
* Understanding Load Statuses and How to Revert Them — if a load isn't in Delivered status


# How to Send the Rate Confirmation to a Carrier
Source: https://docs.alvys.com/en/help/loads-trips/how-to-send-the-rate-confirmation-to-a-carrier

Send carrier rate confirmations from the Tender panel for e-signature, auto-assign driver details, and share preliminary rate cons before finalizing.

Send the rate confirmation to a carrier directly from the Tender panel on the Load Details Page. The carrier receives a secure link to accept or reject and sign the document without needing an Alvys account. Signed confirmations automatically assign driver details to the load and send email copies to both parties.

## Overview

The carrier rate confirmation is the document that formalizes the agreed-upon rate and trip details with the carrier. You send it from the Tender panel on the Load Details Page. The carrier receives a unique secure link and can sign without an Alvys account.

Once the carrier signs, any driver details they provide are automatically applied to the load. Both your organization and the carrier receive an email copy of the signed document.

You can also send a preliminary rate confirmation before all load details are finalized. The preliminary version shows only essential information (lane, rate, equipment type, and commodity) and hides sensitive details like full addresses and exact times.

Synonyms: rate con, carrier rate con, rate confirmation email, send rate confirmation, tender document.

## Before You Start

You need the **"EditCarrierRate"** permission to generate rate confirmations, and the **"SendCarrierRateConEmail"** permission to email them to the carrier.

The load must have a carrier assigned to the trip before you can send the rate confirmation.

## Steps

1. Open the Tender panel. From the Load Details Page, locate the management ribbon and click the **Tender** button.

   <img alt="The Tender button in the management ribbon on the Load Details Page." />

   *The Tender button in the management ribbon on the Load Details Page.*
2. Generate the rate confirmation. In the Tender panel, click the **Generate** drop-down menu and select **Carrier Rate Confirmation**.

   <img alt="The Generate drop-down menu in the Tender panel showing the Carrier Rate Confirmation option." />

   *The Generate drop-down menu in the Tender panel showing the Carrier Rate Confirmation option.*
3. Email the rate confirmation to the carrier. After generating the document, click the option to email it to the carrier. The carrier receives a secure link to view and sign. This link expires 48 hours after it is sent.

## Result

The carrier receives an email with a unique link to their rate confirmation. They can accept or reject it through that link without needing an Alvys account. If they accept and sign:

* The driver details they provide are automatically assigned to the load.
* Both the carrier and your organization receive an email copy of the signed rate confirmation.

## Variations

### Send a preliminary rate confirmation

Use the preliminary rate confirmation to confirm a carrier's interest before all load details are finalized. It shares only the lane (city and state), rate, equipment type, and commodity. Full addresses, exact times, and other sensitive details are hidden.

Once the carrier signs the preliminary version, Alvys automatically generates and emails the full rate confirmation without any additional steps from you.

1. Open the Tender panel from the Load Details Page.
2. Click the **Generate** drop-down and select **Preliminary Carrier Rate Confirmation**.

   <img alt="The Generate drop-down menu in the Tender panel showing the Preliminary Carrier Rate Confirmation option." />

   *The Generate drop-down menu in the Tender panel showing the Preliminary Carrier Rate Confirmation option.*
3. Email the preliminary rate confirmation to the carrier. The carrier receives a link to review and sign. The same 48-hour expiry applies.

## Troubleshooting

### Generate option is not visible in the Tender panel

The Generate controls are only shown to users with the **"EditCarrierRate"** permission. Contact your Admin or Partner Admin to request this permission.

### Email option is not available after generating

Sending the rate confirmation by email requires the **"SendCarrierRateConEmail"** permission. Contact your Admin or Partner Admin if this option is missing.

### Carrier says the link has expired

Rate confirmation links expire 48 hours after they are sent. Return to the Tender panel and generate and send a new rate confirmation.

### Driver details were not applied to the load after the carrier signed

Driver details are applied automatically only when the carrier enters them during the signing step. If the carrier signed without providing driver details, assign them manually on the load.

## FAQs

**Q: Does the carrier need an Alvys account to sign the rate confirmation?**

**A:** No. The carrier receives a unique secure link and signs through that link without needing an Alvys account.

**Q: How long does the carrier have to sign?**

**A:** The link expires 48 hours after it is sent. If the link expires before the carrier signs, generate and send a new rate confirmation.

**Q: What is the difference between the Carrier Rate Confirmation and the Preliminary Carrier Rate Confirmation?**

**A:** The full Carrier Rate Confirmation includes all load and trip details. The Preliminary Carrier Rate Confirmation shows only the lane (city and state), rate, equipment type, and commodity, keeping full addresses and exact times hidden. Use the preliminary version when you want the carrier's commitment before all details are finalized.

## Go Deeper

* [Tenders](/en/help/loads-trips/tenders)
* [Tendering Permissions](/en/help/administration/tendering-permissions)


# How to Set Up Auto-Assign Fleets to Loads
Source: https://docs.alvys.com/en/help/loads-trips/how-to-set-up-auto-assign-fleets-to-loads

Enable auto-assign fleets so Alvys applies the correct fleet to each load based on driver, truck, or trailer, with a default for external carriers.

Configure Alvys to automatically assign the correct fleet to a load based on the truck, trailer, or driver on that load. Set a default fleet for loads covered by external carriers. This setting is configured once and runs automatically on every new load.

## Overview

The Auto-Assign Fleets feature removes the need to manually set a fleet on every load. When enabled, Alvys checks the fleet associated with the truck, trailer, or driver assigned to the load and applies that fleet to the load automatically. You can also designate a default fleet for loads covered by external carriers, ensuring all loads are attributed to a fleet for reporting purposes.

Synonyms: auto-assign fleet, automatic fleet assignment, fleet automation, fleet auto-assign.

## Before You Start

Only users with the **Admin** or **Partner Admin** role can access Management → Fleets and configure this feature.

## Steps

1. Navigate to Management → Fleets. From the main navigation menu, go to **Management**, then click **Fleets**.

   <img alt="The main navigation showing the Management → Fleets path." />

   *The main navigation showing the Management → Fleets path.*
2. Open the Auto-Assign setup. On the Fleets page, locate the "Auto-assign to loads" banner. Click the **Add Automation** button within the banner.

   <img alt="The Auto-assign to loads banner on the Fleets page with the Add Automation button." />

   *The Auto-assign to loads banner on the Fleets page with the Add Automation button.*
3. Select the Asset Fleet matching rule. In the modal that opens, select **Asset Fleet** as the matching rule. This tells Alvys to match the fleet on a load to the fleet of the truck, trailer, or driver assigned to that load.

   <img alt="The modal showing the Asset Fleet matching rule option." />

   *The modal showing the Asset Fleet matching rule option.*
4. Set a default fleet for external carriers (recommended). When a load is covered by an external carrier rather than one of your internal assets, Alvys needs a designated fleet for reporting. In the same modal, select a fleet to use as the default for these loads.

<Info>
  💡 Create a dedicated fleet named "External" or "Brokerage Loads" and select it here.
</Info>

<img alt="The modal showing the default fleet selection for loads covered by external carriers." />

*The modal showing the default fleet selection for loads covered by external carriers.*

1. Save the automation. Click **Save** to confirm your settings. The Fleets page updates to show the automation as active.

   <img alt="The Fleets page showing the Auto-assign automation as active." />

   *The Fleets page showing the Auto-assign automation as active.*

## Result

Once active, every time a truck, trailer, or driver is assigned to a load, Alvys automatically finds the fleet that asset belongs to and applies it to the load. Loads covered by external carriers receive the default fleet you configured.

## Variations

### Disable Auto-Assign

If you need to turn this feature off:

1. Go to **Management → Fleets**.
2. Click **Edit** on the active Auto-assign banner.
3. In the edit screen, click the **Disable** button.
4. Click **Save** to apply the change.

## Troubleshooting

### Fleet was not automatically assigned to a load

Auto-assignment only runs when the assigned asset has a fleet linked to its profile in Alvys. If the truck, trailer, or driver on a load is not assigned to any fleet, auto-assignment cannot run for that asset. Ensure all assets are linked to a fleet in their respective profiles under Assets.

### The wrong fleet was applied to a load

Alvys applies the fleet from the matching asset. If the wrong fleet was applied, the asset may be linked to an incorrect fleet in its profile. Update the asset's fleet assignment, then manually correct the fleet on the affected load.

## FAQs

**Q: Can I manually change the fleet on a load after auto-assignment runs?**

**A:** Yes. Auto-assignment sets the fleet as a starting point. You can manually update the assigned fleet on any load at any time.

**Q: Does this feature apply retroactively to loads created before I enabled it?**

**A:** No. Auto-assign only applies to new assignments made after the feature is activated. Existing loads are not updated.

**Q: What happens if the truck and driver on a load belong to different fleets?**

**A:** Alvys applies the fleet from the first asset it matches. To avoid inconsistencies, ensure the truck, trailer, and driver on each load belong to the same fleet where possible.

## Go Deeper

* [Adding Fleets](/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys)


# How to Show or Hide the Carrier Name on BOLs
Source: https://docs.alvys.com/en/help/loads-trips/how-to-show-or-hide-the-carrier-name-on-bols

Toggle the Remove Carrier Name option in Document Configuration to include or hide the carrier's name and phone number on generated BOLs.

<Note>
  Use the Remove Carrier Name checkbox in Document Configuration to control whether the carrier's name and phone number appear on Bills of Lading (BOLs) generated from your account. The setting is off by default, meaning carrier details are shown. Enabling it hides carrier information from the BOL.
</Note>

## Overview

The **Document Configuration** section in your company profile controls how BOL documents are generated. It replaced what was previously called **Important Information**. One of the options it adds is the **Remove Carrier Name** checkbox, which lets you hide the carrier's name and phone number from the BOL. This is useful when you do not want to display carrier information on documents shared with shippers or other parties.

By default, the **Remove Carrier Name** checkbox is unchecked, meaning the carrier's name and phone number appear on the BOL as usual. Checking it hides those details from all BOLs generated by your account.

Synonyms: hide carrier name, remove carrier name, BOL carrier details, Bill of Lading configuration, document configuration.

## Before You Start

* You must be an **Admin** or **Partner Admin** to access and save Document Configuration settings. The endpoint that saves this configuration requires the **Admin** or **Partner Admin** role (enforced by the CompanyProfileManager policy).
* This setting applies to your account's BOL template. Changing it affects all future BOLs generated; it does not retroactively alter previously generated documents.

## Steps

**Open Document Configuration.**

* Select your username in the bottom-left corner of the screen.
* Navigate to **Management → Company Profile**.
* Locate the **Document Configuration** section on the Company Profile page. This section replaced what was previously called **Important Information**.

  <img alt="The Management → Company Profile page with the Document Configuration section highlighted" />

  *The Management → Company Profile page with the Document Configuration section highlighted*

  **Enable or disable the Remove Carrier Name setting.**
* Inside **Document Configuration**, find the **Bill of Lading** editing area.
* Locate the **Remove Carrier Name** checkbox.
* To hide the carrier's name and phone number from BOLs: check the **Remove Carrier Name** checkbox.
* To show the carrier's name and phone number on BOLs: leave the **Remove Carrier Name** checkbox unchecked (the default state).
* Save the configuration.

  <img alt="The Bill of Lading editing window inside Document Configuration, with the Remove Carrier Name checkbox visible and unchecked (default state)" />

  *The Bill of Lading editing window inside Document Configuration, with the Remove Carrier Name checkbox visible and unchecked (default state)*

## Result

When **Remove Carrier Name** is checked, the carrier's name and phone number are omitted from the carrier section of the BOL. When it is unchecked, the carrier's name and phone number appear on the BOL as usual.

## Troubleshooting

### Document Configuration section is not visible on the Company Profile page

1. Confirm your role is **Admin** or **Partner Admin**. Users with other roles cannot access or modify Document Configuration settings.
2. If your role is correct and the section is still not visible, contact Alvys support.

### Changes to Remove Carrier Name are not saving

1. Confirm you are logged in with an **Admin** or **Partner Admin** role. The save endpoint enforces this role requirement; requests from other roles are rejected.
2. If your role is correct and the save is still failing, contact Alvys support.

## FAQs

**Q: Does the Remove Carrier Name setting affect previously generated BOLs?**

**A:** No. The setting applies to BOLs generated after the change is saved. Previously generated BOL documents are not modified.

**Q: If no carrier is assigned to a load, will the BOL still generate without a carrier name?**

**A:** Yes. The BOL will generate without a carrier name section if no carrier is assigned, regardless of the Remove Carrier Name setting.

**Q: Who can change this setting?**

**A:** Only users with the **Admin** or **Partner Admin** role can access and save Document Configuration settings.

**Q: Where is Document Configuration located?**

**A:** It is on the Company Profile page, reached from Management → Company Profile. It replaced the previous Important Information section.


# How to Switch the Customer on a Released Load
Source: https://docs.alvys.com/en/help/loads-trips/how-to-switch-the-customer-on-a-released-load

Change the customer on a Released load by reverting it to Delivered, updating the customer, and re-releasing it using the ReleaseLoads permission.

<Note>
  You cannot change the customer directly on a **Released** load. To update the customer, you must first revert the load to **Delivered** status, make the change, and then release it again.
</Note>

## Overview

Once a load is in **Released** status, the customer field is locked. This prevents edits to billing records while a load is under accounting review. To swap, replace, or correct the customer, you need to revert the load, change the customer, and re-release it.

## Before You Start

* The load must be in **Released** status.
* You must have the **"ReleaseLoads"** permission to revert and re-release the load. Ask your administrator if you do not see the Revert Status option.

## Steps

1. Revert the load to **Delivered**.

   * Open the load.
   * Click on the **Manage** dropdown menu
   * Select **Revert Status**. The load status changes from **Released** back to **Delivered**.

     <img alt="Image showing “Manage” dropdown menu with “Revert Status” button." />

     *Image showing “Manage” dropdown menu with “Revert Status” button.*
2. Update the customer.

   * On the load record, click the “**Change Customer” button**.
   * Select the correct customer and confirm the change.

     <img alt="Image showing the “Change Customer” button in the load details section." />

     *Image showing the “**Change Customer**” button in the load details section.*
3. Re-release the load.

   * Click **Manage** again.
   * Select **Release**. The load returns to **Released** status and is available to your accounting team.

<Note>
  <img alt="Image showing “Manage” dropdown menu with “Release” button." />

  *Image showing “Manage” dropdown menu with “Release” button.*
</Note>

## Result

The load is back in **Released** status with the updated customer. Your accounting team can continue invoice processing.

### Request Assistance

If you prefer not to adjust the load or trip status yourself, you can get help from our support team:

1. **Use the Chat Bot:**

   Navigate to the chat feature within Alvys and start a conversation with our **chat bot**..
2. **Choose "Talk to a Person":**

Select the **Talk to a person** option to connect with a support representative. They can assist you with updating the customer without altering the load or trip status.

## FAQs

**Q: Can I change the customer directly on a released load without reverting?**

**A:** No. The customer field is locked on **Released** loads. You must revert the load to **Delivered** first.

**Q: Will reverting the load affect my accounting team's work?**

**A:** Reverting moves the load out of **Released** status. Any in-progress invoice steps will need to be restarted after you re-release the load.

## Troubleshooting

### Revert Status is not visible in the Manage menu

* Your account does not have the **"ReleaseLoads"** permission, which is required to revert a load from **Released** status. Ask your administrator to assign this permission to your account.

### Change Customer is not visible after reverting

Confirm the load is now in **Delivered** status. If the load returned to **TONU** status instead, a TONU date was recorded on the load and it reverted to **TONU** rather than **Delivered**.

## Go Deeper

* [How to Release a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)


# How to Upload Documents Using the Mobile App
Source: https://docs.alvys.com/en/help/loads-trips/how-to-upload-documents-using-the-mobile-app

Upload trip documents from the Alvys driver mobile app by selecting a load and document type, then submitting a JPEG, PNG, or GIF file.

<Note>
  Upload trip documents directly from the Alvys driver app by selecting your load, choosing a document type, and submitting a photo or file: keeping paperwork current and ensuring timely driver payment.
</Note>

## Overview

The Alvys driver app makes it easy to submit, send, and attach all trip paperwork as it happens, keeping records current and ensuring drivers get paid quickly. You can upload photos taken in the moment or files already saved on your device. Accepted file formats are JPEG, PNG, and GIF. The maximum file size is 25 MB per upload.

## Before You Start

**Required role:** Driver. This feature is available to drivers only.

Prerequisites before beginning:

* The Alvys driver app is installed on your device (Android 8.0 or later; iOS 15 or later)
* Your driver account is set up and you are signed in
* A trip has been assigned to you
* The document you want to upload is ready: either on your device or available to photograph

Accepted formats: JPEG, PNG, GIF

Maximum file size: 25 MB per file

## Steps

1. Select your load.
2. Open the Alvys driver app and choose the load you want to add documents to from your load list.
3. Go to the **Documents** tab.
4. Inside the load, navigate to the **Documents** tab.
5. Tap the upload button.
6. Tap **Upload** to begin adding a document.
7. Choose Camera or Gallery. Select how you want to provide the document:
8. **Camera:** take a photo of the document using your device camera.
9. **Gallery:** select an existing image or file already saved on your device.
10. Capture the document (Camera only).
11. If you chose Camera, position the document so it is clearly visible in the frame. You may optionally apply a black-and-white filter or keep the original photo. Tap **Done** when finished.
12. Select the document type. Choose the appropriate document type from the list. The available types are:
13. Bill of Lading
14. Proof of Delivery
15. Proof of Pickup
16. Carrier Rate Confirmation
17. Load Manifest
18. Trip Report
19. Temp. Log
20. Scale Ticket
21. Shipping Labels
22. Notice of Assignment
23. NOA (Notice of Assignment)
24. Tap **Upload** to confirm. The document is saved to the load and immediately visible to your team.

<Info>
  💡 NOA and Notice of Assignment are both available as separate selections in the app. They refer to the same underlying document type; select whichever label matches the document you received.
</Info>

## Result

Your document is now uploaded and attached to the load. The office can see it right away. Drivers get paid faster when documents are submitted promptly after each stop.

## Variations

### Uploading multiple documents

Repeat steps 3 through 7 for each additional document. Each document is uploaded individually.

### Uploading from Gallery instead of Camera

At step 4, select Gallery. Browse to the file on your device and select it. Continue from step 6 to assign the document type.

## Troubleshooting

### Upload button not visible

The Upload button appears only when a trip has been assigned to you in the Alvys system. Confirm with your dispatcher that the trip has been assigned to your account. If the trip is assigned and the button still does not appear, check whether an app update is available and install it. If neither of those resolves the issue, contact Alvys support.

### Upload fails or file is rejected

The upload will fail if the file format is not JPEG, PNG, or GIF. The upload will also fail if the file exceeds 25 MB. Check the format and size of the file before retrying. Also confirm you have an active internet connection before uploading.

### App shows device compatibility error

The Alvys driver app requires Android 8.0 or later, or iOS 15 or later. Rooted or jailbroken devices are not supported. If your device does not meet these requirements, the app may not function correctly. Upgrade your device's operating system if an update is available.

## FAQs

**Q: Can I upload documents after the trip is completed?**

**A:** Yes. You can upload documents to a load after the trip is completed as long as the load remains accessible in your app. Contact your dispatcher if a load you need to add documents to is no longer visible.

**Q: What types of documents can I upload?**

**A:** You can upload Bill of Lading, Proof of Delivery, Proof of Pickup, Carrier Rate Confirmation, Load Manifest, Trip Report, Temp. Log, Scale Ticket, Shipping Labels, Notice of Assignment, and NOA.

**Q: Does the office see the document immediately?**

**A:** Yes. Once you tap Upload and the upload completes, the document is immediately visible to your team in the Alvys system.

**Q: Is there a way for a driver to upload a PDF file from their phone in the app?**

**A:** No — right now the app only supports scanning documents or selecting photos. There's no option for a driver to upload an existing PDF file directly.

**Q: What if I selected the wrong document type?**

**A:** Contact your dispatcher. Once a document type is selected and uploaded, it cannot be changed in the app. Your dispatcher can correct the document type from the back office.

## Go Deeper

* [How to Use the Driver Companion Mobile App](/en/help/assets-fleet/driver-companion-mobile-app)


# How to Use Bulk Actions in Dispatch Planner
Source: https://docs.alvys.com/en/help/loads-trips/how-to-use-bulk-actions-in-dispatch-planner

Apply operations to multiple trips at once in Dispatch Planner — bulk assign, dispatch, unassign, change dispatcher, and set priority across any selection of trips.

<Note>
  Bulk Actions lets planners select multiple trips in the Trips table and apply an operation to all of them at once — turning an hours-long manual process into a two-click workflow.
</Note>

## Overview

Bulk Actions is available to all Dispatch Planner users at no additional cost. Six operations are supported:

\| cells |

\|---|

\| cells |

\| cells |

\| cells |

\| cells |

\| cells |

\| cells |

## Before You Start

Before using Bulk Actions, confirm the following:

* You have access to **Loads and Trips > Dispatch Planner v2**. All authenticated Alvys users can access Dispatch Planner v2.
* The trips you want to act on are visible in the Trips table and are in a status eligible for the operation you intend to apply (see the table in Overview above).

## How to Use Bulk Actions

### Select trips

1. Navigate to **Loads and Trips > Dispatch Planner v2**.
2. In the Trips table, select trips using the checkbox column:
3. Click a checkbox individually to select a single trip.
4. Shift-click a second checkbox to select all trips in the range between the two.
5. Click the checkbox in the column header to select all trips on the current page.

### Apply an operation

1. Once trips are selected, a bulk action header appears above the Trips table. Click the **Actions** menu in that header.
2. Choose the operation you want to apply.
3. Confirm in the modal. Bulk Actions applies the change to every selected trip.

### Using Bulk Actions with Find Drivers

When choosing **Find Drivers**, a driver selection table appears at the bottom of the screen.

1. Select a driver from the bottom table.
2. Take the assignment action from the side panel.
3. The action applies to all selected trips at once.

## Result

After the operation runs, a success or failure toast appears at the bottom of the screen. If the operation failed for some trips but not others, the toast shows per-trip detail so you know exactly what went through and what did not.

## FAQs

**Q: Who has access to Bulk Actions?**

**A:** All users with Dispatch Planner v2 access. There is no additional cost and no special role required.

**Q: Can I select trips across multiple pages?**

**A:** The select-all checkbox in the column header selects all trips on the current page. To act on trips across pages, apply the operation page by page or use column filters to narrow the Trips table to the set you want to act on.

**Q: What happens if an operation fails for some trips but not others?**

**A:** The result toast shows per-trip detail for partial failures. Successfully updated trips keep their new status; trips that failed are unchanged.

**Q: Why doesn't an operation appear in the Actions menu?**

**A:** Operations are shown based on the eligible statuses of your selected trips. If the trips you have selected are not in a status that supports a given operation, that operation will not appear. Check that the selected trips are in the correct status for the action you want to take (see the Overview table above).

## Go Deeper

* [Dispatch Planner overview](/en/help/loads-trips/dispatch-planner)
* [How to Dispatch a Load](/en/help/loads-trips/how-to-dispatch-a-load)


# How to Use Intel
Source: https://docs.alvys.com/en/help/loads-trips/how-to-use-intel

Intel gives real-time risk and event intelligence tied directly to your trips and lanes — so you see disruptions before they cost you time or money.

### What Intel does

Intel continuously monitors for events that can impact your freight, including:

* Cargo theft and hijackings
* Severe weather (hurricanes, floods, winter storms, high winds)
* Accidents and roadway incidents
* Road, rail, and port closures or disruptions
* Facility outages and hazmat incidents

When an event overlaps your active trips, Intel surfaces it automatically — no setup, no manual searching.

### Where to find Intel

### 1. Asset Map

Risk events show as a live signal layer over your active trips on the Asset Map. Open a trip marker to see nearby alerts and how they relate to the route.

### 2. Trip sidebar — Risk Alerts tab

Open any trip and select the **Risk Alerts** tab to see events impacting that specific load — location, type, and relevant detail.

### 3. Ask AI (Insights)

Ask natural-language questions like:

* "Show me my trips at risk"
* "Are there any alerts on trip #12345?"
* "What's happening near \[lane/city]?"

Insights returns a prioritized list of affected trips with a summary and recommendation for each.

### Availability

Intel is included free for all Insights customers. It's on by default — nothing to enable.

### FAQ

**Do I need to configure anything?**
No. Intel runs automatically against your active trips.

**Can I filter which alert types I see?**
Filtering options are on the roadmap; not available at initial launch.

**Where does the data come from?**
Intel draws on a broad, continuously updated set of public risk and event signals — not carrier or load data you haven't shared with Alvys.

**Does this replace my carrier's tracking/ELD data?**
No — Intel is a risk-awareness layer on top of your existing tracking, not a replacement for it.


# Load Board Region Filters
Source: https://docs.alvys.com/en/help/loads-trips/load-board-region-filters

Filter and sort the Load Board by DAT origin and destination regions and markets to plan freight by geographic boundaries without external tools.

<Note>
  The Load Board includes four region and market filter columns (Origin Region, Origin Market, Destination Region, and Destination Market) that let you filter, sort, and plan loads by DAT-defined geographic boundaries directly within the load board grid, without using external tools.
</Note>

## Overview

The Load Board Region Filters let you narrow, refine, and segment the load board to loads and trips matching specific geographic regions or markets at the origin or destination. Regions and markets are based on DAT shape files, a standard geographic reference used across the trucking industry.

The four filter columns are:

* **Origin Region**: the DAT region where the load originates
* **Origin Market**: the DAT market where the load originates
* **Destination Region**: the DAT region where the load is delivered
* **Destination Market**: the DAT market where the load is delivered

If a load or trip spans multiple regions or markets, all applicable values appear as a comma-separated list in the column.

## Where to Find It

Navigate to **Loads and Trips**, then open the **Load Board**. The four columns (**Origin Region**, **Origin Market**, **Destination Region**, and **Destination Market**) appear in the load board grid.

Each column supports two filter modes:

* Free-text search: type a region or market name to narrow results
* Set filter picker: select one or more predefined values from a multi-select list

<Note>
  📷 **IMAGE:** Screenshot showing the four region and market filter columns in the load board grid.

  <img alt="Notion Image" />
</Note>

## Key Concepts

### DAT Regions

DAT regions are predefined geographic groupings of US states and Canadian provinces, defined by zip code ranges and postal prefixes. There are 18 DAT regions: New England, Upper Atlantic, Lower Atlantic, Carolinas, Florida-So Georgia, Southeast, Ohio River, Great Lakes, Upper Midwest, Lower Midwest, South Central, Lower Mountain, Upper Mountain, California, Pacific Northwest, Canada East, Canada Central, and Canada West.

### DAT Markets

DAT markets are more granular geographic areas within regions, typically centered on a metropolitan area or freight hub. There are 149 DAT markets.

## Settings & Permissions

All authenticated users have access to the **Origin Region**, **Origin Market**, **Destination Region**, and **Destination Market** columns in the load board. No additional role or permission is required to view or use these filters.

## Limits & Behavior

* Region and market values are assigned automatically based on the zip codes of the load's origin and destination stops. You cannot manually set or override a region or market on a load.
* If a load or trip spans multiple regions or markets, all applicable region or market names appear in the column as a comma-separated list.
* Region and market values are blank when the load's origin or destination zip code does not fall within any DAT-defined boundary. This can occur for loads with incomplete address data or for locations not covered by the DAT shape file dataset.
* The filter picker for each column displays only the predefined DAT values. Free-text search within the filter also matches against those same predefined values.

## FAQs

**Q: Why is the Region or Market column blank for some loads?**

**A:** A blank value means the origin or destination zip code on that load does not match any DAT-defined region or market boundary. This typically occurs when the stop address is incomplete or when the zip code falls outside the geographic areas covered by the DAT shape file dataset. Verify that the origin and destination addresses on the load have valid zip codes. If the addresses are correct and the column remains blank, contact Alvys support.

**Q: Can I manually set a region or market on a load?**

**A:** No. Region and market values are assigned automatically based on the zip codes of the load's origin and destination stops. There is no option to manually enter or override these values.

**Q: Why does a load show multiple regions in one column?**

**A:** When a load has stops in more than one DAT region or market, all applicable values are listed together in the column, separated by commas.

**Q: Which users can see these filters?**

**A:** All authenticated users in your organization can see and use these filter columns. No special role or permission is required.

## Go Deeper

* [Alvys Load Board](/en/help/loads-trips/alvys-load-board)


# Loads stay under company driver after status change
Source: https://docs.alvys.com/en/help/loads-trips/loads-stay-under-company-driver-after-a-driver-s-status-changes-to-owner-operator

Fix loads that stay under the wrong Pay Drivers tab after a company driver becomes an owner operator (or vice versa) by reassigning the driver.

<Note>
  When a driver's status changes from Company Driver to Owner Operator (or the reverse), existing loads do not automatically move to the new driver type tab in Pay Drivers. Reassigning the driver to the load resolves this.
</Note>

## Symptom

After changing a driver's status from **Company Driver** to **Owner Operator** (or the reverse), their previously assigned loads still appear under the original driver type tab in the Pay Drivers module. The loads do not move to the new tab automatically.

## Cause

When a driver is assigned to a load, Alvys records the driver's type at the time of assignment. This record is stored as a snapshot on the load and is not updated retroactively when the driver's status changes later. Existing loads remain categorized under the driver type that was active at the time they were assigned.

## Resolution

1. Open the load that is appearing under the wrong driver type tab.
2. Reassign the driver. Click Manage Assets.

<Note>
  <img alt="Image showing “Manage Assets” button in Carrier Details section on load details page." />

  *Image showing “**Manage Asset**s” button in **Carrier Details section on load details page.***
</Note>

1. Confirm the update.

   * The load now reflects the driver's current status and moves to the correct tab in Pay Drivers.

## If That Didn't Work

### A settlement statement has already been processed for this load

If a settlement statement has already been processed, the assignment cannot be updated until the statement is reverted. Open the **Pay Drivers** module, locate the statement for that load, and click **Revert this statement back to draft**. Then repeat the reassignment steps above.

If you have completed all the steps above and the load still does not appear under the correct tab, contact Alvys support.


# Managing a Load
Source: https://docs.alvys.com/en/help/loads-trips/managing-a-load

Understand the Manage dropdown and action buttons on a load, including Map, Notes, Docs, and status controls that change with each stage.

<Note>
  A load record in Alvys includes a set of management controls for tracking progress, uploading documents, and taking workflow actions at each stage of the freight lifecycle.
</Note>

### Overview

Every load in Alvys has a row of action buttons and a **Manage** dropdown that control, govern, and adjust what you can do at each stage. The available options change based on the load's current status and your account permissions. This article explains what each control does.

### Where to Find It

Open any load record. The action buttons appear in the management ribbon just below the carrier details panel. The **Manage** button at the top of the load opens a dropdown with status and workflow actions.

<img alt="Load management ribbon with action buttons and the Manage dropdown" />

### Key Concepts

#### Map

Opens a visual map of the load's route and stop locations so you can review the planned path.

#### Notes

Lets you add free-form internal notes to the load record. Notes are visible to other users on your account but are not sent to the carrier.

#### Docs

Opens the documents panel where you can view and upload load-related files such as the rate confirmation and proof of delivery.

#### Check Calls

Records a driver check-in update for the load, including location and status notes.

#### Add Stop

Inserts an additional stop into the trip route. This option is only available while the load has not yet reached **Delivered** or **TONU** status. Once the load is delivered, the stop list is locked. If you need to add or modify a stop after delivery, contact Alvys Support.

1. Open the load record.
2. Click **Add Stop** in the management ribbon.
3. Enter the stop details, including the location address, stop type, and scheduled time window.
4. Click **Save** to insert the stop into the route.

#### Tender

Accesses bill of lading and load manifest features for the trip.

#### Optimize

Rearranges stop order or initiates a trip split to adjust the route.

#### Manage

Opens a dropdown menu with status and workflow actions. The options shown depend on the load's current status and your account permissions. Common actions include Dispatch, Release, TONU, Reserve, Revert Status, Clone, and Cancel Load.

#### Clone

Creates a copy of the load with the same route and carrier information. Document attachments are not copied to the new record.

1. Open the load you want to copy.
2. Click **Manage** on the Load Management ribbon.
3. Select **Clone** from the dropdown.
4. The new load opens pre-filled with the original route and carrier. Update any fields as needed, then save.

#### Reserve

Places the load in **Reserved** status. This option is only available when the load is in **Open** status. It does not appear once the load has advanced to **Covered**, **Dispatched**, **In Transit**, **Delivered**, or any other later stage.

1. Open the load record.
2. Click **Manage** on the Load Management ribbon.
3. Select **Reserve** from the dropdown.
4. Confirm when prompted. The load status updates to **Reserved**.

#### Revert Status

Returns the load to **Delivered** status. This option is available only when the load is in **Released** or **Queued** status, and it is not available if the trip status is **Completed**.

1. Open the load record.
2. Click **Manage** on the Load Management ribbon.
3. Select **Revert Status** from the dropdown.
4. Confirm the revert when prompted. The load returns to **Delivered** status.

#### Cancel Load

To cancel a load in Alvys:

1. Open the load you want to cancel.
2. Click **Manage** at the top of the load.
3. Select **Cancel Load**.
4. Confirm the cancellation when prompted.

A few important notes:

* A cancelled load cannot be restored. If the load is needed again, create a new load or clone the cancelled one.
* The option may depend on the load's current status and your permissions.
* Operational loads should generally be cancelled, not deleted. Only training or test loads may be eligible for deletion, depending on the case.
* If the load is already invoiced, released, factored, or tied to a batch, it may need to be reverted first before it can be cancelled.

For the full set of status-by-status steps, see [How to Cancel Loads in Alvys](/en/help/loads-trips/how-to-cancel-loads-in-alvys).

### How to Use It

For step-by-step instructions on specific actions available from this screen, see:

* [How to Release a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)
* [How to Switch the Customer on a Released Load](/en/help/loads-trips/how-to-switch-the-customer-on-a-released-load)

### Settings & Permissions

The **Manage** dropdown shows only the actions your account is permitted to take at the load's current status. For example, **Release** appears only if you have the **"ReleaseLoads"** permission and the load is in **Delivered** or **TONU** status. Contact your administrator if an expected action is not visible.

### Limits & Behavior

* **Add Stop** is not available after a load reaches **Delivered** or **TONU** status. Once a load is delivered, the stop list is locked.
* **Tender** availability varies depending on the load type and carrier setup.
* **Clone** creates a new load with the same route and carrier information but does not copy document attachments.
* **Cancel Load** removes the load from active dispatch. A cancelled load cannot be restored; a new load record must be created.

### FAQs

**Q: Why don't I see all the options listed under Manage?**

**A:** The Manage dropdown shows only the actions that are valid for the load's current status and your account's permissions. If an option is missing, either the load's status does not allow that action, or your account does not have the required permission.

**Q: Can I add a stop after the driver has picked up?**

**A:** Yes, as long as the load has not yet reached **Delivered** or **TONU** status. Once a load is delivered or marked TONU, the route is locked.

**Q: How do I revert a load's status from Released back to Delivered?**

**A:** Click **Manage** on the Load Management ribbon and select **Revert Status**. This option is available when the load is in **Released** or **Queued** status and the trip is not marked **Completed**.

### Go Deeper

* [How to Release a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)
* [How to Switch the Customer on a Released Load](/en/help/loads-trips/how-to-switch-the-customer-on-a-released-load)

## Marking a Load as TONU

If a load is canceled after being assigned but before delivery, you may need to mark it as **TONU** (Truck Ordered Not Used).

### Steps to Mark as TONU

1. Open the load via the Global Search bar (by load #, trip #, or broker order #)
2. Click **Manage** on the Load Management ribbon
3. Select **TONU** from the dropdown
4. Confirm when prompted

<Note>
  💡 TONU is only available for loads with assets assigned and not yet delivered. The load must be in statuses like Covered, Dispatched, or In Transit.
</Note>

<img alt="Marking a load as TONU from the Manage dropdown" />

### Adjust Stop Status

Update the stop status depending on what occurred in real life. To change a stop status, go to each stop (pickup or delivery) and click the downward arrow on the right side of the location title and address:

* **Arrived** if the driver reached the shipper
* **Picked Up** if the driver has loaded and is ready to depart. This moves the load to **In Transit** status.
* **Empty** for the delivery location. Marking the delivery location as empty moves the load to **Delivered** status.

### Update Money Box

* **Update Customer Rate** – adjust the customer-facing amounts, including Line Haul, Fuel Surcharge, and the total Freight Amount / Total Billable.
* **Update Carrier Rate** – adjust the Carrier Line Haul amount, which determines the carrier Payable.
* **Update Owner Operator / Driver Payables** – adjust the Trip Value or other payable rates for the driver or owner operator.

### Release to Billing

Once all updates are made and the load shows TONU status, click **Manage** again and choose **Release** to hand it off to your billing team.

## FAQs

**Q: What happens to loaded miles when a load is marked as TONU?**

A: Loaded miles are automatically zeroed out since the trip wasn’t completed.

**Q: Can I mark a load as TONU after delivery?**

A: No. TONU can only be applied before the load is marked delivered.


# Mileage Sources and Types
Source: https://docs.alvys.com/en/help/loads-trips/mileage-sources-and-types

Configure Customer and Dispatch mileage sources on a load to control invoicing, driver settlement pay, and automatic route recalculation.

<Note>
  Alvys tracks two types of mileage on every load: Customer mileage used for invoicing and Dispatch mileage used for driver settlements. Each type can be set to one of several sources that determine where the mileage value comes from and whether it recalculates automatically when the route changes.
</Note>

## Overview

Mileage in Alvys controls two separate billing streams. Customer mileage determines what appears on the customer invoice. Dispatch mileage is split per trip into Loaded Miles and Empty Miles and determines what drivers are paid.

Getting the right mileage source on each load ensures accurate invoices, correct driver settlements, and reliable reporting.

## Where to Find It

Mileage fields appear on the Load Details Page in the Stops section. Each stop row shows the calculated or entered mileage.

Customer mileage is visible on the invoice preview and the load header details. Dispatch mileage per trip is shown in the Trips section of the load.

<Note>
  <img alt="Load Details Page showing Customer mileage and Dispatch mileage fields in the Stops section." />

  * Load Details Page showing Customer mileage and Dispatch mileage fields in the Stops section.\*

    <img alt="Notion Image" />
</Note>

## Key Concepts

### Mileage Types

Alvys uses two mileage types on every load.

**Customer mileage** is the total miles used for customer invoicing. It appears on the customer invoice and rate confirmation. It is a single value for the full load.

**Dispatch mileage** is used for driver settlements. It is tracked per trip and is split into two components: Loaded Miles (miles driven while carrying cargo) and Empty Miles (miles driven without cargo, such as deadhead between trips).

### Mileage Sources

The source determines where the mileage value comes from. Available sources differ by mileage type.

**Automatic** (available for both Customer and Dispatch mileage): The mileage engine calculates miles based on the current stop addresses. If stops are added, removed, or reordered, Automatic mileage recalculates. This is the recommended source for most loads.

**Manual** (available for both Customer and Dispatch mileage): You enter the mileage value directly. Manual mileage does not recalculate when stops change. A notification is shown to remind you that the mileage is user-entered and will not update automatically.

**Customer Contract** (available for Customer mileage only): Mileage is pulled from the contracted lane rate on the customer profile. This source is used when the customer has a lane rate contract with a defined mileage. Mileage does not recalculate when stops change. A notification is shown.

**Customer Tender** (available for Customer mileage only): Mileage is pulled from the EDI tender transmitted by the customer. This source is only available when the EDI Tenders integration is active for the customer. Mileage does not recalculate when stops change. A notification is shown.

### Mileage Engines

When the source is set to Automatic, one of the following mileage engines calculates the route distance.

**PCMiler** is the default mileage engine in Alvys. It calculates commercial truck routing distances. Most loads will use PCMiler unless a different engine has been configured.

**HereMaps** is an alternate routing engine available as a configuration option.

**Google Maps** is an alternate routing engine available as a configuration option.

**MileMaker** is an alternate routing engine available as a configuration option.

The active engine is set by your Alvys administrator and applies tenant-wide. Contact your administrator if you need to confirm or change the mileage engine in use.

<Note>
  <img alt="Global Settings where admin can create and edit Mileage Profiles for both customer and dispatch mileage." />

  \*Global Settings where admin can create and edit Mileage Profiles for both customer and dispatch mileage. \*
</Note>

### Mileage Notifications

When Customer or Dispatch mileage is set to any source other than Automatic, Alvys displays a notification on the load to alert dispatchers and billing users that the mileage is fixed and will not recalculate.

This notification appears near the mileage fields on the Load Details Page. It is informational and does not block any actions.

## Settings and Permissions

Viewing mileage on a load is available to all authenticated Alvys users. No additional permission is required to see mileage values.

Editing mileage (changing the source or entering a manual value) requires permission to edit the load. No separate mileage-specific permission is required.

<Note>
  <img alt="Permission to edit miles" />

  *Permission to edit miles*
</Note>

### Customer Mileage Source Priority

When a new load is created, Alvys determines the default Customer mileage source in the following order:

1. The mileage source configured on the customer's profile in Alvys.
2. The tenant-wide default mileage source configured in Tenant Management settings.
3. The system default: Automatic using PCMiler.

If a customer profile has a mileage source configured, that source takes precedence over the tenant-wide setting.

<Note>
  <img alt="Customer profile mileage source setting in the Companies module." />

  *Customer profile mileage source setting in the Companies module.*
</Note>

<Note>
  <img alt="Tenant Management mileage default settings panel." />

  *Tenant Management mileage default settings panel.*
</Note>

### Dispatch Mileage Sources

Dispatch mileage supports Automatic and Manual sources only. Customer Contract and Customer Tender are not available for Dispatch mileage.

## Limits and Behavior

* Customer mileage sources: Automatic, Manual, Customer Contract, Customer Tender.
* Dispatch mileage sources: Automatic and Manual only.
* Automatic mileage recalculates whenever stops are added, removed, or reordered.
* Manual, Customer Contract, and Customer Tender mileage do not recalculate on route changes.
* Editing a trip's previous stop recalculates Empty Miles on every trip, whatever the trip's dispatch mileage source is. The recalculated value appears as soon as you save, with no page reload. If the mileage lookup fails, Empty Miles is cleared rather than left at the old figure, so a blank means "not yet calculated" rather than zero. Re-save the previous stop to try again.
* A dispatch mileage value you entered by hand is still never overwritten by an automatic recalculation. Only the previous-stop leg behind Empty Miles is recomputed.
* The default mileage engine is PCMiler.
* Changing the tenant-wide mileage engine affects all new loads; existing loads are not retroactively updated.
* Customer Tender mileage source is only available when the EDI Tenders integration is active.

## FAQs

**Q: Why does my Customer mileage show a notification and not recalculate when I update stops?**

**A:** The mileage source is set to Manual, Customer Contract, or Customer Tender. These sources are fixed values that do not recalculate automatically. To have mileage recalculate, change the source to Automatic.

**Q: I changed the previous stop on a trip. Why are Empty Miles blank now?**

**A:** A blank means the mileage lookup did not return a distance for the new previous stop, so Alvys cleared the value instead of leaving the old, now-wrong figure in place. Check the previous stop's address and re-save it to recalculate. A blank is never the same as zero miles.

**Q: Which mileage engine does Alvys use by default?**

**A:** PCMiler is the default mileage engine. It calculates commercial truck routing distances. Administrators can configure an alternate engine in Tenant Management settings.

**Q: Can I set different mileage engines for Customer mileage and Dispatch mileage?**

**A:** The mileage engine is a tenant-wide setting. It applies to all Automatic mileage calculations, both Customer and Dispatch.

**Q: How do I make a customer always use a specific mileage source by default?**

**A:** Configure the mileage source on the customer's profile in the Companies module. That setting overrides the tenant-wide default for any load created for that customer.


# Mileage to Next Stop
Source: https://docs.alvys.com/en/help/loads-trips/mileage-to-next-stop

Track real-time miles from a truck's last GPS location to the next stop on the Load Details page and Dispatch Planner v2's dedicated column.

<Note>
  Alvys calculates the miles from a load's last known GPS location to its next scheduled stop and displays this in two places: the Location Tracking section on the Load Details page, and the Miles to Next Stop column in Dispatch Planner v2.
</Note>

## Overview

Mileage to Next Stop shows how far a truck currently is from its next scheduled stop, based on its last known GPS location. Dispatchers use this to monitor load progress, prioritize attention on loads approaching a stop, and filter the Dispatch Planner by remaining miles.

The value appears in two places:

* The Location Tracking section of a load's trip card on the Load Details page
* The Miles to Next Stop column in Dispatch Planner v2 (DPv2)

## Where to Find It

**On the Load Details page:**

Open any load in Loads and Trips. In the trip card, scroll to the Location Tracking section. The Mileage to Next Stop field shows the current distance to the next stop in miles, alongside Last Updated, Last Location, Next Stop, and Next Stop ETA.

The Mileage to Next Stop field only appears when a GPS ping has been received for the trip's assigned driver or truck. If no GPS data is available, the field is not shown.

**In Dispatch Planner v2:**

Navigate to Dispatch Planner ( [https://app.alvys.com/dispatch-planner](https://app.alvys.com/dispatch-planner)). The Miles to Next Stop column is available in the trips grid. The column can be sorted and filtered by mileage range; for example, filtering to show only trips within 50 miles of their next stop.

<Note>
  <img alt="Image showing “Miles to Next Stop” Column on Dispatch Planner" />

  *Image showing “Miles to Next Stop” Column on Dispatch Planner*
</Note>

## Key Concepts

**GPS-based calculation:** Mileage to Next Stop is calculated from the truck's last known GPS location to the coordinates of its next scheduled stop. The calculation depends on GPS pings being received from the driver's ELD or tracking integration; if no ping has been received, no value is shown.

**Location Tracking section:** The section of the trip card on the Load Details page that displays real-time GPS data, including the last updated timestamp, last known address, next stop name, next stop ETA, and Mileage to Next Stop.

<Note>
  <img alt="Location Tracking section on the Load Details page showing the Mileage to Next Stop field." />

  *Location Tracking section on the Load Details page showing the Mileage to Next Stop field.*
</Note>

**Miles to Next Stop column (DPv2):** An optional column in the Dispatch Planner v2 trips grid. It is sortable and filterable by mileage range.

## How to Use It

For how to sort and filter by Miles to Next Stop in Dispatch Planner v2, see the Dispatch Planner help article ([Dispatch Planner](/en/help/loads-trips/dispatch-planner)).

## Settings and Permissions

No additional settings or permissions are required. Any authenticated user with access to the Load Details page or Dispatch Planner v2 can see this data when GPS location information is available for the trip.

## Limits and Behavior

* The Mileage to Next Stop field on the Load Details page only appears when a GPS ping has been received. It is not shown if GPS tracking has not returned a location.
* The Miles to Next Stop column in Dispatch Planner v2 is blank for trips without active GPS data.
* The update frequency depends on the ELD or tracking integration in use and is set by the integration provider.
* Mileage to Next Stop reflects distance to the next scheduled stop, not the final destination.

## FAQs

**Q: Why is the Mileage to Next Stop field not showing on my load?**

**A:** The field only appears when a GPS ping has been received for the assigned driver or truck. Verify that the driver's ELD integration is active and connected. If the integration is active and the field is still missing, contact Alvys support.

**Q: Why does the Miles to Next Stop column show a blank value in Dispatch Planner v2?**

**A:** A blank value means no GPS location data has been received for that trip. The column only displays a value when an active GPS ping is available for the assigned driver or truck.

**Q: What does "next stop" mean?**

**A:** Next stop refers to the next scheduled pickup or delivery stop on the trip that has not yet been departed.


# Mileage Troubleshooting
Source: https://docs.alvys.com/en/help/loads-trips/mileage-troubleshooting

Mileage Troubleshooting

**Q: Can I use different Mileage Profiles for different customers?**

**A:** Yes. Mileage Profiles can be assigned per customer in the Customer Profile, overriding the tenant default. Create a separate profile for each customer that requires unique routing parameters or a specific PC Miler version.

**Q: Where do I create and manage Mileage Profiles?**

**A:** Click the person icon in the lower-left corner of any page, select Settings, and navigate to Mileage Profiles. From there you can create, name, configure, and delete profiles.


# Optimize - Split Trips & Rearrange Stops
Source: https://docs.alvys.com/en/help/loads-trips/optimize-split-trips-rearrange-stops

We’ve increased the trip split limit from 5 to 20, giving you greater control over how trips are structured within the Load Details Page

<Info>
  👤 User roles with access: Dispatchers, Load Planners, and Admins
</Info>

## Summary

The **Split Trip** feature in Alvys enables you to divide a single load’s journey into multiple distinct trips. This is especially useful when a load requires a change of assets—such as a different driver, truck, or trailer—at an intermediary point, or when a complex route needs to be broken into manageable, traceable segments. Each resulting trip has its own origin and destination, allowing for independent dispatching and tracking of every segment. This streamlines management and provides greater operational control, even for the most intricate routes.

## Step-by-Step Instructions

### Open Optimize Modal

To begin, open the specific load for which you want to split a trip. This page is referred to as the Load Details page. Here you can see the current breakdown of stops, such as one pickup and one delivery.

In the "Trips / Stops" section of the Load Details Page you can see the current breakdown of stops, such as one pickup and one delivery. Above or below all the stops, locate and click the **"Optimize"** button. The 'Optimize' button also allows you to rearrange the sequence of deliveries within a trip, providing flexibility in managing delivery schedules.

<Note>
  <img alt="Notion Image" />
</Note>

### Enter Address

<Note>
  <img alt="Notion Image" />
</Note>

Within this modal, click the **"Split"** option.

Next, enter the location where the trip will be split so that an asset change .

**Enter the Split Point Address:**

* You need to enter the exact address where the trip will be split. This is the intermediary stop where the asset change (driver, truck, or trailer) would occur.
* Type the address into the designated field. You can also view the coordinates and the location on the map, similar to how you enter addresses elsewhere in the app.

  **Save the Split Point Location:**
* Click the **"Save"** button after entering the address.

  **Indicate Split Date and Time:**
* You will be prompted to enter the specific date and time when the split will occur at the new location.
* Enter the date and time.

  **Add the Location (Finalize Split Point):**
* Click **"Add Location"**.
* The system will now break down your original trip into two trips. The first trip ends at the split point you just added, and the second trip begins there, continuing to the original destination.
* *Note: The location you added acts as both the end point of the first new trip and the start point of the second new trip.*

  **Save the Load Changes:**
* After the trips are split, you will see the updated trip breakdown. Scroll down the page and click **"Save"**.

  *\[Video not supported]*

  **View Updated Trips:**
* After saving, if you scroll back up to the top of the Load Details Page, you will see the breakdown showing your original journey is now represented as two separate trips (e.g., "Michigan to Georgia" and "Georgia to Illinois".

  *\[Video not supported]*

### Adding Multiple Splits:

* Alvys allows you to repeat this process to split a single load's journey up to **20 times**. This provides extensive flexibility for modeling complex routes with many segments.

### What Happens to the Trailer

Splitting a trip no longer drops the trailer from the new leg. When you split, Alvys asks whether to carry the trailer over to the new leg and assumes you want to, so keeping it is the default and you only have to act if you do not.

If you set a trailer on one leg after the split, Alvys offers to apply it to the other legs of the same split. Legs with no trailer yet are filled in, and any leg that already has a different trailer is left as it is.

Removing a driver or a truck from a leg no longer removes the trailer along with them. When you do want the trailer removed too, use the separate **Also remove trailer** checkbox.

<Note>
  Assigning a trailer that is already committed to another trip over the same period raises a warning naming the other trip. It does not stop you from continuing. See [Equipment conflict warnings](/en/help/loads-trips/how-to-dispatch-a-load#equipment-conflict-warnings).
</Note>

### Re-Arrange Stops (Optional):

* If you need to change the sequence of pickups and deliveries within a trip (especially after splitting):
* From the "Optimize Trips" modal (accessed via the "Optimize" button), click the **"Re-Arrange"** button.
* You can then drag and drop stops to your preferred order.
* Click **"Save"** to confirm the new sequence.

*\[Video not supported]*

***

## Frequently Asked Questions (FAQ)

**Q: When would I typically use the "Split Trip" feature?** A: You would use this feature when a load's route requires a change in assets at an intermediary point. It's also useful for breaking down a single, long trip into multiple smaller, manageable segments for more precise tracking or dispatching.

**Q: Can I split at trip if it is in transit?**

A: Yes!


# Override Authorization Error When Assigning a Carrier
Source: https://docs.alvys.com/en/help/loads-trips/override-authorization-error-when-assigning-a-carrier

Learn why an error appears when assigning a carrier and how to resolve it by certifying the carrier in RMIS or using an admin override

<Note>
  When assigning a carrier to a trip, Alvys may block the assignment and display an authorization error if the carrier's compliance status with Highway, RMIS, or MyCarrierPackets (MCP) does not meet your company's requirements. This article explains the cause and how to resolve it.
</Note>

## Symptom

When assigning a carrier to a trip, Alvys displays the message: "We're sorry, but it appears that the carrier you've selected requires a supervisor/manager's approval to proceed with the assignment." The assignment cannot be completed without an override.

<img alt="Error message dialog when assigning a non-compliant carrier" />

*Error message dialog when assigning a non-compliant carrier*

## Cause

Your company requires carriers to pass a compliance check with one or more verification providers before they can be assigned to a load. The carrier you selected has a status that does not meet that requirement with at least one of the following providers:

**Highway:** The carrier's status is **Fail** (non-compliant) or **Incomplete** (requires review).

**RMIS:** The carrier's status is **Not Certified** (non-compliant).

**MyCarrierPackets (MCP):** The carrier's status is **UnacceptableFail** or **UnacceptableReview** (non-compliant), or **Moderate** (requires review).

**Statuses that do not trigger this restriction**: Pass, Acceptable, Certified, and Partial Pass.

## Resolution

A user with the **"OverrideCarrierRestriction"** permission (shown as **"Override Carrier Restriction"** in Administration, Permissions) can approve the assignment directly in the assign-carrier dialog.

1. Identify a user in your organization who has the **"OverrideCarrierRestriction"** permission.
2. Ask that user to review the carrier's compliance status and confirm whether proceeding is appropriate.
3. Have the authorized user complete the override step in the assign-carrier dialog to allow the assignment.

   <img alt="Assign-carrier dialog showing the override option" />

   *Assign-carrier dialog showing the override option*

## If That Didn't Work

If the override option does not appear in the assign-carrier dialog, or no user in your organization has the **"OverrideCarrierRestriction"** permission, contact Alvys support for help configuring carrier restriction settings.

## FAQs

**Q: How can I find out which provider is causing the restriction?**

**A:** Open the carrier's profile in Alvys and review the compliance section. The verification result from each provider (Highway, RMIS, MCP) is shown there, along with the carrier's current status.

**Q: Does overriding the restriction change the carrier's compliance status permanently?**

**A:** No. The override only allows this specific assignment to proceed. The carrier's compliance status with the verification provider is unchanged and will continue to trigger the restriction on future assignments until the carrier resolves their compliance issue with the provider.

**Q: Who can grant the "OverrideCarrierRestriction" permission to a user?**

**A:** Admins and Partner Admins can assign this permission to other users through Administration settings.

## Go Deeper

* [Carrier Verification](/en/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys)
* [MyCarrierPackets (MCP)](/en/help/integrations/mycarrierpackets-mcp-integration)


# Owner Operators cannot be assigned to a trip
Source: https://docs.alvys.com/en/help/loads-trips/owner-operators-cannot-be-assigned-to-a-trip

Fix the "2 Owner Operators cannot be assigned to a trip" error caused when a truck is already linked to a different OOP during driver assignment.

<Note>
  This error appears when you try to assign a driver who is an Owner Operator (also referred to as OOP) to a trip where the selected truck is already linked to a different Owner Operator. Each truck can be linked to only one Owner Operator at a time.
</Note>

## Overview

This article explains the "2 Owner Operators cannot be assigned to a trip" error: why it happens, what it means, and how to clear it. In Alvys, a truck (also called an asset or unit) can be tied to only one Owner Operator (OOP) at a time, so pairing a second Owner Operator with that truck on the same trip is blocked.

## Symptom

When assigning a driver or truck to a trip, you see the error: "2 Owner Operators cannot be assigned to a trip."

<Note>
  <img alt="Error dialog displaying the message '2 Owner Operators cannot be assigned to a trip'" />

  *Error dialog displaying the message "2 Owner Operators cannot be assigned to a trip"*
</Note>

## Cause

Each truck in Alvys can be owned by only one Owner Operator (OOP) at a time. This error occurs when the truck you selected is already registered under a different Owner Operator than the driver you are assigning. Alvys prevents this combination to avoid conflicting ownership records on the same trip.

## Resolution

Check the truck's current ownership. Go to the driver or asset list and confirm which Owner Operator the selected truck is linked to.

<Note>
  <img alt="Truck list showing the Owner column with an Owner Operator name displayed next to each truck." />

  * Truck list showing the Owner column with an Owner Operator name displayed next to each truck.\*
</Note>

Choose one of the following options based on what you find.

* Option A: Select a different truck. Choose a truck that is owned by the same Owner Operator as the driver you are assigning, or choose a truck with no Owner Operator currently linked.
* Option B: Change the driver's contractor status to Company Driver. If the driver should be classified as a Company Driver rather than an Owner Operator, update their contractor type in the driver record. After changing the status, return to the trip and reassign the driver.

<Note>
  <img alt="Screen recording showing the process of changing a driver's contractor status from Owner Operator to Company Driver in the driver record." />

  *Screen recording showing the process of changing a driver's contractor status from Owner Operator to Company Driver in the driver record.*
</Note>

* Option C: Update the truck's ownership in fleet settings. If the truck ownership record is incorrect, update the linked Owner Operator for that truck in your fleet settings before returning to reassign the driver.

## Troubleshooting

### Error persists after confirming ownership and contractor status

If you have confirmed the truck ownership and driver contractor statuses are correct and the error still appears, contact Alvys support with the load number and the names of the driver and truck you are trying to assign. Brokerage loads use a separate ownership validation path and may require support review.

## Related

* [How to Release a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)


# Previous Trip and Last Location on the Load Details Page
Source: https://docs.alvys.com/en/help/loads-trips/previous-trip-and-last-location-on-the-load-details-page

Find the Previous Trip and Last Location panel in the Stops section of the Load Details page after it moved from the Carrier Details area.

<Note>
  The "Previous Trip and Last Location" information for a carrier or driver now appears in the Stops section of the Load Details Page (LDP), not in the Carrier Details section. No functionality has changed; only the placement has moved.
</Note>

## Overview

The **Previous Trip and Last Location** information (also referred to as "Previous Stop and Last Location") was relocated from the **Carrier Details** section to the **Stops** section on the Load Details Page (LDP). The data itself and the actions available have not changed. Only where it appears on the page has moved.

This change places the previous trip's location alongside the current trip's stop details, so dispatchers can reference the carrier's or driver's last known position without navigating to a different section of the page.

## Where to Find It

Open a load and go to the Load Details Page. The **Previous Trip and Last Location** information is now displayed in the **Stops** section, below the stop list for the current trip.

Previously this information appeared in the **Carrier Details** section. If you are looking for it there and cannot find it, check the Stops section instead.

<Note>
  📷 **Image:** Previous Trip and Last Location shown in the Stops section of the Load Details Page, with the carrier's last known location alongside the current trip stop details.

  <img alt="Notion Image" />
</Note>

## Key Concepts

**Previous Trip:** The most recent completed trip for the assigned carrier or driver before the current load.

**Last Location:** The last known geographic location of the carrier or driver, pulled from tracking data.

**Stops section:** The part of the Load Details Page that lists the pickup, delivery, and any intermediate stops for the current load. Previous Trip and Last Location now appears here.

## How to Use It

Dispatchers can use Previous Trip and Last Location to verify where a carrier or driver is coming from before the current load begins. This helps confirm proximity to the first pickup stop and supports more accurate estimated time of arrival (ETA) planning.

No separate action is needed to view the information. Open the Load Details Page for any load with an assigned carrier and scroll to the **Stops** section.

## Limits and Behavior

* The Previous Trip and Last Location information is read-only. No changes have been made to the existing functionality.
* The data shown depends on tracking availability for the assigned carrier or driver. If no tracking data is available, the Last Location field may be empty.
* This section appears in the Stops section for all loads where a carrier or driver is assigned.

## FAQs

**Q: Can I still find Previous Trip and Last Location in the Carrier Details section?**

**A:** No. It has been moved permanently to the Stops section. It no longer appears in Carrier Details.

**Q: Has anything changed about what information is displayed or what I can do with it?**

**A:** No. The data and available actions are the same. Only the placement on the page has changed.

**Q: Why was this information moved to the Stops section?**

**A:** Placing the previous trip's location next to the current trip's stop details makes it easier for dispatchers to see a carrier's last known position alongside the current load's route, reducing the need to scroll between sections.


# Public Load Tracking
Source: https://docs.alvys.com/en/help/loads-trips/public-load-tracking

Enable Public Load Tracking to give customers a branded self-service page for real-time shipment status without calls or emails to dispatch.

## Empower Your Customers with Real-Time Load Tracking

The Public Load Tracking feature is designed to provide your customers with a seamless, self-service way to stay informed about their shipments. Instead of fielding constant calls and emails for status updates, you can empower customers to track their loads in real time, directly from a custom-branded tracking page. This not only improves customer satisfaction but also frees up your team to focus on other high-priority tasks.

### How to Check if Public Load Tracking is Active

This feature is only visible to Admin and Partner Admin users. To check if Public Load Tracking is enabled for your account, follow these steps:

1. Click on your person icon in the bottom left corner of the screen.
2. Select **Company Profile**.
3. Look for the **Public Load Tracking** toggle.

If the toggle is switched to **On**, the feature is active. If you don’t see Public Load Tracking in your Company Profile, you will need to contact [Alvys Customer Support](mailto:support@alvys.com) to have it enabled.

<img alt="Notion Image" />

## How to Use the Public Load Tracking Link

Once activated, you can copy the unique tracking link from your Company Profile page and share it with your customers. You can even embed this link in your email signature for easy access.

Your company's name will automatically appear on the tracking page, providing a professional and branded experience for your customers. Customers accessing the link can simply enter their order number and see tracking and status updates for that load.

* When a customer opens this link, they will see the tracking landing page where they can enter their order number under their search field.
* Once a valid order number has been entered, they will be able to see tracking and status information on that load. *You can brand this page, so the customer sees your logo!*

<img alt="Notion Image" />


# Rate Analytics
Source: https://docs.alvys.com/en/help/loads-trips/rate-analytics

Use Rate Analytics (beta) to compare your historical customer and carrier lane rates with market benchmarks when quoting or pricing loads.

<Note>
  Rate Analytics is a beta tool that shows your historical Customer and Carrier rates for a lane alongside market rate benchmarks, helping you price loads competitively.
</Note>

## Overview

Rate Analytics (also called the rates widget) lets you look up rate history for any lane by entering an origin and destination. The tool shows two data sets side by side: your own historical rates from loads you have run on that lane, and an aggregate market rate drawn from the broader Alvys network. This comparison helps you evaluate whether a rate you are quoting is competitive given current market conditions.

Rate Analytics is a beta feature. Rate coverage varies by lane and values may update as new data arrives.

## Where to Find It

Rate Analytics is available in two places in Alvys.

**Dedicated Rate Analytics page:** Navigate to Loads and Trips > Rate Analytics in the left navigation. This opens the full search interface where you can enter an origin, destination, search radius, and equipment type to retrieve rate history for any lane.

**Load board side panel (Marketplace):** When you open a load in the Marketplace and expand its side panel, a Rate Analytics chart appears automatically in the Rates section. This chart shows the last 30 days of Carrier rate history for that load's lane without requiring a manual search.

<Note>
  <img alt="Load board side panel showing the Rate Analytics section with a rate history chart" />

  *Load board side panel showing the Rate Analytics section with a rate history chart*
</Note>

<Note>
  <img alt="Load detail page showing the Rate Analytics chart in the Rates section." />

  *Load detail page showing the Rate Analytics chart in the Rates section.*
</Note>

## Key Concepts

**Your Rates vs. Market Rates**

Each chart displays two lines:

* Your Rates: the median rate your company has charged for that lane, drawn from your own load history.
* Market Rates: an aggregate median rate from the broader Alvys network for the same lane and time period. This line appears only when you have the **"ViewAlvysRateHistory"** permission.

  **Customer tab and Carrier tab**

  The Rate Analytics page organizes data into two tabs:
* Customer tab: shows rates on the Customer side of the load.
* Carrier tab: shows rates on the Carrier side of the load.

Both tabs display a Your Rates line and a Market Rates line for the selected lane.

**Time window**

All charts show rate data for the last 30 days. The window is fixed; it is not user-adjustable.

**Equipment types**

You can filter rate data by equipment type. Supported equipment types: Van, Reefer, Flatbed, Tanker, and Power Only. If no equipment type is selected, the search defaults to Van and Reefer.

## How to Use It

For step-by-step instructions on searching for rates on the Rate Analytics page, see the Contracted Rates article linked in Go Deeper.

## Settings and Permissions

Access to Rate Analytics requires at least one of the following permissions: **"ViewTenantRateHistory"**, **"ViewAlvysRateHistory"**, **"ViewCarrierRate"**, **"ViewCustomerRate"**, or **"Bidding"**.

The **"ViewTenantRateHistory"** permission is required to retrieve any rate data. Users without this permission receive an access error when the tool loads.

The **"ViewAlvysRateHistory"** permission controls whether the Market Rates line appears on the charts. Users with only **"ViewTenantRateHistory"** see their own company's rates but not the market benchmark.

If the Rate Analytics menu item does not appear under Loads and Trips, the feature may not be enabled for your account. First confirm you have one of the required permissions listed above; if so, contact Alvys support.

## Limits and Behavior

* The search window is always the last 30 days. Historical data beyond 30 days is not displayed.
* Rate coverage varies by lane. Low-volume lanes may return no data or data with wider min/max ranges.
* If no data is found, the tool displays a "No Data Available" message. Adjusting the origin, destination radius, or equipment type may return results.
* The Market Rates line is visible only to users with the **"ViewAlvysRateHistory"** permission. If only your company's line appears, your account does not have this permission.
* The Customer tab notes that customer rates do not include accessorials.
* Rate Analytics is a beta feature. Values may update as new data arrives.

## FAQs

**Q: Why does the Rate Analytics option not appear in my Loads and Trips menu?**

**A:** The menu item is hidden when your account does not have any of the required permissions: **"ViewTenantRateHistory"**, **"ViewAlvysRateHistory"**, **"ViewCarrierRate"**, **"ViewCustomerRate"**, or **"Bidding"**. If your account should have access, contact Alvys support.

**Q: Why do I see only one line on the chart instead of two?**

**A:** The Market Rates line requires the **"ViewAlvysRateHistory"** permission. If your account has only **"ViewTenantRateHistory"**, only your company's historical rates are shown.

**Q: Why does the search return no data for a lane I have run loads on?**

**A:** Rate data is retrieved for the last 30 days. If no loads matching the origin, destination, and equipment type were found in that window, the tool shows "No Data Available." Try widening the search radius or selecting a different equipment type.

**Q: Can I view rates for more than 30 days?**

**A:** No. The current time window is fixed at the last 30 days and is not user-adjustable.

**Q: What equipment types are supported?**

**A:** Van, Reefer, Flatbed, Tanker, and Power Only. If no equipment type is selected, the search defaults to Van and Reefer.

## Go Deeper

* [Contracted Rates](/en/help/loads-trips/contracted-rates)


# Stop Dates and Times
Source: https://docs.alvys.com/en/help/loads-trips/stop-dates-and-times

Set stop schedule types (FCFS or APPT) and record actual arrived and departed times as drivers progress through each stop on a trip.

<Note>
  Stop Dates and Times controls how arrived and departed times are set on each stop of a trip. You can set a schedule type (FCFS or APPT) when building or updating a load, and actual arrived and departed times are recorded as the driver progresses through each stop.
</Note>

## Overview

Every stop on a trip has two kinds of time information: the scheduled time (when the stop is planned to happen) and the actual time (when the driver actually arrived and departed). This article covers both.

Scheduling is set using a schedule type of **FCFS** (First Come First Serve, which uses begin and end window times) or **APPT** (Appointment, which uses a single appointment date and time). Actual arrived and departed times are recorded separately, based on the stop's current status.

The arrived and departed fields on a stop only appear when the stop is in a status that makes those fields relevant:

* The **Arrived** time field appears when the stop status is **Arrived**, **Picked Up**, **Empty**, or **Departed** (for waypoint stops).
* The **Departed** time field appears when the stop status is **Picked Up**, **Empty**, or **Departed** (for waypoint stops).

Schedule date and time details are included in the Rate Con, Load Manifest, Bill of Lading, and the driver's mobile app.

## Where to Find It

Stop scheduling and actual times are accessed in three places:

* **New load creation**: in step 4 (Order Details) of the new load form, each stop has a Schedule type field.
* **Existing load**: open a load, go to the Trips section, and open a stop to view or update its schedule type and actual times.
* **Company Profile**: go to **Management > Company Profile > Scheduling Info** to set the default schedule type that auto-fills on new stops.

## Key Concepts

**Schedule type** controls what date and time fields appear on a stop before the load is dispatched:

* **FCFS (First Come First Serve)**: requires a Begin Window time and an End Window time. Use this when the facility accepts drivers on a first-come, first-served basis within a time window.

<Note>
  📷 **Image:** FCFS schedule type selected in the new load creation form (Order Details step), displaying Begin Window and End Window time fields.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 **Image:** Additional view of FCFS scheduling configuration in the new load creation form, showing the Begin Window and End Window fields filled in.

  <img alt="Notion Image" />
</Note>

* **APPT (Appointment)**: requires a single Appointment Date and time. Use this when the facility requires a confirmed appointment.

<Note>
  <img alt="Notion Image" />
</Note>

The default schedule type is set in Company Profile under Scheduling Info. Each stop can override the default manually.

<Note>
  📷 **Image:** Company Profile page, Scheduling Info section, where the default schedule type for new stops is configured.

  <img alt="Notion Image" />
</Note>

**Arrived and Departed times** are the actual times recorded as the driver progresses through the stop. These fields only appear when the stop is in a relevant status (see Overview above).

## How to Use It

For step-by-step instructions on setting stop dates and times:

* Setting the schedule type on a new load: follow the steps in the New Load creation flow, step 4 (Order Details).
* Updating the schedule type on an existing load: open the load, navigate to the stop, and change the schedule type field. If you navigate away without completing the required fields, the system will show a confirmation prompt before reverting to the original schedule type.

  <img alt="Notion Image" />
* Adding a new stop or splitting a trip: when you add a stop or split a trip, select the schedule type for the new stop. The Company Profile default will auto-fill if no manual selection is made. For a split trip, enter the date and time for the stop that divides the trip.

  <img alt="Notion Image" />
* Recording actual arrived and departed times: open the stop in an active trip and enter the times directly in the Arrived and Departed fields when they are visible based on stop status.

## Settings and Permissions

Recording and updating arrived and departed times on a stop requires the **"Dispatch"** permission.

The default schedule type for new stops is configured in **Management > Company Profile > Scheduling Info**. Changing this setting requires the Company Profile Manager role.

## Limits and Behavior

* The **Arrived** field is only shown when the stop status is **Arrived**, **Picked Up**, **Empty**, or **Departed** (waypoints only).
* The **Departed** field is only shown when the stop status is **Picked Up**, **Empty**, or **Departed** (waypoints only).
* If you change the schedule type on an existing stop but do not fill in the required fields (Begin/End Window for FCFS, or Appointment Date for APPT), the schedule type reverts to the previous value.
* If you navigate away from a stop after changing the schedule type without saving, a confirmation modal appears asking whether you want to keep the current (unsaved) schedule or discard your changes.
* Waypoint stops support only FCFS schedule type. Appointments cannot be set on waypoints.
* Stop date and time details are automatically included in the Rate Con, Load Manifest, Bill of Lading, and the driver's mobile app after they are saved.

<Note>
  📷 **Image:** Rate Con document displaying stop schedule date and time information in the pickup and delivery sections.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 **Image:** Load Manifest document displaying stop date and time information for each stop on the trip.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 **Image:** Bill of Lading document displaying stop date and time information.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 **Image:** Driver mobile app screen displaying stop date and time information, showing the schedule for the driver's current trip.

  <img alt="Notion Image" />
</Note>

## FAQs

**Q: Why don't I see Arrived or Departed fields on my stop?**

**A:** These fields only appear when the stop is in a status that makes them relevant. The Arrived field appears when the stop status is **Arrived**, **Picked Up**, **Empty**, or **Departed** (waypoints). The Departed field appears when the stop status is **Picked Up**, **Empty**, or **Departed** (waypoints). If the stop is in a different status, these fields are hidden until the status changes.

**Q: What is the difference between FCFS and APPT schedule types?**

**A:** FCFS (First Come First Serve) requires a Begin Window and End Window time, used when the facility accepts drivers during an open window. APPT (Appointment) requires a single confirmed Appointment Date and time. Select the type based on how the facility schedules pickups and deliveries.

**Q: Can I set a default schedule type so I don't have to choose it on every stop?**

**A:** Yes. Go to **Management > Company Profile > Scheduling Info** and set your preferred default. New stops will auto-fill with that schedule type. You can still override it on individual stops.

**Q: What happens if I change the schedule type but don't fill in the required fields?**

**A:** The schedule type will revert to its previous value. The system does not save a partial schedule type change without the required date and time fields completed.

**Q: Are stop times sent to the driver?**

**A:** Yes. Schedule dates and times are sent to the driver's mobile app and are also included in the Rate Con, Load Manifest, and Bill of Lading.

## Go Deeper

* [Stop Time Validations](/en/help/loads-trips/error-when-recording-arrival-or-departure-time-on-a-stop): Understand the validation rules that prevent arrived and departed times from being saved with conflicting or future timestamps.


# Stop Type: Waypoint
Source: https://docs.alvys.com/en/help/loads-trips/stop-type-waypoint

Add waypoints to a trip for fuel, rest, and border crossings so mileage and routing stay accurate without creating a pickup or delivery stop.

<Note>
  🚀

  #### Now Available! Waypoints are now live!

  The engineering team was hard at work building this exciting new feature to bring you even more precise trip planning. Check it out!
</Note>

## Adding and Managing Waypoints on Trips

The **Waypoints** feature in Alvys allows you to define and manage intermediate stops within a trip that are neither pickups nor deliveries. These are crucial for accurately modeling operational points such as mandatory fuel stops, rest areas, or asset transfer points, providing a more precise representation of your trip's actual route.

**User Roles with Access:** All users who have access to add and manage stops on a trip (e.g., **Dispatchers**, **Load Planners**, **Admins**).

**Summary:** Waypoints enhance trip modeling by allowing you to include non-revenue-generating stops. You can add Waypoints with specific locations, time windows, instructions, and references. They are visible on the Load Details Page within the trip timeline and are communicated to drivers via the Driver Companion App, where drivers can check in/out and issue e-checks just like regular stops. This improves mileage accuracy and streamlines planning.

***

### How to Add a Waypoint

You can add Waypoints by editing an existing load on the Load Details Page.

#### Adding a Waypoint via the Load Details Page

**Navigate to the Load Details Page:**

Open the specific load to which you want to add a Waypoint.

**Click "Add Stop":**

In the "Trips / Stops" section, locate and click the **"Add Stop"** button.

**Choose "Waypoint" Stop Type:**

In the "Add Stop" modal that appears, select the **"Waypoint"** radio button. This will display the fields relevant to a Waypoint.

**Enter Waypoint Properties:**

**Dates (Required):** Enter the beginning and end date and times.

**Location/Address (Required):** Enter the Waypoint's location. You can manually type an address, select from the map, or choose an existing company.

**Scheduled Time Window:** Provide a start and end time for the planned arrival at the Waypoint.

**Stop Instructions:** Add any free-form text to provide additional information to the driver (e.g., "Mandatory fuel stop, use card 1234").

**References:** Add any relevant references to the stop.

<img alt="Notion Image" />

**Save the Waypoint:**

Click the **"Save"** button in the modal to attach the Waypoint to the trip.

***

### How Waypoints Appear and Function

Once a Waypoint is added and saved, it integrates seamlessly into your trip management workflows:

#### On the Load Details Page (LDP)

**Visibility:** Waypoints will appear clearly in the trip timelines within the "Trips / Stops" section of the LDP. They are visually distinguishable from Pickup and Delivery stops.

<img alt="Notion Image" />

**Expand/Collapse:** After a Waypoint is saved, it will appear on the LDP as a stop that can be expanded and collapsed, allowing you to customize your view.

<img alt="Notion Image" />

**Sequencing:** The order of Waypoints within a trip can be changed using the traditional **"Optimize > Rearrange"** flow. If you rearrange stops, the mileage between stops will automatically update.

<img alt="Notion Image" />

**Actual Times:** `Actual Arrival & Departure Times` will be system-generated timestamps, dependent on driver check-in and check-out events, enabling real-time progress tracking for Waypoints.

#### In the Driver Companion App

**Visibility:** When a trip gets dispatched to a driver, the Waypoint stop type will appear in the Driver Companion App (mobile app) as part of their trip itinerary.

<img alt="Notion Image" />

**Driver Interaction:** Drivers can click on the Waypoint stop to see additional Stop Details (e.g., instructions, references).

<img alt="Notion Image" />

**Check-in/out & E-check:** Drivers have the ability to check in, check out, and issue e-checks for Waypoints, just like they do for traditional Pickup or Delivery stop types.

***

### Frequently Asked Questions (FAQ)

**Q: Can a Waypoint be the first or last stop of a load?** A: A Waypoint can be the first or last stop *within a trip segment*. However, for a load to be considered revenue-generating and complete its full lifecycle, it must still include at least one Pickup stop and one Delivery stop.

**Q: Do Waypoints appear on Rate Confirmations or other external documents?** A: Initially, Waypoints will appear internally only (e.g., on the Load Details Page, in the Driver Companion App, in Driver Pay, on the Trips Manifest and IFTA report). They are not automatically included on external documents like Rate Confirmations in this version.

**Q. Are ETAs calculated differently with waypoints?**

A. On the Load Details Page and Dispatch Planner, the ETA to Next Stop will not be changed and will still be showing the ETA to the next ‘Customer’ stop.

**Q. In Driver Rates, will a waypoint count as a stop if I pay per stop?**

A. Yes. Per stop pay is inclusive of waypoints.


# Tender Documents - Customer Rate Confirmation V1
Source: https://docs.alvys.com/en/help/loads-trips/tender-documents-customer-rate-confirmation-v1

Generate Customer Rate Confirmations from the redesigned Tender modal so brokers and carriers can capture signed load details and reduce disputes.

## Overview

To reduce the risks associated with informal exchange of critical load details, brokers and carriers can now generate Customer Rate Confirmations, which include all necessary load information to be signed by the customer.

This new feature replaces informal documentation methods, enhancing security and reducing potential disputes. Additionally, we've redesigned the Documents and Tender modals for improved usability.

## Generating Tender Documents - Tender Modal

The Tender modal now consists of two tabs: **Customer** and **Carrier** (or **Driver/Owner Operator**).

ℹ️ **Dynamic Tab Headings:**

* If the **Tender As** subsidiary is a **Broker**, the tab headings will be **Customer and Carrier**.
* If the **Tender As** subsidiary is a **Carrier**, the tab headings will be **Customer and Driver/Owner Operator**.

  <img alt="Notion Image" />

  <img alt="Notion Image" />

  Each tab includes documents based on the intended audience:

1. **Customer:** Customer Rate Confirmation
2. **Carrier or Driver/Owner Operator:** Carrier Rate Confirmation, Bill of Lading, Load Manifest

**💡 Note:** The existing Rate Confirmation has been renamed to Carrier Rate Confirmation

<img alt="Notion Image" />

<img alt="Notion Image" />

## Generating the Customer Rate Confirmation

Users can generate the Customer Rate Confirmation from the Tender modal on the Load Details page. Follow these steps to generate the document:

1. Navigate to the Tender modal on the Load Details page.
2. Click the **Generate Customer Rate Confirmation** button.

   <img alt="Notion Image" />

## Emailing the Customer Rate Confirmation

After generating the Customer Rate Confirmation, you can email it to the customer for review and signature:

1. In the Tender modal, select the checkbox next to the Customer Rate Confirmation.
2. Click the **Email Selected Documents** button to open the Compose Email window.

   <img alt="Notion Image" />

## Handling Signed Customer Rate Confirmations

Currently, **e-signature functionality for Customer Rate Confirmations is not available.** Customers will need to sign the document using a third-party e-signature tool. Once signed, the document can be returned via email, and tenants can upload the signed Customer Rate Confirmation in the Documents modal using the document type **Signed Customer Rate Confirmation**.

<img alt="Notion Image" />

<img alt="Notion Image" />

## Customer Rate Confirmation Details

The Customer Rate Confirmation includes the following information:

* **Broker / Carrier Details:**
* Name
* Address
* Contact
* **Contact Details (of the person who generated the Rate Confirmation):**
* Name
* Contact
* **Customer Name**
* **Date** (generated)
* **Alvys Load Number**
* **Customer Order Number**
* **Total Weight**
* **Equipment Type**
* **Total Miles**
* **Temperature**
* **Commodity**
* **Stop Details**
* **Line Haul Rate**
* **Accessorial Charges**
* **Customer Signature Lines:**
* Name
* Signature
* Position
* Date

  <img alt="Notion Image" />

## Documents Modal

### Context Menu Options

Options to Edit, Download, Email, and Delete documents are now stored in a context menu. Click the vertical ellipses to expand the menu and reveal these options.

<img alt="Notion Image" />

### Merge Files

The Merge File function remains unchanged. However, a warning will be displayed if a user attempts to merge files meant for different audiences (carrier vs customer), informing them: **“You’re merging Carrier and Customer documents”**.

ℹ️ This warning **DOES NOT** prevent users from proceeding with the merge action.

<img alt="Notion Image" />

By following these steps, users can effectively generate, send, and manage Customer Rate Confirmations, ensuring all critical load details are formally documented and reducing the risk of disputes.


# Tenders
Source: https://docs.alvys.com/en/help/loads-trips/tenders

Manage new, change, and cancellation tenders on the Alvys Tenders Board, accepting or rejecting via EDI and reviewing load changes in one screen.

## Overview

Learn how to efficiently manage and respond to **new**, **change**, and **cancellation** tenders using the Alvys Tenders Board. Accept or reject tenders, view detailed load changes, and communicate with shippers via EDI—all from one screen.

## Accepting or Rejecting New Tenders

Manage incoming **Original** tenders directly from the **Tenders** board.

### Accept a New Tender

<Note>
  <img alt="Notion Image" />
</Note>

On the Tenders Board, find a tender with type **Original** and status **New**. Click \*\*Accept \*\*and select the companies and fleet in the modal that appears:

<Note>
  <img alt="Notion Image" />
</Note>

Click **Accept** again to finalize, which will create a load automatically and notify the shipper via EDI.

### Reject a New Tender

On the Tenders Board, click the **Reject** link on the tender row that you’d like to reject. In the modal that appears choose a rejection reason and click Reject to confirm and send the rejection and reason to the shipper via EDI.

<Note>
  <img alt="Notion Image" />
</Note>

## Handling Change Tenders

Change tenders appear on the Tenders Board with an **orange “Change”** label.

### Review and Act on a Change Tender

When a tender of type Change arrives you’ll need to review the changes and decide whether to accept it. To begin, click **View Changes** in the **Actions** column.

<Note>
  <img alt="Notion Image" />
</Note>

A new browser tab will open the **Load Details** page with a sidebar open showing the **Tender Update** where you can review the specifics:

<Note>
  <img alt="Notion Image" />
</Note>

Choose an action:

* **Accept** – approve the update.
* **Reject Tender Only** – reject the update, keep the original load.
* **Reject and Cancel Load** – reject the update and cancel the load (EDI notification is sent).

  If you clicked **Accept**, decide how to apply changes:
* Check **Apply all changes to the load** to apply everything at once, or
* Leave it unchecked to apply changes individually.

  (Optional) Apply items one by one in the **Tender Update** panel:
* Click **Apply** to update the load with that change.
* Click **Skip** to ignore it.

<Note>
  <img alt="Notion Image" />
</Note>

When an applied change triggers the addition of a stop, you’ll be asked to confirm or assign the appropriate Company:

<img alt="Notion Image" />

Your selection is recorded and communicated via EDI where applicable; the load is updated according to the changes you applied.

<Warning>
  ⚠️ Once a change is applied, it cannot be undone (you can still edit the load manually afterward).
</Warning>

## Handling Cancellation Tenders

Cancellation tenders notify you that the shipper wishes to cancel the shipment.

### Cancel a Load from a Cancellation Tender

#### Steps

1. Click **View Changes** on the tender.
2. Review the **Tender Update** panel indicating the cancellation.
3. Click **Cancel Load** (red button) to confirm.

#### Outcome

The load is canceled.

<Info>
  ℹ️ If you believe the cancellation is incorrect, simply close the panel; the load remains active.
</Info>

## Filtering and Finding Tenders

Quickly locate specific tenders using filters at the top of the Tenders Board.

### Use Filters

#### Steps

1. Set filters such as **Status**, **Type**, **Flag**, or **Customer**.
2. Scroll to load additional results as needed.

#### Outcome

The list reflects only tenders matching your criteria.

<Note>
  Customer names appear only when matching tenders are visible.
</Note>

## Viewing Tender Details and EDI History

Dive deeper into tender specifics and message flows.

### View Tender Details

#### Steps

1. Click any tender row to expand details.
2. Review fields like **Equipment Type**, **Stops**, **Notes**, **Weight**, **Temperature**, and **Miles**.

#### Outcome

You see current load/tender specifics without leaving the board.

### View EDI Transaction History

#### Steps

1. Click the **round arrow icon** at the far right of the tender row.
2. Review inbound/outbound EDI messages.
3. Click the **download icon** to save any file locally.

#### Outcome

You have a complete audit trail of EDI communications.

## FAQs

#### Do change tenders create a new row?

No. The existing tender row is updated and its type changes to **Change**.

#### What happens if I reject a change tender?

You’ll be prompted for a reason. You can either keep the original load active or cancel the load entirely.

#### Can I undo changes after applying them?

No. Applied changes are permanent, though you can still edit the load manually afterward.


# Understanding Address Input
Source: https://docs.alvys.com/en/help/loads-trips/understanding-address-input

Enter accurate stop and profile addresses using Google autocomplete, manual entry, Address Line 2, and coordinate-based map pinning across Alvys.

<Note>
  Alvys address fields support Google autocomplete, manual entry, an optional Address Line 2 field, and coordinate-based map pinning. These options appear consistently across load stops, company profiles, and other address forms to ensure accurate location data for routing, mileage, and invoicing.
</Note>

## Overview

Accurate addresses are essential for driver routing, mileage calculations, and document generation. Alvys address input fields offer multiple entry methods so you can capture precise locations even when Google autocomplete does not have a result.

<Note>
  <img alt="Alvys Cover Image" />

  \*Alvys Cover Image \*
</Note>

These input methods are available on address forms:

* **Google autocomplete:** The primary method. Start typing in the Address Line 1 field and select from the suggestions list. City, State, ZIP, and Country fill in automatically.
* **Manual entry:** When autocomplete does not return a match, type each field directly. All fields including Country are required for a valid address.
* **Address Line 2:** An optional field for suite numbers, apartment numbers, dock numbers, or other location details.
* **Map Pinning for Coordinates**: When accurate coordinates are necessary, you can drop a pin on the map to specify the location manually.

<Note>
  <img alt="Address input form showing all entry options, including Google autocomplete, Address Line 2, and the map panel." />

  *Address input form showing all entry options, including Google autocomplete, Address Line 2, and the map panel.*
</Note>

## Where to Find It

Address input fields appear in the following locations:

**Loads and Trips**

* Load creation form: the stop panels for each pickup and delivery
* Load Details Page: the Stops section when adding or editing a stop (Add Stop, Split Trip)
* Load Details Page: the Tenders section, External tab, carrier details panel

  **Companies**
* Company profile: Physical Address section
* Company profile: Invoicing address section

  **Fleet**
* Driver Profile: Physical Address and Company Address fields
* Trucks: New Truck form, Asset Leased From and Asset Leased To fields
* Subsidiary General Info: Physical Address and Remit Address fields

## Key Concepts

### Google Autocomplete

Google autocomplete is the default search tool on every Address Line 1 field in Alvys. As you type, a dropdown of suggestions appears. Selecting a suggestion populates City, State, ZIP, and Country automatically.

<Note>
  <img alt="Image displaying Address Line 1 field with Google autocomplete dropdown appearing as the user types" />

  *Image displaying Address Line 1 field with Google autocomplete dropdown appearing as the user types*
</Note>

Autocomplete may not return results for newly built locations, rural addresses, or internal facility locations such as a specific dock door within a large warehouse. When no suggestion appears, use manual entry instead.

### Manual Entry (if Address Not Found)

If autocomplete does not return a match, type the full address directly into each field: Address Line 1, City, State, ZIP, and Country. Country is required and must be selected from the dropdown.

### Address Line 2

Address Line 2 is an optional field present on every address form. Use it to specify details critical for drivers:

* Suite or office number (for example, Suite 200)
* Apartment number (for example, Apt 125)
* Dock or door number (for example, Dock 3)
* Building number or floor

This field does not affect geocoding or mileage calculations. Its value appears on rate confirmations, invoices, and other documents where the address is shown.

<Note>
  <img alt="Address Line 2 field with an example value entered (dock or suite number)." />

  *Address Line 2 field with an example value entered (dock or suite number).*
</Note>

### Map Coordinates

For addresses where precise geolocation is required (e.g., for stops on a load), you can now manually set the exact coordinates by dropping a pin on a map. You can set coordinates two ways:

* Type latitude and longitude directly into the Coordinates field using the format "lat, lng."
* Click anywhere on the map to drop a pin at that location, or drag the existing pin to adjust the position.

<Note>
  <img alt="Map panel with an interactive pin dropped and the Coordinates field populated." />

  *Map panel with an interactive pin dropped and the Coordinates field populated.*
</Note>

When coordinates are set, the system performs a reverse geocode to suggest address field values. Existing user-entered address fields are preserved; only the Coordinates field is updated.

## Settings and Permissions

Access to address input is governed by the permission required to edit the parent record.

* Editing stop addresses on a load requires the **"Dispatch"** permission.
* Editing company, customer, or carrier profile addresses requires the **"EditCustomer"** permission.
* Editing asset record addresses (trucks, trailers) requires the **"EditAsset"** permission.
* Editing driver profile addresses requires driver record edit access.

If you can open and edit the load, profile, or asset record, the address fields within it are accessible.

## Limits and Behavior

* Country is required when entering an address manually. Google autocomplete fills Country automatically when a suggestion is selected.
* Address Line 2 is always optional. Leaving it blank does not prevent saving the record.
* Coordinates are optional on load stops.
* The interactive map pin is only available on non-revenue stop address forms when the location mode is set to Address. On all other forms, the map is a read-only preview when coordinates have been set.
* When you click the map to set coordinates, existing user-entered Address Line 1, City, State, and ZIP values are preserved.

## FAQs

**Q: Why would I need to manually enter an address if Google autocomplete is available?**

**A:** Google autocomplete may not recognize new construction sites, rural addresses, or specific internal locations such as a particular dock door at a large facility. Manual entry lets you capture those details accurately.

**Q: How does adding Address Line 2 help my operations?**

**A:** Address Line 2 lets you include precise details critical for drivers, such as the exact suite, apartment, or dock number. This reduces confusion at pickup and delivery locations and ensures the correct details appear on rate confirmations and invoices.

**Q: Why can I see the map but cannot click on it to place a pin?**

**A:** The interactive map pin is only available on non-revenue stop address forms when the location mode is set to Address. On all other forms, the map is a read-only preview.


# Understanding Load Statuses and How to Revert Them
Source: https://docs.alvys.com/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them

Understand each load status from Open through Paid and learn when and how to revert a status to keep dispatch, billing, and reporting accurate.

<img alt="Notion Image" />

In Alvys, load statuses represent key stages in a load's lifecycle, helping you track progress from dispatch to payment. Understanding these statuses is essential for efficient operations and ensures accuracy when adjustments are needed. This guide explains each load status, what they mean, and provides step-by-step guidance on when and how to revert a status if necessary.

| **Status**     | **Brokers**                                                                                                                                                                                                  | **Carriers**                                                                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Open**       | A load that has been created but has not yet been assigned to a carrier.                                                                                                                                     | A load that has been created but has not yet been assigned to a carrier or driver.                                                                                                                           |
| **Quoted**     | A load for which bids or quotes have been received from carriers, but no further action has been taken yet.                                                                                                  |                                                                                                                                                                                                              |
| **Reserved**   | A load assigned to a carrier, but the carrier has not yet completed the required carrier packet.                                                                                                             |                                                                                                                                                                                                              |
| **Covered**    | A load that has a carrier assigned but is awaiting the carrier’s signature on the rate confirmation.                                                                                                         | A load that has been assigned assets (drivers and/or equipment) but has not yet been dispatched.                                                                                                             |
| **Dispatched** | A load with an assigned carrier that has been officially dispatched to begin the shipping process.                                                                                                           | A load with assigned assets that has been officially dispatched to begin the shipping process.                                                                                                               |
| **Delivered**  | A load is marked as **Delivered** once it reaches its final destination and all stops have been successfully completed. This status signifies that the load is ready to move forward in the billing process. | A load is marked as **Delivered** once it reaches its final destination and all stops have been successfully completed. This status signifies that the load is ready to move forward in the billing process. |

### ↩️ Reverting from Delivered to In Transit

If a load needs to be reverted to **In Transit**, users can update the status of the final stop by marking it as **Arrived** or **Covered**. This will automatically change the load/trip status back to **In Transit**—*unless* the assets have already been paid.

<img alt="Notion Image" />

## Released

A load enters the **Released** status after it has been delivered and verified as ready for the billing process. Users can move a load to **Released** by selecting **Manage > Release**. Once a load is in **Released**, the next step is typically to verify the documentation and generate the invoice.

### ↩️ Reverting from Released to Delivered

Users have the option to revert a load from **Released** by selecting **Manage > Revert Status**. This allows them to make any necessary adjustments or updates before continuing with the billing process.

<img alt="Notion Image" />

<Tip>
  Moving a load between **Released** and **Delivered** — in both directions — requires the **Release Loads** permission. If the Revert Status option is missing, confirm this permission is enabled on your profile. See [Dispatch Permissions](/en/help/administration/dispatch-permissions) for default role assignments.
</Tip>

## Queued

A load is marked as **Queued** when its invoice has been generated and is ready to be submitted to a customer, broker, or factoring company.

### ↩️ Reverting from Queued to Released

Users cannot currently revert a load from **Queued**; this can only be done by the support team. If you believe a change is necessary, please contact support, and they will assist after reviewing your request.

Before reverting from **Queued** to **Released**, the support team will:

* Assess why the change is needed, as it may not be required.
* Note that adjustments, such as rate changes or adding/removing accessorials, can still be made while the load is in **Queued** or **Invoiced** status.

**Situations Where Reverting to Released Is *Not* Necessary:**

* You need to adjust the freight rate.
* You need to add or remove accessorials.

**Situations Where Reverting to Released *Might* Be Necessary:**

* The load is not yet ready for invoicing, and dispatchers still need to work on it.
* Users responsible for generating invoices want to prevent others from accidentally submitting the invoice while it’s in **Queued**.
* You need to change the **Invoice As** setting, which requires the load to be in **Released**.
* You need to change the customer, which can only be done in **Delivered** status.
* A recent change to invoicing settings needs to be applied, requiring the load to revert to **Released** for the settings to take effect.

## Invoiced

A load is marked as Invoiced when its invoice has been submitted directly to a customer, broker, or factoring company. This status indicates that the invoicing process is complete on your end, and the next step is awaiting payment or processing by the recipient.

### ↩️ Reverting from Invoiced to Queued

Reverting a load from Invoiced can be a complex process, and it’s essential to first determine why the change is necessary and understand any potential consequences. Below are scenarios where reverting may apply:

### When It Should Remain Invoiced

If you need to adjust the rate, add accessorial charges, or make other changes to the invoice after it’s already submitted, the status should generally remain Invoiced.

* For invoices submitted to factoring, any updated invoice should be sent to the factoring company directly by email.

### When It Can Be Reverted

**For Non-Factoring Invoicing Methods:**

If the load was invoiced incorrectly (e.g., wrong amounts or details), the status can be reverted so you can re-create and submit the invoice. You’ll be able to re-invoice the load yourself once the changes are finalized.

**For Factoring Invoicing Methods:**

If the invoice was submitted to factoring in the wrong batch or under the wrong subsidiary, additional steps are required:

* Ensure the factoring company is aware of the issue and has removed the invoice from their batch.
* Contact support to manually remove the load from the batch in the system.
* Once removed, you can re-create the invoice under the correct subsidiary and send it in a new batch.

## Financed

A load is marked as **Financed** when its invoice has been purchased and funded by the factoring company.

↩️ Reverting a **Financed** status is not possible. If you require help, please contact the support team.

## Completed

A load is marked as **Completed** once the customer or factoring company has paid the full linehaul amount, and no other payments are outstanding. This represents the final stage in a load's lifecycle.

↩️ Reverting a **Completed** status is not possible. If you need assistance, please contact the support team.

## Troubleshooting

### Why is the revert option unavailable?

Work through this checklist to find the cause:

1. **Load is in Completed or Financed status.** Contact Alvys Support through the Help button in the bottom-left corner of Alvys and they will assess whether the revert is necessary and perform it if appropriate.
2. **Load is in Queued status.** Reverting from Queued to Released cannot be done through the UI by any user. Contact Alvys Support through the Help button in the bottom-left corner of Alvys and they will assess whether the revert is necessary and perform it if appropriate.
3. **Missing Release Loads permission.** Both releasing a load (Delivered → Released) and reverting it (Released → Delivered) require the **Release Loads** permission. Without it, the Revert Status option does not appear in the Manage menu. See [Dispatch Permissions](/en/help/administration/dispatch-permissions) to check which roles have this permission and how to grant it.
4. **Load is in Invoiced status and you want to revert.** Invoiced loads can be reverted in some scenarios (see the Invoiced section above), but the process depends on whether the load was submitted to factoring. For non-factoring loads, the revert can be done by the user. For factoring loads, contact the factoring company first, then contact Alvys Support to remove the load from the batch before re-invoicing.


# Safety and maintenance overview
Source: https://docs.alvys.com/help/assets-fleet/safety-and-maintenance-overview

Where safety and maintenance records live in Alvys: the Asset Safety Report, carrier verification, and maintenance on trucks and trailers.

Safety and maintenance in Alvys is the work of keeping driver and equipment documents current so the fleet can operate. The Asset Safety Report is the list view; driver and asset profiles hold the records themselves.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="Safety and Maintenance Records Overview" />

[Open the recording](https://www.loom.com/share/4042fa9c028d4a0497667fffdce6c5dd)

## Where to work

**Asset Safety Report** — **Reports > Safety** (`app.alvys.com/#/reports/safety`). This is the page the **"View Asset Safety Report"** permission opens. It shows documents that have expired or are about to expire:

* **Drivers:** license, medical certification, last motor vehicle record, Clearinghouse dates
* **Trucks and trailers:** assigned driver, plate expiration, inspection expiration, lease start and end

You need the **"View Asset Safety Report"** permission. Safety, Admin, Partner Admin, Operation Manager, Dispatcher, and Office Admin have it by default. See [Report permissions](/help/administration/report-permissions).

**Driver and asset profiles** — open a driver, truck, or trailer to add or update the records the report reads. Create the asset first if it does not exist yet.

<CardGroup>
  <Card title="Create a driver" icon="id-card" href="/help/assets-fleet/how-to-create-a-driver">
    Add the driver profile that holds license and medical records.
  </Card>

  <Card title="Add a truck" icon="truck" href="/help/assets-fleet/how-to-add-a-truck-in-alvys">
    Add the truck profile that holds plate, inspection, and lease dates.
  </Card>

  <Card title="Verify a motor carrier" icon="shield-check" href="/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys">
    Confirm a carrier representative is authorized by the FMCSA owner.
  </Card>

  <Card title="Fleetrock maintenance" icon="wrench" href="/help/integrations/fleetrock-maintenance-integration">
    Sync shop and maintenance work from Fleetrock when that integration is on.
  </Card>

  <Card title="IFTA reports" icon="gas-pump" href="/reporting/reports/overview">
    Fuel-tax reporting that Safety and Accounting often run together.
  </Card>
</CardGroup>


# Dispatch as a broker
Source: https://docs.alvys.com/help/loads-trips/dispatching-as-a-broker

Cover a load with an outside carrier, send the rate confirmation, and track the move.

When you broker a load, dispatching means assigning a carrier (not your own driver and truck), sending the rate confirmation, and tracking the move. Watch the walkthrough, then use the written how-tos for each step.

## Watch the walkthrough

<Note>
  If a screen in the video looks different, follow the written steps below.
</Note>

<iframe title="How to complete dispatching as a Broker" />

[Open the recording](https://drive.google.com/file/d/1HbPLRUMLYG2o4xIK3q-6xJe6M1EiYBvu/view)

## Written steps

<CardGroup>
  <Card title="How to dispatch a load" icon="truck-fast" href="/help/loads-trips/how-to-dispatch-a-load">
    Cover the trip. On a brokered load you assign a carrier instead of a company driver.
  </Card>

  <Card title="Send the rate confirmation" icon="envelope" href="/help/loads-trips/how-to-send-the-rate-confirmation-to-a-carrier">
    Send the carrier their rate confirmation after you cover the load.
  </Card>

  <Card title="Verify a motor carrier" icon="shield-check" href="/help/assets-fleet/how-to-verify-a-motor-carrier-in-alvys">
    Confirm the person representing the carrier is authorized by the FMCSA owner.
  </Card>

  <Card title="Tenders" icon="file-contract" href="/help/loads-trips/tenders">
    Receive and work a customer tender when the load comes in over EDI.
  </Card>

  <Card title="Load statuses" icon="signal" href="/help/loads-trips/understanding-load-statuses-and-how-to-revert-them">
    What Covered, In Transit, and Delivered mean on a brokered load.
  </Card>
</CardGroup>

If you cover loads with your own drivers and trucks, use [Dispatch as a carrier](/help/loads-trips/dispatching-as-a-carrier).


# Bulk Deleting and Restoring Transactions in the Fuel Report
Source: https://docs.alvys.com/en/help/accounting-settlements/bulk-deleting-and-restoring-transactions-in-the-fuel-report

Select multiple fuel transactions at once in the Fuel Report to delete or restore them in a few clicks instead of processing each row individually.

Managing fuel transactions just got easier with bulk select. Instead of deleting or restoring transactions one by one, you can now select multiple at once and process them in a few clicks. This is especially helpful if you need to clean up or recover a large number of transactions without having to contact support.

<img alt="Notion Image" />

To delete multiple transactions, open the **Fuel Report**, use the checkboxes in the left column to select the ones you want to remove, and click the **Delete** button that appears at the bottom of the screen. If you need to restore deleted transactions, go to the **Deleted** tab, select the transactions you want to recover, and click **Restore**.

You can still right-click a single transaction to delete or restore it if needed, but bulk select makes it much faster to handle large lists.


# Driver statements
Source: https://docs.alvys.com/en/help/accounting-settlements/driver-statements

How to customize driver statements and settlements

<img alt="Screenshot" />

Driver statements customization can be found in the driver settlements settings. Select the customize option to configure layout types as well as transaction information found on the statement.


# Email/ Submit Invoice fails:
Source: https://docs.alvys.com/en/help/accounting-settlements/email-submit-invoice-fails

Fix the invoice email error "Unexpected character encountered while parsing value" caused by PDFs over the 10 MB limit by compressing and resending.

<Note>
  When submitting an invoice (also called billing or sending a bill) by email, the error "Unexpected character encountered while parsing value" means the invoice file exceeds the 10 MB limit; compress the file and resend.
</Note>

## Symptom

When you submit an invoice through Batch Invoicing using email delivery, the following error appears: "Unexpected character encountered while parsing value." The invoice is not sent and the load remains in **Queued** or **Released** status.

<Note>
  <img alt="Screenshot of the error message displayed during invoice submission" />

  *Screenshot of the error message displayed during invoice submission*
</Note>

## Cause

The invoice PDF exceeds the 10 MB file size limit enforced during email submission. A file over this limit causes the email parsing process to fail before the invoice is delivered to the customer.

## Resolution

1. Check the invoice file size. Open the invoice PDF from the load and confirm whether it exceeds 10 MB. If the file is under 10 MB and the error still appears, go to "If That Didn't Work" below.
2. Compress the invoice file. Use a PDF compression tool to reduce the file below 10 MB. Verify the compressed file is still legible before proceeding.
3. Resend the invoice. Return to Batch Invoicing, locate the load, attach or regenerate the compressed invoice document, and resubmit using Create & Send or Send Invoice.

<Note>
  <img alt="GIF showing the step of resubmitting a compressed invoice from the Queued tab" />

  *GIF showing the step of resubmitting a compressed invoice from the Queued tab*
</Note>

## Troubleshooting

### The file is under 10 MB but the error persists

Verify the invoice document is a valid, uncorrupted PDF. If the problem continues, contact Alvys support with the load number, the full error message text, and the file size.

## FAQs

**Q: What file size limit applies to invoices sent by email?**

**A:** The invoice file must be under 10 MB. Files at or above this limit cause the email submission to fail with the parsing error.

**Q: Why does the error mention "parsing" instead of file size?**

**A:** The oversized file disrupts the email parsing process before delivery, so the system surfaces a parsing error rather than an explicit size message. The underlying cause is the file exceeding 10 MB.

## Related

* [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing)


# Escrow Accounts
Source: https://docs.alvys.com/en/help/accounting-settlements/escrow-accounts

Set up driver escrow accounts in Alvys to reserve earnings for insurance, tolls, plates, and maintenance using scheduled or one-time deductions.

## Overview

An Alvys Escrow Account (also called a driver reserve or driver holdback) works similarly to a savings account. Its purpose is to reserve a portion of a driver's or owner-operator's earnings to cover anticipated costs associated with their trucking operations.

Also known as: driver reserve, driver holdback, escrow deposit, escrow withdrawal.

Expenses that escrow accounts commonly cover include Insurance, Equipment, Security deposit, General reserves, Tolls, Plates, 2290 fees, and Maintenance.

Deposits and withdrawals can be made on a scheduled basis (recurring) or as a one-time deduction from payroll. The system supports scheduling based on a calendar, a set number of occurrences, or other customizable parameters.

Escrow accounts support **Min Balance** and **Max Balance** values for monitoring. If a balance falls below the minimum, the system alerts you to create a deposit to replenish it. Max Balance is a reference threshold only — reaching it does not automatically stop or reduce scheduled deposits.

## How it works

Key concepts:

* **Escrow Account:** A named reserve account created for a specific driver or owner-operator. Each account has a defined purpose (such as Insurance or Maintenance), and can have minimum and maximum balance limits.
* **Deposit:** An amount added to the escrow account, deducted from the driver's payroll.
* **Withdrawal:** An amount removed from the escrow account, returned to the driver or applied to a specific expense.
* **Split Deduction:** A one-time expense that is divided between the driver's payroll and the escrow account. The user decides how much comes from each source.
* **Balance Visibility:** Balances are not reflected in the escrow account until a paystub is generated that includes the relevant transaction.

Behavior and limits:

* Escrow account balances are updated only when a paystub is generated that includes the deposit or withdrawal transaction.
* When a one-time escrow deposit or withdrawal is added, two entries appear in the deductions table: one for the initial account balance and one for the deposit or withdrawal.
* **Reaching the Max Balance does not stop scheduled deposits.** Deposits continue on their schedule once the balance passes Max Balance. To stop collecting into a funded account, edit or remove the recurring escrow deduction on the Deductions tab.
* If the balance falls below the minimum, you will receive an alert to create a new deposit.
* When splitting an expense between payroll and the escrow account, entering the payroll amount calculates the escrow portion automatically (or vice versa).

## How to use

Where to find it: navigate to the driver or owner-operator profile.

1. Open the profile from **Assets > Drivers** (for company drivers) or **Assets > Owner-Operators** (for owner-operators).
2. Select the **Escrow Account** tab on the profile to view, create, and manage escrow accounts.
3. To create deposits or withdrawals, go to the **Deductions** tab on the same driver or owner-operator profile.

### Settings and permissions

Escrow accounts require the **Pay Driver** permission. This permission reveals the **Escrow Account**, **Deductions**, and **Fuels** tabs on a driver or owner-operator profile. Without it, those tabs are hidden entirely and the user cannot view or manage escrow accounts. See [Billing Permissions](/en/help/administration/billing-permissions) for how to grant it.

Escrow accounts are supported for both company drivers and owner-operators. For owner-operator payroll, the separate **Pay Owner Operator** permission controls access to the Owner Operator view within Pay Drivers and Driver Settlements.

After creation, only the **"Min Balance"** and **"Max Balance"** fields can be edited; all other account fields are set at creation and cannot be changed. To change other fields, delete the account and create a new one. To delete an escrow account, select the bin (trash) icon next to the account in the Escrow Account tab.

<Note>
  📋 This image shows a driver profile with the Escrow Account tab selected and the Add Escrow Account button visible.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the Add Escrow Account pop-up form with fields filled in and the Save button.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the escrow account list with the pen (edit) and bin (delete) icons visible next to an account.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the Deductions tab on a driver profile with the Add Deduction button clicked.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the transaction type dropdown open with Escrow Deposit and Escrow Withdrawal options visible.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the escrow account selector dropdown showing existing escrow accounts to choose from.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the amount field and frequency set to Once with a start date entered.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the deductions table after saving a one-time transaction, displaying two entries, one for the initial balance and one for the deposit or withdrawal.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the transactions history table under the Escrow Account tab after a transaction has been recorded.

  <img alt="Notion Image" />
</Note>

<Note>
  📋 This image shows the Driver Settlements page with a driver selected and the Deductions/Reimbursement section scrolled into view. Source:

  <img alt="Notion Image" />
</Note>

## FAQs

**Q: Who can create and manage escrow accounts?**

**A:** Only users with the **Pay Driver** permission. That permission controls whether the **Escrow Account** tab appears on a driver or owner-operator profile at all — users without it never see the tab and cannot view or manage escrow accounts. See [Billing Permissions](/en/help/administration/billing-permissions).

**Q: Can I edit an escrow account after it has been created?**

**A:** Only the **"Min Balance"** and **"Max Balance"** fields can be edited after creation. To change any other field, delete the account and create a new one.

**Q: When does the escrow account balance update?**

**A:** Balances are not reflected until a paystub is generated that includes the relevant transaction. The balance updates when that paystub is produced, not when the deposit or withdrawal is entered.

**Q: What is a split deduction?**

**A:** A split deduction divides a one-time expense between the driver's payroll and the escrow account. You enter the amount for one source, and the system calculates the other automatically.

**Q: Can I schedule recurring deposits or withdrawals?**

**A:** Yes. When adding a deduction of type Escrow Deposit or Escrow Withdrawal, select a frequency of Monthly, Annually, Weekly, or Every Statement, then set a recurring date and start date.

**Q: What happens if the escrow balance exceeds the Max Balance?**

**A:** Nothing automatic. Max Balance is a reference value — scheduled deposits continue past it, and Alvys does not pause or reduce them. To stop collecting into an account once it is funded, edit or remove the recurring escrow deduction on the Deductions tab.

**Q: What happens if the escrow balance falls below the minimum?**

**A:** The system alerts you to create a deposit to replenish the balance.

**Q: Can I view escrow transaction history?**

**A:** Yes. After a transaction is conducted on an escrow account, it is recorded in the transactions history table under the Escrow Account tab on the driver or owner-operator profile.


# How to Issue and Manage E-Checks in Alvys
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-issue-and-manage-e-checks-in-alvys

Issue e-checks to drivers from a load, set per-driver or per-user e-check limits, and search Comdata and EFS check transactions in Alvys Accounting.

<Note>
  Issue e-checks (electronic checks) to drivers directly from a load, set e-check limits per driver or user, and search all e-check transactions from the Accounting module. Requires the **"Issue ECheck"** permission to issue.
</Note>

## Overview

E-checks (also called electronic checks, money codes, or Comchek/EFS checks) let you issue instant electronic payments to drivers without cash or physical checks. Alvys supports e-check issuance through integrations with EFS and Comdata. All accounts include a \$500 default e-check cap as a security measure to prevent accidental or unauthorized large-value issuances. Admins can customize this cap per driver or per user role.

All issued e-checks are searchable and auditable from Accounting > E-Checks.

## Before You Start

To issue an e-check from a load, your user account must have the **"Issue ECheck"** permission. Contact your company Admin if the **Manage E-Check** button is not visible on a load.

To set e-check limits for drivers, you need access to the driver profile (Assets > Drivers). To set limits for users, you need access to the Company Profile (Management > Company Profile > Users tab). Contact your Admin if you cannot access these areas.

Have the driver or recipient name and the payment amount ready before issuing.

## Steps

* Open the load from which you want to issue the e-check.
* **Open the e-check panel.** Scroll to the Money Box section. Click **Manage E-Check**. Alternatively, right-click the load on the Load Board and select **Issue E-Check**.

<Note>
  <img alt="Image showing the “Manage E-Check” button in money box section on a load." />

  *Image showing the “**Manage E-Check**” button in money box section on a load.*
</Note>

* **Select the driver recipient.** In the Manage E-Check panel, search for and select the driver or carrier who will receive the payment.
* **Enter the amount.** Enter the payment amount. Confirm this is within the driver's e-check cap and within any user-level cap set on your account.
* **Select the reason.** Choose the reason for the e-check (for example: Fuel Advance, Lumper Fee, Cash Advance). Available reasons depend on your company's configuration.
* **Choose the provider.** If your company has more than one e-check integration active, select EFS or Comdata as the provider for this payment.
* **Add a reference (optional).** Enter a reference note to associate with this e-check record. This is optional but useful for reconciliation.

<Note>
  <img alt="Image showing the manage E-Check panel, which includes input fields for driver, e-check amount, e-check reason, subsidiary, E-check provider and note." />

  *Image showing the manage E-Check panel, which includes input fields for driver, e-check amount, e-check reason, subsidiary, E-check provider and note.*
</Note>

* **Generate the e-check.** Click **Generate**. The e-check is created, a payment code is issued, and the e-check appears as a line item in the load's Money Box.

<Note>
  <img alt="Image showing generate E-check button." />

  *Image showing generate E-check button.*
</Note>

## Result

The driver or carrier receives a payment code to redeem at authorized locations. The e-check is logged in the load's activity history. To view all e-checks issued across loads, navigate to **Accounting > E-Checks** (requires the **"ECheckFee"** permission to access that page).

## Variations

### Setting E-Check Limits for Individual Drivers

Admins can set a maximum e-check percentage or cap for a specific driver.

* Navigate to Assets > Drivers.
* Locate and click on the driver whose e-check limit you want to set or modify.
* In the driver profile, find the **E-Check %** and **E-Check Cap** fields.

<Note>
  <img alt="Image of the driver profile showing the E-Check % and E-Check Cap fields." />

  *Image of the driver profile showing the E-Check % and E-Check Cap fields.*
</Note>

* Click **Not set** next to either field to open the input window. Enter the desired limit.

  **E-Check Percentage:** The maximum percentage of a payment the driver can receive via e-check.

  **E-Check Cap:** A fixed maximum dollar amount the driver can receive per e-check transaction.
* Save your changes.

### Setting E-Check Limits for Alvys Users

Admins can set a maximum e-check issuance cap for specific users based on their role.

1. Navigate to Management > Company Profile.
2. Click the **Users** tab.
3. Locate and click on the user whose e-check limit you want to modify.
4. Find the **E-Check Cap** field (default: \$500). Click the current value or **Not set** to open the input window and enter the maximum dollar amount this user can issue per e-check.
5. Save your changes.

### Searching and Reviewing E-Checks

All e-check transactions are searchable from the Accounting module.

1. Navigate to Accounting > E-Checks.
2. Define your search criteria. You can filter by Money Code/Check Number, Date Range, Driver, Load Number, Amount Issued, Reason, and Date Generated using the respective fields and column filters.
3. Execute the search.
4. Review the results. The results table shows all matching e-checks with details including driver, load number, amount, reason, and the user who generated it.
5. To view the full load record, click the load number in the results to navigate directly to that load's page.

## Troubleshooting

### Manage E-Check button is not visible on a load

The **Manage E-Check** button is only visible to users with the **"Issue ECheck"** permission. Contact your company Admin to verify that your user account has this permission assigned. The button also does not appear on original trips; it is only available on the working copy of a trip.

### E-check amount exceeds the allowed cap

Each user and driver has an e-check cap (default \$500). If the amount you are trying to issue exceeds the cap, the transaction will be blocked. Contact your Admin to increase the cap in the driver profile (Assets > Drivers) or user settings (Management > Company Profile > Users tab).

### E-check provider not listed in dropdown

The available e-check providers depend on your active Alvys integrations. If EFS or Comdata is not appearing, confirm that the integration has been set up in your account. Contact [support@alvys.com](mailto:support@alvys.com) if the integration is enabled but the provider is still not appearing.

## FAQs

**Q: Which e-check providers does Alvys support?**

**A:** Alvys supports e-check issuance through EFS and Comdata integrations. The providers available in your dropdown depend on which integrations are active on your account.

**Q: How do I find an e-check that was already issued?**

**A:** Navigate to Accounting > E-Checks. You can search by money code, check number, date range, driver, load number, amount, or reason. You can also click any load number in the results to view the full load and its e-check history.

**Q: What is the default e-check cap?**

**A:** All Alvys accounts have a default \$500 e-check cap per transaction as a security measure. Admins can increase or remove this cap individually for each driver (Assets > Drivers > E-Check Cap) or per user (Management > Company Profile > Users > E-Check Cap).

**Q: Can I transfer an e-check from one load to another?**

**A:** Yes, e-checks can be moved between loads. See the separate article on transferring e-checks for instructions.

## Go Deeper

* [E-Check Permissions](/en/help/administration/e-check-permissions)
* [EFS Fuel Checks Integration](/en/help/integrations/efs-fuel-integration)
* [Comdata Fuel Checks Integration](/en/help/integrations/comdata-fuel-checks-integration)


# How to Move an E-Check to a Different Load
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-move-an-e-check-to-a-different-load

Reassign an unpaid e-check (comchek or money code) from one load to another in Alvys, moving accessorials and creating an audit log on both loads.

<Note>
  E-checks (also called comcheks, comchecks, or money codes) can be moved from one load to another directly in Alvys, as long as the e-check has not been paid, cancelled, or included in a driver statement. If the e-check cannot be moved, you can cancel and reissue it, or mark it as unavailable for settlement and add a matching accessorial charge on the destination load.
</Note>

## Overview

An e-check (also called a comchek or money code) issued on a load can be reassigned to a different load and trip without cancelling and reissuing it. This is useful when a check was generated on the wrong load, or when a load is split and the e-check needs to follow the driver to the correct trip.

Moving an e-check also moves the associated accessorial charges to the destination load and trip, and creates an audit log entry on both loads.

## Before You Start

You must have the **"Move Comchek"** permission for the Move option to appear, and the **"Add Accessorials"** permission for the move to complete. Confirm the following before proceeding:

* The e-check must not have been marked as paid.
* The e-check must not have been cancelled.
* The source trip must not be included in a draft or processed driver pay statement; if it is, the move will be blocked.
* The destination trip must exist and must be assigned to the same driver as the source trip.

## Steps

1. Navigate to the Accounting > E-Checks page. In the left navigation, select Accounting, then select E-Checks.
2. Locate the e-check to move. Use the date range filter or the money code search field to find the e-check. Confirm the row shows the correct load number and driver.
3. Initiate the move. Right-click the e-check row in the grid. Select Move from the context menu.
4. Enter the destination trip. In the move dialog, enter the trip number for the destination load. If the e-check is associated with a specific stop, select the correct stop on the destination trip. Click Confirm.

## Result

The e-check is reassigned to the destination load and trip. The accessorial charges linked to the e-check move to the new load. Both the source load and the destination load show an audit log entry recording the move.

## Variations

**If the e-check is paid and cannot be moved:** On the original load, mark the e-check as unavailable for settlement so it does not appear on the driver's pay statement. On the destination load, open the trip and add the amount as a driver accessorial charge using the same accessorial type.

**If the e-check has not been used but needs to go to a different load and cancelling is acceptable:** Cancel the e-check from Accounting > E-Checks (right-click, then select Cancel), then open the destination load, navigate to the trip, and issue a new e-check for the driver.

## Troubleshooting

### Move option is not visible in the context menu

Confirm your user account has the **"Move Comchek"** permission, and that the **"Add Accessorials"** permission is enabled so the move can complete. Ask your administrator to check your role in Management > Users if you are unsure. Also confirm you are right-clicking a row in the E-Checks grid: the Move action is only available from the E-Checks page (Accounting > E-Checks), not from within an individual load.

### Move is blocked with an error message

1. If the error states the e-check is paid, use the paid e-check variation above.
2. If the error states the trip is included in a driver statement, ask your accounting team to remove the trip from the draft statement before retrying the move. If the statement has already been processed, contact Alvys support with the load number and statement details.
3. If the error states the destination trip does not exist, verify the trip number is correct and that the trip is assigned to the same driver.

## FAQs

**Q: Can I move an e-check to a trip on the same load?**

**A:** Moving an e-check to a different trip on the same load is not supported through the Accounting > E-Checks move action. That type of reassignment happens automatically when a load is split in Loads and Trips.

**Q: Does moving an e-check change the money code or check number?**

**A:** No. The money code and check number remain the same after a move. Only the load number, trip number, and stop association are updated.

**Q: Can I move a cancelled e-check?**

**A:** No. Cancelled e-checks cannot be moved. Issue a new e-check on the destination trip instead.

## Go Deeper

* [E-Check Permissions](/en/help/administration/e-check-permissions)


# How to Set Up Balance-Based Deductions
Source: https://docs.alvys.com/en/help/accounting-settlements/how-to-set-up-balance-based-deductions

Configure balance-based recurring driver deductions in Alvys for loans, trailer rent, or equipment, using a starting balance that stops at zero.

## Overview

Balance-based deductions let you set up recurring driver deductions using a starting balance and a maximum amount rather than a fixed end date or occurrence count. Deductions apply automatically each period until the total balance is paid off, which is useful for loans, trailer rent, equipment payments, and similar long-term obligations.

The system tracks progress toward the total automatically and stops deductions when the balance reaches zero. This approach is useful for managing long-term driver obligations such as:

* Trailer or equipment rental
* Driver loans
* Insurance advances
* Training reimbursements

Once configured, the deduction runs on the specified schedule without requiring manual intervention each period.

## Before you start

Before setting up a balance-based deduction:

* The driver must be active in Alvys.
* The deduction category you want to use must support recurring schedules.
* All users have permission to manage deductions on driver profiles. No special role is required.

## Steps

1. Open the driver's Deductions tab:
2. Go to **Assets > Drivers**.
3. Select the driver you want to set up the deduction for.
4. Click the **Deductions** tab on the driver profile.
5. Add a new deduction:
6. Click **Add Deduction**.
7. Select the deduction category that applies (for example: Trailer Rent, Loan, Equipment).
8. Configure the balance-based fields:
9. **Frequency:** Select how often the deduction should run (for example: weekly, biweekly, monthly, every statement).
10. **Maximum Amount:** Enter the total amount owed. This is the full balance the driver needs to pay off.
11. **Starting Balance:** Enter any amount already paid, if applicable. Leave at zero if starting fresh.
12. **Payment Amount:** Enter the amount to deduct each period. When balance-based fields are filled in, the end date and occurrence count fields are automatically disabled; the system uses the balance to determine when to stop.

    <img alt="Upload balance-based-deduction-setup-form.png here. This image shows: the Add Deduction form on a driver profile with the Maximum Amount, Starting Balance, and Payment Amount fields filled in alongside the frequency selector." />

    *Upload balance-based-deduction-setup-form.png here. This image shows: the Add Deduction form on a driver profile with the Maximum Amount, Starting Balance, and Payment Amount fields filled in alongside the frequency selector.*
13. Save the deduction:
14. Click **Save**. The deduction is now active. It will run on the configured schedule and stop automatically when the remaining balance reaches zero.

## Result

After saving:

* The deduction appears in the Deductions tab with the Maximum Amount, Starting Balance, and Remaining Balance columns visible.
* Each time a statement is generated, the payment amount is deducted and the remaining balance updates.
* When the remaining balance reaches zero, the deduction stops automatically. No manual end date or occurrence count is needed.

## Variations

### Show Remaining Balance on Driver Statements

You can choose to display the remaining balance on the driver's statement so the driver can see what they still owe, even on periods when no deduction is taken. To enable this:

1. Open the deduction on the driver's Deductions tab.
2. Turn on **Show current balance on statements**.
3. Click **Save**.

When enabled, the balance appears on every statement that includes this driver, regardless of whether a deduction was applied in that period.

### Viewing Balance Columns in the Deductions List

The Deductions tab includes the following balance-related columns for quick review:

* **Maximum Amount:** The total originally owed.
* **Starting Balance:** The amount that was already paid when the deduction was created.
* **Remaining Balance:** The current outstanding balance, updated after each statement.

### Example

A driver rents a trailer for \$50,000:

* Maximum Amount: \$50,000
* Starting Balance: \$10,000 (already paid before setup)
* Payment Amount: \$1,000
* Frequency: Weekly

Each week, $1,000 is deducted from the driver's pay. The remaining balance updates after each statement. Deductions stop automatically when the remaining balance reaches $0.

## Troubleshooting

### Deduction is not stopping after the balance should be paid off

1. Open the deduction on the driver's Deductions tab and confirm the Maximum Amount and Starting Balance are entered correctly.
2. Confirm that statements have been generated for each period the deduction should have run. Balances update only when a statement is generated; deductions do not apply without a statement.
3. If the remaining balance appears incorrect, contact Alvys support with the driver name, deduction category, and the date range of statements generated.

### End date or occurrence fields are not available

This is expected behavior. When Maximum Amount and Starting Balance are entered, the system disables the end date and occurrence count fields because the balance controls when the deduction stops. If you need to use an end date instead, leave the Maximum Amount and Starting Balance fields empty.

## FAQs

**Q:** Who can set up balance-based deductions?

**A:** All users can create and manage deductions on driver profiles. No special role or permission is required.

**Q:** Can I use balance-based deductions for a one-time expense?

**A:** No. Balance-based deductions are designed for recurring payment schedules. For a one-time expense, create a standard one-time deduction without entering balance-based fields.

**Q:** What happens if no deduction is taken on a statement period?

**A:** If balance visibility is enabled on the deduction, the remaining balance still appears on the statement with no change to the amount. If visibility is not enabled, nothing appears for that period.

**Q:** Can I edit the payment amount after the deduction is created?

**A:** Yes. Open the deduction in the Deductions tab, update the Payment Amount, and save. Changes take effect on the next statement.

**Q:** When does the remaining balance update?

**A:** The remaining balance updates each time a driver statement (paystub) is generated that includes the deduction. It does not update between statements.


# Invoicing settings not reflected on the load
Source: https://docs.alvys.com/en/help/accounting-settlements/i-changed-the-invoicing-settings-but-it-s-not-reflected-on-the-load

Troubleshoot why updated Alvys invoicing settings do not appear on a load, and learn how company defaults and customer overrides apply to invoices.

<Note>
  Invoicing Settings (also called billing configuration or invoice preferences) control how Alvys generates, delivers, and validates invoices across your company. Global defaults are set in Company Profile and can be overridden at the individual customer level.
</Note>

## Overview

Invoicing Settings (sometimes referred to as billing configuration, invoice rules, or invoice preferences) give Admins and Partner Admins control over how invoices are created and delivered. Company-level defaults apply to all customers unless a customer profile overrides them. Five configuration areas are available: Delivery Methods, Document Requirements, Invoice Type, AutoMerge, and the global Invoicing Settings toggle.

## Where to Find It?

Navigate to **Settings** > **Invoicing** (under the **Operations** heading) for \*\*company-wide defaults. \*\*

<Note>
  <img alt="Image showing navigation to Alvys settings page" />

  \*Image showing navigation to Alvys settings page \*
</Note>

<Note>
  <img alt="Image showing the Invoicing settings page in the Company/Tenant profile with the five configuration areas." />

  \*Image showing the Invoicing settings page in the Company/Tenant profile with the five configuration areas. \*
</Note>

**To set overrides for a specific customer/broker**, open the customer or broker profile and scroll to the Invoicing Settings section.

<Note>
  <img alt="Image showing the Invoicing settings page in the Customer/Broker profile with the five configuration areas." />

  \*Image showing the Invoicing settings page in the Customer/Broker profile with the five configuration areas. \*
</Note>

## Key Concepts

* **Delivery Methods:** Controls how invoices reach the customer. Options are EDI, Email, Factoring Company, Online System, and Originals. Each method determines which integration or address Alvys uses when the invoice is sent.
* **Document Requirements:** Specifies which documents must be present on a load before an invoice can be generated. Requirements are set separately for the Released action and the Invoiced action.
* **Invoice Type:** Sets whether invoices are generated per load (Individual) or grouped into one periodic invoice per customer (Summary). See [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing) for the full workflow when using the Summary type.
* **AutoMerge:** Automatically consolidates all loads for a customer into one invoice draft. AutoMerge is required when the customer's Delivery Method is set to Factoring Company; it must be enabled for factoring customers to invoice correctly.
* **Invoicing Settings toggle:** When enabled at the company level, these settings apply as the default for all customers. Customer-level settings override the company default for that specific customer only.

## How to Use It?

For invoice generation workflows using these invoicing settings, see [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing). For the Summary Invoicing workflow, see [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing).

## Settings and Permissions

Only Admins and Partner Admins can modify Invoicing Settings in Company Profile. This is controlled by the **"Company Profile Manager"** access level, which is granted to the Admin, Support, and Partner Admin roles.

## Limits and Behavior

Changes to invoicing settings, such as customer details, delivery methods, or required documents, are instantly reflected on loads with a **'Released'** status or earlier. However, for loads in the **'Queued'** status or beyond, the invoicing settings will remain as they were at the time the invoice was generated.

Changing invoicing settings after an invoice has already been generated does not update that invoice automatically. To apply updated settings, revert the load to **Released**, update the settings, then regenerate the invoice.

## FAQs

**Q: Can I set different invoicing settings for different customers?**

**A:** Yes. Set company-wide defaults in Company Profile, then override any setting in the individual customer profile. The customer-level setting takes precedence over the company default.

**Q: What happens if I change document requirements after an invoice is already generated?**

**A:** The change applies to new invoices only. For an existing load, revert it to **Released**, update the requirements, and regenerate the invoice.

**Q: Is AutoMerge required for all customers?**

**A:** AutoMerge is required only when the customer's Delivery Method is set to Factoring Company. For other delivery methods it is optional.

**Q: Who can change Invoicing Settings?**

**A:** Only Admins and Partner Admins can modify Invoicing Settings in Company Profile.

## Go Deeper

* [Batch Invoicing](/en/help/accounting-settlements/batch-invoicing)
* [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)


# Off-cycle driver pay periods
Source: https://docs.alvys.com/en/help/accounting-settlements/off-cycle-driver-pay-periods

Generate a driver statement outside your normal pay period schedule to cover late paperwork or old trips that need a specific pay period date.

<img alt="" />

Sometimes drivers submit documents late and miss their chance to be paid for a trip they ran until the next cycle or they have old trips that need a specific pay period date on the statement.

**You can generate a statement outside of your normal pay periods by running off-cycle pay periods.** This is useful when you need to generate a statement early or issue a statement outside your regular cycle.


# Rebalancing driver statements
Source: https://docs.alvys.com/en/help/accounting-settlements/rebalancing-driver-statements

How to ensure drivers avoid receiving a negative statement amount.

When a driver's deductions exceed their earnings, the statement goes negative. Rather than removing deductions outright, split them and defer part of the balance to a future pay period — this keeps the driver whole on the current statement while preserving the full amount owed. Splitting deductions is the fastest and most reliable way to rebalance.

***

### From the Open tab

1. Open the driver's statement and review the negative deductions driving the balance down.
2. Decide how much of each deduction the driver can absorb this pay period.
3. Click the **more menu (⋯)** on the deduction you want to defer.
4. Select **Split** and enter the amount to carry forward.
5. **Approve** the split portion to a future pay period.
6. Repeat for any remaining deductions until the statement balance is no longer negative.
7. Confirm the statement total, then finalize as usual.

***

### From the Approved tab

1. Open the driver's statement and review the negative deductions on the approved statement.
2. Click the **more menu (⋯)** on the deduction you want to defer.
3. Select **Split** and enter the amount to carry forward.
4. **Approve** the split portion to a future pay period **OR** **unapprove the split deductions** so they drop off the current draft statement. *(This step is required — without it, the deferred amounts stay on the current statement and the balance won't rebalance.)*
5. Repeat for any remaining deductions until the balance is no longer negative.
6. Confirm the statement total, then finalize as usual.


# Split Fuel Transactions
Source: https://docs.alvys.com/en/help/accounting-settlements/split-fuel-transactions

Break down a single fuel card transaction into diesel, cash advance, grocery, and maintenance line items on the Alvys Fuel Report for cleaner accounting.

## Overview

Split Fuel Transactions gives visibility into individual purchase categories within a single fuel card transaction, so dispatchers and accounting teams can distinguish driver expenses from company expenses on the Fuel Report.

When a driver uses a fuel card at a store or fuel pump, multiple types of purchases may occur in a single transaction: diesel fuel, cash advances, groceries, maintenance items, and more. Previously, all categories within one transaction were grouped into a single line item labeled as a fuel transaction for the truck. Split Fuel Transactions separates each purchase category into its own row in the Fuel Report, making it possible to identify exactly what was purchased, which expenses belong to the driver, and which belong to the company.

Also known as: split fuel, transaction categories, fuel card line items, fuel category breakdown.

## How it works

When a transaction contains items from multiple purchase categories, the Fuel Report shows one row per category instead of a single combined row. For example, if a driver's fuel card was used at a stop that included diesel fuel, a cash advance, and a grocery purchase, the Fuel Report will display three separate rows for that transaction, one for each category.

Each row shows the category detail, the amount, and the associated driver, allowing you to assess whether each line item is a driver expense or a company expense.

If a fuel card transaction contains only one purchase category (for example, diesel only), it appears as a single row. The split behavior applies only when multiple categories are present in the same transaction.

Before you start:

* Your fuel card provider integration must be connected and active in Alvys (Management > Integrations > Fuel).
* Drivers must have their fuel card numbers linked to their driver profiles (Assets > Drivers).
* All users have access to the Fuel Report and can view split transaction rows.

## How to use

1. Go to **Reports > Fuel Report**. The Fuel Report displays all imported fuel card transactions for your drivers.
2. Review the split transaction rows. When a transaction contains items from multiple purchase categories, the report shows one row per category, each showing the category detail, the amount, and the associated driver.
3. Take action based on each category:

   * Driver expenses (such as cash advances or personal purchases) may need to be set up as deductions on the driver's profile.
   * Company expenses (such as maintenance items) are recorded separately for accounting purposes.

After this workflow, the Fuel Report shows one row per purchase category for any multi-category fuel card transaction, each row clearly identifies the purchase category, amount, and associated driver, and you can distinguish driver expenses from company expenses within the same transaction event.

## Troubleshooting

### Expected category rows are not appearing

1. Confirm the fuel transaction has been imported into the Fuel Report (either via automatic sync or manual CSV upload).
2. Confirm your fuel card provider sends category-level detail in their transaction data. Not all providers supply category breakdowns in their export files.
3. If you expected multiple category rows but see only one, the provider may have grouped the transaction before sending it to Alvys. Contact your fuel card provider to confirm whether category-level data is included in their file format.
4. If category detail is expected and still not appearing, contact Alvys support with the transaction date, driver name, and provider name.

## FAQs

**Q: Does Split Fuel Transactions change anything about how I upload or sync fuel transactions?**

**A:** No. You use the same Fuel Report and the same upload or sync process as before. Split Fuel Transactions only changes how the report displays transactions that contain multiple purchase categories.

**Q: What purchase categories can appear as separate rows?**

**A:** Categories depend on what the fuel card provider includes in their transaction data. Common categories include fuel for the truck, cash advance, groceries, and maintenance items. The exact categories available vary by provider.

**Q: Who has access to the Fuel Report?**

**A:** All users have access to the Fuel Report.


# Why you can't release or invoice a load in Alvys
Source: https://docs.alvys.com/en/help/accounting-settlements/why-can-t-i-release-or-invoice-a-load-in-alvys-and-how-can-i-resolve-it

In Alvys, issues with releasing or invoicing a load can arise due to missing information, incorrect settings, or document-related requirements.

<Note>
  This article explains the specific reasons a load cannot be released to billing or invoiced in Alvys, including load status requirements, missing documents, customer configuration, and invoicing settings, and the exact steps to resolve each one.
</Note>

## Overview

You try to release a load to billing or generate an invoice, and the action is blocked. Common symptoms include: the Release to Billing button is grayed out or returns an error; the Generate Invoice button does not appear on the load; or an invoice you generated does not show up in a batch report. This article covers invoice generation, release to billing, summary invoicing, TONU loads, supplemental invoicing, split loads, and related issues (also referred to as: billing release issues, invoice blocked, can't release load, Generate Invoice missing).

Each issue has a distinct cause. Match your symptom to the cause below before proceeding to the Resolution section.

## Causes

### Load is not in a releasable status

* The load must be in **Delivered** or **TONU** status before it can be released to billing. If the load is in any other status such as **In Transit**, **Dispatched**, **Open**, or a post-billing status like **Released**, **Invoiced**, or **Completed**, the release action will be blocked.

### Missing required documents

* Your invoicing settings may require one or more specific documents before the load can be released or invoiced. If any required document is absent, the system returns the error: "Load cannot be released: missing required documents." Required document types may include: **Proof of Delivery**, **Bill of Lading**, **Customer Rate Confirmation**, **Receipt**, and **Scale Ticket**. Which documents are required depends on your customer or subsidiary invoicing configuration.

### Corrupted or empty document file

* A document uploaded with a file size of 0 bytes will be rejected during invoice generation even if the document type appears in the load's document list.

### Document name does not match the required type

* Document names must match the type configured as required in invoicing settings. If a document is uploaded under the wrong type (for example, uploaded as "Unclassified" when "Customer Rate Confirmation" is required), the requirement will not be satisfied.

### No invoice delivery method configured

* Every customer subsidiary must have at least one invoice delivery method selected. Without a delivery method, invoicing is blocked with the message "Missing invoice delivery method(s)." The available delivery methods are: **EDI**, **Email**, **Factoring Company**, **Online System**, and **Originals**.

### Missing invoicing email address

* If **Email** is one of the configured delivery methods, the customer record must have a billing contact email address. Without it, invoice delivery cannot proceed.

### Customer is configured for Summary invoicing

* If the customer's Invoice Type is set to **Summary**, the Generate Invoice button will not appear on individual loads. Summary invoicing batches multiple loads into a single invoice and is processed through Accounting > Summary Invoicing, not on the individual load.

### Load appears invoiced but the customer invoice document is missing

* A load may appear to be in **Invoiced** status because the carrier trips have been invoiced, while the customer-facing invoicing step has not been completed. These are separate actions.

### Invoice not appearing in batch report after rebilling

* If an invoice does not appear in the batch report after rebilling, the load may not have been moved back to **Released** status before the invoice was changed, or the wrong customer or subsidiary was selected when generating the new invoice.

### Order number exceeds the 30-character limit

* Order numbers (also called reference numbers) have a maximum length of 30 characters. An order number exceeding 30 characters may cause errors during invoice generation or EDI transmission.

### Supplemental invoice cannot be generated

* If a load has already been invoiced and you attempt to generate an additional invoice, the system requires pending changes on the load such as updated rates or new fees. Without pending changes, a supplemental invoice cannot be generated.

## Resolution

### Load is not in a releasable status

1. Open the load from the Load Board and confirm its current status in the load header.
2. If the load is in **Delivered** status, proceed to release it to billing using the Release to Billing action.
3. If the load is in **TONU** status, it can be released or invoiced directly without requiring a separate release step.
4. If the load is in a status earlier than **Delivered** (such as **In Transit** or **Dispatched**), update the load's stop times and statuses so all stops are marked complete, bringing the load to **Delivered** status before releasing.
5. If the load is already in a post-release status (**Released**, **Queued**, **Invoiced**, **Financed**, or **Completed**), reverting it requires manual intervention. Check the load status revert options first; if none apply, contact Alvys support with the load number.

### Missing required documents

1. Open the customer record in Company Management.
2. Click the Invoicing Settings button (gear icon) for the relevant subsidiary.
3. Review the list of required documents to confirm which types are required.
4. Open the load and go to the Documents section.
5. Upload the missing document with the type set to match exactly what is required in your invoicing settings.
6. Note: by default, only an actual **Proof of Delivery** satisfies a POD requirement — a Bill of Lading does not stand in for it. A BOL only counts as the POD when the subsidiary has opted in via **Use BOL if there is no POD** in Invoicing Settings, and only when no POD is uploaded on the load. If both a POD and a BOL are present, the POD always wins. See [Invoicing Settings](/en/help/accounting-settlements/invoicing-settings#proof-of-delivery-and-bill-of-lading) for how to enable the fallback.

### Corrupted or empty document file

1. Open the load and go to the Documents section.
2. Identify any file showing a size of 0 bytes.
3. Delete the corrupted file.
4. Upload a valid version of the document.

### Document name does not match the required type

1. Open the load and go to the Documents section.
2. Identify the document that does not match the required type.
3. Re-upload the document and set the type to match the name required in your invoicing settings exactly (for example, "Customer Rate Confirmation").

### No invoice delivery method configured

1. Open the customer record in Company Management.
2. Click the Invoicing Settings button (gear icon) for the subsidiary.
3. Select at least one delivery method: **EDI**, **Email**, **Factoring Company**, **Online System**, or **Originals**.
4. Save your changes.

### Missing invoicing email address

1. Open the customer record in Company Management.
2. Enter the billing contact email address in the Invoicing Email field.
3. Save your changes. If you deliver invoices via **EDI**, **Factoring Company**, **Online System**, or **Originals** only, an email address is not required.

### Customer is configured for Summary invoicing

1. Open the customer record in Company Management, click the Invoicing Settings gear, and review the Invoice Type setting.
2. If Invoice Type is set to **Summary** and you want to invoice per load, change it to **Individual** and save. The Generate Invoice button will then appear on each load.
3. If the customer should remain on Summary invoicing: release each load to billing individually from the Load Board, then go to Accounting > Summary Invoicing and process the invoice from there.

### Load appears invoiced but customer invoice document is missing

1. Open the load and confirm the load-level status.
2. If carrier trips show as invoiced but the customer load does not, complete the customer invoicing step by generating an invoice from the load.
3. If the customer is configured for **Summary** invoicing, confirm the load has been processed through Accounting > Summary Invoicing.

### Invoice not appearing in batch report after rebilling

1. Confirm the load was moved back to **Released** status before the invoice was changed.
2. Confirm the correct customer and subsidiary are selected.
3. Regenerate the invoice, then refresh the batch report.

### Order number exceeds the 30-character limit

1. Open the load and locate the order number field.
2. Shorten the order number to 30 characters or fewer.
3. Save the load and retry invoice generation.

### Supplemental invoice cannot be generated

1. Confirm there are pending changes on the load, such as rate adjustments or new accessorial fees.
2. If no changes are pending, make the necessary update to the load.
3. Once a pending change exists, generate the supplemental invoice from the load.

### TONU loads

* Loads in **TONU** (Truck Ordered, Not Used; also called truck order not used or truck ordered not used) status can be invoiced directly without being released first. TONU loads also skip certain document requirements such as Proof of Delivery and Receipt, because no delivery occurred.

### Split loads

* For split loads, ensure you are working in the correct load section that corresponds to the specific part of the load being billed. Each split generates its own billable portion and must be released and invoiced separately.

### Closing a load with a zero-dollar balance

* To close a load on the billing side when the customer owes nothing: generate an invoice for the load, then apply a manual payment of \$0. The system will automatically move the load to **Completed** status.

## If That Didn't Work

If you have confirmed the load is in **Delivered** or **TONU** status, all required documents are uploaded with correct names and types, at least one delivery method is configured, the customer Invoice Type is correct, and the issue still persists: contact Alvys support with the load number and a description of the error message you received.

## FAQs

**Q: Why can't I generate an invoice for a load in Released status?**

**A:** Check for missing required documents (Proof of Delivery, Customer Rate Confirmation), a missing invoice delivery method, or a missing billing contact email address. Also verify the customer's Invoice Type; if it is set to **Summary**, the Generate Invoice button will not appear on individual loads.

**Q: Why doesn't the Generate Invoice button appear on my load?**

**A:** The most common reason is that the customer is configured for **Summary** invoicing. In Summary mode, invoices are generated through Accounting > Summary Invoicing rather than on individual loads. Check the customer's Invoicing Settings in Company Management to confirm.

**Q: Does a TONU load need to be released before it can be invoiced?**

**A:** No. Loads in **TONU** status can be invoiced directly without a prior release step. They also skip document requirements such as Proof of Delivery and Receipt.

**Q: Can I invoice a load that is not in Delivered status?**

**A:** Releasing to billing requires the load to be in **Delivered** or **TONU** status. Loads in earlier statuses (**In Transit**, **Dispatched**, etc.) must reach **Delivered** before they can be released.

## Related

* [Releasing a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)
* [Invoicing Settings](/en/help/accounting-settlements/invoicing-settings)
* [Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)
* [Billing Permissions](/en/help/administration/billing-permissions)


# Additional Load Permissions
Source: https://docs.alvys.com/en/help/administration/additional-load-permissions

Configure the four extra load permissions that control Load Template access and Load Rate History visibility for Alvys rates and tenant pricing data.

<Note>
  This article explains the four additional load permissions in Alvys that govern Load Templates and Load Rate History: who can view and use saved load templates, who can create and manage them, and which type of historical rate data a user can access.
</Note>

## Overview

Alvys organizes load permissions into sub-categories. This article covers four permissions outside the core load management and dispatch groups: two that control access to Load Templates, and two that control access to Load Rate History. Together they govern whether a user can build loads faster using saved configurations, and whether that user can see historical pricing data to inform rate decisions.

Load Templates help teams create recurring loads without re-entering the same details each time. Load Rate History gives users market context and company-specific pricing data to support rate negotiations and pricing decisions.

## Where to Find It

These permissions are set at the individual user level inside the User Management interface. To reach it:

* Select your username in the bottom-left corner.
* Navigate to **Management > Company Profile** and select the **Users** tab.

<Note>
  <img alt="Image showing navigation to Company profile" />

  \*Image showing navigation to Company profile \*
</Note>

* Choose an existing user to edit, or select **Add User** to create a new profile.

<Note>
  <img alt="Company Profile with the Users tab selected in the left navigation." />

  *Company Profile with the Users tab selected in the left navigation.*
</Note>

* Scroll to the **Permissions** section.
* Locate the **Load Rate History** category to find the **View Alvys Rates History** and **View Tenant Rates History** checkboxes.

<Note>
  <img alt="Permissions panel with the Load Rate History category expanded, displaying View Alvys Rates History and View Tenant Rates History checkboxes." />

  *Permissions panel with the Load Rate History category expanded, displaying View Alvys Rates History and View Tenant Rates History checkboxes.*
</Note>

* Locate the **Load Templates** category to find the **View Load Templates** and **Manage Load Templates** checkboxes.

<Note>
  <img alt="Shows: Permissions panel with the Load Templates category expanded, displaying View Load Templates and Manage Load Templates checkboxes." />

  *Shows: Permissions panel with the Load Templates category expanded, displaying View Load Templates and Manage Load Templates checkboxes.*
</Note>

Modifying any permission requires the logged-in user to hold the **"SetPermission"** permission in the Management category. Without it, the user profile is visible but no checkboxes can be changed.

<Warning>
  ⚠️ To modify permissions, the user making the change must hold the **"SetPermission"** permission, found in the Management category. See the Management and Privacy Permissions article for details.
</Warning>

## Key Concepts

**What is a lane?**

A lane is a defined origin-to-destination freight route, such as Chicago, IL to Atlanta, GA for a 53-foot dry van. Rate history is organized by lane and equipment type.

**What is a load template?**

A load template is a pre-saved set of load details (shipper address, consignee address, commodity, equipment type, special instructions) that can be applied to a new load in a single step. Templates are most useful for dedicated lanes and recurring loads.

## Settings & Permissions

### View Load Templates

**"ViewLoadTemplates"** controls whether a user can access the Load Templates page, view the existing template library, and build new loads from those templates. Selecting a template when creating a load automatically populates the load fields with the template's saved information; the user can then edit any field before saving.

<Note>
  <img alt="Load Templates page accessed from the Loads navigation, with the template library list and a button to create a new load from a template." />

  *Load Templates page accessed from the Loads navigation, with the template library list and a button to create a new load from a template.*
</Note>

<Note>
  <img alt="Load Templates list page showing saved templates with template name, route, and equipment type columns." />

  *Load Templates list page showing saved templates with template name, route, and equipment type columns.*
</Note>

By default this permission is granted to: **Partner Admin**, **Admin**, **Operation Manager**, **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, and **Office Admin**. It is not granted by default to the **Safety** or **Driver** roles.

<Info>
  ✅ Best practice: Grant View Load Templates to all dispatchers who create loads regularly. Combine it with a well-organized, clearly named template library so dispatchers can find the right template quickly.
</Info>

### Manage Load Templates

**"ManageLoadTemplates"** allows a user to create new templates, edit existing ones, and delete templates that are no longer needed. It is the administrative complement to View Load Templates: where View is for using the library, Manage is for building and maintaining it.

A user with Manage Load Templates can:

* Create new load templates
* Edit existing templates
* Delete templates that are outdated or duplicated

<Note>
  <img alt="Load Templates page with Edit and Delete action buttons visible on template rows, available only to users with the Manage Load Templates permission." />

  *Load Templates page with Edit and Delete action buttons visible on template rows, available only to users with the Manage Load Templates permission.*
</Note>

Having Manage Load Templates implicitly includes all viewing and building capabilities.

By default this permission is granted to: **Partner Admin**, **Admin**, **Operation Manager**, and **Office Admin**. It is not granted by default to **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, **Safety**, or **Driver** roles.

<Info>
  ✅ Best practice: Limit Manage Load Templates to Office Admins and Operations Managers who are responsible for maintaining the template library. Most operational users should have View Load Templates without Manage.
</Info>

### View Alvys Rates History

**"ViewAlvysRateHistory"** enables a user to access rate history data aggregated anonymously across all Alvys tenants. With this permission, users gain a market-level perspective: what rates have been charged and paid for a lane across the entire Alvys platform, not just within their own company.

The **Rates** button in the Money Box footer on a trip's detail page becomes visible when a user has either View Alvys Rates History or View Tenant Rates History. Clicking it opens a dialog showing historical pricing data.

<Note>
  <img alt="Load Board with a load selected and the side tray open, showing trip detail including the Money Box." />

  *Load Board with a load selected and the side tray open, showing trip detail including the Money Box.*
</Note>

<Note>
  <img alt="Shows: Money Box footer on the trip detail page with the Rates button highlighted." />

  * Shows: Money Box footer on the trip detail page with the Rates button highlighted.\*
</Note>

The Alvys Rates History chart displays the **median rate** for a specific lane. Filters include Equipment Type, Deadhead Radius (DH-O origin / DH-D destination), and Timeframe (5, 15, or 30 days).

The chart legend shows:

* 🟠 Orange line: Shipper-to-Carrier contract rates (stable, direct-to-shipper pricing)
* 🟢 Green line: Broker-to-Carrier spot market rates (volatile, reflects current carrier availability)

<Note>
  <img alt="Shows: Alvys Rates History chart with orange Shipper-Carrier contract rate line and green Broker-Carrier spot market line, with Equipment Type, Deadhead Radius, and Timeframe filter controls." />

  *Shows: Alvys Rates History chart with orange Shipper-Carrier contract rate line and green Broker-Carrier spot market line, with Equipment Type, Deadhead Radius, and Timeframe filter controls.*
</Note>

Alvys aggregates rate data anonymously. Individual company identities and specific transaction records are never disclosed. Users see only aggregated, statistical rate information.

By default this permission is granted to: **Partner Admin**, **Admin**, and **Operation Manager**. It is not granted by default to **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, **Office Admin**, **Safety**, or **Driver** roles.

<Info>
  💡 Best practice: Grant View Alvys Rates History to dispatchers, pricing staff, and operations managers who are regularly involved in rate setting or carrier negotiations.
</Info>

### View Tenant Rates History

**"ViewTenantRateHistory"** gives a user access to your company's own historical rate data for specific lanes: what rates your company has actually charged customers and paid carriers on each lane, over time.

The **Rates** button in the Money Box footer becomes visible when the user has View Tenant Rates History OR View Alvys Rates History. Either permission makes the button visible. When both permissions are granted, the rates dialog shows two charts side by side: a Tenant chart (your company's history) on the left, and an Alvys market benchmark chart on the right.

<Note>
  <img alt="Money Box footer with the Rates button visible (same button as in View Alvys Rates History)." />

  *Money Box footer with the Rates button visible (same button as in View Alvys Rates History).*
</Note>

<Note>
  <img alt="Rate history dialog with the Tenant chart (company's own historical rates) on the left and the Alvys market benchmark chart on the right, displayed side by side." />

  *Rate history dialog with the Tenant chart (company's own historical rates) on the left and the Alvys market benchmark chart on the right, displayed side by side.*
</Note>

To open rate history, you need **"ViewTenantRateHistory"**. Without it, you see a permissions error even if you also have **"ViewAlvysRateHistory"**. With **"ViewTenantRateHistory"** in place, **"ViewAlvysRateHistory"** controls whether market-wide data appears alongside your company's data.

By default this permission is granted to: **Partner Admin**, **Admin**, and **Operation Manager**. It is not granted by default to **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, **Office Admin**, **Safety**, or **Driver** roles.

<Info>
  💡 Best practice: Grant View Tenant Rates History alongside View Alvys Rates History for a complete view of both company-specific historical rates and platform-wide market benchmarks.
</Info>

## Limits & Behavior

* The **Rates** button in the Money Box is hidden unless the user holds at least one of the two Load Rate History permissions.
* Rate history is filtered by equipment type, deadhead radius, and timeframe (5, 15, or 30 days). No other filter options are available.
* Load templates are shared across the team. Deleting a template affects all users who rely on it.
* Building a load from a template does not modify the original template. It is a read-level action covered by **"ViewLoadTemplates"**.

## FAQs

**Q: What is the difference between View Alvys Rates History and View Tenant Rates History?**

**A:** View Alvys Rates History provides an anonymous, aggregated market view of rates paid across the entire Alvys platform. View Tenant Rates History shows only your own company's historical data for specific lanes.

**Q: Why are Load Rate History permissions restricted to administrators by default?**

**A:** Historical rate data is considered sensitive pricing intelligence. Restricting it to admin-level roles by default protects your company's competitive positioning. If dispatchers or sales agents need this data for negotiations, the permissions must be granted explicitly.

**Q: Can a user build a load from a template if they only have View Load Templates?**

**A:** Yes. **"ViewLoadTemplates"** allows users to view the template library and generate new loads from those templates. Building a load from a template is a view-level action because it does not change the original template.

**Q: What is the difference between View Load Templates and Manage Load Templates?**

**A:** **"ViewLoadTemplates"** is for using the library to create loads quickly. **"ManageLoadTemplates"** is an administrative permission that allows a user to create, edit, or delete the templates that the rest of the team relies on.

**Q: Why does the Office Admin role have Manage Load Templates while Dispatchers do not?**

**A:** The Office Admin role is responsible for maintaining shared resources and workflow configurations. Dispatchers are operational users who need to use templates for efficiency but typically should not have the authority to modify the master template library.

**Q: Where is the Rates button to view rate history?**

**A:** The **Rates** button is in the footer of the **Money Box** on a trip's detail page. It is hidden if the user does not have at least one Load Rate History permission.

**Q: What exactly is a "lane" in the context of rate history?**

**A:** A lane is a defined route from a specific origin to a destination; for example, Chicago, IL to Atlanta, GA. Rate history shows what has been charged or paid for specific equipment types on these routes over 5, 15, or 30-day timeframes.

## Go Deeper

* [User Roles and Permissions Collection](/en/help/administration/user-roles-permissions-collection)
* [Contracted Lanes Permissions](/en/help/administration/contracted-lanes-permissions)


# App Permissions
Source: https://docs.alvys.com/en/help/administration/app-permissions

Set the nine mobile App permissions that decide what drivers and carriers see in the Alvys app, from load pay and documents to on-the-road edits.

<Note>
  App permissions control what drivers and carrier users can see and do inside the Alvys mobile app: this article explains each of the nine App permissions, where to find them, and how to decide which drivers should have them.
</Note>

## Overview

App permissions (also called mobile permissions or driver app settings) govern the mobile experience for drivers and carriers using the Alvys app. These permissions are separate from the web-based permissions that control what back-office staff can do in the TMS.

App permissions sit at the intersection of operations, finance, and privacy. They determine whether a driver can see their pay rate before delivery, whether they can edit load information while on the road, and which documents are accessible during a trip.

Understanding these settings matters for every administrator and operations manager because the choices made here shape the driver experience and determine what information carriers can access. Some companies choose full transparency — showing pay, documents, and trip value. Others take a more restricted approach for privacy or security reasons. Both approaches are valid. This article explains what each permission does so you can make the right decisions for your operation.

## Where to Find It

App permissions are managed from the user profile in the Alvys web application.

<Warning>
  ⚠️ To modify any user's permissions, the logged-in user must have the **"Set Permission"** permission (located in the Management category), or hold the Admin, Partner Admin, Operation Manager, or Support role. · Without **"Set Permission"**, a user can view a profile but cannot change any permissions. · For more information, see the [Management & Privacy Permissions article](/en/help/administration/management-privacy-permissions).
</Warning>

To reach App permissions from the user profile:

1. Select your **username** in the bottom-left corner of the screen.

   <img alt="Notion Image" />

   <img alt="Username location in bottom-left navigation." />

   \*Username location in bottom-left navigation. \*
2. Navigate to **Company Profile** and select the **Users** tab.
3. Select an existing user to **Edit**, or select **Add User** to create a new profile.

<Note>
  📷

  <img alt="Company Profile Users tab" />

  *Company Profile Users tab*
</Note>

1. Scroll to the **Permissions** section and locate the **App** category.
2. The App category contains nine checkboxes: **"View Trip Value"**, **"Issue ECheck"**, **"Cancel ECheck"**, **"View Customer Rate Confirmation"**, **"View Carrier Rate Confirmation"**, **"View Payable Amount"**, **"View App Paystubs"**, **"Edit Trailer Number"**, and **"Send Carrier Rate Confirmation Email"**.

<Note>
  📷

  <img alt="App permissions checkbox list in the Permissions section." />

  \*App permissions checkbox list in the Permissions section. \*
</Note>

## Key Concepts

**App permissions vs. web permissions:** Web permissions control what back-office users see and do in the TMS. App permissions control what drivers and carriers see and do in the mobile app. A permission that appears in both the App category and another category (such as Rates or E-Check) is the same permission: enabling it in one place enables it everywhere.

**Driver app onboarding:** When an administrator creates a new driver in the Driver List, they enter the driver's mobile phone number. This number is the unique identifier that connects the driver to the Alvys mobile app. Once the driver downloads the app and enters their phone number, the system sends a one-time SMS verification code. After successful verification, Alvys automatically creates a user account with the Driver role under Company Profile > Users. The administrator can then assign App permissions to that account.

<Info>
  💡 Driver app onboarding flow: Driver record created in Driver List (with mobile number) → Driver downloads app → Driver enters phone number → SMS verification code sent → Driver verifies → System auto-creates Driver user account under Company Profile > Users → Administrator assigns App permissions.
</Info>

## How to Use It

App permissions are set per user. There is no global default that applies to all drivers at once. Each driver's App permissions must be configured individually on their user profile.

For step-by-step instructions on navigating to and changing a user's permissions, see the [Management & Privacy Permissions article](/en/help/administration/management-privacy-permissions).

## Settings & Permissions

### "View Trip Value"

**"View Trip Value"** controls whether a driver can see the total value of a trip in the mobile app. When this permission is not granted, the trip value field is hidden on the load screen.

This permission also appears in the Rates category, where it governs trip value visibility on the web interface load board and Money Box components. It is the same permission: enabling it in either location enables it in both.

<Note>
  📷

  <img alt="Mobile app load screen showing trip value field" />

  *Mobile app load screen showing trip value field*
</Note>

<Info>
  💡 This permission controls trip value visibility across both the web interfaces. For full documentation of its web behavior, see the [Rates Permissions article](/en/help/administration/rates-permissions).

  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Info>

<Info>
  💡 Best practice: Grant **"View Trip Value"** to owner-operators who need to verify their trip payments in the mobile app. For company drivers, evaluate whether visibility of trip values is necessary before enabling this permission.
</Info>

### "Issue ECheck"

**"Issue ECheck"** controls whether a driver can generate e-checks through the mobile app. E-checks are electronic payment instruments used to provide drivers with funds for fuel, lumper fees, and other road expenses.

Generating e-checks requires an active e-check integration. The company must be integrated with Comdata or EFS for this permission to function.

This permission also appears in the E-Check category, where it controls e-check issuance through the web interface. It is the same permission in both places.

<Note>
  📷

  <img alt="Mobile app e-check generation screen." />

  \*Mobile app e-check generation screen. \*

  <img alt="E-check issuance form in the mobile app" />

  *E-check issuance form in the mobile app*
</Note>

<Info>
  💡 For full documentation of this permission's behavior in the web interface, see the [E-Check Permissions article](/en/help/administration/e-check-permissions).

  <img alt="E-Check category permission checkbox showing Issue ECheck." />

  *E-Check category permission checkbox showing Issue ECheck.*
</Info>

<Info>
  💡 Best practice: Grant **"Issue ECheck"** only to drivers who have the authority to commit company funds for road expenses. Also ensure that an e-check spending cap is set for any driver receiving this permission.

  <img alt="E-check cap field on the driver profile." />

  *E-check cap field on the driver profile.*
</Info>

### "Cancel ECheck"

**"Cancel ECheck"** controls whether a driver can cancel a previously issued e-check through the mobile app. Canceling an e-check voids the payment before the funds are cashed, reversing the authorization.

This is a corrective action used when an e-check was issued in error, when the driver no longer needs the funds, or when the amount was incorrect. Canceling from the mobile app allows a quick response to changing field conditions without requiring a call to the back office.

This permission also appears in the E-Check category and controls the same action in both the web interface and the mobile app.

<Note>
  📷

  <img alt="Mobile app e-check cancellation screen" />

  *Mobile app e-check cancellation screen*
</Note>

<Info>
  💡 For full documentation of this permission's behavior in the web interface, see the [E-Check Permissions article](/en/help/administration/e-check-permissions).

  <img alt="E-Check category permission checkbox showing Cancel ECheck" />

  *E-Check category permission checkbox showing Cancel ECheck*
</Info>

<Info>
  💡 Best practice: Grant **"Cancel ECheck"** alongside **"Issue ECheck"**. Drivers who can generate e-checks should typically also be able to cancel them to correct errors quickly.
</Info>

### "View Customer Rate Confirmation"

**"View Customer Rate Confirmation"** allows a driver or carrier user to open and read the customer rate confirmation document in the mobile app. This document shows the rate your company has agreed to receive from the customer for the load: it is the rate your company charges the customer, not the rate paid to the driver or carrier.

The document typically includes the customer's name, the contracted rate, the lane, commodity, and terms. This is normally a back-office document between your company and your customer. Granting this permission means the driver can see what the customer is paying your company, which is separate from what the driver or carrier is being paid.

There are legitimate operational reasons for a driver to see this document. For example, a driver representing your company at a shipper's dock may need to reference the agreed rate for paperwork matching. However, this is a sensitive business document. If the customer rate is significantly higher than the driver or carrier rate, a driver who can see both values can infer your company's margin on the load.

<Note>
  📷

  <img alt="Mobile app customer rate confirmation document view." />

  *Mobile app customer rate confirmation document view.*
</Note>

<Info>
  💡 Best practice: Do not grant **"View Customer Rate Confirmation"** to all drivers. Limit this permission to scenarios where it is operationally necessary, such as a broker-carrier relationship where the carrier legitimately needs the customer document for bill of lading or customs purposes.
</Info>

### "View Carrier Rate Confirmation"

**"View Carrier Rate Confirmation"** allows a driver to open and read their own carrier rate confirmation document in the mobile app. This document states the rate your company has agreed to pay the carrier for the load. It includes the lane, load details, agreed rate, and any special terms specific to the carrier.

Without this permission, carrier rate confirmation documents are hidden in the mobile interface. With it, the driver can open and review the document directly on their device.

<Note>
  📷

  <img alt="Mobile app carrier rate confirmation document view." />

  \*Mobile app carrier rate confirmation document view. \*
</Note>

<Info>
  💡 Best practice: Grant **"View Carrier Rate Confirmation"** to owner-operators and leased operators who need to verify their contracted rate before or during a load. This permission is standard for carriers operating under their own authority.
</Info>

### "View Payable Amount"

**"View Payable Amount"** allows a driver to see the specific dollar amount they will be paid for a trip directly in the mobile app.

This is different from **"View Trip Value"**. While **"View Trip Value"** shows the total value of the trip, **"View Payable Amount"** shows the portion payable to the driver specifically. The payable amount includes the base rate, accessorials, deductions, and settlement items to calculate the net amount owed to the driver.

Without this permission, no pay figure appears on the load screen. Pay information is only accessible to the driver after settlement processing is complete. For example, if a load pays $2,200 total and the driver is on a 70% split, **"View Payable Amount"** would show $1,540 — the driver's share — rather than the total rate.

<Note>
  📷

  <img alt="Mobile app load screen showing payable amount field." />

  * Mobile app load screen showing payable amount field.\*
</Note>

<Info>
  💡 Best practice: Grant **"View Payable Amount"** to owner-operators and drivers on percentage-based pay plans who need to verify their earnings per load. For salaried drivers, evaluate whether per-load pay visibility is necessary.
</Info>

### "View App Paystubs"

**"View App Paystubs"** allows a driver to access their historical pay stubs directly within the Alvys mobile app. Drivers with this permission can browse their pay history in the app, including settlement amounts, deductions, advance repayments, and load-by-load breakdowns for each pay period.

Without this permission, no pay history section appears in the app and the driver can only view current load information. With this permission, a Pay Statements section appears in the driver profile within the app.

<Note>
  📷

  <img alt="Mobile app Pay Statements section in driver profile." />

  *Mobile app Pay Statements section in driver profile.*
</Note>

<Info>
  💡 Best practice: Grant **"View App Paystubs"** to all drivers who use the mobile app. This provides convenient self-service access to pay history and reduces calls to the back office for pay questions.
</Info>

### "Edit Trailer Number"

**"Edit Trailer Number"** allows a driver to change the trailer number on their load directly within the Alvys mobile app. The trailer number identifies the physical trailer being hauled. Without this permission, the trailer number can only be updated by a dispatcher or back-office user in the TMS.

Drivers frequently swap equipment at drop yards or due to mechanical issues. Enabling this permission allows them to update the system in real time, keeping fleet tracking and compliance records accurate without requiring a call to dispatch.

<Note>
  📷

  <img alt="Mobile app trailer number field on load screen." />

  \*Mobile app trailer number field on load screen. \*
</Note>

<Info>
  💡 Best practice: Grant **"Edit Trailer Number"** to all company drivers and owner-operators. The frequency of legitimate trailer swaps in normal operations makes this a practical necessity. Train drivers to update the trailer number immediately upon a swap, not at the end of the day, to keep records current.
</Info>

### "Send Carrier Rate Confirmation Email"

**"Send Carrier Rate Confirmation Email"** controls whether a driver or carrier user can trigger the system to send a carrier rate confirmation email directly from the mobile app. This allows the driver or carrier to request or resend the carrier rate confirmation document to an email address without involving a back-office user.

This permission is relevant in scenarios where a carrier needs a copy of their rate confirmation sent to a specific contact for record-keeping or dispatch purposes.

## Limits & Behavior

* App permissions apply per user account. There is no batch assignment for all drivers at once.
* Permissions that appear in both the App category and another category (Rates, E-Check) are the same permission. Enabling either instance enables both.
* **"Issue ECheck"** and **"Cancel ECheck"** require an active Comdata or EFS integration to function. Granting the permissions without an active integration will not produce any error — the e-check functionality simply will not appear.
* **"View Payable Amount"** reflects the driver's net payable amount after deductions and accessorials. It does not show the full load rate unless the driver is on a 100% pay plan.
* Driver user accounts are created automatically when a driver verifies the mobile app with their phone number. Until that verification occurs, no user account exists to assign App permissions to.

## FAQs

**Q:** How do drivers gain access to the Alvys mobile app initially?

**A:** Access is tied to the mobile phone number entered on the driver's profile. Once the driver downloads the app and enters their phone number, they receive an SMS verification code. After successful entry, Alvys automatically links their app to a Driver user account in the system. An administrator can then assign App permissions to that account.

**Q:** Why do some App permissions also appear in other categories like Rates or E-Check?

**A:** Permissions such as **"View Trip Value"**, **"Issue ECheck"**, and **"Cancel ECheck"** are shared across categories because they control functionality in both the web TMS and the mobile app. Enabling the permission in one category automatically enables it in the other — they are the same underlying permission.

**Q:** Should I grant all App permissions to every driver?

**A:** No. Evaluate each permission based on the driver's relationship with the company and their operational needs. Owner-operators generally benefit from more visibility permissions (payable amount, carrier rate confirmation, paystubs). Company drivers on salaried pay typically need fewer financial visibility permissions.

**Q:** What is the difference between **"View App Paystubs"** and a paystubs permission in the Billing category?

**A:** They are separate permissions. **"View App Paystubs"** unlocks the Pay Statements section in the mobile app. A Billing-category paystubs permission controls access through the web interface. A driver needs the App-specific permission to view pay history on their phone or tablet.

**Q:** Can a driver see customer rates on the web load board if I grant them **"View Customer Rate Confirmation"**?

**A:** No. **"View Customer Rate Confirmation"** only allows the driver to open the customer rate confirmation document within the mobile app. It does not affect what the driver can view on the web interface.

**Q:** Why is **"Edit Trailer Number"** important for drivers?

**A:** Drivers frequently swap trailers at drop yards or during mechanical issues. Enabling this permission allows them to update the trailer record in real time, ensuring fleet tracking and compliance records stay accurate without requiring a call to dispatch.

## Go Deeper

* [E-Check Permissions](/en/help/administration/e-check-permissions)
* [Rates Permissions](/en/help/administration/rates-permissions)
* [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [Tendering Permissions](/en/help/administration/tendering-permissions)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Billing Permissions
Source: https://docs.alvys.com/en/help/administration/billing-permissions

Assign the fifteen Billing permissions that gate invoicing, driver settlements, paystubs, pay plans, factoring, and financial report access in Alvys.

<Note>
  Billing permissions (also called financial access rights or accounting entitlements) control access to invoicing, driver settlements, carrier payments, and financial reporting. This article describes each of the fifteen billing permissions and the specific actions each one enables.
</Note>

## Overview

Billing permissions (sometimes referred to as financial access rights or accounting entitlements) determine what each user can see and do within the financial and accounting areas of Alvys. They are configured per user and apply across the platform, including loads, reports, and the Accounting menu. The fifteen permissions in the Billing category range from foundational access (the **"Billing"** permission itself) to granular controls over paystubs, pay plans, and factoring.

## Where to Find It

1. Open **Settings** from the main navigation.
2. Select **Organization**, then **Users**.
3. Click **Edit** on an existing user, or click **Add User** to create a new profile.
4. Scroll to the **Permissions** section and locate the **Billing** category.
5. Enable or disable individual checkboxes to adjust the user's billing access.

<img alt="Screenshot of Settings in the main navigation" />

*Screenshot of Settings in the main navigation.*

<img alt="Screenshot of the Users tab under Organization" />

*Screenshot of the Users tab under Organization.*

<img alt="Screenshot of the Billing permissions category showing all fifteen checkboxes." />

*Screenshot of the Billing permissions category showing all fifteen checkboxes.*

To modify any permission, the logged-in user must hold the **"Permissions"** permission (the "Set Permission" toggle, located in the Management category). Without it, the user profile is read-only.

<Tip>
  **Requesting access from your admin:** If a Billing permission you need is not enabled on your profile, identify the specific permission name from the sections below, then ask your admin to enable it in **Settings → Organization → Users → \[your profile] → Permissions → Billing** category. Your admin must hold the **Set Permission** toggle (in the Management category) to make changes. If no one in your organization holds this permission, contact Alvys Support through the Help button in the bottom-left corner of Alvys.
</Tip>

## How to Use It

For step-by-step instructions on adding users and configuring permissions, see [Management and Privacy Permissions](/en/help/administration/management-privacy-permissions).

## Settings and Permissions

**Partner Admin** receives all Billing permissions by default. **Safety** and **Driver** roles receive none. The table below shows confirmed default assignments for the permissions with explicitly documented role assignments. For the remaining permissions (Billing master, Generate Invoice, Override Invoice, Pay Driver, Pay Owner Operator, View/Edit Paystubs, Rollback Transaction), check the individual sections below or view current assignments directly in **Settings → Organization → Users**.

| Permission               | Admin | Op. Manager | Biller | Dispatcher | Sales Agent |
| ------------------------ | ----- | ----------- | ------ | ---------- | ----------- |
| View Pay Plans           | ✓     | –           | –      | –          | –           |
| Edit Pay Plans           | ✓     | –           | –      | –          | –           |
| Approve Payable Items    | ✓     | ✓           | ✓      | –          | –           |
| Create Carrier Statement | ✓     | ✓           | ✓      | –          | –           |
| Revert Carrier Statement | ✓     | ✓           | –      | –          | –           |
| Edit Invoice Customer As | ✓     | ✓           | ✓      | –          | –           |

### Billing

The **"Billing"** permission is the master access key for the financial areas of Alvys. Staff with this permission can see and work with money: invoices, customer payments, factoring records, and financial reports. Staff without it see only the operational side of the platform; all financial information is hidden regardless of what other billing permissions they hold.

Enabling **"Billing"** provides the following access:

* The **Bill Summary** dashboard card on the home page (live load counts by billing stage).
* The **Invoicing**, **Summary Invoicing**, **Factoring Upload**, and **Error Transactions** pages under Accounting.
* The **Brokered Trips**, **Aging**, and **Factoring** reports from the Reports menu.
* Ability to view and download all load document types (customer invoices, carrier invoices, rate confirmations, receipts).
* Ability to change the **Date Invoiced** and **Bill Due Date** on a load.
* Ability to manage Customer Payments (view, add, edit, and remove) on any individual load.
* The **Purchase Report Transactions panel**, which shows the Funded Amount, Funded Fee Amount, and any other factoring transaction data tied to a factored load.
* Ability to view and edit the **Factoring ID field** on customer and broker company profiles (when a factoring integration such as TAFS is active).
* All financial columns in the Load Board (Customer Rate, Carrier Rate, Gross Margin, Factoring Payments, and related fields).

**"Billing"** is a prerequisite for many of the specific billing permissions below to take full effect on loads in billing statuses (**Released**, **Queued**, **Invoiced**, **Financed**, **Completed**, **On Hold**). Admins must enable **"Billing"** first.

<img alt="Notion Image" />

<Info>
  💡 A user with the **"Billing"** permission can view customer rates, carrier rates, and trip values even without explicit rate-viewing permissions, because the billing function requires access to all financial data associated with a load.
</Info>

### Generate Invoice

The **"Invoice"** permission (shown as "Generate Invoice" in the user interface) allows a user to generate and regenerate invoices, submit invoices to customers, and send payment reminders for individual loads.

Specifically, this enables the **Generate Invoice** button on loads in **Released**, **Queued**, **Invoiced**, **Financed**, or **TONU** status, accessible from the Money Box in the Trip Info view.

<img alt="Generate Invoice button on a load." />

*Generate Invoice button on a load.*

### Override Invoice

The **"Override Invoice"** permission allows a user to modify two date fields on an already-invoiced load: the **Invoice Due Date** and the **Date Invoiced**, visible on the load details page.

These fields can be edited on loads in **Released**, **Queued**, **Invoiced**, or **Financed** status. They remain locked for all users on loads in other operational statuses regardless of permissions.

The master **"Billing"** permission inherently provides this ability; **"Override Invoice"** is a narrower alternative for personnel who need to correct dates without full billing access.

<img alt="Invoice Due Date and Date Invoiced fields on a load" />

*Invoice Due Date and Date Invoiced fields on a load.*

### Rollback Transaction

The **"RollBackTransaction"** permission (shown as "Rollback Transaction" in the user interface) allows a user to revert factored loads that have been uploaded to a factoring provider via FTP (such as Capital Depot or RTS). The **Revert Factored Load** option appears in the **Manage** dropdown on the load details page only when all three conditions are met: the user holds this permission, the load is in **Invoiced** status, and the load was previously included in a factoring company FTP batch.

<img alt="Manage dropdown showing the Revert Factored Load option" />

*Manage dropdown showing the Revert Factored Load option.*

### Void Transaction

<Warning>
  ⚠️ The **"VoidTransaction"** permission has been deprecated. Enabling it has no effect.
</Warning>

### Pay Driver

The **"Pay Driver"** permission controls access to all driver paystub functions in Alvys. Users with this permission can access the **Pay Drivers** or **Driver Settlements** page under Accounting and can generate paystubs for company drivers.

This permission also reveals the **Deductions**, **Escrow Account**, and **Fuels** tabs within each driver profile. These tabs are completely hidden from users without this permission.

To modify a driver profile in addition to viewing it, the **"Edit Asset"** permission is also required.

<img alt="Pay Drivers / Driver Settlements page" />

*Pay Drivers / Driver Settlements page.*

<img alt="Image shows driver profile showing the Deductions, Escrow Account, and Fuels tabs." />

*Driver profile showing the Deductions, Escrow Account, and Fuels tabs.*

### Pay Owner Operator

The **"Pay Owner Operator"** permission controls access to owner operator payroll processing. It gates the **Owner Op** tab on the Pay Driver page and the owner operator filter on the Driver Settlements page. Without it, users can still process paystubs for company drivers and trucks but cannot access the owner operator view.

**"Pay Owner Operator"** works alongside **"Pay Driver"**: Pay Driver controls access to the settlements page and the company driver view; Pay Owner Operator adds the owner operator tab within that same page.

### View Paystubs

The **"View Paystubs"** permission enables a user to view driver and owner operator paystub records from the driver profile. Without it, paystub data is hidden entirely. This permission is a strict prerequisite for **"Edit Paystubs"**.

<img alt="Paystub list in a driver profile" />

*Paystub list in a driver profile.*

### Edit Paystubs

The **"Edit Paystubs"** permission enables two actions on driver paystubs from the three-dot menu in the driver profile: opening and modifying an existing paystub on its edit page, and deleting (reverting) a paystub.

**"View Paystubs"** is a strict prerequisite. Additionally, the edit and delete actions apply only to paystubs generated through the legacy driver pay workflow. Driver settlement statements generated through the modern Driver Settlements module cannot be modified or deleted from the driver profile; those must be reverted within the statements tab of the Driver Settlements module.

<img alt="Three-dot menu on a paystub showing edit and delete options." />

*Three-dot menu on a paystub showing edit and delete options.*

### View Pay Plans

The **View Pay Plans** permission works together with Pay Plans being enabled for your company, and both requirements must be met for the Pay Plans page to appear in the management menu. Enablement controls whether the feature is available to your company at all; the permission controls which users can access it once it is.

By default, the View Pay Plans permission is granted to the Partner Admin and Admin roles.

<Info>
  ✅ **Best Practice:** Restrict this access to administrators and compensation managers.
</Info>

### Edit Pay Plans

The Edit Pay Plans permission governs the ability of a user to create, modify, and delete driver pay plan templates within the Alvys TMS. For this permission to take effect, Pay Plans must be enabled for your company. If it is not enabled, users cannot open the Pay Plans page regardless of the permissions they hold. Accessing the Edit Pay Plans functionality also requires the View Pay Plans permission as a prerequisite. Without the ability to view the page, a user cannot interact with the editing interface.

When granted this permission, a user gains access to three specific write operations. They can:

* Create a new pay plan through a modal form.
* Modify any existing plan by selecting the edit icon.
* Permanently remove a plan via a confirmation dialog.

<img alt="Edit Pay Plan modal." />

*Edit Pay Plan modal.*

<img alt="Update Pay Plan modal showing pay plan name and rate configuration fields." />

*Update Pay Plan modal showing pay plan name and rate configuration fields.*

<img alt="Pay Plans list showing a pay plan row with plan name, plan rates, and action buttons" />

*Pay Plans list showing a pay plan row with plan name, plan rates, and action buttons.*

<img alt="Delete Pay Plan confirmation dialog asking to confirm deletion of a pay plan" />

*Delete Pay Plan confirmation dialog asking to confirm deletion of a pay plan.*

Because pay plan configurations impact the compensation of every driver and owner operator across your organization, unauthorized changes can lead to significant payroll errors or driver disputes.

By default, the Edit Pay Plans permission is assigned to the Partner Admin and Admin roles. It is explicitly excluded from the Operation Manager, Dispatcher, Biller, and other operational roles to maintain a clear separation of duties.

<Info>
  ✅ **Best Practice:** Restrict this permission to a very small number of senior administrators and consider implementing a formal review process for any modifications to existing pay plan structures.
</Info>

### Approve Payable Items

The **Approve Payable Items** permission controls whether a user can approve or unapprove payable line items for [carrier](https://app.alvys.com/accounting/carrier-settlements) and [driver settlements](https://app.alvys.com/accounting/driver-settlements). In Alvys TMS, payable items are individual charges, such as trip values, accessorials, and e-checks, that must be approved before they can be included in a settlement. This approval process acts as a quality control step, allowing an authorized user to review each item before it is approved for payment. Without this permission, a user cannot approve items for statement generation.

<img alt="Screenshot showing payable items approval interface." />

*Screenshot showing the payable items approval interface.*

<img alt="Screenshot showing the Deductions and Reimbursements panel with the Unapprove option for an approved payable item." />

*Screenshot showing the Deductions and Reimbursements panel with the Unapprove option for an approved payable item.*

By default, this permission is granted to the Partner Admin, Admin, Operation Manager, and Biller roles. Conversely, this specific access is not assigned by default to the Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, or Driver roles.

### Create Carrier Statement

The Create Carrier Statement permission controls whether a user can generate [carrier settlement](https://app.alvys.com/accounting/carrier-settlements) statements. A carrier statement is a formal financial document that summarizes all charges, payments, and deductions for a carrier over a settlement period. Creating a statement is the step that finalizes the carrier's settlement and prepares it for payment. Without it, the user cannot finalize carrier settlements.

<img alt="Screenshot of the Create Carrier Statement action." />

*Screenshot of the Create Carrier Statement action.*

By default, this authorization is **granted** to the **Partner Admin**, **Admin**, **Operation Manager**, and **Biller** roles. Conversely, this specific permission is not assigned by default to the **Dispatcher**, **Sales Agent**, **Data Entry**, **Office Admin**, **Safety**, or **Driver** roles.

<Info>
  ✅ **Best Practice:** Verify all payable items before creating a carrier statement. Once created, a statement requires the Revert Carrier Statement permission to undo.
</Info>

### Revert Carrier Statement

The Revert Carrier Statement permission controls whether a user can revert (undo) a [carrier settlement](https://app.alvys.com/accounting/carrier-settlements) statement that has been generated. Reverting a statement returns the carrier's payable items to their pre-statement state, effectively canceling the settlement and allowing corrections to be made before a new statement is generated.

<img alt="Screenshot showing the Revert Carrier Statement option" />

*Screenshot showing the Revert Carrier Statement option.*

This is a corrective action that should only be performed when errors in the original statement have been identified and need to be fixed. Because reverting affects the carrier's payment expectations and may require coordination with the carrier, it is restricted to administrator-level users who can make informed decisions about financial reversals.

<Warning>
  ⚠️ Regardless of whether a user has been granted this permission, they are prohibited from reverting carrier statements that have reached a Paid status.
</Warning>

<img alt="Notion Image" />

By default, this authorization is granted to the Partner Admin, Admin, and Operation Manager roles. Conversely, this specific permission is not assigned by default to the Biller, Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, or Driver roles. This permission is more restrictive than **"Create Carrier Statement"** (which the Biller receives) and reflects the sensitive nature of reverting financial commitments.

<Info>
  ✅ **Best Practice:** Keep this permission restricted to manager-level roles to maintain the separation of duties between statement creation (Biller) and statement reversal (Accounting Manager).
</Info>

### Edit Invoice Customer As

The Edit Invoice Customer As permission controls the "Invoice Customer As" dropdown on the Load Details page. It allows a user to select a different company subsidiary than the one shown on the customer invoice for a load. This is useful for companies with multiple subsidiaries, where a load may be handled under one entity but billed under another with a separate customer relationship. When a selection is made, the system updates the load record with the chosen subsidiary.

<Warning>
  ⚠️ The Invoice Customer As value can only be changed when the load is in one of the following statuses: In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, Released, TONU, or Invoiced. It is not editable when the load is Cancelled, Queued, or Paid.
</Warning>

<img alt="Notion Image" />

<img alt="Screenshot of the Invoice Customer As dropdown on a load." />

*Screenshot of the Invoice Customer As dropdown on a load.*

If a user does not have this permission, the dropdown remains visible but is disabled, so they can view the current selection but cannot change it. By default, this permission is granted to the Partner Admin, Admin, Operation Manager, and Biller roles only.

## Frequently Asked Questions (FAQs)

**Q: What is the difference between the "Billing" permission and the other 14 specific billing toggles?**

**A:** The "Billing" permission acts as the master entry key for the entire accounting module. It unlocks the Billing module and provides broad visibility into financial data. The other 14 permissions control specific actions, such as generating invoices, processing payments, or managing settlements. Usually, a user needs the "Billing" permission for general access plus specific toggles for their daily tasks.

**Q: Can I change the "Invoice Customer As" subsidiary after a load has been paid?**

**A:** No. The "Invoice Customer As" dropdown is only editable when a load is in statuses such as Open, Dispatched, Delivered, or Invoiced. Once a load reaches **Queued** or **Paid** status, the subsidiary field is locked to maintain financial integrity.

**Q: What is required to edit a customer rate on a load that has already been released to billing?**

**A:** To edit rates at this stage, a user must have both the **Edit Customer Rate** permission and the master **Billing** permission. Without the Billing toggle, the financial fields become read-only once the load is released into billing.

**Q: Why can some of my team members see the "Deductions" and "Fuels" tabs on a driver's profile while others cannot?**

**A:** Visibility of these tabs is controlled by the **Pay Driver** permission. This is sensitive financial data, so Alvys hides these tabs entirely for any user who does not have the authority to process driver settlements.

**Q: Why can't I revert a carrier statement that I just created?**

**A:** You likely possess the **Create Carrier Statement** permission but lack the **Revert Carrier Statement** permission.

**Q: Under what specific conditions will the "Revert Factored Load" option appear in the Manage menu?**

**A:** This option only appears when three conditions are met simultaneously: you have the Rollback Transaction permission, the load is in the Invoiced status, and the load was previously included in a factoring company FTP batch (such as Capital Depot or RTS). If any of these conditions are missing, the option will not be visible in the dropdown.

**Q: Why can't I see the Pay Plans option in the Management menu even though I'm an Admin?**

**A:** Access to Pay Plans requires the View Pay Plans permission, and Pay Plans must be enabled for your company. Contact Alvys Support to have it enabled.

**Q: What happens if I have "Edit Pay Plans" enabled but "View Pay Plans" is turned off?**

**A:** You will be unable to make any changes. The View Pay Plans permission is a strict prerequisite; without the ability to access and view the Pay Plans page, you cannot interact with the interface to create, modify, or delete any pay plans.

## Next Steps

<Info>
  ⏭️ Proceed to [Report Permissions](/en/help/administration/report-permissions), which explains how to control access to fuel, toll, financial, safety, and driver earnings reports, ensuring each role in your organization has the appropriate level of visibility into operational and financial data.
</Info>

## Return to Collection

<Info>
  📁 [Back to User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)
</Info>


# Company Management Permissions
Source: https://docs.alvys.com/en/help/administration/company-management-permissions

Grant the four Company Management permissions that let users create, edit, activate, or delete shippers, warehouses, factoring, and other non-customer records.

<Note>
  Company Management Permissions control who can create, edit, activate, and delete non-customer company records such as shippers, warehouses, and factoring companies. Safety and Driver roles do not have these permissions by default.
</Note>

## Overview

In Alvys, "companies" encompass a wide range of business entities beyond customers. The system supports multiple company types, and the Company Management Permissions category governs who can create, modify, activate, and delete non-customer company records. This includes shippers, warehouses, factoring companies, terminals, lease companies, and other business entities your operation interacts with.

<Info>
  💡 **Company Management permissions** govern actions on non-customer company types, while [Customer Management permissions](/en/help/administration/customer-management-permissions) govern actions on Customer and Broker/3PL types.
</Info>

The Companies List in Alvys is visible to all non-Driver roles. Having navigation access to the Companies page does not automatically grant the ability to create, edit, activate, or delete records; each of these actions requires the specific permissions described in this article.

With four individual permissions, this category mirrors the [Customer Management category](/en/help/administration/customer-management-permissions) in structure but applies to different company types.

## Where to Find It

Company Management Permissions are configured at the individual user level within the User Management interface. This interface is located at Management > Company Profile > Users tab.

<Warning>
  ⚠️ To modify these permissions, the logged-in user, preferably an administrator, must possess the **"Set Permission"** permission located within the Management category. Without **"Set Permission"**, a user can view the user profile or form but cannot adjust any permissions. For additional information, refer to the [Management & Privacy Permissions article](/en/help/administration/management-privacy-permissions).
</Warning>

To open the Company Management permissions for a user:

1. Select your username located in the bottom left corner of the Alvys interface.

   <img alt="Screenshot showing the username in the bottom left corner of the Alvys navigation, with the user menu expanded." />

   *Screenshot showing the username in the bottom left corner of the Alvys navigation, with the user menu expanded.*
2. Navigate to Management > Company Profile and select the **Users** tab

   <img alt="Screenshot of the Management tab with Users highlighted" />

   *Screenshot of the Management tab with Users highlighted*
3. Choose an existing user to **Edit**, or select the **Add User** button to create a new profile.
4. Scroll to the **Permissions** section and locate the **Company Management** category. Identify the four individual checkboxes: **"Create Company"**, **"Edit Company"**, **"Activate Company"**, and **"Delete Company"**.

<Note>
  <img alt="Screenshot showing the Permissions section with the Company Management category expanded and all four permission checkboxes visible." />

  *Screenshot showing the Permissions section with the Company Management category expanded and all four permission checkboxes visible.*
</Note>

## Company Management Permissions Breakdown

### "Create Company"

The **"Create Company"** permission controls whether a user can create new non-customer company records and import shippers into the system. This applies to company types such as Shippers, Warehouses, Lease Companies, Terminals, Factoring Companies, and other business entities that are not classified as Customer or Broker/3PL.

<Note>
  <img alt="Screenshot showing the Companies page with the New Customer button visible in the top right." />

  \*Screenshot showing the Companies page with the New Customer button visible in the top right. \*
</Note>

The **New Company** button is displayed if a user has either the **"Create Customer"** permission (for Customer or Broker-type companies) or the **"Create Company"** permission (for non-customer companies, such as a Shipper or Warehouse).

However, if a user has only the **"Create Customer"** permission, they will receive an error if they attempt to create a non-customer company type, such as a Shipper or Warehouse, because they do not have the **"Create Company"** permission.

<Note>
  <img alt="Screenshot showing the error message a user receives when attempting to create a non-customer company type without the 'Create Company' permission." />

  *Screenshot showing the error message a user receives when attempting to create a non-customer company type without the "Create Company" permission.*
</Note>

By default, this permission is assigned to: Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin. Not assigned by default to: Safety or Driver.

<Info>
  💡 **Best Practice:** Assign **"Create Company"** only to roles responsible for operational setup, such as Data Entry staff, managers, owners, or a dedicated Operations Coordinator. Always review new company records promptly to ensure accuracy before they are referenced on loads.
</Info>

### "Edit Company"

The **"Edit Company"** permission allows a user to modify information on an existing company profile for company types such as Shippers, Warehouses, Terminals, and others. This includes updating addresses, contacts, phone numbers, operating hours, notes, and any other editable fields on the company record. Without this permission, the user can view the company profile, but all fields appear in read-only mode and no changes can be made.

By default, this permission is assigned to: Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin. Not assigned by default to: Safety or Driver.

<Info>
  💡 **Best Practice:** Grant **"Edit Company"** alongside **"Edit Customer"**. Users who maintain one type of company record typically need access to modify all company types.
</Info>

### "Activate Company"

The **"Activate Company"** permission controls whether a user can modify the activation status of non-customer company records, including Shippers, Warehouses, and other non-customer entity types. Status options include **Active**, **Inactive**, **On Hold**, **Do Not Use**, and **Disabled**.

**Active** companies are available for use in load operations. Deactivating a company removes it from active use, preventing it from being referenced in new loads while preserving all historical records tied to that entity. Without this permission, a user cannot change a non-customer company's activation status.

<Info>
  💡 Deactivating a company does not affect loads that have already been created referencing that entity. In-progress and historical loads remain fully intact. Deactivation only prevents the company from being selected for new transactions going forward.
</Info>

By default, this permission is assigned to: Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin.

To modify a company's activation status:

1. Navigate to the Companies page.
2. Open the Shipper, Warehouse, or relevant company profile.
3. Locate the status button in the top right corner of the company profile.

   <img alt="Screenshot showing the status button in the top right corner of a company profile." />

   \*Screenshot showing the status button in the top right corner of a company profile. \*
4. Click the status dropdown and select the desired status (for example, **Inactive**).

<Note>
  <img alt="Screenshot showing the status dropdown open with the available status options: Active, Inactive, On Hold, Do Not Use, Disabled." />

  \*Screenshot showing the status dropdown open with the available status options: Active, Inactive, On Hold, Do Not Use, Disabled. \*
</Note>

To reactivate a company: navigate to the Companies page (filter for inactive records if needed), open the inactive company's profile, locate the status button, click the dropdown and select **Active**.

<Info>
  💡 **Best Practice:** Use deactivation as the default action when a shipper, warehouse, or facility relationship ends or becomes temporarily unavailable. Reserve deletion for confirmed duplicate records or test entries with no load history.
</Info>

### "Delete Company"

The **"Delete Company"** permission allows a user to remove a non-customer company record, such as Shippers, Warehouses, and other non-customer entity types, from Alvys. When this permission is enabled, a **Delete** button appears in the top-right corner of the company's profile.

<Note>
  <img alt="Screenshot showing Delete button in top right corner of customer profile" />

  *Screenshot showing Delete button in top right corner of customer profile*
</Note>

Deletion is rarely the right tool. In almost every case, what a user actually wants is deactivation (see "Activate Company" above). This permission should be tightly restricted and used only in clearly justified, exceptional circumstances. The **"Delete Company"** permission is restricted to the highest-level administrators as a last resort.

By default, this permission is assigned exclusively to Support and Partner Admin. Not assigned by default to any other role.

<Info>
  💡 **Best Practice:** Never grant **"Delete Company"** to non-admin roles. Assign it only to one or two trusted administrators in your Alvys account, typically the owner and a senior manager. Before deleting a company, verify that it has no current or active records. Consider requiring a second approval via your internal process before proceeding.
</Info>

## Limits & Behavior

Viewing company records does not require any Company Management permission. All non-Driver roles can navigate to the Companies page and view records in read-only mode.

The **New Company** button is visible to any user who holds either **"Create Customer"** or **"Create Company"** permission. Attempting to create a non-customer company type without **"Create Company"** produces an error, even if **"Create Customer"** is held.

Deactivating a company does not affect in-progress or historical loads that reference it. Those loads remain fully intact.

Deleting a company is permanent. There is no undo. This is why deactivation is the strongly preferred action in all but exceptional circumstances.

Company Management permissions and Customer Management permissions are independent. A user can hold one set without the other.

## Troubleshooting

### The New Company button is visible but creating a Shipper or Warehouse throws an error

The user holds only **"Create Customer"**, which surfaces the button but does not authorize non-customer company types. Grant **"Create Company"** to allow creating Shippers, Warehouses, and other non-customer entities.

### A user cannot change a company's status

The user is missing **"Activate Company"**. Without it, the status control on the company profile is unavailable.

### The Delete button does not appear on a company profile

The **"Delete Company"** permission is not granted. By default it is restricted to Support and Partner Admin only.

### Company fields appear read-only

The user is missing **"Edit Company"**. View access alone displays the profile in read-only mode.

## FAQs

**Q: What company types use Company Management permissions?**

**A:** Any company type that is not Customer or Broker/3PL uses Company Management permissions. This includes Shippers, Warehouses, Terminals, Lease Companies, Factoring Companies, and other non-customer entities.

**Q: Can a user see all company types without Company Management permissions?**

**A:** Yes. Viewing company records is separate from management permissions. Users without Company Management permissions can see records in read-only mode but cannot create, edit, activate, or delete them.

**Q: How should deactivation be used versus deletion?**

**A:** Deactivate companies by default when relationships end or become temporarily unavailable. Deletion should only be used for duplicates or test records without historical references, and only by the highest-level administrators.

## Go Deeper

[App Permissions](/en/help/administration/app-permissions): Learn how to manage driver and carrier access in the Alvys mobile app.


# Contracted Lanes Permissions
Source: https://docs.alvys.com/en/help/administration/contracted-lanes-permissions

Manage the four Contracted Lanes permissions that govern viewing, creating, deleting, and auto-applying negotiated customer lane rate agreements on new loads.

<Note>
  The Contracted Lanes Permissions category in Alvys controls who can view, create, update, delete, and apply pre-negotiated lane rate agreements (contracted lanes) between your company and its customers. There are four permissions in this category: "View Contracted Lanes", "Update/Create Contracted Lanes", "Delete Contracted Lanes", and "Apply Contracted Lanes On New Load".
</Note>

## Overview

A contracted lane is a pre-negotiated rate agreement between your company and a specific customer for a defined route. For example, you might have an agreement with Customer ABC specifying that any load from Dallas, TX to Houston, TX will be billed at \$850. Storing contracted lanes in Alvys eliminates the need for dispatchers to look up or remember rate agreements manually. When a new load is created on a lane with a contracted rate, Alvys can automatically reference and populate that rate.

Lane rate contracts, also referred to as lane rate agreements or contracted rates, are a fundamental pricing tool in freight brokerage. Instead of negotiating rates for each load individually, companies establish standing agreements for frequently used lanes. These contracts specify the rate, fuel surcharge structure, and terms for each customer and route. Proper access control is critical when managing these contracts, as they directly impact pricing, revenue, and customer relationships.

The Contracted Lanes Permissions category in Alvys controls access to lane rate contracts. With four permissions, this category governs who can view contracted lane rates, create and update contracts, delete contracts, and apply contracted rates when creating new loads.

## Where to Find It

Contracted Lanes Permissions are configured at the individual user level within the User Management interface. To access user permissions, select your **username** in the bottom left corner of the screen, navigate to **Company Profile**, and select the **Users** tab.

<Note>
  📷 The Company Profile page with the Users tab selected, showing the user list.

  <img alt="Notion Image" />
</Note>

Choose an existing user to **Edit** or select the **Add User** button to create a new profile. In the user profile, scroll to the **Permissions** section and locate the **Contracted Lanes** category to find the four individual checkboxes: **"View Contracted Lanes"**, **"Update/Create Contracted Lanes"**, **"Delete Contracted Lanes"**, and **"Apply Contracted Lanes On New Load"**.

<Note>
  📷 The Permissions section of a user profile showing the Contracted Lanes category with its four checkboxes.

  <img alt="Notion Image" />
</Note>

<Warning>
  ⚠️ To modify these permissions, the logged-in user must possess the **"Set Permission"** permission located within the Management category. Without **"Set Permission"**, a user can view the user profile or form but cannot adjust any permissions. For additional information, refer to the [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions) article.
</Warning>

## Key Concepts

A contracted lane defines the customer, the origin address, the destination address, the agreed-upon rate, and any fuel surcharge terms. Contracts are stored on the customer or broker profile in Alvys. When a new load is created on a matching lane, the system can automatically reference the active contract and populate the rate, provided the user has the **"Apply Contracted Lanes On New Load"** permission.

The Contracted Lanes category uses two naming conventions. The permissions are displayed in the interface as "Contracted Lanes" (for example, **"View Contracted Lanes"**), while the system identifies them internally using the term "Contracted Rates" (for example, **"ViewContractedRates"**). Both terms refer to the same feature: lane rate contracts.

All four Contracted Lanes permissions are excluded from the default permission set for Admin and Operation Manager roles. Even users with the Admin role must have these permissions explicitly granted. Only the Support and Partner Admin roles receive all four Contracted Lanes permissions by default.

## Settings & Permissions

### "View Contracted Lanes"

The **"ViewContractedRates"** permission (displayed as **"View Contracted Lanes"**) determines whether a user can access lane rate agreements on a customer or broker profile in Alvys. It provides read-only access to contracted lane data. Without this permission, the contracted lanes information and related interface elements remain hidden from the user.

When a user has this permission and accesses a customer or broker profile, the Contracted Lanes and Fuel Surcharges section is visible in the top right corner above the contacts heading. Selecting this section presents a complete list of all rate agreements associated with that customer.

<Note>
  📷 A customer profile in Alvys showing the Contracted Lanes and Fuel Surcharges section visible in the top right corner above the contacts heading.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 The Contracted Lanes and Fuel Surcharges panel expanded, showing a list of rate agreements for a customer with lane details and rates.

  <img alt="Notion Image" />
</Note>

By default, this permission is granted exclusively to the Support and Partner Admin roles. Admin and Operation Manager roles do not receive it by default; it must be explicitly granted.

<Info>
  ✅ **Best Practice:** Assign **"View Contracted Lanes"** to users responsible for managing customer relationships, negotiating rates, or requiring visibility into lane pricing. Because Admin and Operation Manager roles do not receive this permission by default, ensure it is explicitly granted to any admin-level users involved in managing contracted lanes.
</Info>

### "Update/Create Contracted Lanes"

The **"WriteContractedRates"** permission (displayed as **"Update/Create Contracted Lanes"**) enables a user to create new contracted lane rate agreements and modify existing ones on a customer or broker profile. This permission governs the building and maintenance of the rate library in Alvys, including setting rates, defining lanes, configuring fuel surcharge terms, and updating contract details. Because these modifications directly affect pricing commitments, this permission ensures that only authorized users can create or adjust financial agreements.

<Note>
  📷 The Create Contract button highlighted under the contracted lanes view

  <img alt="Notion Image" />
</Note>

<Info>
  💡 **Note:** A user who creates or edits contracts will generally also require the **"View Contracted Lanes"** permission to access and review the contracts they are managing.
</Info>

The Edit action within this permission controls a user's ability to modify existing lane rate contracts, including updating rates, terms, and effective dates.

<Note>
  📷 An existing contracted lane contract open in edit mode, showing the rate, effective date, and terms fields available for modification.

  <img alt="Notion Image" />
</Note>

By default, this permission is granted to the Support and Partner Admin roles only. Admin and Operation Manager roles do not receive it by default; it must be explicitly granted.

<Info>
  ✅ **Best Practice:** Assign **"Update/Create Contracted Lanes"** only to users who are authorized to make pricing commitments. Always pair it with the **"View Contracted Lanes"** permission so users can access and review the contracts they manage. Consider implementing a review workflow in which all contract changes are verified by a second authorized user.
</Info>

### "Delete Contracted Lanes"

The **"DeleteContractedRates"** permission (displayed as **"Delete Contracted Lanes"**) determines whether a user can remove lane rate contracts. Deleting a contract permanently eliminates the pre-negotiated rate agreement, requiring manual rate entry for any subsequent loads on that lane. This is the most critical and potentially disruptive action within the Contracted Lanes category.

<Warning>
  ⚠️ Deletion is completely blocked if any loads currently reference the contract.
</Warning>

To delete a contracted lane, navigate to the customer or broker profile and locate the Contracted Lanes & Fuel Surcharges section in the top right corner.

In the contracted lanes list, select the **three-dot menu** for the lane you want to remove.

<Note>
  📷 The contracted lanes list with the three-dot action menu open for a specific lane row.

  <img alt="Notion Image" />
</Note>

Select **Delete** and confirm the action to remove the contract.

<Note>
  📷 The delete confirmation dialog for a contracted lane.

  <img alt="Notion Image" />
</Note>

By default, this permission is granted to the Support and Partner Admin roles only. Admin and Operation Manager roles do not receive it by default; it must be explicitly granted.

<Info>
  ✅ **Best Practice:** Grant **"Delete Contracted Lanes"** very sparingly. Most users who manage contracts need View and Update/Create but not Delete. Consider restricting Delete to senior pricing staff or managers.
</Info>

### "Apply Contracted Lanes On New Load"

The **"ApplyContractedRatesOnNewLoad"** permission (displayed as **"Apply Contracted Lanes On New Load"**) governs whether a user can select and apply a contract from an existing agreement when creating a new load. The system cross-references the load's customer and lane details; if a matching active contract is found, it automatically populates the agreed-upon rate in the stop details step of the load creation process.

When creating a new load, select the specific customer or broker associated with the existing lane agreement, as the contract is linked to that entity. Leave billing rates blank at this stage: the system will populate them automatically when the matching contract is applied. Verify that the **Invoice As** field matches the subsidiary that was set when the lane contract was created; if these do not align, the system will not recognize the contract. Confirm that the pickup and delivery addresses exactly match the lane addresses defined in the contract. Once the lane details match, the system returns the relevant contract; select it from the dropdown to automatically populate the pre-negotiated rates and terms. Only active contracts appear in this dropdown.

<Note>
  📷 The load creation screen showing the Choose Contract dropdown in the stop details step, with a matched contract available for selection.

  <img alt="Notion Image" />
</Note>

<Note>
  📷 The load creation screen after a contract has been selected from the dropdown, showing the contracted rate automatically populated in the billing rate fields.

  <img alt="Notion Image" />
</Note>

By default, this permission is granted to the Support and Partner Admin roles only. Admin and Operation Manager roles do not receive it by default; it must be explicitly granted.

<Info>
  ✅ **Best Practice:** Grant **"Apply Contracted Lanes On New Load"** to dispatchers and load creators who work with customers that have active contracted lanes. This improves pricing accuracy and reduces manual data entry. Pair it with **"View Contracted Lanes"** so users can verify the rates being applied. Before enabling this permission, audit your contracted lane records to ensure every agreement on file reflects your current negotiated rates.
</Info>

## Limits & Behavior

* Deletion of a contracted lane is completely blocked by the system if any active loads currently reference that contract. This prevents the accidental removal of financial data tied to live operations.
* Only active contracts are returned in the Choose Contract dropdown during load creation. Expired or inactive contracts do not appear.
* When **"Apply Contracted Lanes On New Load"** is enabled, contracted rates are automatically populated during load creation; however, authorized users can still manually override the amount on the load if a specific situation requires a price adjustment. The permission controls automatic population, not rate lock-in.
* The Invoice As subsidiary on the load must match the subsidiary that was set when the lane contract was created. If these do not align, the system will not recognize the contract during load creation.
* Pickup and delivery addresses must exactly match the lane addresses defined in the contract for the contract to appear in the dropdown.

## FAQs

**Q: What is a contracted lane in Alvys?**

**A:** A contracted lane is a pre-negotiated rate agreement between your company and a specific customer for a defined route. Storing these in Alvys allows the system to automatically populate rates during load creation, eliminating the need for manual lookups.

**Q: Can I allow a user to see contracted rates without letting them change them?**

**A:** Yes. You can grant the **"View Contracted Lanes"** permission independently. This provides read-only access, allowing users to reference rates for customer service or planning without the ability to create, update, or delete contracts.

**Q: Why should the Update/Create and View permissions be paired?**

**A:** A user who creates or edits contracts needs the **"View Contracted Lanes"** permission to access and review the data they are managing. Without it, the user may be able to save a contract but will not be able to see the library to verify their work.

**Q: Is there a restriction on deleting a contracted lane?**

**A:** Yes. Deletion is completely blocked by the system if any active loads currently reference that specific contract. This safeguard prevents the accidental removal of financial data tied to live operations.

**Q: Does a contracted rate lock in the price of a load?**

**A:** No. While the system automatically populates the contracted rate when a matching lane is detected, authorized users can still manually override the amount on the load if a specific situation requires a price adjustment.

**Q: Why is the "Choose Contract" dropdown empty even though I have the permission enabled?**

**A:** The dropdown only populates if the load details match a valid lane contract. Ensure that the customer or broker, the Invoice As subsidiary, and the pickup and delivery addresses exactly match the existing customer lane contract.

## Go Deeper

* [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Customer Account Manager Role on Loads
Source: https://docs.alvys.com/en/help/administration/customer-account-manager-role-on-loads

Assign the Customer Account Manager role on loads and customer profiles to auto-populate account owners, improve payroll tracking, and clarify accountability.

<Note>
  The Customer Account Manager is a role that appears on the Load Details page and on Customer Profiles. When a Customer Account Manager is assigned to a Customer Profile, Alvys automatically populates that user as the Customer Account Manager on any new loads created for that customer. The field can also be updated manually on individual loads at any time.
</Note>

## Overview

The Customer Account Manager role lets your organization track which team member is responsible for a customer's account on a per-load basis. This role appears on the Load Details page alongside other load roles such as Load Planner, Customer Service Rep, and Sales Manager.

The Customer Account Manager role is designed for organizations that need additional role types to track payroll and maintain clear accountability across their teams.

Only users with an **Admin** or **User** Alvys account type can be assigned as a Customer Account Manager on a load.

## Where to Find It

The Customer Account Manager field appears in two places:

* **Load Details page:** In the roles section of a load, alongside Load Planner, Customer Service Rep, and Sales Manager.
* **Customer Profile:** In the roles section of a customer's profile, where you set the default Account Manager for that customer.

## Key Concepts

### Auto-population on new loads

When you assign a Customer Account Manager to a Customer Profile, Alvys automatically fills in that user as the Customer Account Manager on every new load created for that customer. This eliminates the need to manually assign the Account Manager each time a load is created for that customer.

### Load-level overrides

The auto-populated Customer Account Manager on a load can be changed at any time. Updates made directly on a load affect only that load. Changing the Customer Account Manager on a Customer Profile does not retroactively update the Customer Account Manager field on any existing loads. Each load must be updated separately if a change is needed on previously created loads.

### Who can be assigned

Only users with an **Admin** or **User** Alvys account type can be assigned as a Customer Account Manager on a load.

## How to Use It

* To set the default Customer Account Manager for a customer, see the Customer Profile settings in the Customers module.
* To update the Customer Account Manager on an individual load, open the load on the Load Details page and edit the Customer Account Manager field directly in the roles section.

## Settings & Permissions

No additional permission beyond standard login is required to update the Customer Account Manager field on a load. Any authenticated user can make this change.

Users must have an **Admin** or **User** Alvys account type to appear as an available selection when assigning a Customer Account Manager.

## Limits & Behavior

* Only one Customer Account Manager can be assigned to a load at a time.
* Changing the Customer Account Manager on a Customer Profile does not update the field on any existing loads. Existing loads retain the Customer Account Manager that was set when each load was created (or last manually updated).
* If no Customer Account Manager is assigned on the Customer Profile at the time a load is created, the Customer Account Manager field on the new load will be empty.

## FAQs

**Q: Will changing the Customer Account Manager on a Customer Profile update existing loads?**

**A:** No. The change applies only to new loads created after the update. Existing loads retain their current Customer Account Manager and must be updated individually.

**Q: Who can be selected as a Customer Account Manager on a load?**

**A:** Only users with an Admin or User Alvys account type can be assigned as a Customer Account Manager.

**Q: Can I remove the Customer Account Manager from a load without assigning a new one?**

**A:** Yes. You can clear the Customer Account Manager field on a load without replacing it. The field will be left empty.

**Q: Do I need a special permission to assign or change the Customer Account Manager on a load?**

**A:** No. Any authenticated user can update the Customer Account Manager field on a load. No additional permission is required.

**Q: Where else does the Customer Account Manager role appear besides on loads?**

**A:** The Customer Account Manager role also appears on Customer Profiles, where it sets the default value that auto-populates on new loads for that customer.


# Customer Management Permissions
Source: https://docs.alvys.com/en/help/administration/customer-management-permissions

Control who can create, edit, activate, or delete Customer and Broker/3PL records in Alvys with the four Customer Management user permissions.

Customer Management permissions control who can create, edit, activate, and delete customer and Broker/3PL records in Alvys. This article explains each permission, its default role assignments, and how to configure it in User Management.

## Overview

The Customer Management permissions category in Alvys controls who can create, modify, activate, and delete customer records (also called client records or shipper-customer accounts). These permissions are separate from the broader Company Management permissions and apply specifically to entities classified as type Customer or BrokerOr3PL in the system. Shippers, warehouses, and other company types fall under Company Management permissions instead. See the [Company Management Permissions](/en/help/administration/company-management-permissions) article for additional details.

There are four permissions in this category:

* **"Create Customer"**: controls the ability to create new customer and Broker/3PL records and import customers
* **"Edit Customer"**: controls the ability to modify existing customer and Broker/3PL profiles
* **"Activate Customer"**: controls the ability to change a customer's status (active, on hold, inactive, disabled)
* **"Delete Customer"**: controls the ability to permanently remove a customer record

## Where to Find It

Customer Management permissions are configured at the individual user level within the User Management interface.

<Note>
  📋 To modify these permissions, the logged-in user must possess the **"Set Permission"** permission located within the Management category. Without **"Set Permission"**, a user can view the user profile or form but cannot adjust any permissions. For additional information regarding **"Set Permission"**, refer to the [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions) article.
</Note>

1. Open User Management. Select your **username** located in the bottom left corner of the screen.
2. Navigate to the Users tab. Go to Company Profile and select the **Users** tab.

   <img alt="Notion Image" />
3. Open a user profile. Choose an existing user to **Edit** or select the **Add User** button to create a new profile.
4. Locate the Customer Management category. Scroll to the **Permissions** section and locate the **Customer Management** category.
5. Configure the checkboxes. Identify the four individual checkboxes: **Create Customer**, **Edit Customer**, **Activate Customer**, and **Delete Customer**.

<Note>
  📋 Image placeholder: The Customer Management section in the Permissions panel with four checkboxes:

  <img alt="Notion Image" />
</Note>

## Key Concepts

**Customer vs. Company types:** The system applies Customer Management permissions to exactly two company types: Customer and BrokerOr3PL. All other company types (Shippers, Warehouses, and other operational entities) are governed by Company Management permissions. The system automatically checks the relevant permission based on the company type being created or modified.

**Deactivation vs. deletion:** Deactivating a customer (setting status to Inactive) prevents new loads from being created for that account while preserving all historical invoices, load records, and documents. Deletion permanently removes the record. In almost every situation, deactivation is the correct action.

## Settings & Permissions

### "Create Customer"

The **"Create Customer"** permission controls whether a user can create new customer records and Broker/3PL records, as well as import customers into the system. Customer records are the foundation of the revenue cycle: every load starts with a customer booking, and every invoice is sent to a customer. Creating a customer record establishes the business relationship in the system, including billing preferences, credit terms, and contact information. Unrestricted customer creation could lead to duplicate records, incomplete profiles, or unauthorized business relationships. This permission ensures that only designated staff can onboard new customers.

Without this permission, a user cannot import existing customers or create new Customer or Broker/3PL records. The **New Company** button is displayed if a user has either the **"Create Customer"** permission (for Customer or Broker-type companies) or the **"Create Company"** permission (for non-customer companies). However, if the user has only the **"Create Company"** permission, they will receive an error if they access the company creation form and select a company type of Broker or Customer, because they do not have the **"Create Customer"** permission.

By default, this permission is granted to the Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin roles.

<Info>
  💡 **Best Practice:** Assign the **"Create Customer"** permission only to roles trained in your company's customer intake process, typically a lead dispatcher, office manager, or owner. Always review new customer records within 24 hours to catch data entry errors before a load is built against them.
</Info>

### "Edit Customer"

The **"Edit Customer"** permission lets a user modify information on an existing broker or customer profile. This includes changing contact details, billing addresses, payment terms, credit limits, factoring company assignments, notes, and any other editable fields on the customer record. Without this permission, all customer and broker fields appear in read-only mode; the user can view the information but cannot change anything. The **"Edit Customer"** permission ensures that customer data can be maintained by authorized staff while preventing unauthorized modifications that could disrupt business relationships or financial processes.

By default, this permission is granted to the Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin roles.

<Info>
  💡 **Best Practice:** Grant the **"Edit Customer"** permission to dispatchers and billers who actively manage customer relationships day-to-day. Consider restricting it for roles that only need to view customer information.
</Info>

### "Activate Customer"

The **"Activate Customer"** permission controls whether a user can modify a customer's status: activating, placing on hold, deactivating (inactive), or disabling a customer or Broker/3PL record. Active customers can have loads booked and invoices generated against them. Deactivating a customer prevents new loads from being created for that account while preserving all historical invoices, load records, and documents. Without this permission, a user cannot change a customer's activation status.

By default, this permission is granted to the Support, Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin roles.

<Note>
  📋 Deactivating a customer does not affect loads that have already been created and assigned to that customer. In-progress loads, pending invoices, and historical records remain fully intact and accessible. Deactivation only prevents new loads from being created for that customer.
</Note>

To modify a customer's status:

1. Navigate to the Companies page.
2. Open the broker or customer's profile.
3. Locate the customer status button in the top right.
4. Select the status dropdown and change the status, for example to **Inactive**.

<Note>
  📋 Image placeholder: The customer status button in the top right of a customer profile page.

  <img alt="Notion Image" />
</Note>

To reactivate a customer: navigate to the Companies page (use the Inactive or Show All filter to find the record), open the inactive customer's profile, locate the status button, select **Active** from the dropdown.

<Info>
  💡 **Best Practice:** Make deactivation the default action when a customer relationship ends. Reserve deletion for confirmed duplicate records or test entries with no load history. When uncertain, always choose deactivation.
</Info>

### "Delete Customer"

The **"Delete Customer"** permission allows a user to remove a customer record from Alvys. With this permission, a Delete button or menu option is visible on the customer's profile.

Deletion is rarely the right tool. In almost every case, what a user actually wants is deactivation (see **"Activate Customer"** above). This permission should be tightly restricted and used only in clearly justified, exceptional circumstances. It is granted by default to the Support and Partner Admin roles only.

<Warning>
  ⚠️ **Best Practice:** Never grant the **"Delete Customer"** permission to non-admin roles. Assign it only to one or two trusted administrators in your Alvys account, typically the owner and a senior manager. Before deleting a customer, verify that they have no current loads. Consider requiring a second approval outside of Alvys, via your internal process, before proceeding with the deletion.
</Warning>

## Limits & Behavior

The **"Create Customer"** permission covers both creating and importing records of type Customer and BrokerOr3PL. It does not cover creating other company types such as Shippers or Warehouses.

The **New Company** button remains visible to any user who has either **"Create Customer"** or **"Create Company"**. A user with only **"Create Company"** will receive an error if they attempt to create a Customer or Broker/3PL type from the creation form.

Deactivating a customer does not interrupt any load already in progress. Existing loads, pending invoices, and all historical records continue through their normal lifecycle regardless of the customer's activation status.

A deleted customer record is permanently removed; there is no undo. All historical load and invoice records that referenced that customer remain in the system, but the customer profile itself is gone.

## FAQs

**Q: What is the difference between Customer Management and Company Management permissions?**

**A:** Both categories control the same operations (Create, Edit, Activate, Delete) but apply to different entities. Customer Management specifically governs Customer and BrokerOr3PL types. Company Management governs other types like Shippers and Warehouses. The system automatically checks the relevant permission based on the company type.

**Q: Can a user with the Create Customer permission also create a Shipper or Warehouse?**

**A:** No. Creating Shippers or Warehouses requires the **"Create Company"** permission. If a user only has **"Create Customer"** and tries to select "Shipper" on the creation form, the system will return an error because the permissions are gated by company type.

**Q: What happens to active loads if a customer is deactivated?**

**A:** Deactivating a customer only prevents the creation of new loads. Any loads already in progress and pending invoices will continue through their lifecycle normally without interruption.

**Q: What is the benefit of deactivating a customer instead of deleting them?**

**A:** Deactivation (setting a status to Inactive) prevents new business while preserving all historical data and audit trails. An inactive customer can be reactivated at any time, whereas a deleted customer record is permanently lost.

**Q: Which company types are governed by Customer Management permissions?**

**A:** These permissions specifically apply to two company types: Customer and BrokerOr3PL.

## Go Deeper

* [Company Management Permissions](/en/help/administration/company-management-permissions)
* [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Dispatch Permissions
Source: https://docs.alvys.com/en/help/administration/dispatch-permissions

Configure Dispatch permissions that let users assign carriers, override stop statuses or load weights, release loads to billing, and bypass restrictions.

Dispatch permissions control which users can perform core freight movement actions in Alvys, including assigning carriers, recording stop statuses, releasing loads to billing, and overriding carrier compliance restrictions.

## Overview

The Dispatch permissions category in Alvys governs the fundamental actions required to keep freight moving from assignment through delivery and into billing. These permissions cover carrier assignment, stop status management, load weight overrides, load release, and carrier compliance overrides. Each permission targets a specific operational need: a dispatcher managing day-to-day carrier assignments requires the **"Dispatch"** permission, a team member correcting a stop status out of sequence requires **"Override Stop Status"**, a user adjusting a weight set on a load requires **"Override Load Weight"**, a user handing off a delivered load to accounting requires **"Release Loads"**, and a dispatcher assigning a carrier flagged for compliance review requires **"Override Carrier Restriction"**.

## Where to Find It

To assign or modify Dispatch permissions for a user:

1. Open **Settings** from the main navigation.
2. Select **Organization**, then **Users**.
3. Choose an existing user to edit, or select **Add User** to create a new profile.
4. Scroll to the **Permissions** section.
5. Locate the **Dispatch** category. It contains five individual checkboxes: **"Dispatch"**, **"Override Stop Status"**, **"Override Load Weight"**, **"Release Loads"**, and **"Override Carrier Restriction"**.

<img alt="Notion Image" />

<Warning>
  ⚠️ To modify permissions, the logged-in user must hold the **"Set Permission"** permission from the Management category. Without it, a user can view the profile but cannot change any permission checkboxes. See [Management and Privacy Permissions](/en/help/administration/management-privacy-permissions) for details on **"Set Permission"**.
</Warning>

## Key Concepts

### What "permission" means here

A permission in Alvys is a granular authorization checkbox assigned to an individual user profile. Permissions are separate from roles. A user's role (for example, Sales Agent or Office Admin) determines their default access, but individual permissions can extend or restrict what that user can do regardless of role.

### The Dispatch category

The Dispatch category groups five permissions that relate to load execution and handoff. These permissions are independent: a user can hold any combination of them. Granting one does not automatically grant another.

### How permissions interact with load status

Several Dispatch permissions behave differently depending on the current status of a load or trip. The exact status conditions are noted in each permission's section below. Load statuses referenced in this article include: **Open**, **Covered**, **Dispatched**, **In Transit**, **Delivered**, **TONU**, **Released**, **Invoiced**, and **Completed**.

## Settings and Permissions

The table below shows default assignments by role. **Partner Admin** receives all five permissions by default. **Driver** receives none. Individual assignments can be adjusted per user in their profile.

| Permission                   | Admin  | Op. Manager | Dispatcher | Biller | Sales Agent | Data Entry / Office Admin | Safety |
| ---------------------------- | ------ | ----------- | ---------- | ------ | ----------- | ------------------------- | ------ |
| Dispatch                     | ✓      | ✓           | ✓          | –      | ✓           | –                         | –      |
| Override Stop Status         | ✓      | ✓           | ✓          | ✓      | ✓           | ✓                         | –      |
| Override Load Weight         | Varies | Varies      | Varies     | Varies | Varies      | Varies                    | –      |
| Release Loads                | ✓      | ✓           | ✓          | ✓      | –           | –                         | –      |
| Override Carrier Restriction | –      | –           | –          | –      | –           | –                         | –      |

### "Dispatch"

The **"Dispatch"** permission identifies a user as a dispatcher within Alvys and grants authority to perform core dispatching actions. It governs two distinct things: whether the system recognizes the user as an eligible dispatcher for load assignment purposes, and whether the user can edit mileage on load legs.

<Info>
  💡 The act of transitioning a trip's status from Covered to Dispatched using the Dispatch button on the load details page does not require this permission. That action is governed by trip status alone. The **"Dispatch"** permission concerns the identification of a user as a dispatcher and the ability to edit mileage, not the Dispatch button itself.
</Info>

This permission controls the following behaviors:

**My Trips column on the dashboard:** The My Trips column on the Alvys home dashboard is visible only to users who have the Dispatcher or Sales Agent role, or who hold the **"Dispatch"** permission. This allows tenants to give dispatching dashboard access to users in other roles, such as an Operation Manager acting as a dispatcher, without changing their role.

<img alt="Notion Image" />

**Stop leg mileage editing:** Users with this permission can edit mileage for individual trip stop-to-stop legs and the Previous Location miles field on a load. Edit mileage manually when the auto-calculated route distance differs from actual miles driven, or when incorrect values need to be corrected after dispatch.

<img alt="Notion Image" />

<img alt="Notion Image" />

**Dispatcher selector on trips:** When a user opens the dispatcher selector on a trip, the picker dialog is filtered to show only users who hold the **"Dispatch"** permission. This prevents assigning a user who is not recognized as a dispatcher by the system.

<img alt="Notion Image" />

<img alt="Notion Image" />

**Dispatch Planner dispatcher list:** The Dispatch Planner filters its dispatcher dropdown to show only users with the Dispatcher role or the **"Dispatch"** permission. Only users matching either criterion appear for selection.

**Dispatch Planner My Assets tab:** This permission also grants access to the My Assets tab in the Dispatch Planner.

<img alt="Notion Image" />

By default, the **"Dispatch"** permission is granted to the Partner Admin, Admin, Operation Manager, Dispatcher, and Sales Agent roles. It is not assigned by default to the Biller, Data Entry, Office Admin, Safety, or Driver roles.

### "Override Stop Status"

The **"Override Stop Status"** permission allows a user to change a stop's status outside the normal sequential workflow. Under standard conditions, stop statuses progress in a fixed order and the status selector is active only when the trip is in an operational status such as **Covered**, **Dispatched**, **In Transit**, or **Delivered** (provided the driver has not yet been paid).

A user without this permission sees the stop status button, but it remains disabled unless the trip meets those conditions. With this permission, the user can interact with the status selector even when the trip is in a locked status such as **Released** or **Invoiced**, or after driver payment has been recorded.

<img alt="Notion Image" />

<Warning>
  ⚠️ If a load is in **Completed** status, stop statuses cannot be changed even with this permission. Additionally, the trip must have an assigned carrier. If no carrier is assigned, the status button remains disabled regardless of permissions.
</Warning>

By default, the **"Override Stop Status"** permission is granted to the Partner Admin, Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, and Office Admin roles. It is not assigned by default to the Safety or Driver roles.

### "Override Load Weight"

The **"Override Load Weight"** permission allows a user to override the weight values set on a load. Without this permission, a user cannot change a load's recorded weight once it has been entered. This control supports operational corrections, such as adjusting a weight that was entered incorrectly or updating it to match a revised bill of lading, while limiting weight changes to authorized staff.

By default, the **"Override Load Weight"** permission follows your tenant's standard dispatch role configuration. Confirm the current assignment in the Permissions panel for the role in question before relying on it.

### "Release Loads"

The **"Release Loads"** permission authorizes a user to advance a load from **Delivered** or **TONU** status to **Released** status, making it visible to billing and accounting in the invoicing queue. This permission also controls the reverse: moving a load backward from **Released** to its previous operational status. Without this permission, a user cannot perform either the release or the un-release action.

**Release button (Trip Info Panel):** Advances a trip in **Delivered** or **TONU** status to **Released** status.

<img alt="Notion Image" />

**Revert Status button (Trip Info Panel):** Moves a trip from **Released** back to **Delivered** status. The trip must currently be in **Released** status for this button to be available.

<img alt="Notion Image" />

**Release Load button (multi-trip):** Releases all trips on a load at once. This button requires the load to have more than one trip, with at least one trip in **Delivered** or **TONU** status.

<img alt="Notion Image" />

By default, the **"Release Loads"** permission is granted to the Partner Admin, Admin, Operation Manager, Dispatcher, and Biller roles. It is not assigned by default to the Sales Agent, Data Entry, Office Admin, Safety, or Driver roles.

### "Override Carrier Restriction"

The **"Override Carrier Restriction"** permission allows a user to assign a carrier whose compliance status is flagged as NonCompliant or RequiresReview during the carrier assignment process.

When a user with this permission selects a carrier with one of those compliance statuses, a confirmation dialog appears before the assignment is completed. The dialog asks the user to acknowledge the compliance flag and confirm the assignment. Without this permission, the confirmation dialog does not appear; the user cannot proceed with assigning a non-compliant or under-review carrier.

<img alt="Notion Image" />

<img alt="Notion Image" />

By default, the **"Override Carrier Restriction"** permission is not assigned to any role. It must be granted individually to users whose job function requires assigning carriers with active compliance flags.

<Tip>
  **Resolving the underlying compliance issue:** Rather than assigning Override Carrier Restriction broadly, consider clearing the carrier's compliance flag directly. Update the carrier's insurance certificate, RMIS registration, or Highway credentials in the carrier's profile. Once the flag is cleared, standard users can assign the carrier without needing this permission.
</Tip>

## Limits and Behavior

* The **"Dispatch"** permission does not grant access to the Dispatch button on the load details page. That button's availability is governed by the trip's current status (**Covered** or **In Review**), not by this permission.
* The **"Override Stop Status"** permission cannot override the **Completed** load status. Once a load reaches **Completed**, stop statuses are immutable.
* The **"Override Stop Status"** permission has no effect on trips without an assigned carrier. The status button remains disabled regardless of this permission.
* The **"Release Loads"** permission is required for both releasing (forward) and un-releasing (backward) transitions involving **Released** status. Holding the permission grants both directions.
* The **"Release Load"** multi-trip button requires more than one trip on the load and at least one trip in **Delivered** or **TONU** status.
* The **"Override Carrier Restriction"** permission triggers a confirmation dialog rather than silently bypassing the compliance check. The confirmation step is mandatory.
* None of these permissions can be self-assigned. The logged-in user making the change must hold the **"Set Permission"** permission.

## FAQs

**Q: Can I grant Dispatch permissions to a user without changing their role?**

**A:** Yes. Permissions and roles are independent in Alvys. You can assign any Dispatch permission to a user in any role (except Driver) without changing their role. The permission takes effect immediately after saving.

**Q: Why does the Dispatch button on a load still not work after I gave a user the "Dispatch" permission?**

**A:** The Dispatch button transitions a trip from Covered or In Review to Dispatched status. This action is controlled by the trip's current status, not by the **"Dispatch"** permission. If the Dispatch button is unavailable, confirm the trip is in **Covered** or **In Review** status.

**Q: A user with "Override Stop Status" still cannot change a stop. Why?**

**A:** Two conditions block the stop status button even with this permission: the load is in **Completed** status (which is always immutable), or the trip has no assigned carrier. Confirm neither condition applies. If the load is not in **Completed** status and a carrier is assigned, contact Alvys Support.

**Q: What is the difference between releasing a load and dispatching a load?**

**A:** Dispatching a trip moves it from **Covered** or **In Review** to **Dispatched** status and signals that the carrier has been notified. Releasing a load moves a **Delivered** or **TONU** trip to **Released** status and hands it off to billing. These are separate actions controlled by different permissions.

**Q: Who should receive the "Override Carrier Restriction" permission?**

**A:** This permission should be limited to senior dispatchers or operations managers whose role explicitly includes the authority to assign carriers with active compliance flags. It should not be granted broadly, as it bypasses a compliance safeguard that protects the company from liability.

**Q: Which Dispatch permission do I need for each common action?**

**A:** Quick reference:

* Release a load from Delivered or TONU to billing → **Release Loads**
* Revert a load from Released back to Delivered → **Release Loads** (the same permission covers both directions)
* Change a stop status on a Released or Invoiced load → **Override Stop Status**
* Change a stop status on a Covered, Dispatched, or In Transit load → no extra permission needed; governed by the load's status alone
* Assign a carrier with a NonCompliant or RequiresReview flag → **Override Carrier Restriction**
* Edit mileage on a trip leg or Previous Location field → **Dispatch**
* Appear as a selectable dispatcher on trips → **Dispatch**

## Go Deeper

* [User Roles and Permissions Collection](/en/help/administration/user-roles-permissions-collection)
* [Management and Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [Releasing a Load to Billing](/en/help/loads-trips/how-to-release-a-load-to-billing)

## Next Steps

<Info>
  ⏭️ Proceed to [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions) to learn how to control access to user management, carrier management, asset visibility, safety records, and sensitive personal data such as Tax Identification Numbers, Social Security Numbers, and ACH banking details.
</Info>


# E-Check Permissions
Source: https://docs.alvys.com/en/help/administration/e-check-permissions

Control who can issue, cancel, move, or modify e-checks (comchecks) on loads in Alvys with the five per-user E-Check permission toggles.

<Note>
  E-Check permissions control which users can issue, cancel, move, and modify e-checks (also called comchecks or Comcheks). Five individual permissions govern these actions; each is set per user in the Users tab of Company Profile.
</Note>

## Overview

E-check functionality in Alvys is gated by five separate permissions. Each permission controls a distinct action. Users without the correct permission will not see the corresponding button or option. Permissions are assigned at the user level in Management > Company Profile > Users.

E-checks are also called comchecks, Comcheks, money codes, or electronic checks.

## Where to Find It

Navigate to Management > Company Profile, then open the Users tab. Locate the user whose permissions you want to update and click to open their profile. Scroll to the Permissions section to view and toggle the e-check permissions.

<Note>
  <img alt="Screenshot of the Company Profile Users tab" />

  * Screenshot of the Company Profile Users tab\*

    <img alt="Screenshot of the User tab of the Company Profile" />

  *Screenshot of the User tab of the Company Profile*
</Note>

## Key Concepts

**"Issue ECheck":** Allows the user to issue a new e-check from a load. Without this permission, the Manage E-Check button is not visible on the load. This permission is required before any other e-check action is available.

<Note>
  <img alt="Issue ECheck permission toggle" />

  * Issue ECheck permission toggle\*
</Note>

**"Cancel ECheck":** Allows the user to cancel an e-check that has not yet been used or cashed. This permission also requires the **"Add Accessorials"** permission, because cancelling reverses the associated accessorial charge. Without **"Add Accessorials"**, the cancel action will fail even if **"Cancel ECheck"** is enabled.

<Note>
  <img alt="Cancel ECheck permission toggle" />

  *Cancel ECheck permission toggle*
</Note>

**"Move Comchek":** Allows the user to move an e-check from one load to another load assigned to the same driver. This permission also requires **"Add Accessorials"** to function, because moving an e-check transfers its associated accessorial charges. The destination load must have the same driver assigned.

<Note>
  <img alt="Move Comchek permission toggle" />

  *Move Comchek permission toggle*
</Note>

**"Modify E-Check Fee":** Allows the user to edit the fee amount on an existing e-check after it has been issued. This permission also grants access to the Accounting > E-Checks page, which lists all e-checks across loads. Without this permission, users cannot view or search the company-wide e-check list.

<Note>
  <img alt="Modify E-Check Fee permission toggle" />

  *Modify E-Check Fee permission toggle*
</Note>

**"Delete Notes":** Allows the user to delete notes associated with an e-check record. This is a standalone permission independent of the other four e-check permissions.

<Note>
  <img alt="Delete Notes permission toggle" />

  *Delete Notes permission toggle*
</Note>

## How to Use It

To grant or remove an e-check permission: open Management > Company Profile > Users, locate the user, open their profile, scroll to the Permissions section, and toggle the relevant permission on or off. Save the change. The user's access updates immediately.

## Settings & Permissions

Only Admins and Partner Admins can view and modify permissions in the Users tab. Operations Managers cannot grant permissions.

By default, e-check permissions are pre-selected for Admin, Partner Admin, and Operations Manager roles when an active EFS or Comdata integration is detected on the account. Billers and Dispatchers receive no e-check permissions by default.

## Limits & Behavior

**"Cancel ECheck"** requires **"Add Accessorials"** to function. Enabling **"Cancel ECheck"** alone is not sufficient.

**"Move Comchek"** requires **"Add Accessorials"** to function. Enabling **"Move Comchek"** alone is not sufficient.

**"Modify E-Check Fee"** grants view access to Accounting > E-Checks in addition to fee editing. This is the only permission that unlocks the E-Checks accounting page.

Driver-level e-check fee edits (adjusting the cap or percentage on a driver profile) require the **"Edit Asset"** permission, not **"Modify E-Check Fee"**. These are separate controls.

A user who has **"Issue ECheck"** but not **"Cancel ECheck"** can issue e-checks but cannot cancel them. Each action requires its own permission.

## FAQs

**Q: Why can a user see the Manage E-Check button but not cancel an e-check?**

**A:** The user has **"Issue ECheck"** but not **"Cancel ECheck"**. Both are separate permissions. Enable **"Cancel ECheck"** and confirm **"Add Accessorials"** is also enabled on that user.

**Q: Why does the cancel action fail even though Cancel ECheck is enabled?**

**A:** Cancelling an e-check also requires the **"Add Accessorials"** permission. Enable **"Add Accessorials"** on the user and retry.

**Q: Who can access the Accounting > E-Checks page?**

**A:** Only users with the **"Modify E-Check Fee"** permission. This permission controls both fee editing and access to the E-Checks accounting page.

**Q: Can a Dispatcher issue e-checks?**

**A:** Not by default. Dispatchers receive no e-check permissions by default. An Admin or Partner Admin must explicitly enable **"Issue ECheck"** on the Dispatcher's user profile.

**Q: Why can't a user edit the e-check cap on a driver profile?**

**A:** Editing the e-check settings on a driver profile requires the **"Edit Asset"** permission, not any of the five e-check permissions. Enable **"Edit Asset"** on the user's profile.

**Q: Can I bulk-assign e-check permissions to multiple users at once?**

**A:** No. Permissions are set individually per user in Management > Company Profile > Users.

## Go Deeper

* [How to issue an e-check](/en/help/accounting-settlements/how-to-issue-and-manage-e-checks-in-alvys)


# General Permissions
Source: https://docs.alvys.com/en/help/administration/general-permissions

Enable the five General permissions covering DAT and Truckstop load boards, past-date stops, unlocking loads, and viewing maintenance dollar amounts.

<Note>
  General Permissions control access to foundational features that span the entire system, from load-board integrations to editing historical records and viewing financial amounts in maintenance logs.
</Note>

## Overview

General Permissions (sometimes called system-wide permissions or platform permissions) in Alvys control access to foundational features that span the entire system: from integrating with external load boards to editing historical records and viewing financial data in maintenance logs. Unlike rate permissions, which are scoped to individual loads, general permissions typically affect entire sections of the platform or unlock capabilities that apply system-wide.

General Permissions are a set of five individual user-level toggles found in the **General** category of a user's permissions section. Each permission unlocks a distinct capability: enabling DAT or Truckstop freight load board features, selecting past dates on stop dialogs, overriding locks set by other users, and viewing dollar amounts in maintenance records.

General Permissions are distinct from Dispatch or Billing permissions even though they may affect workflows in those areas. For example, **"Unlock Loads"** affects load management but is categorized under General because it is not specific to dispatching or billing alone.

## Where to Find It

General Permissions are configured at the individual user level within the User Management interface, accessible through Management > Company Profile > Users.

<Warning>
  ⚠️ To modify these permissions, the logged-in user must have the **"Set Permission"** permission located within the Management category. · Without it, a user can view a user profile but cannot adjust any permissions. · For more information, see the [Management & Privacy Permissions article](/en/help/administration/management-privacy-permissions).
</Warning>

To reach the General permissions category:

1. Select your **username** in the bottom-left corner, then navigate to **Company Profile** and select the **Users** tab.

   <img alt="Users tab in Company Profile." />

   *Users tab in Company Profile.*
2. Select an existing user to edit, or select **Add User** to create a new profile.

   <img alt="Edit user or Add User button." />

   *Edit user or Add User button.*
3. Scroll to the **Permissions** section and locate the **General** category. You will see five individual checkboxes: **"DAT User"**, **"TruckStop User"**, **"Calendar Past Dates"**, **"Unlock Loads"**, and **"View Maintenance Amounts"**.

<Note>
  <img alt="Five General permission checkboxes in the user permissions form." />

  *Five General permission checkboxes in the user permissions form.*
</Note>

## Key Concepts

General Permissions operate at the per-user level. Each permission is an independent toggle — enabling one does not affect the others. Permissions can be granted or revoked at any time by a user with the **"Set Permission"** permission (Admin, Partner Admin, and Operation Manager roles receive this by default, as does any user who has been explicitly granted the **"Set Permission"** permission).

The five General Permissions are:

* **"DAT User"**: enables DAT load board features within Alvys for that user
* **"TruckStop User"**: enables Truckstop load board features within Alvys for that user
* **"Calendar Past Dates"**: allows the user to select past dates in stop dialogs
* **"Unlock Loads"**: allows the user to unlock loads locked by other users
* **"View Maintenance Amounts"**: shows financial columns in the Maintenance module

## How to Use It

For step-by-step instructions on managing user permissions, see [How to manage user roles and permissions](/en/help/administration/user-roles-permissions-collection).

## DAT User

DAT (Dial-A-Truck / DAT Freight and Analytics) is one of the largest digital freight marketplaces in North America, providing load board services, rate data, and carrier-shipper matching. When a company integrates its Alvys account with DAT, the **"DAT User"** permission controls which individual users can access DAT-powered features within the Alvys interface: posting loads to the DAT load board, deleting postings from DAT, updating posted rates on DAT, and modifying external board rates on loads.

Without this permission, the user will not see DAT-related options in the right-click context menu on the Load Board, even if the company has an active DAT integration.

<Warning>
  ⚠️ This permission is relevant only when your company has the DAT integration enabled at the subsidiary level. · It does not grant access to DAT's own platform or billing; it simply unlocks the DAT features built into the Alvys interface. · For more details on setting up your DAT integration, see [Post Loads to DAT Load Board](/en/help/integrations/post-loads-to-dat-load-board).

  <img alt="DAT integration note callout with screenshot" />

  *DAT integration note callout with screenshot*
</Warning>

This permission affects the following areas:

* **Load Board context menu:** When a user has the **"DAT User"** permission and the subsidiary's DAT integration is active, right-clicking a load with **Open**, **Quoted**, or **Reserved** status displays additional options: **Post Load** (when the load does not yet have a DAT board record), **Update Rate** (for loads already posted), and **Delete Posting** (when a load already has a DAT board record).

  <img alt="Load Board right-click context menu showing DAT options." />

  *Load Board right-click context menu showing DAT options.*
* **Load Details page — Post load:** The Post Load action is also available from within the load details page.

  <img alt="Load Details page showing Post Load option for DAT." />

  *Load Details page showing Post Load option for DAT.*
* **Load Details — Posted Rate:** When the DAT integration is active and the user has this permission, they can modify the Posted Rate field on loads in **Open**, **Quoted**, or **Reserved** status.

<Note>
  <img alt="Load Details Posted Rate field (DAT)." />

  *Load Details Posted Rate field (DAT).*
</Note>

Upon user creation, the Admin, Partner Admin, and Operation Manager roles are automatically granted this permission.

<Info>
  💡 Grant **"DAT User"** to Dispatchers, Operation Managers, and Sales Agents who handle spot freight or manage carrier sourcing. If your company operates exclusively with dedicated carrier relationships, leave this permission disabled for most users to prevent accidental postings.
</Info>

## TruckStop User

The **"TruckStop User"** permission controls whether a specific user can interact with Truckstop-powered features within Alvys. Truckstop (formerly [Truckstop.com](http://truckstop.com/), now part of Truckstop Group) is a major digital freight marketplace that provides load board services, rate intelligence, and freight-matching tools to carriers and brokers across North America. Similar to **"DAT User"**, **"TruckStop User"** acts as a per-user control on top of the company-wide Truckstop integration. Without it, the user will not see Truckstop-related options in the Load Board context menu.

<Warning>
  ⚠️ This permission is relevant only when your company has the Truckstop integration configured and active at the subsidiary level. · It does not grant access to Truckstop's platform or billing; it simply unlocks the Truckstop features within the Alvys interface. · For more details on setting up your Truckstop integration, see [Truckstop Integration](/en/help/integrations/truckstop-load-board-integration).

  <img alt="TruckStop integration note callout with screenshot." />

  *TruckStop integration note callout with screenshot.*
</Warning>

The **"TruckStop User"** permission functions almost identically to **"DAT User"** in terms of where it is evaluated and which UI elements it controls. The primary difference is the target integration: DAT versus Truckstop. Many companies maintain integrations with both platforms simultaneously and may grant one or both permissions to the same user, depending on which load boards that user needs to access.

This permission affects the following areas:

* **Load Board context menu:** When a user has the **"TruckStop User"** permission and the company has an active Truckstop integration, right-clicking a qualifying load displays: **Post Load** (for loads in **Open**, **Quoted**, or **Reserved** status without an existing Truckstop record), **Delete Posting** (when the load has an existing Truckstop board record), and **Update Rate** (for loads in **Open**, **Quoted**, or **Reserved** status).

  <img alt="Load Board right-click context menu showing Truckstop options." />

  * Load Board right-click context menu showing Truckstop options. \*
* **Load Details — External Board Rate:** The user can modify the external board rate field on loads in **Open**, **Quoted**, or **Reserved** status when a Truckstop integration is active.

<Note>
  <img alt="Load Details External Board Rate field (TruckStop)." />

  \*Load Details External Board Rate field (TruckStop). \*
</Note>

Upon user creation, the Admin, Partner Admin, and Operation Manager roles are automatically granted this permission. The following roles do not receive **"TruckStop User"** by default: Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, and Driver.

<Info>
  💡 If your company uses both DAT and Truckstop, decide whether each dispatcher needs access to both or just one. Assign **"TruckStop User"** only to users who are trained on the Truckstop platform and understand your company's posting strategy.
</Info>

## Calendar Past Dates

The **"Calendar Past Dates"** permission controls whether a user can select past dates in the Add Stop dialog when building a load. When the permission is absent, the date picker's minimum selectable date is set to today, preventing the user from picking any date in the past. When the permission is present, the full calendar is available, including all past dates.

This is useful for back-dating scenarios that occur routinely in trucking: for example, adding a stop with a date that has already passed due to a late system entry or a correction.

<Note>
  <img alt="Add Stop calendar without Calendar Past Dates permission (past dates restricted)." />

  *Add Stop calendar without Calendar Past Dates permission (past dates restricted).*

  <img alt="Add Stop calendar with Calendar Past Dates permission" />

  \*Add Stop calendar with Calendar Past Dates permission \*
</Note>

The only role that does not receive **"Calendar Past Dates"** by default is Driver. This permission is relevant to nearly all office-based roles: Dispatchers, Billers, Data Entry, Sales Agents, Office Admins, Operation Managers, and Safety personnel.

<Info>
  💡 Grant **"Calendar Past Dates"** to roles that regularly perform data entry or manage loads. For roles that are intended to be view-only, consider leaving this permission disabled to prevent accidental changes to historical dates.
</Info>

## Unlock Loads

The **"Unlock Loads"** permission allows a user to unlock any load that has been locked by another user. Without this permission, users are limited to unlocking only the loads they have locked themselves.

This capability is essential for maintaining operational continuity when a load becomes inaccessible because the original user is unavailable. A locked load prevents other team members from performing time-sensitive actions such as assigning a carrier, updating rates, or confirming delivery — all of which can impact revenue and customer satisfaction. Granting this permission to designated users provides a controlled override, ensuring that locked loads do not stall operations.

When a load is locked, a closed lock icon is displayed in the top right corner of the load details page. Selecting the icon produces one of two outcomes:

* **With "Unlock Loads" permission:** A confirmation dialog appears asking if the user wants to unlock the load. Confirming releases the lock and allows editing.

<Note>
  <img alt="Notion Image" />

  <img alt="Load details page showing the closed lock icon in the top right corner." />

  \*Load details page showing the closed lock icon in the top right corner. \*

  <img alt="Confirmation dialog asking the user to confirm unlocking the load." />

  *Confirmation dialog asking the user to confirm unlocking the load.*
</Note>

* **Without "Unlock Loads" permission:** The user can see that the load is locked but will not receive a prompt to unlock it (unless they are the user who originally locked it).

The Safety and Driver roles do not receive **"Unlock Loads"** by default. This permission is most relevant for Dispatchers, Billers, Data Entry, Sales Agents, Office Admins, and Operation Managers who regularly edit loads and may encounter locks set by other users.

<Info>
  💡 Ensure that at least two users per shift have the **"Unlock Loads"** permission so that someone is always available to release stuck loads. Avoid granting this permission to users who do not regularly work with loads, as unnecessary access increases the risk of accidental unlocks.
</Info>

## View Maintenance Amounts

The **"View Maintenance Amounts"** permission controls whether a user can see the dollar amounts associated with maintenance records and maintenance expense totals. Without this permission, a user can still view maintenance records if they have the appropriate Management-category permission, but the financial columns — "Amount" in the records grid and "Expenses" in the totals table — are hidden.

By separating the ability to view maintenance records from the ability to view maintenance costs, Alvys provides a clear separation of concerns: operational users see operational data, and financial users see financial data.

<Info>
  💡 **"View Maintenance Amounts"** is only useful if the user also has the **"View Maintenance Records & Totals"** permission from the Management category, which controls access to the Maintenance module itself. Without the Management-category permission, the user cannot access the Maintenance pages where amounts would be displayed.

  <img alt="Maintenance module callout showing the relationship between View Maintenance Amounts and the Management-category permission." />

  *Maintenance module callout showing the relationship between View Maintenance Amounts and the Management-category permission.*
</Info>

This permission specifically affects two areas of the Maintenance module:

* **Maintenance Records Board:** When a user lacks **"View Maintenance Amounts"**, the "Amount" column is removed from the maintenance records grid. The user can still see all other maintenance record details — asset, date, type of service, vendor, and so on — but the dollar amount of each record is hidden.

  <img alt="Maintenance Records Board with the Amount column hidden." />

  *Maintenance Records Board with the Amount column hidden.*
* **Maintenance Totals Table:** When a user lacks this permission, the "Expenses" column is removed from the maintenance totals summary table. The totals table provides an aggregated view of maintenance spending by asset or category; without the permission, the financial aggregations are not visible.

<Note>
  <img alt="Maintenance Totals Table with the Expenses column hidden." />

  * Maintenance Totals Table with the Expenses column hidden.\*
</Note>

The following roles do not receive **"View Maintenance Amounts"** by default: Biller, Sales Agent, Data Entry, and Driver. The default assignment reflects the principle that roles involved in fleet operations and safety need to see maintenance costs, while roles focused on sales, data entry, or billing — which deal with load-related finances rather than maintenance finances — do not require this visibility by default.

<Info>
  💡 Grant **"View Maintenance Amounts"** only to users who have a business need to see maintenance costs, such as fleet managers, safety officers, operations managers, and owners. For users who only need to verify that maintenance was performed — such as checking if a truck is road-ready — the **"View Maintenance Records & Totals"** permission alone is sufficient.
</Info>

## Settings & Permissions

All five General Permissions are set at the individual user level. A user can hold any combination of these permissions regardless of their role. The list below summarizes which roles receive each permission by default upon user creation.

* **"DAT User"**: Admin, Partner Admin, and Operation Manager receive this by default. Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, and Driver do not.
* **"TruckStop User"**: Admin, Partner Admin, and Operation Manager receive this by default. Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, and Driver do not.
* **"Calendar Past Dates"**: All roles except Driver receive this by default.
* **"Unlock Loads"**: Admin, Partner Admin, Operation Manager, Dispatcher, Biller, Data Entry, Sales Agent, and Office Admin receive this by default. Safety and Driver do not.
* **"View Maintenance Amounts"**: Admin, Partner Admin, Operation Manager, Dispatcher, Office Admin, and Safety receive this by default. Biller, Sales Agent, Data Entry, and Driver do not.

To modify any of these permissions, the editing user must hold the **"Set Permission"** permission. Admins, Partner Admins, and Operation Managers have this by default; it can also be granted explicitly to any other user.

## Limits & Behavior

* **"DAT User"** and **"TruckStop User"** have no effect unless the corresponding integration is enabled at the subsidiary level. Enabling the permission for a user when no integration is active does not produce any visible UI change.
* **"Calendar Past Dates"** affects the Add Stop dialog date picker only. It does not affect other date fields in the system.
* **"Unlock Loads"** is not required to unlock a load the user locked themselves; any user can unlock their own locks. The permission is only required to override locks set by other users.
* **"View Maintenance Amounts"** is only meaningful if the user also has the **"View Maintenance Records & Totals"** permission from the Management category. Without it, the user cannot navigate to the Maintenance module at all.
* Permissions changes take effect immediately upon saving; no page refresh or re-login is required.

## FAQs

**Q:** Where can I find the General Permissions section in Alvys?

**A:** Select your username in the bottom-left corner, navigate to **Company Profile**, open the **Users** tab, and select a user to edit. General Permissions are located in the **General** category within the permissions section.

**Q:** What does the **"DAT User"** permission allow a user to do?

**A:** This permission enables users to post loads to the DAT load board, update rates, and delete postings directly from the Alvys interface. These options appear in the right-click context menu on the Load Board for loads in **Open**, **Quoted**, or **Reserved** status.

**Q:** Is the **"TruckStop User"** permission different from the **"DAT User"** permission?

**A:** While they function similarly, they target different platforms. **"TruckStop User"** specifically unlocks Truckstop-powered features such as posting and rate management, whereas **"DAT User"** applies only to DAT Freight and Analytics features.

**Q:** Does the **"Calendar Past Dates"** permission affect all date fields in the system?

**A:** No. It primarily impacts the Add Stop dialog. Without this permission, the date picker restricts the user to today's date or future dates only.

**Q:** How does the **"Unlock Loads"** permission work when a load is locked by another user?

**A:** If a user has this permission, selecting the closed lock icon on the load details page triggers a confirmation dialog. Once the user confirms, the lock is released and they can edit the load. Without this permission, the user can see that the load is locked but will not receive a prompt to unlock it.

**Q:** Can a user unlock a load they locked themselves without the **"Unlock Loads"** permission?

**A:** Yes. Any user can unlock a load they personally locked, regardless of whether they have the **"Unlock Loads"** permission. The permission is only required to override locks set by other team members.

**Q:** What is the relationship between **"View Maintenance Amounts"** and the Management category?

**A:** **"View Maintenance Amounts"** is only functional if the user also has the **"View Maintenance Records & Totals"** permission from the Management category. Without the Management-category permission, the user cannot access the Maintenance module at all.

**Q:** What specific data is hidden if a user lacks the **"View Maintenance Amounts"** permission?

**A:** The "Amount" column is removed from the Maintenance Records grid and the "Expenses" column is removed from the Maintenance Totals summary table. All other non-financial maintenance details remain visible.

## Go Deeper

* [User Roles and Permissions Collection](/en/help/administration/user-roles-permissions-collection)
* [Marketplace Permissions](/en/help/administration/marketplace-permissions)
* [Management and Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [Post Loads to DAT Load Board](/en/help/integrations/post-loads-to-dat-load-board)
* [Truckstop Integration](/en/help/integrations/truckstop-load-board-integration)


# How to Add a Custom Domain to Alvys
Source: https://docs.alvys.com/en/help/administration/how-to-add-a-custom-domain-to-alvys

Send Alvys email from your own company domain by adding the domain, creating CNAME records at your registrar, and validating it in Management > Email.

<Note>
  📋 **Applies to:** All users

  **Module:** Management > Email

  Adding a custom domain to Alvys (also called a sending domain or branded email domain) allows you to send emails from your own company domain instead of a default Alvys address.
</Note>

## Overview

Adding a custom domain to Alvys (also called a sending domain or branded email domain) allows you to send emails from your own company domain instead of a default address. A custom domain lets you send emails from an address at your own company domain, such as [dispatch@mycompany.com](mailto:dispatch@mycompany.com), rather than from a generic Alvys address. This supports your branding and may improve email deliverability.

Setting up a custom domain requires two things: adding the domain in Alvys to generate the required DNS records, and then adding those records at your domain registrar (such as GoDaddy, Google Domains, or [Domain.com](http://domain.com/)).

## Before You Start

Before you begin, confirm the following:

* You have access to your company's domain registrar account (the service where your domain is registered, such as GoDaddy, Google Domains, or [Domain.com](http://domain.com/)).
* You are logged in to Alvys.
* No specific permission beyond being a logged-in Alvys user is required to add a custom domain.

## Steps

### Step 1: Add the domain in Alvys

1. Click your profile in the bottom-left corner of the screen.
2. Select the **Email** option from the menu.
   <img alt="Screenshot showing the profile menu in the bottom left corner with the Email option highlighted." />
   *Screenshot showing the profile menu in the bottom left corner with the Email option highlighted.*
3. Click the **ADD DOMAIN** button.
   <img alt="Screenshot showing the Domains Management screen with the ADD DOMAIN button visible." />
   *Screenshot showing the Domains Management screen with the ADD DOMAIN button visible.*
4. Enter your domain name, for example [mycompany.com](http://mycompany.com/).
5. Click **ADD DOMAIN** to confirm. After adding the domain, Alvys displays the CNAME records you need to add at your domain registrar.
   <img alt="Screenshot showing the CNAME records provided by Alvys after a domain is added." />
   *Screenshot showing the CNAME records provided by Alvys after a domain is added.*

## Step 2: Access Your Domain Registrar

You'll now configure your DNS settings. Log into your domain registrar's management portal (e.g., GoDaddy, Google Domains, or [Domain.com](http://domain.com/)).

## How to Find DNS Settings in Popular Registrars:

* **GoDaddy**: Go to **My Products** > **DNS**.
* **Google Domains**: Go to **My Domains** > **DNS Settings**.
* [**Domain.com**](http://domain.com/): Navigate to **Domain Management** > **DNS**.

💡 For registrar-specific instructions, a simple Google search like "configure DNS CNAME records \[Registrar Name]" can be helpful.

## Step 3: Add CNAME Records

Once you're in your registrar's DNS settings, add the CNAME records provided by Alvys:

1. Look for an option like **Custom DNS Records** or **DNS Management**.
2. For each CNAME record, add the following:
   * **Type**: CNAME
   * **Host**: This will be the subdomain portion (e.g., `s1._`[`domainkey.alvys.com`](http://domainkey.alvys.com/)).
   * **Value**: This is the value provided by Alvys, pointing back to our servers.
3. Save the records.

⚠️For Squarespace users (and legacy Google Domains), please only copy `s1._domainkey` instead of the full host address for all three records. The value can be left as is.

## Step 4: Validate the Domain in Alvys

After configuring the DNS records, return to Alvys and do the following:

1. Navigate back to **Domains Management**.
2. Click **Validate**.
   * If your records are set up correctly, the status will update to **Valid**.
   * If it doesn’t, wait a few minutes (up to 48 hours for DNS propagation) and try again.
   * You may need to refresh the popup for updated status.

## 🌐 Understanding DNS Propagation Time

DNS changes may take time to propagate across the internet. Although most updates are processed within a few minutes to a couple of hours, it can take up to 48 hours in some cases.

## Common Signs of Propagation Issues:

* The domain status does not validate within Alvys after several attempts.
* The CNAME records aren’t reflecting as expected within your DNS checker.

If you're experiencing delays in validation, it’s most likely due to DNS propagation.

**Tip**: Use DNS lookup tools like [DNSChecker](https://dnschecker.org/) to verify if the CNAME records have propagated globally. Simply enter your domain and check whether your DNS settings have taken effect.

By following this guide, you can successfully add and validate your domain in Alvys. If you encounter any issues, don't hesitate to reach out to our support team at [support@alvys.com](mailto:support@alvys.com)


# How to add a USDOT# to a Subsidiary
Source: https://docs.alvys.com/en/help/administration/how-to-add-a-usdot-to-a-subsidiary

Add or update the USDOT number on a subsidiary in the Company Profile, use FMCSA pre-fill, and resolve a USDOT# that is already in use.

<Note>
  Adding a USDOT# (also called a DOT number, DOT#, US DOT number, USDOT number, or Department of Transportation number) to a subsidiary lets Alvys identify your operating entity for regulatory purposes and, when creating a new subsidiary, automatically fills in company details from the FMCSA.
</Note>

## Overview

The USDOT# is a unique identifier assigned by the Federal Motor Carrier Safety Administration to entities involved in interstate and intrastate commerce. In Alvys, you can attach a USDOT# to a subsidiary either at the time you create the subsidiary or after the subsidiary already exists.

When you enter a USDOT# during subsidiary creation, Alvys looks up that number with the FMCSA and pre-fills the subsidiary's name, MC#, company type, physical address, contact email, and phone number. You can review and update any of those pre-filled values before saving.

### Ownership verification

Creating a subsidiary now includes a step that confirms you own the MC# or USDOT# you are registering, before the subsidiary is created. Once you pass it, the verified carrier details pre-fill the form.

Three things follow from this:

* **The verified number is locked.** After a subsidiary is verified, its MC# and USDOT# can no longer be edited. The number prints on rate confirmations and invoices, so a correction is a support request rather than a self-serve edit.
* **An MC# or USDOT# already registered by any Alvys account is refused,** and the reason is shown. This is wider than your own account: another company already operating under that authority blocks it too.
* **If verification cannot be completed, the subsidiary is not created.** Alvys refuses rather than letting an unverified authority through. Try again shortly.

<Note>
  Ownership verification is rolling out to accounts gradually, so you may not see this step yet.
</Note>

## Prerequisites

You must have the **Admin**, **Partner Admin**, or **Support** role to create a subsidiary or edit the company profile. Other roles can open the company profile and read it, but the owner phone, owner email, and operating countries are shown read-only, and **New Subsidiary** is not offered. A field with nothing in it reads **Not Set** rather than inviting you to add a value you would not be allowed to save.

<Note>
  If you are a Biller, Accountant, Dispatcher, or Operation Manager and the option to create a subsidiary is missing, that is expected. It is a role restriction, not a fault and not a plan limit.
</Note>

If you are adding a USDOT# to a new subsidiary, have the USDOT# available before you begin. If you are adding a USDOT# to an existing subsidiary, that subsidiary must not already have a USDOT# assigned; each subsidiary can only have one USDOT#.

## Steps

1. **Open Company Profile:**
   * Select Management in the left navigation.
   * Select Company Profile.
   * Locate the subsidiary you want to update in the subsidiary list on the left side, or proceed to create a new subsidiary.
2. **Add the USDOT# to a new subsidiary (**If you are creating a new subsidiary**)**:
   * Select the option to create a new subsidiary.
   * Enter the USDOT# in the USDOT# field.
   * Alvys contacts the FMCSA and pre-fills the subsidiary name, MC#, company type, physical address, contact email, and phone number based on the USDOT# you entered.
   * Review the pre-filled values. You can edit any of them before saving.
   * Complete all required fields (physical address and remit address are required) and save the subsidiary.

<Note>
  <img alt="Create Subsidiary form with the USDOT# field highlighted and FMCSA pre-fill visible." />

  *Create Subsidiary form with the USDOT# field highlighted and FMCSA pre-fill visible.*
</Note>

\*\*Add the USDOT# to an existing subsidiary (\*\*If the subsidiary already exists and does not yet have a USDOT#):

<Note>
  <img alt="Subsidiary details page showing the USDOT# field with the link to add a DOT number." />

  *Subsidiary details page showing the USDOT# field with the link to add a DOT number.*
</Note>

## Variations

Not all subsidiaries have an MC#. For intrastate-only carriers, the USDOT# alone is sufficient. The FMCSA pre-fill works as long as the USDOT# is valid and registered in the FMCSA database.

## Troubleshooting

### USDOT# field does not appear or cannot be edited

* The USDOT# and MC# fields are locked after a subsidiary is created. You cannot edit a USDOT# that was entered at creation time. If the USDOT# on file is incorrect and you need it changed, contact Alvys support; this is not something that can be self-served, because these fields are locked by design to prevent duplicate subsidiaries in the system.

### FMCSA pre-fill does not populate any fields

* The pre-fill depends on the FMCSA returning a match for the USDOT# you entered. If no data appears, verify that the number is correct and is registered with the FMCSA. The pre-fill is informational only; you can still enter all required fields manually.

### Cannot create a subsidiary with a USDOT# already in use

* The system prevents creating a new subsidiary if the MC# or USDOT# is already registered, and shows you the reason. The check covers every Alvys account, not only your own, so a number held by another company is refused as well. Use a unique USDOT# for each subsidiary, and contact Alvys support if a number you own is reported as already in use.

## FAQs

**Q: Can I edit the USDOT# after a subsidiary has been created?**

**A:** No. Once a subsidiary is created, the USDOT# and MC# fields are locked and cannot be edited. If a correction is needed, contact Alvys support.

**Q: Is a USDOT# required to create a subsidiary?**

**A:** No. The USDOT# is optional when creating a subsidiary. You can create a subsidiary without one and add the USDOT# afterward using the link in the subsidiary details.

**Q: Does adding a USDOT# to an existing subsidiary update any other fields automatically?**

**A:** No. The FMCSA pre-fill only applies during new subsidiary creation. Adding a USDOT# to an existing subsidiary attaches the number only; it does not update the subsidiary name, address, or other fields.

**Q: Can two subsidiaries share the same USDOT#?**

**A:** No. The system prevents creating a subsidiary with a USDOT# that is already registered, whether the existing subsidiary is in your account or in another company's.


# How to Add and Manage Users in Alvys
Source: https://docs.alvys.com/en/help/administration/how-to-add-and-manage-users-in-alvys

Step-by-step guide to add, edit, deactivate, and reset passwords for Alvys user accounts, plus assigning roles and permissions during setup.

<Note>
  This article covers the full lifecycle of a user account in Alvys: creating a new account, assigning a role and permissions, editing an existing profile, deactivating an account when someone leaves, resetting a password, and resetting MFA.
</Note>

## Overview

Every person on your team who needs access to Alvys must have their own unique user account. This article walks you through the entire lifecycle of a user account: creating it for the first time, assigning the appropriate role and permissions, updating access as responsibilities change, deactivating the account when someone leaves, and resetting passwords.

Synonyms: add user, create user, invite user, manage users, user setup, user account management, enable user, disable user, deactivate user.

## Before You Start

Before you can create or edit users, both of the following conditions must be met:

1. Your user account must have one of the following roles: **Admin**, **Partner Admin**, or **Office Admin**. Users assigned any other role — such as **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, **Safety**, **Operations Manager**, or **Driver** — will not see the Users page and cannot create, view, or modify user accounts.
2. To create a new user, your account must have the **"Add User"** permission enabled. To adjust permissions on a new or existing user, your account must also have the **"Set Permission"** permission enabled. Without **"Set Permission"**, you can create an account but cannot modify its permissions, which results in an incomplete setup.

<Info>
  ℹ️ The **Operations Manager** role can update existing users but cannot create new users.
</Info>

## Open the Users page

1. Open **Settings** from the main navigation.
2. Select **Organization**, then **Users**. This displays all active and inactive users in your organization.

<img alt="Notion Image" />

## Open the new user creation form

Click the **Add User** button in the upper right corner of the Users screen. This opens the new user creation form.

<img alt="Notion Image" />

<Info>
  ℹ️ If the **Add User** button is not visible, your account does not have the **"Add User"** permission. Contact your Admin to request access.
</Info>

## Enter the user's basic information

Fill in the following fields:

1. **First and Last Name:** Enter the user's legal or preferred name. This name appears in notifications, activity logs, and throughout Alvys.
2. **Email Address:** Provide a valid work email address. This becomes the user's unique login username and must not already exist in the system.
3. **Password:** Assign a temporary password. Instruct the user to update it immediately on their first login.
4. **Office Location:** Select the branch or office to which the user is assigned.
5. **Role:** Skip this field for now — role selection is covered in the next step.

## Assign a base role

The role you select determines the starting set of permissions the user receives. In the **Role** dropdown, select the role that best matches the user's job function. Refer to the [User Roles in Alvys](/en/help/administration/user-roles-in-alvys) article for a detailed comparison of all roles.

<img alt="Notion Image" />

Common role assignments by job title:

* IT or System Administrator: assign the **Admin** role.
* Company Owner, President, CEO, or General Manager: assign the **Partner Admin** role.
* Operations Manager, Fleet Manager, or Terminal Manager: assign the **Operation Manager** role.
* Office Manager, Administrative Manager, or Back-Office Coordinator: assign the **Office Admin** role.
* Freight Dispatcher, Load Planner, Load Coordinator, or Driver Manager: assign the **Dispatcher** role.
* Billing Clerk, Accounts Receivable/Payable Specialist, Payroll Clerk, or Transportation Accountant: assign the **Biller** role.
* Freight Broker, Logistics Sales Representative, Account Executive, or Business Development Representative: assign the **Sales Agent** role.
* Data Entry Clerk, Administrative Assistant, Load Builder, or EDI Coordinator: assign the **Data Entry** role.
* Safety Manager, DOT Compliance Officer, Fleet Safety Coordinator, or Risk/Compliance Specialist: assign the **Safety** role.

<Warning>
  ⚠️ Do not assign the **Admin** role to every user as a shortcut to give them full access. The Admin role carries significant permissions, including the ability to edit pay plans, view financial data, and modify carrier and customer records, that most dispatchers and data entry staff should not have. Assign the most appropriate restricted role first, then adjust specific permissions as needed.
</Warning>

## Review and adjust permissions

Once a base role is selected, Alvys automatically populates the default permissions for that role. Before saving the account, review and refine the user's access:

1. Scroll down to the **Permissions** area of the user form to view the available toggles organized by operational category.
2. Any toggle currently on (checked) represents an active permission. Evaluate these defaults against the user's specific job responsibilities.
3. Turn individual toggles off for any capability this user should not have.
4. Turn individual toggles on for any additional capability the user specifically needs that is not in the default set.
5. For a full explanation of what each permission does, see the [User Roles and Permissions Collection](/en/help/administration/user-roles-permissions-collection).

<img alt="Notion Image" />

<Info>
  ✅ **Best Practice:** Do not rush this step. Taking a few minutes to review permissions when creating an account is far less disruptive than troubleshooting access issues afterward or discovering that a user had access to sensitive financial data they should not have.
</Info>

## Save the account

1. Once you are satisfied with the role and permission configuration, click the **Add User** button in the bottom left corner of the form.
2. The user will receive a login invitation at their email address. Alternatively, you can share the temporary password directly, depending on your company's onboarding process.
3. The new user now appears in your Users list and is active immediately upon saving.

<Info>
  ℹ️ If you are setting up an account for someone who has not yet started, you can create it in advance and ask them to change their password on their first day.
</Info>

## Confirm access

After saving the new account, follow these steps to verify the user has the correct access:

1. Ask the new user to log in and confirm they can reach all operational sections required for their role.
2. Have them report any areas where they receive an "Access Denied" message or do not see expected buttons. These instances indicate a missing permission toggle.
3. Return to the user's profile in **Settings → Organization → Users** to enable any missing permissions.

## Variations

### Editing an existing user's profile

To change a user's name, email, role, or individual permissions:

1. Navigate to **Settings → Organization → Users**.
2. Find the user by name or email. Use the search bar if your team is large.
3. Click the user's name or row to open their profile.
4. You will see the user's basic information, assigned role, and current permission toggles.
5. Modify the fields you need to change. To reassign the user to a different role, change the **Role** dropdown.
6. Adjust individual permission toggles as needed, then save.

<img alt="Notion Image" />

<Warning>
  ⚠️ Changing a role automatically resets all permissions to the new role's defaults. Review the permission toggles after a role change to ensure they reflect the intended access.
</Warning>

<Info>
  ✅ **Best Practice:** Review user profiles periodically, ideally quarterly, to ensure people only have access that matches their current job responsibilities.
</Info>

### Resetting a user's password

If a user forgets their password or you need to reset access:

1. Open the user's profile (steps above).
2. Select the **Reset Password** option.
3. Alvys sends a password reset link to the user's registered email address.
4. Notify the user to check their email and click the link to set a new password.

<img alt="Notion Image" />

### Resetting a user's MFA

If a user is locked out because they have lost access to their MFA device or app, an Admin or Partner Admin can reset their enrolled authenticators. The user will be prompted to set up MFA again at their next sign-in.

1. Navigate to **Settings → Organization → Users** and open the user's profile.
2. Click **Reset MFA**.
3. Confirm. The user's enrolled authenticators are cleared immediately.

<Warning>
  ⚠️ A Partner Admin cannot reset MFA for another Partner Admin. Those requests must go through Alvys Support.
</Warning>

### Deactivating and reactivating a user

Deactivating a user account is the correct action when someone leaves your company or takes an extended leave. Deactivation prevents the user from logging in immediately, preserves their historical activity log and audit trail in Alvys, and allows the account to be reactivated in the future if needed.

To deactivate a user:

1. Find the user by name or email in the Users list.
2. From the user row, select the status dropdown menu.
3. Set the account to **Disabled**.
4. Save. The user will be unable to log in from this point forward.

<img alt="Notion Image" />

<Info>
  ✅ **Best Practice:** Deactivate a departing employee's account on their last day, ideally before their shift ends. Do not wait until their IT equipment has been returned or their email has been shut down, as an active Alvys login still allows access from any device.
</Info>

To reactivate: return to the user's profile, select the status dropdown, set it to **Active**, and save. The user will regain access with their previous permissions intact.

<Tip>
  Use the **Status filter** on the Users list to locate disabled users quickly before reactivating their account.
</Tip>

## Troubleshooting

### Add User button is not visible

The **Add User** button is controlled by the **"Add User"** permission. If the button does not appear on the Users screen, your account does not have this permission enabled. Contact your Admin and ask them to enable the **"Add User"** permission on your profile.

### Users page is not visible in the navigation

The Users page is only accessible to users with the **Admin**, **Partner Admin**, or **Office Admin** role. If **Settings → Organization → Users** is not visible, your account is assigned a different role. Contact your Admin if you believe your role is incorrect.

### User receives Access Denied after account is created

This indicates a missing permission toggle. Identify which action the user was attempting, then open their profile in **Settings → Organization → Users** and enable the corresponding permission. If the permission is not visible in their profile, verify that your own account has the **"Set Permission"** permission enabled.

### Cannot adjust permissions on a user profile

Modifying permissions requires the **"Set Permission"** permission on your own account. If the permission toggles are visible but not editable, contact your Admin and ask them to enable **"Set Permission"** on your profile.

### Role change reset the user's custom permissions

This is expected behavior. Changing a user's base role automatically resets all permission toggles to the new role's defaults. After any role change, scroll to the Permissions area and re-apply any custom toggles the user needed.

### User is not appearing in the Users list

If a user is missing from the list but the system indicates they already exist, the cause is usually the account's status or its role classification.

**Disabled account**

* **Cause:** The user profile exists but is disabled.
* **Solution:**
  1. Navigate to **Settings → Organization → Users**.
  2. Use the **Status filter** to view disabled users.
  3. Locate the user and change their status to **Active**.
  4. The user should now appear in the list and regain access.

**Role misclassification**

* **Cause:** The user is assigned to an incorrect role (for example, Driver instead of Dispatcher).
* **Solution:**
  1. Review the user's role classification.
  2. Reassign them to the correct role.
  3. The user will appear in the appropriate list and have the correct access.

### Email conflict error when adding a new user

If you see an error stating that the email already exists, an existing or deactivated account is already using that address.

1. Go to **Settings → Organization → Users** and search for the email, including disabled users by filtering on status.
2. If the account is disabled, reactivate it.
3. If a different person will use the same email, update the name as needed. The user can then set their own password with the **Forgot Password** option.
4. If you genuinely need a separate account with a similar address, use a variant such as `dispatch1@example.com`.

### User is unable to log in, or the account shows as already active

* **Cause:** The account exists but is disabled.
* **Solution:**
  1. Go to **Settings → Organization → Users**.
  2. Use the **Status filter** to view disabled users.
  3. Locate the user and set their status back to **Active**.
  4. Ask the user to try logging in again.

## FAQs

**Q: Which roles can access the Users page?**

**A:** The Users page under **Settings → Organization** is visible only to users with the **Admin**, **Partner Admin**, or **Office Admin** role. Users with any other role will not see this option.

**Q: What happens if I change a user's base role after customizing their permissions?**

**A:** Changing a role automatically resets all permissions to the new role's defaults. You must review and re-apply the permission toggles after switching a role to ensure the intended access is maintained.

**Q: Should I delete or deactivate an account when an employee leaves?**

**A:** Deactivation is strongly preferred. It prevents the user from logging in while preserving their historical activity logs and audit trails. If you do need to permanently delete a user, open their profile in **Settings → Organization → Users** and use the **Delete user** option. Deletion cannot be undone and removes the user's historical data from the system.

**Q: Can multiple employees share a single Alvys login?**

**A:** No. Every user must have a unique email address. Shared accounts compromise security and make it impossible to track which individual performed specific actions.

**Q: Does deactivating a user affect the loads they previously dispatched?**

**A:** No. Deactivation only blocks future logins. All historical records, including dispatched loads and processed invoices associated with that user, remain intact for reporting and audit purposes.

**Q: Can an Admin reset MFA for another user?**

**A:** Yes. Admins and Partner Admins can clear a user's enrolled authenticators with the **Reset MFA** button on the user's profile. The one exception is that a Partner Admin cannot reset MFA for another Partner Admin — contact Alvys Support for those requests.

**Q: What should I do if I get an error saying the email already exists?**

**A:** Search for the email in **Settings → Organization → Users**, including disabled users in your search. If the account is disabled, reactivate it. If a different person will use the same email, update the name and have them reset their password. Alternatively, create a new account using a variant of the email address.

## Go Deeper

* [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)
* [User Permissions Glossary](/en/help/administration/user-permissions-glossary)
* [User Roles and Permissions Collection](/en/help/administration/user-roles-permissions-collection)

## Next Steps

<Info>
  ⏭️ Proceed to the [User Permissions Glossary](/en/help/administration/user-permissions-glossary) to understand the full list of user permissions available in Alvys and what each permission controls. This includes guidance on permission categories, feature access, and role-specific visibility, helping ensure each user is assigned the right permissions for their responsibilities.
</Info>


# How to Manage Your Alvys Subscription
Source: https://docs.alvys.com/en/help/administration/how-to-manage-your-alvys-subscription

Review your Alvys subscription plan, view invoices and payment history, update your Stripe payment method, and manage billing from the Billing page.

<Note>
  Use the Billing page in Alvys to review your subscription details, view invoices and payment history, and manage your payment method. Linking and unlinking Stripe accounts requires the Support role.
</Note>

## Overview

The Billing page in Alvys gives you visibility into your subscription plan (your service plan or account), current charges, upcoming invoices, and payment history. From this page, you can update the payment method associated with each subscription. Alvys uses Stripe to process subscription payments; depending on your bank or card statement, charges may appear with Stripe in the descriptor.

Support users can also link or unlink your company's Stripe account directly from this page.

## Before You Start

Required role to access the Billing page: Admin, Partner Admin, or Support. If you do not see a Billing option in your user menu, your account does not have the required role.

Linking or unlinking a Stripe account additionally requires the Support role. Admins and Partner Admins can view billing details and manage payment methods but cannot perform the Link Stripe or Unlink Stripe actions.

## Steps

1. **Open the Billing page**

   Click your user icon in the bottom-left corner of Alvys and select **Billing**. You can also navigate directly to Administration > Billing.
2. **Review subscription and billing details**

   From the Billing page you can:

   * Review your current plan and charges.
   * View upcoming invoices and payment history.
   * Update your payment method for any active subscription (card or ACH, if available for your account).
   * Download invoices or receipts where applicable.
3. **Update your payment method**

   To update your payment method, locate the payment method section on the Billing page and follow the on-screen prompts. Each active subscription can have its own payment method assigned. To switch to ACH bank transfer and avoid the 2.9% card processing fee, see How to Switch to ACH Payments for Alvys Billing.
4. **Link a Stripe account (Support only)**

   <img alt="Screenshot of the Billing page showing the Link Stripe button and the modal dialog for searching and selecting a customer's Stripe account." />

   *Screenshot of the Billing page showing the Link Stripe button and the modal dialog for searching and selecting a customer's Stripe account.*
5. Click the **Link Stripe** button on the Billing page.
6. A modal dialog will appear. Use the search field to find and select the customer's Stripe account.
7. Follow the on-screen prompts to complete the linking process. The company profile billing data will automatically refresh to reflect the linked account.
8. **Unlink a Stripe account (Support only)**

   <img alt="Screenshot of the Billing page showing the Unlink Stripe button and the confirmation dialog" />

   *Screenshot of the Billing page showing the Unlink Stripe button and the confirmation dialog*
9. Click the **Unlink Stripe** button on the Billing page.
10. A confirmation dialog will appear asking you to confirm the action.
11. Review the information and confirm to proceed. The company profile billing data will automatically refresh to reflect the unlinked state.

## Result

Your Billing page reflects the current state of your subscription, payment method, and invoice history. Changes to the linked Stripe account (link or unlink) take effect immediately after the on-screen confirmation.

## Troubleshooting

### Link Stripe or Unlink Stripe button is not visible

The **Link Stripe** and **Unlink Stripe** buttons are only visible to users with the Support role. Admins and Partner Admins can access the Billing page but do not see these buttons. If you need to link or unlink a Stripe account, contact an Alvys Support team member.

### An invoice or receipt cannot be found

Invoices and payment history are listed on the Billing page. If you cannot find what you need, contact Support and include your company name, the date, and the amount of the charge.

## FAQs

**Q: Why do I see a charge from Stripe on my bank or card statement?**

**A:** Alvys uses Stripe to process subscription payments. Depending on your bank or card statement, charges may appear with Stripe in the descriptor rather than with the Alvys name.

**Q: Can I get a copy of my invoice or receipt?**

**A:** Invoices and payment history are available on the Billing page. If you cannot access what you need there, contact Support and include your company name, the date, and the amount of the charge.

**Q: What if my bank is not available for Instant Verification via Stripe?**

**A:** If instant bank verification is not available for your institution, fill out the [Bank Draft (ACH) Authorization Form](https://eform.pandadoc.com/?eform=d34a3cfc-d855-45f9-9e48-2e2378e06b31) so the Alvys billing team can securely enter your bank information. The billing team will reach out to continue the verification process via micro-deposit confirmation.

## Go Deeper

How to Switch to ACH Payments for Alvys Billing


# How to map accessorials for EDI
Source: https://docs.alvys.com/en/help/administration/how-to-map-accessorials-for-edi

Map accessorial charges to partner trading codes and vendor descriptions so EDI files send correct detention, fuel surcharge, and add-on fees to shippers.

<Note>
  Accessorial EDI mapping ensures that extra charges on loads are correctly identified in EDI files: each trading partner requires their own unique trading codes and vendor descriptions before the mapping is active.
</Note>

Accessorial EDI mapping ensures that extra charges on your loads (such as detention or fuel surcharges) are correctly identified in EDI files exchanged with your trading partners. Each partner requires their own unique trading codes and exact vendor descriptions.

## Overview

Accessorial mapping for EDI (Electronic Data Interchange) configures how extra shipping charges, also called surcharges or add-on fees, appear in EDI files exchanged with trading partners. Without correct mapping, accessorial charges may fail validation or be misrouted during EDI transactions. Each trading partner requires their own partner trading code and exact vendor description before the mapping is active.

## Before You Start

You must have Admin or Partner Admin access to reach the EDI & Visibility settings.

To map accessorial types, **partner trading codes** and **exact vendor descriptions** are required to ensure smooth and accurate communication between trading partners. Here’s why:

* **Partner Trading Codes**: These are unique identifiers assigned to each trading partner. They help the system recognize where the data is coming from and ensure it is routed to the correct partner. Without these codes, transactions may fail or be misdirected.
* **Exact Vendor Descriptions**: These provide precise details about the items or services being exchanged. They ensure that both partners interpret the data the same way, avoiding confusion or errors in orders, shipments, or billing.

## Steps

**Open EDI & Visibility settings**

Navigate to Settings > EDI & Visibility.

**Select the EDI partner**

Locate the partner you want to configure and click to open their settings panel.

**Scroll to Accessorial Mapping**

Scroll down within the partner settings panel to find the Accessorial Mapping section.

<Note>
  <img alt="Screenshot showing the Accessorial Mapping section within an EDI partner settings panel." />

  *Screenshot showing the Accessorial Mapping section within an EDI partner settings panel.*
</Note>

**Enter trading codes and vendor descriptions**

For each accessorial type you want to map, enter:

* Partner Trading Code: the unique identifier your trading partner uses for this accessorial type
* Exact Vendor Description: the precise description text your trading partner expects for this charge

If an EDI partner is not correctly mapped you’ll notice a yellow “needs attention” badge within the card. This will also appear in the accessorial settings area, alerting you that an EDI partner may not be configured correctly. Once configured correctly this will display as **Active.**

<Note>
  <img alt="Screenshot showing a completed accessorial mapping row with trading code and vendor description filled in, with the status showing Active vs an incomplete one that needs attention" />

  *Screenshot showing a completed accessorial mapping row with trading code and vendor description filled in, with the status showing Active vs an incomplete one that needs attention*
</Note>

**Save and verify**

Save the settings. A correctly mapped accessorial shows as **Active** on its card. An unmapped or incorrectly entered accessorial displays a yellow "needs attention" badge.

## Result

Once all accessorial types show as **Active**, EDI files exchanged with that partner will include the correct codes and descriptions. The yellow "needs attention" badge will no longer appear.

## Troubleshooting

### Yellow "needs attention" badge remains after saving

Return to the Accessorial Mapping section. One or more accessorial types are still missing a trading code or vendor description, or the entered values do not exactly match what the partner expects. Verify each entry against the partner's specification and save again.

### Accessorial not appearing in EDI files after mapping

Confirm the accessorial type is also added to the load in the Money Box. Mapping only configures the code translation in EDI; the accessorial must be present on the load for it to be included in EDI output.

## FAQs

**Q: What are partner trading codes?**

**A:** Partner trading codes are unique identifiers assigned by your EDI trading partner to each type of extra charge. They ensure the receiving system routes the accessorial data to the correct record. Obtain them directly from your trading partner.

**Q: What happens if a trading code is entered incorrectly?**

**A:** The mapping will not function correctly. EDI transactions that include that accessorial type may fail or be misrouted. Correct the code in Settings > EDI & Visibility and save.

**Q: Can I map the same accessorial type to multiple EDI partners?**

**A:** Yes. Each EDI partner has its own Accessorial Mapping section. The same accessorial type can be mapped separately for each partner with different trading codes and descriptions as required.

## Go Deeper

* [How to create and add accessorials](/en/help/loads-trips/how-to-create-and-add-accessorials)


# How to Set Up Custom References in Alvys
Source: https://docs.alvys.com/en/help/administration/how-to-set-up-custom-references-in-alvys

Define custom-named reference fields on loads, trips, stops, drivers, customers, locations, and other records so your team can capture and search the identifiers your customers use.

<Note>
  📋 **Applies to:** Admin · Partner Admin · Operation Manager

  **Module:** Settings > Custom References

  Custom References let you define and attach custom-named fields to loads, trips, stops, drivers, trucks, trailers, customers, and locations in Alvys so your team can capture business-specific information not covered by standard fields.
</Note>

## Overview

Custom References let you define and attach custom-named fields (also called user-defined fields or custom data fields) to loads, trips, stops, drivers, trucks, trailers, customers, and locations in Alvys, so your team can capture business-specific information not covered by standard fields.

Custom References allow your organization to create additional data fields tailored to your operations. Once defined, these fields appear on the relevant entity pages throughout Alvys and can be included on documents such as rate confirmations and invoices.

Supported field types are Text, Date, Select, and Checkbox. References can be applied to Loads, Trips, Stops, Drivers, Trucks, Trailers, Customers, and Locations.

Load and Trip Custom References also display on the Driver Mobile App within Trip Details. Driver Custom References display on the Driver Mobile App within the Driver Profile.

Custom Load References appear as custom columns on the Load Board once created.

## Before You Start

You must be an **"Admin"**, **"Partner Admin"**, or **"Operation Manager"** to access Settings > Custom References. This setting must be enabled for your account; if you do not see Custom References in Settings, contact Alvys Support.

## Steps

### Navigate to Settings > Custom References

1. Click your user profile menu in the bottom-left corner of Alvys.
2. Select **Settings** from the menu.
3. Click **Custom References** in the left navigation panel.

<Note>
  <img alt="Screenshot showing the Settings navigation with Custom References selected in the left panel." />

  *Screenshot showing the Settings navigation with Custom References selected in the left panel.*
</Note>

### Select the entity tab

1. The Custom References page is organized by entity type. Select the appropriate tab: **Loads**, **Trips**, **Stops**, **Drivers**, **Trucks**, **Trailers**, **Customers**, or **Locations**.
2. The table displays the **Field Name**, **Description**, **Date Created**, and **Created By** for each existing reference on that entity.
3. You can rearrange, sort, and search these columns to manage the list.

<Note>
  <img alt="Screenshot showing the Custom References management page with entity tabs (Loads, Trips, Stops, Drivers, Trucks, Trailers) visible." />

  *Screenshot showing the Custom References management page with entity tabs (Loads, Trips, Stops, Drivers, Trucks, Trailers) visible.*
</Note>

### Create a new reference

1. Click the **New Reference** button (blue button in the top right) to open the creation modal.

<Note>
  <img alt="Screenshot showing the full New Reference form with all fields visible" />

  *Screenshot showing the full New Reference form with all fields visible*
</Note>

<Note>
  <img alt="Screenshot showing the Driver Mobile App with Load and Trip Custom References displayed under Trip Details and the View All References toggle." />

  *Screenshot showing the Driver Mobile App with Load and Trip Custom References displayed under Trip Details and the View All References toggle.*
</Note>

1. Fill in the following fields:
   * **Name:** Enter a name that is easily identifiable by others in your organization.
   * **Description:** Optionally describe what this reference is intended for.
   * **Field Type:** Choose the type that best suits the data you want to store. Options are Text, Date, Select, and Checkbox. You cannot change the field type after saving.
   * **Include in Alvys:** Check the boxes to indicate which pages in Alvys should display this reference.
   * **Show on documents:** Check the boxes to indicate which documents should display this reference (for example, rate confirmations or invoices).

<Note>
  <img alt="Screenshot showing the Driver Mobile App with Driver Custom References displayed within the Driver Profile." />

  *Screenshot showing the Driver Mobile App with Driver Custom References displayed within the Driver Profile.*
</Note>

Load and Trip Custom References display on the Driver Mobile App within Trip Details. If you click **View All References**, you can toggle between tabs to see Load or Trip Custom References. Driver Custom References display on the Driver Mobile App within the Driver Profile.

<Note>
  <img alt="Screenshot from the driver's profile" />

  *Screenshot from the driver's profile*
</Note>

### Save the reference

1. Click **Save**. The reference is immediately available for use on the selected entity.
2. Confirm the new reference appears in the list on the correct entity tab.

The custom reference is now active and visible to all users on the pages and documents you selected. Users can fill in the field when creating or editing the relevant entity (load, trip, stop, driver, truck, trailer, customer, or location). Custom Load References appear as additional columns on the Load Board. Customer and location references appear in a **References** section on the company or location profile, and each reference can be shown as a column on the Customers and Locations grids.

<Note>
  ℹ️ Customer and location reference values are available through the public API. On the Customers and Locations grids, the reference columns display values but do not yet support sorting or filtering, and reference values are not yet included in the Customers or Locations CSV export. Rate confirmations, Bills of Lading, and invoices do not carry customer or location references, matching the behaviour for driver, truck, and trailer references.
</Note>

<Warning>
  ⚠️ You can only create up to 20 references associated with Loads or Trips but unlimited references for Stops.
</Warning>

<Note>
  ℹ️ The custom load references you set up at the Load Level will be mirrored as custom reference columns on the Load Board.
</Note>

## Managing Existing Custom References

To edit an existing reference, click **Edit** on the right side of the row. The creation modal opens with the existing data. You can change the Name, Description, and View settings. You cannot change the Field Type.

Changes to an existing reference apply only to new entities created after you save. Existing and historical records retain the previous reference settings.

<Note>
  <img alt="Screenshot showing the Edit reference modal for an existing custom reference." />

  *Screenshot showing the Edit reference modal for an existing custom reference.*
</Note>

<Note>
  <img alt="Screenshot showing the Enable/Disable toggle inside the Edit reference modal." />

  *Screenshot showing the Enable/Disable toggle inside the Edit reference modal.*
</Note>

<Tip>
  💡 Note: Only stop references that have been attached manually can be edited. Stop references coming from EDI / Ratecon / Marketplace cannot be edited
</Tip>

## Troubleshooting

### Custom References option is not visible in Settings

1. Confirm you are signed in as an **"Admin"**, **"Partner Admin"**, or **"Operation Manager"**. Other roles do not have access to Settings > Custom References.
2. Confirm that the Custom References feature is enabled for your account. If you do not see the option after verifying your role, contact Alvys Support with your account name so they can confirm whether the feature is enabled.

### Reference appears grayed out in the list

1. A grayed-out reference has been disabled. Click **Edit** on that row.
2. Toggle the **Enable** switch in the top-right corner of the modal to the Enabled position and click **Save**.

### New reference does not appear on loads or other entities

1. Confirm you checked the correct boxes under **Include in Alvys** when creating the reference. If the relevant page was not checked, the field will not appear there.
2. Open the Edit modal for the reference, verify the Include in Alvys selections, update as needed, and save. The change applies to new entities only; existing records are not affected.

## FAQs

**Q: Where do I enter a custom reference for a driver once it has been created in Settings?**

**A:** You can add Driver custom references on the Driver Profile page.

**Q: What happens to existing loads if I change the View settings for a Custom Load Reference?**

**A:** The change applies only to new loads created after you save. Any existing or active loads retain the previous view settings. Review any references previously set to show on all documents, as their display settings on historical loads will not change.

**Q: Why is my custom reference grayed out in the list?**

**A:** A grayed-out reference has been disabled. To re-enable it, click the Edit icon, toggle the Enable switch in the top-right corner of the modal to the Enabled position, and save.

**Q: How many custom references can I create?**

**A:** You can create up to 20 custom references for Loads and up to 20 for Trips. There is no limit on references for Stops, Drivers, Trucks, or Trailers.

**Q: Can I sort and filter by custom references on the Load Board or Dispatch Planner?**

**A:** Sorting and filtering by custom reference columns on the Load Board and Dispatch Planner is not yet available. The same limit applies to the customer and location reference columns on the Customers and Locations grids: values display, but sort and filter are not yet supported. These capabilities are planned for a future release.


# How to Set Up Offices in Alvys
Source: https://docs.alvys.com/en/help/administration/how-to-set-up-offices-in-alvys

Create offices in Alvys to group users, loads, and customers, set commission rates, and configure office-to-office load data sharing between subsidiaries.

<Note>
  Offices are organizational units in Alvys that group users and loads together, limiting each user's data access to the loads and customers linked to their assigned office.
</Note>

## Overview

Setting up offices in Alvys, also called subsidiaries or organizational units, helps limit the scope of information users can access by associating them with specific offices. It also improves data organization by ensuring users only see loads and customers relevant to their assigned office.

When creating or editing an office, you can configure which other offices it shares load data with. Users from one office can access loads from another office when load sharing (data sharing) is enabled between those offices.

Deletion of an office requires contacting Alvys Support, as there is no self-service delete option for offices.

## Prerequisites

You must have the **"Admin"** or **"Partner Admin"** role to create and edit offices. **"Office Admin"** users can view the Offices section but cannot create or edit offices.

## Steps

**Navigate to Offices.**

1. Click **Management** in the top navigation bar.
2. Select **Company Profile** from the menu.
3. Click the **Offices** tab.

   **Create a new office.**
4. Click **Add Office** to open the office creation form.
5. Fill in the following fields:

   * **Name:** Enter a name for the office.
   * **Address:** Enter the office address.
   * **Commission Rates:** Set the commission rates that apply to loads associated with this office.
   * **Data Sharing:** Select which other offices this office will share load data with. Users assigned to this office will be able to view loads from the shared offices.
6. Click **Save** to create the office.

   <img alt="GIF showing the process of navigating to Offices and creating a new office including name, address, commission rates, and data sharing fields" />

   *GIF showing the process of navigating to Offices and creating a new office including name, address, commission rates, and data sharing fields*
7. Assign users to the office.
8. When adding a new user, assign them to the appropriate office during the user creation process (Management > Company Profile > Users > Add User).
9. For existing users, open their user profile and update the Office field to associate them with the correct office.
10. Users assigned to an office can generally view only the loads and customers linked to that office, unless load sharing is configured between offices.
11. Configure load sharing (optional).
12. Open an existing office by clicking on its name in the Offices list.
13. Under the **Data Sharing** section, select the offices whose loads this office's users should be able to access.
14. Save the changes.

    <img alt="Screenshot showing the Data Sharing configuration panel on an office, with other offices listed for selection" />

    *Screenshot showing the Data Sharing configuration panel on an office, with other offices listed for selection*

Once an office is created and users are assigned, those users see only the loads and customers associated with their office (and any offices included in the data sharing configuration). New loads created by users in that office are linked to that office automatically.

To edit an office, navigate to Management > Company Profile > Offices, click on the office name, update the relevant fields (name, address, commission rates, or data sharing), and save. You cannot delete an office through the Alvys interface; to delete an office, contact Alvys Support with the name of the office you want to remove, and ensure no active users or loads are assigned to the office before requesting deletion.

## Troubleshooting

### Add Office button is not visible

1. Confirm you are signed in with the **"Admin"** or **"Partner Admin"** role. **"Office Admin"** and other roles cannot create offices and will not see the Add Office button.
2. If you have an **"Admin"** or **"Partner Admin"** role and the button is still not visible, contact Alvys Support with your account name and role for investigation.

### Users can see loads from other offices they should not access

1. Open the office record for the user's assigned office (Management > Company Profile > Offices > click the office name).
2. Review the **Data Sharing** section. Remove any offices that should not be sharing data with this office and save.
3. If the issue persists after removing data sharing, contact Alvys Support.

### User is not seeing loads associated with their office

1. Open the user's profile (Management > Company Profile > Users) and confirm the Office field is set to the correct office.
2. If the office assignment is correct and the user still cannot see the expected loads, verify that those loads are linked to the correct office. Contact Alvys Support if the issue continues.

## FAQs

**Q: Can a user be assigned to more than one office?**

**A:** Each user is assigned to one office. Load visibility across multiple offices is controlled through the Data Sharing setting on each office, not by assigning users to multiple offices.

**Q: Will changing a user's office assignment affect loads they have already worked on?**

**A:** Changing a user's office assignment does not retroactively change the office association on historical loads. It only affects which loads the user can see going forward based on the new office's data sharing configuration.

**Q: Who can delete an office?**

**A:** Offices cannot be deleted through the Alvys interface. Contact Alvys Support to request office deletion. Before requesting, ensure no active users or loads are assigned to that office.

**Q: What is the difference between commission rates set on the office and rates set elsewhere?**

**A:** Commission rates configured on an office apply to loads associated with that office. If you need to understand how office-level commission rates interact with other rate configurations, contact Alvys Support for guidance specific to your setup.


# How to Switch to ACH Payments for Alvys Billing
Source: https://docs.alvys.com/en/help/administration/how-to-switch-to-ach-payments-for-alvys-billing

Move your Alvys subscription from card to ACH bank transfer in the Stripe portal to avoid the card processing fee, and fix failed bank verification.

<Note>
  📋 **Applies to:** Admins · Partner Admins · Support

  **Module:** Administration > Billing

  Switch your Alvys billing payment method from credit or debit card to ACH bank transfer to avoid the 2.9% card processing fee that applies starting May 1, 2026.
</Note>

## Overview

ACH (Automated Clearing House) payments, also called bank draft, direct debit, or ACH payment, let you pay your Alvys subscription directly from a bank account with no additional processing charge. Starting May 1, 2026, a 2.9% processing fee applies to all credit card and debit card payments made to Alvys. This fee is charged by the card processor, not by Alvys, and reflects standard card processing costs. Switching to ACH removes this fee entirely.

Alvys uses Stripe to process ACH payments through a secure, encrypted connection. Your bank account is verified either instantly (by logging in through Stripe's portal) or manually (via small micro-deposits sent to your account).

## Before You Start

Required role: Admin, Partner Admin, or Support. Access to the Billing page is restricted to these roles. If you do not see a Billing option in your user menu, your account does not have the required role. Contact [support@alvys.com](mailto:support@alvys.com) for assistance.

Have your bank account number and routing number available before you begin. If your bank does not support Stripe instant verification, you will need to complete a Bank Draft (ACH) Authorization Form instead (see the manual verification path below).

## Steps

1. **Open the Billing page**
   Click your user icon in the bottom-left corner of Alvys and select **Billing**. You can also navigate directly to Administration > Billing.
   <img alt="Opening the Billing page from the user menu" />
   *Opening the Billing page from the user menu*
2. **Open Manage Payment Methods**
   Find the **Manage Payment Methods** section at the center of the Billing page. Click it to be redirected to the Stripe payment portal. From this portal, you can update the payment method for each active subscription on your account. Note: each subscription can have its own payment method, so you may need to update multiple subscriptions.
   <img alt="Stripe portal: managing payment methods" />
   *Stripe portal: managing payment methods*
3. **Add a bank account**
   Click **Add payment method**. Select **US Bank account** for US-based accounts, or **Pre-Authorized Debit** for non-US-based accounts.
   <img alt="Adding a bank account as a payment method" />
   *Adding a bank account as a payment method*
4. **Verify your bank account**

Enter your bank details to verify your account. Two verification paths are available depending on your bank institution.

**Instant Verification:** Log in to your bank through Stripe's secure portal. Your account is ready for ACH payments immediately after login.

**Manual Verification (micro-deposits):** If instant verification is not available for your institution, fill out the [Bank Draft (ACH) Authorization Form](https://eform.pandadoc.com/) so the Alvys billing team can securely enter your bank information in Stripe. The billing team will reach out to continue the verification process. You will then receive two small micro-deposits (typically under \$1.00 each) within 2-3 business days. Each deposit will include a unique 6-digit descriptor code in the transaction description, similar to "SMFM8E-Alvys ACCTVERIFY." Once you see the deposits, return to your Billing page, open Manage Payment Methods, click **Edit** on the account pending verification, and enter the deposit amounts to complete verification. Contact [billing@alvys.com](mailto:billing@alvys.com) with any questions during this process.

<img alt="Instant verification: logging in to your bank via Stripe" />

*Instant verification: logging in to your bank via Stripe*

1. **Set the bank account as your default payment method**
   Once verified, set your bank account as the **default** payment method. This is important because each active subscription on your account can have its own payment method assigned. Only subscriptions with a bank account set as default are exempt from the 2.9% credit card processing surcharge. Subscriptions that retain a card on file will continue to incur the surcharge.
   <Warning>
     ⚠️ **Notice:** By clicking accept, you authorize Alvys to debit the bank account specified for any amount owed for recurring charges arising from your subscription as outlined in your Alvys contractual agreement, pursuant to the Alvys Master Services Agreement, the Terms of Use, and our Privacy Policy, until this authorization is revoked. You may amend or cancel this authorization at any time by removing your bank account on the Billing page or by providing 30 days notice to Alvys.
   </Warning>
2. **Remove your previous payment method (optional)**

After your bank account is added and confirmed as the default, you can remove your previous credit or debit card from the Stripe portal.

## Result

Your bank account is set as the default payment method for your Alvys subscription. Future charges are debited via ACH at no additional processing fee. ACH payments take 3-5 business days to settle an invoice as paid. Alvys will not reattempt any collection for a payment already pending settlement.

## Variations

**Enterprise plan customers:** If you are on the Enterprise plan and have been approved to pay by invoice with extended terms, you can select your preferred payment method each time you pay via the **Pay Online** link provided with your PDF invoice.

**Non-US accounts:** Select **Pre-Authorized Debit** in the add-bank-account step instead of US Bank account.

## Troubleshooting

### Bank is not available for instant Stripe verification

Fill out the [Bank Draft (ACH) Authorization Form](https://eform.pandadoc.com/). The Alvys billing team will enter your bank information and initiate micro-deposit verification. Contact [billing@alvys.com](mailto:billing@alvys.com) for assistance with the process.

### ACH debit is being blocked by your bank

Your bank may be filtering or blocking Stripe ACH debits. Contact your bank and ask them to whitelist Stripe's ACH company IDs: **1800948598** and **4270465600** (Stripe Payments Company). You can also add Stripe to your Positive Pay authorized list. See [Allowing Stripe ACH debits and deposits](https://support.stripe.com/questions/ach-direct-debit-company-ids-for-stripe) for details.

### Payment collection fails

Stripe automatically reattempts failed drafts up to 2 additional times. If payment still fails after all reattempts, navigate to your open invoice and click **Pay online** to manually initiate a draft. Continued failures on your open balance may restrict your ability to pay via ACH to avoid credit card surcharges.

## FAQs

**Q: When should I expect my account to be drafted?**

**A:** Your account will be drafted on the invoice due date, the same as current credit card charge behavior. Alvys recommends switching to ACH 2-3 days before your next invoice due date to avoid card fees or late payments during the transition.

**Q: What if my payment fails?**

**A:** If payment collection fails (due to insufficient funds or other bank rejection reasons), Stripe will automatically reattempt to draft your account 2 times. If payment still fails, navigate to your open invoice and select **Pay online** to manually initiate a draft. Continued draft failures on your open balance will result in restriction on your ability to pay via ACH to avoid credit card surcharges.

**Q: When will my payments be applied?**

**A:** Payments are automatically linked to your Stripe account and applied to open invoices. Payments can take 3-5 business days to settle an invoice as paid. Alvys will not reattempt any payment collection for a pending payment.

**Q: Can I opt out of draft ACH? Can I initiate ACH payments from my own bank instead?**

**A:** ACH push payments (initiated from your own bank) are not supported at this time. Work with your Alvys account manager if you have concerns about this.

**Q: Can I initiate payments on my own?**

**A:** If you are on the Enterprise plan and have been approved to pay by invoice with extended terms, you can select your preferred payment method each time you pay via the Pay Online link provided with your PDF invoice.

**Q: What if my bank is not available for Instant Verification via Stripe?**

**A:** Fill out the [Bank Draft (ACH) Authorization Form](https://eform.pandadoc.com/) so the Alvys billing team can securely enter your bank information in Stripe. The billing team will reach out to continue the verification process via micro-deposit confirmation.

**Q: How long before my account is activated for ACH payments?**

**A:** If you use Stripe's Instant Verification by logging in to your bank, your account is ready immediately. If you submit a Bank Draft (ACH) Authorization Form: you will receive two small micro-deposits (typically under \$1.00 each) within 2-3 business days; each deposit includes a unique 6-digit descriptor code similar to "SMFM8E-Alvys ACCTVERIFY"; once you see the deposits, return to your Billing page, open Manage Payment Methods, click Edit on the account pending verification, and enter the deposit amounts; your account will be immediately ready once the amounts are verified. Contact [billing@alvys.com](mailto:billing@alvys.com) with any questions.

**Q: How do I prevent potential failed debits due to unauthorized transaction failures?**

**A:** Contact your bank and ask them to whitelist Stripe's ACH company IDs: **1800948598** and **4270465600** (Stripe Payments Company). You can also add Stripe to your Positive Pay authorized list. See [Allowing Stripe ACH debits and deposits](https://support.stripe.com/questions/ach-direct-debit-company-ids-for-stripe) for details.

## Go Deeper

[How to Manage Your Alvys Subscription](/en/help/administration/how-to-manage-your-alvys-subscription)


# Management & Privacy Permissions
Source: https://docs.alvys.com/en/help/administration/management-privacy-permissions

Assign the 16 Management and 4 Privacy permissions that gate user setup, carrier and asset control, webhooks, Tax ID, SSN, PII, and ACH banking access.

<Note>
  Management and Privacy permissions control who can manage users, carriers, and assets, and who can access sensitive personal data such as Tax Identification Numbers, Social Security Numbers, and ACH banking details. This article covers all 16 Management permissions and all 4 Privacy permissions.
</Note>

<Info>
  📌 **Scope:** This article covers user management, carrier management, asset visibility, safety records, and sensitive data (PII/ACH) permissions. For load operations and financial rate permissions see [Dispatch Permissions](/en/help/administration/dispatch-permissions), [Billing Permissions](/en/help/administration/billing-permissions), and [Understanding Load Statuses and How to Revert Them](/en/help/loads-trips/understanding-load-statuses-and-how-to-revert-them).
</Info>

## Overview

Management and Privacy permissions are two distinct permission groups within Alvys. They share a common theme: governing access to company resources and sensitive personal data.

Management permissions determine who can create and delete users, manage carriers and assets, view safety records such as accidents and roadside inspections, and configure webhooks. Privacy permissions control who can see or edit Tax IDs, Social Security Numbers, personally identifiable information (PII) in Alvys Insights, and ACH banking details.

These permissions are configured at the individual user level. They are not tied to a role by default for all users; each must be explicitly granted or revoked by a user who holds the **"Set Permission"** permission.

## Where to Find It

Management and Privacy permissions are found in the User Management interface, inside each user's profile.

To reach the permissions section:

* Select your username in the bottom left corner of the screen, then select **Settings**.

<Note>
  <img alt="Settings highlighted within Account Management." />

  *Settings highlighted within Account Management.*
</Note>

* Go to **Organization** and select the **Users** tab.

<Note>
  <img alt="Users tab highlighted within Organization, showing the Edit option and Add User button." />

  *Users tab highlighted within Organization, showing the Edit option and Add User button.*
</Note>

* Open an existing user's profile by clicking **Edit**, or create a new user by clicking **Add User**.
* Scroll to the **Permissions** section.
* Locate the **Management** category to find the 16 checkboxes described in this article.

<Note>
  <img alt="Permissions section showing all 16 Management permission checkboxes." />

  *Permissions section showing all 16 Management permission checkboxes.*
</Note>

* Locate the **Privacy** category to find the 4 checkboxes described in this article.

<Note>
  <img alt="Permissions section showing all 4 Privacy permission checkboxes." />

  *Permissions section showing all 4 Privacy permission checkboxes.*
</Note>

<Warning>
  ⚠️ To modify any user's permissions, the logged-in user must have the **"Set Permission"** permission, which is located within the Management category. Without **"Set Permission"**, a user can view a user's profile but cannot change any permissions.
</Warning>

## Privacy Permissions

Partner Admin receives all four Privacy permissions by default. The table below shows defaults for the other roles. Roles not listed (Sales Agent, Data Entry, Driver) receive none of these by default.

| Permission          | Admin | Op. Manager | Dispatcher | Biller | Office Admin | Safety |
| ------------------- | ----- | ----------- | ---------- | ------ | ------------ | ------ |
| View Tax ID/SSN     | ✓     | ✓           | –          | –      | –            | –      |
| Edit Tax ID/SSN     | ✓     | ✓           | –          | –      | –            | –      |
| View PII (Insights) | ✓     | –           | –          | –      | –            | –      |
| View ACH Details    | ✓     | –           | –          | –      | –            | –      |

### "View Tax ID/SSN"

This permission controls whether a user can see Tax Identification Numbers (TINs) and Social Security Numbers (SSNs) stored on carrier and driver records. Without it, these fields are hidden entirely.

In Alvys, Tax IDs and SSNs appear in the following locations when the user has this permission:

**Carrier list and carrier profile:** The carrier list includes Tax Identification Number and Tax ID Type columns only for users with this permission. These columns are not visible to users without it.

<Note>
  <img alt="Carrier list showing Tax ID and Tax ID Type columns visible for users with View Tax ID/SSN" />

  *Carrier list showing Tax ID and Tax ID Type columns visible for users with View Tax ID/SSN*
</Note>

On the carrier profile, the Tax Identification Number appears in the Form 1099 section. Without this permission, both the type and number are hidden.

<Note>
  <img alt="Carrier profile Form 1099 section showing Tax Identification Number" />

  *Carrier profile Form 1099 section showing Tax Identification Number*
</Note>

**Driver list and driver profile:** The driver list includes a Tax Identification Number column only for users with this permission.

<Note>
  <img alt="Driver list showing the Tax Identification Number column" />

  *Driver list showing the Tax Identification Number column*
</Note>

On the driver profile, the tax category, identification type, and Tax Identification Number are all hidden without this permission.

<Note>
  <img alt="Driver profile tax information section showing tax category, type, and number." />

  *Driver profile tax information section showing tax category, type, and number.*
</Note>

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles. It is not granted by default to Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, or Driver roles.

<Info>
  ✅ **Best Practice:** Grant **"View Tax ID/SSN"** only to accounting, compliance, and finance staff who handle tax reporting. Do not grant it to operational roles unless there is a specific, documented need.
</Info>

### "Edit Tax ID/SSN"

This permission controls whether a user can modify Tax Identification Numbers and Social Security Numbers on carrier and driver records. Without it, the fields are read-only (if the user has **"View Tax ID/SSN"**) or hidden entirely (if they lack both permissions).

<Note>
  <img alt="Driver profile showing “Tax Identification Number” form" />

  *Driver profile showing “**Tax Identification Number**” form*
</Note>

<Note>
  <img alt="Carrier profile showing Edit Tax ID/SSN field in editable state" />

  *Carrier profile showing Edit Tax ID/SSN field in editable state*
</Note>

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles. It is not granted by default to Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, or Driver roles.

<Info>
  ✅ **Best Practice:** Grant **"Edit Tax ID/SSN"** to the smallest number of users possible, typically only senior accounting or compliance staff. Always pair it with **"View Tax ID/SSN"** so the user can see the data they are editing.
</Info>

### "View PII"

This permission controls whether personally identifiable information is shown or masked in Alvys Insights responses. **"View PII"** specifically governs the visibility of sensitive data fields within the Insights AI feature. Without it, sensitive values in Insights results are replaced by masked placeholders.

Alvys Insights uses a two-tier access model to protect privacy:

**Tier 1 (Standard Data Access):** Requires at least one matching domain permission such as Billing, View Drivers, or Dispatch. This controls access to operational data fields like financial amounts, vehicle information, and trip counts.

**Tier 2 (Personally Identifiable Information):** Requires both a relevant domain permission and the **"View PII"** permission. This controls visibility of specific fields such as names, email addresses, phone numbers, dates of birth, driver license numbers, geolocation, and insurance details. Without **"View PII"**, Tier 2 fields remain masked regardless of Tier 1 domain permissions.

<Warning>
  ⚠️ **"View PII"** applies specifically to the Insights feature. For this masking logic to apply, a user must also have access to Insights via the **"View Insights"** permission, and Insights must be enabled for the company.
</Warning>

By default, this permission is granted to Admin and Partner Admin roles. All other roles must have it explicitly granted by an administrator.

### "View ACH Details"

This permission controls whether a user can view ACH banking details stored on carrier and driver records. ACH details include bank account and routing information used for direct payment processing. Without this permission, these fields are hidden. If you see masked dots instead of full routing and account numbers, it means your user account does not have the "View ACH Details" permission enabled. This applies to both drivers and carriers.

By default, this permission is not granted to any role except Admin and Partner Admin.

<Info>
  ✅ **Best Practice:** Grant this permission only to accounting and finance staff who process ACH payments. Do not grant it broadly.
</Info>

<Warning>
  ⚠️ **Troubleshooting:** If ACH details seem to disappear after saving a driver profile, it is likely due to the "View ACH Details" permission not being enabled. Ensure that this permission is active for your user account.
</Warning>

## Management Permissions

Partner Admin receives all Management permissions by default. The Driver role receives none.

| Permission                | Admin | Op. Manager | Dispatcher | Biller | Sales Agent | Data Entry | Office Admin | Safety |
| ------------------------- | ----- | ----------- | ---------- | ------ | ----------- | ---------- | ------------ | ------ |
| Add User                  | ✓     | ✓           | –          | –      | –           | –          | ✓            | –      |
| Set Permission            | ✓     | ✓           | –          | –      | –           | –          | ✓            | –      |
| Activate Carrier          | ✓     | ✓           | –          | –      | –           | –          | –            | –      |
| Edit Carrier              | ✓     | ✓           | –          | –      | –           | –          | –            | –      |
| Delete Carrier            | ✓     | –           | –          | –      | –           | –          | –            | –      |
| Delete User               | ✓     | ✓           | –          | –      | –           | –          | –            | –      |
| Edit Asset                | ✓     | ✓           | –          | –      | –           | –          | –            | –      |
| Delete Asset              | –     | –           | –          | –      | –           | –          | –            | –      |
| View Drivers              | ✓     | ✓           | ✓          | ✓      | ✓           | ✓          | ✓            | ✓      |
| View Trucks               | ✓     | ✓           | ✓          | ✓      | ✓           | ✓          | ✓            | ✓      |
| View Trailers             | ✓     | ✓           | ✓          | ✓      | ✓           | ✓          | ✓            | ✓      |
| View Maintenance          | ✓     | ✓           | ✓          | –      | –           | –          | ✓            | ✓      |
| View Accidents            | ✓     | ✓           | ✓          | –      | –           | –          | ✓            | ✓      |
| View Claims               | ✓     | ✓           | ✓          | –      | –           | –          | ✓            | ✓      |
| View Roadside Inspections | ✓     | ✓           | ✓          | –      | –           | –          | ✓            | ✓      |
| Edit Webhooks             | ✓     | ✓           | –          | –      | –           | –          | –            | –      |

### "Add User"

This permission controls whether a user can create new user accounts in Alvys. Without it, the Add User page is inaccessible.

<Note>
  <img alt="Add User form showing name, email, office, status, role, and reporting access" />

  *Add User form showing name, email, office, status, role, and reporting access*
</Note>

<Warning>
  ⚠️ **"Add User"** and **"Set Permission"** work together. A user with **"Add User"** but without **"Set Permission"** can create a new account but cannot assign permissions to it, resulting in an incomplete setup. Assign both permissions together to anyone responsible for onboarding.
</Warning>

By default, this permission is granted to Partner Admin, Admin, Operation Manager, and Office Admin roles. It is not granted by default to Dispatcher, Biller, Sales Agent, Data Entry, Safety, or Driver roles.

<Info>
  ✅ **Best Practice:** Grant **Add User** only to administrative roles responsible for employee onboarding. Do not assign it broadly just for convenience, it is better to have one or two trusted people who handle account creation consistently. Always pair with **Set Permission** so the same person can both create the account and configure its permissions.
</Info>

### "Set Permission"

This permission controls whether a user can modify the permissions assigned to other users. Without it, the permissions section on a user's profile is read-only.

<Note>
  <img alt="User profile permissions section showing toggleable permission checkboxes." />

  *User profile permissions section showing toggleable permission checkboxes.*
</Note>

This is one of the highest-privilege capabilities in Alvys because it determines who can change what other users are authorized to do. Restrict it to highly trusted administrators.

By default, this permission is granted to Partner Admin, Admin, Operation Manager, and Office Admin roles. It is not granted by default to Dispatcher, Biller, Sales Agent, Data Entry, Safety, or Driver roles.

<Info>
  ✅ **Best Practice:** The Set Permission authorization should be restricted exclusively to administrators who maintain formal responsibility for user access management. Furthermore, permission modifications should be audited on a regular basis to identify any unauthorized adjustments.
</Info>

### "Activate Carrier"

The Activate Carrier permission ensures that only authorized staff can change a carrier’s status e.g. from inactive or pending to active. Carrier activation typically follows carrier onboarding and compliance review, including insurance verification, authority checks, and documentation review. When a company establishes a new carrier relationship, the carrier must be activated before loads can be assigned. Conversely, when a carrier relationship ends or a carrier has compliance issues, deactivation prevents further assignments.

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles.

<Info>
  ✅ **Best Practice:** Assign Activate Carrier only to compliance staff or operations managers who are part of the carrier onboarding workflow. Pair this with a documented checklist: insurance certificate on file, operating authority verified, contact information complete before any activation is approved.
</Info>

### "Edit Carrier"

Carrier records need to stay current. Insurance policies expire and are renewed, contacts change, and addresses change. Without the ability to edit carrier records, outdated information remains in the system and can cause dispatch errors, compliance gaps, or failed communications. The Edit Carrier permission controls whether a user can modify carrier profile information, such as contact details, addresses, payment terms, insurance information, MC and DOT numbers, and other carrier attributes. Without it, carrier data is read-only. Accurate carrier data is essential for load assignment, settlement, and regulatory compliance.

<Warning>
  ⚠️ This permission does not grant the ability to activate or delete a carrier, those require separate permissions.
</Warning>

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles.

### "Delete Carrier"

Carrier records may need to be deleted when carriers go out of business, when duplicate records are created by mistake, or when a carrier relationship is permanently terminated. Without the ability to delete records, your carrier list can accumulate stale or duplicate entries that create confusion during dispatch. The Delete Carrier permission controls whether a user can permanently delete carrier records from the system. Carrier records contain historical load, payment, and compliance data; deleting a carrier removes this audit trail. This permission does not require **Edit Carrier** or **Activate Carrier**.

By default, this permission is granted to Partner Admin and Admin roles.

<Info>
  ✅ **Best Practice:** Never grant Delete Carrier to non-admin roles. Even for Partner Admins, consider whether deactivation would serve the same purpose. Require verbal confirmation before performing carrier deletions.
</Info>

### "Delete User"

The Delete User permission controls whether a user can permanently delete other user accounts from the system. Like Delete Carrier, this is a destructive action that removes user records permanently. When an employee leaves the company, their Alvys account should be deactivated or removed, and Delete User is the permission that allows this action. However, because user deletion is irreversible and can affect audit trails, it must be handled carefully. In most cases, disabling a user account is preferable to deletion. This permission is restricted to the highest-level administrators.

<Note>
  <img alt="Notion Image" />
</Note>

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles.

<Info>
  ✅ **Best Practice:** Disable user accounts instead of deleting them. This preserves the audit trail and prevents data loss. To disable a user account, go to **Settings → Organization → Users**, search for the user, click the status dropdown for that user, and select the Disabled option. Reserve deletion for duplicate user accounts or test user accounts with no meaningful history.
</Info>

### "Edit Asset"

The Edit Asset permission controls whether a user can modify asset records, including drivers, trucks, and trailers. This is a broad permission that governs the ability to update asset profiles, change asset information, and manage asset-related data such as driver rate policies and bank information. Asset records form the operational foundation. Driver qualifications, truck specifications, trailer types, and equipment availability all depend on accurate asset data. Additionally, driver rate policies and bank information are sensitive financial data that affect driver settlements. This permission ensures that only authorized staff can modify asset records, preventing unauthorized changes that could impact operations, settlements, or compliance.

When this permission is active, the user can: Create and import asset records, such as drivers, trucks, and trailers.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

Open any asset record (driver, truck, or trailer) and edit fields such as subsidiary, email, make, model, year, VIN, license plate, and more.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

By default, this permission is granted to Partner Admin, Admin, and Operation Manager roles.

<Info>
  ✅ **Best Practice:** Grant the Edit Asset permission to Billers and Data Entry staff who manage asset onboarding and maintenance. Consider whether Dispatchers need Edit Asset access; in many companies, dispatchers should be able to view but not modify asset records.
</Info>

### "Delete Asset"

The Delete Asset permission controls whether a user can delete asset records (drivers, trucks, trailers) from the system. This is a destructive action that removes the asset and its associated data. In most cases, deactivating an asset is the appropriate action.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

By default, this authorization is extended exclusively to the Partner Admin role. Conversely, this permission is not assigned by default to the Admin, Operation Manager, Dispatcher, Biller, Sales Agent, Data Entry, Office Admin, Safety, or Driver roles.

<Info>
  ✅ **Best Practice:** The **Delete Asset** permission should never be granted to non administrative roles. As a matter of best practice, the deactivation of assets should be utilized rather than deletion for assets that are no longer in service.
</Info>

### "View Drivers"

The View Drivers permission controls whether a user can see the [driver list](https://app.alvys.com/assets/drivers) and individual driver profiles. Without it, the user cannot select the Driver option from the Assets menu.

<Note>
  <img alt="Notion Image" />
</Note>

Driver records are referenced throughout the system in load assignments, dispatch planning, settlement records, and safety reports. Most operational roles need at least read access to driver data to perform their functions effectively.

<Note>
  <img alt="Notion Image" />
</Note>

By default, this permission is granted to all roles except the Driver role.

### "View Trucks"

The View Trucks permission allows a user to see truck records. Without it, the [truck list](https://app.alvys.com/#/assets/trucks) is hidden and a user cannot view any truck profiles. Its default role assignments, behavior, and risk profile are identical to View Drivers.

<Note>
  <img alt="Notion Image" />
</Note>

Truck records contain equipment specifications, maintenance status, and availability data. Dispatchers need truck visibility for load assignment; billers need it for settlement context; safety staff need it for compliance monitoring.

<Note>
  <img alt="Notion Image" />
</Note>

<Info>
  ✅ **Best Practice:** Assign View Trucks to all dispatchers, fleet managers, and operations managers. Pair with the View Drivers permission for anyone who needs to use Assignment Preferences. The Driver role should be excluded, as drivers do not use the TMS web interface and primarily interact with the system through the mobile app.
</Info>

### "View Trailers"

Allows a user to see the [list of trailers](https://app.alvys.com/#/assets/trailers) in the Assets section of Alvys and open individual trailer records. Its default role assignments, behavior, and risk profile are identical to View Drivers and View Trucks. Without this permission, the trailer menu item and list are hidden. It is broadly assigned to almost all roles, as Dispatchers need trailer visibility for load planning, and safety staff need it for inspection and maintenance monitoring.

<Note>
  <img alt="Notion Image" />
</Note>

<Info>
  ✅ **Best Practice:** Grant **View Trailers** alongside **View Trucks** and **View Drivers** permissions as a set.
</Info>

### "View Maintenance Records & Totals"

This permission determines whether authenticated users can access the maintenance module, view [maintenance records](https://app.alvys.com/#/maintenance), add maintenance records, review closed maintenance records etc., and also see [maintenance totals](https://app.alvys.com/#/maintenance/totals) for assets (Trucks and trailers). Without it, maintenance data is hidden.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

<Info>
  💡 **View Maintenance Amounts** is an additional permission that reveals the dollar amounts within maintenance records. Both permissions must be active for a user to see the full financial details of maintenance work. With **View Maintenance Amounts**, dollar amounts on maintenance records, including parts costs, labor costs, and totals, become visible. Without this permission, those fields are hidden.

  <img alt="Notion Image" />
</Info>

By default, this specific authorization is extended to the Partner Admin, Admin, Operation Manager, Dispatcher, Office Admin, and Safety roles. Conversely, this permission is not assigned by default to the Biller, Sales Agent, Data Entry, or Driver roles.

This data is essential for fleet managers and safety staff to ensure vehicles meet DOT requirements and are safe to operate. The narrower default assignment (compared to Asset View permissions) reflects the specialized nature of maintenance data—dispatchers need it for equipment decisions, but billers and sales agents typically do not.

<Info>
  ✅ **Best Practice:** Grant this permission to all fleet managers, maintenance coordinators, and anyone responsible for scheduling repairs. Grant View Maintenance Amounts only to controllers, owners, and operations managers who need to track maintenance costs. Also include these permissions as part of the full Safety View permissions set, since users who need maintenance data typically also require access to accident, claim, and inspection records.
</Info>

### "View Accidents"

The **View Accidents** permission enables a user to access the [Accidents page](https://app.alvys.com/#/accidents) within the Safety menu and observe detailed accident reports. The View Accidents permission controls whether a user can see, add, and edit accident records associated with assets, including accident reports, dates, descriptions, and related details. When this permission is active, the Safety Accidents menu option becomes visible and accessible. Conversely, in the absence of this permission, any attempt to navigate to the Accidents page is blocked.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

This permission is part of the Safety View permissions set. Accident records contain sensitive safety and legal information and may be involved in insurance claims, legal proceedings, and regulatory investigations. Access should be limited to safety staff, dispatchers who need to consider safety history when making assignments, and management.

By default, this specific authorization is extended to the **Partner Admin**, **Admin**, **Operation Manager**, **Dispatcher**, **Office Admin**, and **Safety** roles.

<Info>
  ✅ **Best Practice:** Grant as part of the full Safety View permissions set.
</Info>

### "View Claims"

The View Claims permission controls whether a user can access the [Claims report page](https://app.alvys.com/#/claims) within the Safety menu to view, modify, and add insurance and cargo claim records associated with specific assets. This includes claim amounts, statuses, descriptions, and related details. Without it, claims data is hidden. Furthermore, insurance claims incorporate sensitive financial and legal information derived from incidents involving organizational assets. Consequently, access should be restricted to safety personnel, management, and operational roles that require comprehensive visibility into claim histories to facilitate informed risk management and assignment decisions.

<Note>
  <img alt="Notion Image" />
</Note>

By default, this permission is granted to the Partner Admin, Admin, Operation Manager, Dispatcher, Office Admin, and Safety roles.

<Info>
  ✅ **Best Practice:** Assign the View Claims permission to owners, controllers, safety managers, and compliance staff. Do not assign it broadly, as claims data can have legal implications and should be accessed only by staff actively involved in claims management.
</Info>

### "View Roadside Inspections"

The View Roadside Inspections permission allows a user to access the [Roadside Inspections page](https://app.alvys.com/#/roadside-inspections) within the Safety menu to view, add, and edit roadside inspection records for assets. This includes inspection results, violations, dates, and locations. Roadside inspection records are critical compliance data, directly impacting the company’s DOT safety rating (CSA scores) and potentially influencing insurance premiums and regulatory oversight. Safety staff use this information to identify problematic vehicles or drivers, while dispatchers may consider inspection history when making assignment decisions.

By default, this permission is granted to the Partner Admin, Admin, Operation Manager, Dispatcher, Office Admin, and Safety roles.

<Info>
  ✅ **Best Practice:** Assign the **View Roadside Inspections** permission to safety managers, compliance officers, and operations managers who actively monitor CSA scores. This is a foundational safety permission for anyone responsible for DOT compliance. Include this permission as part of the full Safety View permissions set.
</Info>

### "Edit Webhooks"

Webhooks are automated connections that send data from Alvys to external software systems, such as load status changes, new bookings, or settlement events. The Edit Webhooks permission controls whether a user can create, update, delete, and enable or disable webhook integrations within the company’s subsidiary settings. Without this permission, the webhooks section of company settings is inaccessible. This is a technical permission typically needed only by IT administrators or integration engineers. Misconfigured webhooks can send sensitive data to unauthorized endpoints, cause integration failures, or overwhelm external systems with excessive notifications.

**Granted by default to:** Partner Admin, Admin, Operation Manager.

<Info>
  ✅ **Best Practice:** Assign Edit Webhooks only to technical administrators or IT staff who understand what each webhook does and where it sends data. Before editing or deleting any webhook, confirm with the person or team who built the integration what the downstream impact will be. Do not grant this permission to operational roles.
</Info>

## FAQs

**Q: Should I grant View Tax ID/SSN and Edit Tax ID/SSN together?**

**A:** Not necessarily, as they are independent permissions. You can grant View Tax ID/SSN to staff who only need to view the data without the power to change it; however, if you grant Edit Tax ID/SSN, you should always pair it with View Tax ID/SSN so the user can actually see the data they are modifying.

**Q: Who has access to sensitive personal information (PII) by default?**

**A:** To maintain strict security, the **View PII** permission is granted by default only to **Admin** and **Partner Admin** roles, while all other users must have it explicitly assigned by an administrator.

**Q: If I have the View PII permission, can I see all personal data in the system?**

**A:** No, you must hold **both** the **View PII** permission **and** the relevant domain permission such as **Billing, Dispatch, View Trucks, or View Drivers** to reveal sensitive details in your results.

**Q: I was just granted the View PII permission, but I still see the data being masked. How do I fix this?**

**A:** Permission updates do not apply to active sessions, so you must **log out and log back in** to refresh your access and view unmasked data.

**Q: What happens if my View PII permission is revoked while I am currently using Insights?**

**A:** Your current session will retain its access level until you log out; a fresh login is required to apply the updated, restricted security settings.

**Q: What specific fields are protected by the View PII permission?**

**A:** This permission masks highly sensitive details including **names, contact information, dates of birth, license numbers, insurance details, and geolocation.**

**Q: What is the difference between the Edit Carrier and Activate Carrier permissions?**

**A:** **Edit Carrier** allows a user to modify profile data like contact information and payment terms. **Activate Carrier** specifically controls the ability to change a carrier's status, such as moving them from pending to active.

**Q: Why are Dispatchers denied the Edit Asset permission by default?**

**A:** While dispatchers must see assets to assign loads, editing asset records involves sensitive financial data like driver rate policies and bank information. To maintain security, these administrative tasks are reserved for billers, office admins, and data entry staff.

**Q: Can I grant individual Safety View permissions instead of the entire set?**

**A:** Yes, each safety permission operates independently. However, for a consistent user experience and to ensure the Safety Report page functions correctly, it is recommended to grant all safety-related permissions as a complete set.

**Q: Can a user create an account if they have the Add User permission but lack Set Permission?**

**A:** Yes, the user can initiate the creation of a new account. However, because they lack **Set Permission**, the permissions section will be read-only, and the new account will default to standard role settings until an administrator with set permissions adjusts them.

**Q: Why is the Set Permission authorization considered a high-privilege capability?**

**A:** This permission allows a user to modify what every other person in the company is authorized to do. Because it governs the entire security framework of the system, it should be restricted to a very small number of trusted administrators.

**Q: Is the Delete Carrier permission required to deactivate a carrier?**

**A:** No. **Delete Carrier** and **Activate Carrier** (deactivation) are separate. It is almost always preferable to deactivate a carrier to preserve historical load and payment data rather than deleting the record entirely.

**Q: Who should be granted the Edit Webhooks permission?**

**A:** This should be restricted to IT administrators or integration engineers. Since webhooks send data to external endpoints, misconfiguration can lead to data breaches.

**Q: Does the Edit Webhooks permission require any other specific authorizations?**

**A:** **Edit Webhooks** operates independently. However, because these settings are located within the Company Settings area, the user typically needs an admin-level role to navigate to that section of the TMS.

**Q: Who can assign Management and Privacy permissions?**

**A:** Only users who have the **"Set Permission"** permission can assign or remove permissions for other users. Typically this is limited to Admin, Partner Admin, Operation Manager, and Office Admin roles.

**Q: Will deleting a carrier remove it from existing loads?**

**A:** Yes. If the carrier has been assigned to any loads in Alvys, deleting it will also remove the carrier from those loads. Use the **"Delete Carrier"** permission with extreme caution.

**Q: Does "View PII" give access to PII across the whole platform?**

**A:** No. **"View PII"** specifically controls whether PII fields are unmasked in Alvys Insights. It has no effect on PII visibility in other parts of the application such as driver profiles or carrier records.

**Q: Can I grant "Edit Tax ID/SSN" without also granting "View Tax ID/SSN"?**

**A:** The permissions can be granted independently, but granting edit access without view access means the user cannot see the Tax ID field they are editing. Always grant **"View Tax ID/SSN"** together with **"Edit Tax ID/SSN"**.

**Q: What happens if a user has "Set Permission" but not "Add User"?**

**A:** A user with **"Set Permission"** but without **"Add User"** can modify permissions on existing user profiles but cannot access the user creation workflow. They cannot create new user accounts.

**Q: ACH details disappear after I save a driver profile. Why?**

**A:** This issue occurs when the "View ACH Details" permission is not enabled for your user account. Contact an administrator to ensure this permission is granted.

## Next Steps

<Info>
  ⏭️ Proceed to [General Permissions](/en/help/administration/general-permissions) to learn how to control broad user access settings, including load board permissions for DAT and TruckStop, default permission behavior, and where to configure general permissions within a user’s profile.
</Info>

## Go Deeper

* [Adding and Managing Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys)
* [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)
* [App Permissions](/en/help/administration/app-permissions)
* [Back to User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Marketplace Permissions
Source: https://docs.alvys.com/en/help/administration/marketplace-permissions

Grant Marketplace permissions that let users search, book, bid on, and post loads through the Alvys, DAT, Uber Freight, or Truckstop integrated load boards.

👥 **Primary Audience:** **Admins**, **Partner Admins**, **Office Admins**, **Operation Managers**, **Dispatchers**

📁[Return to User Roles & Permissions Collection ](/en/help/administration/user-roles-permissions-collection)

### Overview

The Marketplace Permissions category in Alvys controls access to the system's load marketplace functionality (also called a load board). The Carrier Marketplace is an integrated load board built directly into the TMS. It lets carriers and brokers search for available freight, book or bid on loads, and post their own loads for other carriers to pick up, all without leaving Alvys.

Because the Marketplace connects your organization to external brokers and carriers, access (rights, entitlements) is managed through dedicated permissions that define exactly what each user can see and do. This article explains each Marketplace permission, what it enables, why it is important, and which roles typically require it.

<Warning>
  ⚠️ To use the Marketplace, the subsidiary must have an active integration with one of the following sources: **Alvys Marketplace**, **DAT Marketplace**, **Uber Freight**, or **Truckstop Marketplace**.
</Warning>

<Note>
  <img alt="Marketplace search page." />

  *Marketplace search page.*
</Note>

### Where to Find It

Marketplace permissions are configured at the individual user level within the User Management interface.

<Warning>
  ⚠️ To modify these permissions, the logged-in user must have the **"Set Permission"** permission, located within the Management category. Without **"Set Permission"**, a user can view the user profile or form but cannot adjust any permissions. For more information, refer to the [Management & Privacy Permissions article](/en/help/administration/management-privacy-permissions).
</Warning>

To adjust Marketplace permissions:

1. Select your **Username** in the bottom left corner.
2. Navigate to **Company Profile** and select the **Users** tab.

   <img alt="Notion Image" />
3. Select an existing user to edit, or click **Create New User**.

   <img alt="Notion Image" />
4. Scroll to the **Permissions** section and locate the **Marketplace** category. You will see four individual checkboxes: **"View Marketplace Loads"**, **"Book Marketplace Loads"**, **"Bid on Marketplace Loads"**, and **"Post Loads to Marketplace"**.

<Note>
  <img alt="Marketplace permissions overview screenshot." />

  *Marketplace permissions overview screenshot.*
</Note>

### Key Concepts

The four Marketplace permissions are independent and can be granted in any combination. They control progressively more powerful actions on the Marketplace:

* **"View Marketplace Loads"** is the baseline permission required to access the Marketplace page at all. Having any of **"View Marketplace Loads"**, **"Book Marketplace Loads"**, or **"Bid on Marketplace Loads"** causes the Marketplace sidebar item to appear under Loads and Trips.
* **"Book Marketplace Loads"** allows accepting a load at the listed rate without negotiation.
* **"Bid on Marketplace Loads"** allows submitting a counter-offer on a load. Users with **"Bid on Marketplace Loads"** also have the ability to book marketplace loads. This is because the system's booking authorization accepts either the **"Book Marketplace Loads"** or **"Bid on Marketplace Loads"** permission — granting bidding access inherently includes booking capability.
* **"Post Loads to Marketplace"** allows making the company's own loads visible to external carriers on load boards, and removing them (unposting).

The ability to bid or book directly through Alvys depends on the integration capabilities of each load provider. Truckstop currently requires offline negotiation. Uber Freight and certain DAT loads support instant booking or bidding.

### How to Use It

For step-by-step workflows on searching, booking, bidding, and posting in the Marketplace, see:

* [Understanding the Marketplace](/en/help/integrations/alvys-carrier-marketplace)
* Alvys Internal Marketplace

### Settings & Permissions

#### "View Marketplace Loads"

**"View Marketplace Loads"** is a read-only permission. It grants users the ability to access the Marketplace, search for available loads, view load details (origin, destination, equipment type, rate), and evaluate whether loads match their capacity needs. A user with this permission cannot take any action on a load.

The Marketplace is accessed from the left navigation by selecting **Loads and Trips**, then the **Marketplace** menu item.

<Note>
  <img alt="Left navigation showing Loads and Trips > Marketplace." />

  *Left navigation showing Loads and Trips > Marketplace.*

  <img alt="Market place search page" />

  *Market place search page*
</Note>

<Info>
  💡 Having **"View Marketplace Loads"**, **"Book Marketplace Loads"**, or **"Bid on Marketplace Loads"** causes the Marketplace sidebar item to appear, allowing the user to access the marketplace page. Use **"View Marketplace Loads"** alone when the goal is read-only access.
</Info>

By default, this permission is granted to Partner Admin, Admin, Operation Manager, Dispatcher, and Office Admin roles. It is not assigned by default to the Biller, Sales Agent, Data Entry, Safety, or Driver roles.

<Info>
  💡 **Best Practice:** Grant **"View Marketplace Loads"** to all users who actively search for and evaluate available loads, such as Dispatchers, Load Planners, and Operations Managers. Any user with Book, Bid, or Post permissions should also have **"View Marketplace Loads"** as a baseline.
</Info>

#### "Book Marketplace Loads"

**"Book Marketplace Loads"** determines whether a user can accept a load from marketplace sources at the listed rate in a single action, bypassing negotiation. Users with this permission can click the **Book Now** button (or **Submit Booking** for DAT sources) to submit a booking request immediately. Booking a load commits the company to haul the freight at the specified price and terms.

The **Book Now** button appears in the marketplace table for each result, and also in the side panel action controls when a user selects a load to view its details.

<Note>
  <img alt="Book Now button in marketplace table and side panel." />

  *Book Now button in marketplace table and side panel.*
</Note>

By default, this permission is granted to Partner Admin, Admin, Operation Manager, Dispatcher, and Office Admin roles. It is not assigned by default to the Biller, Sales Agent, Data Entry, Safety, or Driver roles.

<Info>
  💡 **Best Practice:** Grant **"Book Marketplace Loads"** to users such as Dispatchers and Operations Managers who have the authority to commit the company to hauling freight. Note that users with **"Bid on Marketplace Loads"** also have booking capability.
</Info>

#### "Bid on Marketplace Loads"

**"Bid on Marketplace Loads"** allows a user to submit a bid or counter-offer on a marketplace load. Unlike booking, which accepts the listed rate, bidding lets the user propose an alternative rate, which the shipper or broker can accept, reject, or counter.

Users with **"Bid on Marketplace Loads"** also have the ability to book marketplace loads. The system's booking authorization accepts either the **"Book Marketplace Loads"** or **"Bid on Marketplace Loads"** permission, so bidding access inherently includes booking capability.

<Info>
  💡 The ability to bid or book directly through Alvys depends on the integration capabilities of each load provider. Truckstop currently requires offline negotiation. Uber Freight and certain DAT loads support instant booking or bidding.
</Info>

The **Submit Bid** button appears in the marketplace table within the row of each load result. The **Bid** button is also available in the side panel footer when a user selects a load to view its details.

<Note>
  <img alt="Submit Bid button in marketplace table row." />

  *Submit Bid button in marketplace table row.*

  <img alt="Bid button in side panel footer." />

  \*Bid button in side panel footer. \*
</Note>

This permission also controls whether users can access the **Bids** tab within the Marketplace to view their bid history, submit new bids with custom rates, and manage counter-offers.

<Note>
  <img alt="Bids tab in the Marketplace." />

  *Bids tab in the Marketplace.*
</Note>

By default, this permission is extended to the Partner Admin, Admin, Operation Manager, Dispatcher, and Office Admin roles. Conversely, this permission is not assigned by default to the Biller, Sales Agent, Data Entry, Safety, or Driver roles.

<Info>
  ✅ Grant the Bid on Marketplace Loads permission to Dispatchers, Sales Agents (when applicable), and Operations Managers who are responsible for negotiating rates and managing bids on marketplace loads. Because bidding involves rate negotiation, assign this permission only to staff familiar with your cost structure, fuel expenses, and lane-specific market conditions. Note that granting this permission also provides the ability to book loads, so users with bidding access can automatically book as well.
</Info>

### Post Loads to Marketplace

The Post Loads to Marketplace permission controls whether a user can make the company's loads available on external marketplace load boards for carriers to discover. Unlike the browse-and-book workflow, where users search for loads to haul, this permission allows a user to post the company's freight for others to bid on or accept.

This permission also includes the ability to unpost, or remove, loads from the marketplace. Without it, users cannot make loads visible to external carriers. Restricting access ensures that only authorized users can manage the company’s marketplace presence, preventing accidental exposure of internal loads or posting of incorrect rates.The “**Post load**” button can be found on the individual load details page at the footer of the Carrier Information card (next to the load details card).

<Note>
  <img alt="Post load button on load details page." />

  \*Post load button on load details page. \*
</Note>

By default, this authorization is extended to the **Partner Admin**, **Admin**, **Operation Manager**, **Dispatcher**, and **Office Admin** roles. Conversely, this permission is not assigned by default to the **Biller**, **Sales Agent**, **Data Entry**, **Safety**, or **Driver** roles.

<Info>
  ✅ **Best Practice:** Grant Post Loads to Marketplace only to users, such as Dispatchers, Load Planners, or Operations Managers, who are responsible for managing the company’s marketplace load postings. Establish clear internal guidelines for when loads should be posted externally versus handled internally, and define appropriate rate ranges to maintain consistency and control
</Info>

### Limits & Behavior

* The Marketplace sidebar item appears only when a user has **"View Marketplace Loads"**, **"Book Marketplace Loads"**, or **"Bid on Marketplace Loads"**. Without any of these three, the Marketplace page is not accessible.
* **"Bid on Marketplace Loads"** grants both bidding and booking capability. The system's booking endpoint accepts either **"Book Marketplace Loads"** or **"Bid on Marketplace Loads"**, so a user with bidding permission can also book loads at the listed rate.
* **"Post Loads to Marketplace"** covers both posting and unposting. There is no separate permission to remove loads once posted.
* The subsidiary must have an active integration with a supported source (Alvys Marketplace, DAT, Uber Freight, or Truckstop) before any Marketplace functionality is available, regardless of user permissions.
* Bidding and instant booking availability depends on the load provider. Truckstop requires offline negotiation. Uber Freight and certain DAT loads support instant booking and bidding within Alvys.
* Sales Agents are excluded from default Marketplace permissions. Even though Sales Agents may have dispatch permissions, Marketplace access is treated as a separate set of responsibilities and must be explicitly assigned.

### FAQs

**Q:** Do I need to grant all four Marketplace permissions at once, or can I grant them individually?

**A:** You can grant them individually for granular control. For example, you can allow a user to search and bid without giving them the authority to post company freight. Note that the **"Bid on Marketplace Loads"** permission effectively includes booking access.

**Q:** Which roles are granted Marketplace permissions by default?

**A:** By default, these permissions are granted to Partner Admin, Admin, Operation Manager, Dispatcher, and Office Admin roles. Biller, Sales Agent, Data Entry, Safety, and Driver roles do not receive Marketplace access by default.

**Q:** Why are Sales Agents excluded from default Marketplace permissions?

**A:** Marketplace access is treated as a separate set of responsibilities from dispatch functions. If a Sales Agent needs to interact with the Marketplace, an administrator must explicitly assign the required permissions.

**Q:** What does it mean to unpost a load, and which permission is required?

**A:** Unposting removes your company's freight from external boards so it is no longer visible to other carriers. This action is covered by the **"Post Loads to Marketplace"** permission, which controls both making a load public and removing it.

**Q:** Should Marketplace permissions be granted to Accounting or Billing staff?

**A:** Generally, no. Marketplace activity is an operational function for finding and committing to freight. Billing staff focused on invoicing and settlements rarely need the ability to book or post loads.

**Q:** What is required at the company level to use Marketplace features?

**A:** Beyond user permissions, the subsidiary must have an active integration with a supported source: Alvys Marketplace, DAT, Uber Freight, or Truckstop.

### Troubleshooting

#### The Marketplace item does not appear in the sidebar

The user is missing all three access permissions. Grant at least one of **"View Marketplace Loads"**, **"Book Marketplace Loads"**, or **"Bid on Marketplace Loads"** to surface the Marketplace page.

#### A user can view loads but the Book Now and Submit Bid buttons are missing

The user holds **"View Marketplace Loads"** only. Grant **"Book Marketplace Loads"** for booking or **"Bid on Marketplace Loads"** for bidding (which also enables booking).

#### The Post load button does not appear on a load

The user is missing **"Post Loads to Marketplace"**, which controls both posting and unposting.

#### No loads appear in the Marketplace at all

Confirm the subsidiary has an active integration with a supported source (Alvys Marketplace, DAT, Uber Freight, or Truckstop). Without an integration, no Marketplace functionality is available regardless of permissions.

### Go Deeper

* [Understanding the Marketplace](/en/help/integrations/alvys-carrier-marketplace)
* Alvys Internal Marketplace
* [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)
* [Customer Management Permissions](/en/help/administration/customer-management-permissions)

## Next Steps

<Info>
  ⏭️ Proceed to the [Customer Management Permissions](/en/help/administration/customer-management-permissions) article to learn how to assign and manage permissions for creating, editing, activating, and deleting customer records. This will help ensure that only authorized users handle sensitive customer information and maintain accurate records in Alvys.
</Info>

## Return to Collection

<Info>
  📁 [Back to User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)
</Info>


# Overview of User Permissions
Source: https://docs.alvys.com/en/help/administration/overview-of-user-permissions

Reference list of every Alvys user permission, grouped by category, with plain-language notes on what each access right, role toggle, or privilege controls.

<Note>
  Alvys uses a permission-based access system; this article lists every available permission and explains what each one controls.
</Note>

## Overview

Alvys uses a permission-based access system. Each user account has a set of individual permissions (also called access rights or privileges) that control what that user can see and do within the platform. Permissions are grouped into categories that reflect the area of the product they affect.

This article lists every available permission along with a plain-language description of what it does.

## Where to Find It

Permissions are managed from **Settings → Organization → Users**. Open a user's profile and navigate to their permissions tab to view or edit the permissions assigned to that account.

## How to Grant a Permission

You must hold the **"Set Permission"** permission to change another user's permissions. If you don't have it, ask your Admin or Partner Admin to make the change.

1. Navigate to **Settings → Organization → Users**.
2. Locate the user and click their name to open their profile.
3. Click the **Permissions** tab on their profile.
4. Enable the checkbox next to the permission you want to grant, or disable it to remove access.
5. Changes save automatically — no separate save button is required.

## Key Concepts

Permissions are distinct from roles. A role is a bundle of pre-configured permissions assigned to a user at account creation. Individual permissions can be added to or removed from a user account at any time by a user who holds the **"Set Permission"** permission.

Some permissions depend on other permissions to be meaningful. For example, editing a carrier requires the **"Edit Carrier"** permission, but activating or deactivating that carrier also requires **"Activate Carrier"** to be enabled separately.

Delete permissions carry significant risk. If a carrier, company, customer, or asset that has been assigned to any load is deleted, it will also be removed from those loads in Alvys. Enable delete permissions only when necessary, and apply them with caution.

## Permission Combinations by Task

Some tasks require more than one permission to work end-to-end. If a user has the correct access level but still cannot complete a task, check that all permissions in the relevant combination are enabled.

| Task                                                      | Required Permissions                                                                                     |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Full invoicing access                                     | Billing + Generate Invoice + Pay Driver + Export                                                         |
| Full carrier management                                   | Activate Carrier + Edit Carrier                                                                          |
| View financial columns in load reports (margin, profit %) | View Customer Rate + View Carrier Rate + View Trip Value                                                 |
| Delete a driver profile                                   | Delete Asset (controls the delete button on driver, truck, and trailer profiles)                         |
| Driver app full financial visibility                      | View Trip Value + View Payable Amount + View Customer Rate Confirmation + View Carrier Rate Confirmation |
| Assign a non-compliant carrier to a load                  | Assign Carrier + Override Carrier Restriction                                                            |

## Settings & Permissions

### Rates Permissions

* **"View Customer Rate"**: Ability to view the customer rate on a load
* **"Edit Customer Rate"**: Ability to view and edit the customer rate on a load
* **"View Carrier Rate"**: Ability to view the carrier rate on a load
* **"Edit Carrier Rate"**: Ability to view and edit the carrier rate on a load
* **"View Trip Value"**: Ability to view the trip value on a load
* **"Edit Trip Value"**: Ability to view and edit the trip value on a load
* **"Add Accessorials"**: Ability to add, edit, and remove accessorials on a load
* **"View Driver Rates"**: Ability to view driver rates
* **"Edit Driver Rates"**: Ability to view and edit driver rates

### E-Check Permissions

* **"Issue ECheck"**: Ability to issue e-checks
* **"Cancel ECheck"**: Ability to cancel e-checks
* **"Modify E-Check Fee"**: Ability to make changes to existing e-checks
* **"Move Comchek"**: Ability to move an e-check from one load to another
* **"Delete Notes"**: Ability to delete notes added to a load

### Billing Permissions

* **"Billing"**: Allows the user to view and access the billing loads board
* **"Generate Invoice"**: Ability to generate invoices
* **"Overriding Invoice"**: Ability to override an existing invoice
* **"Rollback Transaction"**: Ability to roll back billing transactions
* **"Void Transaction"**: Ability to void billing transactions
* **"Pay Driver"**: Ability to see the Pay Drivers option in the main menu, and provides access to the pay driver tab and menu option
* **"Pay Owner Operator"**: Ability to process payments for owner operators
* **"View Paystubs"**: Ability to see paystubs within driver profiles
* **"Edit Paystubs"**: Ability to edit paystubs within driver profiles
* **"View Pay Plans"**: Ability to view driver and owner operator pay plans
* **"Edit Pay Plans"**: Ability to view and edit driver and owner operator pay plans
* **"Approve Payable Items"**: Ability to approve payable items in billing
* **"Create Carrier Statement"**: Ability to create carrier statements
* **"Revert Carrier Statement"**: Ability to revert carrier statements
* **"Edit Invoice Customer As"**: Ability to edit the customer assignment on an invoice

### Report Permissions

* **"Fuel Report"**: Ability to access the Fuel Report option from the main menu
* **"Toll Report"**: Ability to access the Toll Report option in the main menu
* **"View Summary Financial Report"**: Ability to access the Summary Financial Report
* **"View Detailed Financial Report"**: Ability to access the Detailed Financial Report
* **"View Statement List Report"**: Ability to access the Statement List Report
* **"View Statement Items Report"**: Ability to access the Statement Items Report
* **"View Asset Safety Report"**: Ability to access the Asset Safety Report
* **"View Driver YTD"**: Ability to view driver year-to-date earnings and payment data

### Dispatch Permissions

* **"Dispatch"**: Marks the user as a dispatcher within the Dispatchers list in the Assets pages of Alvys
* **"Assign Carrier"**: Ability to assign a carrier to a load
* **"Override Stop Status"**: Ability to override stop statuses
* **"Override Load Weight"**: Ability to override weights set on a load
* **"Release Loads"**: Ability to release a load
* **"Override Carrier Restriction"**: Ability to assign a carrier whose compliance status is flagged as NonCompliant or RequiresReview

### Privacy Permissions

* **"View Tax ID/SSN"**: Ability to see the Tax ID/SSN information in driver profiles and carrier profiles
* **"Edit Tax ID/SSN"**: Ability to edit the Tax ID/SSN information in driver profiles and carrier profiles
* **"View PII"**: Ability to view personally identifiable information within driver and carrier profiles
* **"View ACH Details"**: Ability to view driver bank account and routing numbers (ACH details) in driver profiles. Without this permission, account details appear masked.

### General Permissions

* **"DAT User"**: Only to be enabled for companies that use a DAT integration. This allows the user to enter the DAT credentials necessary for their company's DAT integration.
* **"TruckStop User"**: Only to be enabled for companies that use a TruckStop integration. This allows the user to enter the TruckStop credentials necessary for their company's TruckStop integration.
* **"Calendar Past Dates"**: Ability to set or edit dates in the past on loads and records
* **"Unlock Loads"**: Ability to unlock loads to allow editing
* **"View Maintenance Amounts"**: Ability to view cost amounts associated with maintenance records

### Marketplace Permissions

* **"View Marketplace Loads"**: Ability to view loads available on the Alvys Marketplace
* **"Book Marketplace Loads"**: Ability to book loads directly from the Alvys Marketplace
* **"Bid on Marketplace Loads"**: Ability to place bids on loads listed in the Alvys Marketplace
* **"Post Loads to Marketplace"**: Ability to post loads to the Alvys Marketplace

### Management Permissions

* **"Add User"**: Ability to create users
* **"Set Permission"**: Ability to update or change permission settings for other user accounts
* **"Activate Carrier"**: Allows the user to create, activate, or inactivate a carrier
* **"Edit Carrier"**: Allows the user to edit an existing carrier. Activating or inactivating a carrier also requires the **"Activate Carrier"** permission.
* **"Delete Carrier"**: Ability to delete a carrier from the carriers list. If the carrier has been assigned to any loads in Alvys, deleting it will also remove it from those loads.
* **"Delete User"**: Ability to delete a user
* **"Edit Asset"**: Ability to edit a trailer, truck, or driver within the assets lists
* **"Delete Asset"**: Ability to delete a trailer, truck, or driver within the assets lists. If the asset has been assigned to any loads in Alvys, deleting it will also remove it from those loads.
* **"View Drivers"**: Ability to view the Drivers list within the Assets section
* **"View Trucks"**: Ability to view the Trucks list within the Assets section
* **"View Trailers"**: Ability to view the Trailers list within the Assets section
* **"View Maintenance Records & Totals"**: Ability to view maintenance records and cost totals for assets
* **"View Accidents"**: Ability to view accident records for drivers and assets
* **"View Claims"**: Ability to view insurance claims
* **"View Roadside Inspections"**: Ability to view roadside inspection records for drivers and vehicles
* **"Edit Webhooks"**: Ability to configure and manage webhook integrations

### Customer Management Permissions

* **"Create Customer"**: Allows the user to create or import a company where the company type is Customer or Broker/3PL
* **"Edit Customer"**: Ability to edit companies in the companies list where the company type is Customer or Broker/3PL
* **"Activate Customer"**: Allows the user to activate or inactivate a company where the company type is Customer or Broker/3PL
* **"Delete Customer"**: Ability to delete a company from the companies list where the company type is Customer or Broker/3PL. If the company has been assigned to any loads in Alvys, deleting it will also remove it from those loads.
* **"View Credit Limits"**: Ability to view credit limits set on customer accounts
* **"Manage Credit Limits"**: Ability to set and manage credit limits on customer accounts

### Company Management Permissions

* **"Create Company"**: Allows the user to create a company where the company type is Cold-Warehouse, Dry-Warehouse, Factoring Company, Lease, Shipper/Consignee, or Terminal
* **"Edit Company"**: Ability to edit companies in the companies list where the company type is Cold-Warehouse, Dry-Warehouse, Factoring Company, Lease, Shipper/Consignee, or Terminal
* **"Activate Company"**: Allows the user to activate or inactivate a company where the company type is Cold-Warehouse, Dry-Warehouse, Factoring Company, Lease, Shipper/Consignee, or Terminal
* **"Delete Company"**: Ability to delete a company from the companies list where the company type is Cold-Warehouse, Dry-Warehouse, Factoring Company, Lease, Shipper/Consignee, or Terminal. If the company has been assigned to any loads in Alvys, deleting it will also remove it from those loads.

### App Permissions (Alvys Mobile App)

These permissions apply to driver-facing access within the Alvys mobile app.

* **"View Trip Value"**: Allows the driver to view the trip value
* **"Issue ECheck"**: Ability for the driver to create and access e-checks
* **"Cancel ECheck"**: Ability for the driver to cancel e-checks
* **"View Customer Rate Confirmation"**: Allows the driver to view the customer rate
* **"View Carrier Rate Confirmation"**: Allows the driver to view the carrier rate
* **"View Payable Amount"**: Allows the driver to see their payable amount
* **"View App Paystubs"**: Allows the driver to view their paystubs in the Alvys mobile app
* **"Edit Trailer Number"**: Allows the driver to edit their assigned trailer number in the Alvys mobile app
* **"Send Carrier Rate Confirmation Email"**: Allows the driver to send carrier rate confirmation emails from the Alvys mobile app

### Load Permissions

* **"Edit Miles"**: Ability to edit the loaded and empty miles on a load

## Troubleshooting

### User has the permission but still cannot access the feature

1. Ask the user to **log out and log back in**. Permission changes take effect on the next session — this resolves the majority of cases where a newly granted permission is not visible.
2. If the issue persists after re-login, **clear the browser cache and cookies**, then try again.
3. Confirm the permission is **actually saved**. Navigate to **Settings → Organization → Users → \[user] → Permissions** and verify the checkbox is enabled. In some cases (particularly in Safari), toggling a permission can trigger an unexpected session logout before the change saves — re-enable the permission and confirm the session stays active.
4. Check whether the issue is **load-specific**. Some actions are blocked not by permissions but by load state: a locked load, missing required documents, incomplete stops, or active tracking can all prevent actions even when permissions are correctly set. Unlock the load and confirm all required steps are complete before re-testing.
5. Check whether the issue is **office-specific**. If a user cannot see certain loads despite correct permissions, the loads may be assigned to an office that does not share with the user's office. Office-level load sharing is configured separately from user permissions — see Office Configuration.

### Permission appears to reset or disappear after a system update

Occasional platform updates can cause temporary permission drops. If a user reports losing access they previously had and no admin has changed their permissions, ask them to log out and back in. If the issue persists across multiple users, contact Alvys Support — this may indicate a platform-level bug.

### Admin role lost or needs to be restored

Role assignment in Alvys follows a strict hierarchy — you can only grant a role below your own. If someone at your company holds a role high enough to grant the needed access, they can do this directly from **Settings → Organization → Users**. If no one at your company holds a high enough role (for example, the only Admin has left), contact your Alvys Customer Success Manager or Alvys Support — account-level intervention is required in that case only.

## FAQs

**Q: Who can change a user's permissions?**

**A:** Any user who holds the **"Set Permission"** permission can update or change permission settings for other user accounts.

**Q: Do delete permissions affect load history?**

**A:** Yes. If a carrier, company, customer, or asset that has been assigned to loads is deleted, it is also removed from those loads in Alvys. Enable delete permissions with caution.

**Q: What is the difference between "Activate Carrier" and "Edit Carrier"?**

**A:** **"Edit Carrier"** allows editing the details of an existing carrier record. **"Activate Carrier"** is a separate permission required to create, activate, or inactivate a carrier. Both permissions must be enabled for a user who needs full carrier management access.

**Q: Why would I enable "DAT User" or "TruckStop User"?**

**A:** These permissions are only relevant for companies that have set up a DAT or TruckStop integration respectively. Enabling them allows the user to enter their personal credentials for those integrations. If your company does not use these integrations, these permissions are not needed.

**Q: Can I grant someone the Admin or Partner Admin role from within Alvys?**

**A:** Yes, if your own role sits above the one you're granting. Alvys has eleven built-in roles in a strict hierarchy, and you can only assign a role below your own — so an Admin can grant Partner Admin, but a Partner Admin cannot promote anyone to Admin. Office Admins can add users and adjust permissions only for users beneath them, and cannot promote anyone to Office Admin or higher. If no one at your company holds a high enough role — for example the only Admin has left — contact your Alvys Customer Success Manager or Alvys Support.

**Q: A user has the correct permissions but still cannot perform an action — what else could be blocking them?**

**A:** Permissions control access, but some actions also require the load or record to be in a specific state. A load that is locked for editing, missing required documents, has incomplete stops, or has active tracking enabled can block actions regardless of permission settings. See the Troubleshooting section above for a step-by-step resolution path.

<Warning>
  **Office visibility is separate from permissions.** If a user has the correct permissions but still cannot see specific loads, check whether those loads are assigned to an office that shares with the user's office. Office-level load sharing is configured separately from user permissions — adjusting permissions will not resolve office visibility issues.
</Warning>

## What Permissions Don't Control

The following are commonly mistaken for permission issues but are controlled by feature configuration, not the permissions panel:

* **Tab visibility by role.** Hiding or showing navigation tabs (Reports, Assets, Carriers, Maintenance, Safety, Accounting) for specific roles is not fully controlled by individual permission toggles. Some tabs require full role reassignment rather than permission changes to hide.
* **Assignment preference restrictions.** There is no permission that prevents users from editing their own assignment preferences. This is a product behavior, not a permission setting.
* **Carrier packet / onboarding form fields.** The fields that carriers are required to complete during onboarding cannot be customised through permissions. Only the Carrier Agreement PDF and the email message sent with the carrier packet can be modified.
* **TONU rate rules and other load configuration settings.** These are feature settings configured at the load or subsidiary level, not permission controls.
* **Office-level load sharing.** Which offices share loads with each other is an office configuration setting, not a user permission.

## Go Deeper

* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Rates Permissions
Source: https://docs.alvys.com/en/help/administration/rates-permissions

Set the nine Rates permissions that gate viewing and editing of customer rates, carrier rates, trip values, accessorials, and driver pay on every load.

<Note>
  The Rates category controls who can see or hide financial data on loads — including line haul (customer rate), carrier rate, driver pay (trip value), and accessorial charges. Use these permissions to turn rate visibility on or off for dispatchers, drivers, owner operators, and other roles.
</Note>

## Overview

Rates Permissions govern access to the financial data at the core of every load in Alvys. Nine permissions are organized into four view-and-edit pairs plus one standalone permission, giving administrators precise control over who can see and who can change the numbers that drive revenue, cost, and driver pay.

Restricting rate visibility and editing rights (rate access, rate control) protects your company from unauthorized changes that could affect profitability, customer billing accuracy, and driver settlement integrity.

## Where to Find It

To view or modify Rates Permissions for a user, navigate to **Settings → Organization → Users**, open the user's profile, and select **Edit**. The Rates section appears within the permissions panel. The logged-in user must have the **"Set Permission"** permission (located in the Management category) to make any changes.

<Warning>
  To modify permissions, the logged-in user must have the **"Set Permission"** permission in the Management category. Without it, a user can view the profile but cannot adjust any permissions.
</Warning>

<Tip>
  **Driver app permissions work differently.** For drivers using the Alvys mobile app, rate and pay visibility is controlled from the driver's profile under **Assets → Drivers** — not from the user profile in **Settings → Organization → Users**. Driver user profiles under **Settings → Organization → Users** are accessible to support only.
</Tip>

Navigate to **Settings → Organization → Users** and open the **Users** tab.

<img alt="Image showing navigation to Settings" />

*Image showing navigation to Settings*

Choose an existing user to **Edit**, or select **Add User** to create a new profile.

<img alt="Image showing the Users tab in Settings with the Add User button" />

*Image showing the "Users" tab in Settings with the "Add User" button*

Scroll to the **Permissions** section and locate the **Rates** category. The nine Rates checkboxes are **"View Customer Rate"**, **"Edit Customer Rate"**, **"View Carrier Rate"**, **"Edit Carrier Rate"**, **"View Trip Value"**, **"Edit Trip Value"**, **"Add Accessorials"**, **"View Driver Rates"**, and **"Edit Driver Rates"**.

<img alt="Image showing Rates permissions checkboxes (9 permissions) on user profile" />

*Image showing Rates permissions checkboxes (9 permissions) on user profile*

## Key Concepts

The Rates category contains nine permissions in four view-and-edit pairs plus one standalone:

* **"View Customer Rate"** and **"Edit Customer Rate"** — control access to the customer-facing revenue side of a load
* **"View Carrier Rate"** and **"Edit Carrier Rate"** — control access to the carrier cost side of a load
* **"View Trip Value"** and **"Edit Trip Value"** — control access to the driver compensation amount
* **"View Driver Rates"** and **"Edit Driver Rates"** — control access to driver pay rate configurations in driver profiles
* **"Add Accessorials"** — controls the ability to create and manage supplemental charges (detention, lumper fees, TONU, etc.)

<Warning>
  **Rate Permissions apply to all loads retroactively, not just future ones.** Enabling or disabling a Rate Permission takes effect immediately across all loads in the system, including historical ones. This is especially important when a driver changes roles — for example, a company driver converting to an owner operator. A driver granted rate visibility will be able to see that data on past loads from their previous role. There is currently no way to restrict rate visibility to loads from a specific date onward — if a driver should not have access to historical rate data from a previous role, do not enable rate permissions on their profile.
</Warning>

## How to Use It

To enable or disable Rates Permissions for a user:

1. Navigate to **Settings → Organization → Users** and open the user's profile.
2. Click **Edit**.
3. Scroll to the **Permissions** section and locate the **Rates** category.
4. Enable or disable the relevant checkboxes.
5. Click **Save** to apply.

Use the **Key Concepts** section above to identify which permissions are appropriate for the role before making changes. For full instructions on creating and managing user profiles, see [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys).

## "View Customer Rate" (Line Haul)

The **"View Customer Rate"** permission controls whether a user can see the customer-facing rate on a load, which represents what the company charges the customer for moving freight. When enabled, users can view the Customer Money Box on the Load Details page and see the Customer Freight Charge and Customer Revenue columns in the Load Board grid.

<img alt="Image showing Customer Rate card / Customer Money Box" />

*Image showing Customer Rate card / Customer Money Box*

<Warning>
  This permission is strictly for viewing and does not allow users to modify customer rates. To make changes to customer rates, the **"Edit Customer Rate"** permission is required.
</Warning>

<Tip>
  **The Billing permission provides a separate path to the customer rate.** A user without **"View Customer Rate"** will not see the rate in the Money Box on the load — it simply does not appear. However, if that user has the **Billing** permission enabled, they can access the generated invoice, which displays the customer rate. These are two independent surfaces controlled by different permissions.
</Tip>

<img alt="Image showing Customer Freight Charge and Customer Revenue columns in Load Board" />

*Image showing Customer Freight Charge and Customer Revenue columns in Load Board*

<Tip>
  **Best Practice:** Grant **"View Customer Rate"** to users who need to monitor rates such as Billers and Dispatchers so they can see what loads are worth and make informed sourcing decisions.
</Tip>

## "Edit Customer Rate"

The **"Edit Customer Rate"** permission allows users to modify the customer-facing rate on a load. Editing customer rates directly affects the revenue side of every load and can impact invoicing accuracy, so this permission should be granted carefully.

<img alt="Edit Customer Rate (Customer Money Box editable)" />

*Edit Customer Rate (Customer Money Box editable)*

<Tip>
  **Best Practice:** Separate **"View Customer Rate"** (broad access, most dispatchers) from **"Edit Customer Rate"** (restricted access, billing and management only). This is the most important rate permission split in Alvys. Letting dispatchers see rates without being able to change them strikes the right balance between operational transparency and financial control.
</Tip>

## "View Carrier Rate"

The **"View Carrier Rate"** permission controls whether a user can see the carrier cost on a load, including the Carrier Money Box on the Load Details page, the Carrier Rate and Carrier All-in Rate columns in the Load Board grid, and the Payment History table in the carrier's profile.

<img alt="Image showing Carrier Rate card / Carrier Money Box" />

*Image showing Carrier Rate card / Carrier Money Box*

The Carrier Rate and Carrier All-in Rate columns in the Load Board grid become visible with this permission.

<img alt="Image showing Carrier Rate and Carrier All-in Rate columns in Load Board" />

*Image showing Carrier Rate and Carrier All-in Rate columns in Load Board*

For trips with external carriers that have a carrier payment, this permission also reveals the Payment History table in the Carrier Details section.

<img alt="Image showing Payment History table in Carrier Details section on a Trip" />

*Image showing Payment History table in Carrier Details section on a Trip.*

<Tip>
  **Best Practice:** Grant **"View Carrier Rate"** to users involved in the load's financial lifecycle: dispatchers, billers, and operations managers. Withhold this access from personnel who do not require cost visibility.
</Tip>

## "Edit Carrier Rate"

The **"Edit Carrier Rate"** permission allows users to modify the carrier cost on a load. Because carrier rates directly affect profit margins and settlement calculations, editing is status-dependent and restricted on loads that have already entered billing or payment workflows.

<img alt="Edit Carrier Rate — Carrier Money Box with editable fields" />

*Edit Carrier Rate — Carrier Money Box with editable fields*

<img alt="Payment History table in Carrier Details with Add carrier payment and delete icons" />

*Payment History table in Carrier Details — Add carrier payment and delete icons visible when Edit Carrier Rate is enabled*

<img alt="Edit Carrier Rate in the Carrier Settlements module" />

*Edit Carrier Rate in the Carrier Settlements module*

<Tip>
  **Best Practice:** Pair **"Edit Carrier Rate"** with **"View Carrier Rate"** so that users who can edit rates can also see them. Consider limiting **"Edit Carrier Rate"** to senior dispatchers and billing staff rather than granting it to all operational roles.
</Tip>

## "View Trip Value" (Driver Pay)

The **"View Trip Value"** permission controls whether a user can see the driver compensation amount on a load. Trip value is distinct from carrier rate: it reflects what the driver or owner-operator earns rather than what the company pays the carrier. When enabled, users can see the Trip Value Money Box, the Driver Money Box (covering Primary Driver, Secondary Driver, and Owner-Operator pay), the Trip Value column in the Trip Board, and driver pay information in the Alvys mobile app.

<img alt="View Trip Value / Trip Value Money Box" />

*View Trip Value / Trip Value Money Box*

When enabled, the Driver Money Box becomes accessible, showing the trip value for the Primary Driver, the Secondary Driver, and the Owner-Operator depending on how the load is set up.

<img alt="A driver money box card on a load, with the Trip Value row highlighted" />

*A driver money box card on a load, with the Trip Value row highlighted. A load shows one card per driver position, so a team load shows a second card as well.*

*This screenshot predates the May 2026 rename and still shows the old **Driver 1** heading. In the app, driver positions now read **Primary Driver** and **Secondary Driver**.*

The same permission also controls trip value visibility in the Alvys mobile app; it is selected automatically in the App category when View Trip Value is enabled in the Rates category.

<Note>
  Drivers must first be created via **Assets → Drivers** and complete SMS verification. Driver app permissions are managed from the driver's profile under **Assets → Drivers** — not from the user profile under **Settings → Organization → Users**, which is accessible to support only.
</Note>

<img alt="Image showing View Trip Value permission which also controls viewing the trip value in the mobile app" />

*Image showing View Trip Value permission which also controls viewing the trip value in the mobile app*

This permission also controls the visibility of the **Trip Value** column in the [Trip Board](https://app.alvys.com/#/loads/v2).

<img alt="Image showing the Trip Value column in Trips Board" />

*Image showing the Trip Value column in Trips Board*

<Tip>
  **Best Practice:** Grant **"View Trip Value"** to all users involved in load financial planning and driver settlement. Withhold it from Driver role users (who have separate app-level permissions for viewing their own pay) and Safety personnel who do not need compensation visibility.
</Tip>

## "Edit Trip Value" (Custom Driver Payment)

The **"Edit Trip Value"** permission allows users to modify the driver compensation amount on a load. Changes to trip value directly affect driver settlements and paystubs, so this permission carries significant financial risk if granted broadly.

The trip value fields are interactive when this permission is enabled, but they lock automatically once a driver has been marked as **Paid** or a truck statement has been generated. This prevents retroactive changes to finalized pay.

<img alt="Edit Trip Value (fields interactive) in Money Box" />

*Edit Trip Value (fields interactive) in Money Box*

<img alt="The Trip Value row in a driver money box card, which becomes editable with this permission" />

*The Trip Value row in a driver money box card, which becomes editable with this permission. As above, the heading in this screenshot predates the Primary Driver rename.*

If a trip value must be edited after a driver has been marked Paid, the truck statement must first be reverted to unlock the fields.

<img alt="Image showing error message displayed to user when the Trip Value locked because a driver was paid" />

*Image showing error message displayed to user when the Trip Value locked because a driver was paid.*

When the driver has been marked Paid or a truck statement has been generated, the Trip Value fields display as plain text rather than editable inputs.

<img alt="Trip Value fields locked as plain text after the driver is marked Paid" />

*Trip Value fields locked as plain text after the driver is marked Paid*

<Tip>
  **Best Practice:** Restrict **"Edit Trip Value"** to users who actively manage driver pay, typically dispatchers and billing personnel. For operations managers and sales agents who need to see trip values for planning purposes, grant **"View Trip Value"** only without the edit capability.
</Tip>

## "Add Accessorials" (Lumper, Detention, Road Service)

The **"Add Accessorials"** permission enables users to create, edit, and manage supplemental charges beyond the base freight rate. These accessorials cover specialized services or conditions encountered during a load's lifecycle, such as detention, lumper fees, fuel surcharges, layovers, and TONU (Truck Ordered Not Used). Within Alvys, these charges can be applied to three distinct pillars: the Customer for revenue, the Carrier for cost, and the Driver or Owner-Operator for pay.

<Warning>
  **This permission governs create, edit, and delete — not just creation.** Without **"Add Accessorials"**, a user cannot edit the amount of an existing accessorial or remove it using the trash icon. Attempting either action returns an **"Access denied"** message. Grant this permission to any user who needs to manage charges already on a load, not only those adding new ones.
</Warning>

<img alt="Image showing the Add Accessorial button" />

*Image showing the "Add Accessorial" button*

<img alt="Image showing Alvys money box with accessorial options such as edit amount, mark as paid, and remove accessorial" />

*Image showing Alvys money box with options for accessorials such as edit amount, mark as paid, and remove accessorial*

<Warning>
  The **"Add Accessorials"** permission is also required for performing some E-Check operations such as adding an e-check, canceling an e-check, moving an e-check between loads, and marking an e-check as paid. These e-check operations are considered modifications to load charges that fall under the accessorials umbrella.
</Warning>

If accessorials are added carelessly or incorrectly, the company either absorbs an unnecessary cost or bills a customer incorrectly, damaging the business relationship. By restricting **"Add Accessorials"**, companies ensure that only authorized personnel can create and modify these charges. By default, this permission is granted to all roles except Safety and Driver. It is essential for Dispatchers managing real-time transit issues and Billing personnel who reconcile final invoices and settlements.

<Tip>
  **Best Practice:** Grant **"Add Accessorials"** to dispatchers and billers who regularly manage load charges. Require documentation (such as uploaded receipts) for accessorial charges to maintain an audit trail. Review accessorial patterns periodically to identify unusual activity.
</Tip>

<Warning>
  **On split loads:** The **Add Accessorials** button is disabled on the original load when it has been split into multiple trips. To add an accessorial on a split load, open the individual **split trip** — not the original load — and add the accessorial from the trip's detail view.
</Warning>

<Warning>
  **E-check-backed accessorials cannot be deleted — they must be moved.** If an accessorial is tied to a **used** e-check (one where the funds have already been disbursed), clicking the trash icon will not remove it. The system blocks deletion. If the e-check has not yet been used, the accessorial can be removed normally. To remove this type of accessorial from a load (for example, to cancel the load), the e-check must first be moved to another load completed by the same driver. Once moved, the charge is removed from the original load and the cancellation can proceed. See **How to Move an E-Check to a Different Load** for steps.
</Warning>

## "View Driver Rates" (Driver Pay Rate)

The **"View Driver Rates"** permission regulates a user's ability to access sensitive compensation structures stored within driver profiles and load-level contexts throughout Alvys. This authority encompasses the specific rate data that determines how company drivers and owner-operators are remunerated, such as per mile, per load, percentage, or hourly configurations. This permission is distinct from trip value or carrier rates because it governs the underlying pay methodology rather than just the final settlement amount. Upon being granted, the Rate section of the driver profile becomes visible, driver rates on individual loads are accessible, and the Driver Rate column appears in the Load Board grid.

When **"View Driver Rates"** is enabled, the Rate section of the driver profile is visible, displaying the rate structure (for example: per mile, rate per job, percentage, etc.). This information can be used to calculate expected driver pay for a given load, verify payroll accuracy, or review compensation structures during performance discussions. Without this permission, the compensation section of driver profiles remains hidden.

<img alt="View Driver Rates: driver profile Rate section" />

*View Driver Rates: driver profile Rate section*

Driver and owner-operator rate information is also visible at the load level when this permission is enabled:

<img alt="Image showing driver rate at the load level" />

*Image showing driver rate at the load level*

This permission additionally governs the visibility of the Driver Rate column within grid views and the column selection on the Trip Board. If this permission is withheld, the Driver Rate column is suppressed entirely, preventing users from manually adding it to their Trip Board. This ensures that granular financial metrics remain hidden in the trip details and driver asset pages.

<img alt="Image showing Driver Rate column in Trip Board grid" />

*Image showing Driver Rate column in Trip Board grid*

**"View Driver Rates"** is assigned by default to all roles except Safety and Driver. It remains most relevant for Operations Managers, Dispatchers, and Billers who require visibility into compensation for planning, settlement, and cost analysis. For payroll personnel, this access is indispensable for auditing and verifying the accuracy of settlements before processing payments.

<Tip>
  **Best Practice:** Provide **"View Driver Rates"** only to users who require it for payroll, HR, or fleet management purposes, as general dispatchers typically do not need to observe individual driver pay rates to assign and manage loads. Grant this permission alongside **"View Trip Value"** for users responsible for managing driver compensation.
</Tip>

## "Edit Driver Rates" (Driver Pay Rate)

The **"Edit Driver Rates"** permission grants authorized personnel the ability to modify pay rate configurations within driver profiles, including cents-per-mile, flat rates, percentage-based structures, and other compensation parameters. Any adjustment directly influences all subsequent payroll calculations and financial settlements. This permission operates as a view-edit pair with **"View Driver Rates"**: while **"View Driver Rates"** enables a user to observe the data, **"Edit Driver Rates"** provides the authorization to perform inline editing within the driver money box for both revenue and non-revenue load details and driver asset profiles. Without this permission, even users who can view the rates are restricted from making any alterations, ensuring that sensitive financial data remains secure from accidental or unauthorized modification.

<img alt="Image showing Rates section on Driver Profile" />

*Image showing Rates section on Driver Profile*

<img alt="Image showing the Edit option for the driver rate on the driver profile" />

*Image showing the Edit option for the driver rate on the driver profile.*

**"Edit Driver Rates"** is assigned by default to all roles with the exception of Safety and Driver. It remains most relevant to personnel involved in settlement processing, cost analysis, and driver management. For accounting teams, this authorization is vital for rectifying billing errors and ensuring that driver compensation aligns with the most current negotiated terms.

<Tip>
  **Best Practice:** Grant **"Edit Driver Rates"** to users who manage driver compensation as part of their daily workflow. For users who only need to review rates, such as auditors, grant **"View Driver Rates"** exclusively.
</Tip>

## FAQs

**Q:** How are Rates Permissions organized in Alvys?

**A:** The Rates category contains nine permissions arranged into four view-and-edit pairs along with a standalone **"Add Accessorials"** permission. Each view permission governs the visibility of rate data, while each edit permission governs the ability to modify that data.

**Q:** Can a user edit a rate without being able to view it?

**A:** The system does not strictly prevent granting edit access without view access, but doing so creates a poor user experience because the fields will remain hidden. Always grant the view permission alongside its corresponding edit permission.

**Q:** A user without "View Customer Rate" can still see the customer rate on an invoice. Why?

**A:** The Money Box on a load and the generated invoice are two separate surfaces controlled by different permissions. **"View Customer Rate"** controls whether the rate appears in the Money Box — without it, the rate is not visible there. The **Billing** permission controls access to generated invoices, which display the customer rate regardless of whether **"View Customer Rate"** is enabled. A user can therefore see the customer rate on an invoice through Billing access without ever having rate view access on the load itself.

**Q:** Why can't I edit the carrier rate on a load even though I have the "Edit Carrier Rate" permission?

**A:** Carrier rate editing is status-dependent. The system blocks editing on loads in **TONU**, **Released**, **Queued**, **Invoiced**, **Financed**, **Completed**, or **On Hold** status. Only loads in **Open**, **Quoted**, **Reserved**, **Covered**, or **Delivered** status allow carrier rate editing. Check the current status of the load to determine if editing is available.

**Q:** What happens if I remove all Rates Permissions from a user?

**A:** The user will lose visibility of all financial rate information on loads. The Money Box on the Load Details page will not show customer rate, carrier rate, or trip value sections. The Load Board will not display rate columns. The user can still see non-financial load information such as origin, destination, status, and equipment type, and perform other actions based on their remaining permissions.

**Q:** Does the "Add Accessorials" permission affect e-check operations?

**A:** Yes. The **"Add Accessorials"** permission is required for some e-check operations such as canceling an e-check, moving an e-check between loads, and marking an e-check as paid. These operations modify load charges that fall under the accessorials umbrella.

**Q:** I need to cancel a load but it is blocked by an accessorial tied to an e-check. What do I do?

**A:** An accessorial backed by a **used** e-check (one where the funds have already been disbursed) cannot be deleted using the trash icon — the system prevents removal. If the e-check has not yet been used, the accessorial can be removed normally. To unblock the cancellation when a used e-check is involved, move the e-check to another load completed by the same driver first. This removes the charge from the original load, which then allows cancellation to proceed.

**Q:** Can a Driver role user ever see rates?

**A:** The Driver role receives no Rates Permissions by default. However, separate permissions in the App category, such as **"View Trip Value"**, **"View Payable Amount"**, and **"View App Paystubs"**, can grant drivers limited visibility into their own compensation through the Alvys mobile application. These App permissions are distinct from the web-facing Rates Permissions covered in this article.

**Q:** Why do Safety and Driver roles not receive Rates Permissions by default?

**A:** These roles focus on compliance and hauling rather than financial management, so they do not require access to sensitive company revenue and cost data.

**Q:** If I grant "Edit Customer Rate", does the user also need "Edit Carrier Rate" to modify both sides of a load?

**A:** Yes. Customer rates and carrier rates have separate edit permissions. Granting **"Edit Customer Rate"** only allows the user to modify the customer side. To modify both sides, the user needs both **"Edit Customer Rate"** and **"Edit Carrier Rate"**.

**Q:** What is the relationship between "Edit Carrier Rate" and "Add Accessorials"?

**A:** Some parts of the system require both permissions to modify carrier charges. If a user has **"Edit Carrier Rate"** but not **"Add Accessorials"**, they may have limited ability to modify carrier-side line items. Grant both permissions to users who manage carrier rates and charges. If a user has the **"Edit Carrier Rate"** permission but still cannot edit the carrier rate, check whether the load is part of a carrier settlement or has been split.

**Q:** Should dispatchers or billing staff have the "Add Accessorials" permission?

**A:** Most operations grant this to both roles so dispatchers can log real-time issues like detention while billers ensure all charges are captured during final reconciliation.

**Q:** I want dispatchers to be able to see both sides of the load margin (customer rate and carrier rate). Do I need to enable four permissions?

**A:** You need two permissions for view-only access to both rates: **"View Customer Rate"** and **"View Carrier Rate"**. These two permissions together give the dispatcher a full margin picture including what the load earns and what it costs, without the ability to change either figure. The Edit permissions are separate and not required for read-only visibility.

**Q:** A driver is converting from company driver to owner operator. Will enabling rate permissions let them see rates from their past loads in their company driver role?

**A:** Yes. Rate Permissions apply to all loads in the system, not just future ones. Enabling **"View Driver Rates"** or **"View Trip Value"** on a profile gives that user access to rate data on past loads as well. There is currently no way to restrict rate visibility to a specific date range. If the driver should not have access to rate data from their time as a company driver, do not enable rate permissions on their profile — once enabled, they will apply to all loads including historical ones.

## Troubleshooting

### "Edit Carrier Rate" is granted but the carrier rate field will not change

Carrier rate editing is status-dependent. Editing is blocked on loads in TONU, Released, Queued, Invoiced, Financed, Completed, or On Hold status. Confirm the load is in Open, Quoted, Reserved, Covered, or Delivered status.

### Rate columns are missing from the Load Board grid

The user is missing the corresponding view permission. Customer rate columns require **"View Customer Rate"**, carrier rate columns require **"View Carrier Rate"**, and the Driver Rate column requires **"View Driver Rates"**.

### A user can view rates but cannot edit them

The user holds only the view permission for that rate. Grant the paired edit permission (for example, **"Edit Customer Rate"** alongside **"View Customer Rate"**).

### Contract rate not applying to a load

If a contracted rate exists but is not populating on a load, check these conditions in order:

* **Address order:** Confirm the load's pickup and delivery addresses match the contract's lane criteria exactly. Reversed addresses (pickup entered as delivery and vice versa) will not trigger a match.
* **Commodity and equipment type:** Confirm the load's commodity and equipment type meet the contract's requirements.
* **Contract date range:** Confirm the contract is active for the load's pickup date.
* **Customer assignment:** Confirm the load is assigned to the customer or broker specified in the contract.

### Driver pay calculating incorrectly when multiple rate plans are active

If a driver has more than one active rate plan and pay is calculating unexpectedly, review the rate plan priority order in the driver's profile. Only one rate plan should be active for a given load type at a time. Deactivate any conflicting plans that do not apply to the current scenario, then verify the remaining plan's rules match the load type, customer, and equipment in use.

### "View Trip Value" is enabled but the driver cannot see pay in the mobile app

Driver app permissions are managed from the driver's profile under **Assets → Drivers** — not from **Settings → Organization → Users**. After enabling **"View Trip Value"** in the Rates category, the driver must first log into the Alvys mobile app. Once they have logged in, the App permissions section appears in their driver profile under **Assets → Drivers**, where you can verify or adjust which pay fields are visible in the app.

## Go Deeper

Proceed to the [E-Check Permissions](/en/help/administration/e-check-permissions) article to learn how to issue, cancel, and move e-checks for both carriers and drivers, including how to configure processing fees and the specific permissions required to delete load notes.

<Info>
  📁 Back to [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)
</Info>


# Report Permissions
Source: https://docs.alvys.com/en/help/administration/report-permissions

Configure the Summary and Detailed Financial Report toggles in Alvys Report permissions to control which users can access sensitive financial reporting.

<Note>
  Report Permissions control access to all nine reports in Alvys — Fuel Report, Toll Report, View Summary Financial Report, View Detailed Financial Report, View Statement List Report, View Statement Items Report, View Asset Safety Report, View Driver YTD, and View Insights. This article covers what each permission unlocks, which roles receive it by default, how to enable one, and what to check when a report page is missing from your menu.
</Note>

## Overview

Report Permissions (also called reporting access or report permissions) control access to financial and operational reporting within Alvys. This article covers all eight permissions in the **Reports** category: **"Fuel Report"**, **"Toll Report"**, **"View Summary Financial Report"**, **"View Detailed Financial Report"**, **"View Statement List Report"**, **"View Statement Items Report"**, **"View Asset Safety Report"**, and **"View Driver YTD"**. Each permission controls access to a specific report and can be assigned independently, allowing you to grant each user exactly the reporting visibility their role requires.

<Info>
  This article covers all eight permissions in the Reports category. Reports gated outside this category — IFTA, Custom Reports, and Alvys Insights — are covered in the articles linked under Go Deeper.
</Info>

Insights is not a Reports permission. Access to Alvys Insights is controlled by the separate **"View Insights"** permission and also requires Alvys Intelligence to be enabled for your account.

## Where to Find It

Report Permissions are configured at the individual user level within the User Management interface.

<Warning>
  To modify these permissions, the logged-in user must have the **"Set Permission"** permission enabled. Without it, the user can view the form but cannot make changes. See [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions) for details.
</Warning>

To adjust these settings:

* Select your **username** in the bottom-left corner of the Alvys interface.

<img alt="Image showing navigation to Settings" />

*Screenshot of Settings highlighted within Account Management*

* Go to **Settings → Organization** and select the **Users** tab.

<img alt="Screenshot showing the Users tab selected in Organization." />

*Screenshot of the Users tab highlighted within Organization*

* Choose an existing user to **Edit**, or select the **Add User** button to create a new profile.
* Scroll to the **Permissions** section and locate the **Reports** category.
* Identify the **nine (9)** individual checkboxes corresponding to the specific permissions detailed in this article: **Fuel Report**, **Toll Report**, **View Summary Financial Report**, **View Detailed Financial Report**, **View Statement List Report**, **View Statement Items Report**, **View Asset Safety Report**, **View Driver YTD**, and **View Insights**.

<img alt="Image Showing Report permissions category" />

*Image Showing Report permissions category*

## Report Permissions Breakdown

### "Fuel Report"

Fuel constitutes one of the largest variable costs for a trucking company, often ranking second only to driver wages. The Fuel Report provides essential visibility into fuel expenditures by driver, vehicle, location, and time period. The Fuel Report permission governs access to the [Fuel Report page](https://app.alvys.com/assets/fuel) which is located within the Asset module. This report displays fuel transaction data for both drivers and vehicles, allowing users to audit fuel card purchases, analyze gallon consumption, manage driver fuel deductions, and upload external transaction files among other related functions. In the absence of this permission, the page remains hidden from the navigation menu of the user.

<img alt="Screenshot showing the Alvys Fuel Report." />

*Screenshot showing the Alvys Fuel Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, Biller, and Safety. Not assigned by default to: Dispatcher, Sales Agent, Data Entry, Office Admin, or Driver.

To upload fuel transactions manually, go to **Assets → Fuel** and select **Transaction File Upload** — the button is labelled **Transaction File Upload** rather than "Import". This control is not separately permission-gated: if you can open the Fuel Report page, you can upload to it.

<Info>
  ✅ Best practice: Grant the Fuel Report permission to all staff who manage fuel expenses or who need to audit driver fuel card usage. Consider also giving it to fuel card administrators who need to reconcile transactions. You do not need to restrict this permission as tightly as financial or HR reports.
</Info>

### "Toll Report"

The Toll Report permission governs access to the [Toll Report page](https://app.alvys.com/assets/tolls) situated within the Asset module. This report provides a comprehensive display of toll transaction data, enabling users to analyze toll charges according to specific drivers, vehicles, routes, and time periods. In the absence of this permission, users are unable to navigate to the Toll Report page as it remains excluded from the navigation menu.

<img alt="Screenshot showing the Alvys Toll Report." />

*Screenshot showing the Alvys Toll Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, Biller, and Safety. Not assigned by default to: Dispatcher, Sales Agent, Data Entry, Office Admin, or Driver.

### "View Summary Financial Report"

The **"View Summary Financial Report"** permission grants access to the [Summary Financial Report](https://app.alvys.com/#/reports/asset) in Alvys, which provides an operational and financial overview of load and trip activity across a configurable date range. The Summary Financial Report gives managers and dispatchers a quick view of revenue and expenses aggregated by asset, load counts, and other high-level metrics without requiring access to individual invoice-level line items.

<img alt="Screenshot showing the Alvys Summary Financial Report." />

*Screenshot showing the Alvys Summary Financial Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, and Biller. Not assigned by default to: Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, and Driver.

<Info>
  ✅ Best practice: Grant **"View Summary Financial Report"** broadly to roles that manage or monitor operational activity. This report aggregates revenue and expenses by asset rather than exposing individual invoice line items. Use the **"View Detailed Financial Report"** permission to control access to more granular financial data.
</Info>

### "View Detailed Financial Report"

The **"View Detailed Financial Report"** permission grants access to the Detailed Financial Report in Alvys, which provides a granular breakdown of revenue, costs, and margins at the load and trip level. This report exposes individual invoice amounts, cost breakdowns, and margin data and should be limited to roles that genuinely need detailed financial visibility.

<img alt="Screenshot showing the Alvys Detailed Financial Report." />

*Screenshot showing the Alvys Detailed Financial Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, and Biller. Not assigned by default to: Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, and Driver.

<Info>
  💡 Best practice: Restrict **"View Detailed Financial Report"** to roles with a direct need for financial data: billing staff, office managers, senior managers, and owners.
</Info>

### "View Statement List Report"

The View Statement List Report permission governs access to the [Statement List Report page](https://app.alvys.com/#/reports/statement/list) located within the Financial Reports section of the Reports module. This report provides a comprehensive audit trail of all driver statements for both owner operators and company drivers, which are summarized at the statement level. It enables billing and settlement personnel to observe all statements for a specific driver, including the date period and their respective totals for mileage, gross revenue, deductions, credits, and net earnings without the requirement to open each statement individually. Access to this information should be limited to billing and accounting personnel who manage carrier payments.

<img alt="Screenshot showing the Alvys Statement List Report." />

*Screenshot showing the Alvys Statement List Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, and Biller.

<Info>
  ✅ Best practice: Grant **"View Statement List Report"** and **"View Statement Items Report"** together. The Statement List shows which statements exist; the Statement Items report shows the line-item detail on each statement.
</Info>

### "View Statement Items Report"

The **View Statement Items Report** permission controls access to the [Statement Items Report page](https://app.alvys.com/#/reports/statement/items) within the Reports module. While the Statement List Report provides an overview of all driver statements, the Statement Items Report displays the individual line items within those statements, such as specific loads, charges, and deductions.

These statement items represent the granular financial detail behind each driver payment, including individual load charges, accessorial fees, deductions, and adjustments. This level of detail is necessary for billing staff who need to verify the accuracy of driver statements to ensure that all charges are accounted for. Restricting access prevents unauthorized users from viewing detailed driver payment breakdowns.

<img alt="Screenshot showing the Alvys Statement Items Report." />

*Screenshot showing the Alvys Statement Items Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, and Biller.

### "View Asset Safety Report"

The View Asset Safety Report permission governs access to the [Asset Safety Report page](https://app.alvys.com/#/reports/safety) situated within the Reports module. Safety personnel bear the primary responsibility for ensuring that documentation for all assets remains current and that the fleet can legally operate within regulatory frameworks. This report provides a centralized view for safety users to monitor essential certifications that have expired or are approaching expiration.

For drivers, the report highlights critical data points including license expiration, medical certification expiration, the most recent motor vehicle record date, and Clearinghouse status dates. Regarding equipment, the report tracks assigned drivers, license plate expiration, and inspection expiration dates for both trucks and trailers. Additionally, it provides visibility into lease commencement and termination dates to ensure lease compliance across the fleet. By centralizing these diverse metrics, the Asset Safety Report enables proactive management of asset documentation to prevent operational disruptions and maintain full compliance.

<img alt="Screenshot showing the Alvys Drive Safety Report." />

*Screenshot showing the Alvys Drive Safety Report.*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, Dispatcher, Office Admin, and Safety. Not assigned by default to: Biller, Sales Agent, Data Entry, or Driver.

### "View Driver YTD"

The View Driver Year to Date permission governs access to the [Driver Year to Date report page](https://app.alvys.com/#/reports/driver/ytd) situated within the Reports module. This report serves as a centralized resource for monitoring cumulative earnings and financial data for drivers throughout the current calendar year. It provides comprehensive visibility into driver compensation totals, detailed pay period breakdowns, and cumulative year to date accumulations. Because this data discloses sensitive individual earnings and financial performance over time, this authorization acts as a critical security measure to ensure that only authorized personnel can evaluate these specific compensation metrics.

<img alt="Screenshot showing the Alvys Driver Year to Date Report" />

*Screenshot showing the Alvys Driver Year to Date Report*

By default, this permission is granted to: Partner Admin, Admin, Operation Manager, and Biller. Not assigned by default to: Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, and Driver.

<Info>
  ✅ Best practice: Restrict **"View Driver YTD"** to accounting staff and managers who handle driver pay and tax reporting. This report contains sensitive earnings data.
</Info>

### "View Insights"

The **"View Insights"** permission controls access to the Alvys Insights feature, the AI-powered chat interface where users can ask simple questions about their operational and financial data, such as loads, drivers, finances, carriers, and other transportation management system (TMS) data. The [Insights chat interface](https://app.alvys.com/chat) can be accessed from the left navigation panel under **"Insights"**.

<img alt="Image showing navigation to Insights Page" />

*Image showing navigation to the Insights page*

By default, the Admin and Partner Admin roles have this permission. This approach ensures that access to AI analytics is assigned specifically, rather than being available to all users by default. Because Insights queries can reveal sensitive financial, operational, and identity data, restricting access to these trusted roles prevents unintended exposure.

Your data visibility within Insights is structured across two **(2)** distinct security levels to ensure sensitive information remains protected according to your specific role in Alvys.

#### Level 1: Standard domain permissions

The first level of access is determined by standard role-based Alvys permissions. While the **"View Insights"** permission allows you to access the chat interface, your existing domain permissions control which specific categories of data you can see in your query results. For example, to view financial amounts in chat results, you must have an associated permission such as **"Billing"**, **"View Customer Rate"**, or **"View Driver Rates"**. Similarly, viewing equipment or personnel details requires permissions such as **"View Trucks"**, **"View Trailers"**, **"View Drivers"**, or **"View Maintenance"**. If you do not have the required permission for a specific category, that information will be hidden or masked in the results, ensuring that the same security rules applied throughout Alvys are strictly enforced in the Insights tool.

#### Level 2: View personally identifiable information privacy permission

The second level of access corresponds to the **View Personally Identifiable Information (PII)** permission, which is the permission most directly related to the level of detail shown in Insights responses. It acts as a critical secondary security layer that works alongside Level 1 domain permissions to protect sensitive information.

<img alt="Image showing View PII Permissions" />

*Image showing permissions to view personally identifiable information (PII).*

To view highly sensitive information, such as names, email addresses, phone numbers, driver's license numbers, and insurance details, the user must have the **"View Personally Identifiable Information"** permission in addition to the corresponding Level 1 domain permissions. Without this specific permission, these fields will be replaced with masked placeholders, ensuring that personally identifiable information remains protected even when analyzing general data categories.

<Info>
  ✅ Best practice: Grant the **"View Insights"** permission only to senior leadership and owners. If a user was just granted this permission but Insights data does not appear, ask them to sign out and sign back in. Data may take up to 24 hours to load after the permission is enabled for the first time.
</Info>

## Settings & Permissions

Most Reports permissions follow one of three patterns. Financial and statement reports go to Partner Admin, Admin, Operation Manager and Biller. Fuel and Toll add Safety. Asset Safety goes to the operational roles — Dispatcher, Office Admin and Safety — but not Biller.

| Permission                       | Assigned by default to                                                    | Not assigned by default to                                        |
| -------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| "Fuel Report"                    | Partner Admin, Admin, Operation Manager, Biller, Safety                   | Dispatcher, Sales Agent, Data Entry, Office Admin, Driver         |
| "Toll Report"                    | Partner Admin, Admin, Operation Manager, Biller, Safety                   | Dispatcher, Sales Agent, Data Entry, Office Admin, Driver         |
| "View Summary Financial Report"  | Partner Admin, Admin, Operation Manager, Biller                           | Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, Driver |
| "View Detailed Financial Report" | Partner Admin, Admin, Operation Manager, Biller                           | Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, Driver |
| "View Statement List Report"     | Partner Admin, Admin, Operation Manager, Biller                           | Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, Driver |
| "View Statement Items Report"    | Partner Admin, Admin, Operation Manager, Biller                           | Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, Driver |
| "View Asset Safety Report"       | Partner Admin, Admin, Operation Manager, Dispatcher, Office Admin, Safety | Biller, Sales Agent, Data Entry, Driver                           |
| "View Driver YTD"                | Partner Admin, Admin, Operation Manager, Biller                           | Dispatcher, Sales Agent, Data Entry, Office Admin, Safety, Driver |

## Limits & Behavior

* All report permissions are independent. Granting one does not automatically grant any other.
* Users without the required Report permission will not see that report's page in the navigation menu.
* When an admin adds a permission to your account, the change takes effect immediately — you stay signed in, and a banner appears at the top of the screen letting you know your access was updated. Select **Refresh** whenever convenient to reload the page and see the new options.

<Warning>
  When a permission is removed, or when your role is changed, you are signed out for security. Sign back in to continue with your updated access.
</Warning>

## Troubleshooting

### A report page is missing from my menu

If a report does not appear in your navigation, the matching Report permission is almost certainly not enabled on your profile. Each report is gated by its own permission — there is no master toggle that unlocks all of them.

1. Find the report in the breakdown above and note the exact permission name that controls it.
2. Ask a user with the **Set Permission** permission — usually your Admin or Partner Admin — to open **Settings → Organization → Users**, edit your profile, and enable that permission in the **Reports** category.
3. Once it is added your access is live immediately. A banner appears at the top of the screen; select **Refresh** to reload and see the report.

If the permission is already enabled and the page still does not appear, contact Alvys support — something other than permissions is blocking it.

### A report page opens but shows no data

This is not a permissions problem — if you can open the page, your access is working. Empty results normally come from the data source rather than your profile. For IFTA reports specifically, see [Managing and Troubleshooting IFTA Reporting in Alvys](/en/help/accounting-settlements/managing-and-troubleshooting-ifta-reporting-in-alvys) under Go Deeper. For any other report, contact Alvys support.

## FAQs

**Q: What is the difference between the Summary Financial Report and the Detailed Financial Report?**

**A:** The Summary Financial Report provides a high-level overview of revenue and expenses aggregated by asset. The Detailed Financial Report provides invoice-level financial data including revenue, costs, and margins for each load or trip. The Detailed Financial Report is more sensitive and is restricted to fewer roles by default.

**Q: Can I grant Detailed Financial Report access to a Dispatcher?**

**A:** Yes. Dispatcher is not assigned **"View Detailed Financial Report"** by default, but a user with the **"Set Permission"** permission can enable it on an individual dispatcher's profile.

**Q: Do Safety or Driver roles receive any Report permissions by default?**

**A:** No. Neither Safety nor Driver roles are assigned either financial report permission by default.

**Q: Who can modify Report permissions?**

**A:** Any user with the **"Set Permission"** permission enabled on their profile.

**Q: Which Alvys reports require specific permissions to access?**

**A:** All reports in Alvys require the corresponding permission. The full list in the Reports category includes: **"Fuel Report"**, **"Toll Report"**, **"View Summary Financial Report"**, **"View Detailed Financial Report"**, **"View Statement List Report"**, **"View Statement Items Report"**, **"View Asset Safety Report"**, and **"View Driver YTD"**. Each is enabled independently.

**Q: Is there a master permission that unlocks all reporting pages at once?**

**A:** No. Each report permission is independent and must be enabled individually.

**Q: Do I need Billing permissions to view these reports?**

**A:** No. Report permissions in the Reports category are independent of the **"Billing"** permission.

**Q: Why can't I see the Insights menu item in my navigation panel?**

**A:** The Insights menu item is only visible to users with the **"View Insights"** permission. By default, only Admin and Partner Admin roles have this permission.

**Q: A user was just granted new permissions but their Insights results have not changed. What should I do?**

**A:** Ask the user to log out and log back in first. If data still does not appear after 24 hours, contact Alvys support.

## Go Deeper

* [Managing and Troubleshooting IFTA Reporting in Alvys](/en/help/accounting-settlements/managing-and-troubleshooting-ifta-reporting-in-alvys)
* [User Permissions Glossary](/en/help/administration/user-permissions-glossary)
* [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)


# Tendering Permissions
Source: https://docs.alvys.com/en/help/administration/tendering-permissions

Grant the two Tendering permissions that govern EDI 204 and 990 tender board access, accepting or rejecting shipper tenders, and sharing EDI data externally.

👥 **Primary Audience:** **Admins**, **Partner Admins**, **Operation Managers**, **Data Entry**, **Dispatchers**

📁[Return to User Roles & Permissions Collection ](/en/help/administration/user-roles-permissions-collection)

The Tendering Permissions category in Alvys controls access to EDI (Electronic Data Interchange) tendering functionality, the automated process by which shippers send load offers (tenders) to carriers and brokers. Users with these permissions can accept, reject, or update tenders. This category includes **two (2)** permissions that govern who can participate in the tender workflow by viewing and acting on the Tender Board, as well as who can share EDI data externally.

Tendering is a specialized function in freight logistics. Unlike load creation, which is usually done manually, tendering relies on electronic messaging standards, primarily EDI 204 and 990, to exchange load information between trading partners’ systems. Not all Alvys users interact with tenders; this functionality is mainly relevant to users whose companies have active EDI integrations with shippers or other trading partners.

<Warning>
  ⚠️ Tendering functionality requires EDI integrations between your company and your trading partners. If your company does not use EDI, these permissions will have no practical effect even if granted.
</Warning>

### Where to Manage Tendering Permissions

<Warning>
  ⚠️ To modify these permissions, the logged-in user, preferably an administrator, must possess the “Set Permission\*\*”\*\* permission located within the Management category. Without “Set Permission”, a user can view the user profile or form but cannot adjust any permissions. For additional information regarding the “Set Permission\*\*”\*\*, please refer to the [Management & Privacy Permissions article.](/en/help/administration/management-privacy-permissions)
</Warning>

Tendering Permissions are configured at the individual user level within the User Management interface. To adjust these settings:

1. Select your **username** located in the bottom left corner.
2. Navigate to Company Profile and select the **Users** tab.

<Note>
  <img alt="Screenshot showing the Company Profile page with the Users tab selected." />

  *Screenshot showing the Company Profile page with the Users tab selected.*
</Note>

1. Choose an existing user to **Edit** or select the **Add User** button to create a new profile.

   <img alt="Screenshot showing the user list with Edit and Add User options visible." />

   *Screenshot showing the user list with Edit and Add User options visible.*
2. Scroll to the **Permissions** section and locate the **Tendering** category. Identify the two individual checkboxes: **"Participate In Tender"** and **"EDI Share"**.

<Note>
  <img alt="Screenshot showing the Permissions section with the Tendering category expanded, displaying both checkboxes." />

  *Screenshot showing the Permissions section with the Tendering category expanded, displaying both checkboxes.*
</Note>

### Participate In Tender

The **Participate In Tender** permission allows a user to access the [Tender Board page](https://app.alvys.com/#/tenders/board), where they can view, accept, reject, and manage incoming EDI tenders from shippers and trading partners. Without this permission, the Tender Board is not accessible. Responding to inbound tenders requires specialized knowledge, including lane pricing, equipment availability, and the company’s capacity to fulfill the tendered loads. Limiting access to the Tender Board ensures that only qualified personnel handle load offers, protecting the company’s commitments and revenue. For more information on participating in tendering, see the [help center article](/en/help/loads-trips/tenders).

<Note>
  <img alt="Notion Image" />
</Note>

Users with the **"Participate In Tender"** permission can accept or reject tenders, view tender details, and review EDI history. When accepting a tender, each stop must be linked to a company. If the required company does not yet exist in the system, the user can create it inline. This action triggers a company creation permission check: the user must have the **"Create Customer"** permission for brokers or customers, or the **"Create Company"** permission for non-customer entities such as shippers or terminals, depending on the type of company being created.

<Note>
  <img alt="Screenshot of the Tender Board page showing incoming tenders with accept and reject options." />

  *Screenshot of the Tender Board page showing incoming tenders with accept and reject options.*
</Note>

<Warning>
  ⚠️ **EDI integration required:** Inbound tenders come from trading partners via EDI. Without valid and active [EDI integrations](https://app.alvys.com/#/manage/edi-visibility), no tenders will appear on the Tender Board.
</Warning>

**Default role assignments**

By default, this permission is granted to the **Support**, **Partner Admin**, **Admin**, **Operation Manager**, and **Data Entry** roles. It is not assigned by default to the **Dispatcher**, **Biller**, **Sales Agent**, **Office Admin**, **Safety**, or **Driver** roles.

Data Entry is the only non-admin role that receives **"Participate In Tender"** by default. This may seem unusual, but Data Entry users often handle EDI tender intake and load creation from incoming tenders as part of their data processing workflow.

<Info>
  💡 **Best Practice:** Grant the **"Participate In Tender"** permission to users responsible for handling incoming load offers from EDI trading partners, in addition to Data Entry staff. In companies that use EDI tenders extensively, also consider granting this permission to Dispatchers so they can respond to tenders in real time based on available capacity and operational knowledge.
</Info>

For more information on the tendering workflow, see the [Tenders help center article](/en/help/loads-trips/tenders).

### EDI Share

The **"EDI Share"** permission allows a user to share load visibility data externally with EDI trading partners. This includes status updates, tracking information, appointment times, and other operational details. Without this permission, users cannot perform outbound EDI sharing.

Without **"EDI Share"**, teams must manually receive load information from shippers by email, phone, or customer portal and re-enter it into Alvys. For large shippers sending dozens or hundreds of loads weekly, this manual process is slow, error-prone, and unsustainable. Granting **"EDI Share"** automates this step and positions your company as a preferred carrier or broker for shippers who require EDI capability.

<Warning>
  ⚠️ External sharing requires configured EDI integrations with trading partners.
</Warning>

To share an EDI update for a stop:

1. Open an EDI load in the system.
2. On the Load Details page, scroll to the **Trips / Stops** section.
3. Expand a stop and click into an individual stop, either pickup or delivery.
4. The **Share EDI Update** button will appear on the stop card when the stop is in a valid status (**Arrived**, **Picked up**, or **Empty**). The button will only appear if the EDI integration is properly configured to allow updates for that load.

<Note>
  <img alt="Screenshot of an expanded stop card on an EDI load showing the Share EDI Update button." />

  *Screenshot of an expanded stop card on an EDI load showing the Share EDI Update button.*
</Note>

By default, this authorization is conferred upon the **Support**, **Partner Admin**, **Admin**, and **Operation Manager** roles. Conversely, this specific permission is not assigned by default to the **Dispatcher**, **Biller**, **Sales Agent**, **Data Entry**, **Office Admin**, **Safety**, or **Driver** roles.

<Info>
  ✅ **Best Practice:** Grant EDI Share to users responsible for managing EDI relationships and controlling the sharing of load visibility data with trading partners. If your company automates EDI visibility sharing, this permission is typically only needed for manual overrides or to initiate updates in exceptional cases.
</Info>

## Frequently Asked Questions (FAQs)

**Q: Do these permissions work if my company does not use EDI?** A: No. Tendering is entirely EDI-based. Without active EDI integrations with your shippers or trading partners, these permissions will have no functional effect in the system.

**Q: Why does the Data Entry role receive Participate In Tender by default while Dispatchers do not?** A: In many workflows, Data Entry staff are responsible for the initial intake and conversion of EDI tenders into active loads. Dispatchers usually manage the loads after they have been accepted, though they can be granted this permission manually if they need to make capacity-based decisions.

**Q: What specific actions can a user take on the Tender Board?** A: Users with the **Participate In Tender** permission can view tender details, review EDI history, and either accept or reject incoming load offers.

**Q: Does the Tender Board update automatically when a new offer arrives?** A: Yes. The Tender Board uses a real-time connection to the shipper hub. New tenders and updates to existing ones will appear instantly on the board without requiring a page refresh.

**Q: What is the purpose of the EDI Share permission?** A: **EDI Share** allows a user to send outbound status updates to trading partners, such as arrived/departed notifications, appointment confirmations, and location tracking. This automates the visibility process for large shippers.

**Q: Can a user access the Tender Board without the Participate In Tender permission?** A: No. Access to the Tender Board is strictly guarded. Without this permission, the route is blocked, and the user will be unable to navigate to the page.

**Q: Why is EDI Share not assigned to Data Entry by default?** A: Data Entry typically handles the "intake" of loads. **EDI Share** is an operational function used to send updates as a load progresses, a task usually handled by Dispatchers or Operations Managers who monitor real-time shipment status.

**Q: How do I share an EDI update for a specific stop?** A: With the **EDI Share** permission, navigate to the **Trips/Stops** section of an EDI load, expand the specific stop, and click the **Share EDI Update** button. This button only appears if the EDI integration is properly configured for that load.

**Q: Is manual load creation the same as Create Tender?** A: No. Manual load creation is an internal process within Alvys. **Create Tender** sends a formal, electronic EDI 204 message to an external trading partner’s system, creating a legal and operational commitment.

## Next Steps

<Info>
  ⏭️ Proceed to the [Additional Load Permissions article](/en/help/administration/additional-load-permissions) to understand how to manage supplementary permissions that support load creation, pricing, and management. This includes permissions for Load Templates and Load Rate History.
</Info>

## Return to Collection

<Info>
  📁 [Back to User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)
</Info>


# User Permissions Glossary
Source: https://docs.alvys.com/en/help/administration/user-permissions-glossary

A-to-Z glossary of every Alvys user permission with a plain-language definition of what each access right controls, ideal for setup and access audits.

<Note>
  This glossary provides a quick-reference entry for every user permission within Alvys. Use it to look up what any permission does, whether you are setting up a new user or auditing existing access.
</Note>

## Overview

This glossary lists every permission available in Alvys in alphabetical order. Each entry shows the permission name and a plain-language description of what it controls. For step-by-step instructions on assigning permissions, see [How to Add a User in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys). For a breakdown of which roles receive each permission by default, see [User Permissions Breakdown](/en/help/administration/user-roles-permissions-collection).

<Note>
  <img alt="Notion Image" />
</Note>

## A

**"Activate Carrier"**: Ensures that only authorized staff can change a carrier's status (for example, from inactive or pending to active) following onboarding and compliance review.

**"Activate Company"**: Controls whether a user can modify the activation status of non-customer company records, such as Shippers, Warehouses, and other non-customer entity types.

**"Activate Customer"**: Controls whether a user can modify a customer's status, such as activating, placing on hold, or deactivating Customer or Broker/3PL records.

**"Add Accessorials"**: Enables users to create, edit, and manage supplemental charges beyond the base freight rate, such as detention, lumper fees, fuel surcharges, layovers, or TONU.

**"Add User"**: Controls whether a user can create new user accounts in Alvys and assign their initial roles.

**"Apply Contracted Lanes On New Load"**: Enables users to auto-populate pre-negotiated rates during manual load creation by matching the customer and lane details to existing contract agreements.

**"Approve Payable Items"**: Controls the ability to perform write operations inside the Carrier Settlements workflow, including approving payable line items and trips, reversing approvals, and managing disputes.

## B

**"Bid on Marketplace Loads"**: Allows a user to submit a bid or counter-offer on a marketplace load, proposing an alternative rate to the shipper or broker.

**"Billing"**: Serves as the master financial access gate, determining access to financial and invoicing pages, customer payments, factoring records, and financial reports.

**"Book Marketplace Loads"**: Determines whether a user can book (accept) a load from marketplace sources at the listed rate in a single action.

## C

**"Calendar Past Dates"**: Controls whether a user can select past dates in the Add Stop dialog when building a load.

**"Cancel ECheck"**: Controls whether a user can cancel an existing electronic check issued against a load, provided the funds have not yet been cashed.

**"Create Carrier Statement"**: Controls generating carrier payment statements, marking statements as paid, and marking paid statements as unpaid.

**"Create Company"**: Controls whether a user can create new non-customer company records and import shippers into the system.

**"Create Customer"**: Controls whether a user can create new customer records and Broker/3PL records, as well as import customers.

## D

**"DAT User"**: Unlocks the ability to post loads, update rates, and delete postings on the DAT load board directly from the Alvys interface.

**"Delete Asset"**: Controls whether a user can permanently remove asset records (drivers, trucks, trailers) from the system.

**"Delete Carrier"**: Controls whether a user can permanently delete carrier records, including historical load, payment, and compliance data.

**"Delete Company"**: Allows a user to permanently remove a non-customer company record, such as Shippers or Warehouses, from the system.

**"Delete Contracted Lanes"**: Determines whether a user can remove lane rate contracts; deletion is blocked if any loads currently reference the contract.

**"Delete Customer"**: Allows a user to permanently remove a customer record from the system.

**"Delete Notes"**: Controls whether a user can delete notes that they personally created on load records.

**"Delete User"**: Controls whether a user can permanently delete other user accounts from the system.

**"Dispatch"**: Governs identification of an individual as a dispatcher for load assignment, visibility of the "My Trips" dashboard column, and the ability to edit stop leg mileage.

## E

**"EDI Share"**: Allows a user to share load visibility data, such as status updates and tracking information, externally with EDI trading partners.

**"Edit Asset"**: Controls whether a user can modify asset records, including drivers, trucks, and trailers, and manage related data.

**"Edit Carrier"**: Controls whether a user can modify carrier profile information, such as contact details, addresses, and insurance information.

**"Edit Carrier Rate"**: Authorizes users to adjust carrier compensation data within the Carrier Money Box or the Carrier Settlements module.

**"Edit Company"**: Allows a user to modify information on an existing company profile for types such as Shippers, Warehouses, and Terminals.

**"Edit Customer"**: Lets a user modify information on an existing broker or customer profile, including billing addresses and credit limits.

**"Edit Customer Rate"**: Governs the ability to modify financial data within the Customer Money Box, particularly concerning the Customer Linehaul and Fuel Surcharge.

**"Edit Driver Rates"**: Grants authority to modify pay rate configurations within driver profiles, including cents-per-mile, flat rates, and percentage-based structures.

**"Edit Invoice Customer As"**: Controls the dropdown on the Load Details page that designates a different company subsidiary as the billing entity for the customer-facing invoice.

**"Edit Miles"**: Allows a user to manually override automatically calculated mileage recorded on a load or within driver money boxes.

**"Edit Pay Plans"**: Governs the ability to create, modify, and delete driver pay plan templates.

**"Edit Paystubs"**: Governs the ability to modify the content of an existing driver paystub or delete and revert legacy driver pay statements.

**"Edit Tax ID/SSN"**: Controls whether a user can modify Tax Identification Numbers and Social Security Numbers stored on carrier and driver records.

**"Edit Trailer Number"**: Allows a driver to change the trailer number on their assigned load directly within the Alvys mobile app.

**"Edit Trip Value"**: Grants authority to modify the Trip Value fields for driver and owner-operator compensation, including adjustments to base pay and percentage calculations.

**"Edit Webhooks"**: Controls whether a user can create, update, delete, and manage webhook integrations within company subsidiary settings.

## F

**"Fuel Report"**: Governs access to the Fuel Report page, providing visibility into fuel expenditures by driver, vehicle, and location.

## G

**"Generate Invoice"**: Governs invoice-related actions, including generating, regenerating, and submitting invoices, and sending payment reminders.

## I

**"Issue ECheck"**: Governs whether a user can generate electronic checks against loads for carrier or driver road expenses.

## M

**"Manage Load Templates"**: Allows a user to create, edit, and delete load template libraries used for recurring lanes.

**"Modify E-Check Fee"**: Controls whether a user can adjust the e-check fee configuration for subsidiaries and individual driver profiles.

**"Move Comchek"**: Controls whether a user can transfer an existing electronic check from one load to another.

## O

**"Override Carrier Restriction"**: Allows a user to assign a carrier to a load trip even when that carrier's external compliance status is in a restricted state.

**"Override Invoice"**: Grants the ability to modify the Invoice Due Date and Date Invoiced fields on an already invoiced load.

**"Override Stop Status"**: Enables a user to modify a stop's status (for example, transitioning from Covered to Arrived) independently of the standard sequential workflow.

## P

**"Participate In Tender"**: Allows a user to access the Tender Board to view, accept, reject, and manage incoming EDI tenders from trading partners.

**"Pay Driver"**: Governs access to generating driver paystubs and provides visibility into deductions, escrow accounts, and fuel tabs within driver profiles.

**"Pay Owner Operator"**: Governs access to owner-operator payroll processing, specifically the ability to view, generate, and revert paystubs for owner-operators.

**"Post Loads to Marketplace"**: Controls whether a user can make company loads available on external marketplace load boards or remove them.

## R

**"Release Loads"**: Governs the authorization to advance a **Delivered** or **TONU** load into the **Released** status for billing, or reverse that transition.

**"Revert Carrier Statement"**: Controls the ability to undo a generated carrier payment statement and return items to the Drafts pool or Open status.

**"Rollback Transaction"**: Governs whether a user can revert factored loads that have been uploaded to an FTP for factoring or exported to accounting.

## S

**"Set Permission"**: Controls whether a user can modify the specific permissions assigned to other users from the user profile.

## T

**"Toll Report"**: Governs access to the Toll Report page, displaying toll transaction data by driver, vehicle, and route.

**"TruckStop User"**: Controls whether a user can interact with Truckstop-powered features, such as posting loads or updating rates on the Truckstop board.

## U

**"Unlock Loads"**: Allows a user to unlock any load that has been locked by another user to allow for operational continuity.

**"Update/Create Contracted Lanes"**: Enables a user to create new contracted lane rate agreements and modify existing ones on a customer or company profile.

## V

**"View Accidents"**: Enables a user to access the Accidents page within the Safety menu to observe detailed accident reports and related details.

**"View Alvys Rates History"**: Enables access to a market-level perspective of historical rates across all Alvys tenants for specific lanes.

**"View App Paystubs"**: Allows a driver to access and browse their historical pay stubs directly within the Alvys mobile app.

**"View Asset Safety Report"**: Governs access to the report tracking driver certifications, equipment inspections, and lease compliance dates.

**"View Carrier Rate"**: Governs the visibility of the Carrier Money Box on the Load Details page and carrier-related cost columns in the Load Board.

**"View Carrier Rate Confirmation"**: Allows a driver to open and read their own carrier rate confirmation document within the mobile app.

**"View Claims"**: Controls access to the Claims report page within the Safety menu to view insurance and cargo claim records.

**"View Contracted Lanes"**: Determines whether a user can access lane rate agreements on a customer or broker profile.

**"View Customer Rate"**: Governs whether a user can see customer revenue information on a load and associated columns in the Load Board.

**"View Customer Rate Confirmation"**: Allows a driver or carrier to view the customer rate confirmation document via the mobile app.

**"View Detailed Financial Report"**: Governs access to the Detailed Financial Report, providing granular line-item details for truck transactions.

**"View Driver Rates"**: Regulates access to sensitive compensation structures in driver profiles and load-level driver pay methodology.

**"View Driver YTD"**: Governs access to the report summarizing a driver's year-to-date earnings and settlement totals.

**"View Drivers"**: Controls whether a user can see the driver list and individual driver profiles in the Assets menu.

**"View Insights"**: Controls access to the AI-powered Insights chat interface, allowing users to query operational and financial TMS data using plain-English questions.

**"View Maintenance Amounts"**: Controls whether a user can see the dollar amounts and expense totals within the maintenance module.

**"View Maintenance Records & Totals"**: Determines whether users can access the maintenance module to view service records and asset maintenance totals.

**"View Marketplace Loads"**: Grants users the ability to search for and view available loads from the carrier-side marketplace.

**"View Pay Plans"**: Determines whether a user can access the read-only Pay Plans management page.

**"View Payable Amount"**: Allows a driver to see the specific net dollar amount they will be paid for a trip directly in the mobile app.

**"View Paystubs"**: Enables a user to view driver and owner-operator paystub records and settlement details on driver profiles.

**"View PII"**: Controls whether personally identifiable information fields are unmasked within Insights responses.

**"View Roadside Inspections"**: Allows a user to access roadside inspection records, including violations and results, within the Safety menu.

**"View Statement Items Report"**: Controls access to the granular line-item details (loads, charges, deductions) within driver statements.

**"View Statement List Report"**: Governs access to the audit trail of driver statements, showing period totals for mileage, revenue, and earnings.

**"View Summary Financial Report"**: Governs access to high-level financial reports showing revenue and expenses aggregated by asset.

**"View Tax ID/SSN"**: Controls whether a user can see Tax Identification Numbers or Social Security Numbers on carrier and driver records.

**"View Tenant Rates History"**: Gives a user access to the company's own historical rate data for specific lanes.

**"View Trailers"**: Allows a user to see the list of trailers and individual trailer records in the Assets section.

**"View Trip Value"**: Governs visibility of financial figures used for driver and owner-operator settlements on both web and mobile app interfaces.

**"View Trucks"**: Allows a user to see truck records, including equipment specs and maintenance status, in the Assets section.

**"Void Transaction"**: This permission is deprecated; enabling it will have no effect.

## Go Deeper

[How to Add a User in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys): Step-by-step instructions for creating user accounts and assigning permissions.

[User Permissions Breakdown](/en/help/administration/user-roles-permissions-collection): Full default permission matrix organized by role.


# User Roles in Alvys
Source: https://docs.alvys.com/en/help/administration/user-roles-in-alvys

Explains the eleven built-in Alvys user roles, their hierarchy, default permissions, and how role assignment differs from customizing individual user access.

<Note>
  Every Alvys user is assigned exactly one role that defines their default permissions, determines what they can see and do, and establishes their level of authority. Alvys roles are arranged in a strict hierarchy.
</Note>

## Overview

Every user who logs into Alvys is assigned exactly one role (sometimes called a user type or access profile). A role is a predefined profile that determines a user's default set of permissions, including what they can see, what actions they can take, and which other users they can manage. Roles are the foundation of access control in Alvys and establish each user's baseline permissions at the time of account creation.

Roles can be further customized on a per-user basis after the account is created. A role's position in the hierarchy reflects its level of authority and determines which users a given user is permitted to manage.

<img alt="Sample Image displaying roles" />

*The full roles list as it appears in Settings → Organization → Users.*

## Where to Find It

User roles are managed from **Settings → Organization → Users**. Navigate there from the Settings menu. Each user row displays the role currently assigned to that account.

When creating or editing a user, the role is selected from a dropdown list in the user form.

## Key Concepts

### Roles and Permissions: How They Work Together

A role and a permission are two different things. A role is a named profile, such as Dispatcher or Biller, assigned to a user when their account is created. Each role comes with a default set of permissions that reflect the typical responsibilities of that job. A permission is a specific capability, such as **"Generate Invoice"** or **"View Customer Rate"**, that controls a user's access to a particular action or piece of data.

Think of it this way: a role is a job title, and permissions are the keys on that person's keychain. The role determines which keys they start with. Users with the **"Set Permission"** permission can then add or remove individual keys without changing the person's role.

<img alt="Image illustrating individual permission toggles alongside a role assignment." />

*Image illustrating individual permission toggles alongside a role assignment.*

Some permissions control what a user can view (read-only access), while others control what they can do (create, edit, or delete). For example, **"View Customer Rate"** lets a user see the rate charged to a customer, but **"Edit Customer Rate"** is required before they can change it. When in doubt, assign view-only access first and expand from there.

When an admin adds a permission to your account, the change takes effect immediately. You stay signed in, and a banner appears at the top of the screen letting you know your access was updated. Select **Refresh** whenever it is convenient to reload the page and see the new options.

When a permission is removed, or when your role is changed, you are signed out for security. Sign back in to continue with your updated access.

A role is not the same as a permission set. A role provides a user's default permissions at the time of account creation, but those permissions can be individually added or removed at any point afterward. Two users sharing the same role may have different active permissions if their configurations have been customized after role assignment.

### Hierarchy

A role's position in the hierarchy controls who that user can manage — not how much access the role has. Higher-level roles generally have broader default permissions, but not always. The clearest example is Admin and Partner Admin: Admin sits above Partner Admin in the hierarchy, but Partner Admin starts with the broader default permission set. Other roles are built around specific job functions and include specialized permissions regardless of where they sit.

A user's hierarchy position governs their management reach: users can only manage or modify the permissions of users who sit below them in the hierarchy. For example, a Dispatcher cannot modify an Office Admin's account settings or permissions.

## How to Use It

For step-by-step instructions on assigning roles when creating or editing a user account, see [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys).

## Settings & Permissions

### Admin

The Admin role is the highest role available to company users. This role is intended for company owners, directors of operations, and administrators who need near-complete system access.

Admins are responsible for managing the full user lifecycle, including creating, editing, and deactivating users, as well as configuring carriers, customers, and companies. They have the authority to manage load operations end-to-end, access financial reports, configure pay plans, and control team-wide settings and integrations.

<img alt="Screenshot of the Admin role in Settings, Organization, Users." />

*Screenshot of the Admin role in Settings → Organization → Users.*

By default, Admin users are granted comprehensive access, excluding a small set of the most sensitive permissions. These are intentionally withheld to safeguard data, though an Admin maintains full authority to enable them for themselves or others as required.

<Info>
  💡 Best practice: Reserve the Admin role for the fewest people necessary, ideally the company owner and one backup manager. Use the Office Admin or Operation Manager role for day-to-day supervisory work.
</Info>

### Partner Admin

The Partner Admin is a primary administrator role, typically assigned to the owner of the company or general managers. Partner Admin users receive full permissions and operate with nearly the same level of access as Admin, but they rank below Admin in the hierarchy. A Partner Admin cannot promote another user to Admin, because users cannot be assigned a role that sits higher in the hierarchy than their own.

<img alt="Screenshot of the Partner Admin role in Settings, Organization, Users." />

*Screenshot of the Partner Admin role in Settings → Organization → Users.*

### Operation Manager

The Operation Manager role is designed for middle management and senior operations staff who oversee dispatchers, loads, carriers, and customers. It is positioned between Admin and Office Admin in the hierarchy.

This role is the appropriate choice for trusted supervisors such as operations managers, fleet managers, and terminal managers whose primary responsibilities include overseeing daily dispatch and load operations, managing carriers and customers, reviewing financial summaries and reports, and monitoring driver and asset activity.

<img alt="Screenshot of the Operation Manager role in Settings, Organization, Users." />

*Screenshot of the Operation Manager role in Settings → Organization → Users.*

### Office Admin

The Office Admin role is designed for users who coordinate and manage general office procedures and policies. This role's default permissions focus on managing user accounts, companies, assets (trucks, trailers, drivers), load templates, and marketplace access.

Office managers, administrative managers, or back-office coordinators are the intended users for this role.

<img alt="Screenshot of the Office Admin role in Settings, Organization, Users." />

*Screenshot of the Office Admin role in Settings → Organization → Users.*

Primary goals and actions for Office Admin users:

* Maintain carrier and customer records
* Manage rates (customer and carrier)
* Add new users and adjust permissions for lower-level staff
* Work with load templates
* Monitor asset, driver, and safety data
* Access the marketplace to view, book, and bid on loads

Default permissions include: **"Pay Owner Operator"**, all Rate permissions, **"Add User"**, **"Set Permission"**, **"Edit Carrier"**, **"Activate Carrier"**, all Customer and Company Management permissions, **"Edit Asset"**, **"View Load Templates"**, **"Manage Load Templates"**, all Marketplace permissions, all Asset View permissions, all Safety View permissions, **"View Driver Rates"**, and **"Edit Driver Rates"**.

This role does not include access to financial reports, settlement permissions, or the ability to pay drivers. Office Admins can add users and adjust permissions, but only for users at a lower hierarchy level than themselves. They cannot promote another user to Office Admin or any higher role.

### Dispatcher

Dispatcher is the primary load management role. Dispatchers are the operational backbone of freight operations; they create and manage loads, assign carriers and drivers, and coordinate pickups and deliveries.

This role is intended for freight dispatchers, load planners, load coordinators, and driver managers.

<img alt="Screenshot of the Dispatcher role in Settings, Organization, Users." />

*Screenshot of the Dispatcher role in Settings → Organization → Users.*

Primary goals and actions for Dispatcher users:

* Create, assign, and track loads
* Book carriers and manage carrier relationships
* Manage customers and companies
* Override stop statuses when needed
* Use load templates for repeating lanes
* Access the load marketplace
* Monitor drivers, trucks, and trailers
* View accident, claim, and roadside inspection records

Default permissions include: All Rate permissions, **"Add Accessorials"**, **"Edit Miles"**, **"Dispatch"**, all Load Operation permissions, **"Edit Carrier"**, **"Activate Carrier"**, all Customer and Company Management permissions, **"View Load Templates"**, **"View Driver Rates"**, **"Edit Driver Rates"**, all Marketplace permissions, all Asset View permissions, and all Safety View permissions.

Dispatchers do not have access to billing, invoicing, pay stubs, financial reports, or user management. The **"Dispatch"** permission is included in this role by default, but it can also be enabled on other roles such as Sales Agent or Data Entry.

### Biller

The Biller role is designed for users who handle invoicing, settlements, carrier payments, and financial reporting. Billers have the broadest set of financial permissions among non-admin roles.

This role is intended for billing clerks, accounts receivable specialists, accounts payable clerks, payroll specialists, and transportation accountants.

<img alt="Screenshot of the Biller role in Settings, Organization, Users." />

*Screenshot of the Biller role in Settings → Organization → Users.*

Primary goals and actions for Biller users:

* Generate and manage customer invoices
* Process driver and owner-operator payments
* Manage pay stubs and pay plans
* Approve payable items
* Create and manage carrier statements
* Run financial reports (summary, detailed, statement list, statement items, and driver year-to-date)
* Roll back, void, and override transactions when corrections are needed
* Export financial data

Default permissions include: **"Pay Owner Operator"**, **"Add Accessorials"**, **"Billing"**, **"Export"** (integration-gated), **"Edit Miles"**, all Rate permissions, **"Modify E-Check Fee"** (integration-gated), **"Generate Invoice"**, **"Override Invoice"**, **"Rollback Transaction"** (integration-gated), **"Void Transaction"** (integration-gated), **"View Paystubs"**, **"Fuel Report"**, **"Toll Report"**, all Load Operation permissions, **"Edit Carrier"**, **"Activate Carrier"**, all Customer and Company Management permissions, **"Edit Asset"**, **"View Load Templates"**, **"Edit Paystubs"**, **"View Summary Financial Report"**, **"View Detailed Financial Report"**, **"View Statement List Report"**, **"View Statement Items Report"**, **"View Driver YTD"**, **"View Driver Rates"**, **"Edit Driver Rates"**, **"Pay Driver"**, **"Approve Payable Items"**, **"Create Carrier Statement"**, **"Edit Invoice Customer As"**, and all Asset View permissions.

### Sales Agent

The Sales Agent role is designed for users who manage customer and carrier relationships, negotiate rates, and support load booking. Sales Agents have a permission set similar to Dispatchers, with full visibility into customer and carrier rates.

This role is intended for sales agents, freight brokers, logistics sales representatives, account executives, and business development representatives.

<img alt="Screenshot of the Sales Agent role in Settings, Organization, Users." />

*Screenshot of the Sales Agent role in Settings → Organization → Users.*

Primary goals and actions for Sales Agent users:

* Create and manage loads for their accounts
* Book carriers and manage carrier relationships
* Create and manage customers and companies
* Work with load templates for repeating business
* View and edit driver rates

Default permissions include: **"Pay Owner Operator"**, all Rate permissions, **"Edit Miles"**, **"Dispatch"**, all Load Operation permissions, **"Edit Carrier"**, **"Activate Carrier"**, all Customer and Company Management permissions, **"View Load Templates"**, **"View Driver Rates"**, and **"Edit Driver Rates"**.

This role does not include Billing, Invoicing, any financial report permissions, Marketplace access, Safety View permissions, or any payment permissions.

### Data Entry

The Data Entry role is designed for users who create loads, enter shipment data, and handle tender intake. This role has a targeted permission set centered on load creation and basic operations.

This role is intended for data entry clerks, administrative assistants, load builders, and EDI coordinators.

Data Entry is the only non-admin role that includes **"Participate In Tender"** by default, reflecting its use in processing incoming EDI tenders from trading partners.

<img alt="Screenshot of the Data Entry role in Settings, Organization, Users." />

*Screenshot of the Data Entry role in Settings → Organization → Users.*

Primary goals and actions for Data Entry users:

* Enter and maintain carrier, customer, and company records
* Build loads using templates
* Set up and maintain rate records
* Create and participate in tenders

Default permissions include: All Rate permissions, **"Edit Carrier"**, **"Activate Carrier"**, all Customer and Company Management permissions, **"Edit Miles"**, **"Add Accessorials"**, all Load Operation permissions, **"Edit Asset"**, **"Participate In Tender"**, **"View Load Templates"**, **"View Driver Rates"**, **"Edit Driver Rates"**, and all Asset View permissions.

Data Entry users cannot dispatch loads, override stop statuses, access billing, manage users, or view safety and maintenance records. Despite its position in the hierarchy, the Data Entry role has a substantial permission set covering load creation, carrier management, and customer management.

### Safety

The Safety role is designed for compliance and safety personnel who monitor fleet safety, manage assets, and review safety reports. This is a specialized, narrow-access role.

This role is intended for safety managers, DOT compliance officers, fleet safety coordinators, and risk and compliance specialists.

<img alt="Screenshot of the Safety role in Settings, Organization, Users." />

*Screenshot of the Safety role in Settings → Organization → Users.*

Primary goals and actions for Safety users:

* Monitor vehicle maintenance records
* Review accident and claims records
* Track roadside inspection results
* Generate safety and fuel/toll reports
* Maintain driver and asset records from a compliance perspective

Default permissions include: **"Edit Asset"**, **"Calendar Past Dates"**, **"Fuel Report"**, **"Toll Report"**, all Asset View permissions (**"View Drivers"**, **"View Trailers"**, **"View Trucks"**), and all Safety View permissions (**"View Accidents"**, **"View Claims"**, **"View Roadside Inspections"**, **"View Maintenance Records & Totals"**, **"View Maintenance Amounts"**, **"View Asset Safety Report"**).

Safety users have no access to loads, rates, billing, dispatch, marketplace, customer management, or user administration.

### Driver

The Driver role is for company drivers, owner-operators, contractors, and other personnel who use the Alvys Mobile App. This role provides access to the mobile app and carries no desktop permissions.

By default, the Driver role has an empty permission set. Each driver's permissions should be configured explicitly based on their specific responsibilities. For information on mobile app permissions, see [App Permissions](/en/help/administration/app-permissions).

<Warning>
  ⚠️ Do not create drivers through the Add User form. Driver account creation is handled through the driver setup and mobile app verification process. Always follow the proper driver creation workflow.
</Warning>

<img alt="Notion Image" />

<Info>
  💡 Create drivers in the Driver List by entering essential details such as name, address, and mobile phone number. The mobile phone number serves as the unique identifier linking the driver to the Alvys Mobile App. After successful SMS verification, the system automatically creates a user account with the Driver role under **Settings → Organization → Users**.
</Info>

Primary goals and actions for Driver users:

* View and update schedules
* Log trips and manage their driving records
* Update stop statuses on the road via the mobile app
* Submit documents (BOLs, PODs) through the mobile app
* Access pay stubs through the mobile app (if enabled)

Drivers logging into the desktop application will have no access to any module.

## Limits & Behavior

### Role Hierarchy Summary

Admin sits at the top of the hierarchy available to company users, with Partner Admin directly below it; together they provide company-level administrative control. Below those are the operationally focused roles: Operation Manager, Office Admin, Dispatcher, Biller, Sales Agent, and Data Entry. The Safety role provides specialized access for compliance and asset management. The Driver role carries no default permissions and must be explicitly configured. Position in the hierarchy governs management reach only. It does not indicate how many permissions a role receives by default.

A user's position in the hierarchy governs their management reach: users can only manage or modify the permissions of users who sit below them in the hierarchy. For example, a Dispatcher cannot modify an Office Admin's permissions.

<img alt="Screenshot of the full role hierarchy chart as displayed in Alvys." />

*Screenshot of the full role hierarchy chart as displayed in Alvys.*

### Role Changes Reset Permissions

Changing a user's role resets all of their permissions to the new role's defaults. Because a role change can reduce access, it also signs the user out. They will need to sign back in, and their permissions will reflect the new role's defaults.

### What Permissions Don't Control

Not every access limitation in Alvys is controlled by the permissions panel. Some behaviors are determined by role configuration or feature settings rather than individual permission toggles. Common examples include tab and menu visibility for specific roles, the ability for users to edit their own assignment preferences, required fields on carrier onboarding packets, TONU and load-level rate rules, and office-level load sharing.

<Tip>
  If a user's permissions appear correct but they still cannot access a feature or action, see [Overview of User Permissions](/en/help/administration/overview-of-user-permissions) for a full breakdown, and confirm whether the issue is load-state or office-visibility related before adjusting permissions.
</Tip>

### Multi-Factor Authentication (MFA)

MFA setup is managed by each user individually. Admins and Partner Admins can reset MFA for any user from **Settings → Organization → Users** — this clears all enrolled authenticators and prompts the user to re-enroll at next sign-in.

<Warning>
  ⚠️ A Partner Admin cannot reset another Partner Admin's MFA. Those requests must go through Alvys Support.
</Warning>

## FAQs

**Q:** What is the difference between a role and a permission?

**A:** A role is a predefined profile (such as Dispatcher) assigned to a user at account creation that provides a starting set of default permissions and establishes their place in the hierarchy. A permission is an individual toggle for a specific action, such as **"Edit Miles"** or **"View Customer Rate"**.

**Q:** Can a user be assigned more than one role at a time?

**A:** No. Each user account is assigned exactly one role. If a user performs tasks that span multiple roles, assign the role closest to their primary function and then manually enable the specific permissions they need.

**Q:** What happens to a user's customized permissions if I change their role?

**A:** Changing a user's role resets all their permissions to the new role's defaults. Any previously added or removed permissions are overwritten, so any custom access must be reconfigured after the role change is saved. Changing a role also signs the user out; they sign back in with the new role's access.

**Q:** Why does the Admin role not have Delete or Contracted Lanes permissions by default?

**A:** The Admin role does not include the Delete permissions or the Contracted Lanes permissions in its default set. An Admin can enable any of them, for themselves or for another user, from **Settings → Organization → Users**. Note that the Partner Admin role does include these by default — a role's position in the hierarchy does not determine how many permissions it starts with.

**Q:** What is the primary difference between an Office Admin and an Operation Manager?

**A:** The Office Admin role centers on administrative tasks such as adding new users and managing equipment assets. The Operation Manager role is a supervisory role focused on high-level operational oversight such as reviewing financial summaries and monitoring fleet-wide driver activity.

**Q:** What does the hierarchy position control?

**A:** The hierarchy position determines a user's organizational authority. A user can only manage or modify the permissions of users who sit at a lower hierarchy level than themselves. For example, a Dispatcher cannot modify the account of an Office Admin.

**Q:** Can a user with the Safety role see load and rate information?

**A:** No. The Safety role is limited to compliance, maintenance, and inspection data. It is designed to allow safety officers to perform their duties without exposing commercial or financial information.

**Q:** If a user needs to do both dispatching and billing, which role should I choose?

**A:** Choose the role that represents their primary responsibility. If they need broad financial access, assign Biller and then enable the **"Dispatch"** permission toggle so they can also manage loads.

**Q:** Can an Admin reset MFA for another user?

**A:** Yes — with one exception. An Admin or Partner Admin can open the user in **Settings → Organization → Users** and click **Reset MFA**. This clears the user's enrolled authenticators; they will be prompted to set up MFA again at next sign-in. A Partner Admin cannot reset another Partner Admin's MFA — those requests must go through Alvys Support.

## Go Deeper

* [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys)
* [App Permissions](/en/help/administration/app-permissions)
* [Overview of User Permissions](/en/help/administration/overview-of-user-permissions)
* [User Permissions Glossary](/en/help/administration/user-permissions-glossary)
* [User Roles & Permissions Collection](/en/help/administration/user-roles-permissions-collection)

## Next Steps

<Info>
  ⏭️ Proceed to [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys) to understand how to add new users, edit user profiles, assign roles and permissions, and manage user access in Alvys. This includes guidance on keeping user records accurate and ensuring each team member has the appropriate level of access for their responsibilities.
</Info>


# User Roles & Permissions Collection
Source: https://docs.alvys.com/en/help/administration/user-roles-permissions-collection

Index of every Alvys user roles and permissions article, with a recommended order for setting up team access and auditing permission categories.

<Note>
  This collection links to every user roles and permissions article in Alvys. Use it to configure team access, understand what each permission controls, and troubleshoot visibility or action gaps.
</Note>

## Overview

The Alvys permissions system lets administrators control exactly what each user can see and do across every module. Permissions are organized into categories that map to functional areas of the TMS. Each category has its own dedicated article explaining every checkbox, its default role assignment, and the impact of enabling or disabling it.

Follow the recommended order below when setting up a new team member or auditing an existing user's access. Start with financial and operational categories before moving to administrative and specialized ones.

## Where to Find It?

Navigate to **Management** > **Users**, then open a user record. The **Permissions** section lists every available permission grouped by category. Admins and Account Owners can toggle individual permissions on or off to override the defaults set by the user's base role.

## Permissions Overview

Each article below covers one permission category. The Focus description explains what that category governs.

### 1. Rates Permissions

**Focus:** Serves as the primary control for the visibility and modification of financial data across load records and driver profiles. It governs the split between viewing and editing Customer Rates, Carrier Rates, and Trip Values.

**Article:** [Rates Permissions](/en/help/administration/rates-permissions)

### 2. E-Check Permissions

**Focus:** Regulates the issuance, cancellation, and modification of digital payment instruments. These permissions carry significant financial risk as they involve releasing immediate funds for fuel, lumpers, and similar expenses.

**Article:** [E-Check Permissions](/en/help/administration/e-check-permissions)

### 3. Billing Permissions

**Focus:** The most comprehensive financial category in the TMS. It governs the entire lifecycle of revenue and settlements, ranging from generating invoices to approving carrier payables and managing driver pay plans.

**Article:** [Billing Permissions](/en/help/administration/billing-permissions)

### 4. Report Permissions

**Focus:** Determines the visibility of specific report pages in the navigation menu. It allows administrators to restrict access to sensitive analytical data found in Fuel, Toll, Financial, and Asset Safety reports.

**Article:** [Report Permissions](/en/help/administration/report-permissions)

### 5. Dispatch Permissions

**Focus:** Regulates the fundamental operational actions required to maintain freight movement. This includes identifying users as dispatchers, overriding stop statuses, and releasing delivered loads for billing.

**Article:** [Dispatch Permissions](/en/help/administration/dispatch-permissions)

### 6. Management & Privacy Permissions

**Focus:** Constitutes the administrative and data sensitivity framework. It covers user provisioning, asset management, and the protection of PII such as Tax IDs and Social Security Numbers.

**Article:** [Management & Privacy Permissions](/en/help/administration/management-privacy-permissions)

### 7. General Permissions

**Focus:** Controls access to foundational features that span the entire system, such as DAT and TruckStop load board integrations, calendar past-date selection, and the Unlock Loads capability.

**Article:** [General Permissions](/en/help/administration/general-permissions)

### 8. Marketplace Permissions

**Focus:** Governs access to the integrated Carrier Marketplace. It defines exactly what each user can see and do regarding searching for, bidding on, booking, or posting loads.

**Article:** [Marketplace Permissions](/en/help/administration/marketplace-permissions)

### 9. Customer Management Permissions

**Focus:** Specifically governs the lifecycle of entities classified as Customer or Broker/3PL. It manages the creation, modification, and activation of accounts that form the foundation of the revenue cycle.

**Article:** [Customer Management Permissions](/en/help/administration/customer-management-permissions)

### 10. Company Management Permissions

**Focus:** Governs non-customer company types such as Shippers, Warehouses, and Terminals. It allows for a granular separation between users managing customers and those managing pickup locations.

**Article:** [Company Management Permissions](/en/help/administration/company-management-permissions)

### 11. App Permissions

**Focus:** Controls what drivers and carriers can see and do within the Alvys mobile application, such as viewing pay, editing trailer numbers, or viewing rate confirmations.

**Article:** [App Permissions](/en/help/administration/app-permissions)

### 12. Tendering Permissions

**Focus:** Controls access to EDI functionality. Governs who can participate in the Tender Board to accept or reject automated load offers and share EDI updates externally.

**Article:** [Tendering Permissions](/en/help/administration/tendering-permissions)

### 13. Additional Load Permissions

**Focus:** Supporting tools for efficiency and pricing analysis. It covers the management of Load Templates and the ability to view Alvys-wide Market Rates versus your company's private rate history.

**Article:** [Additional Load Permissions](/en/help/administration/additional-load-permissions)

### 14. Contracted Lanes Permissions

**Focus:** Manages pre-negotiated rate agreements for specific routes. It controls who can view, create, or delete standing rate contracts for recurring customer business.

**Article:** [Contracted Lanes Permissions](/en/help/administration/contracted-lanes-permissions)

### 15. User Roles in Alvys

**Focus:** Explains the foundational role hierarchy. It details how the built-in roles (from Support and Admin to Dispatcher and Driver) establish baseline access and govern the organizational authority to manage other users.

**Article:** [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)

### 16. Adding and Managing Users in Alvys

**Focus:** A step-by-step guide to the user lifecycle. It covers creating new accounts, assigning base roles, using granular overrides to fine-tune access, and the proper procedures for deactivating accounts.

**Article:** [Adding and Managing Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys)

### 17. User Permissions Glossary

**Focus:** An A-Z quick-reference guide for every user permission in the system. It defines the specific impact of each permission to help administrators troubleshoot access issues or audit user capabilities.

**Article:** [User Permissions Glossary](/en/help/administration/user-permissions-glossary)

## Settings & Permissions

Only users with the **"Set Permission"** permission (located within the Management category) can modify another user's permissions. Without **"Set Permission"**, a user can view the permissions section on a user detail page but cannot make changes.

Account Owners and Admins have **"Set Permission"** enabled by default. Dispatchers and other base roles do not.

## Limits & Behavior

* Permissions apply at the individual user level and override the defaults set by the user's base role.
* Removing a permission takes effect immediately: the user loses access without needing to log out and back in.
* The **Permissions** section on a user's detail page is read-only for users who do not hold the **"Set Permission"** permission.
* Some permissions are interdependent: enabling a sub-permission without its parent permission may produce no visible effect. Each category article documents these dependencies explicitly.

## FAQs

**Q: Where do I start when setting up permissions for a new employee?**

**A:** Begin by assigning the correct base role (found in the User Roles in Alvys article), then review the Billing, Dispatch, and Rates categories to apply any overrides needed for that employee's specific responsibilities.

**Q: Can a user see their own permissions?**

**A:** Yes. Any user can navigate to their own profile under Management > Users and view their permissions. They cannot change them unless they hold the **"Set Permission"** permission.

**Q: Why does a permission appear enabled but the feature is still not visible?**

**A:** Some features require more than one permission to be active. Check the relevant category article for dependency notes. If all listed permissions are enabled and the feature is still not visible, contact Alvys support with a screenshot of the user's permissions page.

## Go Deeper

* [User Roles in Alvys](/en/help/administration/user-roles-in-alvys)
* [Adding and Managing Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys)
* [User Permissions Glossary](/en/help/administration/user-permissions-glossary)


# Alvys Insights - Getting Started
Source: https://docs.alvys.com/en/help/insights/alvys-insights-getting-started

Find Alvys Intelligence in your TMS, understand what Insights can answer, and check the View Insights permission before you ask your first question.

<Note>
  **Applies to:** Admin · Partner Admin (users with the **"View Insights"** permission for Insights)

  **Module:** Reports & Analytics

  Alvys Intelligence is the built-in analytics layer of your TMS, combining Insights (ask operations questions in plain English and get instant charts and answers from live data) with custom Business Intelligence dashboards and Reports built natively inside Alvys.
</Note>

## Overview

Alvys Intelligence is the embedded analytics and business intelligence capability inside your TMS. It brings two connected tools together so you can understand performance without exporting data or building spreadsheets elsewhere: Insights, a conversational analytics tool where you ask a question in everyday language and get back live answers and charts; and Business Intelligence dashboards and Reports, custom dashboards and reports built natively inside Alvys so your operational, financial, and asset data is visualized in one place. If you signed up for early access to Alvys Intelligence, these features are rolling out to your account now. Early access for the custom dashboards and reports began May 1st.

<Note>
  <img alt="Image displaying Alvys Insights Page" />

  *Image displaying Alvys Insights Page*
</Note>

## Where to find it

**Insights** lives in the main left navigation as the **Al Intelligence** item, which opens the **Insights** chat experience.

<Note>
  <img alt="Image displaying the Insights left navigation menu item." />

  *Image displaying the Insights left navigation menu item.*
</Note>

You can use it as a floating panel in the lower corner of the screen, as a side panel, or full screen. **Reports** lives in the main left navigation under **Reports**. Custom dashboards and reports you and your team build appear there under **Custom Reports**.

<Note>
  <img alt="Image displaying the Custom Reports left navigation menu item and sub reports." />

  *Image displaying the Custom Reports left navigation menu item and sub reports.*
</Note>

## Key concepts

**Insights (conversational analytics).** Type a question the way you would ask a colleague, and Insights answers from your live operational data. Example questions you can try: Revenue by lane; On-time trends; Driver utilization; "What loads are most important today?"; "Which driver has the least miles in the last two weeks?"; "How much revenue has been invoiced this week?" You get charts and written answers back instantly; there is nothing to configure first.

**Business Intelligence dashboards and Reports.** Custom dashboards and reports are built natively inside Alvys. They cover financial, operational, and asset views of your business and update from your live data, so the numbers you see match what is happening in your operation.

## How to use it

Insights and Reports each have dedicated step-by-step guides:

* Using Alvys Insights: [How to Use Alvys Insights](/en/help/insights/how-to-use-alvys-insights)

## Settings and permissions

**Insights** is controlled by the **"View Insights"** permission. A user must have **"View Insights"** granted to open the Insights chat experience; without it, the tool is not available. Insights rolls out to Admins and Partner Admins first. If you hold the **Admin** or **Partner Admin** role, this feature becomes available to you before your broader team. This gives you a chance to get familiar with the tool and share feedback before you grant the **"View Insights"** permission to other team members. Business Intelligence dashboards and Reports are available to users with the **Admin**, **Partner Admin**, or **Support** role, and to other team members once a reporting role (analytic or viewer) is assigned to them. Admins and Partner Admins have reporting access by default.

## Limits and behavior

* Alvys Intelligence is rolling out to early access accounts; if you did not sign up for early access, the features may not yet appear in your account.
* Custom dashboards and reports began rolling out May 1st as part of early access.
* Insights becomes visible to a user only when both the feature is enabled for the account and that user has the **"View Insights"** permission.

## FAQs

**Q: What can I ask Alvys Insights?**

**A:** Ask anything about your live operations in plain English, such as revenue by lane, on-time trends, driver utilization, which driver has the least miles in the last two weeks, or how much revenue has been invoiced this week. You get charts and answers back instantly.

**Q: Who gets Insights first?**

**A:** Admins and Partner Admins get Insights first. This lets you get familiar with the tool and give feedback before you grant the "View Insights" permission to your broader team.

**Q: When did the custom dashboards and reports become available?**

**A:** Custom Business Intelligence dashboards and reports built natively inside Alvys began rolling out for early access on May 1st.

**Q: I signed up for early access but do not see these features yet. What should I do?**

**A:** The features roll out gradually to early access accounts. If you signed up and still do not see Insights or the custom Reports after the rollout window, confirm you have the "View Insights" permission for Insights, or a reporting role for dashboards; if access still does not appear, reach out to Support.

## Go Deeper

* [Using Alvys Insights](/en/help/insights/how-to-use-alvys-insights)


# How to Use Alvys Insights
Source: https://docs.alvys.com/en/help/insights/how-to-use-alvys-insights

Ask operational and financial questions in plain English, read and validate the answers Insights returns, and troubleshoot masked fields or missing data.

<Note>
  **Applies to:** Admin, Partner Admin, Support

  **Module:** Reports & Analytics
</Note>

### Overview

Alvys Insights is an AI-powered chat interface that lets you ask questions about your operational and financial data in plain English. Instead of building reports or navigating dashboards, you type a question and get an instant answer with supporting data tables. People also call it Alvys Insights, the AI assistant, conversational analytics, or simply "ask a question" analytics. Insights respects your account's existing permissions and data security policies, so every user only sees the data they are authorized to access. This is enforced at the data layer, which means the AI cannot bypass or override your account's security policies. Insights is currently in Preview.

<Note>
  <img alt="Insights chat interface overview." />

  *Insights chat interface overview.*
</Note>

### Before You Start

You need the **"ViewInsights"** permission on your account. This permission is granted by default to the Admin, Partner Admin, and Support roles. If you are on another role, an administrator must grant it explicitly under Company Profile then Users. To see sensitive personal data, you also need the **"ViewPII"** permission, also granted by default to the Admin, Partner Admin, and Support roles. If your permissions were changed after you signed in, log out and log back in so a new session is created and the updated permissions take effect.

<Note>
  <img alt="Selecting an agent from the Analyst dropdown." />

  *Selecting an agent from the Analyst dropdown.*
</Note>

### Understanding Responses

When you ask a question, Insights responds with a natural-language summary of the answer along with a **Results** table showing the underlying data.

### Understanding & Validating Results

You can interact with responses and validate what you’re seeing in several ways:

1. **View Details** — Open the full dataset behind a chart/table to review all rows, and copy or download results. (If a dataset is large, the initial visualization may show only top results.)
2. **Copy or download results** — Use the copy/download controls to export the data.
3. **Diagnostics and Explain the Logic** — Ask follow-up questions like “How was this calculated?” or “What logic was used?” to get a plain-English explanation.
4. **Give feedback** — Use the thumbs up/down icons to rate the quality of responses.
5. Choose how the chat window displays. You can view the chat as a **Floating** window, as a **Sidebar**, or in **Fullscreen**. Switch between these display modes using the view controls in the chat window.

<Note>
  <img alt="Validating results with View Details, copy, download, and feedback controls." />

  *Validating results with View Details, copy, download, and feedback controls.*
</Note>

### Result

When you ask a question, Insights responds with a natural-language summary along with a **Results** table showing the underlying data. You can validate and work with what you see: **View Details** opens the full dataset behind a chart or table so you can review all rows, then copy or download the results (if a dataset is large, the initial visualization may show only top results); **Copy or download results** uses the copy and download controls; **Diagnostics and explain the logic** lets you ask follow-up questions such as "How was this calculated?" to get a plain-English explanation; and **Give feedback** uses the thumbs up and thumbs down icons. Your recent conversations are saved in the left sidebar under **Recents**.

<Note>
  <img alt="Sidebar showing “Recents” to access previous search history" />

  *Sidebar showing “Recents” to access previous search history*
</Note>

### Variations

#### Ask clear, specific questions

The more specific your question, the better the response. Examples: "How many loads were delivered last month?"; "What is the total revenue by customer for Q1 2026?"; "Show me all active drivers and their current status"; "What are our top 5 lanes by load count this year?"; "How much did we spend on fuel last quarter?"

#### Follow up and refine

Ask follow-up questions within the same chat to refine or drill into results. After asking about total loads, you might follow up with "Break that down by customer" or "Show me only the ones from Texas."

#### Understand how permissions shape your results

Permissions are evaluated at the group level, not field by field. If you have at least one relevant permission within a permission group, the data in that category becomes visible. If you do not have any permissions in a particular group, those fields appear masked. Insights uses a two-tier system: for most operational data fields (addresses, financial amounts, driver pay, vehicle information, employee IDs) you need at least one matching permission from the relevant permission group; for highly sensitive personal data (names, email addresses, phone numbers, dates of birth, driver license numbers, insurance details, geolocation) you need both the **"ViewPII"** permission and at least one permission from the relevant group. If you have the domain permission but not **"ViewPII"**, these fields stay masked.

<Note>
  <img alt="View Insights permission setting." />

  *View Insights permission setting.*
</Note>

#### Keep AI accuracy in mind

Insights is powered by AI, which can occasionally make mistakes. Always double-check critical data points against your Alvys reports. A disclaimer at the bottom of the chat reminds you: "AI can make mistakes, so double-check it."

### Troubleshooting

#### Some fields appear masked or hidden in results

When you lack the required permissions, sensitive fields are automatically masked.

1. Identify which category is masked. Financial amounts (invoice totals, rates, pay) require at least one financial permission such as Billing, Invoice, View Customer Rate, or View Driver Rates. Personal contact info (email, phone, name) requires **"ViewPII"** plus a relevant domain permission. Vehicle identifiers (VIN, license plates) require asset permissions such as View Trucks, View Trailers, or Edit Asset.
2. Ask your administrator to review your permissions under Company Profile then Users.

#### Insights says data is not available even though it exists in the application

This happens when your permissions restrict access to that data. In some cases, sensitive fields are not just masked but fully hidden, so Insights treats them as unavailable.

1. Confirm with your administrator that you hold the required permission group for that data.
2. If the data is personal data, confirm you also have the **"ViewPII"** permission.

#### A recent permission change has not taken effect

1. Log out of Alvys.
2. Log back in so a new session is created and the updated permissions are applied.

<Note>
  <img alt="Permissions settings in user profile" />

  *Permissions settings in user profile*
</Note>

<Note>
  ℹ️ **Note:** The View PII permission is enabled by default for the following roles: Admin and Partner Admin Roles. Other users need to have it explicitly granted by an administrator.
</Note>

<Warning>
  ⚠️ **Important:** If a user’s permissions are changed **after their current session was created**, the new access may not apply immediately in Insights. In that case, the user should **log out and log in again** so a new session is created and the updated permissions can be applied.
</Warning>

### What Gets Masked

When you lack the required permissions, sensitive fields are automatically masked in Insights responses. Instead of seeing actual values, you'll see placeholder or redacted content. This ensures that even if the AI references a data field in its response, you will never see data you are not authorized to view.

Examples of data categories and what controls them:

1. **Financial amounts** (invoice totals, rates, pay amounts) — Requires at least one financial permission such as Billing, Invoice, View Customer Rate, View Driver Rates, or similar
2. **Personal contact info** (email, phone, name) — Requires View PII plus a relevant domain permission
3. **Vehicle identifiers** (VIN, license plates) — Requires asset-related permissions like View Trucks, View Trailers, or Edit Asset

<Note>
  ℹ️ **Tip:** If you're seeing masked data in your Insights responses and believe you should have access, contact your administrator to review your user permissions under Company Profile > Users.
</Note>

## Tips for Getting the Best Results

### Ask Clear, Specific Questions

The more specific your question, the better the response. Here are some example questions you might ask:

1. "How many loads were delivered last month?"
2. "What is the total revenue by customer for Q1 2026?"
3. "Show me all active drivers and their current status"
4. "What are our top 5 lanes by load count this year?"
5. "How much did we spend on fuel last quarter?"

### Follow Up and Refine

You can ask follow-up questions within the same chat to refine or drill into results. For example, after asking about total loads, you might follow up with "Break that down by customer" or "Show me only the ones from Texas."

### AI Disclaimer

Insights is powered by AI, which can occasionally make mistakes. Always double-check critical data points against your Alvys reports. A disclaimer at the bottom of the chat reminds you: "AI can make mistakes, so double-check it."

If you don’t have access to a data category or field, the corresponding values may appear masked or missing in results.

## FAQs

**Q: Why am I seeing masked or hidden data in my results?**

A: Your Alvys permissions determine what data you can see. If certain fields appear masked, it means your account does not have the required permissions for that data category. Contact your administrator to review your permissions.

**Q: Can the AI access data that I don't have permission to view?**

A: No. Permissions are enforced at the data layer in Snowflake, not by the AI itself. The AI can only query and return data that your permissions allow. It is technically impossible for the AI to bypass these controls.

**Q: What types of questions can I ask?**

A: You can ask about any data within your Alvys account that you have permissions to access, including loads, trips, drivers, financial data, assets, carriers, maintenance records, safety information, and more.

**Q: Is my chat history saved?**

A: Yes. Your recent conversations appear in the Recents section of the sidebar. You can revisit past conversations at any time.

**Q: Who has access to Insights?**

A: Any user with an Alvys account can access Insights. However, the data each user can see is governed by their individual permissions and role.

**Q: What does the "Auto" mode toggle do?**

A: The Auto mode setting controls how the AI processes your questions. In Auto mode, the system automatically selects the best approach for answering your question.

**Q: Why does Insights say data is not available, even though I know it exists in the application?**

A: This happens when your permissions restrict access to that data. In some cases, sensitive fields are not just masked but fully hidden, so Insights treats them as unavailable. Please check with your administrator to ensure you have the required permissions.


# Alvys API
Source: https://docs.alvys.com/en/help/integrations/alvys-api

Overview of the Alvys Public REST API: where to generate client credentials and API tokens, required roles, and links to developer documentation.

<Note>
  The Alvys Public API lets your company connect outside tools to your Alvys data using API credentials and an API token. This overview explains what the Public API is, where to generate your credentials, and where to find full developer documentation.
</Note>

## Overview

The Alvys Public API (Alvys API, Public API, REST API) is a programmatic way to connect external tools and systems to the data in your Alvys account. Instead of working only inside the Alvys platform, you can use the Public API to retrieve your operational data from another application, such as a reporting or business intelligence tool. Access to the Public API is controlled by API credentials and an API token that you generate inside Alvys, so every connection is tied to your company and authenticated on each request. Full technical reference material, including endpoints and setup guides, lives in the Alvys developer documentation: [https://docs.alvys.com/](https://docs.alvys.com/)

## Where to Find It

You generate and manage your Alvys Public API credentials inside the Alvys platform under Profile > API. This is the page where you create the client applications, API keys, and tokens that authenticate an outside tool to your Alvys data. Opening the API page requires the **"Admin"** or **"Partner Admin"** role.

## Key Concepts

API credentials identify a connection between an outside tool and your Alvys account. When you create a client application on the Profile > API page, Alvys issues the credentials that the outside tool uses to identify itself. An API token authenticates each request that an outside tool sends to the Alvys Public API. The token is what proves a request is allowed, so the connecting tool includes it on every call. Client applications can be created, listed, updated, and deleted from the API page, so you can review existing connections and remove ones you no longer need.

## How to Use It

1. Sign in to Alvys with the **"Admin"** or **"Partner Admin"** role.
2. Go to Profile > API to open the Public API page.
3. Create a client application to generate the API credentials for the tool you want to connect.
4. Generate an API token to authenticate the connection's requests.
5. Use the Alvys developer documentation at [https://docs.alvys.com/](https://docs.alvys.com/) for endpoint details and setup instructions for your specific tool.

## Troubleshooting

If a connection that previously worked stops responding, check whether its client application has expired. A client application can be set to expire on a date you choose, and expired client applications are deactivated automatically, so you will need to issue new credentials to restore the connection. If you cannot update an older client application from the current API page, it was created under the legacy credential format; create a new client application instead. If you cannot open the Profile > API page at all, confirm your account has the **"Admin"** or **"Partner Admin"** role, since users without one of these roles cannot view or manage credentials.

## Settings and Permissions

Generating and managing Alvys Public API credentials requires the **"Admin"** or **"Partner Admin"** role. Users without one of these roles cannot open the Profile > API page or create, view, update, or delete client applications. Because the same page controls all credential actions, granting a user the ability to create credentials also lets that user view, update, and remove existing client applications.

## Limits and Behavior

A client application can be set to expire on a date you choose when you create or update it. Expired client applications are deactivated automatically, so a connection that relied on expired credentials stops working until you issue new ones. Legacy client applications created under the older credential format cannot be updated from the current API page; create a new client application instead.

## FAQs

**Q: Where do I generate my Alvys API credentials?**

**A:** Generate them inside the Alvys platform under Profile > API. You need the **"Admin"** or **"Partner Admin"** role to open that page.

**Q: Where can I find the full Alvys API documentation?**

**A:** The Alvys developer documentation is available at [https://docs.alvys.com/](https://docs.alvys.com/).


# Alvys Carrier Marketplace
Source: https://docs.alvys.com/en/help/integrations/alvys-carrier-marketplace

Search, book, and bid on loads inside the Alvys Carrier Marketplace using Uber Freight, DAT, and Truckstop data with unified filters and bid tracking.

## Overview

The Alvys Marketplace module is a powerful tool designed for carriers to efficiently search for and secure loads, helping to optimize routes, reduce deadhead miles, and manage spot freight. It integrates with multiple load providers to offer a comprehensive view of available freight. This centralized platform allows you to:

* 🚚 **Connect to External Integrations** Search across our data partners, Uber Freight, DAT & Truckstop.
* 🔍 **Complete Robust Searches** Narrow your search parameters, and sort and filter results to quickly find the loads that meet your needs.
* 🖐️ **Bid on and Book Loads** Submit offers and counter offers on DAT loads that are configured as negotiable, and book loads instantly from Uber Freight.
* 📋 **Manage Your Bids** Review bids you've submitted and convert awarded bids into loads within Alvys.

## Permissions

* **(General) View Marketplace Loads** — View the module and complete searches.
* **(General) Book Marketplace Loads** — Bid and book search results.

Follow the guides below for detailed instructions on configuring integrations, searching for loads, and submitting bids and bookings through Alvys.

## Configuring integrations

To begin using the Alvys Carrier Marketplace, you must first configure your integrations with our supported load providers: Uber Freight, DAT, and Truckstop. Each provider has specific prerequisites and setup instructions to ensure seamless access to their load offerings within Alvys.

### Uber Freight integration

To use Uber Freight within the Marketplace, Alvys Support can assist with a basic eligibility confirmation. This process can result in you being provided with an account and access to their load search.

**Step 1: Set up Uber Freight as a customer**

1. From the navigation bar, click **Companies**.
2. Select **Add New Company**.
3. In the **Company Name** field, enter **UberFreight LLC**.
4. Ensure that Uber Freight is correctly categorized as a **Broker/3PL**.
5. Enter this address in the company profile: 433 W Van Buren St, 9th Floor, Chicago, IL, 60607, USA.
6. Include their MC#: 987790.
7. Complete all required details.

<Tip>
  If you are **not already working with Uber Freight**, reach out to your Success Manager to get started.
</Tip>

**Step 2: Coordinate with your Implementation Manager or the Success team ([customersuccess@alvys.com](mailto:customersuccess@alvys.com))**

To complete the Uber Freight integration, reach out to your **Implementation Manager (IM)** to schedule a setup session.

1. **Email your IM** to book a time to integrate and get started.
2. Have your **Uber Freight credentials** ready, including your **group email login** (for example, [dispatch@yourcompanyname.com](mailto:dispatch@yourcompanyname.com)).

<Warning>
  **Important Uber Freight integration information**

  You must ensure that the address used to configure the integration is a **group/dispatch email**, as all communication on a load will go through it. Individual Uber Freight credentials cannot be used.
</Warning>

If you have any questions regarding Uber Freight, contact [Freight-carrier@uber.com](mailto:Freight-carrier@uber.com). You can also check your existing eligibility by logging in to the web portal at [uberfreight.com](https://www.uberfreight.com/): click **Login** in the top right corner, select **Uber Freight Carrier Login**, and enter your email address.

Once the integration is complete, Uber Freight loads will be available in your **Marketplace** tab, allowing you to book loads directly within Alvys.

### DAT integration

To integrate with DAT, you must have a license and a service account that provides API access.

**Step 1: Navigate to Marketplace integration settings**

1. Go to the **Management** page.
2. Click the **Integrations** tab.
3. Under **Marketplace**, locate DAT.

**Step 2: Enter your DAT credentials**

1. Input your **Service Account credentials** in the provided fields.
2. Click **Save** to enable the integration(s).
3. Once approved, your DAT account is connected and you are ready to start using the Marketplace.

<Warning>
  **Important DAT credential information**

  A **Partner Admin** must set up the DAT integration using **Service Account** credentials. Once the Service Account has been added, users are able to add their personal credentials from within the Marketplace.
</Warning>

<img alt="Notion Image" />

### Truckstop integration

The Truckstop integration also requires API access.

**Step 1: Obtain a Truckstop Integration ID**

Truckstop requires an **Integration ID** to connect with Alvys. Contact Truckstop at [TSI@truckstop.com](mailto:TSI@truckstop.com) to request your **Integration ID**. For additional details, see the [Truckstop developer overview](https://developer.truckstop.com/reference/general-overview).

**Step 2: Enable and configure the Truckstop integration**

1. Go to the **Management** page.
2. Click the **Integrations** tab.
3. Under **Marketplace**, enable the **Truckstop** integration.
4. Enter the **Integration ID** in the Truckstop section of your **Marketplace Integrations**.

<img alt="Notion Image" />

5. Click **Save** to enable the connection.
6. Once configured, the **Truckstop chip status** in the **Marketplace** will glow green, indicating a successful integration.

<img alt="Notion Image" />

<Warning>
  **Truckstop does not support API-based bidding or booking.** Loads will appear in search results without digital booking options. However, users can access **contact details** (email and phone number) for each load.
</Warning>

### FAQ

**Q: What if I don't have a Load Board license for DAT?**

**A:** A Load Board license and a service account with API access are prerequisites for using DAT within Alvys Marketplace. You will need to acquire these directly from DAT before configuring the integration in Alvys.

**Q: Can I use the Marketplace without configuring any integrations?**

**A:** No. You must configure at least one load provider integration (Uber Freight, DAT, or Truckstop) to access and use the load search and other functionality within the Alvys Carrier Marketplace.

## Searching for loads

Once your load provider integrations are configured, you can access the Marketplace module to search for loads. Alvys offers a variety of parameters and filters to refine your search, ensuring you can quickly locate loads that meet your specific requirements. You can also customize the display of search results for a personalized viewing experience.

### Step-by-step instructions

**1. Access the Marketplace module**

Navigate to the **Marketplace** module within Alvys from the navigation bar on the left.

**2. Enter search parameters**

You can search for loads using a variety of parameters:

* **Origin:** Enter the origin of the load. Alvys treats the selected origin as a single point or a precise address.
* **Destination:** Enter the destination of the load. Alvys treats the selected destination as a single point or a precise address.
* **Mileage Radii:** Set mileage radii for both the origin and destination to broaden your search area.

Refine your search further by applying filters like:

* **Equipment Type:** Filter by expected equipment types (*Van*, *Reefer*, *Flatbed*, *Specialized*, or *Other*). These are standardized across all our data providers.
* **Load Type:** Filter your search by the type of load:
  * **Bookable:** Loads that can be booked immediately from within Alvys.
  * **Negotiable:** Loads that you can place a bid on from within Alvys.
  * **Other:** For these loads, your main course of action is to review the details on the search result and contact the poster via email or phone.

**3. View search results**

After initiating your search, you can page through the results and view all relevant metadata about each load. Information displayed includes:

* Load source (for example, Truckstop, DAT, Uber Freight)
* Customer
* Advertised rate on the trip
* And more

**4. View load details**

Click into each search result to see all detailed information about the load itself. This includes:

* Other stops along the way
* Provided contact information
* Any notes attached to that load

**5. Configure optional columns**

You can customize the search results table by configuring additional optional columns.

* **DAT-specific columns:** For DAT loads, you can pull in whether the loads are factorable, assurable, or quick-payable.
* **Customize display:** You can resize columns and turn them on or off to customize the look and feel of the search results to your needs.

### FAQ

**Q: Can I save my search filters for future use?**

**A:** The current version of the Alvys Carrier Marketplace does not support saving search filters. You will need to re-enter your desired parameters for each new search.

**Q: Why are some load details missing, such as contact information?**

**A:** The availability of detailed information like contact information depends on the data provider and the specific load. For "Other" load types, you may need to click into the details and contact the poster directly outside of Alvys.

## Bidding and booking loads

The Alvys Carrier Marketplace offers different calls to action for loads depending on the integrated provider. You can instantly book loads, bid on them, or retrieve contact information to negotiate offline. Understanding these distinctions is crucial for efficient load acquisition.

### Step-by-step instructions

**1. Identify the call to action**

On the far right of any search result, you will see a call to action if one is available. The available actions differ across our data providers.

**2. Booking Uber Freight loads**

Uber Freight loads can be booked instantly.

1. **Click "Book Now"** when you see this option for an Uber Freight load. The load is booked at the advertised rate.
2. **Customer creation:** Alvys treats Uber Freight itself as the customer. Ensure "Uber Freight" exists as a customer in your Alvys instance. These loads will always show "Uber Freight" as the customer.
3. **Instant load creation:** The load is created instantaneously in your Alvys system and appears on your tenant's load board for further management.

<Warning>
  **Uber Freight cancellation policy**

  If you need to cancel a load booked with Uber Freight, email fleet support at [fleet-support-uf@uber.com](mailto:fleet-support-uf@uber.com) to officially cancel the load.
</Warning>

**3. Acting on DAT loads**

DAT loads offer several call to action options:

* **Book Now:** Available when the load is configured as "bookable." Booking is subject to confirmation by the provider.
* **Bid Now:** Available when the load is configured as "negotiable," allowing you to submit bids or counter offers.
* If a load does not offer an immediate action, you may need to contact the customer offline. Alvys surfaces the relevant contact information so you can reach out to the provider for more details.

When a bid is awarded, you can convert it into a load in Alvys — either by associating it with an existing customer or by creating a new customer record if needed.

**4. Acting on Truckstop loads**

Currently, Truckstop loads do not support bidding or booking directly through Alvys.

* Truckstop loads appear in search results but **do not support direct API-based booking or bidding**.
* Contact information (email and phone number) is provided for each load so you can **reach out directly** to negotiate and secure the load. Email addresses and phone numbers are hyperlinked to streamline next steps.

<Tip>
  If you search a date range greater than 7 days, only the first 7 days of Truckstop results are returned.
</Tip>

**5. Manage your bids**

When you have submitted bids or booking requests to DAT, manage ongoing negotiations in the **Bids** tab. Filter bids by status and use the available calls to action — such as **Create Load**, **Bid Sent**, and **View Offer**. Once a booking that requires confirmation is accepted, you can convert it to a load via the standard Alvys process to build a load.

### FAQ

**Q: Why can't I bid on or book all loads in the Marketplace?**

**A:** The ability to bid or book directly through Alvys depends on the integration capabilities of each load provider. For example, Truckstop currently requires offline negotiation, while Uber Freight and some DAT loads support instant booking or bidding.

**Q: What should I do if a load has no "call to action" button?**

**A:** If a load has no direct call to action button (like "Book Instantly" or "Bid"), click into the load details to find the poster's contact information (email or phone) and initiate contact outside of the Alvys platform to inquire about the load.


# Alvys Internal Marketplace
Source: https://docs.alvys.com/en/help/integrations/alvys-internal-marketplace

Post loads as a broker, search and bid as a carrier, and close the deal with a digital rate confirmation inside the Alvys-to-Alvys internal marketplace.

<Note>
  📋 **Applies to:** Admin · Partner Admin · Carrier · Broker

  **Module:** Marketplace
</Note>

## Overview

Alvys Brokers, Carriers, and Shippers can now connect seamlessly in the Alvys Marketplace. Carriers can discover, bid, and negotiate quality freight, while Brokers can tap into the Alvys carrier network to cover loads faster and with confidence.

## Configuring the Alvys Marketplace Integration (Optional)

During the Beta, the Alvys integration card is automatically enabled and no set up is required. You can find the integration settings by navigating to User Profile > Integrations > Marketplace > Alvys.

<Note>
  <img alt="Notion Image" />
</Note>

Brokers can provide a default email address for bid notifications (we will not send notifications if the field is left empty). Carriers will automatically get notifications if their bids are accepted or rejected (we will email the user that submitted the bid).

<Note>
  <img alt="Notion Image" />
</Note>

The "Auto-sync posted loads to Alvys marketplace" is enabled by default for all Brokers, which means your open loads will be available in search results for Alvys Carriers participating in the beta.

<Tip>
  💡 Please note that sensitive information (stop addresses, customer information, etc.) is ***not*** shared with Carriers until you accept their bid and generate a digitally signed rate con (see below).
</Tip>

The "Terms of Service" are also linked and available for review in the integration card.

## Searching for Loads and Submitting Bids (For Carriers)

Navigate to the "Marketplace" section from the main menu.

<Note>
  <img alt="Notion Image" />
</Note>

* Use the search bar to find loads. You are required to provide an origin and a range of dates. You can also provide a destination to narrow results.
* The search results will display loads from enabled data partners (DAT, Uber Freight, Truckstop, or Alvys), indicated in the "Source" column.
* Click on any load in the search results to view more details. This includes stops along the way, advertised rates, and any comments or contact information.
* For loads with multiple pickups, the total miles for the trip and empty miles will be displayed.
* To submit a bid, click "Submit Bid" for the desired load.
  <Note>
    <img alt="Notion Image" />
  </Note>
* In the "Submit Bid" modal, you can enter your "All-in Rate." The modal may also show historical data from the past 30 days for rates applied on that specific lane to help you make an informed bid. Once submitted, you will see confirmation, and a pointer to navigate to the “Bids” tab of the Marketplace, where you can manage negotiations.
* Once a bid is submitted, the load will be cleared from your search results, and an indication with the UID of your submitted bid will appear.
* Navigate to the Bids tab to see your bids and their current status (e.g., "Bid Submitted"). The Call to Action section will confirm your bid has been sent.

<Note>
  <img alt="Notion Image" />
</Note>

The bid status can be in various states, including "Bid Rejected" or "Bid Accepted." If a bid is accepted, you can proceed to create a booking. We will automatically send you email notifications as bid status changes.

<Tip>
  💡 If a broker edits stops or equipment requirements, bids will be automatically rejected (given key information driving interest in the load may have changed). In this case, carriers will be able to re-submit bids if still interested
</Tip>

When awarded, you will receive email confirmation with a link to the load details in Alvys. The bid will appear as `Completed` in the Marketplace Bids tab, with an action to view the Load. Carrier will also receive a carrier packet via email if they have not previously done business with the associated broker.

<Note>
  <img alt="Email confirmation" />

  *Email confirmation*

  <img alt="Notion Image" />
</Note>

Within the load, you can view related documents which will include a digital Rate Confirmation document with all relevant details pertaining to the load, its rates, customers, locations and more.

<Tip>
  💡 A digital rate confirmation will include a programmatic signature with the username and timestamp of the individual who submitted the bid.
</Tip>

<Note>
  <img alt="Notion Image" />
</Note>

## Posting Loads to Marketplace (For Brokers)

<Tip>
  💡 In the beta experience, auto sync of loads is enabled by default. Created loads will automatically be posted to the Marketplace.
</Tip>

For open loads without a carrier assigned, you will see a new “Marketplace” tab in the Load Details Page.

<Note>
  <img alt="Notion Image" />
</Note>

Navigating to this tab will display the status of the load in Marketplace as well as any received bids. You will also have the option to manually post a load if auto-sync is disabled or if we failed to auto-sync due to issues with the load (e.g., pick up dates in the past). Simply double check all information and click “Post.”

Once posted, you can monitor the status of the post and respond to bids!

### Editing a Posted Load

<Note>
  <img alt="Notion Image" />
</Note>

To avoid miscommunication with carriers, editing certain information on the load will automatically unpost a load and require all interested carriers to resubmit bids:

* Tender As
* Assign a carrier that did not submit a Marketplace bid
* Edit stop info (add/remove, change sequence, adjust dates/times, etc)
* Change equipment type

### Working with Bids

As bids come in, manage them in the same portion of the Load Details page, taking actions on bids like editing the Carrier Details, emailing the point of contact, or assigning the load:

<Note>
  <img alt="Notion Image" />
</Note>

If you’ve not done business with the prospective carrier in the past, email them to distribute the Carrier Packet and establish an agreement

<Note>
  <img alt="Notion Image" />
</Note>

Accept the bid in order to update the Carrier on the load — and generate an email notification and status update to the awarded Carrier. This also generates a digital Rate Confirmation as a document on the load.

<Warning>
  ⚠️ Assigning the carrier auto generates the digital rate confirmation, as discussed above, applying the user name of the individual assigning the asset. At the time of assignment, all other interested carriers will receive a bid rejection notification via email.
</Warning>

## New and improved Rate Analytics

The Alvys **Rate Analytics**module provides essential tools to research and inform better bids for compelling charges to serve particular lanes, or consider bids from carriers.

<Note>
  <img alt="Notion Image" />
</Note>

### Accessing the Rate Analytics Module

You can access the Rate Analytics module in two ways:

From the Marketplace (When Submitting a Bid)

1. Navigate to the **Marketplace** in Alvys.
2. Select a load you are interested in bidding on.
3. Initiate the bid submission process.
4. The Rate Analytics module will be integrated into the bid submission screen to help you create a compelling offer.
   **As a Standalone Module**
5. From the Alvys navigation bar, click on **Loads and Trips**.
6. From the dropdown menu, select **Rate Analytics**.

### Using the Rate Analytics Module

Once you access the Rate Analytics module, follow these steps to conduct your research:

1. **Enter Origin and Destination:**
   * In the **Origin** field, type the starting location for the lane you are researching. This field is required.
   * In the **Destination** field, type the ending location for the lane you are researching. This field is required.
2. **Specify Mileage Radii (Optional):**
   * To broaden or narrow your search, you can enter a mileage radius for both the origin and destination. This allows Alvys to include data from areas surrounding your specified locations.
3. **Select Equipment Types (Optional):**
   * Choose the relevant **Equipment types** from the dropdown menu to filter the rate data by specific vehicle types. This helps you get more precise analytics for the equipment you plan to use.

### Understanding Rate Trends

After you enter your search criteria, Alvys will display comprehensive rate trends. These trends provide valuable insights into both your historical performance and the broader market:

* **Customer and Carrier Rate Trends:** Alvys shows you what you have been charging (customer rates) or paying (carrier rates) for similar lanes. It also presents what we observe in the market. Rate data is aggregated and anonymized in accordance with Alvys [Terms & Conditions](https://alvys.com/terms) and [Privacy Policy](https://alvys.com/privacy).
* **Timeframes:** Rate trends are displayed for the last **5, 15, and 30 days**. This allows you to identify short-term and medium-term fluctuations in market rates.

By leveraging these insights, you can make more informed decisions and create more competitive bids.


# Alvys Payment Synchronization for Accounting Integrations
Source: https://docs.alvys.com/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations

How Alvys syncs customer and vendor payments with NetSuite, QuickBooks Online, QuickBooks Desktop, and Business Central to avoid manual re-entry.

<Note>
  Alvys automatically synchronizes customer and vendor payments (payment sync, payment export, payment import, accounting integration) between Alvys and your connected accounting system (NetSuite, QuickBooks Online, QuickBooks Desktop, or Business Central).
</Note>

## Overview

Alvys supports automated payment synchronization with NetSuite, QuickBooks Online (QBO), QuickBooks Desktop (QBD), and Business Central. Payment synchronization ensures that customer and vendor payments are accurately reflected between Alvys and your accounting system without manual re-entry. Related terms: payment sync, payment export, payment import, accounting integration, invoice reconciliation.

Payment synchronization covers two flows:

* Customer payment export: Alvys sends customer payments to the external accounting system.
* Customer and vendor payment import: The accounting system sends payment status back into Alvys.

Synchronization runs on an automated schedule. No manual trigger is required from the Alvys interface.

## Customer Payment Export

Customer payments are exported only when the **Export Customer Payments** setting is enabled during the subsidiary's integration configuration. Once this option is selected, a deposit account must also be configured. Payments represent funds received toward an invoice, but they do not always reach the bank individually. A deposit or clearing account can be used to temporarily hold incoming funds until they are grouped and deposited.

<Warning>
  ⚠️ Payments should never be posted directly to bank accounts, income accounts, accounts receivable, or liability accounts. Doing so can result in duplicate deposits, overstated revenue, and inaccurate balances. A recommended deposit account is a clearing account (for example, an "Undeposited Funds" type account), though other deposit account types can also be used.
</Warning>

In Alvys, customer payments can be recorded manually against a load or uploaded via a factoring report. Full payments that qualify for export are synchronized to the external accounting system every five (5) minutes.

<Info>
  💡 Only full payments applied directly to individual loads or uploaded via a factoring report are eligible for export. Partial payments and any payments associated with summary invoices are not supported and will not be exported.
</Info>

<Warning>
  ⚠️ Customer payment export is **not supported** for QuickBooks Desktop or Business Central. This limitation applies regardless of how the integration is configured.
</Warning>

## Customer Payment Import

Customer payment import is supported only for invoices that were exported from individual loads or batch invoicing (Invoicing page) in Alvys. When a payment is recorded in the external accounting system against a qualifying invoice, that payment is imported back into Alvys every 12 hours.

Payments applied in the external accounting system to invoices that were originally generated from the Summary Invoice page in Alvys are not supported for import.

<Info>
  💡 If you have recorded payments in QuickBooks Desktop but do not see them reflected in Alvys, confirm that your Web Connector is active. Payment synchronization for QuickBooks Desktop only occurs when the Web Connector runs and pulls data into your local environment.
</Info>

## Vendor Payment Import

Vendor payment synchronization is one-way: only full payments applied in the accounting system to bills that were originally created from Alvys are imported back into Alvys. Exporting vendor payments from Alvys to the accounting system is not supported.

Imports occur every 12 hours for bills generated from the Trip Details page and the Pay Drivers page (driver paystubs).

<Info>
  💡 Carrier Settlements and Driver Settlements currently do not support vendor payment import.
</Info>

## How Load Status Updates After Payment

Once a payment is imported from the external accounting system or manually added to a load, the transaction is considered closed and the associated load's status updates to **Completed**. Any subsequent updates made to that transaction in the external accounting system will not be reflected in Alvys.

If a transaction for which the payment has already been processed and the load marked as **Completed** requires modification, contact Alvys Support at [support@alvys.com](mailto:support@alvys.com). The system does not automatically retry missed payment synchronizations; support intervention is required to resolve any discrepancies.

## Limits and Unsupported Scenarios

* Customer payment export is not supported for QuickBooks Desktop or Business Central.
* Partial payments are not eligible for export, regardless of the integration type.
* Payments tied to Summary Invoice page invoices are not supported for customer payment import.
* Carrier Settlements and Driver Settlements do not support vendor payment import.
* If a payment export or import is missed, it is not automatically retried.
* Once a load reaches **Completed** status after payment, further accounting system changes to that transaction are not reflected in Alvys.

## FAQs

**Q: When are customer payments exported from Alvys?**

**A:** Customer payments are exported only when the Export Customer Payments setting is enabled for the subsidiary and a deposit account is configured. Only full payments applied to individual loads or uploaded via a factoring report are eligible for export. The sync runs every five (5) minutes.

**Q: Can customer payments be exported to QuickBooks Desktop?**

**A:** No. Customer payment export is not supported for QuickBooks Desktop.

**Q: Can customer payments be exported to Business Central?**

**A:** No. Customer payment export is not supported for Business Central.

**Q: Does the QuickBooks Web Connector need to be running to sync payments?**

**A:** Yes. QuickBooks Desktop is a local application, so Alvys cannot import payments or update load statuses to **Completed** unless the QuickBooks Web Connector is open and running its sync cycle.

**Q: How often are customer payments synchronized to external accounting systems?**

**A:** Full customer payments are exported every five (5) minutes for supported integrations.

**Q: Which invoices are supported for customer payment import?**

**A:** Customer payment import is supported only for invoices exported from individual loads or the Invoicing page (batch invoicing) in Alvys. Payments applied to invoices originally generated from the Summary Invoice page are not supported. Qualifying payments are imported every 12 hours.

**Q: How does vendor payment synchronization work?**

**A:** Vendor payment synchronization is one-way: only full payments applied in the accounting system to bills originally created from Alvys are imported back into Alvys. Vendor payments cannot be exported from Alvys. Imports occur every 12 hours for bills generated from the Trip Details page and the Pay Drivers page.

**Q: Are there any modules that do not support vendor payment import?**

**A:** Yes. Carrier Settlements and Driver Settlements do not currently support vendor payment import.

**Q: What should I do if a payment export or import is missed?**

**A:** First confirm that your integration is active and, for QuickBooks Desktop, that the Web Connector is running. If those are not the cause, contact Alvys Support at [support@alvys.com](mailto:support@alvys.com). Missed payment synchronizations are not automatically retried.

**Q: What happens to a load once a payment is imported or manually added?**

**A:** Once a payment is imported from the external accounting system or manually added to a load, the load status updates to **Completed**. Subsequent updates made to that transaction in the external accounting system will not be reflected in Alvys. If the completed transaction requires modification, contact Alvys Support.

## Go Deeper

* [QuickBooks Online](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)
* [QuickBooks Desktop](/en/help/integrations/identifying-and-resolving-failed-quickbooks-desktop-transaction-exports)
* [NetSuite](/en/help/integrations/transactions-failed-to-sync-to-netsuite)
* [Microsoft Dynamics 365 Business Central](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)


# Broker Credit Check
Source: https://docs.alvys.com/en/help/integrations/broker-credit-check

Run manual or automatic broker and customer credit checks in Alvys through OTR Solutions or Saint John Capital factoring before submitting invoices.

<Note>
  Run a broker credit check (also called a customer credit check or factoring credit check) to have your factoring company evaluate the creditworthiness of a customer or broker before submitting an invoice for funding. Supported providers: OTR Solutions and Saint John Capital Factoring.
</Note>

## Overview

A broker credit check is a procedure your factoring company uses to assess the creditworthiness of a customer or broker before agreeing to purchase an invoice. Running a credit check before submission reduces the risk of a declined invoice and helps keep your factoring workflow moving.

In Alvys, credit checks can be triggered manually by a user or automatically by the system. Manual checks are available from the customer or broker profile and from the load details page. Automatic checks are triggered at specific points in the invoicing workflow.

This feature is only available when your subsidiary has an active factoring integration that supports broker credit checks. The two supported integrations are OTR Solutions and Saint John Capital Factoring.

## Before You Start

* Your subsidiary must have an active factoring integration set up for either OTR Solutions or Saint John Capital Factoring. To set up the integration, go to Management > Integrations, select the subsidiary, expand the Factoring section, and configure the provider.
* The customer or broker profile must have Factoring Company set as the invoicing method for the subsidiary where the integration was added.
* The customer or broker record must have an MC number on file. If the MC number is missing and the company is not a Customer type, the credit check will not run (see Troubleshooting).

No special role or permission beyond an active authenticated session is required to run a credit check. Any user who can access the company profile or load details page can trigger a credit check.

## Steps

### Set up the factoring invoicing method on the customer or broker profile

1. Go to Companies and open the customer or broker profile you want to run a credit check for.
2. Navigate to the Invoicing tab on the profile.
3. Under the subsidiary where your OTR Solutions or Saint John Capital Factoring integration is configured, add Factoring Company as the invoicing method.
4. Click Save.

<Note>
  <img alt="Image displaying the Saint Johns Capital Factoring Integration form in Alvys" />

  \*Image displaying the Saint Johns Capital Factoring Integration form in Alvys \*
</Note>

### Run a manual credit check from the customer or broker profile

Once the integration is successfully added, a refresh icon (↻) appears next to the company name in the profile header. This icon is the manual credit check trigger.

1. Open the customer or broker profile.
2. Click the refresh icon (↻) next to the company name.
3. Alvys sends a credit check request to your factoring provider and returns a status.

<Note>
  <img alt="Refresh icon (↻) next to a customer or broker name in the company profile header after the factoring invoicing method has been added." />

  *Refresh icon (↻) next to a customer or broker name in the company profile header after the factoring invoicing method has been added.*
</Note>

After the check runs, a color-coded status icon appears next to the company name:

The credit check status and the timestamp of the last check are shown in the profile header at all times.

<Note>
  <img alt="Credit check status displayed next to the customer or broker name in the profile header." />

  *Credit check status displayed next to the customer or broker name in the profile header.*
</Note>

### Run a manual credit check from the load details page

1. Go to Loads and open a load whose customer has a subsidiary using the Factoring Company invoicing method.
2. In the Order Details section of the load, locate the Factoring Company row.
3. Click the refresh icon (↻) to trigger a credit check for that customer.

<Note>
  <img alt="Image displaying Credit Check Refresh icon from load details page" />

  *Image displaying Credit Check Refresh icon from load details page*
</Note>

After the check runs, the same color-coded status icons appear in the load's Order Details section. A confirmation message appears at the bottom of the screen:

## Result

After a credit check runs, the status icon next to the customer or broker name is updated to reflect the current result, and the timestamp showing when the last check was run is also updated. This status is visible on both the company profile and the load details page.

## Variations

### Automatic credit checks during invoicing

Alvys runs a credit check automatically in the following situations:

* When you click Invoice Load to generate an invoice, if the last credit check for that customer or broker was more than 24 hours ago, a new check is triggered automatically before the load moves to **Queued** status.
* When a new load is created with a customer who has a factoring invoicing method configured, if the last credit check was more than 24 hours ago, a check is triggered automatically at load creation.

### Submitting a load to factoring when a credit check is declined

The behavior when a declined status exists depends on which factoring provider is configured.

**Saint John Capital Factoring:** If a load's customer has a credit check status of **Declined**, you cannot select that load on the Factoring Upload page. The load will be greyed out and cannot be added to a batch.

**OTR Solutions:** Whether the credit check status is **Declined**, **Call Credit**, or **Approved**, you can still select the load and submit it to OTR Solutions. OTR Solutions does not block batch submission based on credit check status.

The full workflow to submit a load to factoring after a credit check:

1. Open or create a load with a customer whose subsidiary is configured with the Factoring Company invoicing method.
2. Advance the load to **Released** status.
3. Click **Invoice Load** to generate the invoice. If the last credit check is older than 24 hours, a new check runs automatically at this step. The load moves to **Queued** status.
4. Go to Accounting > Factoring Upload.
5. Select the correct subsidiary.
6. Select the loads to include in the batch. For Saint John Capital, any load with a **Declined** credit check status cannot be selected.

   <img alt="Image displaying load selection for factoring batch" />

   \*Image displaying load selection for factoring batch \*
7. Click Submit Batch.

## Troubleshooting

### Credit check icon does not appear on the company profile

**Step 1:** Confirm the company has Factoring Company set as the invoicing method on the subsidiary where your OTR Solutions or Saint John Capital Factoring integration is active.

**Step 2:** Confirm your tenant has an OTR Solutions or Saint John Capital Factoring integration active. Other factoring providers (Apex Capital, TAFS, Triumph, RTS, Capital Depot, Compass Funding Solutions, WinFactor, and Wex FleetOne) do not support broker credit checks and will not show the credit check icon.

**Step 3:** If both conditions are met and the icon still does not appear, contact Alvys support.

### Credit check returns "MC Number is required"

The credit check requires an MC number to identify the broker or customer with the factoring provider. If the company record does not have an MC number on file, the credit check will not run. Add the MC number to the company's profile and then retry the credit check.

### Load cannot be selected on the Factoring Upload page

A load is blocked from batch selection when the customer has a **Declined** credit check status and the subsidiary is configured with Saint John Capital Factoring. Run a new credit check from the customer profile. If the provider approves on the new check, the load becomes selectable. If the provider declines again, contact your Saint John Capital representative directly to resolve the credit status before resubmitting.

### Credit check status is not updating after running a new check

Refresh the page after triggering a credit check. If the status remains unchanged after refreshing, the factoring provider may be experiencing a delay. Wait a few minutes and try again. If the issue persists, contact Alvys support.

## FAQs

**Q: Which factoring integrations support broker credit checks?**

**A:** OTR Solutions and Saint John Capital Factoring. All other factoring providers available in Alvys do not support broker credit checks, and the credit check icon will not appear for companies whose subsidiary uses a different provider.

**Q: How often does a credit check need to be run?**

**A:** The system automatically runs a new credit check when the most recent check is older than 24 hours. You can also trigger a manual check at any time by clicking the refresh icon (↻) on the company profile or the load details page.

**Q: What happens if a credit check is declined for OTR Solutions?**

**A:** For OTR Solutions, a **Declined** status does not block you from selecting that load on the Factoring Upload page or submitting the batch. The factoring company will apply its own rules after submission.

**Q: What does the amber "Call Credit" status mean?**

**A:** The **Call Credit** status is specific to OTR Solutions. It means the customer or broker must contact OTR Solutions directly to receive credit approval before the factoring company will fund the invoice.

**Q: Can I run a credit check if I do not use factoring for invoicing?**

**A:** No. The credit check feature is only available when the company has the Factoring Company invoicing method configured for a subsidiary with an active OTR Solutions or Saint John Capital Factoring integration. Without that configuration, the credit check icon does not appear.

**Q: Does running a broker credit check require a special permission?**

**A:** No. Any authenticated Alvys user who can access the company profile or load details page can trigger a manual credit check. There is no dedicated credit check permission in Alvys.

## Go Deeper

* [Understanding Factoring in Alvys](/en/help/integrations/how-to-set-up-and-use-factoring-in-alvys)
* [OTR Solutions Integration and Features](/en/help/integrations/otr-solutions-factoring-integration)
* [Saint Johns Capital Factoring](/en/help/integrations/saint-johns-capital-factoring-integration)


# Business Central: Overview
Source: https://docs.alvys.com/en/help/integrations/business-central-integration-collection

Collection of articles for setting up, using, and troubleshooting the Microsoft Dynamics 365 Business Central accounting export integration in Alvys.

<Note>
  This collection includes all articles and guidance for configuring, using, and troubleshooting the Microsoft Dynamics 365 Business Central integration (BC, Business Central, accounting integration, transaction export, sync) in Alvys.
</Note>

## Overview

The Business Central integration allows Alvys to automatically export financial transactions, including load invoices, trip bills, e-checks, paystubs, and carrier bills, to your Business Central General Ledger. This collection covers every step from initial setup through ongoing transaction management and error resolution. Follow the recommended order to get started, or jump to a specific topic using the links below.

## Articles in This Collection

### 1. Business Central: Prerequisites

What to prepare in your Business Central environment before connecting to Alvys. Covers organizational architecture (Separate Companies vs. MEM), required user licensing, granular permission sets, and the mandatory setup of the Chart of Accounts, Posting Groups, and Journal Batches.

[Business Central: Prerequisites](/en/help/integrations/how-to-prepare-business-central-before-connecting-to-alvys)

### 2. Business Central: Connection and Settings

Authenticate the connection between Alvys and Business Central and configure core transaction settings. Covers Revenue and Expense toggles, driver billing configuration, subsidiary and fleet dimension mapping, and e-check automation.

[Business Central: Connection and Settings Configuration](/en/help/integrations/how-to-connect-business-central-to-alvys-and-configure-settings)

### 3. Business Central: Account Mappings

Map Alvys transaction types to Business Central General Ledger accounts. Covers required default accounts (accounts receivable, accounts payable, default revenue, and default expense) and optional specific mappings for Loads, Trips, Accessorials, E-Checks, Deductions, Fuel, Tolls, and Escrow.

[Business Central: Account Mappings](/en/help/integrations/how-to-set-up-business-central-account-mappings)

### 4. Business Central: Transaction Export and Modification Workflow

How Alvys routes invoices and bills to Business Central based on Invoice As and Tender As logic. Covers how customer and vendor records are linked or created and the workflow for modifying, regenerating, or reversing transactions after they have been exported.

[Business Central: Transaction Export and Modification Workflow](/en/help/integrations/business-central-transaction-export-and-modification-workflow)

### 5. Business Central: Payment Synchronization

How vendor payment updates sync between Business Central and Alvys, including status update behavior and known limitations. Note: Customer Payment Export is not supported for Business Central.

[Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)

### 6. How to resolve Business Central transaction export errors

How to view and resolve failed transaction exports using the Error Transactions page. Covers the error table columns, which transaction types can be re-synced directly, the re-sync and Mark as Synced workflows, and resolution steps for common Business Central error messages.

[Business Central: Identifying and Resolving Failed Transactions](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)


# Business Central: Export & modify transactions
Source: https://docs.alvys.com/en/help/integrations/business-central-transaction-export-and-modification-workflow

How Alvys exports invoices and bills to Business Central, routes them by subsidiary, matches customer and vendor records, and modifies past exports.

<Note>
  This article explains how Alvys exports customer invoices and carrier and driver bills to Business Central (BC, Business Central, accounting export), how subsidiary routing determines which BC company or entity receives each transaction, and how to modify previously exported transactions.
</Note>

## Overview

The Business Central integration enables Alvys to automatically export accounting transactions (including customer invoices (sales invoices), carrier purchase invoices, and driver purchase invoices) to your Business Central environment. Alvys serves as the system of record for all exported transactions. Changes must always be made in Alvys and then synchronized to Business Central through regeneration; edits made directly in Business Central can cause data inconsistencies.

This article covers:

* How Alvys determines which Business Central company or entity receives each transaction (subsidiary routing)
* How customer and vendor records are matched or created in Business Central
* How to export invoices and bills from Alvys
* How to modify previously exported transactions depending on their status in Business Central
* Limitations specific to the Carrier Settlements module and Summary Invoicing

Synonyms used throughout: BC, Business Central, accounting export, transaction sync, invoice export, bill export, purchase invoice, sales invoice.

## Where to Find It?

* **Load Details page:** Individual load invoice export is triggered from the load record itself.
* **Batch Invoicing page:** Accounting > Invoice ([https://app.alvys.com/#/accounting/invoicing](https://app.alvys.com/#/accounting/invoicing))
* **Summary Invoicing page:** Accounting > Summary Invoicing ([https://app.alvys.com/#/accounting/summary-invoicing](https://app.alvys.com/#/accounting/summary-invoicing))
* **Carrier Settlements page:** Accounting > Carrier Settlements
* **Pay Drivers page (legacy):** Accessible from the Accounting section for tenants using the legacy driver pay workflow.
* **Driver Settlements page:** Accessible from the Accounting section for tenants using the Driver Settlements module.
* **Error Transactions page:** Accounting > Error Transactions ([https://app.alvys.com/#/accounting/error-help](https://app.alvys.com/#/accounting/error-help)): review failed exports here.

## Key Concepts

### Subsidiary Routing

When configuring the Business Central integration, each Alvys subsidiary is linked to a specific company connection. This routing logic determines which connected Business Central entity receives exported invoices and bills.

Routing works differently depending on your organizational setup:

* **Individual Company Setup (no subsidiary mapping):** Alvys directs transactions to the specific, separate Business Central database connected to that subsidiary.
* **Multi-Entity Management (MEM) setup (subsidiary mapped to entity dimension value):** Alvys sends transactions to a shared Business Central database and tags each transaction with the correct Entity Code (Dimension) based on the subsidiary mapping. This allows multiple legal entities to be managed accurately within a single Business Central company.

### Invoice As Field

The **Invoice As** field on a load represents the billing subsidiary responsible for issuing the customer invoice. It determines the legal entity name displayed on the invoice. All Accounts Receivable (AR) transactions exported to Business Central are linked to the subsidiary mapped to the Invoice As field.

For example, if a load's Invoice As field is set to Alvys Inc:

* **Standard Integration:** The sales invoice is exported to the specific Business Central company connection tied to that subsidiary.
* **MEM Integration:** The invoice is exported to the shared Business Central database, and the Entity Code (Dimension) on the invoice is automatically set to the Business Central value linked to the Invoice As subsidiary (Alvys Inc in this example).

For example, if a load’s Invoice As field is set to Alvys Inc, upon invoice generation:

<Note>
  <img alt="Load Details page showing “Invoice As” field" />

  *Load Details page showing “Invoice As” field*
</Note>

### Tender As Field

The **Tender As** field identifies the subsidiary responsible for dispatching the load and paying the carrier. It also determines the trip type: if the selected subsidiary is set up as a broker, the trip type is Brokerage; if set up as a carrier, the trip type is Carrier.

For example, if a load's Tender As field is set to Alvys Brokerage:

* **Standard Integration:** The carrier purchase invoice is exported to the specific Business Central company connection tied to that subsidiary.
* **MEM Integration:** The bill is exported to the shared Business Central database, and the Entity Code (Dimension) on the bill is automatically set to the Business Central value linked to the Tender As subsidiary (Alvys Brokerage in this example).

The Tender As field identifies the subsidiary responsible for dispatching the load and paying the carrier. It also determines the trip type. If the selected subsidiary is set up as a broker, the trip type is Brokerage. If the selected subsidiary is set up as a carrier, the trip type is Carrier. For example, if a load’s Tender As field is set to Alvys Brokerage, upon exporting the external carrier bill/Purchase Invoice:

<Note>
  <img alt="Load Details Page showing “Tendering As”" />

  *Load Details Page showing “Tendering As”*
</Note>

### Dual Authority Carriers

For carriers operating with dual authority, the operational mode is automatically determined based on the Tender As subsidiary. Users can manually change the operational mode to Carrier or Broker. The chosen operational mode affects how bills are categorized and exported to Business Central.

<Note>
  <img alt="Notion Image" />

  <img alt="Operational Mode selection for carriers with dual authority." />

  \*Operational Mode selection for carriers with dual authority. \*
</Note>

### Driver Subsidiary Field

Each driver profile includes a Subsidiary field representing the business unit to which the driver is assigned. When generating driver statements, the resulting Vendor Bill is exported based on the driver’s assigned subsidiary:

<Note>
  <img alt="Subsidiary field in driver profile" />

  *Subsidiary field in driver profile*
</Note>

### Business Central Transaction Statuses

The status of a transaction in Business Central determines what modifications are possible:

* **Draft:** The transaction is unposted and can be edited directly in Business Central. Changes made in Alvys will update the existing Business Central record on the next sync or invoice regeneration.
* **Open:** The transaction has been posted. It can no longer be edited directly. Alvys will automatically generate and export a Sales Credit Memo to reverse the original transaction, followed by a new Sales Invoice with the updated details, when the invoice is regenerated in Alvys.
* **Closed:** A payment has been fully applied and synced from Business Central. No further modifications are permitted at this stage. Contact Alvys Support; this status is the code-verified reason why self-service modification is blocked, as the transaction record is locked once payment is fully reconciled.

## How to Use It?

### Customer Linkage and Accounting Fields

*\[Heading 4 not supported]*

The customer's **External Accounting Name** is used to identify a customer or broker in Business Central. When exporting an invoice, Alvys first searches for an exact match in Business Central using this field.

### Customer External Accounting Name

The customer’s **External Accounting Name** is used to identify a customer or broker in Business Central. When exporting an invoice Alvys first searches for an **exact match** in Business Central using this field.

<Note>
  <img alt="External Accounting Name field on Customer profile" />

  *External Accounting Name field on Customer profile*
</Note>

* If a matching customer exists in Business Central, the invoice is linked to that customer.
* If no match is found and the External Accounting Name is set on the customer profile, Alvys automatically creates a new customer in Business Central using the External Accounting Name.
* For tenants where the External Accounting Name is not set, Alvys attempts to match using the Customer Name. If no match is found, a new customer is created in Business Central using the Customer Name.

The External Accounting Name always takes priority. If it differs from an existing Business Central customer name, even if the Customer Name in Alvys matches, a new customer will be created using the External Accounting Name.

*\[Heading 4 not supported]*

The **Invoicing Name** (previously called Billing Name) determines how the customer or broker appears on invoices generated in Alvys. It does not affect the customer record created in Business Central.

<Note>
  <img alt="Invoicing Name on Customer Profile" />

  *Invoicing Name on Customer Profile*
</Note>

When creating customers in Business Central, Alvys uses the following fields from the customer or broker profile:

* **Name:** The External Accounting Name is used; if the external name is not set, it defaults to the customer or broker's name.
* **Invoicing Address**
* **Customer Email** (not the Invoicing Email)
* **Customer Phone** (not the Company Number)
* **Payment Terms**

Alvys is the source of truth for these fields. If a user later updates this information directly in Business Central after Alvys has created the customer record, those changes will be overwritten the next time an invoice is synced from Alvys. All updates to these fields must be made within Alvys to ensure data consistency.

### Payment Terms

The Payment Terms field specifies the agreed-upon period within which a customer must pay an invoice, calculated from the invoice date. In Alvys, this can be set to any value between 0 and 365 days within the customer profile.

<Note>
  <img alt="Customer Profile field for payment terms" />

  *Customer Profile field for payment terms*
</Note>

Payment Terms determine the due date for the load as well as the invoice due date and payment terms exported to Business Central on the sales invoice. When Alvys creates a new customer in Business Central, it attempts to match the customer's payment terms to existing Payment Terms Codes in Business Central. If no exact match is found, Alvys defaults the customer's terms to 30 Days. Also, when Alvys creates a new customer in Business Central, it attempts to match the customer’s payment terms to the Payment Terms Codes existing in Business Central. If no exact match is found, Alvys defaults the customer's terms to 30 Days.

<Note>
  <img alt="BC field for Payment Terms Code" />

  *BC field for Payment Terms Code*
</Note>

### Vendor Linkage and Accounting Fields

*\[Heading 4 not supported]*

The carrier's **External Accounting Name** is used to identify a vendor in Business Central. When exporting a purchase invoice, Alvys first searches for an exact match in Business Central using this field.

### Carrier External Accounting Name

The carrier’s **External Accounting Name** is used to identify a vendor in Business Central. When exporting a purchase Invoice, Alvys first searches for an **exact match** in Business Central using this field.

<Note>
  <img alt="External Accounting Name on Carrier Profile" />

  *External Accounting Name on Carrier Profile*
</Note>

* If a matching vendor exists in Business Central, the bill is linked to that vendor.
* If no match is found and the External Accounting Name is set on the carrier profile, Alvys automatically creates a new vendor in Business Central using the External Accounting Name.
* For carriers where the External Accounting Name is not set, Alvys attempts to match using the Carrier Name. If no match is found, a new vendor is created in Business Central using that name.

The External Accounting Name takes priority. If it differs from an existing Business Central vendor name, even if the Carrier or Driver Name in Alvys matches, Alvys will create a new vendor using the External Accounting Name.

*\[Heading 4 not supported]*

Drivers, including company drivers and owner-operators, may operate as 1099 drivers. These drivers have additional tax detail fields on their profiles:

* **Tax Company Name**
* **Tax Company Address**

<Note>
  <img alt="Driver Profile showing fields for Tax Category, Company Name, and Company Address." />

  \*Driver Profile showing fields for Tax Category, Company Name, and Company Address. \*
</Note>

When generating driver statements, if these fields are set and the Business Central integration is configured to create vendors using 1099 details, Alvys will create the vendor using the tax information (company name and address). If this setting is not enabled, the vendor will be created using the driver’s name.

<Note>
  <img alt="Payment terms in company profile of subsidiary" />

  *Payment terms in company profile of subsidiary*

  <img alt="Notion Image" />
</Note>

For external carriers, the purchase invoice due date is determined using the Carrier Payment Terms from the company profile of the subsidiary specified in the Tender As field on the trip.

### Invoice Transaction Export

*\[Heading 4 not supported]*

Generating a customer invoice from the **Load Details** page triggers its export to Business Central. Before generating the invoice, verify the following:

1. Verify that the customer being invoiced is correct. Ensure the External Accounting Name is properly configured on the customer profile. If no External Accounting Name is set, the standard customer or broker name must exactly match the corresponding customer record in Business Central.

### Individual Load Invoice Export

Generating a customer invoice from the **Load Details** page triggers its export to Business Central. To ensure a successful export, all relevant configurations and data must be verified before the invoice is generated.

Verify that the customer being invoiced is correct. Ensure the **External Accounting Name** is properly configured on the customer profile. If no External Accounting Name is set, the standard customer or broker name must exactly match the corresponding customer record in Business Central.

<Note>
  <img alt="External Accounting Name on customer profile" />

  *External Accounting Name on customer profile*

  <img alt="Customer Card in Business Central" />

  *Customer Card in Business Central*
</Note>

Verify the customer’s invoice settings for the subsidiary used as the Invoice As entity on the load. The Invoice As subsidiary must correspond to the subsidiary configured within the Business Central integration. This alignment determines which specific Business Central company or entity dimension receives the transaction data.

<Note>
  <img alt="Where to find invoice settings on the customer profile." />

  \*Where to find invoice settings on the customer profile. \*

  <img alt="This warning alerts you that your updated settings do not match the default." />

  \*This warning alerts you that your updated settings do not match the default. \*
</Note>

1. Once these conditions are satisfied and the load is in **Released** status, generate the invoice. Generating the invoice automatically initiates the export to Business Central.

<Note>
  <img alt="Notion Image" />

  <img alt="Load details page on a load showing where to generate an invoice." />

  \*Load details page on a load showing where to generate an invoice. \*
</Note>

1. Once the invoice is successfully exported from Alvys, locate it in Business Central by navigating to the Sales dropdown menu and selecting Sales Invoices. Invoices are exported as Unposted Sales Invoices, allowing the accounting team to perform a final review of amounts and tax codes before posting to the General Ledger.

<Note>
  <img alt="Sales Invoice in Business Central" />

  *Sales Invoice in Business Central*
</Note>

If the invoice was not exported due to an error, the issue can be reviewed on the Error Transactions page ([https://app.alvys.com/#/accounting/error-help](https://app.alvys.com/#/accounting/error-help)). See the Business Central: Identifying and Resolving Failed Transactions article for guidance ([How to resolve Business Central transaction export errors](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)).

*\[Heading 4 not supported]*

The Batch Invoicing page is located at Accounting > Invoice in the left navigation menu ([https://app.alvys.com/#/accounting/invoicing](https://app.alvys.com/#/accounting/invoicing)). This page allows users to create invoices for multiple loads across one or more customers simultaneously. Each selected load is processed as an individual invoice, and the export to Business Central is triggered automatically when the invoices are generated.

<Note>
  <img alt="Invoice tab in Alvys" />

  *Invoice tab in Alvys*
</Note>

1. From the **Released** tab, select the loads for which you want to generate invoices. Verify that the customer being invoiced is correct. If an External Accounting Name is configured, it must exactly match the corresponding customer record in Business Central. If no External Accounting Name is configured, the standard customer or broker name must match the customer record. Verify that the Invoice As subsidiary on each load is correctly configured, as this determines which specific Business Central company or entity dimension receives the transaction data.

   <img alt="Loads in the Released tab of the accounting module." />

   \*Loads in the Released tab of the accounting module. \*
2. Generate the invoices using one of the following options:

   * **Generate Invoice:** Creates the invoices and exports them to Business Central.
   * **Create and Send:** Generates the invoices, exports them to Business Central, and sends them to the customer according to the invoicing method configured for that customer.

<Note>
  <img alt="Generate Invoice button found in the Invoicing module" />

  *Generate Invoice button found in the Invoicing module*
</Note>

Once exported, invoices are recorded in Business Central under the corresponding customer and can be located by navigating to the Sales dropdown menu and selecting Sales Invoices.

If an invoice was not exported due to an error, review the issue on the Error Transactions page ([https://app.alvys.com/#/accounting/error-help](https://app.alvys.com/#/accounting/error-help)). See the Business Central: Identifying and Resolving Failed Transactions article for guidance ([How to resolve Business Central transaction export errors](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)).

*\[Heading 4 not supported]*

Summary invoicing consolidates multiple loads for a customer into a single invoice. The Summary Invoicing page can be accessed at Accounting > Summary Invoicing. For information on configuring customers for summary invoicing, see the Summary Invoicing article ([How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)).

The invoice export is triggered when the consolidated summary invoice is generated, creating a single invoice reflecting the total amount for all included loads. Only customers configured with the summary invoice type will appear when selecting a subsidiary. The subsidiary selection determines the Business Central subsidiary to which the invoice will be linked.

1. On the Summary Invoicing page ([https://app.alvys.com/#/accounting/summary-invoicing](https://app.alvys.com/#/accounting/summary-invoicing)), open the Loads Not Invoiced tab. Select the loads to include and add them to a draft summary invoice.

<Note>
  <img alt="Summary Invoicing tab with customer selected" />

  *Summary Invoicing tab with customer selected*

  <img alt="List of Draft Invoices with the “Generate Invoice” option available" />

  *List of Draft Invoices with the “Generate Invoice” option available*
</Note>

1. Generate the invoice. This creates the summary invoice and exports it to Business Central.

Once exported, the invoice is recorded in Business Central under the corresponding customer and can be located by navigating to the Sales dropdown menu and selecting Sales Invoices.

### Bill Transaction Export

*\[Heading 4 not supported]*

External carrier bills can be exported directly from individual loads based on the configured external accounting settings. The export is triggered when the customer invoice is generated.

Before generating the invoice, verify the following:

* The correct external carrier is assigned to the trip.
* The subsidiary selected in the Tender As field is verified; this subsidiary determines which Business Central company or entity dimension the carrier bill will be linked to. The selected subsidiary must be configured to receive carrier bills through the Business Central integration.

For tenants operating in dual-authority mode, an additional validation is required: the operational mode must be set to **Brokerage**. If the operational mode is set to **Carrier**, the external carrier bill export will not occur.

<Warning>
  ⚠️ For tenants operating in dual-authority mode, an additional validation is required. The operational mode must be set to **Brokerage**. If the operational mode is set to **Carrier**, the external carrier bill export will not occur.

  <img alt="Dual authority toggle" />

  *Dual authority toggle*
</Warning>

When an external carrier is assigned and the trip is released to billing, the system evaluates the **Generate Carrier Invoice Separately** setting:

* If this setting is **not enabled:** The carrier bill is exported automatically when the customer invoice is generated.
* If this setting is **enabled:** The system checks whether a document of type Carrier Invoice has been uploaded to the trip. If the document is present, the carrier bill is exported to Business Central when the customer invoice is generated.

<Note>
  <img alt="Document upload with Type set to “Carrier Invoice”" />

  \*Document upload with Type set to “Carrier Invoice” \*
</Note>

*\[Heading 4 not supported]*

In Alvys, the carrier invoice number is entered when uploading a document of the type Carrier Invoice to a trip. When the carrier purchase invoice is exported to Business Central, this number is automatically populated in the **Vendor Invoice No.** field. This allows accounting teams to quickly locate purchase invoices within Business Central by searching the Purchase Invoices list using the specific carrier invoice number.

<Note>
  <img alt="Carrier Info section of Load Details Page" />

  *Carrier Info section of Load Details Page*

  <img alt="Purchase invoice example in Business Central." />

  \*Purchase invoice example in Business Central. \*
</Note>

*\[Heading 4 not supported]*

The Carrier Settlements module provides brokers with tools to generate transparent and accurate carrier statements and settlement bills. This page is accessible from Accounting > Carrier Settlements. For additional details, see the Carrier Settlements article ([Carrier Settlements](/en/help/accounting-settlements/carrier-settlements)).

When carrier settlements are used, the carrier bill is exported when a carrier statement is generated. To allow this export, the **Carrier Statements External Accounting** setting must be enabled for the subsidiary. If this setting is not enabled, no carrier bill will be exported when the statement is generated.

<Note>
  <img alt="Carrier Statements toggle in the Business Central Integration settings." />

  \*Carrier Statements toggle in the Business Central Integration settings. \*
</Note>

If this setting is enabled and a user generates a customer invoice for an individual load with an external carrier, the carrier bill will not be exported from the load. In this scenario, the system expects the bill to be exported from the Carrier Settlements module when the statement is generated.

If a carrier bill requires modification after export, see the Modifying Previously Exported Transactions section below.

**Carrier Settlements Module: Payment Sync Limitation**

The current version of the Carrier Settlements feature does not support payment synchronization. While carrier bills are exported from the Carrier Settlements module to Business Central, payments applied in Business Central do not automatically sync back to Alvys. Payments must be recorded manually within Alvys for external carriers.

If an error occurs while exporting a carrier purchase invoice from the Carrier Settlements module, the error details are displayed directly within the module. Carrier statements cannot be re-sent from the Error Transactions page. All corrections must be made within the Carrier Settlements module, and the statement must be regenerated there.

For tenants that use the Carrier Settlements module but prefer carrier bills to export when the carrier invoice is uploaded on the trip, it is recommended not to enable the Carrier Statements External Accounting setting. In this configuration, enable the Generate Carrier Invoice Separately setting, upload the carrier invoice to the trip, and then generate the customer invoice to trigger the carrier bill export.

*\[Heading 4 not supported]*

Driver statements (purchase invoices) can be exported from either the legacy Pay Drivers page or the Driver Settlements module. The export behavior is governed by your specific driver billing configuration.

**Single Bill Export (Recommended)**

The recommended configuration is Single Bill for Driver Statement Export. When enabled, all trips, deductions, and credits included in a driver statement are consolidated into a single bill for export to Business Central. This approach is ideal for tenants operating on weekly or biweekly pay cycles.

The subsidiary used for exporting driver bills is determined by the subsidiary assigned on the driver profile in Alvys.

**Pay Drivers Page (Legacy)**

For tenants using the legacy Pay Drivers page, generating a driver statement automatically triggers the export of the purchase invoice to Business Central.

If an error occurs while exporting a carrier purchase invoice from the Carrier Settlements module, the error details are displayed directly within the module. Carrier statements cannot be re-sent from the Error Transactions page. All corrections must be made within the Carrier Settlements module, and the statement must be regenerated there.

For tenants that use the Carrier Settlements module but prefer carrier bills to export when the carrier invoice is uploaded on the trip, it is recommended not to enable the Carrier Statements external accounting setting. In this configuration, enabling the generate carrier invoice separately setting and uploading the carrier invoice to the trip then generating the customer invoice will trigger the carrier bill export.

<Note>
  <img alt="Notion Image" />

  <img alt="Driver Settlements module view with option to “generate stub.”" />

  *Driver Settlements module view with option to “generate stub.”*
</Note>

If a correction is needed, driver statements generated from this page can be reverted. To revert, navigate to the driver profile, click the three dots next to the statement in the right-hand corner, and select the Delete option.

<Note>
  <img alt="How to delete a driver statement" />

  *How to delete a driver statement*
</Note>

Reverting a driver statement in Alvys automatically deletes the corresponding purchase invoice from Business Central, provided the bill remains unposted and no payments have been applied to it.

**Driver Settlements Module**

The Driver Settlements module replaces the legacy Pay Drivers page and introduces advanced features such as draft statements, predefined pay periods, and bulk actions. For additional details, see the Driver Settlements article ([Driver Settlements FAQ](/en/help/accounting-settlements/driver-settlements-faq)).

For statements generated via the Driver Settlements module, reverting the statement from the Statements tab automatically removes the associated driver bill from Business Central. This synchronization is successful provided the bill remains unposted and no payments have been applied.

## Settings and Permissions

* **Who can export transactions:** Users with the **"Admin"** or **"Partner Admin"** role. The Accounting Integrations area is restricted to these roles.
* **Carrier Statements External Accounting setting:** Must be enabled per subsidiary to allow carrier bill export from the Carrier Settlements module. When enabled, carrier bills will not export from individual load invoice generation for external carriers; the system expects the bill to come from the Carrier Settlements module instead.
* **Generate Carrier Invoice Separately setting:** When enabled, carrier bill export from an individual load is held until a Carrier Invoice document is uploaded to the trip.
* **Single Bill for Driver Statement Export:** Configured per tenant. When enabled, all trips and adjustments in a driver statement are consolidated into a single purchase invoice for Business Central.
* **1099 Tax Details for vendor creation:** When this setting is enabled in the Business Central integration configuration, Alvys uses the driver's Tax Company Name and Tax Company Address to create the vendor record instead of the driver's name.
* **Alvys is the source of truth:** Customer and vendor field values managed in Alvys (name, address, phone, payment terms) will overwrite any changes made directly in Business Central on the next sync.

## Limits and Behavior

\##a inconsistencies and prevent updates from syncing correctly. Do not delete transactions in Business Central if you plan to edit and resend them.

*\[Heading 4 not supported]*

The behavior of modifications to previously exported invoices depends on the status of the record in Business Central:

**Unposted Invoices (Draft status in BC)**

If the invoice remains unposted in Business Central (**Draft** status), changes made in Alvys will update the existing record upon the next synchronization or invoice regeneration.

**Posted Invoices (Open status in BC)**

If the invoice has already been posted (**Open** status), it can no longer be directly edited. Alvys will automatically generate and export a Sales Credit Memo to reverse the original transaction, followed by a new Sales Invoice containing the updated details, once the invoice is regenerated in Alvys.

**Closed Invoices (Closed status in BC)**

Once a payment has been fully applied and synced from Business Central, the invoice reaches **Closed** status in Alvys. At this stage, no further modifications are permitted. The reason is that the transaction record is locked once payment is fully reconciled in Business Central. Contact Alvys Support for assistance if a **Closed** invoice requires changes.

*\[Heading 4 not supported]*

Certain load invoice fields automatically update the Business Central sales invoice without requiring invoice regeneration. Updates to the following fields are applied automatically when saved in Alvys; refresh the invoice page in Business Central to see the changes:

* Customer linehaul amount
* Customer fuel surcharge

  <img alt="Money box in the load details page of a load showing customer Linehaul and fuel surcharge." />

  \*Money box in the load details page of a load showing customer Linehaul and fuel surcharge. \*
* Accessorial charges (added, edited, or removed)

  <img alt="Accessorial example in the money box." />

  \*Accessorial example in the money box. \*
* Invoice Date (Document Date in BC)
* Invoice Due Date

<Note>
  <img alt="Invoice due date on the load details page of a load under the customer information." />

  \*Invoice due date on the load details page of a load under the customer information. \*
</Note>

Other changes require invoice regeneration to sync correctly.

*\[Heading 4 not supported]*

The customer associated with a load can only be changed while the load is in a status prior to **Invoiced** (for example, **Queued**). **Queued** status indicates that the invoice has been generated in Alvys but has not yet been submitted to the customer. Once the invoice has been submitted, the load status updates to **Invoiced** based on the invoicing mode, and the customer cannot be changed directly.

If the load is in **Invoiced** status, contact Alvys Support to revert the load status to **Queued**, which then allows the customer to be updated and the invoice to be regenerated for synchronization with Business Central.

**Sample Business Central Invoice Exported from Alvys**

The customer's name displayed on the exported invoice reflects the External Accounting Name.

### Sample Business Central Invoice Exported from Alvys

The customer’s name displayed on the exported invoice reflects the **External Accounting Name**.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

**To update the customer on an invoice:**

1. In the Load Details section of the load, click the **Change Customer** button.

   <img alt="Notion Image" />
2. Select the correct customer to assign to the load and save the change.

<Note>
  <img alt="Notion Image" />

  <img alt="Notion Image" />
</Note>

1. Regenerate the invoice in Alvys.

   <img alt="Notion Image" />
2. Refresh or reopen the invoice in Business Central to verify that the customer information has been updated correctly.

<Note>
  <img alt="Notion Image" />
</Note>

*\[Heading 4 not supported]*

Fields such as invoicing address, shipping address, customer email, and customer phone are managed in the customer profile.

For these changes to take effect, the load status must be prior to **Invoiced**. If the load has already been invoiced, contact Alvys Support to revert the status to **Queued** before making updates.

**To update customer fields:**

1. Navigate to the customer profile in Alvys.
2. Apply the necessary changes.
3. Save the updates.
4. Regenerate the invoice.
5. Refresh or reopen the invoice in Business Central to view the changes.

   *\[Heading 4 not supported]*

If the Invoice As subsidiary on a load needs to be changed after an invoice has already been exported, the process requires the **"Edit Invoice Customer As"** permission. Because changing the subsidiary routes the invoice to a different Business Central company or entity, the old invoice cannot be automatically updated or replaced through regeneration. The user must manually delete the old invoice from Business Central before regenerating the invoice with the corrected Invoice As subsidiary in Alvys.

*\[Heading 4 not supported]*

Modifications to summary invoices that have already been exported depend on the specific scenario.

**Adding or Removing Loads from a Summary Invoice**

The only supported mechanism for adding or removing loads from a summary invoice is to revert the summary invoice. A summary invoice can be reverted only when its status is **Processed**. If the invoice has already been **Sent** or **Paid**, further modification requires intervention from Alvys Support.

Reverting a summary invoice does not update the original invoice in Business Central. After reverting, the user must generate a new summary invoice in Alvys. This new invoice will receive a new summary invoice number, which will be exported to Business Central. The old summary invoice remains in Business Central unless manually deleted.

**Procedure:**

1. Navigate to the All-Invoices tab in Alvys.
2. Locate the invoice and click the Delete icon for the specific summary invoice.

   <img alt="Notion Image" />
3. Navigate to the Loads Not Invoiced tab.
4. Select the loads to be included in the new summary invoice.
5. Regenerate the summary invoice.
6. Verify that the updated summary invoice amount is accurately reflected in Business Central.
7. Manually delete the old summary invoice from Business Central to avoid duplicate records.

**Modifying or Adding Charges to Loads within a Summary Invoice**

Loads included in a summary invoice can be edited to add charges or make adjustments. Only summary invoices in the following statuses can be regenerated: **Pending**, **Sent**, or **Partially Paid**. If a summary invoice is fully paid, regeneration is not permitted.

**Sample Summary Invoice in Business Central**

<Note>
  <img alt="Notion Image" />
</Note>

**To modify or add charges to loads:**

1. Confirm that the summary invoice status is not **Paid** in Alvys. If the invoice is marked as Paid, all loads included in the summary invoice are set to Completed, and any subsequent modifications will not sync to Business Central for completed loads.
2. Navigate to the Load Details page for the specific load included in the summary invoice that requires modification.

   <img alt="Load number listed in the summary invoice" />

   *Load number listed in the summary invoice*
3. Apply the necessary updates (for example: add charges, adjust amounts, update notes).

<Note>
  <img alt="Add accessorial button in the load details page" />

  *Add accessorial button in the load details page*

  <img alt="The new accessorial once it has been added." />

  *The new accessorial once it has been added.*
</Note>

1. Navigate back to the Summary Invoice in Alvys and regenerate the summary invoice.

   <img alt="Regenerate button within Summary Invoice" />

   *Regenerate button within Summary Invoice*
2. Verify in Business Central that the updated invoice amount and associated load details are accurately reflected.

<Note>
  <img alt="Sales invoice example in Business Central." />

  \*Sales invoice example in Business Central. \*
</Note>

## FAQs

**Q: How does Alvys determine which Business Central company or entity receives an exported transaction?**

**A:** Routing is based on the subsidiary connection. In a standard setup, Alvys sends data to the specific Business Central database linked to that subsidiary. In a Multi-Entity Management (MEM) setup, transactions are sent to a shared database but are tagged with the correct Entity Code (Dimension) based on the subsidiary mapping.

**Q: What is the difference between the Invoice As and Tender As fields in relation to Business Central?**

**A:** The Invoice As field determines the subsidiary responsible for the customer invoice (Accounts Receivable). The Tender As field identifies the subsidiary paying the carrier (Accounts Payable) and determines the trip type (Brokerage vs. Carrier).

**Q: Is External Accounting Name the same as the Invoicing Name?**

**A:** No. The External Accounting Name is used solely to match the record in Business Central. The Invoicing Name controls how the name appears on invoices generated in Alvys. Changing the Invoicing Name does not affect the Business Central link as long as the External Accounting Name remains unchanged.

**Q: Which field takes priority when linking an Alvys customer or carrier to a record in Business Central?**

**A:** The External Accounting Name always takes priority. Alvys searches for an exact match in Business Central using this field first. If it is not set, Alvys defaults to matching by the standard Customer or Carrier Name. If no match is found, a new record is created in Business Central using the External Accounting Name (or the Name if the External Accounting Name is blank).

**Q: What happens if I update customer information (address, phone, or terms) directly in Business Central?**

**A:** Alvys is the source of truth for these fields. Any changes made directly in Business Central will be overwritten the next time an invoice is synced from Alvys. All updates should be made within the Alvys profile to ensure data consistency.

**Q: How are Payment Terms handled if an exact match isn't found in Business Central?** A: Alvys attempts to match the customer’s payment terms to existing Payment Terms Codes in BC. If no exact match is found, the system defaults the customer's terms to 30 Days.

**Q: Where do exported customer invoices appear in Business Central?**

**A:** Invoices are exported as Unposted Sales Invoices. This allows the accounting team to perform a final review of amounts and tax codes before posting them to the General Ledger. Navigate to the Sales dropdown menu in Business Central and select Sales Invoices to locate them.

**Q: When exactly is an external carrier bill exported to Business Central?**

**A:** The timing depends on your settings. If Generate Carrier Invoice Separately is disabled, the bill exports automatically when the customer invoice is generated. If it is enabled, the system waits until a document of type Carrier Invoice is uploaded to the trip before exporting the bill.

**Q: Does the carrier invoice number appear in Business Central?**

**A:** Yes. When a document of the type Carrier Invoice is uploaded to a trip in Alvys and the invoice number is entered, that value is automatically populated in the Vendor Invoice No. field within Business Central.

**Q: Can I sync carrier payments from Business Central back to the Alvys Carrier Settlements module?** A: No. The current version of the Carrier Settlements module does not support payment synchronization. While bills are exported to BC, payments applied in BC must be recorded manually within Alvys for those external carriers.

**Q: What happens in Business Central if I delete or revert a driver statement in Alvys?**

**A:** Reverting or deleting a driver statement in Alvys automatically deletes the corresponding purchase invoice in Business Central, provided the bill is still unposted and no payments have been applied to it.

**Q: How do I modify an invoice that has already been posted in Business Central?**

**A:** Since posted invoices cannot be edited directly, Alvys will automatically generate and export a Sales Credit Memo to reverse the original transaction, followed by a new Sales Invoice with the updated details, once you regenerate the invoice in Alvys.

**Q: Which load fields can be updated in Business Central without needing to regenerate the invoice in Alvys?**

**A:** Updates to the Customer Linehaul amount, Fuel Surcharge, Accessorial charges (added, edited, or removed), Invoice Date, and Invoice Due Date sync automatically to the Business Central sales invoice upon saving the change in Alvys and refreshing the Business Central page.

**Q: How do I change the customer on a load that has already been invoiced?**

**A:** Once a load is in **Invoiced** status, the customer cannot be changed directly. Contact Alvys Support to revert the load status to **Queued**, which then allows you to update the customer and regenerate the invoice for Business Central.

**Q: What is the process for adding or removing loads from an exported Summary Invoice?**

**A:** Revert the summary invoice in Alvys (only available when the status is **Processed**), which allows you to adjust the loads. Reverting in Alvys does not delete the old invoice in Business Central. Manually delete the old summary invoice in Business Central and then generate a new summary invoice in Alvys; the new invoice will receive a new invoice number.

## Go Deeper

* [Business Central: Identifying and Resolving Failed Transactions](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)
* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)
* [Business Central Integration Collection](/en/help/integrations/business-central-integration-collection)
* [Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)
* [Carrier Settlements](/en/help/accounting-settlements/carrier-settlements)
* [Driver Settlements](/en/help/accounting-settlements/driver-settlements-faq)


# Connect OneStepGPS to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-onestepgps-to-alvys

Connect OneStepGPS to Alvys with an API key to pull real-time GPS location data from equipped trucks and trailers into the Asset Map and dispatch planning.

<Note>
  The OneStepGPS integration connects your GPS-equipped trucks and trailers to Alvys, automatically pulling real-time location data so your fleet appears live on the Asset Map and in dispatch planning, with no manual location entry required.
</Note>

## What This Integration Does

OneStepGPS is a telematics provider that delivers real-time GPS tracking and asset monitoring. When connected to Alvys, it pushes location data from your OneStepGPS-equipped trucks and trailers directly into Alvys, giving dispatchers live visibility on the Asset Map and enabling more accurate trip planning.

This is a one-way integration: location data flows from OneStepGPS into Alvys only. No load, trip, or driver data is sent back to OneStepGPS.

## Prerequisites

Before you can connect OneStepGPS to Alvys, confirm the following:

* You have an active OneStepGPS account with GPS-equipped trucks or trailers.
* You have the Admin, Partner Admin, or Support role in Alvys (required to access the Integrations tab in Company Profile).
* You have the truck number for each asset you want to map, exactly as it appears in your OneStepGPS portal.
* You have emailed [integration@onestepgps.com](mailto:integration@onestepgps.com) to request an API key. Include a brief description of your intended use (integration with Alvys TMS). OneStepGPS will send your API key by reply — keep it ready before proceeding.

## How to connect

1. Navigate to Company Profile. Click your profile icon in the lower-left corner of Alvys. From the menu that appears, select the subsidiary you want to configure. Then click the **Integrations** tab.
2. Open the OneStepGPS ELD settings. Expand the **ELD** section on the Integrations tab. Locate the OneStepGPS card and click the pencil (edit) icon.

   <img alt="ELD section on the Integrations tab, showing the OneStepGPS card with pencil edit icon highlighted." />

   *ELD section on the Integrations tab, showing the OneStepGPS card with pencil edit icon highlighted.*
3. Enter your API key and save. Enter your OneStepGPS **API Key** in the field provided, then click **Save**.

   <img alt="OneStepGPS API Key input field and Save button on the ELD integration settings screen." />

   *OneStepGPS API Key input field and Save button on the ELD integration settings screen.*

   Alvys will verify your API key immediately. If the key is accepted, the integration status updates to active. If Alvys shows a validation error, your API key is incorrect — request a replacement key from OneStepGPS.

   After the integration is active, link each physical truck or trailer in Alvys to its corresponding asset in OneStepGPS. Alvys uses the truck number from OneStepGPS as the Integration ID to match location signals to the correct asset.
4. Open the asset you want to configure. Go to **Assets** in the left navigation menu and select **Trucks** or **Trailers**.

   Go to **Assets** in the left menu and select **Trucks** or **Trailers**.

   <img alt="Left navigation menu showing Assets section with Trucks and Trailers options." />

   *Left navigation menu showing Assets section with Trucks and Trailers options.*

   Double-click the truck or trailer you want to configure to open its asset profile.
5. Add the OneStepGPS integration to the asset. Scroll down to the **ELD Integrations** section on the asset profile and click **Add Integration**. From the provider dropdown, select **OneStepGPS**. In the **Integration ID** field, enter the truck number exactly as it appears in your OneStepGPS portal. Click **Save**.

   <img alt="Asset profile ELD Integrations section with OneStepGPS selected in the provider dropdown and Integration ID field." />

   *Asset profile ELD Integrations section with OneStepGPS selected in the provider dropdown and Integration ID field.*

Repeat the asset steps above for every truck or trailer you want to track.

## What syncs

* Location data flows from OneStepGPS to Alvys only. No data is sent from Alvys back to OneStepGPS.
* Once an asset is mapped, its position updates automatically based on location updates from OneStepGPS.
* Location data appears on the **Asset Map** (Assets > Map) and in dispatch planning views.
* Only GPS position data (location) is pulled from OneStepGPS. Hours of service, driver behavior scores, and other OneStepGPS data points are not imported into Alvys.

To confirm the integration is working, go to **Assets > Map** in the left navigation, locate the truck or trailer you configured, and confirm the **Address** field shows a recent location.

## Troubleshooting

### Asset shows no location or stale location after setup

1. Confirm the integration is active: open your company profile, open the **Integrations** tab, expand the **ELD** section, and verify the OneStepGPS card shows an active status.
2. Confirm the asset is mapped: open the asset profile (Assets > Trucks or Trailers > double-click the asset), scroll to the **ELD Integrations** section, and verify OneStepGPS is listed with an Integration ID.
3. Confirm the truck number in the Integration ID field matches exactly what appears in your OneStepGPS portal; a mismatch will cause location data to fail silently.
4. Confirm the GPS device on the asset is powered on and transmitting in OneStepGPS by logging in to your OneStepGPS portal.
5. If the asset shows a current location in your OneStepGPS portal but not in Alvys after completing these checks, contact Alvys support.

### Validation error when saving the API key

Confirm you are entering the API key exactly as provided by OneStepGPS, with no extra spaces at the beginning or end. If the key may have expired, email [integration@onestepgps.com](mailto:integration@onestepgps.com) to request a fresh API key, then re-enter it.

## FAQs

**Q: Where do I find my OneStepGPS truck numbers?**

**A:** Your truck numbers are available in your OneStepGPS portal. Log in to OneStepGPS and look up each asset to find the number as it appears there — this is the value to enter in the Integration ID field in Alvys.

**Q: Can I track both trucks and trailers with OneStepGPS?**

**A:** Yes. You can add the OneStepGPS integration to both trucks and trailers by completing the asset mapping steps for each asset type.

**Q: What happens if I enter an incorrect API key?**

**A:** Alvys verifies the key at the time you click Save. If the API key is incorrect, you will see a validation error immediately and the integration will not activate. Correct the key and try again.

**Q: Do I need to repeat the setup for each subsidiary?**

**A:** Yes. The integration is configured at the subsidiary level. Navigate to each subsidiary's Company Profile and complete the setup steps separately for each one.

## Go Deeper

* [Asset Map](/en/help/assets-fleet/asset-map)


# Connect Orbcomm Platform to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-orbcomm-platform-to-alvys

Connect the Orbcomm Platform to Alvys to sync trailer location, temperature, and reefer status data into the Asset Map for tracking refrigerated freight.

<Note>
  The Orbcomm Platform integration connects your Orbcomm-equipped trailers to Alvys, automatically pulling trailer location, temperature, and reefer status data into the Asset Map and dispatch planning.
</Note>

## Overview

The Orbcomm Platform integration, also called Orbcomm telematics or Orbcomm asset tracking, connects your Orbcomm-equipped trailers to Alvys, automatically pulling trailer location, temperature, and reefer status data into the Asset Map and dispatch planning. The integration is one-way: Orbcomm sends trailer location and temperature data to Alvys.

Once connected, Alvys automatically syncs trailer location data and reefer temperature readings so you can monitor assets on the Asset Map and use live location in dispatch planning. This integration supports trailers only. Trucks are not tracked through Orbcomm Platform. Hours of Service (HOS) monitoring and IFTA reporting are not available through this integration.

<Warning>
  ⚠️ The older Orbcomm Cargowatch integration is no longer supported. All customers must use the current Orbcomm Platform integration described in this article.
</Warning>

## Prerequisites

Before you can connect Orbcomm Platform to Alvys, you need:

* An active Orbcomm account with a designated Orbcomm Customer Success Manager
* Integration credentials from Orbcomm (a Username, Password, and Org Key, provided after an integration request is submitted to Orbcomm)
* The Orbcomm Asset ID for each trailer you want to track (available in your Orbcomm portal)
* An **"Admin"**, **"Partner Admin"**, or **"Support"** role in Alvys

## How to connect

1. Request integration credentials from Orbcomm. Contact your Orbcomm Customer Success Manager and ask them to submit an integration request on your behalf. Once Orbcomm completes the setup, they will send you a Username, Password, and Org Key.
2. Open the Integrations tab in Alvys. Click your profile icon in the lower-left corner of Alvys to open **"Company Profile"**. Select the subsidiary you want to configure, then click the **"Integrations"** tab.
3. Open the Orbcomm Platform card. Scroll down to the **"ELD"** section and click the pencil (edit) icon on the **"Orbcomm Platform"** card.

   <img alt="ELD section showing the Orbcomm Platform card" />

   *ELD section showing the Orbcomm Platform card*
4. Enter your credentials and select subsidiaries. Enter your Orbcomm Platform **"Username"**, **"Password"**, and **"Org Key"**. Select the **"Subsidiaries"** whose assets will use this integration, then click **"Save"**.

   <img alt="Orbcomm Platform credentials dialog showing Username, Password, and Subsidiaries fields." />

   *Orbcomm Platform credentials dialog showing Username, Password, and Subsidiaries fields.*

Alvys validates your credentials when you click Save. If the credentials are correct, the integration becomes active.

### Link each trailer to its Orbcomm Asset ID

Each trailer in Alvys must be linked to its corresponding Orbcomm Asset ID individually. There is no automated field mapping.

1. Go to **"Assets"** in the left menu and select **"Trailers"**. Double-click the trailer you want to configure, then scroll down to the **"ELD Integrations"** section and click **"Add Integration"**.
2. Select **"OrbcommPlatform"** from the dropdown, enter the **"Orbcomm Asset ID"** in the Integration ID field, then click **"Save"**.

   <img alt="Trailer detail showing the ELD Integrations section with OrbcommPlatform selected in the dropdown and the Integration ID field." />

   *Trailer detail showing the ELD Integrations section with OrbcommPlatform selected in the dropdown and the Integration ID field.*

Repeat this process for each trailer you want to track with Orbcomm Platform.

### Verify it's working

After completing setup, confirm the integration is active:

1. Go to **"Assets > Trailers"** and open a trailer you configured.
2. Confirm that location and temperature data appear on the trailer detail page.
3. Navigate to the Asset Map (**"Assets > Map"**) and verify the trailer appears with a current location pin.

## What syncs

* **Direction:** One-way. Orbcomm sends data to Alvys; Alvys does not send any data back to Orbcomm.
* **Asset types synced:** Trailers only. Trucks are not supported by this integration.
* **Data synced per trailer:** GPS coordinates, speed, total distance, reefer operation mode, setpoint temperature (up to 3 zones), return air temperature (up to 3 zones), discharge/supply air temperature (up to 3 zones), remote probe temperatures (up to 3), ambient temperature, and reefer fuel percent.
* **HOS and IFTA:** Hours of Service monitoring and IFTA mileage reporting are not available through Orbcomm Platform.

## Troubleshooting

### Credentials rejected when saving

1. Confirm the Username and Password were entered exactly as provided by Orbcomm, with no extra spaces.
2. Contact your Orbcomm Customer Success Manager to verify that the integration request was fully completed on their end and that your credentials are active.
3. If the credentials are confirmed correct and the error still appears, contact Alvys support.

### Trailer location not appearing on the Asset Map

1. Confirm the trailer has an Orbcomm Asset ID entered in the ELD Integrations section of its record.
2. Confirm the Orbcomm Asset ID matches exactly what is registered for that trailer in your Orbcomm portal.
3. Confirm the trailer is powered on and actively transmitting location data in your Orbcomm portal.
4. If the Asset ID is correct and the trailer is reporting in Orbcomm but not appearing in Alvys, contact Alvys support.

## FAQs

**Q: What happened to Orbcomm Cargowatch?**

**A:** The older Orbcomm Cargowatch integration is no longer supported. All customers must use the current Orbcomm Platform integration. Contact your Orbcomm Customer Success Manager to obtain the credentials needed for Orbcomm Platform.

**Q: Where do I find my Orbcomm Asset IDs?**

**A:** Your Orbcomm Asset IDs are available in your Orbcomm portal. You can also request them from your Orbcomm Customer Success Manager.

**Q: Does this integration support trucks as well as trailers?**

**A:** No. The Orbcomm Platform integration supports trailers only. Trucks are not tracked through this integration.

**Q: What happens if I enter incorrect credentials?**

**A:** Alvys validates credentials when you click Save. An error appears immediately if the credentials are incorrect; the integration will not be saved until valid credentials are entered.

**Q: Can I use Orbcomm Platform across multiple subsidiaries?**

**A:** Yes. When configuring the integration, you select which subsidiaries will use it. All trailers mapped with Orbcomm Asset IDs under those subsidiaries are tracked.


# Connecting Power BI to Alvys Public API
Source: https://docs.alvys.com/en/help/integrations/connecting-power-bi-to-alvys-public-api

Connect Microsoft Power BI to the Alvys Public API using client credentials to build live dashboards, run POST queries, and visualize load and driver data.

<Note>
  Connect Power BI to the Alvys Public API to pull live operational data into Power BI dashboards and reports using GET and POST methods for filtering and retrieval.
</Note>

## Overview

This integration connects Microsoft Power BI (also called Power BI, PowerBI, Microsoft Power BI, or business intelligence) to the Alvys Public API (OData/REST API) so you can pull live operational data into Power BI for reporting and analytics. Once connected, Power BI retrieves data from Alvys in real time so you can build up-to-date dashboards and use Power BI's visualization tools to represent Alvys data. The connection supports both GET requests for basic data retrieval and POST methods for advanced searches, which add filtering, date range selection, and status-based queries that go beyond basic reporting. The data moves in one direction only: from Alvys into Power BI. With access to endpoints such as Loads, Drivers, Fuel, Invoices, Trips, and Trucks, you can explore data across multiple operational areas and generate analytics tailored to your needs.

## Prerequisites

Before you connect Power BI to Alvys, make sure you have the following. Your account has one of the required roles: generating and managing Alvys Public API credentials requires the **Admin** or **Partner Admin** role. Your Alvys API credentials are ready: you need your Client ID, Tenant ID, and Client Secret from the Alvys platform, generated under Profile then API. Power BI Desktop is installed with the latest version available. Power BI privacy settings are configured to disable privacy checks, so the API integration runs smoothly.

## How to Connect?

1. In the Alvys platform, go to Profile then API to open the Public API page.
2. Locate your API credentials on that page. You need the Client ID, Tenant ID, and Client Secret. These three values authenticate Power BI to the Alvys Public API.
3. Generate an API token. The token authenticates each request that Power BI sends to the Alvys API endpoints.
4. Open Power BI Desktop and confirm you are on the latest version.
5. In Power BI Desktop, configure your settings to disable privacy checks so the API integration runs without interruption.
6. Use your credentials and token to connect Power BI to the Alvys Public API endpoints you want to report on.

For full setup and configuration details, including query examples and a preconfigured Power BI file for quick integration, use the [Alvys Public API documentation](https://docs.alvys.com/en/api/guides/connecting-power-bi-to-alvys-public-api-guide).

## What Syncs?

Power BI pulls data from individual Alvys Public API endpoints, and each endpoint maps to an operational area in Alvys. The Loads Search endpoint returns load data and lets you filter loads by criteria such as date and status. The Drivers Search endpoint returns driver details and lets you query by fleet or status. The Fuel Search endpoint returns fuel transaction histories. The Invoices Search endpoint returns invoice data and lets you retrieve invoices by date or status. Additional endpoints are available for Trips and Trucks, so you can pull data across multiple operational areas into Power BI.

The connection is one-way and on-demand. Power BI retrieves data from the Alvys Public API in real time when you run or refresh a query, so your Power BI dashboards reflect current Alvys data at the time of retrieval. GET requests handle basic data retrieval. POST methods handle advanced searches, including filtering by status or by date ranges. Data flows only from Alvys into Power BI; nothing is written back to Alvys.

### Verify it is working

1. In Power BI Desktop, run a query against one of the Alvys endpoints, such as Loads Search.
2. Confirm that Alvys data loads into Power BI without an authentication or privacy error.
3. Build a simple visualization from the returned data to confirm the fields populate as expected.

## Troubleshooting

### Power BI cannot authenticate to the Alvys API

1. Confirm you are signed in to Alvys with the **Admin** or **Partner Admin** role, since only these roles can generate and manage Public API credentials.
2. Go to Profile then API and confirm your Client ID, Tenant ID, and Client Secret are correct and copied without extra spaces.
3. Generate a fresh API token and use it for your requests.

### Power BI blocks the connection with a privacy error

1. Open Power BI Desktop settings.
2. Disable privacy checks so Power BI allows the Alvys API connection to run.
3. Re-run your query.

### A query returns no data or limited results

1. Confirm you are using a POST method when you need filtering, date range, or status-based searches, since GET requests only return basic data.
2. Check your filter, date range, and status values against the query examples in the Alvys Public API documentation.

### Limits and unsupported

This is a one-way, read-only connection. Power BI pulls data from Alvys and cannot write or push data back into Alvys. Advanced filtering, date range selection, and status-based queries require POST methods. GET requests support basic data retrieval only.

## FAQs

**Q: Can I use Power BI to connect directly to the Alvys API?**

**A:** Yes. The Alvys Public API supports integration with Power BI and enables both GET and POST methods for retrieving data.

**Q: Why use POST methods with Power BI?**

**A:** GET requests allow basic data retrieval. POST methods unlock advanced search capabilities, including filtering by status or by date ranges.

**Q: Where can I find my API credentials?**

**A:** Your API credentials (Client ID, Tenant ID, and Client Secret) are available under Profile then API on the Alvys platform.


# Connect RoadStar to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-roadstar-to-alvys

Connect RoadStar ELD to Alvys to pull real-time truck and trailer locations and driver Hours of Service data into the Asset Map and Dispatch Planner.

<Note>
  RoadStar is an ELD solution that tracks driver Hours of Service and vehicle locations. Connect RoadStar to Alvys to view real-time truck and trailer locations on the Asset Map and in the Dispatch Planner. Also referred to as RoadStar ELD, RoadStar telematics, or RoadStar tracking.
</Note>

## Overview

RoadStar is an electronic logging device (ELD) solution that tracks driver Hours of Service and vehicle locations. Connecting RoadStar to Alvys lets you view real-time truck and trailer locations on the Asset Map and in the Dispatch Planner. This integration is also referred to as RoadStar ELD, RoadStar telematics, or RoadStar tracking.

The RoadStar integration pulls real-time location and driver Hours of Service (HOS) data from your RoadStar-equipped trucks and trailers into Alvys. Once connected, Alvys displays asset positions on the Asset Map, shows HOS clocks in the Asset Map asset panel and in the Dispatch Planner sidebar, and makes location data available for dispatch planning.

This is a one-way integration: RoadStar sends data to Alvys. Alvys does not write data back to RoadStar.

## Prerequisites

Before you begin, confirm the following:

* You have an active RoadStar account with the ability to generate tokens.
* Your trucks and trailers are registered in your RoadStar account.
* You are signed in to Alvys with the **"Admin"** or **"Partner Admin"** role.

## How to connect?

Setting up the integration requires three parts: generating a token in RoadStar, entering that token in Alvys, then mapping each asset to its RoadStar asset ID.

### Generate a token in RoadStar

* Log into your RoadStar account.
* Navigate to **"Management"**, then select **"API Tokens"**.
* Click **"Generate Token"**.

<Note>
  <img alt="RoadStar API Tokens screen showing the Generate Token button" />

  *RoadStar API Tokens screen showing the Generate Token button*
</Note>

* Enter a name for the token (for example, "Alvys Integration") and click **"OK"**.
* The page refreshes and displays the new token. Copy this token; you will need it in the next part.

### Enter the token in Alvys

* In Alvys, click your profile icon in the lower-left corner to open **"Company Profile"**.

<Note>
  <img alt="Image showing navigation to the Alvys Integrations page" />

  \*Image showing navigation to the Alvys Integrations page \*
</Note>

* If your account has multiple subsidiaries, select the subsidiary you want to configure.
* Click the **"Integrations"** tab.
* Expand the **"ELD"** section.

<Note>
  <img alt="Image showing ELD tab expanded on the Alvys Integrations page" />

  \*Image showing ELD tab expanded on the Alvys Integrations page \*
</Note>

* Click the “**Inactive**” button on the RoadStar card.
* Paste your RoadStar token into the **"API Token"** field.
* Click **"Save"**.

<Note>
  <img alt="Image showing the Alvys “Add Integration” form for RoadStar Eld" />

  \*Image showing the Alvys “Add Integration” form for RoadStar Eld \*
</Note>

Alvys validates the credentials immediately. If the token is valid, the integration becomes active. If the token is rejected, Alvys displays an error — re-generate the token in RoadStar and try again.

### Map each asset to its RoadStar asset ID

After the integration is active, you must link each truck or trailer in Alvys to its corresponding record in RoadStar using the RoadStar asset ID. This mapping tells Alvys which RoadStar asset to pull location data from for each vehicle.

To find a RoadStar asset ID: open the asset in your RoadStar account and look at the URL. The number at the end of the URL path is the asset ID. For example, if the URL is [app.brightroadstar.com/client/trucks/25236](http://app.brightroadstar.com/client/trucks/25236), the asset ID is 25236.

1. Go to **"Assets"** in the left navigation menu and select **"Trucks"** or **"Trailers"**.
2. Double-click the asset you want to configure to open its profile.
3. Scroll down to the **"ELD Integrations"** section and click **"Add Integration"**.
4. Select **"RoadStar"** from the dropdown.
5. Enter the RoadStar asset ID in the **"Integration ID"** field.
6. Click **"Save"**.

<Note>
  <img alt="Image showing “Add Integration” dropdown on asset profile" />

  \*Image showing “Add Integration” dropdown on asset profile \*
</Note>

Repeat for each truck or trailer you want to track.

## What syncs?

* Data flows one way: from RoadStar to Alvys.
* Alvys receives location updates as RoadStar transmits them from the ELD device.
* Both trucks and trailers can be mapped for location tracking.
* Driver Hours of Service (HOS) clocks from RoadStar are visible on the Asset Map asset panel and in the Dispatch Planner sidebar. HOS data is not currently surfaced within individual load or trip records.
* Each asset must be mapped individually; there is no bulk-import of asset IDs.

  **What is not supported:**
* Alvys does not send data back to RoadStar. Changes made in Alvys (such as driver assignments) are not synced to RoadStar.
* Each asset must be mapped individually. There is no bulk configuration option.
* Driver HOS data from RoadStar is visible on the Asset Map asset panel and in the Dispatch Planner sidebar. It is not currently surfaced within individual load or trip records.

  **To verify the integration is working after completing setup and mapping at least one asset:**

1. Go to **"Assets"** > **"Map"** in the left navigation menu.
2. Confirm the mapped trucks and trailers appear on the Asset Map with current location data.
3. Click on a mapped asset to view its location details, including the **"Last Modified"** timestamp that shows when the position was last received from RoadStar.

## Troubleshooting

### Token rejected on save

1. Confirm you copied the full token from RoadStar without any extra spaces.
2. Return to your RoadStar account under **"Management"** > **"API Tokens"** and generate a new token.
3. Enter the new token in the Alvys Company Profile > **"Integrations"** tab > ELD section and click **"Save"**.

### Asset not appearing on the Asset Map after mapping

1. Confirm the asset ID you entered matches the number in the asset's URL in your RoadStar account.
2. Verify the ELD device on the truck or trailer is powered on and transmitting.
3. Check the **"Last Modified"** timestamp on the asset's sidebar in the Asset Map — if the timestamp is recent, the device is transmitting. If it is stale, the device may be offline.
4. If none of these conditions apply, contact Alvys support for assistance.

### Integration card not visible in Company Profile

1. Confirm you are signed in with the **"Admin"** or **"Partner Admin"** role. The ELD integration settings are only visible to Admins and Partner Admins.
2. Confirm you are on the correct subsidiary. Integration settings are configured per subsidiary.

## FAQs

**Q: Where do I find my RoadStar asset IDs?**

**A:** Open the asset in your RoadStar account and look at the URL. The number at the end of the URL path is the asset ID. For example, in the URL [app.brightroadstar.com/client/trucks/25236](http://app.brightroadstar.com/client/trucks/25236), the asset ID is 25236.

**Q: Can I track both trucks and trailers with this integration?**

**A:** Yes. You can add the RoadStar integration to both trucks and trailers. Configure each asset individually by following the mapping steps in the How to connect section above.

**Q: What happens if I enter an invalid token?**

**A:** Alvys validates the token immediately when you click Save. If the token is incorrect, you will see an error message right away. Generate a new token in RoadStar and re-enter it in Alvys.

**Q: Do I need to reconnect the integration if I generate a new token in RoadStar?**

**A:** Yes. If you regenerate your token in RoadStar, you must update it in Alvys as well. Go to Company Profile > Integrations tab > ELD section, click the pencil icon on the RoadStar card, enter the new token, and click Save.

## Go Deeper

* [Asset Map](/en/help/assets-fleet/asset-map)


# Connect Samsara to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-samsara-to-alvys

Connect Samsara ELD and telematics to Alvys to pull live locations, HOS clocks, IFTA mileage, and reefer temperature data from your trucks and trailers.

## Overview

The Samsara integration connects your ELD and telematics data to Alvys, enabling real-time truck and trailer location tracking, Hours of Service (HOS) monitoring, IFTA mileage reporting, and temperature sensor data for refrigerated trailers. Setup requires generating a token in Samsara and then linking each asset in Alvys. This integration is also referred to as Samsara ELD tracking, Samsara telematics, or Samsara fleet tracking. Data flows one way from Samsara into Alvys. Alvys does not send load or dispatch data back to Samsara through this integration.

## Prerequisites

Before setting up the Samsara integration, confirm the following:

* You have an active Samsara account with administrator access.
* You are signed in to Alvys with the **"Admin"**, **"Partner Admin"**, or **"Support"** role. Users without one of these roles cannot access the Integrations page.
* Your subsidiaries are already configured in Alvys. The integration is applied per subsidiary, so all subsidiaries that have Samsara-equipped assets must exist in Alvys before you connect.
* Your trucks and trailers are already set up in Alvys before you complete the asset ID step (step 3 below).

## How to connect?

Setting up the integration involves three parts: generating a token in Samsara, configuring the integration in Alvys, then adding Samsara asset IDs to each truck and trailer.

### Generate a Samsara token

1. Log in to your Samsara account and go to **"Settings"**.
2. Select the **"Apps"** tab.
3. Find **"Alvys"** in the list of apps and click its card.
4. Click **"Enable"**.

   <img alt="Samsara Apps page, Alvys card with Enable button." />

   *Samsara Apps page, Alvys card with Enable button.*
5. Samsara will prompt you to accept the **"Samsara Data Import and Sharing Addendum"** terms. Accept the terms to continue.

   <img alt="Samsara Data Import and Sharing Addendum acceptance screen." />

   *Samsara Data Import and Sharing Addendum acceptance screen.*
6. Samsara will display a token in the next window. Copy this token — you will need it when you configure the integration in Alvys.

<Note>
  <img alt="Samsara token generation window." />

  *Samsara token generation window.*
</Note>

### Configure Samsara in Alvys

1. In Alvys, navigate to **"Management"** > **"Integrations"**.
2. Under the **"ELD"** tab, find **"Samsara"** and click the blue **"Integrate"** button.
3. In the **"Add Integration"** window, use the drop-down menu to select **"Samsara"**.
4. Paste the token you copied from Samsara into the **"API Key"** field.
5. Select the subsidiaries that Samsara will be used for. To apply the integration to all subsidiaries, check **"All Subsidiaries"**.
6. Click the blue **"Save"** button.

### Add Samsara asset IDs to trucks and trailers

Before beginning, confirm that all trucks and trailers you want to connect are already set up in Alvys.

1. In Alvys, select **"Assets"** from the left menu, then choose either **"Trucks"** or **"Trailers"**.
2. From the asset list, find the asset you want to configure and double-click it to open the **"Edit Asset"** page.
3. Scroll down to the **"ELD Integrations"** section and click the blue **"Add Integration"** button.
4. In the **"Add Integration"** window, select **"Samsara"** from the drop-down menu.
5. Find the Samsara asset ID. The ID is located in the URL when you view the asset in Samsara. For example, in the URL [https://cloud.samsara.com/o/25542/devices/281474978231471/vehicle](https://cloud.samsara.com/o/25542/devices/281474978231471/vehicle), the asset ID is **281474978231471** (the number in the devices section of the URL).

   <img alt="Example Samsara asset URL with asset ID highlighted" />

   *Example Samsara asset URL with asset ID highlighted*
6. Paste the asset ID into the **"Integration ID"** field.
7. For trailers: fill in the **"Asset ID"** only. Leave the **"Sensor ID"** field blank. Once you save the asset ID, Alvys will automatically connect all associated external sensors, including temperature and door sensors.
8. Click the blue **"Save"** button.
9. Repeat these steps for each remaining truck and trailer.

## What syncs?

Samsara sends the following data types to Alvys through this integration:

* Location data: real-time GPS position of trucks and trailers, displayed on the Alvys asset map.
* Hours of Service (HOS): driver HOS records from Samsara-equipped trucks, used for compliance visibility in dispatch planning.
* IFTA mileage: state-by-state mileage data pulled from Samsara and used in the Alvys IFTA reporting module.
* Temperature and door sensor data: for refrigerated trailers, Samsara transmits temperature readings and door open/close events. These are connected automatically when you save a trailer's asset ID — no separate sensor ID entry is needed.

  The asset ID entered in Alvys must match the Samsara asset ID visible in the URL when you view the asset in Samsara. Mismatched IDs will prevent data from flowing to that asset.

  **How sync behaves:**
* Samsara data flows into Alvys on an ongoing basis once an asset ID is saved and the integration is active for the relevant subsidiary.
* Each asset must be linked individually with its Samsara asset ID. Linking the integration at the subsidiary level does not automatically link individual assets.
* If a driver assigned to a trip is not linked to your Samsara account, Alvys displays a warning during trip assignment. Tablet-based workflows will not be available for that trip: stop tasks, document uploads, and forms are disabled when the driver is not linked to Samsara.
* The Samsara integration supports all subsidiaries in your Alvys account. Selecting **"All Subsidiaries"** when configuring the integration applies the token across all of them.

### What is not supported:

* The **"Sensor ID"** field for trailers is not used with Samsara. Leave it blank; all associated sensors connect automatically through the asset ID.
* Samsara data does not flow back from Alvys to Samsara. Load assignments, stop updates, and dispatch changes in Alvys are not sent to Samsara.
* Each asset must be linked individually. There is no bulk import of Samsara asset IDs.
* The Samsara integration is available only to subsidiaries explicitly selected during the Integrate step. Assets belonging to a subsidiary that was not selected will not receive data.

### To verify the integration is active after setup:

1. Navigate to **"Management"** > **"Integrations"** and confirm that Samsara appears as connected under the **"ELD"** tab.
2. Open an asset (truck or trailer) that you linked with a Samsara asset ID and confirm the **"ELD Integrations"** section shows Samsara as an active integration.
3. Check the Alvys asset map to confirm that the truck or trailer is showing a location.
4. If you are using Samsara for IFTA reporting, navigate to the IFTA module and confirm that ELD mileage data appears for the relevant trucks.

## Troubleshooting

### Samsara does not appear under the ELD tab in Management > Integrations

1. Confirm you are signed in with an **"Admin"**, **"Partner Admin"**, or **"Support"** role. Users without these roles cannot access the Integrations page.
2. Confirm that your Alvys account has the Samsara integration enabled. If you do not see Samsara listed, contact Alvys support to verify that the integration is available for your account.

### ELD data is not flowing to an asset

1. Open the asset in Alvys and verify that Samsara is listed in the **"ELD Integrations"** section with the correct asset ID saved.
2. Confirm that the asset ID in Alvys matches the Samsara asset ID visible in the URL when you view the asset in Samsara. The ID must be entered exactly as it appears in the URL.
3. Confirm that the subsidiary this asset belongs to was selected when you saved the Samsara integration. If the subsidiary was not included, edit the integration and add it.
4. If all of the above are correct and data is still not appearing, contact Alvys support.

### Samsara token is not accepted in Alvys

1. Confirm that you accepted the Samsara Data Import and Sharing Addendum when generating the token. Tokens generated without accepting the addendum may not carry the required permissions.
2. Confirm that all required granular scope permissions were enabled when generating the token in Samsara. If any permissions were missing, edit your existing token in Samsara to add them — the token value will remain the same.
3. If the token was generated but then revoked or expired in Samsara, generate a new token and update the API Key field in Alvys.

### Driver assignment shows a Samsara warning

When Alvys displays the message that a driver is not linked to your Samsara account and that tablet-based workflows will not be available, this means the driver's record in Alvys is not matched to a driver in your Samsara account. Check that the driver exists in Samsara and that their record in Alvys is correctly linked. If the driver should not be linked to Samsara for that subsidiary, the warning can be disregarded.

## FAQs

**Q: What happens if I don't enable all the granular scope permissions when generating the token?**

**A:** ELD data from Samsara will not flow into Alvys. Make sure all required permissions are enabled when generating your token in Samsara.

**Q: Do I need to create a new token if I need to add the Sensors: Write permission?**

**A:** No, you can edit your existing token in Samsara to add the Sensors: Write permission. The token value will remain the same after editing.

**Q: How do I find my Samsara asset IDs for trailers with temperature sensors?**

**A:** The asset ID is the number visible in the URL when you view the trailer in Samsara (for example, 281474978231471 from [https://cloud.samsara.com/o/25542/devices/281474978231471/vehicle](https://cloud.samsara.com/o/25542/devices/281474978231471/vehicle)). Once you save that ID in Alvys, all associated sensors — including temperature and door sensors — will connect automatically.

**Q: Can I use the same Samsara token for multiple subsidiaries?**

**A:** Yes. When you add the Samsara integration in Alvys, you can select multiple subsidiaries or choose All Subsidiaries. A single token covers all subsidiaries you select.

**Q: Why is the ELD Integrations section not visible on an asset page?**

**A:** The ELD Integrations section appears on every truck and trailer page. If you cannot see it, scroll down on the Edit Asset page — the section is located below the main asset details. If the section is missing entirely, contact Alvys support.

## Go Deeper

* [IFTA Reports](/en/reporting/reports/overview)


# Connect SkyBitz to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-skybitz-to-alvys

Connect SkyBitz to Alvys to pull real-time GPS location data for tracked trucks, trailers, and containers into the Asset Map for dispatch visibility.

<Note>
  The SkyBitz integration automatically pulls real-time GPS location data from your SkyBitz-equipped trucks and trailers into Alvys: also known as SkyBitz GPS tracking, SkyBitz asset tracking, or SkyBitz telematics.
</Note>

## Overview

The SkyBitz integration lets Alvys automatically pull real-time GPS location data from your SkyBitz-equipped trucks and trailers, making those assets visible on the Asset Map and available for dispatch planning — no manual location updates required. This integration is also referred to as SkyBitz GPS tracking, SkyBitz asset tracking, or SkyBitz telematics.

SkyBitz is a GPS telematics provider for asset tracking specializing in trailer and container location monitoring. Once the integration is active and your assets are mapped, live positions appear on the Alvys Asset Map and update continuously as your trucks and trailers move.

Setting up the integration involves two stages: connecting your SkyBitz account credentials in Alvys, then mapping each truck or trailer to its corresponding SkyBitz unit number.

## Prerequisites

Before you begin:

* You must have an active SkyBitz account. You need your SkyBitz **"Client ID"** and **"Secret"** — these are provided by SkyBitz and are separate from your portal login.
* Your role in Alvys must be **"Admin"**, **"Partner Admin"**, or **"Support"** to access the Integrations settings.

If you do not have your Client ID and Secret, contact SkyBitz at [customercare.skybitz@ametek.com](mailto:customercare.skybitz@ametek.com) and request credentials for your account.

## How to connect

Setting up the integration involves three parts: opening the SkyBitz settings, entering your credentials, then mapping each asset to its SkyBitz unit number.

### Open the SkyBitz integration settings in Alvys

1. Click your profile icon in the lower-left corner of Alvys.
2. From the menu that appears, select the subsidiary you want to configure.
3. Click the **"Integrations"** tab.
4. Expand the **"ELD"** section and locate the SkyBitz card.
5. Click the pencil icon on the SkyBitz card to open the credential entry form.

<Note>
  <img alt="ELD section of the Integrations tab showing the SkyBitz card with pencil icon" />

  *ELD section of the Integrations tab showing the SkyBitz card with pencil icon*
</Note>

### Enter your SkyBitz credentials

1. Enter your SkyBitz **"Client ID"** in the Client ID field.
2. Enter your **"Secret"** in the Secret field.
3. Click **"Save"**.

Alvys validates the credentials immediately. If the credentials are correct, the integration becomes active. If they are incorrect, an error message appears and no data is saved — correct the credentials and try again.

### Map each asset to its SkyBitz unit number

After the credentials are saved and the integration is active, you need to tell Alvys which SkyBitz unit corresponds to each truck or trailer in your fleet.

1. Go to **"Assets"** in the left navigation and select **"Trucks"** or **"Trailers"**.
2. Double-click the asset you want to configure to open its profile.
3. Scroll down to the **"ELD Integrations"** section and click **"Add Integration"**.
4. In the Add Integration dialog, select **"SkyBitz"** from the provider dropdown.
5. Enter the SkyBitz unit number for that asset in the **"Integration ID"** field.
6. Click **"Save"**.

<Note>
  <img alt="Asset profile showing the ELD Integrations section with the Add Integration button and SkyBitz unit number field" />

  *Asset profile showing the ELD Integrations section with the Add Integration button and SkyBitz unit number field*
</Note>

Repeat this process for each truck or trailer you want to track with SkyBitz.

## What syncs

The SkyBitz integration is one-way: SkyBitz sends GPS location data to Alvys. Alvys does not write any data back to SkyBitz. Location updates flow in continuously as long as the integration is active and the SkyBitz device on the asset is powered and transmitting. Mapped assets display their current location on the Alvys Asset Map.

What is not supported:

* The SkyBitz integration supports GPS location tracking only. Hours of Service data, IFTA mileage reporting, and driver vehicle inspection reports are not available through SkyBitz.
* SkyBitz is primarily a trailer and container tracking solution. While trucks can be configured with SkyBitz unit numbers, driver workflow features such as pre-trip inspections and HOS logs require a separate ELD integration.
* Each asset can have only one SkyBitz unit number mapped to it. To reassign an asset to a different SkyBitz unit, remove the existing mapping first, then add the new one.
* The integration credentials are configured per subsidiary. If your Alvys account includes multiple subsidiaries, you must configure SkyBitz separately for each subsidiary that uses SkyBitz-equipped assets.

To verify the integration is working after saving the unit number mapping, go to **"Assets"** > **"Map"** in the left navigation to open the Asset Map. Locate the asset you just configured. If the integration is working correctly, the asset should display its current GPS position.

## Troubleshooting

### Asset does not appear on the Asset Map after mapping

1. Confirm that the SkyBitz unit number entered in the Integration ID field matches the unit number shown in your SkyBitz portal.
2. Check that the integration credentials are still active by returning to Company Profile > Integrations, expanding the ELD section, and confirming the SkyBitz card shows an active status.
3. Confirm the SkyBitz device on the asset is powered and transmitting.

If none of these conditions explain the issue, contact Alvys support.

### Credentials rejected when saving the integration

Alvys validates credentials at the time of saving. An error message at save time means the Client ID or Secret entered does not match an active SkyBitz account. Re-enter the credentials exactly as provided by SkyBitz.

## FAQs

**Q: Where do I find my SkyBitz unit numbers?**

**A:** Your SkyBitz unit numbers are available in your SkyBitz portal. If you do not have portal access, contact SkyBitz at [customercare.skybitz@ametek.com](mailto:customercare.skybitz@ametek.com).

**Q: Can I track both trucks and trailers with SkyBitz?**

**A:** Yes. You can add SkyBitz unit number mappings to both truck profiles and trailer profiles.

**Q: What happens if I enter invalid credentials?**

**A:** Alvys validates credentials at the time you click Save. If the Client ID or Secret is incorrect, an error message appears immediately and nothing is saved.

**Q: Do I need to configure SkyBitz for every subsidiary separately?**

**A:** Yes. Integration credentials are set per subsidiary.

## Go Deeper

* [Asset Map](/en/help/assets-fleet/asset-map)


# Connect TFM to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-tfm-to-alvys

Connect TFM ELD to Alvys with a token to pull real-time truck and trailer locations and driver Hours of Service data into your dispatch workflow.

<Note>
  TFM is a one-way ELD and telematics integration: TFM sends truck and trailer location and Hours of Service data to Alvys once assets are mapped.
</Note>

## Overview

TFM is an electronic logging device (ELD) solution, also known as a telematics or GPS tracking provider, that tracks driver Hours of Service and vehicle locations. The TFM integration lets Alvys pull live location data from your TFM-equipped trucks and trailers, giving you visibility on the Asset Map and in dispatch planning.

To complete setup, you will generate a token in your TFM account, configure the integration in Alvys, and then map each truck or trailer to its TFM asset ID.

## Prerequisites

Before connecting TFM to Alvys:

* You must have an active TFM account with permission to generate tokens.
* Each truck or trailer you want to track must already be set up in your TFM account.
* You must have the **"Admin"**, **"Partner Admin"**, or **"Support"** role in Alvys. These roles can access **Company Profile > Integrations**.
* If you manage multiple subsidiaries, complete the steps below once for each subsidiary you want to enable.

## How to connect

### Generate your TFM token

1. Log into your TFM account.
2. Navigate to **Management** and select **API Tokens**.
3. Click **Generate Token**.

   <img alt="TFM account: Management > API Tokens screen showing the Generate Token button." />

   *TFM account: Management > API Tokens screen showing the Generate Token button.*
4. Enter a token name (for example, "Alvys Integration") and click **OK**.

   <img alt="TFM token name entry dialog with OK button." />

   *TFM token name entry dialog with OK button.*
5. The page refreshes and displays your new integration token. Copy this token; you will need it in the next section.

### Enter your token in Alvys

1. In Alvys, click your profile icon in the lower-left corner to open **Company Profile**.
2. Select the subsidiary you want to configure.
3. Click the **Integrations** tab.
4. Expand the **ELD** section.
5. Click the pencil icon on the TFM card.

   <img alt="Alvys Integrations tab with ELD section expanded and TFM card pencil icon visible." />

   *Alvys Integrations tab with ELD section expanded and TFM card pencil icon visible.*
6. Enter your TFM **API Token** in the field provided.
7. Click **Save**.

Alvys validates your credentials immediately. If the token is accepted, the TFM integration becomes active for that subsidiary.

### Map each asset to its TFM asset ID

After the integration is active, you map individual trucks and trailers in Alvys to their corresponding asset IDs in TFM. This mapping tells Alvys which TFM asset to pull location data from for each vehicle.

The **Integration ID** field in Alvys corresponds to the asset ID in your TFM account. To find an asset's TFM ID, open the asset in your TFM account and look at the URL. The number at the end of the URL path is the asset ID. For example, if the URL is [app.tfmeld.com/client/trucks/25236](http://app.tfmeld.com/client/trucks/25236), the asset ID is 25236.

1. Go to **Assets** in the left navigation menu and select **Trucks** or **Trailers**.
2. Double-click the asset you want to configure to open its profile.
3. Scroll down to the **ELD Integrations** section and click **Add Integration**.
4. Select **TFM** from the dropdown.
5. Enter the TFM asset ID in the **Integration ID** field.
6. Click **Save**.

Repeat for each truck or trailer you want to track.

## What syncs / data flow

* Data flows one way: TFM sends location and Hours of Service data to Alvys. Alvys does not send data back to TFM.
* Once an asset is mapped, Alvys pulls its location automatically and displays it on the Asset Map and in dispatch planning.
* Each subsidiary's TFM integration is configured and synced independently.

### Verify it is working

1. Go to **Assets** in the left navigation and select **Trucks** or **Trailers**.
2. Open a truck or trailer you have mapped.
3. Confirm the **ELD Integrations** section shows TFM with the asset ID you entered.
4. Open the **Asset Map** in Alvys and confirm the truck or trailer is showing a current location.

<Note>
  📋 **Limits / unsupported:** Each subsidiary requires its own TFM token; a single token cannot be shared across subsidiaries. · Alvys does not write dispatch data, load assignments, or any other information back to TFM — the sync is one-way from TFM into Alvys. · Temperature sensor data from TFM is not surfaced in Alvys.
</Note>

## Troubleshooting

### Token rejected at save

1. Confirm you copied the full token from TFM without any leading or trailing spaces.
2. Return to your TFM account under **Management > API Tokens** and generate a new token, then re-enter it in Alvys.
3. If the error persists, confirm your TFM account has permission to create tokens. Contact Alvys support if none of these reasons apply.

### Asset location not appearing on the Asset Map after mapping

1. Confirm the asset ID you entered in Alvys matches exactly the number shown at the end of the URL path for that asset in your TFM account.
2. Confirm the asset is currently active and reporting in your TFM account.
3. Allow a few minutes for the first location update to sync after saving the mapping.
4. If the asset is active in TFM and the ID is correct but no location appears, contact Alvys support.

### ELD section or TFM card not visible in Alvys

1. Confirm you are signed in with an Admin, Partner Admin, or Support role. The Integrations tab is not visible to other roles.
2. Confirm you are viewing a subsidiary, not the top-level company profile.
3. If you have the correct role and are on a subsidiary but the TFM card is still not visible, contact Alvys support.

## FAQs

**Q: Where do I find my TFM asset IDs?**

**A:** Open the asset in your TFM account. The asset ID is the number at the end of the URL path. For example, if the URL is [app.tfmeld.com/client/trucks/25236](http://app.tfmeld.com/client/trucks/25236), the asset ID is 25236.

**Q: Can I track both trucks and trailers with TFM?**

**A:** Yes. You can add the TFM integration to both trucks and trailers by mapping each asset separately under Assets > Trucks or Assets > Trailers.

**Q: What happens if I enter an invalid token?**

**A:** Alvys validates credentials before saving. If the token is incorrect, you will see an error immediately and the integration will not activate.

**Q: Can I use TFM for multiple subsidiaries?**

**A:** Yes. Repeat the connection and asset mapping steps for each subsidiary. Each subsidiary requires its own TFM token configuration.

## Go Deeper

* [FleetLocate ELD/Telematics](/en/help/integrations/fleetlocate-eld-telematics-integration)
* [Samsara ELD/Telematics](/en/help/integrations/connecting-samsara-to-alvys)
* [ELD Rider ELD/Telematics](/en/help/integrations/eld-rider-eld-telematics-integration)


# Connect Verizon Connect to Alvys
Source: https://docs.alvys.com/en/help/integrations/connecting-verizon-connect-to-alvys

Connect Verizon Connect Reveal (formerly Fleetmatics) to Alvys to sync vehicle GPS locations and driver Hours of Service data for dispatchers and IFTA.

<Note>
  One-way ELD / telematics integration: Verizon Connect (formerly Fleetmatics) sends vehicle location and driver HOS data from Reveal into Alvys.
</Note>

## Overview

Verizon Connect (also known as Fleetmatics) is a fleet telematics platform that provides vehicle tracking and driver hours of service (HOS) monitoring. It is also referred to as an ELD, GPS tracking, or fleet management provider. This integration pulls real-time vehicle location and driver HOS data from Verizon Connect Reveal into Alvys, giving dispatchers visibility on the Asset Map and in the Dispatch Planner.

Setup has three stages: create a Reveal Integration User in the Verizon Connect Marketplace, enter those credentials in Alvys, then map each truck and driver to their corresponding Verizon Connect ID.

## Prerequisites

Before starting, confirm the following:

* You have an active Verizon Connect Reveal account with access to the Verizon Connect Marketplace.
* You have the developer email address where Verizon Connect will send the integration credentials.
* You have the **"Admin"**, **"Partner Admin"**, or **"Support"** role in Alvys. These roles can access **Company Profile > Integrations**.

## How to connect

### Create a Reveal Integration User in the Verizon Connect Marketplace

Before configuring the integration in Alvys, you must create a Reveal Integration User through the Verizon Connect Marketplace. This generates the credentials Alvys uses to pull your data.

1. Follow the steps in the [Verizon Connect Marketplace guide to create a self-service integration](https://reveal-help.verizonconnect.com/hc/en-us/articles/5491815998099-Create-self-service-API-integrations/).
2. Once completed, Verizon Connect sends your integration credentials to two places: the developer email address you provided and the user who initiated the request. Your credentials will look similar to: Username [AlvysTMS\_1234@1234567.com](mailto:AlvysTMS_1234@1234567.com) and Password PaSsWoRD.
3. Keep these credentials ready. You will enter them in the next section.

### Enter your credentials in Alvys

1. Click your profile icon in the lower-left corner of Alvys, then select **Company Profile**.
2. Select the subsidiary you want to configure.
3. Click the **Integrations** tab.
4. Expand the **ELD** section and click the pencil icon on the **Verizon Connect** card.
5. Enter the **Username** and **Password** from your Reveal Integration User credentials.
6. Click **Save**.

Alvys validates your credentials immediately on save. If the credentials are correct, the integration becomes active. If the credentials are invalid, an error appears and nothing is saved.

### Map trucks for location tracking

The vehicle number you enter in Alvys must exactly match the vehicle number listed in the Fleet Summary Report in your Verizon Connect portal. A mismatch prevents location data from appearing for that truck.

1. Go to **Assets** in the left menu and select **Trucks**.
2. Double-click the truck you want to configure.
3. Scroll down to the **ELD Integrations** section and click **Add Integration**.
4. Select **Verizon Connect** from the dropdown.
5. Enter the vehicle number (as it appears in your Fleet Summary Report) in the **Integration ID** field.
6. Click **Save**.

Repeat for each truck you want to track.

### Map drivers for HOS tracking

The driver number you enter in Alvys must exactly match the driver number listed in the ELD Drivers Report in your Verizon Connect portal. A mismatch prevents HOS data from appearing for that driver.

1. Go to **Assets** in the left menu and select **Drivers**.
2. Double-click the driver you want to configure.
3. Find the **ELD Providers** section and click **Add ELD**.
4. Select **Verizon Connect** from the dropdown.
5. Enter the driver number (as it appears in your ELD Drivers Report) in the **Integration ID** field.
6. Click **Save**.

Repeat for each driver who uses Verizon Connect for their hours of service.

## What syncs / data flow

* This integration is one-way: Alvys pulls data from Verizon Connect. No data is written back to Verizon Connect.
* Alvys pulls vehicle location data, odometer readings, and driver HOS clocks from Verizon Connect Reveal.
* Location and HOS data refresh automatically based on what Verizon Connect makes available. There is no manual sync trigger in Alvys.
* Vehicle location appears on the Asset Map and in relevant dispatch screens.
* Driver HOS clocks appear on load details and in the Dispatch Planner.

### Verify it is working

1. Go to **Company Profile > Integrations** and expand the **ELD** section. The Verizon Connect card should show an active status.
2. Go to **Assets > Map**. Trucks you mapped should show their current location if they are transmitting data from their ELD devices.
3. Open a load that has a mapped driver assigned. The driver's HOS clock should appear in the load details panel.

If location or HOS data is not appearing after completing all mapping steps, verify that the vehicle or driver number in Alvys matches the Verizon Connect portal exactly, including letter case and any leading or trailing characters.

<Note>
  📋 **Limits / unsupported:** Trailer location tracking follows the same mapping process as trucks — enter the trailer's vehicle number from Verizon Connect in the trailer's ELD Integrations section under Assets > Trailers. · Only one Verizon Connect integration can be active per subsidiary at a time.
</Note>

## Troubleshooting

### Credentials rejected on save

1. Confirm the username and password you entered match exactly what Verizon Connect sent to your developer email. Copy and paste rather than typing manually.
2. Check whether the Reveal Integration User was fully set up in the Verizon Connect Marketplace. If the request is still pending, the credentials will not yet be valid.
3. If the credentials are confirmed correct and setup is complete, contact Alvys support.

### Truck location not appearing on the Asset Map

1. Confirm the vehicle number entered in the truck's ELD Integrations section in Alvys exactly matches the vehicle number shown in the Fleet Summary Report from your Verizon Connect portal.
2. Confirm the truck's ELD device is powered on and transmitting. If the device is offline or not reporting, no location data will be available regardless of the mapping.
3. Check the Last Modified timestamp on the Asset Map sidebar for that truck. If it is stale, the device may not be transmitting.
4. If the mapping is correct and the device is transmitting, contact Alvys support.

### Driver HOS data not appearing

1. Confirm the driver number entered in the driver's ELD Providers section in Alvys exactly matches the driver number shown in the ELD Drivers Report from your Verizon Connect portal.
2. Confirm the driver is logged into their ELD device and actively generating HOS records.
3. If the mapping is correct and the driver is logged in, contact Alvys support.

## FAQs

**Q:** Where do I find my Verizon Connect vehicle and driver numbers?

**A:** Vehicle numbers are listed in the Fleet Summary Report in your Verizon Connect portal. Driver numbers are listed in the ELD Drivers Report. Use the exact values from those reports when mapping in Alvys.

**Q:** Can I track both vehicle locations and driver HOS with this integration?

**A:** Yes. Verizon Connect supports both vehicle location tracking and driver hours of service tracking in Alvys. Location and HOS are configured separately: trucks are mapped under Assets > Trucks, and drivers are mapped under Assets > Drivers.

**Q:** What happens if I enter invalid credentials?

**A:** Alvys validates the credentials immediately when you click Save. If the credentials are invalid, an error is shown and the integration is not saved. No partial or inactive integration is created.

**Q:** Do I need to re-enter credentials if I update my Reveal Integration User?

**A:** Yes. If your Verizon Connect credentials change, return to Company Profile > Integrations, expand the ELD section, click the pencil icon on the Verizon Connect card, enter the updated credentials, and click Save.

**Q:** What is Verizon Connect Reveal?

**A:** Verizon Connect Reveal is the fleet management platform (formerly known as Fleetmatics) that this integration connects to. Your Verizon Connect account must use the Reveal platform for this integration to function.

## Go Deeper

* [Asset Map](/en/help/assets-fleet/asset-map)


# DAT Rate Sharing Integration
Source: https://docs.alvys.com/en/help/integrations/dat-rate-sharing-integration

Connect DAT Rate Sharing to submit your booked lane rates to DAT daily over FTP, and troubleshoot submissions DAT did not receive.

<Note>
  📋 **Applies to:** Admins · Partner Admins

  **Module:** Management > Integrations

  **Provider:** DAT Solutions · **Integration type:** One-way · **Sync direction:** Alvys to DAT, via FTP, daily automated submission

  Connect your Alvys subsidiary to DAT Rate Sharing to automatically send daily rate data on invoiced loads to DAT via FTP. Participating carriers and brokers receive a discount and additional value from DAT in exchange for sharing this data. Also referred to as DAT rate submission or rate sharing integration.
</Note>

## Overview

DAT Rate Sharing (also called the DAT rate submission or rate sharing integration) is an automated daily integration. Once enabled for a subsidiary, Alvys generates a CSV report containing rate data from loads that were invoiced the previous day and uploads it to DAT via FTP each day at approximately 9:00 AM UTC.

DAT offers a discount and additional value to carriers and brokers that share rates with them through this automated submission. Each subsidiary that participates has its own DAT account credentials.

## Prerequisites

Before enabling DAT Rate Sharing in Alvys, you need credentials from DAT. Contact your DAT Sales Representative and request the credentials required for FTP submission. Each participating subsidiary will need its own set of credentials:

* DAT Account email: the email address of your main DAT account
* DAT Account ID: your unique account identifier from DAT
* FTP Username: provided by DAT
* FTP Password: provided by DAT

You must obtain these credentials from DAT before you can enable the integration in Alvys.

## How to connect

1. Navigate to the subsidiary integration settings. In Alvys, navigate to Management > Integrations. Open the settings for the subsidiary you want to enable DAT Rate Sharing for. Locate the DAT Rate Sharing integration section.
2. Enter your DAT credentials: DAT Account email, DAT Account ID, FTP Username, and FTP Password.
   <img alt="DAT Rate Sharing Integration Settings showing the Credentials fields (DAT Account email, DAT Account ID, FTP Username, FTP Password)." />
   *DAT Rate Sharing Integration Settings showing the Credentials fields (DAT Account email, DAT Account ID, FTP Username, FTP Password).*
3. Configure the sharing settings. After entering your credentials, configure the required sharing settings for the subsidiary.
   <img alt="DAT Rate Sharing Integration Settings showing the Sharing Settings configuration options." />
   *DAT Rate Sharing Integration Settings showing the Sharing Settings configuration options.*
4. Activate the integration. Save your settings to activate DAT Rate Sharing for the subsidiary.
   <img alt="DAT Rate Sharing Integration showing the activated state." />
   *DAT Rate Sharing Integration showing the activated state.*

## What syncs

The integration generates a CSV file containing rate data from loads that were invoiced on the previous day. The file follows a strict format required by DAT. The specific fields included in the submission are determined by DAT's rate sharing data format requirements.

The integration runs once per day, at approximately 9:00 AM UTC. Alvys only generates and sends the file when there are loads that were invoiced the previous day. If no loads were invoiced the previous day, no file is sent that day. Each subsidiary that has DAT Rate Sharing activated sends its own file to its own DAT account via FTP. Sync is one-way: data flows from Alvys to DAT only.

To verify the integration is working, confirm with your DAT Sales Representative that files are being received at the expected FTP destination. The integration runs daily, so allow until the next scheduled run (approximately 9:00 AM UTC the following day after a day with invoiced loads) to confirm the first successful submission.

<Note>
  📋 Each subsidiary must be configured separately with its own DAT account credentials; there is no option to share credentials across subsidiaries. · The integration runs once per day; there is no option to trigger a manual submission or change the daily run time. · Only loads invoiced the previous day are included in each submission; historical load data cannot be submitted through this integration. · Sync is one-way: data flows from Alvys to DAT only. DAT data is not imported back into Alvys through this integration.
</Note>

## Troubleshooting

### No data was received by DAT

1. Confirm that loads were invoiced the previous day in Alvys for the subsidiary that has DAT Rate Sharing enabled. The integration only runs when there are invoiced loads from the prior day.
2. Verify that the DAT credentials entered in Alvys match the credentials provided by your DAT Sales Representative exactly, including the FTP Username and FTP Password.
3. Confirm the integration is in an activated state in Management > Integrations for the correct subsidiary.
4. If credentials are correct, the integration is activated, and loads were invoiced the prior day but DAT still reports no data received, contact Alvys support with the subsidiary name and the date of the expected submission.

### Credentials were updated by DAT

1. Navigate to Management > Integrations and open the DAT Rate Sharing settings for the affected subsidiary.
2. Update the FTP Username and/or FTP Password with the new credentials provided by DAT.
3. Save your changes. The updated credentials will be used at the next scheduled daily run.

## FAQs

**Q: How often does the DAT Rate Sharing integration run?**

**A:** Once per day, at approximately 9:00 AM UTC, and only when there were loads invoiced the previous day.

**Q: Can I share one set of DAT credentials across multiple subsidiaries?**

**A:** No. Each subsidiary must be configured separately with its own DAT account credentials.

**Q: Does data flow back from DAT into Alvys?**

**A:** No. Sync is one-way: data flows from Alvys to DAT only.


# Connect ELD Rider to Alvys
Source: https://docs.alvys.com/en/help/integrations/eld-rider-eld-telematics-integration

Connect ELD Rider to Alvys with an API key to pull truck locations, driver Hours of Service status, and fuel level data into your dispatch workflow.

<Note>
  One-way ELD / telematics integration: Alvys pulls truck locations, HOS status, and fuel level data from ELD Rider into your dispatch workflow.
</Note>

## Overview

ELD Rider is a telematics provider that connects with Alvys to bring truck locations, Hours of Service (HOS) status, and fuel level data directly into your dispatch workflow. It is also known as an ELD (electronic logging device), GPS tracking, or fleet tracking integration.

Connecting ELD Rider to Alvys allows your dispatch team to view real-time truck locations and driver HOS status without leaving Alvys. Fuel level data is also pulled in when available from the device. Trailer locations are not supported by ELD Rider; only truck assets are tracked through this integration.

## Prerequisites

Before connecting, confirm you have the following:

* An active ELD Rider account with API access enabled
* Your ELD Rider API key (generated directly from the ELD Rider platform or provided by your ELD Rider representative)
* The **"Admin"**, **"Partner Admin"**, or **"Support"** role in Alvys. These roles can access **Management > Integrations**.

## How to connect?

1. Open Integrations: go to **Management > Integrations** in the top navigation.
2. Find ELD Rider in the list of available integrations and click to open it.
3. In the credentials field, enter the API key provided by ELD Rider. This key authenticates Alvys to your ELD Rider account.
4. Click **Save**. Alvys validates your API key before saving. As of February 2025, if the key is invalid, an error message appears immediately and the integration is not saved. If the key is valid, the integration status changes to active.

<Note>
  <img alt="Image shows the ELD Rider integration screen in Management > Integrations page" />

  *Image shows the ELD Rider integration screen in Management > Integrations page*
</Note>

## Mapping assets for location tracking

After the integration is active, map your Alvys truck assets to their corresponding ELD Rider asset records. This step links each truck in Alvys to the ELD device installed in it so that GPS location data is matched to the correct truck asset.

1. Navigate to **Assets** in the left navigation and click **Trucks** to open the truck list.
2. Double-click the truck you want to map to open its profile.
3. Scroll to the **ELD Integrations** section of the truck profile.
4. Click **Add Integration**.
5. Select **ELD Rider** from the list of available integrations.
6. Enter the ELD Rider asset ID for this truck. This ID is available in your ELD Rider portal.
7. Click **Save**. The truck is now mapped. GPS location data from ELD Rider will appear for this truck when the device is active and reporting.

<Note>
  <img alt="Image shows truck profile with the ELD Integrations section open" />

  *Image shows truck profile with the ELD Integrations section open*
</Note>

## Mapping drivers for HOS tracking

Map each driver in Alvys to their ELD Rider driver record so that Hours of Service (HOS) data appears in Alvys. HOS clocks (cycle, shift, drive, and break time remaining) will display in the driver profile and on dispatched loads once mapping is complete.

1. Navigate to **Assets** in the left navigation and click **Drivers** to open the Drivers list.
2. Double-click the driver you want to map to open their profile.
3. Find the **ELD Providers** section of the driver profile.
4. Click **Add ELD**.
5. Select **ELD Rider** from the available ELD providers.
6. Enter the ELD Rider driver ID for this driver. This ID is available in your ELD Rider portal.
7. Click **Save**. The driver is now mapped. HOS data will appear in Alvys when the driver is logged in to their ELD Rider device.

<Note>
  <img alt="Image shows the driver profile with the ELD Providers section" />

  *Image shows the driver profile with the ELD Providers section*
</Note>

## What syncs / data flow?

The following data is pulled from ELD Rider into Alvys:

* **Truck location:** Current GPS coordinates for each truck asset
* **HOS clocks:** Remaining time values for cycle time, shift time, drive time, and break time — these are countdown clocks showing time remaining, not time elapsed
* **Fuel level:** Displayed as a percentage when the device reports it

Trailer assets return no data from ELD Rider. Trailers will not appear with location or status from this integration. IFTA mileage data is not supported by ELD Rider and is not available in Alvys through this integration.

Alvys requests updated data from ELD Rider on a regular basis. Location, HOS, and fuel updates reflect the most recent values reported by the ELD device in the truck. Driver records are retrieved in pages of 50, sorted by driver name. If you have more than 50 drivers, Alvys continues retrieving additional pages automatically.

### Verify it is working

1. Go to Loads and open a load that has a driver assigned.
2. Look for the truck location on the map or in the driver/asset tracking section. If the integration is active and the driver's truck has an ELD Rider device, the location and HOS clocks should be visible.
3. Confirm the remaining-time HOS values (cycle, shift, drive, break) appear next to the driver's name or in the driver detail panel.

<Note>
  📋 **Limits / unsupported:** Trailer tracking is not supported: only trucks are tracked. · IFTA mileage reporting is not available through ELD Rider. · HOS values are remaining-time clocks only; elapsed time is not provided. · Battery level data is not displayed in Alvys.
</Note>

## Troubleshooting

### Truck location is not showing

1. Confirm the driver's truck has an ELD Rider device installed and powered on.
2. Verify the API key entered in Alvys matches the one provided by ELD Rider exactly — a mismatched or expired key will prevent data from loading.
3. Check that the integration status in **Management > Integrations** shows as active.

### HOS clocks are missing or blank

1. Confirm the driver is actively using the ELD device and has logged in for their shift.
2. Verify the device is transmitting data to ELD Rider's servers. Contact ELD Rider support if the device appears offline in their portal.

### Fuel level is not displayed

ELD Rider devices report fuel level only when the vehicle's on-board diagnostics support it. If the truck does not have compatible diagnostics, this field will remain blank — this is expected behavior.

## FAQs

**Q: Can I track both asset locations and driver HOS through the same integration?**

**A:** Yes. ELD Rider supports both asset location tracking and driver Hours of Service tracking in Alvys. Map each truck using the ELD Integrations section of the truck profile, and map each driver using the ELD Providers section of the driver profile.

**Q: Where do I find my ELD Rider driver IDs?**

**A:** Driver IDs are not easy to retrieve from the ELD Rider portal. Contact Alvys support at [support@alvys.com](mailto:support@alvys.com) for help retrieving them.

**Q: Why do I only see some of my drivers in the tracking view?**

**A:** ELD Rider returns driver records in groups of 50, sorted by driver name. All drivers are retrieved automatically; if a driver is not appearing, confirm they are active in ELD Rider and have a device assigned.

**Q: Can I track trailers through ELD Rider?**

**A:** No. ELD Rider does not return trailer data. Only truck assets are supported through this integration.

**Q: Why is the fuel level blank for some trucks?**

**A:** Fuel level is only available when the truck's onboard diagnostics system supports reporting it to the ELD device. If the truck does not support this, the fuel field will not display a value.

**Q: Is IFTA mileage available?**

**A:** No. IFTA mileage is not supported by ELD Rider and is not available in Alvys through this integration.

## Go Deeper

Setting Up ELD / Telematics Integrations


# Connect FleetLocate to Alvys
Source: https://docs.alvys.com/en/help/integrations/fleetlocate-eld-telematics-integration

Connect FleetLocate by Spireon to Alvys to pull real-time truck and trailer GPS locations into the Asset Map for dispatch and operations visibility.

<Note>
  FleetLocate by Spireon is a telematics provider that connects with Alvys to bring real-time truck and trailer GPS locations into your dispatch workflow: also known as FleetLocate GPS tracking, Spireon FleetLocate, or Spireon telematics.
</Note>

### Overview

FleetLocate, also known as Spireon FleetLocate, is a telematics provider that connects with Alvys to bring real-time truck and trailer locations directly into your dispatch workflow, also known as GPS tracking, fleet tracking, or telematics integration. The integration is one-way: Alvys pulls location data from FleetLocate.

Connecting FleetLocate to Alvys allows your dispatch and operations team to see current truck and trailer locations without leaving Alvys. Unlike most other ELD integrations, FleetLocate supports both truck and trailer tracking.

<Note>
  📋 Hours of Service (HOS) data and IFTA mileage data are not available through FleetLocate. Only location data is synced.
</Note>

### Prerequisites

Before connecting, confirm you have the following:

* An active FleetLocate (Spireon) account with API access. To request REST API credentials (username, password, and application token), contact FleetLocate support at [ATI-Support@spireon.com](mailto:ATI-Support@spireon.com).
* Your FleetLocate username, password, and application token (all three are required)
* An **"Admin"**, **"Operations Manager"**, or **"Dispatcher"** role in Alvys

FleetLocate requires three credentials to connect: a username, a password, and an application token provided by Spireon.

### How to connect?

1. Open Integrations. Go to **"Management > Integrations"** in the top navigation.

   <img alt="Notion Image" />
2. Select FleetLocate. Find FleetLocate in the list of available integrations and click to open it.

   <img alt="Notion Image" />
3. Enter your credentials. Enter your FleetLocate username, password, and the application token from your Spireon account. All three fields are required.
4. Save and activate. Click **"Save"**. Alvys will verify the credentials. Once confirmed, the integration status changes to active

**After activation, map each truck or trailer to its FleetLocate asset ID:**

Go to **Assets** in the left menu and select **Trucks** or **Trailers**.

<img alt="Notion Image" />

Double-click the asset you want to configure, then scroll down to the **ELD Integrations** section and click **Add Integration**.

<img alt="Notion Image" />

Select **FleetLocate** from the dropdown, enter the **FleetLocate asset ID** in the Integration ID field, and click **Save**.

<img alt="Notion Image" />

Repeat this process for each truck or trailer you want to track with FleetLocate. Once configured, you can view real-time locations on the **Asset Map**.

<img alt="Notion Image" />

#### Verify it's working?

1. Open a load with an assigned truck. Go to **"Loads"** and open a load that has a truck assigned.
2. Check the tracking map. Look for the truck location on the map or in the asset tracking section. If the integration is active and the truck has a FleetLocate device, the current location should be visible.
3. Confirm trailer location (if applicable). If a trailer is assigned to the load and has a FleetLocate device, its location should also appear in the tracking view.

### What syncs?

The following data is pulled from FleetLocate into Alvys:

* **Truck location:** Current GPS coordinates for each truck asset
* **Trailer location:** Current GPS coordinates for each trailer asset. FleetLocate is one of the few telematics providers that supports trailer tracking in Alvys

Alvys requests updated location data from FleetLocate on a regular basis. Both truck and trailer locations reflect the most recent values reported by the FleetLocate device.

### Troubleshooting

#### Truck or trailer location is not showing?

1. Confirm the asset has a FleetLocate device installed and powered on.
2. Verify all three credentials in Alvys (username, password, and application token) are correct and match your Spireon account. A mismatch on any one of the three will prevent the integration from connecting.
3. Check that the integration status in **"Management > Integrations"** shows as active.

#### Trailer location is missing even though the truck shows?

1. Confirm the trailer has its own FleetLocate device. Trailer tracking requires a separate device on the trailer asset.
2. Verify the trailer is active in your FleetLocate account.

#### HOS clocks are not visible

HOS data is not supported by FleetLocate. This is expected behavior and cannot be resolved through configuration.

### FAQs

**Q: Can I see trailer locations with FleetLocate?**

**A:** Yes. FleetLocate supports both truck and trailer location tracking. This is not available with most other telematics integrations in Alvys.

**Q: Why is HOS not showing for my drivers?**

**A:** FleetLocate does not return HOS data. If you need HOS visibility in Alvys, you will need a telematics provider that supports it, such as Geotab or Motive.

**Q: I entered all three credentials but the connection failed. What should I check?**

**A:** Verify that the application token is correct. The token is provided by Spireon and is separate from your login credentials. Contact FleetLocate support if you are unsure which token to use.

### Go Deeper

Setting Up ELD / Telematics Integrations

## FAQ

**Where do I find my FleetLocate asset IDs?**

Your FleetLocate asset IDs should be available in your FleetLocate portal, or you can request them from FleetLocate support.

**Can I track both trucks and trailers?**

Yes, you can configure FleetLocate tracking for both trucks and trailers by adding the integration to each asset type.

**What happens if I enter invalid credentials?**

As of February 2025, Alvys validates credentials before saving, so you'll see an error immediately if your credentials are incorrect.


# Connect FleetPulse to Alvys
Source: https://docs.alvys.com/en/help/integrations/fleetpulse-telematics-integration

Connect FleetPulse trailer telematics to Alvys to view real-time trailer GPS locations and tethered or untethered status inside your dispatch workflow.

<Note>
  FleetPulse is a telematics provider that connects with Alvys to bring real-time trailer locations and tether status into your dispatch workflow. Also referred to as trailer tracking, asset tracking, or telematics integration.
</Note>

## Overview

FleetPulse is a telematics provider that connects with Alvys to bring real-time trailer locations and tether status into your dispatch workflow. This integration is also referred to as trailer tracking, asset tracking, or telematics integration.

Connecting FleetPulse to Alvys allows your team to view current trailer locations and whether each trailer is tethered or untethered, directly from Alvys. FleetPulse is a trailer-focused integration.

## Prerequisites

Before connecting, confirm you have the following:

* An active FleetPulse account
* Your FleetPulse username and password (must be API-enabled credentials — see note below)
* The **"Admin"** role in Alvys

<Warning>
  ⚠️ FleetPulse requires API-enabled credentials, not a standard FleetPulse login. Before connecting, create a new standard user in FleetPulse dedicated exclusively to API access, then contact your FleetPulse representative and request that this user be upgraded for API access. API-enabled credentials provide stable, long-term access and prevent connection interruptions.
</Warning>

## How to connect

FleetPulse uses a username and password to authenticate. Alvys handles session management in the background after the initial connection.

1. In Alvys, select your Username in the bottom-left corner and click the integrations page
2. Find **"FleetPulse"** in the list of available ELD integrations and click to open it.
3. Enter your **FleetPulse** username and password. Only two fields are required.
4. If your account has multiple subsidiaries, select the subsidiaries that should use this integration before clicking Save.
5. Click **"Save"**. Alvys will authenticate with FleetPulse and store the session. Once confirmed, the integration status changes to active. Alvys automatically refreshes the connection in the background; you do not need to reconnect manually.

<Note>
  <img alt="GIF showing the FleetPulse integration setup in Alvys Management > Integrations with the username and password fields." />

  * GIF showing the FleetPulse integration setup in Alvys Management > Integrations with the username and password fields.\*
</Note>

### Map trailers to FleetPulse Unit IDs

After the integration is active, map each trailer in Alvys to its corresponding FleetPulse Unit ID. This tells Alvys which FleetPulse device to pull location data from for each trailer.

1. Go to **"Assets"** > **"Trailers"** in the left navigation.
2. Double-click a trailer to open its profile.
3. Scroll to the **"ELD Integrations"** section and click **"Add Integration"**.
4. Select **"FleetPulse"** from the dropdown.
5. Enter the FleetPulse Unit ID for this trailer.
6. Click **"Update Trailer"** to save your changes.

<Note>
  <img alt="GIF showing the trailer profile in Alvys with the ELD Integrations section and the FleetPulse Unit ID field." />

  *GIF showing the trailer profile in Alvys with the ELD Integrations section and the FleetPulse Unit ID field.*
</Note>

Repeat for each trailer you want to track.

## What syncs

The following data is pulled from FleetPulse into Alvys:

* **Trailer location:** Current GPS coordinates for trailers that have an active location signal
* **Tether status:** Whether the trailer is currently "Tethered" (connected to a truck) or "Untethered" (not connected)

  Alvys requests updated trailer location and tether status from FleetPulse on a regular basis. Trailers must have a valid GPS signal (latitude and longitude) to appear in tracking. Trailers without an active GPS signal will not show a location. Alvys automatically refreshes the FleetPulse connection in the background.

  **What is not supported:**
* Truck location data is not supported — **only trailers**
* HOS (Hours of Service) clocks are not available through FleetPulse
* IFTA mileage reporting is not available through FleetPulse
* Trailers without a valid GPS signal will not show a location

## Troubleshooting

### Trailer location is not showing

1. Confirm the trailer has a FleetPulse device installed and that the device has an active GPS signal. Trailers without a valid GPS reading will not display a location.
2. Verify your username and password in Alvys match your FleetPulse account. Go to **"Management"** > **"Integrations"** and re-enter your credentials if needed.
3. Check that the integration status shows as active.

### Tether status is not displaying

1. Confirm the trailer's FleetPulse device is actively reporting data to FleetPulse's servers.
2. Verify the device supports tether status reporting — not all FleetPulse devices report tether status.

### Truck location is missing

Truck location is not supported by FleetPulse. This is expected behavior. If you need truck location tracking, connect a different telematics provider such as Geotab or Motive.

## FAQs

**Q: Why do I see trailer locations but not truck locations with FleetPulse?**

**A:** FleetPulse is designed for trailer tracking. Truck location data is not returned by this integration. To track truck locations, connect a telematics provider that supports truck tracking, such as Geotab or Motive.

**Q: What does "Untethered" mean?**

**A:** "Untethered" means the trailer is not currently connected to a truck. "Tethered" means the trailer is connected to and being pulled by a truck.

**Q: Do I need to log back in to FleetPulse regularly?**

**A:** No. Alvys automatically manages the session with FleetPulse in the background. You do not need to re-enter credentials or manually reconnect after the initial setup.

**Q: Why is a trailer's location blank even though it has a device?**

**A:** Trailer location only shows when the device has an active GPS signal with valid coordinates. If the device is in a location with poor GPS reception, or if the device is powered off, the location will be blank.

**Q: Where can I find my FleetPulse Unit IDs?**

**A:** You can find the Unit ID for each trailer in your FleetPulse account. Open the trailer record in FleetPulse and look for the Unit ID field. Contact your FleetPulse representative if you need help locating this value.

**Q: Why do I need API-enabled credentials to connect FleetPulse?**

**A:** FleetPulse distinguishes between standard user credentials and API-enabled credentials. Standard credentials expire frequently and cause connection interruptions. API-enabled credentials are designed for integrations and provide stable, long-term access. Contact your FleetPulse representative to upgrade a standard user account to API access.

**Q: What trailer data does FleetPulse send to Alvys?**

**A:** FleetPulse sends current GPS coordinates (trailer location) and tether status to Alvys. Tether status indicates whether the trailer is currently connected to a truck (Tethered) or disconnected (Untethered). Truck location, HOS data, and IFTA mileage are not available through this integration.

## Go Deeper

* Setting Up ELD / Telematics Integrations


# Connect Geotab to Alvys
Source: https://docs.alvys.com/en/help/integrations/geotab-eld-telematics-integration

Connect Geotab ELD and telematics to Alvys to pull real-time truck and trailer locations, driver Hours of Service clocks, and IFTA mileage by state.

<Note>
  Geotab is a telematics and ELD provider that connects with Alvys to bring real-time truck and trailer locations, Hours of Service (HOS) status, and IFTA mileage data into your dispatch workflow. Also known as ELD, electronic logging device, fleet tracking, or GPS integration.
</Note>

## Overview

Geotab is a telematics and ELD provider that connects with Alvys to bring real-time truck and trailer locations, Hours of Service (HOS) status, and IFTA mileage data into your dispatch workflow, also known as ELD, electronic logging device, fleet tracking, or GPS integration. The integration is one-way: Alvys pulls data from Geotab.

Connecting Geotab to Alvys gives your dispatch team visibility into truck and trailer locations, driver HOS remaining-time clocks, and IFTA mileage by state, all without leaving Alvys. Geotab is one of the most comprehensive integrations available in Alvys, supporting trucks, trailers, HOS, and IFTA in a single connection.

## Prerequisites

Before connecting, confirm you have the following:

* An active Geotab account with API access
* Your Geotab username and password
* An **"Admin"** or **"Partner Admin"** role in Alvys

<Info>
  You do not need to look up or enter your Geotab database identifier. Alvys retrieves this automatically when you authenticate, so you only provide your username and password.
</Info>

## How to connect

1. Click on your username in the bottom left corner of the screen and select the **Integration** page.
2. From the left panel, select the correct subsidiary for this integration.
3. Expand the **ELD** section of the integrations list and click the pencil icon on the Geotab integration box.
4. Enter your Geotab account username and password. Do not enter a database name; Alvys retrieves this automatically.
5. Save and activate. Click **"Save"**. Alvys authenticates with Geotab and retrieves your database identifier. Once confirmed, the integration status changes to active.

   <img alt="Geotab integration card in Alvys with username and password fields" />

   *Geotab integration card in Alvys with username and password fields*

### Verify it's working

1. Open a load with an assigned truck and driver.
2. Check truck location. Look for the truck location on the map or in the tracking panel.
3. Check HOS clocks. The remaining-time HOS values should appear next to the driver's name or in the driver detail panel.
4. Confirm IFTA data (if applicable). IFTA mileage by state is visible in the IFTA reporting section of Alvys.

## Enable Location Tracking for Assets

After connecting the integration, add the GeoTab asset ID to each truck and trailer that will be tracked in Alvys. Without this step, location tracking will not appear for those assets.

1. Go to **Assets** on the Alvys toolbar and select **Trucks** or **Trailers** depending on which assets you want to configure.

2. Find and double-click the asset to open the Edit Asset page.

3. Scroll down to the **ELD Integrations** section and click the blue **Add Integration** button.

4. In the Add Integration window, click the drop-down menu and select **GeoTab**. Enter the GeoTab asset ID in the **Integration ID** field and click **Save**.

   <img alt="Add Integration window with GeoTab selected and Integration ID field filled" />

   *Add Integration window with GeoTab selected and Integration ID field filled*

5. Repeat for each truck and trailer that will use GeoTab location tracking.

After the GeoTab asset ID is saved, the asset can be tracked from the Asset Map by searching with the name of the asset.

<img alt="Alvys Asset Map showing a tracked truck located by asset name" />

*Alvys Asset Map showing a tracked truck located by asset name*

### Find Your GeoTab Asset ID

1. Log in to GeoTab and select **Vehicles & Assets** from the sidebar.

   <img alt="Geotab sidebar menu with Vehicles & Assets selected" />

   *Geotab sidebar menu with Vehicles & Assets selected*

2. Select the vehicle you want to configure.

3. Copy the asset ID from the URL. Use only the portion that comes after "id:".

   <img alt="Geotab browser URL with the vehicle asset ID following id:" />

   *Geotab browser URL with the vehicle asset ID following id:*

## Enable Hours of Service for Drivers

After connecting the integration, add the GeoTab asset ID to each driver's profile to enable Hours of Service (HOS) tracking. Without this step, HOS clocks will not appear in Alvys for those drivers.

1. Go to **Assets** on the Alvys toolbar and select **Drivers**.

2. Find and double-click the driver to open their profile.

3. On the right panel of the Driver details page, scroll to the **ELD Providers** section and click **+Add ELD**.

4. Enter the GeoTab asset ID in the **Integration ID** field and click **Save**.

   <img alt="Driver profile ELD Providers section with a GeoTab Integration ID entered" />

   *Driver profile ELD Providers section with a GeoTab Integration ID entered*

5. Repeat for each driver who will use the GeoTab Hours of Service feature.

After setup, Hours of Service can be accessed from the Dispatch planner page and the Load Details Page by selecting the time displayed for the driver.

### Find Driver Asset IDs

1. Log in to GeoTab and select **Activity > HOS > Availability** from the sidebar.

   <img alt="Geotab sidebar menu with Activity, HOS, Availability selected" />

   *Geotab sidebar menu with Activity, HOS, Availability selected*

2. Select the driver you want to configure.

3. Copy the asset ID from the URL. Use only the portion that comes after "id:".

   <img alt="Geotab browser URL with the driver asset ID following id:" />

   *Geotab browser URL with the driver asset ID following id:*

## What Syncs: Geotab to Alvys

The following data is automatically pulled from Geotab into Alvys every **15 minutes**:

* **Truck Location:** Real-time GPS coordinates for each truck asset, which are displayed on both the **Load** page and the **Asset Map**.
* **Trailer Location:** Real-time GPS coordinates for each trailer asset, also visible on the **Load** page and the **Asset Map**.
* **HOS Clocks:** Countdown clocks showing the remaining time for each driver's daily and cycle limits (*Drive Time, Shift Time, Cycle Time, and Break Time*), visible directly within the **Dispatch Planner**.
* **IFTA Mileage:** State-by-state mileage data to streamline your fuel tax reporting.
  * *Note: Once a truck is configured with its Geotab Asset ID, you can select Geotab as the primary mileage source. These calculations are automatically based on the time zone of your subsidiary's address in Alvys.*

Alvys requests updated data from Geotab on a regular basis. Locations, HOS clocks, and IFTA mileage all reflect the most recent values from Geotab's servers.

<Warning>
  IFTA mileage by state is calculated using the time zone associated with your subsidiary's physical address in Alvys. If your subsidiary address is in a different time zone than your drivers operate in, review your subsidiary settings to ensure accurate state-line crossing calculations.
</Warning>

## Troubleshooting

### Truck or trailer location is not showing

1. Confirm the asset has a Geotab device installed and that the device is powered on and reporting.
2. Verify your Geotab username and password are correct in Alvys. Go to **"Integrations"** and re-enter your credentials if needed.
3. Check that the integration status shows as active.

### HOS clocks are blank

1. Confirm the driver is logged in to the Geotab ELD device for their current shift.
2. Verify the device is actively transmitting data to Geotab's servers. If the device shows as offline in the Geotab portal, the HOS data will not update in Alvys.

### IFTA mileage appears incorrect

1. Check your subsidiary's physical address in Alvys. The time zone of that address is used to determine state-line crossings for IFTA purposes.
2. Confirm that trips are marked as completed in Alvys. IFTA mileage is calculated for completed trips.

## FAQs

**Q: Do I need to enter my Geotab database name when connecting?**

**A:** No. Alvys retrieves your Geotab database identifier automatically when you enter your username and password. You only need to provide two fields.

**Q: Why is my IFTA mileage different from what I see in Geotab directly?**

**A:** IFTA mileage in Alvys is calculated using the time zone of your subsidiary's physical address. If your subsidiary address in Alvys is in a different time zone than your Geotab account, the state-line crossings may differ slightly.

**Q: Does Geotab support trailer tracking in Alvys?**

**A:** Yes. Geotab returns location data for both trucks and trailers.

**Q: What HOS information is available?**

**A:** Geotab provides remaining-time HOS clocks: drive time, shift time, cycle time, and break time remaining.

## Go Deeper

Setting Up ELD / Telematics Integrations


# Highway Integration
Source: https://docs.alvys.com/en/help/integrations/highway-integration

Automate carrier compliance with Alvys and Highway—seamless onboarding, real-time updates, and better visibility for smoother operations.

<Note>
  Connect your Highway account to Alvys to automate carrier compliance checks, import onboarded carriers, and receive real-time status updates without leaving your TMS.
</Note>

## Overview

The Highway integration (also called carrier compliance integration or carrier vetting integration) connects Alvys to Highway's carrier compliance platform. Once connected, Alvys syncs with Highway every five minutes to keep carrier data current. Carriers who complete onboarding in Highway are automatically created in Alvys, and status changes are reflected in near real time. This eliminates manual carrier entry and ensures your team always has accurate compliance information before assigning a carrier to a load.

<Note>
  <img alt="Highway logo" />

  *Highway logo*
</Note>

## Prerequisites

Before you begin, you need an active Highway account and an Alvys integration key from Highway.

If you are switching from another TMS, revoke your Highway connection in that TMS before connecting to Alvys. Running two active connections simultaneously can cause sync conflicts.

Once your Highway contact confirms the integration key is ready, all of your previously onboarded carriers will automatically sync into Alvys after you complete the setup below.

## How to connect?

* Open Integrations in Alvys. Click your profile icon in the bottom left corner of Alvys and select **Integrations**. Under the **Carrier Compliance** section, locate the **Highway** card and click it to open the configuration.
* Enter your API key and select subsidiaries. Enter the API key provided by your Highway representative. Then select which subsidiaries you want the integration to apply to. Alvys validates your API key automatically. If the key is invalid or expired, a banner appears prompting you to re-enter your credentials.

<Note>
  <img alt="Highway setup GIF showing entering the API key and selecting subsidiaries" />

  *Highway setup GIF showing entering the API key and selecting subsidiaries*
</Note>

* Confirm the integration is active. Once the API key is accepted, the Highway integration status changes to active. Previously onboarded carriers from Highway will begin syncing into Alvys automatically.

## What syncs?

When a carrier completes onboarding in Highway, Highway sends the following data to Alvys: carrier name, MC/DOT number, address, insurance details, and compliance status. These fields are mapped to the corresponding carrier record in Alvys. Alvys does not push carrier records to Highway; Highway is the system of record for carrier creation.

Real-time updates from Highway include insurance changes, address updates, and compliance status modifications. Each update is applied to the matching carrier record in Alvys.

Alvys polls Highway every five minutes for compliance status changes and new carrier records.

<Warning>
  ⚠️ It is strongly recommended that you avoid adding carriers directly in Alvys when the Highway integration is active. Carriers created directly in Alvys will not be monitored by Highway, which means compliance updates will not be received for those carriers.
</Warning>

To confirm the integration is working, go to your carrier list and look for carriers that were already onboarded in Highway. They should appear automatically in Alvys within five minutes of the integration becoming active. Each carrier should display a Highway compliance status (**Pass**, **Partial Pass**, **Incomplete**, or **Fail**) on their carrier record. If carriers are not appearing, confirm that your Highway representative has marked the integration setup as complete on their side.

<Note>
  <img alt="Notion Image" />
</Note>

<Warning>
  * Carriers added directly in Alvys (not through Highway) will not be monitored for compliance updates by Highway.
  * Deleting a carrier from Alvys does not delete or remove the carrier from Highway; Highway remains the system of record for carrier compliance data.
  * The integration does not support manual one-off compliance checks from within Alvys; all checks are driven by Highway's sync schedule.
</Warning>

## Troubleshooting

### API key validation error on save

1. Confirm you have copied the full API key from your Highway representative with no extra spaces.
2. Ask your Highway representative to generate a new integration key and try again.
3. If the error persists after entering a valid key, contact Alvys Support. The credential validation step may not be reaching Highway's API.

### Carriers not syncing after setup

1. Confirm your Highway representative has completed their side of the integration setup.
2. Wait up to five minutes. The sync interval is five minutes between polls.
3. If carriers that are fully onboarded in Highway are still missing after 10 minutes, contact Alvys Support.

### Carrier with Incomplete or Fail status cannot be assigned to a load

* Carriers with **Incomplete** or **Fail** status are blocked from load assignment by default. This is the expected behavior when the Highway integration is active. If your account has the **"OverrideCarrier"** permission enabled, you can proceed with the assignment at your discretion.

## FAQs

**Q: What happens if I add a carrier directly in Alvys instead of through Highway?**

**A:** Carriers added directly in Alvys are not monitored by Highway. You will not receive compliance status updates for those carriers.

**Q: How often does Alvys sync with Highway?**

**A:** Alvys syncs with Highway every five minutes.

**Q: Can I assign a carrier with Fail status to a load?**

**A:** By default, carriers with **Fail** status are blocked from load assignment. If your account has the **"OverrideCarrier"** permission enabled, you can proceed with the assignment at your discretion.

**Q: What are the four Highway compliance statuses?**

**A:** The four statuses are **Pass** (all requirements met, assignment allowed), **Partial Pass** (some requirements met, assignment allowed), **Incomplete** (documentation not yet complete, assignment blocked by default), and **Fail** (compliance requirements not met, assignment blocked by default).

**Q: If I was using Highway with a different TMS, what do I need to do before connecting to Alvys?**

**A:** You must revoke the Highway connection in your previous TMS before connecting in Alvys. Failing to do so can cause sync conflicts.


# How to clear Error Transactions
Source: https://docs.alvys.com/en/help/integrations/how-to-clear-error-transactions

Use the Mark as Synced action in Alvys to clear resolved sync errors from the Error Transactions list for QuickBooks, NetSuite, and Business Central exports.

<Note>
  Use the Mark as Synced action to remove resolved error transactions from the Error Transactions list so your sync queue (export failures) shows only what still needs attention.
</Note>

## Overview

The Error Transactions page surfaces transactions that failed to sync, export, or post to your connected accounting system (also called sync errors or failed exports). If you have manually resolved the underlying issue in the external accounting system (e.g., manually creating the invoice in QBO), you can mark, clear, or dismiss those transactions as synced to remove them from the list and keep your workspace focused on active errors.

## Before You Start

* You must have the **"Admin"**, **"Biller"**, or **"Partner Admin"** role to use the Mark as Synced action.
* Navigate to Accounting > Error Transactions in Alvys.

## Steps

1. Open the Error Transactions page.

   * Navigate to Accounting > Error Transactions.

<Note>
  <img alt="Alvys Accounting menu with Error Transactions highlighted" />

  *Alvys Accounting menu with Error Transactions highlighted*
</Note>

1. Select the transactions to clear.

   * Select the checkbox next to each transaction you want to mark as synced.

     <Info>
       💡 You can multi-select transactions to save time when clearing several at once.
     </Info>
2. Mark the transactions as synced.

   * Click the “Mark as synced”
   * Confirm your choice in the prompt that appears.

<Note>
  <img alt="Error Transactions page showing “Mark as synced” button highlighted" />

  *Error Transactions page showing “Mark as synced” button highlighted*
</Note>

## Result

The selected transactions are removed from the Error Transactions list. Your list now shows only transactions that still need attention.

<Warning>
  ⚠️ In this first version, cleared transactions will not show up anywhere else in the interface after being removed from the list.
</Warning>

## Troubleshooting

### Marked a transaction as synced by mistake

In this version, there is no built-in way to revert a transaction that has been marked as synced. If you marked a transaction as synced by mistake:

1. Note the transaction details (load number, amount, date) before leaving the page if possible.
2. Re-sync the transaction from the source system if your accounting integration supports re-triggering exports.
3. If the transaction cannot be recovered through re-sync, contact Alvys support with the transaction details so the record can be reviewed.

## FAQs

**Q: Will I be able to see which user cleared a transaction?**

**A:** Not yet; UI-level traceability and audit logs are planned for a future update.


# Sage Intacct: Dimension & custom field mappings
Source: https://docs.alvys.com/en/help/integrations/how-to-configure-dimension-and-custom-field-mappings-for-sage-intacct

Create dimension values and custom fields in Sage Intacct, then map them to Alvys so every exported AR invoice and AP bill carries the right tags and data.

<Note>
  Create dimension values and custom fields in Sage Intacct, then map them to Alvys fields so every exported bill and invoice carries the right dimension tags and custom-field data.
</Note>

## Overview

Dimensions and custom fields let you push additional categorization and data from Alvys into Sage Intacct on every exported bill and invoice. Configuring them (also called field matching or dimension setup) involves work in two systems: you create the values in Sage Intacct first, then map them to the corresponding Alvys fields from your integration settings.

This article walks through all four (4) phases; setting up dimension values in Sage Intacct, mapping those dimensions in Alvys, creating custom fields in Sage Intacct, and mapping custom fields in Alvys — plus the available fields and FAQs.

* **Also referred to as**: Field matching **·** Dimension Setup **· D**imension Mapping

## Before You Start

**Confirm the following before you begin:**

* The Sage Intacct setup wizard in Alvys is complete. The Dimensions and Custom Fields tab does not appear until the wizard finishes.
* You know which Sage Intacct dimension types you want to use. Alvys supports 11 standard types: Location, Department, Class, Customer, Vendor, Employee, Project, Item, Asset, Contract, and Warehouse. Custom Dimensions are not supported.
* Any required dimensions (those with a red Required badge in Alvys) have dimension values created in Sage Intacct and will have a Default Value set. Required dimensions without a Default Value will block financial exports.
* If you are mapping custom fields, you know which Sage object each should attach to: AR Invoice, AR Invoice Item, AP Bill, or AP Bill Item.
* Required role: Admin or Partner Admin.

## Steps

Complete the four phases in order. Phases 1 and 3 are performed in Sage Intacct; phases 2 and 4 are performed in Alvys.

### Phase 1: Set up dimension values in Sage Intacct

A dimension in Sage Intacct is a classification system — think of it as a tag with a set of values — that lets you sort and report on financial data across business segments such as location, department, or class without complicating your chart of accounts. Create the dimension values you need in Sage Intacct before mapping them in Alvys, and repeat this sub-process for each value.

* Navigate to the relevant dimension module. For Location and Department, go to **Company > Setup**. For other standard dimension types, go to **Reports > Setup > Dimensions** to manage all dimension types.

<Note>
  <img alt="Sage Intacct navigation to the dimension module (Company > Setup or Reports > Setup > Dimensions)" />

  *Sage Intacct navigation to the dimension module (Company > Setup or Reports > Setup > Dimensions)*

  <img alt="The dimension values list in Sage Intacct showing the Add button." />

  *The dimension values list in Sage Intacct showing the Add button.*
</Note>

* Click **Add** to begin creating a new dimension value.

<Note>
  <img alt="The location dimension list page in Sage Intacct showing the Add button." />

  *The location dimension list page in Sage Intacct showing the Add button.*
</Note>

* Enter a **unique ID** for the dimension value. We recommend choosing this ID carefully, as it cannot be changed after creation.

<Note>
  <img alt="Image showing new location dimension form with fields such as ID, Name, Status, Parent field etc." />

  *Image showing new location dimension form with fields such as ID, Name, Status, Parent field etc.*
</Note>

* Enter a Name for the dimension value. Unlike the ID, the name can be updated later if needed.
* Optionally provide a Description or other relevant details depending on the dimension type. For locations, you may also configure a primary Contact with address details that appear on invoices and forms.
* To build a parent-child hierarchy, specify a Parent to nest the new value under an existing one. Leave it blank if the value should sit at the top level.
* **Set the Status:** Active allows transactions to post against the value. Active Non-Posting, which is available for Department, Location, Class, Customer, Vendor, and Project dimensions, makes the value available for reporting and roll-ups but prevents Alvys from posting transactions directly to it.
* Click Save. The dimension value will now appear in your list and become available for tagging on transactions throughout the system.

<Note>
  <img alt="Image showing “Save” button on location dimension form in Sage Intacct." />

  *Image showing “**Save**” button on location dimension form in Sage Intacct.*
</Note>

**Repeat these steps for each additional value you need before mapping in Alvys.**

### Phase 2: Map dimensions in Alvys

After creating dimension values in Sage Intacct, map each dimension to an Alvys field from **Settings > Connections > Sage Intacct > Dimensions and Custom Fields**. Each dimension is mapped to one Alvys field.

**The available Alvys fields are:**

* **Subsidiary:** The Alvys subsidiary associated with the transaction.
* **Fleet:** The fleet assigned to the load or trip.

<Note>
  <img alt="Load Fleet: For fleet dimension mapping, the load Fleet set is used to decide which dimension is used for the customer invoice as well as the external carrier bill." />

  ***Load Fleet:** For **fleet** dimension mapping, the load Fleet set is used to decide which dimension is used for the customer invoice as well as the external carrier bill.*
</Note>

<Note>
  <img alt="Driver fleet: The driver assigned fleet is used to determine the fleet mappings for driver bills." />

  ***Driver fleet:** The driver assigned fleet is used to determine the fleet mappings for driver bills.*
</Note>

* **Office:** The load office associated with the transaction.

  <img alt="Image showing the Load office on the load details page with the change office button highlighted" />

  \*Image showing the Load office on the load details page with the change office button highlighted \*
* **Driver:** The driver assigned to the trip.
* **Truck:** The truck assigned to the trip.
* **Trailer:** The trailer assigned to the trip.
* **Contractor Type:** The contractor type of the driver (e.g., Company Driver, Owner Operator).

**The Dimension Mappings table** shows two (2) columns: **Sage Field** (the dimension name from Sage; required dimensions carry a red "Required" badge and must be mapped, or exports fail with validation errors) and **Alvys Field** (an "Add Mapping" dropdown to choose which Alvys field maps to the dimension).

<Note>
  <img alt="The Dimension Mappings table showing the Sage Field and Alvys Field columns with dropdown visible." />

  *The Dimension Mappings table showing the Sage Field and Alvys Field columns with dropdown visible.*
</Note>

Select the appropriate Alvys field from the dropdown for each dimension.

<Check>
  💡 For example, if your Sage "Location" dimension represents terminal locations, you might map it to the Alvys **Office** field so that every exported transaction is tagged with the correct office/terminal.

  <img alt="A dimension row with an Alvys field selected (e.g., Office)." />

  *A dimension row with an Alvys field selected (e.g., Office).*
</Check>

Once a dimension is mapped to an Alvys field, control how individual values are matched between the two systems. The mapping panel provides two levels of control: a Default Value and Specific Value Mappings.

**Default Value.** The Default value is a fallback: when an exported transaction's Alvys value has no specific mapping, Alvys applies the Default as the Sage dimension value, so every transaction is tagged with a valid value. If a dimension is Required in Sage, always set a Default to prevent export failures. With no Default and no specific mapping, Alvys passes the Alvys value through as-is, which may cause validation errors in Sage.

<Note>
  <img alt="Image showing the default dimension value field with a required label" />

  *Image showing the default dimension value field with a required label*
</Note>

**Specific Value Mappings.** Specific Value Mappings define exact one-to-one matches between individual Alvys values and Sage dimension values — for example, mapping the Alvys "Brokerage" office to the Sage location "Boston" and the Alvys "Inc" office to "San Diego Terminal". Any value without a specific mapping falls back to the Default.

<Note>
  <img alt="The dropdown selection menu within the Location - Office mapping interface, with San Diego Terminal actively highlighted for selection." />

  *The dropdown selection menu within the **Location - Office** mapping interface, with **San Diego Terminal** actively highlighted for selection.*
</Note>

To map values, click the **Map Values** button next to the dimension in the Dimension Mappings table.

<Note>
  <img alt="The initial configuration row for the Alvys, Sage Intacct Location Mapping." />

  *The initial configuration row for the Alvys, Sage Intacct **Location** Mapping.*
</Note>

A panel opens with two columns — **Sage Values** (the dimension values from your Sage environment) and **Alvys Values** (the values from the Alvys field you selected). Match each Sage value to the appropriate Alvys value, and set the Default Value at the top of the panel.

<Note>
  <img alt="The configuration modal overview for the Location - Office field." />

  *The configuration modal overview for the **Location - Office** field.*
</Note>

After mapping values, the **Map Values** button updates to show how many values are mapped (e.g., "3 Value(s)") so you can quickly see which dimensions have value mappings configured.

<Note>
  <img alt="Image showing the configured Location field row (1 value configured)." />

  *Image showing the configured **Location** field row (1 value configured).*
</Note>

### Phase 3: Create a custom field in Sage Intacct

Custom fields are user-defined fields added to standard Sage objects; the Alvys integration can populate them with Alvys data on every exported transaction. They are supported on four Sage objects: **AR Invoice** (header), **AR Invoice Item** (line item), **AP Bill** (header), and **AP Bill Item** (line item). The object you pick determines where the field appears. Custom fields must exist in Sage Intacct before you can map them in Alvys — repeat this sub-process for each one.

Depending on your subscription, navigate to **Platform Services > All > Object Customization** (or **Customization Services > All > Object Customization**) and click **Add** next to Custom Fields.

<Note>
  <img alt="The Object Customization page with the Add button next to Custom Fields." />

  *The Object Customization page with the Add button next to Custom Fields.*
</Note>

Select the **Object** to which you want to add the custom field from the dropdown list and click Next. This is where you choose the object type, for example AR Invoice, AP Bill, AR Invoice Item, or AP Bill Item.

<Note>
  <img alt="The Object selection dropdown in the custom field creation wizard." />

  *The Object selection dropdown in the custom field creation wizard.*
</Note>

Select the **Data Type** for your custom field and click Next. The data type determines what kind of information the field will accept.

<Note>
  <img alt="The Data Type selection step in the wizard." />

  *The Data Type selection step in the wizard.*
</Note>

**Only the following data types are supported by the Alvys integration:**

* **Date:** Date values.
* **Currency:** Monetary amounts.
* **Number:** Numeric values.
* **Text:** Short text strings (up to the character limit defined in Sage Intacct).
* **Text Area:** Longer text content.

**Do not select these unsupported types**, as they cannot be mapped to Alvys: Picklist, Picklist (multi-select), Checkbox, Email, Percent, Sequence, URL, or Password. Unsupported custom field types will not appear in the mapping interface.

<Warning>
  ⚠️ You cannot change the data type of a custom field after it is created, so choose carefully.
</Warning>

Enter a **Label** for the field. This is the text that will appear next to the field in the user interface. Sage Intacct will auto-suggest a **Field ID** based on the label. The Field ID is used by APIs and cannot contain spaces.

Define any additional **field characteristics** based on the data type you selected, such as field length, decimal places, default values, or picklist values, and click Next.

<Note>
  <img alt="Field characteristics configuration step showing length and decimal options." />

  *Field characteristics configuration step showing length and decimal options.*
</Note>

Configure **Deployment Options** and click **Done**: set whether the field is **required**, and the **section** and **tab** where it appears on the Sage record.

<Note>
  <img alt="Deployment Options step in the custom field wizard." />

  *Deployment Options step in the custom field wizard.*
</Note>

### Phase 4: Map custom fields in Alvys

Alvys provides built-in fields, organized into seven groups, that can be mapped to Sage custom fields:

* **Load Fields:** Carrier Invoice Number, Subsidiary, PO Number, Order Number, BOL Number, Office, Fleet, Equipment, Commodity, Weight, Volume, Invoiced Date, Created Date.
* **Customer Fields:** Net Payment Terms, Miles, Sales Agent.
* **Dispatch Fields:** Total Miles, Loaded Miles, Empty Miles, Dispatched By, Dispatched Date.
* **Shipper Fields:** Name, Address, City, State, Country, Pickup Date.
* **Consignee Fields:** Name, Address, City, State, Country, Delivery Date.
* **Equipment Fields:** Truck, Trailer.
* **Driver Fields:** Primary, Secondary, Fleet.

In addition, two Custom Reference types can be mapped: **Custom Load References** (resolved from the load at export) and **Custom Trip References** (resolved from the trip at export). These appear in the Alvys Field dropdown grouped under their own headings.

<Note>
  <img alt="Features an open 'Alvys Field' dropdown column on the far right, with a green box highlighting the selection of Custom Trip Reference." />

  *Features an open "Alvys Field" dropdown column on the far right, with a green box highlighting the selection of **Custom Trip Reference**.*
</Note>

Custom references are managed under **Settings > Custom References**, organized into six tabs (Loads, Trips, Stops, Drivers, Trucks, Trailers).

<Note>
  <img alt="Highlights the breadcrumb path in the top header and details the blue + New Reference button on the bottom right inside a green frame." />

  *Highlights the breadcrumb path in the top header and details the blue **+ New Reference** button on the bottom right inside a green frame.*
</Note>

From there you can create a **New Reference**, name and describe it, pick a field type (Text, Date, etc.), and configure whether it shows within Alvys and on documents.

The Custom Field Mappings table displays seven columns: **Sage Field**, **Code**, **Object**, **ID**, **Type**, **Chars** (max character length), and **Alvys Field** (a dropdown grouped by category). To map a custom field, find it in the table and select the Alvys field in the last column — only type-compatible Alvys fields appear.

<Note>
  <img alt="Custom field mapping interface at the Advanced Settings step of the Sage Intacct setup wizard." />

  *Custom field mapping interface at the Advanced Settings step of the Sage Intacct setup wizard.*
</Note>

Custom field mappings can be configured during initial setup or any time afterward. During initial setup, they are configured at **Step 5: Advanced Settings**, where Alvys retrieves your available Sage custom fields and you select the Alvys field for each.

<Note>
  <img alt="The Custom Field Mappings accordion expanded in the Dimensions and Custom Fields tab." />

  *The Custom Field Mappings accordion expanded in the Dimensions and Custom Fields tab.*
</Note>

After setup, modify mappings from **Settings > Connections > Sage Intacct**: click the integration for your subsidiary, select the **Dimensions and Custom Fields** tab, and use the same mapping interface. Mapping changes apply to future exports only — invoices and bills already in Sage are not retroactively updated.

<Note>
  <img alt="The Custom Field Mappings table with all columns visible including the Alvys Field dropdown." />

  *The Custom Field Mappings table with all columns visible including the Alvys Field dropdown.*
</Note>

## Result

After completing all four phases:

* Dimension mappings are active: every financial export from Alvys includes the configured dimension values in the corresponding Sage Intacct fields.
* Custom field mappings are active: every export includes Alvys data in the configured custom fields on the selected Sage objects.
* Required dimensions with a Default Value set no longer block financial exports.
* Tip: export one test transaction and verify the values land correctly in Sage before bulk exporting.

## Variations

* **Updating mappings after initial setup:** Add, change, or remove dimension and custom field mappings any time from the Dimensions and Custom Fields tab. Changes apply to future exports only.
* **Required dimension with no Default Value:** If a required dimension has no Default Value and an unmapped Alvys value reaches export, the export fails. Open Map Values for that dimension and set a Default Value.

## Troubleshooting

### Financial exports fail after dimension mapping is configured

* Open **Settings > Connections > Sage Intacct > Dimensions and Custom Fields** and expand Dimension Mappings.
* Identify any dimension with a red Required badge, and confirm an Alvys field is selected for each.
* Click Map Values for each required dimension and confirm a Default Value is set — exports fail for any unmapped Alvys value when no Default is configured.
* If a required dimension does not appear, confirm the matching Sage subscription is active (Asset → Fixed Assets Management; Contract → Contracts; Warehouse → Inventory).
* If none of the above apply, contact Alvys support.

### A custom field does not appear in the Alvys mapping interface

* Confirm the field uses a supported data type (Date, Currency, Number, Text, Text Area). Unsupported types are not displayed.
* Confirm the field is on a supported object (AR Invoice, AR Invoice Item, AP Bill, AP Bill Item).
* If recently created, refresh the Sage Intacct integration settings page and expand Custom Field Mappings again.
* If it still does not appear, contact Alvys support.

### Exported values are truncated in Sage Intacct

* In the Custom Field Mappings table, check the **Chars** column for the field's maximum length in Sage.
* If the Alvys value typically exceeds that limit, increase the field's maximum length in Sage via Object Customization and export again.
* If the limit cannot be increased, map a shorter Alvys field or use a Custom Reference with a truncated value.

## FAQs

**Q: What is the main benefit of dimensions instead of modifying my chart of accounts?**

A: Dimensions let you tag, slice, and report on financial data across business segments (location, fleet, driver) without overcomplicating your chart of accounts. When you add a new dimension value, all existing account codes automatically become available to it.

**Q: Can I use Custom Dimensions with the Alvys integration?**

A: No. Only standard Sage Intacct dimension types are supported (Location, Department, Class, Customer, Vendor, Employee, Project, Item, Asset, Contract, Warehouse).

**Q: What does "Active Non-Posting" status mean for a dimension value?**

A: The value is available for reporting and roll-ups in Sage Intacct, but Alvys cannot post transactions directly to it.

**Q: What is the difference between a Default Value and a Specific Value Mapping?**

A Specific Value Mapping is an exact one-to-one match between an Alvys value and a Sage dimension value (e.g., Alvys "Brokerage" → Sage "Boston"). The Default Value is the fallback applied when an Alvys value has no specific mapping, preventing export errors.

**Q: What happens if a dimension has a red "Required" badge in the mapping table?**

A: It is required by your GL accounts in Sage. You must map it in Alvys and set a Default Value, otherwise exports fail with validation errors.

**Q: Which Sage Intacct object types support custom fields in this integration?**

A: Four: AR Invoice (header), AR Invoice Item (line item), AP Bill (header), and AP Bill Item (line item).

**Q: What data types are supported when creating custom fields for Alvys mapping?**

A: Date, Currency, Number, Text, and Text Area. Unsupported types (Picklist, multi-select Picklist, Checkbox, Email, Percent, Sequence, URL, Password) do not appear in the Alvys mapping interface.

**Q: Which Alvys Custom References can I map to Sage Intacct?**

**A**: Two: Custom Load References and Custom Trip References (of the six custom reference entities Alvys supports).

**Q: If I update a custom field mapping today, will it update my past invoices in Sage?**

**A:** No. Mapping changes take effect on future exports only; previously exported transactions are never retroactively updated.

**Q: Why should I pay attention to the "Chars" column in the Custom Field Mappings table?**

**A:** It shows the maximum character length Sage Intacct allows for that text field. If the Alvys value exceeds it, the value is truncated on export.

## Go Deeper

* [Sage Intacct: Transaction Export and Modification](/en/help/integrations/sage-intacct-transaction-export-and-modification)
* [Sage Intacct Integration Collection](/en/help/integrations/sage-intacct-integration-collection)


# QuickBooks Online: Connect & configure
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys

Authorize the OAuth connection to QuickBooks Online in Alvys and configure sync settings for invoices, bills, driver pay, and QBO class or location mapping.

<Note>
  This article walks through authorizing the OAuth connection between Alvys and QuickBooks Online, then configuring sync settings for revenue, expenses, driver bills, carrier invoice requirements, and subsidiary or fleet mapping to QBO classes or locations.
</Note>

## What This Integration Does

Alvys connects to QuickBooks Online (QBO, Intuit QuickBooks) via OAuth 2.0, which means you authenticate (sign in and authorize) through Intuit's login portal and Alvys receives a secure token; no passwords are stored in Alvys. Once connected, Alvys automatically exports, syncs, and pushes customer invoices and carrier or vendor bills when loads are processed for billing. When payments are recorded in QBO, QBO sends the payment status back to Alvys.

## Prerequisites

Before connecting, complete all steps in [QuickBooks Online Prerequisites (Start Here)](/en/help/integrations/quickbooks-online-prerequisites):

* Confirm your QBO subscription is Essentials, Plus, or Advanced.
* Verify that your Chart of Accounts includes accounts for Accounts Receivable, Accounts Payable, income, and expenses.
* Enable Custom transaction numbers in QBO at Settings > Account and Settings > Sales > Sales form content if you want QBO invoices to use Alvys load numbers.
* Confirm there are no closed accounting periods that would cover the dates of loads you plan to export.

## Connect / Authenticate

* **Open the Integrations page.** Navigate to Management > Integrations in Alvys and locate the QuickBooks Online tile.

<Note>
  <img alt="Management menu with Integrations highlighted" />

  *Management menu with Integrations highlighted*

  <img alt="QuickBooks Online Tile under the accounting section of the Integrations List." />

  \*QuickBooks Online Tile under the accounting section of the Integrations List. \*
</Note>

* **Initiate the connection.** Click **Connect** on the QuickBooks Online tile. Alvys redirects you to the Intuit authorization page.
* **Sign in and authorize.** Sign in with your QBO credentials and click **Connect**. Once authorized, Intuit redirects you back to Alvys and the connection status shows as connected.
* **Select the QBO company file.** If your Intuit account has access to more than one QBO company file, select the correct one from the dropdown. Only one company file can be connected per Alvys legal entity.

<Note>
  <img alt="Intuit authorization page after clicking Connect." />

  *Intuit authorization page after clicking Connect.*
</Note>

## Field & Data Mapping

After connecting, configure the sync settings. Each section below maps Alvys data to the corresponding QBO field or behavior.

<Note>
  <img alt="QuickBooks Online Account Settings dialogue in Alvys integrations page" />

  *QuickBooks Online Account Settings dialogue in Alvys integrations page*
</Note>

### Transactions Type

There are two transaction types available for synchronization:

1. **Revenue** This option determines whether revenue transactions are synchronized with QBO. When enabled, income related financial data such as customer invoices will be exported to QBO.
2. **Expense** This option determines whether expense transactions are synchronized with QBO. When enabled, cost related financial data such as driver pay and carrier bills will be exported to QBO.

<Info>
  💡 Your selection here takes precedence over all other configuration settings. These options determine the type of financial data that will be integrated. Enable only the options you intend to export to QBO. Once selected, additional settings are available to further control how transactions are exported.
</Info>

### Ignore Driver Bills

This setting allows users to prevent the export of all driver bills, including company drivers and owner operators, to QuickBooks Online (QBO). When enabled, bills associated with drivers will not be exported, giving users greater control over which transactions are sent to external accounting systems. This option is commonly enabled when driver pay is managed outside of QBO, such as through a payroll system or a separate driver settlement solution. Please note that even when this setting is enabled, external carrier bills, subsidiary carrier bills, and company expenses such as fuel and tolls may still be exported if those options are configured.

### Single Bill for Driver Statement

This setting controls how driver bills for company drivers and owner operators are exported to QuickBooks Online (QBO). It is used to consolidate all charges and transactions related to a driver, including trips, fuel, tolls, and other expenses, into a single bill per driver statement.

When this setting is enabled and a driver paystub or statement is generated, a **single bill** is exported to QuickBooks Online for the **total net amount** of the paystub. All components of driver pay are consolidated into this bill, including trip pay, accessorials, deductions, credits, reimbursements, and any other adjustments. Each component appears as a **separate line item** on the bill, providing detailed visibility while keeping the accounting export grouped into one transaction. This option is commonly used when driver pay is processed on a scheduled basis, such as weekly or biweekly payroll cycles.

When this setting is disabled, generating a customer invoice will also export the driver bill for the individual trip. Each trip or delivery is exported as a separate bill. When a paystub is generated, multiple bills are exported for each transaction type on the paystub, including separate bills for credits, deductions/reimbursements.

### Generate Carrier Invoice Separately

This setting applies to brokerage-type trips where an external carrier and its assets are assigned to a load. When enabled, the system checks for an uploaded carrier invoice before exporting the carrier bill to QuickBooks Online (QBO). Specifically, when a brokerage trip is delivered or released and the user uploads a document of the type carrier invoice, the system will export the carrier bill to QBO. This can also be triggered when a user generates the customer invoice for a load; the system will verify that a carrier invoice has been uploaded, and if no carrier invoice is found, the carrier bill will not be exported to QBO. This setting should only be enabled when carrier invoices are required as part of the workflow prior to exporting external carrier bills for payment.

If this setting is disabled, generating the customer invoice for a trip with an external carrier will automatically export the carrier bill to QuickBooks Online, even if the carrier invoice has not been uploaded.

<Info>
  💡 If this setting was previously enabled but no carrier invoice document was uploaded, the carrier bill was not created and therefore was not exported to QuickBooks Online. To resolve this, upload a document of type Carrier Invoice to the trip, then select Regenerate Invoice. This will create the carrier bill and initiate its export to QuickBooks Online.
</Info>

### Process Statement by Tax Category

When enabled, only bills for 1099 drivers are exported to QuickBooks Online (QBO). Bills for W-2 drivers are excluded, allowing users to manage W-2 driver payments in a separate payroll system.

When disabled, bills for both W-2 and 1099 drivers are exported to QBO.

This setting is typically enabled by tenants that handle W-2 driver compensation outside of QBO and want to prevent those bills from being sent to QBO while still exporting 1099 driver expenses.

<Note>
  <img alt="Image showing the Tax Category on driver profile." />

  *Image showing the Tax Category on driver profile.*
</Note>

<Warning>
  ⚠️ Some settings must be used together, while others should not be enabled at the same time. Refer to the **Configuration Dependencies and Incompatible Settings** section for guidance.
</Warning>

### Pay Subsidiary Carrier

This setting applies to trips involving a subsidiary carrier (i.e., a carrier operating under a subsidiary of the main company) that is assigned alongside the tenant’s internal assets. By default, when a driver statement is generated and assuming the Single Bill for Driver Statement setting is enabled, a bill is exported for the tenant’s driver on the trip.

When Pay Subsidiary Carrier is enabled, this behavior changes: instead of exporting a bill for the driver when a paystub is generated, the system exports a bill for the subsidiary carrier when the load invoice is generated.

<Warning>
  ⚠️ Certain settings are mutually exclusive and should not be enabled at the same time. The Pay Subsidiary Carrier setting should not be configured together with the Single Bill for Driver Statement setting. Refer to the \*\*Configuration Dependencies and Incompatible Settings \*\*section for guidance.
</Warning>

### Ignore Zero Valued Transactions

When enabled, this setting excludes invoices and bills with a **total financial value of zero**, meaning transactions that have no overall impact on the accounts will not be exported.

<Note>
  <img alt="Image showing sample Alvys Invoice with total billable of $0" />

  *Image showing sample Alvys Invoice with total billable of \$0*
</Note>

### Create Vendor Using 1099 Tax Company

The **“Create Vendor Using 1099 Tax Company”** setting allows users to determine whether vendors should be created in QuickBooks Online (QBO) using the tax company details (Tax Company Name and Address) specified in the **Tax Information** section of the Alvys driver profile (for either company drivers or owner-operators with the tax category of 1099).

**When this setting is enabled:**

If the vendor does **not** exist in QBO, a vendor will be automatically created when the driver statement is generated, using the Tax Company Name as the vendor's name and the Tax Company Address as the vendor address.

If the vendor **already exists** in QBO, the user must ensure that the vendor's name matches the Tax Company Name specified in the Alvys driver profile to avoid conflicts and create duplicates.

<Note>
  <img alt="Image showing the Tax Company Name and Company Address" />

  *Image showing the Tax Company Name and Company Address*
</Note>

### Carrier Statements

This setting must be enabled to export carrier statements as bills when generating a Carrier Statement from the [Carrier Settlements module](https://app.alvys.com/#/accounting/settlements).

If you use the Carrier Settlements module to generate statements for external carriers and want these statements automatically exported to QuickBooks Online (QBO) upon generation, this setting must be enabled. This is the **only** scenario in which this option should be turned on.

If you do not use the Carrier Settlements module and want carrier statements to be exported only when the carrier invoice is manually uploaded for a trip, this setting should be **disabled**, and the option to generate carrier invoices separately should be **enabled**.

Alternatively, if you prefer carrier statements to be exported only when the customer invoice is generated on a load, this setting should also be **disabled**, and the option to generate carrier invoices separately should remain **disabled**.

### Export Company Fuel Expense

The TMS allows users to record fuel transactions, either manually or imported directly from the fuel provider. These transactions can be viewed in the\*\* \*\*[Alvys Fuel Report](https://app.alvys.com/#/reports/fuel).

In the fuel report, if a transaction is marked “Deduct Transaction” true, the cost will be deducted from the linked driver during payroll (statement generation). If it is not deducted, Deduct Fuel false **(-)**, the transaction is treated as a company expense.

<Note>
  <img alt="Image showing the Alvys Fuel Report with the Deduct Transaction highlighted" />

  *Image showing the Alvys Fuel Report with the Deduct Transaction highlighted*
</Note>

When the “Export Company Fuel Expense” setting is enabled, fuel transactions where Deduct Fuel is set to false (-) (i.e., fuel costs not deducted from drivers) are exported to QuickBooks Online as bills. This allows the company to track and manage fuel expenses not charged to drivers, such as those for company-owned vehicles. Exports are scheduled daily at 6:30 AM UTC

<Warning>
  ⚠️ Please note: if a user was not previously configured to export company fuel transactions and later enables this setting, past transactions will not be exported automatically. Additionally, if an export fails for any reason, contact\*\* \*\*[Alvys Support](mailto:support@alvys.com)[ ](mailto:support@alvys.com)to have those transactions exported.
</Warning>

### Export Company Toll Expense

The TMS allows users to record toll transactions, either manually or imported directly from the toll provider. These transactions can be viewed in the [Alvys Toll Report](https://app.alvys.com/#/reports/toll).

If a transaction is marked “Deduct Toll” true, the cost will be deducted from the linked driver during payroll. If it is not deducted, Deduct Toll false (-), the transaction is treated as a company expense.

<Note>
  <img alt="Image showing the Alvys Toll Report with the Deduct Transaction highlighted" />

  *Image showing the Alvys Toll Report with the Deduct Transaction highlighted*
</Note>

When the “**Export Company Toll Expense**” setting is enabled, toll transactions where Deduct Toll is set to false (i.e., toll costs not deducted from drivers) are exported to the external accounting system as bills. This allows the company to track and manage toll expenses not charged to drivers, such as those incurred by company-owned vehicles. Exports are scheduled daily at 7:30 AM UTC.

### Reference number prefix

This setting allows Alvys’ predefined prefixes to be applied to transaction reference numbers, altering how transactions are identified when sent from Alvys to QuickBooks Online (QBO). Different transaction types, such as Load Invoices, Bills from Trips, and Bills from Paystubs, have specific prefixes. For example, an invoice might appear as **ALD-100000**.

**Alvys Predefined Prefixes:**

* **ALD** – Load
* **ATP** – Trip
* **APS** – Paystub
* **AEK** – E-Check
* **AFL** – Fuel
* **ADT** – Deduction
* **ATL** – Toll
* **AAC** – Accessorial

Users should enable this setting **only** if reference numbers will help organize and identify transactions originating from Alvys. To locate transactions with prefixes, simply enter the reference number, including the prefix, into the QuickBooks search field.

<Note>
  <img alt="Image showing the QuickBooks Online global search with the exported invoice with Alvys predefined prefix" />

  *Image showing the QuickBooks Online global search with the exported invoice with Alvys predefined prefix*
</Note>

In addition to the reference number prefix, users can configure a **fleet prefix**, which applies only to customer invoices exported to QBO. Adding a fleet-specific prefix allows invoices to be easily differentiated across multiple fleets. See the following help center article to configure\*\* \*\*[fleet prefixes](/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys)

**Priority of Prefixes (Reference Number Prefix vs Fleet Prefix):**

If both the external accounting setting for the reference number prefix and the fleet prefix are enabled, the fleet prefix takes precedence for invoices and will be prepended to the invoice number. Other transaction types, such as bills, will continue to use the standard reference number prefix.

### Custom Field

QuickBooks Online (QBO) Custom Fields are user-defined fields that allow additional data to be captured on transactions, such as invoices, to support reporting, tracking, or other operational needs.

In Alvys, the **Custom Field option** currently supports mapping **only the Load Order Number** from a load to a QBO custom field on **customer invoices**. When enabled this ensures that each invoice exported from Alvys with the load order number set is mapped to the custom field.

The custom field mapping applies **only to invoices**; it does not affect other transactions such as bills, from paystubs, or other transaction types. To use this feature, a custom field must first be **created in QBO** and **enabled for invoices**.

\*\*Steps to create and enable a custom field in QBO: \*\*[Create and edit custom fields](https://quickbooks.intuit.com/learn-support/en-global/help-article/custom-templates/create-edit-custom-fields-quickbooks-online/L56PQNif3_ROW_en)

<Info>
  💡 In **QuickBooks Online**, the maximum number of characters you can enter in a **custom field** is **30 characters**.
</Info>

### Subsidiaries

Alvys subsidiaries can be mapped to **QuickBooks Online (QBO) Classes** (also called departments) or **Locations**. This mapping allows you to track transactions and generate reports for each subsidiary in QBO.

* **Classes (Departments):** Use classes if you want to track income, expenses, and transactions at a more detailed, departmental level within a subsidiary. Classes can be assigned **per transaction line item** or to the entire transaction.
* **Locations:** Use locations if you want to track financial activity at a broader, global level for the entire subsidiary. Locations are applied **transaction-wide**, not per line item.

<Warning>
  ⚠️ **A subsidiary can only be assigned to either Classes or Locations, not both.**
</Warning>

**Prerequisites Before Mapping Subsidiaries in Alvys:**

Before you map fleets in Alvys, you need to **set up the corresponding Classes or Locations in QuickBooks Online**:

1. **Decide how you want to track subsidiaries in QBO**
2. **Enable Classes or Locations in QBO**
3. **Create Classes or Locations in QBO**

   Use the provided links below to learn more about setting up QBO classes and locations in QBO

   * [Get started with class tracking](https://quickbooks.intuit.com/learn-support/en-global/help-article/class-list/get-started-class-tracking-quickbooks-online/L04INPWiy_ROW_en)
   * [Using classes and locations](https://quickbooks.intuit.com/au/blog/product-update/using-classes-and-locations-in-quickbooks-online/)
   * [Create and manage classes](https://quickbooks.intuit.com/learn-support/en-global/help-article/class-list/create-manage-classes-quickbooks-online/L1QzEOUxM_ROW_en)
   * [Track locations](https://quickbooks.intuit.com/learn-support/en-global/help-article/track-location/set-use-location-tracking/L2raFkEBC_ROW_en)

### Fleets

Alvys fleets can also be mapped to Classes or Locations in QBO. This allows your company to track revenue, costs, and other financial activity associated with each fleet individually.

* **Classes (Departments/Fleets):** Ideal if you want to assign each fleet to a separate department or category. Classes can be applied **per line item or per transaction**, giving granular insight into performance and profitability.
* **Locations:** Can be used if you want to track the fleet’s transactions at a **broader, global level**, but this is less common for fleets since line-item granularity is usually preferred.

**Fleets can only be assigned to Classes or Locations, not both.**

**Prerequisites Before Mapping Fleets in Alvys:**

Before you map fleets in Alvys, you need to **set up the corresponding Classes or Locations in QuickBooks Online**:

1. Decide how you want to track fleets in QBO
2. Enable Classes or Locations in QBO
3. Create Classes or Locations in QBO

### Export Customer Payments

When enabled, customer payments recorded manually against a load or uploaded via a factoring report are exported to QuickBooks Online every five minutes.

**The following customer payments are included in the export:**

* Payments added **manually** on loads
* Payments added through **factoring report uploads** for factoring loads

  **Please note:**
* Uploading a purchase report on the factoring page does not affect payments sent to the external accounting system. Additionally, any factoring fees applied to loads during the purchase report upload are not exported to QuickBooks Online.
* Only the **final payment amount** is exported to QBO. If multiple payments are recorded for a load, **partial payments are not exported**. The payment is sent only when the total paid amount equals the total billable amount.

After enabling this option, you will be prompted to select a **deposit account** in the setup where customer payments should be recorded. Accounts such as **Accounts Receivable** are **not valid deposit accounts** and should not be used for customer payment configuration.

<Note>
  <img alt="Image showing the Deposit Account mapping in the Alvys QBO setup." />

  *Image showing the Deposit Account mapping in the Alvys QBO setup.*
</Note>

Although exporting payments to QBO is supported, it is **recommended** to record customer payments directly in QuickBooks Online and allow them to sync back to Alvys.

If a payment export is missed or fails for any reason and the payment is not reflected in QuickBooks Online, contact [Alvys Support](mailto:support@alvys.com) to request a re-export.

### Shared Billing/Intercompany Billing

Shared Billing is used when a load is **invoiced by one subsidiary** (Invoice As) and **tendered by another subsidiary** (Tender As), and both subsidiaries have separate accounting integrations. This setting ensures that all financial transactions are correctly recorded across the two subsidiaries.

**Invoice As Subsidiary (e.g., Alvys Inc)**

<Note>
  <img alt="Image showing the Alvys Invoice Customer As field." />

  *Image showing the Alvys Invoice Customer As field.*
</Note>

Creates a **customer invoice** for the load

Creates an **intercompany bill to the Tender As subsidiary** (Alvys Brokerage) for the carrier/driver cost

**Tender As Subsidiary (e.g., Alvys Brokerage)**

<Note>
  <img alt="Image showing the Tendering As field." />

  *Image showing the Tendering As field.*
</Note>

Creates an **intercompany invoice back to the Invoice As subsidiary**

Creates a **vendor bill to the carrier or driver** for the load

<Warning>
  ⚠️ Shared Billing must be enabled on **both subsidiaries**. Without it, the intercompany transactions or carrier/vendor bills will not export correctly.
</Warning>

## Limits / Unsupported

* Only one QBO company file can be connected per Alvys legal entity. Multi-entity setups require a separate connection for each legal entity.
* QBO Simple Start is not supported because it does not include the Accounts Payable module.
* Location and Class Tracking in QBO require QBO Plus or QBO Advanced.

## FAQs

**Q: Can I connect more than one QBO company file to a single Alvys account?**

**A:** No. Each Alvys legal entity can be connected to one QBO company file.

**Q: What QBO plan do I need to use Class or Location Tracking with Alvys?**

**A:** QBO Plus or QBO Advanced. Class and Location Tracking are not available on Essentials or Simple Start.

**Q: What does the Carrier Invoice Requirement setting do?**

**A:** When enabled, Alvys requires a carrier invoice number to be recorded on a load before that load's carrier bill can be exported to QBO.

**Q: What happens to the QBO connection if my Intuit session is invalidated?**

**A:** The OAuth token expires. Disconnect and reconnect to generate a new token.

**Q: How do I export invoices manually if auto-export is disabled?**

**A:** Open the load, navigate to the Transactions tab, and click **Export to QBO**.

## Go Deeper

* [QuickBooks Online Prerequisites (Start Here)](/en/help/integrations/quickbooks-online-prerequisites)
* [How to Map Accounts for QuickBooks Online](/en/help/integrations/how-to-map-accounts-for-quickbooks-online)
* [How to Export and Manage Transactions in QuickBooks Online](/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online)
* [QuickBooks Online: Identifying and Resolving Failed Transactions](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)


# Business Central: Connect & configure
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-business-central-to-alvys-and-configure-settings

Connect a Business Central company to an Alvys subsidiary, then configure transaction export types, vendor matching, and fleet-to-dimension mapping for BC.

<Note>
  Connect (authenticate and link) your Business Central accounting system to Alvys and configure how transaction types, drivers, carriers, subsidiaries, and fleets are exported and synced.
</Note>

## Overview

The Alvys to Business Central integration exports, syncs, and posts customer invoices, carrier bills, and driver settlements from Alvys to Business Central (also called Microsoft Dynamics 365 Business Central or BC) and imports payment updates back into Alvys. After connecting, you configure which transaction types to export, how vendors are matched or created, and how subsidiaries and fleets map to Business Central dimensions.

Each Alvys subsidiary is connected to Business Central separately. Complete this process once per subsidiary.

## Before You Start

Before initiating the connection within the Alvys platform, your Business Central environment must be structurally and administratively prepared. Ensure that your tenant has an active Business Central subscription with an administrator user and that the following items are configured:

* **Company Architecture Setup** (Standard Multiple Companies or MEM Entity Codes)
* **Account Licensing & Permissions** (Essentials/Premium License and Permission Sets)
* **Chart of Accounts Configuration** (Active Revenue/Expense Accounts with Direct Posting enabled)
* **Posting Groups** (Customer, Vendor, and General Business Posting Groups)
* **Tax Setup & Calculation** (Tax Groups and Tax Area Codes)
* **General Journal Setup**
* **IRS 1099 Configuration** (1099 Form Boxes and Vendor Card assignment)

<Info>
  💡 If these are not set up, refer to the Business Central: Prerequisites article before proceeding to the connection steps below.
</Info>

## Steps

Navigate to the [Alvys Integrations Page](https://app.alvys.com/#/manage/integrations) by clicking your username in the bottom-left corner and selecting **Integrations**, or by copying and pasting the following URL into your browser: [https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations).

<Note>
  <img alt="Management menu with Integrations highlighted" />

  *Management menu with Integrations highlighted*
</Note>

From the list of integration types, select **Accounting**.

<Note>
  <img alt="Image showing accounting Integration category dropdown" />

  *Image showing accounting Integration category dropdown*
</Note>

By default, the first subsidiary in your list is selected. If needed, choose a different subsidiary to add the integration to. Click the ✏ (edit) icon next to Business Central to open the integration dialog box.

<Note>
  <img alt="Business Central Tile under the accounting section of the Integrations List." />

  \*Business Central Tile under the accounting section of the Integrations List. \*
</Note>

Select the subsidiary you want to connect to Business Central, then click Save.

<Note>
  <img alt="Shows the 'Add Integration' modal with Alvys Inc selected under the Subsidiaries configuration options." />

  *Shows the "Add Integration" modal with **Alvys Inc** selected under the Subsidiaries configuration options.*
</Note>

<Warning>
  ⚠️ The integration must be completed one subsidiary at a time. After configuring a subsidiary, return to the Integrations page and repeat these steps for any remaining subsidiaries.
</Warning>

In the dialog box, click Login. You will be redirected to sign in using the integration user credentials. Enter the user email and password.

<Note>
  <img alt="Displays the 'Business Central Integration' setup step with a blue box highlighting the clickable Login link." />

  *Displays the "Business Central Integration" setup step with a blue box highlighting the clickable **Login** link.*
</Note>

After successful login, select the appropriate **Business Central Company** from the list.

<Note>
  <img alt="Features step 2 of the integration wizard with a blue box focusing on the company selection dropdown field." />

  *Features step 2 of the integration wizard with a blue box focusing on the company selection dropdown field.*
</Note>

The companies shown here are those that exist within your Business Central environment. To view your companies within Business Central:

1. Click the **Search** icon (magnifying glass) in the top right of the Business Central header.
2. Search for **Companies** and select the related link.

<Note>
  <img alt="Shows Business Central application menu search bar with a blue box highlighting the Companies task list option." />

  * Shows Business Central application menu search bar with a blue box highlighting the **Companies** task list option.\*
</Note>

Next, select the Default Journal you would like Alvys to use.

<Note>
  <img alt="Shows step 3 of the configuration setup, prompting the user to assign a default general journal for journal entries." />

  *Shows step 3 of the configuration setup, prompting the user to assign a default general journal for journal entries.*
</Note>

Then, select the Default Payment Methods for Carriers. This configuration is relevant for vendor-related transactions, such as Purchase Invoices. When Alvys exports a bill to Business Central, it "stamps" that specific Purchase Invoice with the Payment Method Code you select during this setup to define the settlement type. Furthermore, if a vendor match is not found in Business Central during the export process, Alvys creates the vendor record and assigns this selected payment code directly to the Vendor Card.

<Note>
  <img alt="Shows step 4 of the setup, prompting the selection of a default payment method for carriers." />

  *Shows step 4 of the setup, prompting the selection of a default payment method for carriers.*
</Note>

To create or view payment methods in Business Central, use the **Search** icon to find **Payment Methods**.

<Note>
  💡 Selecting a default payment method for vendors is not mandatory, but it offers ease to users.
</Note>

Next, input the **IRS 1099 Code**. This is for vendors/carriers who are 1099-liable. If you do not have these types of vendors, you do not have to input this information. The IRS code must be configured in Business Central for the vendor to be reported correctly.

<Note>
  <img alt="Displays step 5 of the setup tracking the input field for the IRS 1099 Code." />

  *Displays step 5 of the setup tracking the input field for the IRS 1099 Code.*
</Note>

Once these steps are completed the user can click the **“Next”** button to move on to the configuration settings

<Note>
  <img alt="Shows the finalized Step 1 configuration screen with a blue box highlighting the Next navigation button." />

  *Shows the finalized Step 1 configuration screen with a blue box highlighting the Next navigation button.*
</Note>

## Configuration Settings

After successful validation, use this section to define how transactions flow from Alvys to Business Central (BC). These settings determine what data is sent, when it is triggered, and how it appears in your General Ledger.

<Note>
  <img alt="Account Settings dialogue in Alvys integrations page" />

  *Account Settings dialogue in Alvys integrations page*
</Note>

### Transaction Types

**There are two (2) transaction types available for synchronization:**

1. **Revenue** This option determines whether revenue transactions are synchronized. When enabled, income-related financial data such as customer invoices (sales invoices) will be exported.
2. **Expense** This option determines whether expense transactions are synchronized. When enabled, cost-related financial data, such as driver pay and carrier bills (purchase invoices), will be exported.

<Note>
  <img alt="Displays Step 2 (Account Settings) with active checkboxes enabling both Revenue and Expense mappings." />

  *Displays Step 2 (Account Settings) with active checkboxes enabling both Revenue and Expense mappings.*
</Note>

<Warning>
  ⚠️ Your selection here takes precedence over all other configuration settings. These options determine the type of financial data that will be integrated. Enable only the options you intend to export to Business Central. Once selected, additional settings are available to further control how transactions are exported.
</Warning>

### Ignore Driver Bills

This setting prevents the export of all driver bills, including company drivers and owner-operators, to Business Central. When enabled, driver-associated bills will not be exported, giving users greater control over which transactions are sent to external accounting systems. This option is commonly enabled when driver pay is managed outside of Business Central, such as through a payroll system or a separate driver settlement solution. Please note that even when this setting is enabled, external carrier bills, subsidiary carrier bills, and company expenses such as fuel and tolls may still be exported if those options are configured.

### Single Bill for Driver Statement

This setting controls how bills for company drivers and owner operators are exported to Business Central. It is used to consolidate all charges and transactions related to a driver, including trips, fuel, tolls, and other expenses, into a single bill per driver statement.

When enabled, a single bill is exported to Business Central for the total net amount of the paystub. All components of driver pay are consolidated into this bill, including trip pay, accessorials, deductions, credits, reimbursements, and any other adjustments. Each component appears as a **separate line item** on the bill, providing detailed visibility while keeping the accounting export grouped into one transaction. This option is commonly used when driver pay is processed on a scheduled basis, such as weekly or biweekly payroll cycles.

When disabled, generating a customer invoice will also export the driver bill for the individual trip. Each trip or delivery is exported as a separate bill. When a paystub is generated, multiple bills are exported for each transaction type on the paystub, including separate bills for credits, deductions/reimbursements.

### Generate Carrier Invoice Separately

This setting applies to brokerage-type trips where an external carrier and its assets are assigned to a load. When enabled, the system verifies that a carrier invoice document has been uploaded before exporting the carrier bill to Business Central. Specifically, when a brokerage trip is delivered or released and the user uploads a document of the type of carrier invoice, the system will export the carrier bill to Business Central. This can also be triggered when a user generates the customer invoice for a load; the system will verify that a carrier invoice has been uploaded, and if no carrier invoice is found, the carrier bill will not be exported to Business Central. This setting should only be enabled when carrier invoices are required as part of the workflow prior to exporting external carrier bills for payment. If this setting is disabled, generating the customer invoice for a trip with an external carrier will automatically export the carrier bill to Business Central, even if the carrier invoice has not been uploaded.

<Info>
  💡 If this setting was previously enabled but no carrier invoice document was uploaded, the carrier bill was not created and therefore was not exported to Business Central. To resolve this, upload a document of type **Carrier Invoice** to the trip, then select Regenerate Invoice. This will create the carrier bill and initiate its export to Business Central.
</Info>

### Process Statement by Tax Category

When enabled, only bills for 1099 drivers are exported to Business Central. Bills for W-2 drivers are excluded, allowing users to manage W-2 driver payments in a separate payroll system. When disabled, bills for both W-2 and 1099 drivers are exported.

This setting is typically enabled by tenants that handle W-2 driver compensation outside of Business Central and want to prevent those purchase invoices from being sent while still exporting 1099 driver expenses.

<Note>
  <img alt="Image showing the Tax Category on driver profile." />

  **Image showing the Tax Category on driver profile.**
</Note>

<Info>
  💡 Some settings must be used together, while others should not be enabled at the same time. Refer to the **Configuration Dependencies and Incompatible Settings** section for guidance.
</Info>

### Pay Subsidiary Carrier

This setting applies to trips involving a subsidiary carrier (i.e., a carrier operating under a subsidiary of the main company) that is assigned alongside the tenant’s internal assets. By default, when a driver statement is generated and assuming the Single Bill for Driver Statement setting is enabled, a bill is exported for the tenant’s driver on the trip.

When Pay Subsidiary Carrier is enabled, this behavior changes; instead of exporting a bill/purchase invoice for the driver when a paystub is generated, the system exports a purchase invoice for the subsidiary carrier when the load invoice is generated.\*\* E.g. Alvys Inc \*\*

<Note>
  <img alt="Notion Image" />
</Note>

<Warning>
  ⚠️ Certain settings are mutually exclusive and should not be enabled at the same time. The Pay Subsidiary Carrier setting should not be configured together with the Single Bill for Driver Statement setting. Refer to the \*\*Configuration Dependencies and Incompatible Settings \*\*section for guidance.
</Warning>

### Ignore Zero Valued Transactions

When enabled, this setting excludes invoices and bills with a **total financial value of zero**, meaning transactions that have no overall impact on the accounts will not be exported.

<Note>
  <img alt="Image showing sample Alvys Invoice with total billable of $0" />

  **Image showing sample Alvys Invoice with total billable of \$0**
</Note>

<Warning>
  ⚠️ If the **Ignore Zero Valued Transactions** setting was previously enabled and a transaction with a total value of $0 was generated, such as a customer sales invoice/vendor purchase invoice, an issue may occur if that transaction is later updated to a value greater than $0. When attempting to export the updated transaction to Business Central, the system may encounter the following error: **"A digit was expected at position 3 in '(ID)'.”**

  **If an error with this format occurs, please contact **[Alvys Support](mailto:support@alvys.com)** so the transaction can be re-exported.**

  <img alt="Notion Image" />
</Warning>

### Create Vendor Using 1099 Tax Company

The **“Create Vendor Using 1099 Tax Company”** setting allows users to determine whether vendors should be created in Business Central using the tax company details (Tax Company Name and Address) specified in the **Tax Information** section of the Alvys driver profile (for either company drivers or owner-operators with the tax category of 1099).

<Note>
  <img alt="Image showing the Tax Company Name and Company Address" />

  **Image showing the Tax Company Name and Company Address**
</Note>

When this setting is enabled: If the vendor does **not** exist in Business Central, a vendor will be automatically created when the driver statement is generated, using the Tax Company Name as the vendor's name and the Tax Company Address as the vendor address. If the vendor **already exists** in Business Central, the user must ensure that the vendor's name matches the Tax Company Name specified in the Alvys driver profile to avoid conflicts and create duplicates.

### Match Vendors by Name

The **“Match vendors by name”** setting controls how Alvys finds an existing Business Central vendor for a carrier.

Alvys always tries to match a carrier to a vendor by MC number first. This setting decides what happens when no MC-number match is found:

* **Enabled (the default).** Alvys falls back to matching by name. This is the long-standing behavior, so leaving it on changes nothing.
* **Disabled.** Alvys matches by MC number only. When there is no MC-number match it creates a **new vendor** rather than matching on a name, which keeps carriers that share a name but hold different MC numbers separate.

Turn it off if carrier bills have been posting under the wrong vendor because two of your carriers trade under the same name. Because the fallback is what causes that, removing the fallback is the fix.

<Warning>
  **Carrier subsidiaries that export driver statements should leave this setting enabled.** Drivers do not have MC numbers, so they are matched by name. With the setting off, Alvys cannot find the matching driver in Business Central.
</Warning>

### Carrier Statements

This setting must be enabled to export carrier statements as bills when generating a Carrier Statement from the [Carrier Settlements module](https://app.alvys.com/#/accounting/settlements).

If you use the Carrier Settlements module to generate statements for external carriers and want these statements automatically exported to business central upon generation, this setting must be enabled. This is the **only** scenario in which this option should be turned on.

If you do not use the Carrier Settlements module and want carrier statements to be exported only when the carrier invoice is manually uploaded for a trip, this setting should be **disabled**, and the option to generate carrier invoices separately should be **enabled**.

Alternatively, if you prefer carrier statements to be exported only when the customer invoice is generated on a load, this setting should also be **disabled**, and the option to generate carrier invoices separately should remain **disabled**.

### Export Company Fuel Expense

The TMS allows users to record fuel transactions, either manually or imported directly from the fuel provider. These transactions can be viewed in the\*\* \*\*[Alvys Fuel Report](https://app.alvys.com/#/reports/fuel).

In the fuel report, if a transaction is marked “Deduct Transaction” true, the cost will be deducted from the linked driver during payroll (statement generation). If it is not deducted, Deduct Fuel false **(-)**, the transaction is treated as a company expense.

<Note>
  <img alt="Image showing the Alvys Fuel Report with the Deduct Transaction highlighted" />

  **Image showing the Alvys Fuel Report with the Deduct Transaction highlighted**
</Note>

When the “Export Company Fuel Expense” setting is enabled, fuel transactions where Deduct Fuel is set to false (-) (i.e., fuel costs not deducted from drivers) are exported to Business Central as purchase invoices. This allows the company to track and manage fuel expenses not charged to drivers, such as those for company-owned vehicles. Exports are scheduled daily at 6:30 AM UTC

<Warning>
  ⚠️ Please note: if a user was not previously configured to export company fuel transactions and later enables this setting, past transactions will not be exported automatically. Additionally, if an export fails for any reason, contact\*\* \*\*[Alvys Support](mailto:support@alvys.com)[ ](mailto:support@alvys.com)to have those transactions exported.
</Warning>

### Export Company Toll Expense

The TMS allows users to record toll transactions, either manually or imported directly from the toll provider. These transactions can be viewed in the [Alvys Toll Report](https://app.alvys.com/#/reports/toll).

If a transaction is marked “Deduct Toll” true, the cost will be deducted from the linked driver during payroll. If it is not deducted, Deduct Toll false (-), the transaction is treated as a company expense.

<Note>
  <img alt="Image showing the Alvys Toll Report with the Deduct Transaction highlighted" />

  **Image showing the Alvys Toll Report with the Deduct Transaction highlighted**
</Note>

When the “**Export Company Toll Expense**” setting is enabled, toll transactions where Deduct Toll is set to false (i.e., toll costs not deducted from drivers) are exported to the Business Central system as bills. This allows the company to track and manage toll expenses not charged to drivers, such as those incurred by company-owned vehicles. Exports are scheduled daily at 7:30 AM UTC.

### Reference number prefix

This setting allows Alvys’ predefined prefixes to be applied to transaction reference numbers, altering how transactions are identified when sent from Alvys to Business Central. Different transaction types, such as Load Invoices, Bills from Trips, and Bills from Paystubs, have specific prefixes. For example, an invoice might appear as **ALD-100000**. **Alvys Predefined Prefixes:**

* **ALD** – Load
* **ATP** – Trip
* **APS** – Paystub
* **AEK** – E-Check
* **AFL** – Fuel
* **ADT** – Deduction
* **ATL** – Toll
* **AAC** – Accessorial

Users should enable this setting **only** if reference numbers will help organize and identify transactions originating from Alvys.

In addition to the reference number prefix, users can configure a **fleet prefix**, which applies only to customer invoices exported to Business Central. Adding a fleet-specific prefix allows invoices to be easily differentiated across multiple fleets. See the following help center article to configure\*\* \*\*[fleet prefixes](/en/help/assets-fleet/how-to-add-and-manage-fleets-in-alvys)

**Priority of Prefixes (Reference Number Prefix vs Fleet Prefix):**

If both the external accounting setting for the reference number prefix and the fleet prefix are enabled, the fleet prefix takes precedence for invoices and will be prepended to the invoice number. Other transaction types, such as bills, will continue to use the standard reference number prefix.

### Subsidiaries

Alvys subsidiaries can be mapped to an Entity Dimension created in Business Central. Entity dimensions are typically established to distinguish and report on multiple legal entities within a single database environment. For tenants using Multi-Entity Management (MEM), Business Central generally operates as a single database, or single company, that contains multiple legal entities. To ensure proper financial separation and reporting, a Global Dimension commonly labeled Entity, or Subsidiary is used to tag all transactions accordingly. In this structure, each Alvys subsidiary must be mapped to the corresponding Business Central dimension value.

<Warning>
  ⚠️ Subsidiary mapping is mandatory for users who manage multiple legal entities within a single Business Central company (often referred to as Multi-Entity Management or MEM).
</Warning>

However, if the Business Central environment is configured with multiple separate companies, meaning individual databases, rather than a single company utilizing dimensions for MEM, the subsidiary mapping step within the integration is typically unnecessary. In this scenario, the integration logic differs because the Entity is inherently defined by the specific company connection itself.

### Prerequisites for Successful Subsidiary Mapping

Before completing this in Alvys, you must ensure your Dimensions are correctly established in Business Central: **Dimension Definition:** Ensure your "Entity" or "Subsidiary" dimension is set as a **Global Dimension** in your General Ledger Setup. **Value Creation:** Every subsidiary you intend to use must already exist as a **Dimension Value** within that dimension. For detailed instructions on establishing and configuring dimensions within Microsoft Business Central, please refer to the official documentation: [Working with Dimensions - Business Central | Microsoft Learn](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-dimensions)\*\* \*\*[Set up dimensions in Dynamics 365 Business Central](https://learn.microsoft.com/en-us/training/modules/dimensions-dynamics-365-business-central/)

### How to Map Alvys Subsidiaries to Business Central

**Select the Subsidiaries Checkbox:** Within the Alvys integration setup, check the **Subsidiaries** box.

<Note>
  <img alt="Shows an unselected configuration checkbox for the Subsidiaries field parameter." />

  *Shows an unselected configuration checkbox for the **Subsidiaries** field parameter.*
</Note>

**Access the subsidiary mapping Step**

<Note>
  <img alt="Displays a progress indicator icon highlighting Step 3 (Subsidiaries) within a multi-step setup flow." />

  *Displays a progress indicator icon highlighting **Step 3 (Subsidiaries)** within a multi-step setup flow.*
</Note>

Choose the class option from the dropdown menu located under the Subsidiary heading.

<Note>
  <img alt="Shows Step 3 (Subsidiaries) containing an unconfigured Class dropdown menu." />

  *Shows Step 3 (Subsidiaries) containing an unconfigured Class dropdown menu.*
</Note>

Link each relevant subsidiary to its corresponding option presented in the right-hand dropdown menu.

<Note>
  <img alt="hows Step 3 (Subsidiaries) tracking the configuration line for Alvys Inc alongside a searchable dropdown menu." />

  *hows Step 3 (Subsidiaries) tracking the configuration line for Alvys Inc alongside a searchable dropdown menu.*
</Note>

### Fleets

Mapping Alvys Fleets to Business Central Dimensions allows you to track profitability by specific fleet or truck groups within your financial statements. In Business Central, this is usually handled via Dimensions. In Alvys, this mapping ensures that every time a load is synced, the correct "Tag" is attached to the General Ledger entry.

<Warning>
  ⚠️ The Alvys integration logic allows for **either** Fleet mapping or Subsidiary (Entity) mapping, but **not both** simultaneously.
</Warning>

### How to Map Alvys Fleets to Dimensions:

Select the **Fleets** checkbox, which will create an additional step called **Fleets**.

<Note>
  <img alt="Displays an unselected configuration checkbox for the Fleets field" />

  \*Displays an unselected configuration checkbox for the Fleets field \*
</Note>

Click on the **Fleets** step.

<Note>
  <img alt="Displays a progress indicator icon highlighting Step 4 (Fleets) within a multi-step setup flow." />

  *Displays a progress indicator icon highlighting Step 4 (Fleets) within a multi-step setup flow.*
</Note>

Choose the class option from the dropdown menu located under the Fleets heading.

<Note>
  <img alt="Shows Step 4 (Fleets) featuring an unconfigured Class sorting dropdown menu." />

  *Shows Step 4 (Fleets) featuring an unconfigured Class sorting dropdown menu.*
</Note>

Proceed by mapping each specific Alvy's fleet to the corresponding option presented in the right-hand dropdown menu.

### Shared Billing/Intercompany Billing

<Warning>
  🚫 It is not recommended to use Shared Billing with the Alvys Business Integration Central, as it is currently not stable.
</Warning>

Shared Billing is used when a load is **invoiced by one subsidiary** (Invoice As) and **tendered by another subsidiary** (Tender As), and both subsidiaries have separate accounting integrations. This setting ensures that all financial transactions are correctly recorded across the two subsidiaries.

**Invoice As Subsidiary (e.g., Alvys Inc)**

<Note>
  <img alt="view of the billing configuration dropdown menu with Invoice Customer As set to Alvys Inc." />

  *view of the billing configuration dropdown menu with Invoice Customer As set to Alvys Inc.*
</Note>

* Creates a **customer invoice** for the load
* Creates an **intercompany bill to the Tender As subsidiary** (Alvys Brokerage) for the carrier/driver cost

**Tender As Subsidiary (e.g., Alvys Brokerage)**

<Note>
  <img alt="Displays a minimal status line reflecting that the current load is being handled under Tendering As: Alvys Brokerage." />

  *Displays a minimal status line reflecting that the current load is being handled under Tendering As: Alvys Brokerage.*
</Note>

* Creates an **intercompany invoice back to the Invoice As subsidiary**
* Creates a **vendor bill to the carrier or driver** for the load

<Warning>
  ⚠️ Shared Billing must be enabled on **both subsidiaries**. Without it, the intercompany transactions or carrier/vendor bills will not export correctly.
</Warning>

## Send E-Check on Generation

This setting controls whether e-Check transactions created in Alvys are automatically exported to Business Central at the moment the e-Check is generated.

When this setting is enabled, Alvys immediately creates and transmits a journal entry to the selected General Journal Batch in Business Central. The journal entry will post according to the journal batch configuration and the user permissions established in Business Central. It is important to ensure that the designated General Journal Batch exists, is not blocked, and that the integration user has sufficient permissions to create and post journal entries.

If this setting is disabled, e-Check journal entries will not export automatically. Instead, the export occurs when the e-Check is included on a generated driver statement or when a carrier bill is exported.

## Add Asset Dimensions

The **Add Asset Dimensions** setting allows users to map Alvys Assets (trucks and drivers) to Dimensions in Microsoft Dynamics 365 Business Central. In BC Dimensions are used to categorize financial data for reporting and analysis, enabling organizations to track profitability and performance by specific operational assets.

Before enabling this feature in Alvys, the required Dimension Codes and Dimension Values must be created in Business Central.

**Create Dimension Codes (in Business Central):**

* Navigate to the **Dimensions** page (🔍 Search → *Dimensions*).
* Click **New**.
* Create a dimension code such as **DRIVERS** (Name: Drivers).
* Create a dimension code such as **TRUCKS** (Name: Trucks).

  **Create Dimension Values (in Business Central):**
* Open the **DRIVERS** dimension and select **Dimension Values**.
* Click **New** and create a value for each driver (for example, Code: JOHN).
* Open the **TRUCKS** dimension and select **Dimension Values**.
* Click **New** and create a value for each truck (for example, Code: T01).

  \*\*Microsoft documentation reference: \*\*[Work with dimensions](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-dimensions)

  After the Dimension Codes and Values are created in Business Central, the user must map the **Dimension Codes** in the Alvys integration settings. In Alvys, you will map:
* **Alvys Driver** → Business Central Dimension Code: **DRIVERS**
* **Alvys Truck** → Business Central Dimension Code: **TRUCKS**

<Info>
  💡 The user should not map individual Dimension Values in Alvys. During transaction export, Alvys automatically sends the driver and truck identifiers associated with the transaction.
</Info>

## Configuration Dependencies and Incompatible Settings

Some Configuration settings in the Alvys Business Central integration are mutually exclusive (meaning they cannot be enabled at the same time) or render others inactive when enabled. In addition, certain settings may not require configuration at all, depending on the initial selection of Revenue and or Expense transactions

### The Revenue Checkbox

If only the Revenue transaction checkbox is selected (customer invoices, etc.), \*\*do \*\***not** configure any settings related to Expenses, including:

* Single Bill for Driver Statement
* Generate Carrier Invoice Separately
* Process Statement by Tax Category
* Pay Subsidiary Carrier
* Create Vendor Using 1099 Tax Company
* Ignore Driver Bills
* Carrier Statements
* Export Company Fuel Expense (not deducted from a driver)
* Export Company Toll Expense (not deducted from a driver)

<Note>
  <img alt="Displays Step 2 (Account Settings) with only Revenue selected, automatically crossing out all subsequent expense-specific configuration properties." />

  *Displays Step 2 (Account Settings) with only Revenue selected, automatically crossing out all subsequent expense-specific configuration properties.*
</Note>

### Single Bill for Driver Statement

<Note>
  <img alt="Shows the Account Settings interface with Expense mapping enabled and the Single Bill for Driver Statement parameter actively checked." />

  *Shows the Account Settings interface with Expense mapping enabled and the Single Bill for Driver Statement parameter actively checked.*
</Note>

**Do not configure this setting with:**

* **Ignore Driver Bills**
* **Pay Subsidiary Carrier**

**Why:**

Single Bill for Driver Statement assumes that **driver bills are being created and exported**. If driver bills are ignored *(not sent to Business Central)* this consolidation logic no longer applies and will conflict with the export process. Also, if configured with pay subsidiary carrier bills, the single bill for driver statement will take precedence.

### Process Statement by Tax Category

<Note>
  <img alt="Features blue boxes highlighting both Single Bill for Driver Statement and Process Statement By Tax Category enabled concurrently under Expense settings." />

  *Features blue boxes highlighting both Single Bill for Driver Statement and Process Statement By Tax Category enabled concurrently under Expense settings.*
</Note>

**Configuration Dependency:**

* **Single Bill for Driver Statement must be enabled** along with this setting

  **Do not configure this setting with:**
* **Ignore Driver Bills**
* **Pay Subsidiary Carrier Why: This setting depends on driver bill data to separate payments by tax type. If driver bills are ignored or billing is redirected to a subsidiary carrier, tax-based filtering cannot function correctly.**

### Pay Subsidiary Carrier

<Note>
  <img alt="Displays the active configuration of Pay Subsidiary Carrier, which renders conflicting single bill options struck through in red." />

  *Displays the active configuration of Pay Subsidiary Carrier, which renders conflicting single bill options struck through in red.*
</Note>

**Do not configure this setting with:**

* **Single Bill for Driver Statement**
* **Process Statement By Tax Category**
* **Create Vendor Using 1099 Tax Company**
* **Ignore Driver Bills**

**Why:**

When this setting is enabled, billing responsibility shifts **away from the driver entirely**. Any configuration that assumes driver-based billing, or driver vendor creation becomes invalid.

### Ignore Driver Bills

<Note>
  <img alt="Shows Step 2 (Account Settings) with the Ignore Driver Bills toggle checked under the Expense configuration options." />

  *Shows Step 2 (Account Settings) with the Ignore Driver Bills toggle checked under the Expense configuration options.*
</Note>

**Do not configure this setting with:**

* **Single Bill for Driver Statement**
* **Process Statement By Tax Category**
* **Create Vendor Using 1099 Tax Company**

**Why:**

Each of these settings relies on **driver bills being generated and exported**. Ignoring driver bills removes the underlying data required for these settings to work.

### Create Vendor Using 1099 Tax Company

<Note>
  <img alt="eatures blue boundaries highlighting a joint setup enabling both Single Bill for Driver Statement and Create Vendor Using 1099 Tax company." />

  *eatures blue boundaries highlighting a joint setup enabling both Single Bill for Driver Statement and Create Vendor Using 1099 Tax company.*
</Note>

**Configuration Dependency:**

* **Single Bill for Driver Statement must be enabled** along with this setting

  **Do not configure this setting with:**
* **Pay Subsidiary Carrier**
* **Ignore Driver Bills**

**Why:**

This option assumes driver-based billing based on tax category. If billing is redirected to a subsidiary carrier or driver bills are excluded, vendor creation using tax data is no longer applicable.

### Match Vendors by Name

**Configuration Dependency:**

* **Leave enabled** if this subsidiary is a carrier subsidiary that **exports driver statements**

**Why:**

Vendor matching by MC number only works for parties that have an MC number. Drivers do not, so they are resolved by name. Disabling the name fallback to keep same-named *carriers* distinct also removes the only way Alvys can match a *driver*, and driver statement export stops finding its vendor.

## FAQs

**Q: Can I configure the integration for multiple subsidiaries simultaneously?**

**A:** No. The integration must be configured one subsidiary at a time. Return to Management > Integrations and repeat the connection steps for each additional subsidiary.

**Q: What happens if I enable only the Revenue transaction type?**

**A:** Only customer invoices are exported to Business Central. Carrier bills, driver settlements, and expense-related settings have no effect. Do not enable expense-specific settings when only Revenue is selected.

**Q: What happens if I enable only the Expense transaction type?**

**A:** Only carrier bills and driver settlements are exported to Business Central. Customer invoices are not exported.

**Q: What does "Ignore Driver Bills" do?**

**A:** It excludes driver-level bills from export entirely. Use this when you do not need individual driver payroll entries in Business Central, such as when drivers are paid through a separate payroll system.

**Q: Can I enable "Single Bill for Driver Statement" with "Pay Subsidiary Carrier"?**

**A:** No. These settings are incompatible. Single Bill consolidates driver-level billing, while Pay Subsidiary Carrier redirects billing away from drivers entirely. Enable only one or the other.

**Q: How do I exclude W-2 driver payments from exporting to Business Central?**

**A:** Enable Ignore Driver Bills. This excludes all driver bills from export. If you need to export only certain types of driver payments, review the Process Statement by Tax Category and Single Bill for Driver Statement settings for more targeted control.

**Q: Why am I receiving a digit expectation error when exporting a previously \$0 transaction?**

**A:** This error can occur when a transaction that previously had a $0 value is updated and re-exported. Enabling Ignore Zero Valued Transactions prevents $0 transactions from being sent in the first place, which avoids this error on subsequent updates. If the error persists after enabling this setting, contact Alvys support.

**Q: Can I enable both Ignore Driver Bills and Single Bill for Driver Statement?**

**A:** No. These settings are incompatible. Single Bill depends on driver bills being exported; Ignore Driver Bills removes them before export.

**Q: When do fuel and toll expenses sync to Business Central?**

**A:** Fuel and toll expenses sync when the associated load transaction is exported. If Export Company Fuel Expense or Export Company Toll Expense was not enabled when past transactions were processed, those past transactions will not be retroactively exported after the setting is turned on.

**Q: Do I need to manually map every individual driver and truck as a Dimension Value?**

**A:** No. Subsidiaries and Fleets are mapped as groups, not as individual drivers or trucks. After enabling the Subsidiaries or Fleets setting, you map each Alvys subsidiary or fleet to its corresponding Business Central Dimension value.

**Q: Can I map both Fleets and Subsidiaries to Business Central Dimensions?**

**A:** No. These settings are mutually exclusive. You must choose to map by either Subsidiaries or Fleets, not both simultaneously.

**Q: Why has a carrier bill not exported even though the load invoice was generated?**

**A:** If Generate Carrier Invoice Separately is enabled, the carrier bill will not export until the physical carrier invoice has been received and verified in Alvys. Confirm that the carrier invoice has been marked as received on the load. If the invoice is marked received and the bill still has not exported, contact Alvys support.

**Q: What happens if a vendor match is not found in Business Central during export?**

**A:** If no matching vendor is found by name or External Accounting ID, Alvys automatically creates a new vendor in Business Central using the carrier or driver's profile information, along with the Default Payment Method you selected during setup.

## Go Deeper

* [Business Central: Account Mappings](/en/help/integrations/how-to-set-up-business-central-account-mappings)


# QuickBooks Desktop: Connect & configure
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-quickbooks-desktop-to-alvys-and-configure-settings

Link QuickBooks Desktop to Alvys through the QuickBooks Web Connector, then configure how invoices, carrier bills, and driver settlements sync from QBD.

<Note>
  Connect (link and authenticate) QuickBooks Desktop to Alvys using the QuickBooks Web Connector and configure how transactions are exported and synced. This article covers initial connection setup, configuration settings, and recommended configuration choices.
</Note>

## Overview

The Alvys to QuickBooks Desktop integration exports, syncs, and pushes customer invoices, carrier bills, and driver settlements from Alvys to QuickBooks Desktop (also called QuickBooks Desktop, QBD, or Intuit QuickBooks Desktop). It also imports payment status updates from QuickBooks Desktop back into Alvys. The connection is established using the QuickBooks Web Connector, which must be installed and running on the same computer as QuickBooks Desktop.

Each Alvys subsidiary is connected to QuickBooks Desktop separately.

## Before You Start

Before connecting, confirm the following:

* You have the **"Admin"** or **"Partner Admin"** role in Alvys (the **"CompanyProfileManager"** permission controls access to integration settings).
* QuickBooks Desktop is installed on your computer.
* The QuickBooks Web Connector is installed on the same computer as QuickBooks Desktop. If you do not have it, download it from the Intuit Developer site before continuing.
* QuickBooks Desktop is open and you are logged in as a user with permissions to connect third-party applications.
* The Alvys subsidiary you want to connect has already been created in Alvys.

## Steps

1. Open the QuickBooks Desktop integration in Alvys.
2. Navigate to your username > Integrations, or go directly to [https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations).
3. Select Accounting from the list of integration types.
4. Click the edit icon next to QuickBooks Desktop to open the integration dialogue.

   <img alt="Alvys Integrations page showing Accounting section with QuickBooks Desktop edit icon." />

   \*Alvys Integrations page showing Accounting section with QuickBooks Desktop edit icon. \*
5. Select the Alvys subsidiary you want to connect to QuickBooks Desktop.

   <img alt="Subsidiary selector in Alvys QuickBooks Desktop integration dialog." />

   \*Subsidiary selector in Alvys QuickBooks Desktop integration dialog. \*
6. Click Next to continue to the connection step.
7. Download the QuickBooks Web Connector configuration file. Click the Download QWC File button in the Alvys integration dialog. This downloads a .qwc configuration file that you will open in the QuickBooks Web Connector.

<Note>
  <img alt="Download QWC File button in Alvys integration dialog." />

  \*Download QWC File button in Alvys integration dialog. \*
</Note>

Keep the Alvys integration dialog open: you will need the password shown on this screen when you add the configuration file to the Web Connector.

1. Open the QuickBooks Web Connector. Open the QuickBooks Web Connector on your computer. QuickBooks Desktop must be open and running before you proceed. Alternatively, open the Web Connector from inside QuickBooks Desktop by going to File > App Management > Update Web Services.

<Warning>
  ⚠️ Install the QuickBooks Web Connector on one computer only for each company file. Installing it on multiple computers for the same company file causes a Conflict of Access, which results in Record Locked errors and duplicate transactions. For hosted or cloud environments (such as Rightworks or Ace Cloud), upload both the company file and the .qwc file to the remote environment in the same folder.
</Warning>

<Note>
  <img alt="QuickBooks Web Connector application window." />

  *QuickBooks Web Connector application window.*
</Note>

1. Add the configuration file to the Web Connector.
2. In the QuickBooks Web Connector, click Add an Application.
3. Browse to the .qwc file you downloaded earlier and open it.
4. QuickBooks Desktop will prompt you to authorize the connection. When the Application Certificate window appears, select **"Yes, always; allow access even if QuickBooks is not running"** and click Continue, then Done. Selecting this option allows transactions to sync automatically without requiring QuickBooks Desktop to be manually open each time. If QuickBooks Desktop is closed, transactions queue in Alvys for up to 7 days; after that they must be re-triggered from Alvys.
5. The Web Connector will prompt you for a password. Enter the password shown in the Alvys integration dialog.

<Note>
  <img alt="QuickBooks Web Connector Add an Application dialog." />

  * QuickBooks Web Connector Add an Application dialog.\*
</Note>

<Note>
  <img alt="QuickBooks Desktop authorization dialog for third-party application access." />

  *QuickBooks Desktop authorization dialog for third-party application access.*
</Note>

<Note>
  <img alt="QuickBooks Web Connector password entry prompt." />

  *QuickBooks Web Connector password entry prompt.*
</Note>

1. Check the box next to the Alvys application entry in the Web Connector.
2. Set the sync interval and run the first sync.
3. In the QuickBooks Web Connector, set the auto-run interval for the Alvys entry. A 5-minute interval is recommended to keep QuickBooks Desktop and Alvys in sync without overloading the connection.
4. Click Update Selected to run the first sync and confirm the connection is working.

   <img alt="QuickBooks Web Connector with auto-run interval field and Update Selected button." />

   * QuickBooks Web Connector with auto-run interval field and Update Selected button. \*
5. Return to Alvys and verify the connection. Return to the Alvys integration dialog. After the Web Connector sync completes, Alvys will display confirmation that QuickBooks Desktop is connected. Click Next to proceed to Configuration Settings.

   To confirm the connection inside QuickBooks Desktop, go to Edit > Preferences > Integrated Applications > Company Preferences and verify the Alvys integration is listed with its access checkbox selected. To find the QuickBooks company file path (required in Alvys Account Settings), press F2 or Fn+F2 inside QuickBooks Desktop to open the Product Information window; copy the path shown in the File Information section and paste it into Account Settings in Alvys. Then select the Auto Sync Checkbox and select the subsidiary before saving.
6. Configure the Edit Sequence setting before enabling other settings. Before enabling any other configuration settings, review whether Edit Sequence is appropriate for your environment. Edit Sequence controls how Alvys handles QuickBooks Desktop's transaction locking mechanism. Enabling or disabling Edit Sequence after transactions have already been synced can cause sync errors on existing transactions. Set this value before transactions are exported.
7. Save your configuration. After reviewing and setting your configuration options, click Save. The integration becomes active for the selected subsidiary on the next sync cycle.

<Note>
  <img alt="Alvys QuickBooks Desktop configuration settings panel" />

  *Alvys QuickBooks Desktop configuration settings panel*
</Note>

## Recommended Settings

The following settings are recommended for most QuickBooks Desktop integrations to reduce manual work and improve export reliability:

* Enable Ignore Driver Bills if your drivers are paid through a payroll system outside QuickBooks Desktop. This prevents duplicate payroll entries and keeps QuickBooks Desktop focused on carrier and customer transactions.
* Enable Ignore Zero Valued Transactions to prevent $0 transactions from being sent to QuickBooks Desktop. This avoids digit expectation errors if a $0 transaction is later updated and re-exported.
* Enable Generate Carrier Invoice Separately if your workflow requires physical carrier invoices to be reviewed and confirmed in Alvys before the carrier bill is exported to QuickBooks Desktop.
* Review Edit Sequence before enabling any other settings and before the first sync. Changing this setting after transactions have been exported can produce sync errors on existing records.

The following recommendations are organized by operational type to help you choose the right combination of settings for your business.

**Carrier operations:** Enable Revenue and Expense transaction types. Enable Single Bill for Driver Statement to consolidate all line items on a driver's statement into a single bill, which prevents clutter in QuickBooks Desktop and simplifies reconciliation. Enable Export Company Fuel Expense and Export Company Toll Expense if your operation deducts fuel and toll costs from driver pay.

**Broker operations:** Enable Revenue and Expense transaction types. Enable Generate Carrier Invoice Separately to prevent the carrier bill from exporting until the physical carrier invoice has been received and verified in Alvys. This ensures the bill in QuickBooks Desktop matches the confirmed carrier invoice amount.

## Configuration Settings

Configure these settings after the connection is established. Settings that interact with or conflict with each other are described in the Configuration Dependencies and Incompatible Settings section below.

*\[Heading 4 not supported]*

Select the transaction types to export. Revenue exports customer invoices. Expense exports carrier bills and driver settlements. Your selection here takes precedence over all other configuration settings; if a transaction type is not selected, its associated settings have no effect.

<Note>
  <img alt="Transaction Types Revenue/Expense checkboxes in QuickBooks Desktop settings." />

  *Transaction Types Revenue/Expense checkboxes in QuickBooks Desktop settings.*
</Note>

*\[Heading 4 not supported]*

When enabled, driver bills are excluded from export to QuickBooks Desktop.

*\[Heading 4 not supported]*

When enabled, all line items on a driver's statement are consolidated into a single bill for export, rather than exporting each individual trip bill.

*\[Heading 4 not supported]*

When enabled, a carrier bill is not exported to QuickBooks Desktop until the physical carrier invoice has been received and verified in Alvys.

*\[Heading 4 not supported]*

When enabled, driver payments are separated by tax type when exported. Requires Single Bill for Driver Statement to also be enabled.

*\[Heading 4 not supported]*

When enabled, billing responsibility shifts to a subsidiary carrier rather than the individual driver. This setting is incompatible with Single Bill for Driver Statement and other driver-based billing settings.

*\[Heading 4 not supported]*

When enabled, transactions with a \$0 value are excluded from export.

*\[Heading 4 not supported]*

When enabled, Alvys creates new vendors in QuickBooks Desktop using the driver's 1099 tax company information rather than the driver's individual profile. Requires Single Bill for Driver Statement to also be enabled.

*\[Heading 4 not supported]*

When enabled, carrier statements are exported as a batch rather than as individual carrier bills.

*\[Heading 4 not supported]*

When enabled, fuel costs deducted from driver pay are also exported as company overhead expense entries.

*\[Heading 4 not supported]*

When enabled, toll costs deducted from driver pay are also exported as company overhead expense entries. If a driver was not previously configured for company fuel or toll expense export and this setting is later enabled, past transactions will not be exported automatically.

*\[Heading 4 not supported]*

Enter a prefix to be added to all transaction reference numbers exported to QuickBooks Desktop.

*\[Heading 4 not supported]*

Controls how Alvys handles QuickBooks Desktop's transaction edit sequence locking. Enable this setting only if your QuickBooks Desktop environment uses edit sequence locking and you want Alvys to respect it when updating existing transactions. Set this value before the first sync; changing it after transactions have been exported can cause sync errors on existing records.

*\[Heading 4 not supported]*

When enabled, Alvys maps each subsidiary to a Class in QuickBooks Desktop for per-entity profit and loss reporting. Before enabling this setting, turn on Class Tracking in QuickBooks Desktop (Edit > Preferences > Accounting > Company Preferences > Use class tracking for transactions). Then create a Class in QuickBooks Desktop for each subsidiary (Lists > Class List > New). In Alvys, select the Subsidiaries checkbox and map each subsidiary to its corresponding Class. Subsidiaries and Fleets are mutually exclusive: enabling one prevents the use of the other.

*\[Heading 4 not supported]*

When enabled, Alvys maps each fleet to a Class in QuickBooks Desktop for per-fleet profitability tracking. Before enabling this setting, turn on Class Tracking in QuickBooks Desktop (Edit > Preferences > Accounting > Company Preferences > Use class tracking for transactions). Then create a Class in QuickBooks Desktop for each fleet (Lists > Class List > New). In Alvys, select the Fleets checkbox and map each fleet to its corresponding Class. Fleets and Subsidiaries are mutually exclusive: you must choose one or the other.

*\[Heading 4 not supported]*

When enabled, supports intercompany billing scenarios where a load is invoiced by one subsidiary and tendered by another, and both subsidiaries have separate QuickBooks Desktop accounting integrations. Shared Billing must be enabled on both subsidiaries involved in the intercompany transaction. Without it, the intercompany transactions will not export correctly.

## Configuration Dependencies and Incompatible Settings

Some settings must be used together, while others must not be enabled at the same time. Review these rules before saving your configuration.

**Revenue only:** If only the Revenue transaction type is selected, do not enable any of the following: Single Bill for Driver Statement, Generate Carrier Invoice Separately, Process Statement by Tax Category, Pay Subsidiary Carrier, Create Vendor Using 1099 Tax Company, Ignore Driver Bills, Carrier Statements, Export Company Fuel Expense, or Export Company Toll Expense. These settings depend on expense or driver bill data and have no effect without the Expense transaction type.

**Single Bill for Driver Statement:** Do not enable with Ignore Driver Bills or Pay Subsidiary Carrier. Single Bill assumes driver bills are being created and exported; Ignore Driver Bills removes them, and Pay Subsidiary Carrier redirects billing away from the driver entirely.

**Process Statement by Tax Category:** Requires Single Bill for Driver Statement to be enabled. Do not enable with Ignore Driver Bills or Pay Subsidiary Carrier. This setting depends on driver bill data separated by tax type; if driver bills are excluded or billing is redirected to a subsidiary carrier, tax-based filtering cannot function.

**Pay Subsidiary Carrier:** Do not enable with Single Bill for Driver Statement, Process Statement by Tax Category, Create Vendor Using 1099 Tax Company, or Ignore Driver Bills. When billing shifts to a subsidiary carrier, any configuration assuming driver-based billing or driver vendor creation becomes invalid.

**Ignore Driver Bills:** Do not enable with Single Bill for Driver Statement, Process Statement by Tax Category, or Create Vendor Using 1099 Tax Company. Each of these settings depends on driver bills being generated and exported; ignoring driver bills removes the underlying data they require.

**Create Vendor Using 1099 Tax Company:** Requires Single Bill for Driver Statement to be enabled. Do not enable with Pay Subsidiary Carrier or Ignore Driver Bills.

**Edit Sequence:** Set before any transactions are synced. Changing this value after the first sync can cause update errors on previously exported transactions.

## Result

After saving your configuration and confirming the QuickBooks Web Connector is running on a schedule, the integration is active. Alvys will export transactions to QuickBooks Desktop on each Web Connector sync cycle and import payment updates back into Alvys.

## FAQs

**Q: Do I need to keep QuickBooks Desktop open for the integration to work?**

**A:** Yes. The QuickBooks Web Connector requires QuickBooks Desktop to be open and running to sync. If QuickBooks Desktop is closed, the Web Connector will not be able to send or receive data until it is reopened.

**Q: What happens if the QuickBooks Web Connector is not running?**

**A:** Transactions will not be exported or imported until the Web Connector runs again. When it resumes, it will process the pending transactions that accumulated while it was stopped.

**Q: Can I configure the integration for multiple subsidiaries simultaneously?**

**A:** No. The integration must be configured one subsidiary at a time. Return to Management > Integrations and repeat the connection steps for each additional subsidiary.

**Q: What does "Ignore Driver Bills" do?**

**A:** It excludes driver-level bills from export entirely. Use this when drivers are paid through a payroll system outside QuickBooks Desktop.

**Q: Can I enable "Single Bill for Driver Statement" with "Pay Subsidiary Carrier"?**

**A:** No. These settings are incompatible. Single Bill consolidates driver-level billing, while Pay Subsidiary Carrier redirects billing away from drivers entirely.

**Q: Why am I receiving a digit expectation error when exporting a previously \$0 transaction?**

**A:** This error can occur when a transaction that previously had a $0 value is updated and re-exported. Enabling Ignore Zero Valued Transactions prevents $0 transactions from being sent in the first place, which avoids this error on subsequent updates. If the error persists after enabling this setting, contact Alvys support.

**Q: Can I enable both "Ignore Driver Bills" and "Single Bill for Driver Statement"?**

**A:** No. These settings are incompatible. Single Bill depends on driver bills being exported; Ignore Driver Bills removes them before export.

**Q: When do fuel and toll expenses sync to QuickBooks Desktop?**

**A:** Fuel and toll expenses sync when the associated load transaction is exported. If Export Company Fuel Expense or Export Company Toll Expense was not enabled when past transactions were processed, those past transactions will not be retroactively exported after the setting is turned on.

**Q: What happens if I change the Edit Sequence setting after transactions have already been synced?**

**A:** Changing Edit Sequence after the first sync can cause errors on existing records in QuickBooks Desktop, because the edit sequence values Alvys stored for those transactions will no longer match what QuickBooks Desktop expects. Set Edit Sequence before the first sync and do not change it afterward unless directed by Alvys support.

**Q: What happens if a vendor match is not found in QuickBooks Desktop during export?**

**A:** If no matching vendor is found by name or External Accounting ID, Alvys automatically creates a new vendor in QuickBooks Desktop using the carrier or driver's profile information.

**Q: Why does a carrier bill not export even though the load invoice was generated?**

**A:** If Generate Carrier Invoice Separately is enabled, the carrier bill will not export until the physical carrier invoice has been received and verified in Alvys. Confirm that the carrier invoice has been marked as received on the load. If the invoice is marked received and the bill still has not exported, contact Alvys support.

**Q: How do I know the integration is working after setup?**

**A:** After running the first sync in the QuickBooks Web Connector, return to the Alvys integration dialog. Alvys will display a confirmation that QuickBooks Desktop is connected. You can also verify by creating a test transaction in Alvys and checking whether it appears in QuickBooks Desktop after the next Web Connector sync cycle.

**Q: What if the "Authorize New Web Service" popup does not appear after I select the .qwc file?**

**A:** Check the Windows taskbar: the authorization prompt sometimes appears minimized. Also confirm you are logged in to QuickBooks Desktop as an Administrator and that you are in Single User Mode. The authorization prompt will not appear in Multi-User Mode.

**Q: Can I install the QuickBooks Web Connector on multiple computers?**

**A:** No. Installing the Web Connector on more than one computer for the same company file causes a Conflict of Access, which results in Record Locked errors and duplicate transactions. Install and run the Web Connector on one computer only.

**Q: Why should I select "Yes, always; allow access even if QuickBooks is not running"?**

**A:** Selecting this option allows the Web Connector to sync in the background without requiring QuickBooks Desktop to be manually open each time. If QuickBooks Desktop is closed, transactions queue in Alvys for up to 7 days before they must be re-triggered manually from Alvys.

**Q: Can I export only revenue transactions, or only expense transactions?**

**A:** Yes. In Configuration Settings, select only the Revenue checkbox to export customer invoices only. Select only the Expense checkbox to export carrier bills and driver settlements only. Your selection controls which transaction types are sent to QuickBooks Desktop.

**Q: Can I map transactions by both Subsidiary and Fleet at the same time?**

**A:** No. The Subsidiaries and Fleets settings are mutually exclusive. You can map by subsidiary or by fleet, but not both simultaneously.

**Q: Can I use QuickBooks Desktop Classes for tracking transactions by entity or fleet?**

**A:** Yes. Enable Class Tracking in QuickBooks Desktop (Edit > Preferences > Accounting > Company Preferences) and create a Class for each subsidiary or fleet. Then in Alvys, enable the Subsidiaries or Fleets setting and map each entry to its corresponding Class.

**Q: Where do I find the QuickBooks company file path to enter in Alvys?**

**A:** Press F2 (or Fn+F2) inside QuickBooks Desktop to open the Product Information window. The full file path to the .QBW company file appears in the File Information section. Copy this path and paste it into Account Settings in Alvys.

## Go Deeper

* [QuickBooks Desktop Account Mappings](/en/help/integrations/how-to-set-up-quickbooks-desktop-account-mappings-in-alvys)


# Sage Intacct: Connect & configure
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings

Connect a Sage Intacct entity to an Alvys subsidiary, then configure AR and AP sync, payment terms, and carrier export settings for two-way accounting.

<Note>
  This article walks through connecting (linking and authenticating) a Sage Intacct entity to an Alvys subsidiary and configuring AR and AP sync and export settings, payment terms, and carrier export behavior. Complete the Sage preparation steps before starting this wizard.
</Note>

## Overview

The Sage Intacct (also called Intacct) connection wizard links one Alvys subsidiary to one Sage Intacct entity. After connecting, AR invoices export, sync, and post from Alvys to Sage and payments import from Sage to Alvys on a 12-hour schedule. You configure which transaction types sync using the AR Settings and AP Settings tabs. Each Alvys subsidiary you want to connect requires its own separate connection.

## Before You Start

* Sage Intacct preparation must be complete: Web Services must be enabled in your Sage subscription, AlvysMPP must be authorized under Company > Web Services Authorizations, and a Web Services user must be created with "All" permissions on all 10 required modules. See [How to Prepare Sage Intacct Before Connecting to Alvys](/en/help/integrations/how-to-prepare-sage-intacct-before-connecting-to-alvys) before proceeding.
* Have your Sage Company ID, Web Services User ID, and password ready before starting the wizard.
* Only users with the **"Admin"** or **"Partner Admin"** role can access Settings > Connections > Sage Intacct (the **"CompanyProfileManager"** permission controls access).

## Steps

1. Select your Alvys subsidiary. Go to Settings > Connections > Sage Intacct. Click Connect. From the dropdown, select the Alvys subsidiary you want to connect to Sage Intacct. Each subsidiary must be connected separately; repeat this process for each subsidiary you want to link.
2. Choose where transactions will post in Sage. Select how Alvys transactions will be routed in your Sage entity structure:

   * **Matching child entities (Recommended):** Transactions post to the Sage entity whose name matches the Alvys subsidiary. Use this option if your Sage structure has separate child entities for each subsidiary.
   * **Top-level entity:** All transactions post to the top-level Sage entity, regardless of which Alvys subsidiary generated them.

     **Important:** This selection is permanent and cannot be changed after setup. If you need to change the posting destination later, you must disconnect the subsidiary and reconnect with the correct setting. If you are unsure which option applies to your Sage structure, consult your Sage administrator before proceeding.
3. Enter your Sage credentials. Enter the Sage Intacct Company ID, the Web Services User ID, and the password for that user. Alvys uses these credentials to authenticate with the Sage Web Services API. Click Connect to validate the credentials and proceed.
4. Configure AR Settings. Under the AR Settings tab, configure which accounts receivable transactions export to Sage:

   * **Export AR Invoices:** Master toggle. This must be enabled for any AR transactions to export. Disabling this toggle stops all AR exports for this subsidiary, regardless of individual toggle settings.
   * **Include driver bills in AR:** Includes driver-related charges on AR invoices exported to Sage.
   * **Export Carrier Statements:** Exports carrier statement transactions as AR invoices in Sage.
   * **Export E-check Transactions:** Exports e-check payments as AR transactions in Sage.
   * **Export deductions as credits on AR invoice:** Exports deductions as credit line items on the AR invoice rather than as separate transactions.
5. Configure AP Settings. Under the AP Settings tab, configure which accounts payable transactions export to Sage:

   * **Export AP Bills:** Master toggle. This must be enabled for any AP transactions to export. Disabling this toggle stops all AP exports for this subsidiary, regardless of individual toggle settings.
   * **Export driver settlements:** Exports driver settlement statements as AP bills in Sage.
   * **Export carrier settlements:** Exports carrier settlement statements as AP bills in Sage.
   * **Export E-check Transactions:** Exports e-check payments as AP transactions in Sage.
   * **Include fuel transactions:** Includes fuel card charges as line items on AP bills.
   * **Include toll transactions:** Includes toll charges as line items on AP bills.
   * **Include accessorial expenses:** Includes accessorial charges as line items on AP bills.
   * **Export Carrier Statements:** Exports carrier statement transactions as AP bills in Sage. This is a separate toggle from the AR Settings "Export Carrier Statements" toggle; each controls a distinct transaction flow.
   * **Send carrier invoice upon upload:** When enabled, Alvys exports a carrier AP bill to Sage immediately when a carrier invoice document is uploaded in Alvys, rather than waiting for the next scheduled sync cycle.

     **Important:** You cannot disable the last remaining active sync toggle on a subsidiary. If only one sync toggle is still enabled and you attempt to turn it off, Alvys will prevent the change. To pause all syncing without disconnecting, use the Primary Sync toggle for that subsidiary, which acts as a master on/off switch for the entire connection.
6. Configure Advanced Settings. Under the Advanced Settings tab, configure payment terms:

   * **Default Payment Terms:** Sets the fallback payment terms applied when no specific terms are defined for a given customer or carrier. This controls the due date and terms that appear on exported AR invoices and AP bills in Sage.
   * **Custom Payment Terms:** Define payment terms for specific customers or carriers to override the default. Custom terms apply to matching customers or carriers only.
   * **Cross Subsidiary Billing:** If your Sage environment uses cross-subsidiary billing, enable this setting when a load is invoiced by one subsidiary and tendered by another. The Invoice As subsidiary creates a customer invoice and an intercompany bill to the Tender As subsidiary. The Tender As subsidiary creates an intercompany invoice back to the Invoice As subsidiary and a vendor bill to the carrier or driver. Cross Subsidiary Billing must be enabled on both participating subsidiaries for intercompany transactions and carrier bills to export correctly.
   * **Dimension Mappings:** Map Sage Intacct dimensions (such as Location, Department, and Class) to Alvys fields (such as Subsidiary, Fleet, Office, Driver, Truck, Trailer, or Contractor Type). Dimensions are categorization tags in Sage that let you slice financial data by business segment. For full details, see Sage Intacct: Dimensions and Custom Fields.
   * **Custom Field Mappings:** Map Sage custom fields to Alvys data fields. Custom fields let you push additional Alvys data (such as load details, shipper and consignee information, dispatch data, driver names, and equipment numbers) into custom fields on Sage invoices and bills. For full details, see Sage Intacct: Dimensions and Custom Fields.
7. Save and verify the connection. Click Save. Before the connection becomes active, Alvys runs a reconciliation check to validate your configuration against Sage Intacct. If errors are found, Alvys displays a list of the issues along with links to the wizard step where each error can be resolved. Common errors include: a mapped GL account does not exist in Sage, a dimension value references a value removed from Sage, or required fields are missing. Correct each flagged item and click Save again. If the reconciliation succeeds, the connection status for that subsidiary will display as **Active** in Settings > Connections > Sage Intacct. The first sync will run on the next scheduled 12-hour cycle. To confirm transactions are exporting and to review any errors, see [Sage Intacct: Payments and Error Transactions](/en/help/integrations/sage-intacct-payments-and-error-transactions).

## Result

Your Alvys subsidiary is now connected to Sage Intacct. AR invoices and AP bills will export from Alvys to Sage according to your configured settings. Payments recorded in Sage will import back into Alvys on a 12-hour schedule. Each subsidiary you connect maintains its own independent AR, AP, and Advanced settings.

## Modifying Settings After Setup

To change AR, AP, or Advanced settings after the initial connection:

1. Go to Settings > Connections > Sage Intacct.
2. Find the subsidiary whose settings you want to change.
3. Click Edit to open that subsidiary's settings.
4. Select the AR Settings, AP Settings, or Advanced tab and make your changes.
5. Click Save.

The posting destination chosen during the connection wizard cannot be modified after setup. To change it, disconnect the subsidiary and reconnect.

## Setting Up Additional Subsidiaries Using a Template

After completing your first Sage Intacct integration, you can set up additional subsidiaries using an existing integration as a template. Using a template copies all AP settings, AR settings, account mappings, dimension mappings, and custom field mappings from the existing integration to the new subsidiary.

### How to use a template

1. Go to **Settings > Connections > Sage Intacct**.
2. Click the button to add a new integration.
3. From the dropdown, select the Alvys subsidiary you want to connect.
4. Choose where transactions will post in Sage.
5. Enter your Sage credentials and click **Connect**.
6. When prompted to choose a setup method, select "from an existing integration."
7. Select the existing integration you want to use as a template.
8. Select the Sage entity for the new subsidiary.
9. Review the copied settings and make any changes specific to the new subsidiary.
10. Turn on syncing to activate the connection.

After creating an integration from a template, changes made to the template integration do not automatically update integrations that were created from it. Each integration must be maintained independently.

## Disconnecting Sage Intacct

To disconnect a subsidiary from Sage Intacct:

1. Go to Settings > Connections > Sage Intacct.
2. Find the subsidiary you want to disconnect.
3. Click Disconnect.
4. Confirm the disconnection when prompted.

Disconnecting stops all future syncs for that subsidiary. It does not delete any previously exported transaction data in Sage Intacct.

## FAQs

**Q: Can I connect more than one Alvys subsidiary to Sage Intacct?**

**A:** Yes. Each subsidiary connects separately through the wizard. Repeat the connection steps for each subsidiary you want to connect.

**Q: Can multiple Alvys subsidiaries connect to the same Sage entity?**

**A:** Yes. Multiple subsidiaries can connect to the same Sage entity. Each subsidiary's transactions will post according to the posting destination setting configured during its individual setup.

**Q: What is the difference between the "Matching child entities" and "Top-level entity" posting options?**

**A:** Matching child entities routes each subsidiary's transactions to the Sage child entity whose name matches that Alvys subsidiary. Top-level entity posts all transactions to the parent Sage company regardless of which subsidiary generated them. Consult your Sage administrator to determine which option matches your Sage structure.

**Q: Can I change the posting destination after setup?**

**A:** No. The posting destination is permanent once the connection is saved. To change it, disconnect the subsidiary from Settings > Connections > Sage Intacct and reconnect with the correct setting.

**Q: What happens if I disable the Export AR Invoices or Export AP Bills toggle?**

**A:** Disabling either master toggle stops all AR or AP exports for that subsidiary. Individual transaction toggles (such as driver settlements or e-checks) will not export even if their individual toggles remain enabled.

**Q: Which Alvys roles can access the Sage Intacct connection settings?**

**A:** Users with the **"Admin"** or **"Partner Admin"** role can access Settings > Connections > Sage Intacct to connect, edit, or disconnect integrations.

**Q: What does "Send carrier invoice upon upload" do?**

**A:** When this toggle is enabled, Alvys exports a carrier AP bill to Sage immediately when a carrier invoice document is uploaded in Alvys, rather than waiting for the next scheduled 12-hour sync cycle.

**Q: How do I pause syncing temporarily without disconnecting?**

**A:** Use the Primary Sync toggle for the subsidiary. This acts as a master on/off switch for the entire connection. You cannot disable the last active individual sync toggle; if you attempt to do so, Alvys will prevent the change and you will need to use the Primary Sync toggle instead.

**Q: What credentials do I need to enter in the connection wizard?**

**A:** You need the Sage Intacct Company ID, the User ID of the Web Services user created for Alvys, and that user's password. Gather these from Sage before starting the wizard.

**Q: What should I do if the connection wizard returns an authentication error?**

**A:** Verify that the Sage Web Services user credentials are correct, that Web Services is enabled in your Sage subscription, and that AlvysMPP is listed in Company > Web Services Authorizations in Sage. See [How to Prepare Sage Intacct Before Connecting to Alvys](/en/help/integrations/how-to-prepare-sage-intacct-before-connecting-to-alvys) for the full prerequisites checklist.

**Q: Does disconnecting Sage Intacct delete my historical data?**

**A:** No. Disconnecting stops future syncs but leaves all previously exported transactions intact in Sage Intacct.

**Q: Can I configure different AR and AP settings for different subsidiaries?**

**A:** Yes. Each subsidiary has its own AR Settings, AP Settings, and Advanced Settings. Changes to one subsidiary's settings do not affect any other subsidiary.

**Q: What are Custom Payment Terms used for?**

**A:** Custom Payment Terms let you define payment terms for specific customers or carriers, overriding the Default Payment Terms for those parties. This controls the due date and terms that appear on exported AR invoices and AP bills in Sage.

**Q: If I enable "Export Carrier Statements" in both AR Settings and AP Settings, will carrier statements export twice?**

**A:** No. The AR and AP "Export Carrier Statements" toggles control separate transaction flows. The AR toggle exports carrier revenue invoices; the AP toggle exports carrier cost bills. Each controls a distinct set of transactions.

**Q: What happens to transactions that were created before the connection was established?**

**A:** Only transactions created or modified after the connection is established will export to Sage. Historical data from before the connection date is not exported automatically. If you need to bring historical data into Sage, that must be done manually within Sage Intacct.

**Q: What does it mean if the reconciliation check flags a GL account error after saving?**

**A:** It means that a GL account you mapped in Alvys does not exist or is inactive in your Sage Intacct Chart of Accounts. Return to the account mappings step in the wizard, correct the flagged mapping, and click Save again.

## Go Deeper

* [How to Prepare Sage Intacct Before Connecting to Alvys](/en/help/integrations/how-to-prepare-sage-intacct-before-connecting-to-alvys)
* [Sage Intacct: Account Mappings](/en/help/integrations/sage-intacct-account-mappings)
* [Sage Intacct: Payments and Error Transactions](/en/help/integrations/sage-intacct-payments-and-error-transactions)


# Connect Teletrac Navman to Alvys
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-teletrac-navman-to-alvys

Connect Teletrac Navman ELD to Alvys with API credentials to pull live truck locations and driver Hours of Service clocks into the dispatch workflow.

<Note>
  Connect your Teletrac Navman ELD account to Alvys to pull truck locations and driver hours of service (HOS) clocks into Alvys automatically.
</Note>

## Overview

The Teletrac Navman integration connects your Teletrac Navman ELD account to Alvys so that truck location and driver HOS data flow into Alvys automatically. Teletrac Navman is an ELD and telematics provider (also referred to as a GPS tracking or fleet tracking provider). Once connected and mapped, dispatchers can view live truck positions and driver remaining drive time directly in Alvys without switching between systems.

## Prerequisites

Before connecting:

* You have an active Teletrac Navman account with API access enabled. To request API access, contact Teletrac Navman at [us.enterprisesupport@teletracnavman.com](mailto:us.enterprisesupport@teletracnavman.com) and mention that you are an Alvys customer and that Alvys is a Teletrac Navman integration partner. Teletrac Navman will provide your API username and password.
* You have the vehicle name for each truck you want to track, exactly as it appears in Teletrac Navman.
* You have the full name (first name and last name) for each driver you want to track, exactly as it appears in Teletrac Navman.
* Your role in Alvys is **"Admin"**, **"Partner Admin"**, or **"Support"**. These roles can access **Company Profile > Integrations**.

## How to connect

1. Go to **Management > Company Profile > Integrations** tab in Alvys.
2. Locate the Teletrac Navman integration, enter your Username and Password in the fields provided, and click **Save**.

   <img alt="Integrations tab in Alvys showing the Teletrac Navman section with the Username and Password fields and the Save button" />

   *Integrations tab in Alvys showing the Teletrac Navman section with the Username and Password fields and the Save button*

Alvys confirms the connection once your credentials are accepted. If the connection fails, verify your username and password with Teletrac Navman and confirm that API access has been enabled on your account.

### Map each truck and driver

After connecting, map each truck and driver in Alvys to the corresponding record in Teletrac Navman. Each asset must be mapped individually; there is no bulk mapping option.

**Mapping trucks**

* Go to **Management > Fleets > Trucks** and open the truck record you want to map.
* In the ELD Integration section, select **Teletrac Navman** from the provider dropdown.

  <img alt="Truck record in Alvys showing the ELD Integration section with Teletrac Navman selected and the Integration ID field" />

  *Truck record in Alvys showing the ELD Integration section with Teletrac Navman selected and the Integration ID field*

  <img alt="Truck record in Alvys showing the Integration ID field filled in with the vehicle name from Teletrac Navman" />

  *Truck record in Alvys showing the Integration ID field filled in with the vehicle name from Teletrac Navman*
* In the Integration ID field, enter the vehicle name exactly as it appears in Teletrac Navman, including capitalization and spacing.

  <img alt="Driver record in Alvys showing the ELD Integration section with the Add ELD button" />

  *Driver record in Alvys showing the ELD Integration section with the Add ELD button*
* Click **Save**.

Repeat for each truck you want to track.

To map a trailer for location tracking, follow the same process. Go to **Management > Fleets > Trailers** and open the trailer record. In the ELD Integration section, select **Teletrac Navman**, enter the trailer name exactly as it appears in Teletrac Navman in the Integration ID field, and click **Save**. Repeat for each trailer you want to track.

**Mapping drivers**

* Go to **Management > Drivers** and open the driver record you want to map.
* In the ELD Integration section, click **Add ELD**.

  <img alt="ELD provider selection panel that appears after clicking Add ELD, showing the provider dropdown" />

  *ELD provider selection panel that appears after clicking Add ELD, showing the provider dropdown*
* Select **Teletrac Navman** from the dropdown.
* In the Integration ID field, enter the driver's full name exactly as it appears in Teletrac Navman: first name, then a space, then last name.
* Click **Save**.

Repeat for each driver you want to track.

## What syncs

Once trucks and drivers are mapped, Alvys pulls data from Teletrac Navman automatically. The following data syncs from Teletrac Navman to Alvys:

* Truck GPS location
* Driver HOS clocks: break, cycle, drive, and shift remaining time

Data refreshes on Alvys's standard polling interval, not in real time.

### Verify it is working

1. Open a mapped truck in Alvys and confirm that a location is showing in the tracking view.
2. Open a mapped driver record and confirm that HOS clock values are displaying.

If data is not appearing within a few minutes of completing setup, see the Troubleshooting section below.

<Note>
  📋 **Limits / unsupported:** IFTA mileage reporting is not available through the Teletrac Navman integration in Alvys. · Each truck and driver must be mapped individually; there is no bulk mapping option.
</Note>

## Troubleshooting

### Truck location not showing in Alvys

1. Confirm the truck is powered on and has an active GPS signal in Teletrac Navman.
2. Verify the Integration ID in Alvys matches the vehicle name in Teletrac Navman exactly, including capitalization and spacing. Go to **Management > Fleets > Trucks**, open the truck record, and compare the Integration ID to the vehicle name shown in Teletrac Navman.
3. If neither of those conditions applies, contact Alvys support.

### Driver HOS not showing in Alvys

1. Confirm the driver has active HOS data in Teletrac Navman.
2. Verify the Integration ID in Alvys matches the driver's full name in Teletrac Navman exactly, using first name, a space, and last name. Go to **Management > Drivers**, open the driver record, and compare the Integration ID to the name shown in Teletrac Navman.
3. If neither of those conditions applies, contact Alvys support.

## FAQs

**Q: How do I get my Teletrac Navman API credentials?**

**A:** Contact Teletrac Navman at [us.enterprisesupport@teletracnavman.com](mailto:us.enterprisesupport@teletracnavman.com). Mention that you are an Alvys customer and that Alvys is a Teletrac Navman integration partner. Teletrac Navman will provide your username and password for API access.

**Q: What do I enter as the driver Integration ID?**

**A:** Enter the driver's full name exactly as it appears in Teletrac Navman: first name, then a space, then last name. Capitalization and spacing must match exactly.

**Q: What happens if I enter the wrong credentials?**

**A:** Alvys will not be able to connect to Teletrac Navman and the integration will not be active. Return to **Management > Company Profile > Integrations** tab, re-enter the correct username and password, and click **Save**.

**Q: Where do I find my Teletrac Navman asset and driver names?**

**A:** Log in to the Teletrac Navman Director portal. The vehicle and driver names listed there are the exact values to enter as Integration IDs in Alvys. Names are case-sensitive, so copy them exactly as they appear.


# Connect Thermo King to Alvys
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-thermo-king-to-alvys

Connect Thermo King reefer telematics to Alvys to sync trailer locations and temperature readings for tracking refrigerated freight in the Asset Map.

<Note>
  The Thermo King integration, also called Thermo King reefer tracking or trailer telematics, connects your Thermo King account to Alvys so that trailer location and temperature data sync automatically.
</Note>

## Overview

The Thermo King integration, also known as Thermo King reefer tracking or trailer telematics, connects your Thermo King account to Alvys so that trailer location and temperature data sync into Alvys automatically. The integration is one-way: Thermo King sends data to Alvys. Once connected and mapped, dispatchers can view trailer positions and temperature readings directly in Alvys without switching between systems.

## Prerequisites

Before connecting, confirm you have the following:

* An active Thermo King account with API access enabled
* Your External Customer ID, username, and password from Thermo King. If you do not have these credentials, contact Thermo King at [tracking@thermoking.com](mailto:tracking@thermoking.com)
* The trailer name for each trailer you want to track, exactly as it appears in Thermo King
* An **"Admin"**, **"Partner Admin"**, or **"Support"** role in Alvys

## How to connect

1. Go to **"Management > Company Profile > Integrations"** tab in Alvys.
2. Locate the Thermo King integration, enter your External Customer ID, Username, and Password in the fields provided, and click **"Save"**.

Alvys confirms the connection once your credentials are accepted. If the connection fails, verify your External Customer ID, username, and password with Thermo King.

<Note>
  <img alt="Integrations tab in Alvys showing the Thermo King section with the External Customer ID, Username, and Password fields." />

  *Integrations tab in Alvys showing the Thermo King section with the External Customer ID, Username, and Password fields.*
</Note>

### Map your trailers

After connecting, map each trailer in Alvys to the corresponding record in Thermo King. Each trailer must be mapped individually; there is no bulk mapping option.

1. Go to **"Management > Fleets > Trailers"** and open the trailer record you want to map.
2. In the ELD Integration section, select **"Thermo King"** from the provider dropdown.
3. In the Integration ID field, enter the trailer name exactly as it appears in Thermo King, including capitalization and spacing.
4. Click **"Save"**.

<Note>
  <img alt="Notion Image" />
</Note>

<Note>
  <img alt="Trailer record in Alvys showing the Integration ID field filled in with the trailer name from Thermo King" />

  *Trailer record in Alvys showing the Integration ID field filled in with the trailer name from Thermo King*
</Note>

Repeat for each trailer you want to track.

### Verify it's working

1. Open a mapped trailer in Alvys and confirm that a location is showing in the tracking view.
2. Confirm that temperature data is displaying on the trailer record.

If data is not appearing within a few minutes of completing setup, see the Troubleshooting section below.

## What syncs

Once trailers are mapped, Alvys pulls data from Thermo King automatically. The following data syncs from Thermo King to Alvys:

* Trailer GPS location
* Temperature readings for up to three zones: ambient, probe, supply air, and return air
* Setpoint temperatures
* Fuel percentage
* Power status

Data refreshes on Alvys's standard polling interval, not in real time.

<Note>
  📋 What is not available through Thermo King: truck location tracking · driver HOS data · IFTA mileage reporting. Each trailer must be mapped individually; there is no bulk mapping option.
</Note>

## Troubleshooting

### Trailer location or temperature not showing in Alvys

1. Confirm the trailer unit is powered on and has an active connection in Thermo King.
2. Verify the Integration ID in Alvys matches the trailer name in Thermo King exactly, including capitalization and spacing. Go to **"Management > Fleets > Trailers"**, open the trailer record, and compare the Integration ID to the trailer name shown in Thermo King.
3. If neither of those conditions applies, contact Alvys support.

## FAQs

**Q: Where do I find my Thermo King External Customer ID?**

**A:** Contact Thermo King at [tracking@thermoking.com](mailto:tracking@thermoking.com). They can provide your External Customer ID along with your API username and password.

**Q: Can I use this integration to track trucks or driver HOS?**

**A:** No. The Thermo King integration in Alvys supports trailer tracking only. Truck location tracking and driver HOS data are not available through this integration.

**Q: What temperature data does the integration bring into Alvys?**

**A:** The integration pulls ambient, probe, supply air, and return air temperatures for up to three zones, along with setpoint temperatures, fuel percentage, and power status.

**Q: What happens if I enter invalid credentials?**

**A:** As of February 2025, Alvys validates credentials before saving. An error appears immediately if your credentials are incorrect; the integration will not be saved until valid credentials are entered. Contact Thermo King at [tracking@thermoking.com](mailto:tracking@thermoking.com) if you need to verify your credentials.


# QuickBooks Online: Export & manage transactions
Source: https://docs.alvys.com/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online

How Alvys exports invoices and bills to QuickBooks Online, matches customers and vendors, handles manual pushes, and modifies transactions after export.

<Note>
  This article explains how Alvys routes load data to QuickBooks Online, how customers and vendors are matched or created automatically during export, how to manually export transactions, and the steps to modify or revert a transaction that has already been exported.
</Note>

### Overview

When a load is processed for billing in Alvys, the integration creates or updates invoices and bills in QuickBooks Online (QBO) based on the load's billing configuration. This article explains the full export workflow: how Alvys determines who to invoice or pay in QBO, how customers and vendors are matched (linked or auto-created), how to push transactions manually or review the export queue, and what to do when an exported transaction needs to be changed or reversed.

### Before You Start

Before exporting transactions:

* Confirm the QuickBooks Online integration is connected and account mappings are configured.
* Confirm loads are released to billing before attempting to export invoices.
* You need the **"CompanyProfileManager"** permission to access the Integrations export queue and re-export transactions. This permission is available to users with the Admin, Partner Admin, or Support role. Dispatchers and accounting staff who can access the Transactions tab on individual loads may also initiate exports from the load detail page.

#### Subsidiary Determination for Transaction Exports

When setting up the QBO integration, the user normally selects which subsidiary QBO accounts to connect. This section explains which connected QBO account will receive the exported invoices and/or bills.

#### Customer Invoices and Invoice As field

The Invoice As field represents the billing subsidiary responsible for issuing the customer invoice. This determines the legal entity name that appears on the invoice. All Accounts Receivable (AR) transactions are exported to the QBO subscription tied to this subsidiary.

Example: If a load’s Invoice As field is set to Alvys Brokerage, the invoice exports to the QuickBooks subscription linked to Alvys Brokerage.

<Note>
  <img alt="Features the customer load details page with a blue outline focusing on the Invoice Customer As configuration dropdown set to 'Alvys Inc'." />

  *Features the customer load details page with a blue outline focusing on the Invoice Customer As configuration dropdown set to "Alvys Inc".*
</Note>

#### Carrier Bills and Tender As field

The **Tender As** field identifies the subsidiary responsible for dispatching the load and paying the carrier. It also determines the **trip type**:

* If the selected subsidiary is a **broker**, the trip type is set to **Brokerage**.
* If the selected subsidiary is a **carrier**, the trip type is set to **Carrier**.

Carrier bills are exported to the QBO subscription linked to the subsidiary selected in the Tender As field.

<Note>
  <img alt="Shows carrier details with a blue box at the bottom highlighting that the load is being Tendered As Alvys Brokerage." />

  *Shows carrier details with a blue box at the bottom highlighting that the load is being Tendered As Alvys Brokerage.*
</Note>

#### Dual Authority Carriers

For carriers with **dual authority**, operational mode is automatically set based on the **Tender As** subsidiary. Users can manually update operational mode to Carrier or Broker, which may affect QBO exports.

<Note>
  <img alt="Displays a minimal status view of the Operational Mode field showing a blue badge marked as CARRIER." />

  *Displays a minimal status view of the **Operational Mode** field showing a blue badge marked as **CARRIER**.*

  <img alt="Shows the operational advanced settings module with the Operational Mode radio button set specifically to Carrier." />

  *Shows the operational advanced settings module with the Operational Mode radio button set specifically to Carrier.*
</Note>

#### Driver Bills and Driver Subsidiary Field

Each driver profile has a **Subsidiary field** representing the subsidiary the driver is tied to.

When generating driver statements, the QuickBooks subscription receiving the bill depends on the driver’s subsidiary.

<Note>
  <img alt="Shows a driver's employment summary card with a blue box emphasizing its assigned corporate Subsidiary as Alvys Inc." />

  *Shows a driver's employment summary card with a blue box emphasizing its assigned corporate Subsidiary as Alvys Inc.*
</Note>

**Example:**

Load invoiced as **Alvys Inc**, tendered as \*\*Alvys Brokerage \*\*Driver subsidiary assigned to \*\*Alvys Inc \*\*Driver bill exports to the **Alvys Inc** QuickBooks subscription

### Customer Linkage, Creation, and Accounting Fields used for QBO

This section describes how Alvys identifies and links customers and brokers in QuickBooks Online (QBO), how new customer records are created when no match is found, and how key accounting fields such as customer names, invoicing details, and payment terms affect invoice exports and data synchronization.

#### Customer External Accounting Name

The customer’s **External Accounting Name** is used to identify a customer or broker in QuickBooks Online (QBO). When exporting an invoice Alvys first searches for an **exact match** in QBO using this field.

<Note>
  <img alt="Displays customer invoicing info with a blue outline framing the configured External Accounting Name ('Alvys Acct')." />

  *Displays customer invoicing info with a blue outline framing the configured External Accounting Name ("Alvys Acct").*
</Note>

If a matching customer exists, the invoice is linked to that customer. If no match is found and the External Accounting Name is set on the customer profile, Alvys will automatically create a new customer in QBO using the External Accounting Name. For tenants where the External Accounting Name is **not set**, Alvys attempts to match using the **Customer Name**. If no match is found, a new customer is created in QBO using the Customer Name.

It is important to note that the External Accounting Name **takes priority**. If the External Accounting Name differs from an existing QBO customer name, even if the Customer Name in Alvys matches, Alvys will create a new customer using the External Accounting Name.

<Warning>
  ⚠️ QBO requires unique names across customers, vendors, and employees. If Alvys attempts to create a customer whose name already exists as a vendor or employee, the creation will fail.
</Warning>

#### Invoicing Name (Previously Called Billing Name)

The **Invoicing Name** determines how the customer or broker appears on invoices generated in Alvys. It **does not affect the customer record created in QBO**.

<Note>
  <img alt="Features customer profile parameters with a blue bounding box highlighting the designated Invoicing Name ('Alvys Inc')." />

  *Features customer profile parameters with a blue bounding box highlighting the designated Invoicing Name ("Alvys Inc").*
</Note>

When creating customers in QBO, Alvys uses the following fields from the customer or broker profile:

* **Invoicing address** (mapped to the billing address in QBO)
* **Customer email**
* **Customer phone**
* **Customer address** (used for the shipping address in QBO)

Alvys is the **source of truth** for these fields. If a customer is created in QBO by Alvys and a user later update the information directly in QBO, these changes will be **overridden** the next time an invoice is synced from Alvys. To ensure consistency, any updates to these fields should always be made within Alvys.

*\[Heading 4 not supported]*

The Payment Terms field specifies the agreed-upon period within which a customer must pay an invoice, calculated from the invoice date. In Alvys, this can be set to any value between 0 and 365 days.

<Note>
  <img alt="A minimal interface view displaying the customer's billing Payment Terms configured as Net 25" />

  *A minimal interface view displaying the customer's billing Payment Terms configured as Net 25*
</Note>

These terms determine the due date on the load as well as the invoice due date exported to QuickBooks Online

### Vendor Linkage, Creation, and Accounting Fields used for QBO

This section explains how Alvys links carriers and drivers to QuickBooks Online (QBO), how vendor records are created when no match is found, and which accounting fields control bill synchronization.

This section explains how Alvys links carriers and drivers to QuickBooks Online (QBO), how vendor records are created when no match is found, and which accounting fields control bill synchronization.

#### Carrier External Accounting Name

The carrier’s **External Accounting Name** is used to identify a vendor in QuickBooks Online (QBO). When exporting a bill, Alvys first searches for an **exact match** in QBO using this field.

<Note>
  <img alt="Features a carrier's general contact card with a blue box spotlighting the assigned External Accounting Name ('AL Ext Carrier')." />

  *Features a carrier's general contact card with a blue box spotlighting the assigned External Accounting Name ("AL Ext Carrier").*
</Note>

If a matching vendor exists, the bill is linked to that vendor. If no match is found and the External Accounting Name is set on the carrier profile, Alvys will automatically create a new vendor in QBO using the External Accounting Name. For carriers where the External Accounting Name is **not set**, Alvys attempts to match using the **Carrier Name**. If no match is found, a new vendor is created in QBO using that name.

It is important to note that the External Accounting Name **takes priority**. If it differs from an existing QBO vendor name, even if the Carrier or Driver Name in Alvys matches, Alvys will create a new vendor using the External Accounting Name.

#### Driver Name and 1099 Tax Details

Drivers, including company drivers and owner-operators, may operate as **1099 drivers**. These drivers have additional tax detail fields on their profiles, such as:

* **Tax Company Name**
* **Tax Company Address**

<Note>
  <img alt="Displays corporate Tax Information records with blue frames emphasizing the Tax Category (1099), Company Name (Alvys Company), and its Company Address." />

  *Displays corporate Tax Information records with blue frames emphasizing the Tax Category (1099), Company Name (Alvys Company), and its Company Address.*
</Note>

When generating driver statements, if these fields are set and the accounting integration is configured to create vendors using 1099 details, Alvys will create the vendor using the tax information (company name and address). If this setting is not enabled, the vendor will be created using the driver’s name.

#### Carrier Payment Terms

The **Carrier Payment Terms** field defines the agreed-upon time frame for paying a carrier. This is configured on the [company profile](https://app.alvys.com/#/manage/company-profile) for each subsidiary.

<Note>
  <img alt="Displays the Carrier Payment Terms data table detailing standard rules for Standard Pay (20 days, $20 flat fee) and Quick Pay." />

  *Displays the Carrier Payment Terms data table detailing standard rules for Standard Pay (20 days, \$20 flat fee) and Quick Pay.*
</Note>

If a driver is associated with a subsidiary that has this payment terms configured, the bill due date will be calculated based on that subsidiary’s terms.

For external carriers, the due date is determined using the Carrier Payment Terms from the company profile of the subsidiary specified in the Tender As field on the trip.

### Steps

#### Invoice Transaction Export Demonstration

This section provides an overview of the areas within Alvys from which customer invoices can be exported from and the key validations required to ensure successful export to QuickBooks Online.

#### Individual Load Invoice Export

Generating a customer invoice from the Load Details page triggers its export to QuickBooks Online. To ensure a successful export, all relevant configurations and data must be verified before the invoice is generated.

Ensure the customer being invoiced is correct. Verify that the External Accounting Name is set correctly for the customer. If no External Accounting Name is configured, ensure the standard customer or broker name exactly matches the customer record in QuickBooks Online.

<Note>
  <img alt="Shows a customer info layout with a blue box emphasizing the designated External Accounting Name ('Alvys Acct')." />

  *Shows a customer info layout with a blue box emphasizing the designated External Accounting Name ("Alvys Acct").*

  <img alt="Shows the customer info layout in QBO with a blue box emphasizing the designated External Accounting Name ('Alvys Acct')." />

  *Shows the customer info layout in QBO with a blue box emphasizing the designated External Accounting Name ("Alvys Acct").*
</Note>

Also verify the customer’s Invoice settings for the subsidiary which is used as the invoiced as subsidiary on the load. The Invoice As subsidiary used on the load must correspond to the subsidiary configured for the QuickBooks Online integration, as this determines which QuickBooks company receives the invoice.

<Note>
  <img alt="Features a customer profile with a blue box drawing attention to the Invoicing Settings action link." />

  *Features a customer profile with a blue box drawing attention to the **Invoicing Settings** action link.*

  <img alt="Shows the Invoicing Settings parameters modal with a blue border highlighting the chosen 'Alvys Inc' profile on the side panel" />

  *Shows the **Invoicing Settings** parameters modal with a blue border highlighting the chosen "Alvys Inc" profile on the side panel*
</Note>

Once these conditions are satisfied and the load is in Released status, generating the invoice automatically initiates the export to QuickBooks Online.

<Note>
  <img alt="Shows the load details page with a blue bounding box highlighting the main record header for Load — 1061613 Released." />

  *Shows the load details page with a blue bounding box highlighting the main record header for Load — 1061613 Released.*

  <img alt="Shows the money box with a blue outline framing the Generate Invoice execution button." />

  *Shows the money box with a blue outline framing the Generate Invoice execution button.*
</Note>

After the invoice is exported to QuickBooks Online, it can be located using the search field by entering the load number. If an invoice prefix is configured, the prefix should be included along with the load number. The invoice is also available in the Sales Invoices list, where users can browse all invoices and apply date filters to narrow the results. In both cases, the invoice appears under the corresponding customer

<Note>
  <img alt="Displays the QBO transaction search bar results looking up a specific document number to find its corresponding Invoice database row." />

  *Displays the QBO transaction search bar results looking up a specific document number to find its corresponding **Invoice** database row.*
</Note>

<Warning>
  ⚠️ If the invoice was not exported due to an error, the issue can be reviewed on the [Error Transactions page](https://app.alvys.com/#/accounting/error-help). Additional information about the Error Transactions page and how to interpret error details is provided in the [QuickBooks Online: Identifying and Resolving Failed Transactions Article](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)
</Warning>

#### Batch Invoice Export

The Batch Invoicing page in Alvys is located under accounting, then Invoice in the left navigation menu or directly at [https://app.alvys.com/#/accounting/invoicing](https://app.alvys.com/#/accounting/invoicing).

<Note>
  <img alt="Shows the main platform sidebar navigation column with a blue box highlighting the Invoice selection item." />

  *Shows the main platform sidebar navigation column with a blue box highlighting the **Invoice** selection item.*
</Note>

This page enables users to create invoices for multiple loads across one or more customers simultaneously. Each selected load is processed as an individual invoice, and exporting to QuickBooks Online is triggered automatically when the invoices are generated. This approach enables faster and more efficient invoicing while ensuring accurate transaction records for each load.

From the Released tab, select the loads for which you want to generate invoices. Ensure that the selected loads meet the following requirements. The customer being invoiced must be correct. If an External Accounting Name is configured, it must exactly match the corresponding customer record in QuickBooks Online. If no External Accounting Name is configured, the standard customer or broker name must match the customer record. The Invoice As subsidiary on each load must be properly configured to export revenue transactions to QuickBooks Online.

<Note>
  <img alt="Shows the 'Released' tab on the Invoicing page with an Invoice Summary panel that lists three selected customer accounts." />

  *Shows the "Released" tab on the Invoicing page with an **Invoice Summary** panel that lists three selected customer accounts.*
</Note>

After verifying these details, invoices can be generated using the **Generate Invoice** option, which creates the invoices and exports them to QuickBooks Online. Alternatively, the **Create and Send** option generates the invoices, exports them to QuickBooks Online, and sends them to the customer according to the invoicing method configured for that customer.

<Note>
  <img alt="Billing execution controls with a blue box highlighting the Generate Invoice button." />

  *Billing execution controls with a blue box highlighting the **Generate Invoice** button.*

  <img alt="Shows a status toast notification confirming that invoice processing completed and three invoices were generated." />

  *Shows a status toast notification confirming that **invoice processing completed** and three invoices were generated.*
</Note>

Once exported, the invoices are recorded in QuickBooks Online under the corresponding customer and can be located using the search field or within the Sales Invoices list.

<Note>
  <img alt="Displays a search bar dropdown tracking recent transactions for three newly created invoices dated 01/26/2026." />

  *Displays a search bar dropdown tracking recent transactions for three newly created invoices dated 01/26/2026.*
</Note>

<Warning>
  ⚠️ If the invoice was not exported due to an error, the issue can be reviewed on the [Error Transactions page](https://app.alvys.com/#/accounting/error-help). Additional information about the Error Transactions page and how to interpret error details is provided in the [QuickBooks Online: Identifying and Resolving Failed Transactions Article](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)
</Warning>

#### Summary invoice Export

Summary invoicing consolidates multiple loads for a customer into a single invoice. The Summary Invoicing page can be accessed from Accounting then Summary Invoicing. For more information on configuring customers for summary invoicing, see [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing).

The invoice export is triggered when the consolidated summary invoice is generated, creating a single invoice that reflects the total amount for all loads included. Only customers configured with the summary invoice type will appear when selecting a subsidiary. Ensure that the subsidiary is correct, as this determines the QuickBooks Online company where the invoice will be sent.

On the [Summary Invoicing page](https://app.alvys.com/#/accounting/summary-invoicing), from the Loads Not Invoiced tab, select the loads to include and add them to a draft summary invoice. Once the draft is prepared, generating the invoice will create the summary invoice and export it to QuickBooks Online.

<Note>
  <img alt="Features the Summary invoicing, Load Not Invoiced tab with a blue box highlighting the Add to Draft option for selected un-invoiced loads." />

  *Features the Summary invoicing, Load Not Invoiced tab with a blue box highlighting the **Add to Draft** option for selected un-invoiced loads.*

  <img alt="Shows the 'Draft Invoice' staging tab with a blue outline focusing on the Generate Invoice action button." />

  *Shows the "Draft Invoice" staging tab with a blue outline focusing on the **Generate Invoice** action button.*
</Note>

After the invoice is exported, it can be located in QuickBooks Online using the search field by entering the summary invoice number e.g. S1000048\*\*.\*\* The invoice is also available in the Sales Invoices list, where users can browse all invoices and apply date filters to narrow results.

<Note>
  <img alt="Displays the 'All Invoices' log tracking summary invoice S1000048 in a Pending status state." />

  *Displays the "All Invoices" log tracking summary invoice **S1000048** in a **Pending** status state.*

  <img alt="Image showing the QBO global transaction search bar in results with a blue box framing the record for summary invoice S1000048." />

  *Image showing the QBO global transaction search bar in results with a blue box framing the record for summary invoice **S1000048**.*
</Note>

<Warning>
  ⚠️ If the summary invoice is not exported due to an error, the issue can be reviewed on the Error Transactions page. However, summary invoices cannot be re-sent directly from the Error Transactions page. Any required modifications must be made on the Summary Invoicing page, and the invoice must be regenerated from there. Additional guidance on modifying summary invoices can be found in the section titled “Modifying Previously Exported Transactions”**.**
</Warning>

## Bill Transaction Export Demonstration

This section explains the different methods available in Alvys for exporting bill transactions to QuickBooks Online. It covers external carrier bills, carrier settlements, and driver bill exports, including the configuration requirements that determine when and how each bill is exported.

#### Individual Trip External Carrier Bill Export

External carrier bills can be exported directly from individual loads based on the configured external accounting settings. The export is triggered when the customer invoice is generated. Before generating the invoice, ensure the correct external carrier is assigned to the trip. The subsidiary selected in the **Tender As** field must also be verified, as this subsidiary determines where the carrier bill will be sent. The selected subsidiary must be configured to receive carrier bills through the QBO integration.

<Warning>
  ⚠️ For tenants operating in dual-authority mode, an additional validation is required. The operational mode must be set to **Brokerage**. If the operational mode is set to **Carrier**, the external carrier bill export will not occur.

  <img alt="Displays the advanced configuration card with the trip's Operational Mode radio toggle set to Brokerage." />

  *Displays the advanced configuration card with the trip's **Operational Mode** radio toggle set to **Brokerage**.*
</Warning>

When an external carrier is assigned and the trip is released to billing, the system evaluates the **Generate Carrier Invoice Separately** setting.

If this setting is not enabled, the carrier bill is exported automatically when the customer invoice is generated. However, if enabled, the system verifies whether a document of type **Carrier Invoice** has been uploaded to the trip. If the document is present, the carrier bill is exported to QuickBooks Online when the customer invoice is generated.

<Note>
  <img alt="Image showing the Documents management modal with blue boxes highlighting the Docs menu tab and the Carrier Invoice file type classification dropdown." />

  *Image showing the **Documents** management modal with blue boxes highlighting the **Docs** menu tab and the **Carrier Invoice** file type classification dropdown.*
</Note>

\*\*Carrier Invoice number \*\*

In Alvys, the carrier invoice number is entered when uploading a document of type Carrier Invoice to a trip. When the carrier bill is exported to QuickBooks Online, this number is automatically appended to the memo field. This allows accounting teams to easily search for, reference, and reconcile carrier bills using the carrier’s original invoice number.

<Note>
  <img alt="Shows carrier billing entries under a brokerage load with a blue frame highlighting the assigned Carrier Invoice Number ('AL202512')." />

  *Shows carrier billing entries under a brokerage load with a blue frame highlighting the assigned **Carrier Invoice Number** ("AL202512").*

  <img alt="Shows global search results looking up carrier invoice 'AL202512' to locate its corresponding bill transaction row in the lower panel." />

  *Shows global search results looking up carrier invoice "AL202512" to locate its corresponding bill transaction row in the lower panel.*

  <img alt="Displays a transaction Memo text box containing specific trip routing details alongside the underlined carrier invoice number." />

  *Displays a transaction **Memo** text box containing specific trip routing details alongside the underlined carrier invoice number.*
</Note>

### Carrier Settlements

The Carrier Settlements module provides brokers with tools to generate transparent and accurate carrier statements and settlement bills. This page can be accessed from the accounting section of Alvys under Carrier Settlements. Additional details about this feature can be found in the [Carrier Settlements Help Center Article](/en/help/accounting-settlements/carrier-settlements).

When carrier settlements are used, the carrier bill is exported when a carrier statement is generated. To allow this export, the **Carrier Statements External Accounting** setting must be enabled for the subsidiary. If this setting is not enabled, no carrier bill will be exported when the statement is generated.

<Note>
  <img alt="Shows the checked option box for enabling Carrier Statements within the configuration parameters." />

  *Shows the checked option box for enabling **Carrier Statements** within the configuration parameters.*
</Note>

If this setting is enabled and a user generates a customer invoice for an individual load with an external carrier, the carrier bill will not be exported from the load. In this scenario, the system expects the bill to be exported from the Carrier Settlements module when the statement is generated.

<Info>
  💡 If a carrier bill requires modification after export, refer to the **Modifications to Transactions** section for guidance.
</Info>

<Warning>
  ⚠️ **Carrier Settlements Payment Sync Limitation**

  The current version of the Carrier Settlements feature **does not** support payment synchronization. While carrier bills are exported from the Carrier Settlements module to QuickBooks Online, payments applied in QuickBooks Online do not automatically sync back to Alvys. Payments must be recorded manually within Alvys for external carriers.
</Warning>

If an error occurs while exporting a carrier bill from the Carrier Settlements module, the error details are displayed directly within the module. Carrier statements cannot be re-sent from the Error Transactions page. All corrections must be made within the Carrier Settlements module, and the statement must be regenerated there.

For tenants that use the Carrier Settlements module but prefer carrier bills to export when the carrier invoice is uploaded on the trip, it is recommended not to enable the Carrier Statements external accounting setting. In this configuration, enabling the generate carrier invoice separately setting and uploading the carrier invoice to the trip then generating the customer invoice will trigger the carrier bill export.

### Driver Bill Export

Driver bills can be exported either from the legacy Pay Drivers page or from the newer Driver Settlements module. The export behavior depends on the configured driver billing settings.

The recommended configuration is **Single Bill Export**. When enabled, multiple trips, deductions, and credits included in a driver statement are consolidated into a single bill and exported to QuickBooks Online. This approach is ideal for tenants operating on weekly or biweekly pay cycles.

The subsidiary used for exporting driver bills is determined by the subsidiary assigned on the driver profile in Alvys.

#### Driver Pay Page (Legacy)

For tenants still using the legacy Pay Drivers page, driver statements generated from this page may be reverted from the driver profile.

Reverting a driver statement deletes the corresponding driver bill from QuickBooks Online, provided the bill remains open and no payments have been applied.

#### Driver Settlements

Driver Settlements replaces the Pay Drivers module and introduces enhancements such as draft statements, predefined pay periods, and bulk actions. Additional details can be found in the [Driver Settlements Help Center Article](/en/help/accounting-settlements/driver-settlements-faq).

For statements generated using the Driver Settlements module, reverting the statement from the Statements tab removes the associated driver bill from QuickBooks Online, as long as the bill remains open and no payments have been applied.

## Shared billing Walkthrough/Demonstration

#### Enable Shared Billing on both subsidiaries

In the QBO accounting integration setup shared billing must be enabled on both the **Invoice As** subsidiary and the **Tender As** subsidiary. Each subsidiary must also have its own QuickBooks Online integration configured. If shared billing is not enabled on both sides, intercompany transactions and carrier or vendor bills will not export correctly.

<Note>
  <img alt="Displays the checked checkbox for enabling Shared Billing functionality across subsidiaries with individual accounting setups." />

  *Displays the checked checkbox for enabling **Shared Billing** functionality across subsidiaries with individual accounting setups.*
</Note>

#### Assign different subsidiaries on the load

On the load, select:

* **Invoice As subsidiary** – the subsidiary responsible for billing the customer.
* **Tender As subsidiary** – the subsidiary responsible for paying the carrier or driver.

The subsidiaries must be different for shared billing logic to apply.

<Note>
  <img alt="Shows load details with blue outlines highlighting the Invoice Customer As and Tendering As corporate identity fields." />

  *Shows load details with blue outlines highlighting the **Invoice Customer As** and **Tendering As** corporate identity fields.*
</Note>

#### Release the load

Once dispatch and financial details are complete, release the load so it becomes eligible for invoicing. Ensure all required documents are present on the load before attempting to invoice.

<Note>
  <img alt="Shows the tracking summary tracking header for Load — 1061669 marked with a red Released status badge." />

  *Shows the tracking summary tracking header for **Load — 1061669** marked with a red **Released** status badge.*
</Note>

#### Generate the customer invoice

Shared billing export is triggered when the customer invoice is generated.

<Note>
  <img alt="Displays the load's financial Money Box dashboard panel tracking sales margins, mileage totals, and final trip values." />

  *Displays the load's financial **Money Box** dashboard panel tracking sales margins, mileage totals, and final trip values.*

  <img alt="Features side-by-side Customer and Carrier Rate columns with a blue box emphasizing the clickable Generate Invoice execution button." />

  \*Features side-by-side Customer and Carrier Rate columns with a blue box emphasizing the clickable **Generate Invoice** execution button. \*
</Note>

#### Transactions created during export

**Invoice As subsidiary:**

* An intercompany bill is created to the Tender As subsidiary
* A customer invoice is created and exported to QuickBooks Online.

  **Tender As subsidiary:**
* A vendor bill is created for the external carrier or driver.
* An intercompany invoice is created back to the Invoice As subsidiary.

#### Verify transactions in QuickBooks Online

Each subsidiary will receive only the transactions applicable to its accounting company. This ensures that revenue, expenses, and intercompany balances remain accurate and properly separated.

**Invoice As Subsidiary e.g. Alvys Inc**

<Note>
  <img alt="Displays the QBO transaction interface with a green border highlighting recent ledger records for a bill and an invoice linked to load 1061669." />

  *Displays the QBO transaction interface with a green border highlighting recent ledger records for a bill and an invoice linked to load 1061669.*
</Note>

\*\*Tender As Subsidiary e.g. Alvys Brokerage \*\*

<Note>
  <img alt="Shows the QBO recent transactions search log tracking updated bill and invoice ledger rows generated under different entities for load 1061669." />

  *Shows the QBO recent transactions search log tracking updated bill and invoice ledger rows generated under different entities for load 1061669.*
</Note>

## Modifying Previously Exported Transactions

Once a transaction has been exported from Alvys to QuickBooks Online (QBO), all corrections and updates must be made in Alvys and then synchronized to QBO through the regeneration process. Alvys serves as the system of record for all exported accounting transactions. Changes made directly in QBO can result in data inconsistencies and prevent updates from syncing correctly.

This section explains how previously exported transactions can be modified, which changes are supported, and the conditions under which those modifications are allowed.

<Warning>
  ⚠️ For transactions that have already been exported from Alvys to QuickBooks Online, Alvys remains the system of record. Do not delete these transactions in QBO if you plan to edit and resend them. All updates must be made in Alvys and then regenerated to ensure accurate synchronization and maintain data integrity.
</Warning>

### Customer Invoices Exported from Load and Invoicing Pages

Previously exported invoices may be modified only while the invoice remains open. An invoice is considered open when a full payment has not been applied in QBO. Once a payment is fully applied and synced, the invoice becomes closed in Alvys and no further modifications are permitted. In these situations, [Alvys Support](mailto:support@alvys.com) must be contacted for assistance.

Invoice updates are typically synchronized by regenerating the customer invoice after changes are made. However, certain fields automatically update the QBO invoice without requiring regeneration.

Updates to the following load invoice fields are applied automatically to QuickBooks Online without requiring invoice regeneration:

**Customer linehaul amount**

**Customer fuel surcharge**

<Note>
  <img alt="Displays a customer billing layout with blue boxes highlighting a Line Haul rate of 500.00 and a manual Fuel Surcharge rate of 80.00." />

  *Displays a customer billing layout with blue boxes highlighting a Line Haul rate of $500.00 and a manual Fuel Surcharge rate of $80.00.*
</Note>

\*\*Accessorial charges added, edited, or removed \*\*

<Note>
  <img alt="Notion Image" />
</Note>

**Invoice Date**

**Invoice Due Date**

<Note>
  <img alt="Shows a portion of the Load Details workspace with blue boxes outlining the Invoice Due Date (February 14, 2026) and the Date Invoiced (Tue. Jan 20, 2026)." />

  *Shows a portion of the Load Details workspace with blue boxes outlining the Invoice Due Date (February 14, 2026) and the Date Invoiced (Tue. Jan 20, 2026).*
</Note>

To apply these updates, make the changes in Alvys and then refresh the invoice page in QuickBooks Online. The updates should appear immediately without regenerating the invoice. Other changes will require invoice regeneration to sync correctly

#### Changing the Customer on a Previously Exported Invoice

The customer associated with a load can only be changed while the load is in a status **prior to Invoiced** (e.g., **Queued**). This indicates that the invoice has been generated in Alvys but **has not yet been submitted to the customer**. Once the invoice has been submitted, the load status updates to **Invoiced** based on the invoicing mode, and the customer cannot be changed directly. In this case, users must contact [Alvys Support](mailto:support@alvys.com) to revert the load status to queued, allowing the customer to be updated and the invoice regenerated for synchronization with QuickBooks Online.

#### Sample QBO Invoice Exported from Alvys

The customer’s name displayed on the exported invoice reflects the **External Accounting Name**.

<Note>
  <img alt="Displays a customer account profile window with a blue box emphasizing the designated External Accounting Name ('Alvys Acct')." />

  *Displays a customer account profile window with a blue box emphasizing the designated External Accounting Name ("Alvys Acct").*

  <img alt="Features a comprehensive document view for Invoice 1059177, with a blue outline focusing on the main client account selection dropdown menu ('Alvys Acct')." />

  *Features a comprehensive document view for Invoice 1059177, with a blue outline focusing on the main client account selection dropdown menu ("Alvys Acct").*
</Note>

**Steps to Update the Customer on an Invoice:**

In the **Load Details** section of the load, click the **Change Customer** button.

<Note>
  <img alt="Shows a load tracking card focusing on load parameters, with a blue box highlighting the clickable Change Customer button at the bottom." />

  *Shows a load tracking card focusing on load parameters, with a blue box highlighting the clickable Change Customer button at the bottom.*
</Note>

Select the correct customer to assign to the load and save the change.

<Note>
  <img alt="Displays a Customer AutoComplete input dialog panel, providing a text field to edit or save 'Test Customer test'." />

  *Displays a Customer AutoComplete input dialog panel, providing a text field to edit or save "Test Customer test".*
</Note>

Regenerate the invoice in Alvys.

<Note>
  <img alt="Features financial workflow option controls with a blue box calling attention to the Regenerate Invoice action button." />

  *Features financial workflow option controls with a blue box calling attention to the Regenerate Invoice action button.*
</Note>

Refresh or reopen the invoice in QuickBooks Online to verify that the customer information has been updated correctly.

<Note>
  <img alt="Shows the updated invoice view for document 1059177, highlighting the blue dropdown box that reflects the new buyer profile name ('Test Customer test')." />

  *Shows the updated invoice view for document 1059177, highlighting the blue dropdown box that reflects the new buyer profile name ("Test Customer test").*
</Note>

#### Updating Invoice Customer Fields

Fields such as invoicing address, shipping address, customer email, and customer phone are managed in the customer profile.

<Warning>
  ⚠️ For these changes to take effect, the load status must be **prior to "Invoiced"**. If the load has already been invoiced, contact [Alvys Support](mailto:support@alvys.com) to revert the status to **Queued** before making updates.
</Warning>

**Steps to update customer fields:**

1. Navigate to the customer profile in Alvys.
2. Apply the necessary changes.
3. Save the updates.
4. Regenerate the invoice.
5. Refresh or reopen the invoice in QBO to view the changes.

#### Updating the Invoice-As Subsidiary After Invoice Export

Changing the Invoice-As subsidiary and regenerating the invoice will automatically remove the original invoice that was already exported to the connected QBO subsidiary. However, to prevent duplicates, ensure that the original invoice is removed; if not, manually delete it after exporting the updated invoice.

<Warning>
  ⚠️ To modify the **Invoice-As Subsidiary** on a load, the user must have the **Edit Invoice Customer As** setting enabled. Without this setting, the dropdown will be disabled and changes cannot be made.
</Warning>

**Steps to update the Invoice-As Subsidiary:**

In the Load Details section, click the Invoice Customer As dropdown.

<Note>
  <img alt="Displays the revised Load Details form showing a highlighted blue box around the Invoice Customer As selection dropdown menu." />

  *Displays the revised Load Details form showing a highlighted blue box around the Invoice Customer As selection dropdown menu.*
</Note>

1. Select the correct subsidiary to assign to the load.
2. Save the changes.
3. Regenerate the invoice in Alvys.
4. Verify in the subsidiary’s QBO account that the new invoice has been successfully exported.
5. Delete the original invoice in QBO to avoid duplicates.

#### Customer Payment terms

Alvys does not set customer payment terms on exported invoices. Instead, the payment terms configured on the **customer profile** are used to calculate the invoice due date.

<Note>
  <img alt="Shows a QBO invoice with a red box emphasizing the Terms dropdown row." />

  *Shows a QBO invoice with a red box emphasizing the **Terms** dropdown row.*
</Note>

Any updates to payment terms made directly in QBO will affect the invoice due date. However, if the invoice is regenerated from Alvys, the due date will be recalculated based on the invoice settings in Alvys and may override any manual changes made in QBO.

#### Modifications to Summary Invoices

Modifications to summary invoices that have already been exported can be made depending on the scenario.

#### Steps to Modify a Summary Invoice (Add or Remove Loads)

In Alvys, the **only supported mechanism** for adding or removing loads from a summary invoice is to **revert the summary invoice**. A summary invoice can be reverted **only when its status is “Processed”**. If the invoice has already been **Sent** or **Paid**, further modification requires intervention from [Alvys Support.](mailto:support@alvys.com)

<Warning>
  ⚠️ Reverting a summary invoice does **not update the original invoice in QuickBooks Online (QBO)**. After reverting, the user must **generate a new summary invoice in Alvys**. This new invoice will receive a **new summary invoice number**, which will be exported to QBO. The old summary invoice remains in QBO unless manually deleted.
</Warning>

**Procedure:**

1. Revert the summary invoice by navigating to the **All-Invoices** tab in Alvys.
2. Locate the invoice and Click the **Delete** icon for the specific summary invoice.

   <img alt="Features the 'All Invoices' dashboard ledger with blue boxes highlighting a Pending status and its corresponding trash can action icon." />

   *Features the "All Invoices" dashboard ledger with blue boxes highlighting a Pending status and its corresponding trash can action icon.*
3. Navigate to the **Loads Not Invoiced** tab.
4. Select the loads to be included in the new summary invoice.
5. Regenerate the summary invoice.
6. Verify that the updated summary invoice amount is accurately reflected in QuickBooks Online (QBO).
7. Manually delete the old summary invoice from QBO to avoid duplicate records.

#### Modifying or Adding Charges to Loads within a Summary Invoice

Loads included in a summary invoice can be edited to add charges or make adjustments. Only summary invoices in the following statuses can be regenerated: Pending, Sent, or Partially Paid. If a summary invoice is fully paid, regeneration is not permitted.

**Steps to Modify or Add Charges to Loads:**

Confirm that the summary invoice status is not \*\*Paid \*\*in Alvys. If the invoice is marked as Paid, all loads included in the summary invoice are set to Completed, and any subsequent modifications will not sync to QuickBooks Online for completed loads.

Navigate to the **Load Details** page for the specific load included in the summary invoice that requires modification.

<Note>
  <img alt="Shows the preview for summary invoice S1000048, with a blue box framing the first load line item (Load 1061630 for $500.00)." />

  *Shows the preview for summary invoice S1000048, with a blue box framing the first load line item (Load 1061630 for \$500.00).*
</Note>

Apply the necessary updates (e.g., add charges, adjust amounts, update notes).

<Note>
  <img alt="Features a customer rate configuration panel with a blue box highlighting the clickable Add Accessorial button at the bottom." />

  *Features a customer rate configuration panel with a blue box highlighting the clickable **Add Accessorial** button at the bottom.*

  <img alt="Displays the customer rate panel with a blue box highlighting a newly added General accessorial charge of $50.00 ." />

  *Displays the customer rate panel with a blue box highlighting a newly added **General** accessorial charge of \$50.00 .*
</Note>

Navigate back to the **Summary Invoice** in Alvys and **regenerate the summary invoice**.

<Note>
  <img alt="Features a load subtotal breakdown with a blue box highlighting the white REGENERATE action button." />

  *Features a load subtotal breakdown with a blue box highlighting the white **REGENERATE** action button.*
</Note>

Verify in **QuickBooks Online (QBO)** that the updated invoice amount and associated load details are accurately reflected.

### Troubleshooting

#### Export button is not visible on the Transactions tab

Confirm that Sync Revenue to QBO (for invoices) or Sync Expenses to QBO (for bills) is enabled in the integration settings. If either toggle is off, the Export to QBO action is not available for that transaction type.

#### A new customer or vendor was created in QBO instead of matching an existing one

Alvys matches customers and vendors by name. If the name in Alvys does not exactly match the name in QBO, a new record is created. Ensure the customer or vendor name in Alvys is an exact match to the name in your QBO customer or vendor list.

#### Transaction reverted in Alvys but original still visible in QBO

Reverting a transaction in Alvys only marks it as reverted in Alvys. The original transaction in QBO must be manually voided or deleted. Log in to QBO, locate the original invoice or bill, and void or delete it.

#### Payment recorded in QBO is not showing in Alvys

Payment status syncs on a polling interval; allow several minutes for the update to propagate. If the payment status has not updated in Alvys after 15 minutes, confirm the payment in QBO is linked to the correct invoice or bill and that the QBO transaction ID matches the one in Alvys. If the issue persists, contact Alvys Support.

### FAQs

**Q: What is the Invoice As field and why does it matter for QBO exports?**

**A:** The Invoice As field determines which entity Alvys invoices in QBO. Alvys uses this name to search for a matching customer in QBO. If a match is found, the invoice is created under that existing customer. If no match is found, Alvys creates a new customer in QBO.

**Q: What is the Tender As field?**

**A:** The Tender As field determines which carrier or vendor entity is paid in QBO. Alvys uses this name to search for a matching vendor in QBO, creating a new vendor if none is found.

**Q: Does reverting a transaction in Alvys void it in QBO?**

**A:** No. Reverting in Alvys only marks the transaction as reverted on the Alvys side. You must manually void or delete the original transaction in QBO.

**Q: Can I re-export a transaction after it fails?**

**A:** Yes. Go to Management > Integrations > Transactions, filter for Error status, select the failed transaction, and click Re-export. Resolve the underlying error (such as a missing account mapping or a duplicate document number) before re-exporting.

**Q: How long does it take for a QBO payment to show in Alvys?**

**A:** Payment status syncs on a polling interval. Allow several minutes after recording a payment in QBO for the status to update in Alvys.

**Q: Can auto-export be turned off after it has been running?**

**A:** Yes. Toggle off auto-export in the integration settings at Management > Integrations. After disabling, new transactions must be exported manually. Transactions already in the queue at the time of the toggle change are not affected.

**Q: What happens if a load has multiple invoices or bills?**

**A:** Each invoice and each bill on the load is exported as a separate QBO transaction. The Transactions tab shows each one individually with its own export status.

**Q: How do I see all failed transactions across all loads?**

**A:** Navigate to Management > Integrations > Transactions and filter by Error status. This consolidated view shows all failed exports across all loads so you can bulk re-export or resolve errors in one place.

**Q: How does Alvys decide which QuickBooks subscription receives an invoice or bill?**

**A:** It depends on the subsidiary fields. **Invoice As** determines which QBO account receives the customer invoice, while **Tender As** determines which QBO account receives the carrier bill. For drivers, the **Subsidiary** field on the driver profile determines where the bill is exported.

**Q: Which changes to a load update QuickBooks automatically without needing to regenerate?**

**A:** Updates to the **Linehaul amount, Fuel Surcharge, Accessorials, Invoice Date,** and **Invoice Due Date** sync automatically. Simply make the change in Alvys and refresh the page in QBO to see the update.

**Q: How do I change the customer on an invoice that has already been exported?**

**A:** If the load status is still **Queued**, use the **Change Customer** button in Load Details, save, and then click **Regenerate Invoice**. If the status is already **Invoiced**, contact Alvys Support to revert the status to **Queued** before making the change.

**Q: Can Alvys pull customers or vendors from QuickBooks automatically?**

**A:** No. The integration is push-only; customers and vendors are not imported from QBO. You must enter the External Accounting Name manually, as this defines the linkage to the QuickBooks customer or vendor. If no match is found, the customer or vendor is automatically created in QBO.

**Q: Can I modify an invoice that has already been paid in QuickBooks?**

**A:** No. Once a payment is fully applied and synced, the invoice is considered closed and cannot be modified. If changes are necessary after payment, contact Alvys Support for assistance.

### Go Deeper

* [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys)
* [How to Map Accounts for QuickBooks Online](/en/help/integrations/how-to-map-accounts-for-quickbooks-online)
* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)
* [QuickBooks Online: Identifying and Resolving Failed Transactions](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)
* [QuickBooks Online Integration Collection](/en/help/integrations/quickbooks-online-integration-overview)


# NetSuite: Export & modify transactions
Source: https://docs.alvys.com/en/help/integrations/how-to-export-and-modify-transactions-in-netsuite

Export customer invoices, carrier bills, and driver bills from Alvys to NetSuite, route them by subsidiary, and correct transactions after they post.

<Note>
  This article explains how Alvys exports customer invoices, carrier bills, and driver bills to NetSuite, how subsidiaries, customers, and vendors are linked during export, and how to correct a transaction after it has been exported.
</Note>

## Overview

When you generate an invoice or release a load in Alvys, transaction data is automatically queued for export (push) to NetSuite. Alvys determines which NetSuite subsidiary receives each transaction based on fields set on the load (Invoice As, Tender As) and the driver profile. Once exported, all corrections must originate in Alvys and then synchronize to NetSuite. Editing or deleting transactions directly in NetSuite while Alvys still manages that record will cause sync conflicts.

## Before You Start

Complete the following before exporting transactions:

1. NetSuite: Prerequisites (Start Here)
2. NetSuite: Authentication and Settings Configuration in Alvys
3. NetSuite: Account Mappings and Item Mappings

You also need the **"CompanyProfileManager"** permission, available to users with the Admin, Partner Admin, or Support role, to access Management > Integrations.

## Subsidiary Determination for Transaction Exports

*\[Heading 4 not supported]*

The **Invoice As** field on a load represents the billing subsidiary responsible for issuing the customer invoice. All Accounts Receivable (AR) transactions are exported to NetSuite and linked to the subsidiary mapped to the Invoice As field.

<Note>
  <img alt="Invoice As field on a load record." />

  *Invoice As field on a load record.*
</Note>

*\[Heading 4 not supported]*

The **Tender As** field identifies the subsidiary responsible for dispatching the load and paying the carrier. It also determines the trip type: Brokerage (if the subsidiary is set up as a broker) or Carrier (if set up as a carrier). Carrier bills are exported and the Subsidiary field on the Vendor Bill is set to the NetSuite subsidiary linked to the Tender As field.

<Note>
  <img alt="Tender As field on a trip." />

  *Tender As field on a trip.*
</Note>

**Dual Authority Carriers:** For carriers operating with dual authority, the operational mode is automatically determined based on the Tender As subsidiary. You can manually change the operational mode to Carrier or Broker on the trip.

<Note>
  <img alt="Dual authority carrier operational mode toggle on trip." />

  *Dual authority carrier operational mode toggle on trip.*
</Note>

*\[Heading 4 not supported]*

Each driver profile includes a **Subsidiary** field. When generating driver statements, the Vendor Bill is exported to the NetSuite subsidiary linked to the driver's assigned subsidiary.

<Note>
  <img alt="Subsidiary field on a sample driver profile." />

  * Subsidiary field on a sample driver profile.\*
</Note>

## Customer Linkage, Creation, and Accounting Fields

### Customer External Accounting Name

By default (when **Use Existing Customers** is disabled), the customer's **External Accounting Name** is used to identify the customer in NetSuite. Alvys first searches for an exact match using this field. If a match exists, the invoice is linked to that customer. If no match is found and the External Accounting Name is set, Alvys automatically creates a new customer in NetSuite using the External Accounting Name. If no External Accounting Name is set, Alvys falls back to the Customer Name.

<Note>
  <img alt="External Accounting Name field on customer profile." />

  *External Accounting Name field on customer profile.*
</Note>

**Important:** The External Accounting Name always takes priority. If it differs from an existing NetSuite customer name, a new customer will be created using the External Accounting Name.

### Use Existing Customers

The **Use Existing Customers** setting in the NetSuite integration determines whether Alvys links invoices to existing customers using their NetSuite customer IDs, bypassing name-based matching. When enabled, set the NetSuite customer ID on each customer profile in Alvys for the relevant subsidiary.

<Note>
  <img alt="Customer profile with External Accounting ID Field" />

  *Customer profile with External Accounting ID Field*
</Note>

<Note>
  <img alt="External Accounting form with Customer ID Field" />

  *External Accounting form with Customer ID Field*
</Note>

The customer ID can be found in the URL of the customer record in NetSuite (the parameter **id=12345** in the URL).

**Important:** If the ID is missing, incorrect, or points to a non-existent customer record, the invoice export will fail with this error on the Error Transactions page: `CustomerNotFound: Customer not found. Customer not found for name '[Customer Name]' and id '[Customer ID]'`

### Invoicing Name

The **Invoicing Name** determines how the customer or broker appears on invoices generated in Alvys. It does not affect the customer record created or matched in NetSuite.

<Note>
  <img alt="Invoicing Name field on sample customer profile." />

  *Invoicing Name field on sample customer profile.*
</Note>

Alvys is the source of truth for customer fields (invoicing address, email, phone). If a customer is created in NetSuite by Alvys and a user later updates the information directly in NetSuite, those changes will be overridden on the next invoice sync from Alvys.

### Payment Terms

The **Payment Terms** field specifies the agreed-upon payment period, calculated from the invoice date. In Alvys, this can be set between 0 and 365 days and determines the invoice due date exported to NetSuite.

<Note>
  <img alt="Payment Terms field on a sample customer profile." />

  \*Payment Terms field on a sample customer profile. \*
</Note>

## Vendor Linkage, Creation, and Accounting Fields

### Carrier External Accounting Name

The carrier's **External Accounting Name** is used to identify a vendor in NetSuite. If a matching vendor exists, the bill is linked to it. If no match is found, Alvys creates a new vendor using the External Accounting Name (or the Carrier Name if External Accounting Name is not set).

<Note>
  <img alt="External Accounting Name field on a sample carrier profile." />

  *External Accounting Name field on a sample carrier profile.*
</Note>

<Warning>
  ⚠️ The External Accounting Name takes priority. If it differs from an existing NetSuite vendor name, Alvys will create a new vendor.
</Warning>

### Driver Name and 1099 Tax Details

Drivers may have additional tax fields on their profiles: Tax Company Name and Tax Company Address.

<Note>
  <img alt="Tax detail fields on driver profile (Tac Category, Tax Company Name and Tax Company Address)." />

  *Tax detail fields on driver profile (Tac Category, Tax Company Name and Tax Company Address).*
</Note>

When generating driver statements, if these fields are set and the integration is configured to create vendors using 1099 details, Alvys creates the vendor in NetSuite using the tax information. If this setting is not enabled, the vendor is created using the driver's name.

### Carrier Payment Terms

The **Carrier Payment Terms** field defines the time frame for paying a carrier, configured on the company profile (Management > Company Profile) for each subsidiary.

<Note>
  <img alt="Carrier Payment Terms field on company profile." />

  *Carrier Payment Terms field on company profile.*
</Note>

For external carriers, the due date is determined using the Carrier Payment Terms from the company profile of the subsidiary specified in the Tender As field on the trip.

## Steps

### Individual Load Invoice Export

**Verify pre-export conditions for a single-load invoice.**

* Confirm the customer being invoiced is correct.
* Ensure the **External Accounting Name** is set on the customer profile. If not set, the standard customer or broker name must exactly match the corresponding customer record in NetSuite.

<Note>
  <img alt="Customer profile with External Accounting Name field highlighted." />

  *Customer profile with External Accounting Name field highlighted.*
</Note>

<Note>
  <img alt="Image showing Customer Name in NetSuite" />

  *Image showing Customer Name in NetSuite*
</Note>

* If **Use Existing Customers** is enabled, confirm the NetSuite customer ID is entered in the **External Accounting ID** field and matches the customer ID in NetSuite.
* Verify the customer's invoice settings for the subsidiary used as the Invoice As subsidiary on the load.

<Note>
  <img alt="Customer invoice settings per subsidiary." />

  *Customer invoice settings per subsidiary.*
</Note>

Generate the invoice to trigger export.

* Once pre-export conditions are met and the load is in **Released** status, generating the invoice automatically initiates the export to NetSuite.

<Note>
  <img alt="Generate Invoice button on Load Details." />

  *Generate Invoice button on Load Details.*
</Note>

*\[Heading 4 not supported]*

The Batch Invoicing page in Alvys is located under accounting, then Invoice in the left navigation menu or directly at [https://app.alvys.com/#/accounting/invoicing](https://app.alvys.com/#/accounting/invoicing).

<Note>
  <img alt="Image showing navigation to invoicing page" />

  \*Image showing navigation to invoicing page \*
</Note>

This page allows users to create invoices for multiple loads across one or more customers simultaneously. Each selected load is processed as an individual invoice, and exporting to NetSuite is triggered automatically when the invoices are generated. This approach enables faster and more efficient invoicing while ensuring accurate transaction records for each load.

From the **Released** tab, select the loads for which you want to generate invoices.

<Note>
  <img alt="Image showing loads selected for invoicing in the released tab" />

  *Image showing loads selected for invoicing in the released tab*
</Note>

<Info>
  💡 Ensure that the customer being invoiced is correct. If an **External Accounting Name** is configured, it must exactly match the corresponding customer record in NetSuite. If no External Accounting Name is configured, the standard customer or broker name must match the customer record.

  For users with the **Use Existing Customers** setting enabled, verify that the NetSuite customer ID is set on the customer profile. Additionally, the **Invoice As** subsidiary on each load must be correctly configured, as this determines which NetSuite subsidiary will be linked to the exported invoice.
</Info>

After verifying these details, invoices can be generated using the **Generate Invoice** option, which creates the invoices and exports them to NetSuite. Alternatively, the **Create and Send** option generates the invoices, exports them to NetSuite, and sends them to the customer according to the invoicing method configured for that customer.

<Note>
  <img alt="Image showing Generate Invoicing button" />

  *Image showing Generate Invoicing button*
</Note>

Once exported, the invoices are recorded in NetSuite under the corresponding customer and can be located either using the search field or by browsing the Invoices list.

<Note>
  <img alt="Image showing the exported invoices from Alvys in NetSuite" />

  \*Image showing the exported invoices from Alvys in NetSuite \*
</Note>

*\[Heading 4 not supported]*

Summary invoicing consolidates multiple loads for a customer into a single invoice. The Summary Invoicing page can be accessed from Accounting then Summary Invoicing. For more information on configuring customers for summary invoicing, see [How to use Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing).

The invoice export is triggered when the consolidated summary invoice is generated, creating a single invoice that reflects the total amount for all included loads. Only customers configured with the summary invoice type will appear when selecting a subsidiary. Ensure that the subsidiary is correct, as this determines the NetSuite subsidiary to which the invoice will be linked.

On the [Summary Invoicing page](https://app.alvys.com/#/accounting/summary-invoicing), from the Loads Not Invoiced tab, select the loads to include and add them to a draft summary invoice. Once the draft is prepared, generating the invoice will create the summary invoice and export it to NetSuite.

<Note>
  <img alt="Image showing the “Loads Not Invoiced” tab on the Summary invocing page with loads selected and the “Add To Draft” button highlighted." />

  *Image showing the “**Loads Not Invoiced**” tab on the Summary invocing page with loads selected and the “**Add To Draft**” button highlighted.*

  <img alt="Image showing the “Draft Invoice” tab on the Summary invocing page with loads selected and the “Generate Invoice” button highlighted." />

  *Image showing the “**Draft Invoice**” tab on the Summary invocing page with loads selected and the “**Generate Invoice**” button highlighted.*
</Note>

After the invoice is exported, it can be located in the NetSuite **Invoices** list, where users can browse all invoices and apply date filters to narrow the results.

<Note>
  <img alt="Image showing the exported summary invoice from Alvys in NetSuite" />

  \*Image showing the exported summary invoice from Alvys in NetSuite \*
</Note>

<Warning>
  ⚠️ If the summary invoice is not exported due to an error, the issue can be reviewed on the Error Transactions page. However, summary invoices cannot be re-sent directly from the Error Transactions page. Any required modifications must be made on the Summary Invoicing page, and the invoice must be regenerated from there. Additional guidance on modifying summary invoices can be found in the section titled “**Modifying Previously Exported Transactions**”**.**
</Warning>

## Bill Transaction Export Demonstration

This section explains the different methods available in Alvys for exporting bill transactions to NetSuite. It covers external carrier bills, carrier settlements, and driver bill exports, including the configuration requirements that determine when and how each bill is exported.

*\[Heading 4 not supported]*

External carrier bills can be exported directly from individual loads based on the configured external accounting settings. The export is triggered when the customer invoice is generated. Before generating the invoice, ensure that the correct external carrier is assigned to the trip. The subsidiary selected in the **Tender As** field must also be verified, as this subsidiary determines which NetSuite subsidiary the carrier bill will be linked to. The selected subsidiary must be configured to receive carrier bills through the NetSuite integration.

<Warning>
  ⚠️ For tenants operating in dual-authority mode, an additional validation is required. The operational mode must be set to **Brokerage**. If the operational mode is set to **Carrier**, the external carrier bill export will not occur.

  <img alt="Image showing operational mode with brokerage selected" />

  *Image showing operational mode with brokerage selected*
</Warning>

When an external carrier is assigned and the trip is released to billing, the system evaluates the **Generate Carrier Invoice Separately** setting.

If this setting is not enabled, the carrier bill is exported automatically when the customer invoice is generated. However, if the setting is enabled, the system checks whether a document of type **Carrier Invoice** has been uploaded to the trip. If the document is present, the carrier bill is exported to NetSuite when the customer invoice is generated.

<Note>
  <img alt="Image showing document upload form with sample carrier invoice document" />

  *Image showing document upload form with sample carrier invoice document*
</Note>

*\[Heading 4 not supported]*

In Alvys, the carrier invoice number is entered when uploading a document of type **Carrier Invoice** to a trip. When the carrier bill is exported to NetSuite, this number is automatically appended to both the **Memo** field and the **Reference Number** field. This allows accounting teams to easily search for, reference, and reconcile carrier bills using the carrier’s original invoice number.

<Note>
  <img alt="Image showing carrier invoice number on load details page" />

  *Image showing carrier invoice number on load details page*

  <img alt="Image showing carrier invoice number added to the memo field onthe carrier billing Netsuite" />

  *Image showing carrier invoice number added to the memo field onthe carrier billing Netsuite*

  <img alt="Image showing Carrier Invoice number used as reference number on carrier bill exported to NetSuite" />

  \*Image showing Carrier Invoice number used as reference number on carrier bill exported to NetSuite \*
</Note>

### Carrier Settlements

The Carrier Settlements module provides brokers with tools to generate transparent and accurate carrier statements and settlement bills. This page can be accessed from the accounting section of Alvys under Carrier Settlements.

When carrier settlements are used, the carrier bill is exported when a carrier statement is generated. To allow this export, the **Carrier Statements External Accounting** setting must be enabled for the subsidiary. If this setting is not enabled, no carrier bill will be exported when the statement is generated

<Note>
  <img alt="Image showing the carrier statements setting enabled in the accounting integration setup." />

  *Image showing the carrier statements setting enabled in the accounting integration setup.*
</Note>

If this setting is enabled and a user generates a customer invoice for an individual load with an external carrier, the carrier bill will not be exported from the load. In this scenario, the system expects the bill to be exported from the Carrier Settlements module when the statement is generated.

<Info>
  💡 If a carrier bill requires modification after export, refer to the **Modifications to Transactions** section for guidance.
</Info>

<Warning>
  ⚠️ **Carrier Settlements Module Payment Sync Limitation**

  The current version of the Carrier Settlements feature **does not** support payment synchronization. While carrier bills are exported from the Carrier Settlements module to NetSuite, payments applied in NetSuite do not automatically sync back to Alvys. Payments must be recorded manually within Alvys for the external carriers.
</Warning>

If an error occurs while exporting a carrier bill from the Carrier Settlements module, the error details are displayed directly within the module. Carrier statements cannot be re-sent from the Error Transactions page. All corrections must be made within the Carrier Settlements module, and the statement must be regenerated there.

For tenants that use the Carrier Settlements module but prefer carrier bills to export when the carrier invoice is uploaded on the trip, it is recommended not to enable the Carrier Statements external accounting setting. In this configuration, enabling the generate carrier invoice separately setting and uploading the carrier invoice to the trip then generating the customer invoice will trigger the carrier bill export.

### Driver Bill Export

Driver bills can be exported either from the legacy **Pay Drivers** page or from the newer **Driver Settlements** module. The export behavior depends on the configured driver billing settings.

The recommended configuration is **Single Bill Export**. When enabled, multiple trips, deductions, and credits included in a driver statement are consolidated into a single bill and exported to NetSuite. This approach is ideal for tenants operating on weekly or biweekly pay cycles.

The subsidiary used for exporting driver bills is determined by the subsidiary assigned on the driver profile in Alvys.

*\[Heading 4 not supported]*

For tenants still using the legacy **Pay Drivers** page, driver statements generated from this page may be reverted from the driver profile. Reverting a driver statement deletes the corresponding driver bill from NetSuite, provided the bill remains open and no payments have been applied.

*\[Heading 4 not supported]*

Driver Settlements replaces the Pay Drivers module and introduces enhancements such as draft statements, predefined pay periods, and bulk actions. Additional details can be found at: [Driver Settlements Help Center Article](/en/help/accounting-settlements/driver-settlements-faq)

For statements generated using the Driver Settlements module, reverting the statement from the **Statements** tab removes the associated driver bill from NetSuite, as long as the bill remains open and no payments have been applied.

## Modifying Exported Transactions

Once a transaction has been exported from Alvys to NetSuite, all corrections and updates must be made in Alvys and then synchronized to NetSuite through the regeneration process. Alvys serves as the **system of record** for all accounting transactions that were exported. Changes made directly in NetSuite will *not* sync back to Alvys and can result in data inconsistencies or failed export updates. This section explains how previously exported transactions can be modified, which changes are supported, and the conditions under which those modifications are allowed.

For transactions that have already been exported from Alvys to NetSuite, Alvys remains the system of record. Do *not* edit or delete these transactions directly in NetSuite if you plan to update and resend them from Alvys. All updates must be made in Alvys and then regenerated to ensure accurate synchronization and maintain data integrity.

### Customer Invoices Exported from Load and Invoicing Pages

Previously exported invoices can only be modified while they are still considered **open** (i.e., not fully paid) in NetSuite. Once a payment is fully applied and synced, the invoice becomes closed in Alvys and no further modifications are permitted. In these situations, [Alvys Support](mailto:support@alvys.com) must be contacted for assistance.

Invoice updates are typically synchronized by regenerating the customer invoice after changes are made. However, certain fields automatically update the NetSuite invoice without requiring regeneration.

Updates to the following load invoice fields are applied automatically to NetSuite without requiring invoice regeneration:

**Customer linehaul amount**

**Customer fuel surcharge**

<Note>
  <img alt="Image showing customer rate card in money box with linehaul and fuel surcharge fields" />

  *Image showing customer rate card in money box with linehaul and fuel surcharge fields*
</Note>

Accessorial charges added, edited, or removed

<Note>
  <img alt="Image showing a sample accessorial with the accessorial options highlighted." />

  *Image showing a sample accessorial with the accessorial options highlighted.*
</Note>

**Invoice Date**

**Invoice Due Date**

<Note>
  <img alt="Image showing “Invoice Date” and Invoice Due Date fields on the load details page." />

  *Image showing “Invoice Date” and Invoice Due Date fields on the load details page.*
</Note>

To apply these updates, make the changes in Alvys and then refresh the invoice page in NetSuite. The updates should appear immediately without regenerating the invoice. Other changes will require invoice regeneration to sync correctly

*\[Heading 4 not supported]*

Fields such as invoicing address, customer email, and customer phone are managed in the customer profile.

<Warning>
  ⚠️ For these changes to take effect, the load status must be **prior to "Invoiced"**. If the load has already been invoiced, contact [Alvys Support](mailto:support@alvys.com) to revert the status to **Queued** before making updates.
</Warning>

**Steps to update customer fields:**

1. Navigate to the customer profile in Alvys.
2. Apply the necessary changes.
3. Save the updates.
4. Regenerate the invoice.
5. Refresh or reopen the invoice in NetSuite to view the changes.

### Customer Payment terms

Alvys does not set customer payment terms on exported invoices. Instead, the payment terms configured on the **customer profile** are used to calculate the invoice due date.

<Note>
  <img alt="Image showing exported Invoice in NetSuite with invoice due date set." />

  *Image showing exported Invoice in NetSuite with invoice due date set.*
</Note>

Any updates to payment terms made directly in NetSuite will affect the invoice due date. However, if the invoice is regenerated from Alvys, the due date will be recalculated based on the invoice settings in Alvys and may override any manual changes made in NetSuite.

### Modifications to Summary Invoices

Modifications to summary invoices that have already been exported can be made depending on the scenario.

*\[Heading 4 not supported]*

In Alvys, the **only supported mechanism** for adding or removing loads from a summary invoice is to **revert the summary invoice**. A summary invoice can be reverted **only when its status is “Processed”**. If the invoice has already been **Sent** or **Paid**, further modification requires intervention from [Alvys Support.](mailto:support@alvys.com)

<Warning>
  ⚠️ Reverting a summary invoice does **not update the original invoice in NetSuite**. After reverting, the user must **generate a new summary invoice in Alvys**. This new invoice will receive a **new summary invoice number**, which will be exported to NetSuite. The old summary invoice remains in NetSuite unless manually deleted.
</Warning>

**Procedure:**

* Revert the summary invoice by navigating to the **All-Invoices** tab in Alvys.
* Locate the invoice and Click the **Delete** icon for the specific summary invoice.

<Note>
  <img alt="Image showing Summary invoice page, “All invoices” tab with “Delete” icon highlighted for a sample invoice." />

  *Image showing Summary invoice page, “All invoices” tab with “Delete” icon highlighted for a sample invoice.*
</Note>

* Navigate to the **Loads Not Invoiced** tab.
* Select the loads to be included in the new summary invoice.
* Regenerate the summary invoice.
* Verify that the updated summary invoice amount is accurately reflected in NetSuite.
* Manually delete the old summary invoice from NetSuite to avoid duplicate records.

### Modifying or Adding Charges to Loads within a Summary Invoice

Loads included in a summary invoice can be edited to add charges or make adjustments. Only summary invoices in the following statuses can be regenerated: Pending, Sent, or Partially Paid. If a summary invoice is fully paid, regeneration is not permitted.

**Steps to Modify or Add Charges to Loads:**

Confirm that the summary invoice status is not \*\*Paid \*\*in Alvys. If the invoice is marked as Paid, all loads included in the summary invoice are set to Completed, and any subsequent modifications will not sync to NetSuite for completed loads.

Navigate to the **Load Details** page for the specific load included in the summary invoice that requires modification.

Apply the necessary updates (e.g., add charges, adjust amounts, update notes). In the image below, the fuel surcharge amount and an accessorial charge were added to the load

<Note>
  <img alt="Image showing customer rate card in money box with linehaul, fuel surcharge field and accessorials highlighted." />

  *Image showing customer rate card in money box with linehaul, fuel surcharge field and accessorials highlighted.*
</Note>

Navigate back to the **Summary Invoice** in Alvys and **regenerate the summary invoice**.

<Note>
  <img alt="Image showing summary invoicing page with regenerate button" />

  *Image showing summary invoicing page with regenerate button*
</Note>

Verify in NetSuite that the updated invoice amount and associated load details are accurately reflected.

<Note>
  <img alt="Image showing updated exported invoice in NetSuite" />

  *Image showing updated exported invoice in NetSuite*
</Note>

<Warning>
  ⚠️ Some changes are currently not supported in Alvys. Specifically, changing the customer on an invoice or changing the Invoice As or Tender As subsidiary for previously exported transactions will not update the corresponding transaction in NetSuite. If a transaction was previously exported with incorrect information, please contact [Alvys Support](mailto:support@alvys.com) for assistance.
</Warning>

## Troubleshooting

### Invoice export fails immediately after generation

**Step 1:** Check the Error Transactions page in Alvys (Management > Integrations).

**Step 2:** Review the error message: common causes are the External Accounting Name not matching any customer in NetSuite, missing or incorrect External Accounting ID when Use Existing Customers is enabled, or the Invoice As subsidiary not mapped in integration settings.

**Step 3:** Correct the underlying issue in the customer profile or integration settings.

**Step 4:** Re-export from the Error Transactions page or by regenerating the invoice.

### Carrier bill or driver bill not appearing in NetSuite

**Step 1:** Confirm the carrier or driver has an External Accounting Name set. If not set, the name must match an existing vendor exactly.

**Step 2:** Check the Error Transactions page for any error on that transaction.

**Step 3:** If the driver bill is not appearing, verify that **Ignore Driver Bills** is not enabled in the NetSuite integration settings.

### Shared Billing transactions not exporting correctly

**Step 1:** Confirm Shared Billing is enabled on both the Invoice As subsidiary and the Tender As subsidiary.

**Step 2:** Verify both subsidiaries are mapped to their respective NetSuite subsidiaries in the integration settings.

**Step 3:** Confirm the load has a different subsidiary set in Invoice As and Tender As.

**Step 4:** Check the Error Transactions page for errors related to either subsidiary.

### Updated transaction not reflected in NetSuite after re-export

**Step 1:** Confirm the correction was saved in Alvys before the re-export was triggered.

**Step 2:** Check the Error Transactions page. If a conflict error appears mentioning the transaction's internal ID, the transaction may have been manually edited in NetSuite. Contact Alvys Support if none of the above reasons apply.

## FAQs

**Q: Can I edit a transaction directly in NetSuite instead of in Alvys?**

**A:** No. All corrections must be made in Alvys and then synchronized to NetSuite. Editing a transaction directly in NetSuite may cause sync conflicts or result in the NetSuite record being overwritten on the next export.

**Q: Why was a new customer created in NetSuite instead of linking to an existing one?**

**A:** Alvys uses the External Accounting Name on the customer profile to find a match in NetSuite. If the External Accounting Name does not exactly match an existing NetSuite customer name, Alvys creates a new customer. To prevent duplicates, set the External Accounting Name to match the exact name in NetSuite, or enable the Use Existing Customers setting and enter the NetSuite customer ID in the External Accounting ID field.

**Q: What happens if the Invoice As subsidiary on a load is not mapped to a NetSuite subsidiary?**

**A:** The invoice export will fail. An error will appear on the Error Transactions page. The Invoice As subsidiary must be mapped in the integration settings before invoices can be exported for that load.

**Q: Does the Invoicing Name affect which customer record is created or matched in NetSuite?**

**A:** No. The Invoicing Name controls how the customer appears on invoices in Alvys. The External Accounting Name or Customer Name is used for NetSuite matching.

**Q: Can driver bills be excluded from the NetSuite export?**

**A:** Yes. The **Ignore Driver Bills** setting in the NetSuite integration configuration prevents driver-associated bills from being exported to NetSuite when enabled.

**Q: What is the error format when a customer is not found during export?**

**A:** `CustomerNotFound: Customer not found. Customer not found for name '[Customer Name]' and id '[Customer ID]'`

**Q: For Shared Billing loads, how many transactions are created in NetSuite?**

**A:** Four: a customer invoice linked to the Invoice As subsidiary, a carrier vendor bill linked to the Tender As subsidiary, an intercompany sales invoice from the Tender As subsidiary to the Invoice As subsidiary, and an intercompany vendor bill from the Invoice As subsidiary to the Tender As subsidiary.

**Q: What should I enter for the External Accounting Name?**

**A:** Enter the customer or vendor name exactly as it appears in NetSuite. Alvys uses this field to match records during invoice and bill exports. If the field is not set, Alvys falls back to the Customer Name or Vendor Name.

**Q: Can Alvys pull customers or vendors from NetSuite automatically?**

**A:** No. The integration is push-only from Alvys to NetSuite. You must manually enter the External Accounting Name (or Customer ID if using Use Existing Customers), which defines the linkage to NetSuite. If no match is found, Alvys can create the customer or vendor automatically in NetSuite.

**Q: Which changes are not supported in Alvys after export?**

**A:** Modifying the customer on an invoice or changing the Invoice As or Tender As subsidiary for previously exported transactions will not update the corresponding transaction in NetSuite. Contact Alvys Support to assist with correcting the export in these cases.

**Q: How do I update customer details like address, email, or phone?**

**A:** Update the customer profile in Alvys before regenerating the invoice. If the invoice has already been generated, it must be reverted to Queued in Alvys before changes take effect. After updating, regenerate the invoice to sync the changes to NetSuite.

**Q: How can I locate an exported invoice or bill in NetSuite?**

**A:** Use the NetSuite search bar to enter the load number or invoice number, including any prefix if configured. Invoices appear under the corresponding customer in the Invoices list; bills appear in the Bills list.

**Q: Does the carrier invoice number appear in NetSuite?**

**A:** Yes. When uploading a carrier invoice to a trip, the number is appended to both the Memo and Reference Number fields in the NetSuite bill.

**Q: How do I modify a summary invoice after it has been exported?**

**A:** Loads can be added or removed only by reverting the summary invoice (when the status is Processed) and regenerating it. Fully paid or sent invoices require Alvys Support intervention. Each regenerated summary invoice receives a new invoice number in NetSuite; the original remains unless manually deleted.

## Go Deeper

* [NetSuite: Identifying and Resolving Failed Transactions](/en/help/integrations/transactions-failed-to-sync-to-netsuite)
* [NetSuite: Account Mappings and Item Mappings](/en/help/integrations/how-to-set-up-netsuite-account-and-item-mappings-in-alvys)
* [NetSuite: Authentication and Settings Configuration in Alvys](/en/help/integrations/netsuite-authentication-and-settings-configuration-in-alvys)
* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)


# QuickBooks Desktop: Export & modify transactions
Source: https://docs.alvys.com/en/help/integrations/how-to-export-and-modify-transactions-in-quickbooks-desktop

Export customer invoices, carrier bills, and driver settlements from Alvys to QuickBooks Desktop using the Web Connector, then modify posted transactions.

<Note>
  This article covers how to export customer invoices, carrier bills, and driver settlements from Alvys to QuickBooks Desktop (QBD), and how to modify previously exported transactions. Also covers the QBD export queue, customer and vendor matching, shared billing, and using the QuickBooks Web Connector.
</Note>

## Overview

The Alvys and QuickBooks Desktop integration exports (pushes) customer invoices, carrier bills, and driver settlements from Alvys to your QuickBooks Desktop company file. Exports are triggered by actions you take in Alvys (generating an invoice, creating a settlement), and the data transfer occurs when the QuickBooks Web Connector runs its sync cycle.

All transaction types follow the same export flow: after a transaction is triggered in Alvys, it appears on the Accounting > Error Transactions page in a queued state (shown as a dash). The transaction waits on this page until the QuickBooks Web Connector connects and pulls it into your company file. Appearing on the Error Transactions page in a queued state does not indicate a failure.

## Before You Start

Before exporting transactions, confirm the following:

* You have Admin, Partner Admin, or Support access in Alvys. The accounting integration requires the **"CompanyProfileManager"** permission, which is available to those three roles.
* The QuickBooks Desktop integration is active for the relevant subsidiary. See How to connect QuickBooks Desktop to Alvys and configure settings to complete the connection first.
* The QuickBooks Web Connector is installed and running on the same computer as QuickBooks Desktop.
* For customer invoice exports: the load must be in an invoiceable status: **TONU**, **Released**, **Queued**, **Invoiced**, **Financed**, or **Completed**.

## Key Concepts

### The export queue and Error Transactions page

When a transaction is triggered in Alvys, it is placed in a pending export queue and appears on the Error Transactions page with a dash status. This queued state is not an error. The transaction waits here until the QuickBooks Web Connector runs and pulls it into your company file. Once the sync completes, the transaction clears from this page.

<Note>
  <img alt="Screenshot showing the Error Transactions page with a queued (dash status) transaction." />

  *Screenshot showing the Error Transactions page with a queued (dash status) transaction.*
</Note>

You can manually trigger an export at any time by opening the QuickBooks Web Connector, checking the box next to the Alvys application, and clicking Update Selected.

### Which subsidiary receives each transaction

Each Alvys subsidiary is connected to its own QuickBooks Desktop company file. The subsidiary that receives a transaction is determined as follows:

* **Customer invoices** export to the QuickBooks company linked to the subsidiary in the **Invoice As** field on the load.

<Note>
  <img alt="Image showing the “Invoice As” dropdown button in the load details page" />

  *Image showing the “Invoice As” dropdown button in the load details page*
</Note>

* **Carrier bills** export to the QuickBooks company linked to the subsidiary in the **Tender As** field on the load.

<Note>
  <img alt="Image showing the Tendering As field in the carrier details on the load details page." />

  *Image showing the Tendering As field in the carrier details on the load details page.*
</Note>

* **Driver bills** export to the QuickBooks company linked to the subsidiary assigned on the driver's profile.

<Note>
  <img alt="Image showing the Subsidiary field on a driver profile" />

  *Image showing the Subsidiary field on a driver profile*
</Note>

### How Alvys matches customers in QuickBooks

The customer’s **External Accounting Name** is used to identify a customer or broker in **QuickBooks Desktop (QBD)**. When exporting an invoice, Alvys first searches for an exact match in **QBD** using this field.

If a matching customer exists, the invoice is linked to that customer. If no match is found and the **External Accounting Name** is set on the customer profile, Alvys will automatically create a new customer in **QBD** using that name. For tenants where the **External Accounting Name** is not set, Alvys attempts to match using the **Customer Name**. If no match is found, a new customer is created in **QBD** using the **Customer Name**.

It is important to note that the External Accounting Name **takes priority**. If the External Accounting Name differs from an existing QBD customer name, even if the Customer Name in Alvys matches, Alvys will create a new customer using the External Accounting Name.

<Note>
  <img alt="Image showing the External Accounting Name field on the Customer profile." />

  *Image showing the External Accounting Name field on the Customer profile.*
</Note>

When exporting a transaction, Alvys searches your QuickBooks file for an exact match using the External Accounting Name on the customer or carrier profile. If a match is found, the transaction links to that existing record. If no match is found, Alvys automatically creates a new customer or vendor in QuickBooks using that name.

<Warning>
  ⚠️ QuickBooks requires unique names across all lists: Customers, Vendors, and Employees. If Alvys tries to create a name that already exists in a different list, the export will fail.
</Warning>

### How Alvys matches Vendors in QuickBooks

This section explains how Alvys links carriers and drivers to QuickBooks Desktop (QBD), how vendor records are created when no match is found, and which accounting fields control bill synchronization.

*\[Heading 4 not supported]*

The carrier’s **External Accounting Name** is used to identify a vendor in QuickBooks Desktop (QBD). When exporting a bill, Alvys first searches for an **exact match** in QBD using this field.

<Note>
  <img alt="Image showing the External Accounting Name field on the Carrier profile." />

  *Image showing the External Accounting Name field on the Carrier profile.*
</Note>

If a matching vendor exists, the bill is linked to that vendor. If no match is found and the External Accounting Name is set on the carrier profile, Alvys will automatically create a new vendor in QBD using the External Accounting Name. For carriers where the External Accounting Name is **not set**, Alvys attempts to match using the **Carrier Name**. If no match is found, a new vendor is created in QBD using the Carrier name.

It is important to note that the External Accounting Name **takes priority**. If it differs from an existing QBD vendor name, even if the Carrier or Driver Name in Alvys matches, Alvys will create a new vendor using the External Accounting Name.

*\[Heading 4 not supported]*

Drivers, including company drivers and owner-operators, may operate as **1099 drivers**. These drivers have additional tax detail fields on their profiles, such as:

* **Tax Company Name**
* **Tax Company Address**

<Note>
  <img alt="Image showing the Tax Information on a sample driver profile" />

  *Image showing the Tax Information on a sample driver profile*
</Note>

When generating driver statements, if these fields are set and the accounting integration is configured to create vendors using 1099 details, Alvys will create the vendor using the tax information (company name and address). If this setting is not enabled, the vendor will be created using the driver’s name.

*\[Heading 4 not supported]*

The **Carrier Payment Terms** field defines the agreed-upon time frame for paying a carrier. This is configured on the [company profile](https://app.alvys.com/#/manage/company-profile) for each subsidiary.

<Note>
  <img alt="Image showing carrier payment terms on the company/tenant profile" />

  \*Image showing carrier payment terms on the company/tenant profile \*
</Note>

If a driver is associated with a subsidiary that has this payment terms configured, the bill due date will be calculated based on that subsidiary’s terms.

For external carriers, the due date is determined using the Carrier Payment Terms from the company profile of the subsidiary specified in the Tender As field on the trip.

## Steps

### 1. Export a customer invoice

### Individual load invoice

* Verify the load is in an invoiceable status: **TONU**, **Released**, **Queued**, **Invoiced**, **Financed**, or **Completed**.
* Confirm the customer is correct on the load, and the Invoice As subsidiary matches the subsidiary connected to the QuickBooks Desktop company that should receive the invoice.
* Confirm the customer's External Accounting Name is set and matches the corresponding customer in QuickBooks Desktop.

<Note>
  <img alt="Screenshot showing the Invoice As and External Accounting Name fields on a load." />

  \*Screenshot showing the Invoice As and External Accounting Name fields on a load. \*
</Note>

* Generate the invoice from the load's Invoice section.
* Open the QuickBooks Web Connector and click Update Selected to trigger the export.

<Note>
  <img alt="Image showing the update selected button in the QBD web connector" />

  \*Image showing the update selected button in the QBD web connector \*
</Note>

* After the connector completes this sync, the invoice can be located by navigating to the Customer Center and selecting the specific customer to view their Transactions tab. Users can filter the list for Invoices and apply date filters to browse the results and confirm the export.

<Note>
  <img alt="Image showing customer information with invoices in QuickBooks Desktop." />

  *Image showing customer information with invoices in QuickBooks Desktop.*
</Note>

### Batch invoice export

1. Navigate to Accounting > Invoice to open the Batch Invoicing page.
2. On the **Released** tab, select the loads for which you want to generate invoices.
3. Confirm the customer and Invoice As subsidiary are correct for each selected load.

<Note>
  <img alt="Screenshot showing the Batch Invoicing page with loads selected." />

  *Screenshot showing the Batch Invoicing page with loads selected.*
</Note>

1. Click Generate Invoice to generate invoices and queue them for export, or click Create and Send to generate, queue, and email invoices to customers.
2. Open the QuickBooks Web Connector and click Update Selected.

### Summary invoice export

1. On the Loads Not Invoiced tab, select the loads to include. Confirm the subsidiary is correct before proceeding.
2. Generate the summary invoice. The transaction is queued on the Error Transactions page.
3. Open the QuickBooks Web Connector and click Update Selected.

<Note>
  <img alt="Screenshot showing a summary invoice in the QuickBooks Customer Center." />

  *Screenshot showing a summary invoice in the QuickBooks Customer Center.*
</Note>

### 2. Export a carrier bill

### Individual trip external carrier bill

1. Confirm the correct external carrier is assigned to the trip.
2. Verify the Tender As subsidiary on the load. For dual authority tenants: confirm the trip's operational mode is set to **Brokerage**. If the mode is **Carrier**, no external carrier bill will export.
3. If Generate Carrier Invoice Separately is enabled, upload a document categorized as Carrier Invoice to the trip before generating the customer invoice.
4. If this setting is not enabled, the carrier bill is exported automatically when the customer invoice is generated.
5. Open the QuickBooks Web Connector and click Update Selected.

<Note>
  <img alt="Screenshot showing a carrier bill in the QuickBooks Vendor Center." />

  \*Screenshot showing a carrier bill in the QuickBooks Vendor Center. \*
</Note>

### Carrier settlements bill export

The Carrier Settlements module provides brokers with tools to generate transparent and accurate carrier statements and settlement bills. This page can be accessed from the accounting section of Alvys under Carrier Settlements. Additional details about this module can be found in the [Carrier Settlements Help Center Article](/en/help/accounting-settlements/carrier-settlements).

When carrier settlements are used, the carrier bill is exported when a carrier statement is generated. To allow this export, the **Carrier Statements External Accounting** setting must be enabled for the subsidiary. If this setting is not enabled, no carrier bill will be exported when the statement is generated.

<Note>
  <img alt="Image showing carrier statements external accounting setting in QBD setup" />

  *Image showing carrier statements external accounting setting in QBD setup*
</Note>

If this setting is enabled and a user generates a customer invoice for an individual load with an external carrier, the carrier bill will not be exported from the load. In this scenario, the system expects the bill to be exported from the Carrier Settlements module when the statement is generated.

<Warning>
  ⚠️ Carrier Settlements payment sync limitation: payments applied in QuickBooks Desktop do not automatically sync back to Alvys. Record carrier payments manually in Alvys to keep your records accurate.
</Warning>

If an error occurs while exporting a carrier bill from the Carrier Settlements module, the error details are displayed directly within the module. Carrier statements cannot be re-sent from the Error Transactions page. All corrections must be made within the Carrier Settlements module, and the statement must be regenerated there.

For tenants that use the Carrier Settlements module but prefer carrier bills to export when the carrier invoice is uploaded on the trip, it is recommended not to enable the Carrier Statements external accounting setting. In this configuration, enabling the generate carrier invoice separately setting and uploading the carrier invoice to the trip then generating the customer invoice will trigger the carrier bill export.

### 3. Export driver bills

Driver bills export from the legacy Pay Drivers page (Accounting > Pay Drivers) or from the Driver Settlements module (Accounting > Driver Settlements). The subsidiary on the driver's profile determines which QuickBooks company receives the bill.

### 4. Export with shared billing

In the QBD accounting integration setup shared billing must be enabled on both the **Invoice As** subsidiary and the **Tender As** subsidiary. Each subsidiary must also have its own QuickBooks Desktop company connected. If shared billing is not enabled on both sides, intercompany transactions and carrier or vendor bills will not export correctly.

1. In the QBD integration settings for each subsidiary participating in shared billing, enable the Shared Billing option.

   <img alt="Screenshot showing the Shared Billing toggle in the QBD integration settings." />

   \*Screenshot showing the Shared Billing toggle in the QBD integration settings. \*
2. On the load, assign different subsidiaries to Invoice As and Tender As.

<Note>
  <img alt="Image showing Invoice as and Tendering As fields on load details page" />

  \*Image showing Invoice as and Tendering As fields on load details page \*
</Note>

1. Generate the customer invoice. This triggers the shared billing export.
2. After export, both subsidiary companies receive appropriate intercompany entries.
3. Open the QuickBooks Web Connector and click Update Selected.

   \*\*Transactions created during export: \*\*

   **Invoice As subsidiary (Alvys Motor Company):**

   * An intercompany bill is created to the Tender As subsidiary (Alvys Motor 2)
   * A customer invoice is created, and export is initiated to QBD.

     **Tender As subsidiary (Alvys Motor 2 Company):**
   * An intercompany invoice is created back to the Invoice As subsidiary (Alvys Motor).
   * A vendor bill is created for the external carrier or driver (when paystub is generated) on the trip

<Note>
  <img alt="Screenshot showing the intercompany entries in Error Transactions Page" />

  *Screenshot showing the intercompany entries in Error Transactions Page*
</Note>

### 5. Modify a previously exported transaction

Alvys is the system of record for all exported accounting transactions. All corrections must be made in Alvys and re-synced to QuickBooks Desktop.

### Customer invoices — auto-syncing fields

The following fields update QuickBooks Desktop automatically without invoice regeneration: customer linehaul amount, customer fuel surcharge, accessorial charges (added, edited, or removed), and Invoice Date. Make the changes in Alvys, then run the Web Connector.

### To change the customer on an exported invoice:

1. In the Load Details section, click the Change Customer button.
2. Select the correct customer and save.
3. Regenerate the invoice in Alvys.
4. Open the Web Connector and click Update Selected.

<Note>
  <img alt="Screenshot showing the Change Customer button on a load." />

  *Screenshot showing the Change Customer button on a load.*
</Note>

### To change the Invoice As subsidiary after export:

1. In Load Details, click the Invoice Customer As dropdown and select the correct subsidiary.
2. Regenerate the invoice.
3. Open the Web Connector and click Update Selected.
4. Manually delete the original invoice in the previous subsidiary's QuickBooks company.

<Note>
  <img alt="Screenshot showing the Invoice Customer As dropdown on a load." />

  *Screenshot showing the Invoice Customer As dropdown on a load.*
</Note>

### To modify a summary invoice:

In Alvys, the **only supported mechanism** for adding or removing loads from a summary invoice is to **revert the summary invoice**. A summary invoice can be reverted **only when its status is “Processed”**. If the invoice has already been **Sent** or **Paid**, further modification requires intervention from [Alvys Support.](mailto:support@alvys.com)

<Warning>
  ⚠️ Reverting a summary invoice does **not update the original invoice in QuickBooks Desktop (QBD)**. After reverting, the user must **generate a new summary invoice in Alvys**. This new invoice will receive a **new summary invoice number**, which will be exported to QBD. The old summary invoice remains in QBD unless manually deleted.
</Warning>

* Revert the summary invoice by navigating to the **All-Invoices** tab in Alvys.
* Locate the invoice and Click the **Delete** icon for the specific summary invoice.

  <img alt="Image showing delete icon for summary invoice" />

  *Image showing delete icon for summary invoice*
* Navigate to the **Loads Not Invoiced** tab.
* Select the loads to be included in the new summary invoice.
* Regenerate the summary invoice.
* Open the **QuickBooks Desktop Connector** and pull in the updates to export the new summary invoice to your company file.
* Confirm that the new summary invoice and the updated total amount are accurately reflected under the customer’s account in QuickBooks Desktop.
* Locate the old summary invoice in QuickBooks Desktop and manually delete it to avoid duplicate records and inaccurate aging reports.

## FAQs

**Q: Does appearing on the Error Transactions page mean my export failed?**

**A:** Not necessarily. All transactions are initially held in a queued state on this page (shown as a dash). This means Alvys is waiting for the QuickBooks Web Connector to run. Once the connector syncs, the transactions clear from this page.

**Q: How does Alvys match customers and vendors in QuickBooks?**

**A:** Alvys first searches for an exact match using the External Accounting Name. If no match is found, it uses the standard Customer or Carrier Name. If no record exists in QuickBooks Desktop, Alvys automatically creates a new customer or vendor.

**Q: Can I update an invoice after it has already been exported to QuickBooks Desktop?**

**A:** Yes, provided the invoice is still open (not fully paid). Changes to linehaul, fuel surcharges, and accessorials sync automatically the next time you run the Web Connector. For other changes, regenerate the invoice in Alvys first.

**Q: Does Alvys sync carrier payments from QuickBooks Desktop back to Alvys?**

**A:** No. Record carrier payments manually in Alvys to keep your records accurate.

**Q: Why isn't my external carrier bill exporting?**

**A:** Check that the trip is in **Brokerage** mode (for dual authority setups), and that a Carrier Invoice document is uploaded if Generate Carrier Invoice Separately is enabled.

## Go Deeper

* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)
* [QuickBooks Desktop Integration Collection](/en/help/integrations/quickbooks-desktop-integration-collection)
* [Summary Invoicing](/en/help/accounting-settlements/how-to-use-summary-invoicing)
* [Carrier Settlements](/en/help/accounting-settlements/carrier-settlements)
* [Driver Settlements](/en/help/accounting-settlements/driver-settlements-faq)


# QuickBooks Online: Account mappings
Source: https://docs.alvys.com/en/help/integrations/how-to-map-accounts-for-quickbooks-online

Map Alvys transaction line items — loads, trips, accessorials, e-checks, deductions, fuel, tolls, and escrow — to QuickBooks Online Chart of Accounts.

<Note>
  Account mappings connect Alvys transaction line items to specific accounts in your QuickBooks Online Chart of Accounts. This article explains how to configure both default fallback accounts and specific mappings for loads, trips, accessorials, e-checks, deductions, fuel, tolls, and escrow liability.
</Note>

## Overview

Account mappings (also called account assignments) tell Alvys which QBO account to post each type of transaction line item to when exporting. Each mapping has two levels: a default account that applies when no specific mapping is configured, and specific mappings that override the default for particular load types, trip types, accessorials, or other line items.

If a line item does not have a specific mapping, Alvys falls back to the default account for that category. If neither a specific nor a default mapping exists, the export will fail for that transaction.

## Before You Start

Before configuring account mappings:

* Confirm the QuickBooks Online integration is connected. If not, complete [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys) first.
* Confirm your QBO Chart of Accounts includes all accounts you intend to map to. Alvys displays the accounts available in your connected QBO file; if an account is missing, add it in QBO first and then return to this page.
* You need the **"CompanyProfileManager"** permission to configure account mappings. This permission is available to users with the Admin, Support, or Partner Admin role.

## Steps

Open the integrations settings.

Navigate to Management > Integrations and open the QuickBooks Online settings.

Locate the Account Mappings section.

Scroll to the Account Mappings section within the QBO settings page.

<Note>
  <img alt="Screenshot showing the Account Mappings section in QuickBooks Online settings" />

  *Screenshot showing the Account Mappings section in QuickBooks Online settings*
</Note>

Set the default revenue account.

In the Revenue Mappings section, select the QBO income account that Alvys should use when no specific revenue mapping exists. This is typically your primary freight revenue or freight income account.

<Note>
  <img alt="Screenshot showing the default Revenue account and Accounts Receivable mapping fields in Alvys QBO settings." />

  \*Screenshot showing the default Revenue account and Accounts Receivable mapping fields in Alvys QBO settings. \*
</Note>

Set the default expense account.

In the Expense Mappings section, select the QBO expense account that Alvys should use when no specific expense mapping exists. This is typically your purchased transportation or carrier cost account.

Configure specific load type mappings.

Expand the Load Type Mappings section. For each load type used in your Alvys account (such as asset loads or brokerage loads), select the QBO income or expense account to post that load type's transactions to. If a load type does not have a specific mapping, Alvys uses the default accounts set in steps 3 and 4.

<Note>
  <img alt="Screenshot showing the Load Type Mappings section in Alvys QBO settings with load category and trip category account dropdown selectors." />

  *Screenshot showing the Load Type Mappings section in Alvys QBO settings with load category and trip category account dropdown selectors.*
</Note>

Configure accessorial mappings.

Expand the Accessorials section. For each accessorial charge used in your Alvys account (such as detention, fuel surcharges, or layover), assign a QBO income account for customer-facing accessorials and a QBO expense account for carrier-facing accessorials. Accessorials without a specific mapping post to the default revenue or expense account.

<Note>
  <img alt="Screenshot showing the Accessorials mapping section in Alvys QBO settings with revenue and expense account dropdowns for each accessorial type." />

  *Screenshot showing the Accessorials mapping section in Alvys QBO settings with revenue and expense account dropdowns for each accessorial type.*
</Note>

Configure e-check and deduction mappings.

Expand the Deductions and E-check sections. Assign QBO expense or liability accounts for driver e-checks and deduction line items that appear on driver settlements. These map to the accounts Alvys uses when exporting driver bills to QBO.

<Note>
  <img alt="Screenshot showing the E-Check and Deductions mapping sections in Alvys QBO settings." />

  *Screenshot showing the E-Check and Deductions mapping sections in Alvys QBO settings.*
</Note>

Configure fuel and toll mappings.

Expand the Fuel and Tolls sections. Assign QBO accounts for fuel advances and toll charges. These line items appear on driver settlements and carrier bills when applicable.

<Note>
  <img alt="Notion Image" />

  <img alt="Screenshot showing the Fuel and Tolls mapping sections in Alvys QBO settings." />

  *Screenshot showing the Fuel and Tolls mapping sections in Alvys QBO settings.*
</Note>

Configure escrow liability mappings.

If your operation holds escrow for drivers, expand the Escrow Liability section and assign the QBO liability account used to track funds held in escrow. This account receives the credit entry when escrow is deducted from a driver settlement.

<Note>
  <img alt="Screenshot showing the Escrow Liability mapping section in Alvys QBO settings." />

  *Screenshot showing the Escrow Liability mapping section in Alvys QBO settings.*
</Note>

Save the mappings.

Click **Save** at the bottom of the Account Mappings section. Alvys applies the saved mappings to all future exports. Existing exported transactions are not retroactively updated.

<Note>
  <img alt="Screenshot showing the Save button at the bottom of the Account Mappings section." />

  *Screenshot showing the Save button at the bottom of the Account Mappings section.*
</Note>

<Note>
  <img alt="Screenshot showing the green checkmark confirmation state after Account Mappings are saved successfully in Alvys." />

  * Screenshot showing the green checkmark confirmation state after Account Mappings are saved successfully in Alvys.\*
</Note>

## Result

After saving, Alvys uses the configured mappings for all QBO exports. Each transaction line item posts to its specific mapped account; line items without a specific mapping post to the applicable default account. If an export fails because a required mapping is missing, the transaction appears in the Error Transactions queue with an error indicating which account is missing.

## Troubleshooting

### A line item is posting to the wrong QBO account

Check whether a specific mapping exists for that line item type. If no specific mapping is found, Alvys uses the default account. Update the specific mapping or the default account to correct future exports. Transactions already exported must be corrected manually in QBO.

### An account I need is not appearing in the mapping dropdown

The dropdown shows accounts available in your connected QBO company file. If an account is missing, add it in QBO first, then return to Management > Integrations and refresh the account mappings page. The new account should now appear in the dropdown.

### Exports are failing with an account-related error

Open the Error Transactions queue at Management > Integrations > Error Transactions and review the error message. Errors referencing an invalid account type indicate that the QBO account type does not match the expected type for that line item (for example, an income account was assigned where an expense account is required). Correct the mapping and re-export the transaction.

## FAQs

**Q: What happens if I have a line item with no mapping configured?**

**A:** Alvys falls back to the default account for that line item category. If no default is set either, the export fails and the transaction appears in the Error Transactions queue.

**Q: Do I need to set specific mappings for every accessorial?**

**A:** No. Only set specific mappings for accessorials that should post to a different account than the default. All others will use the default revenue or expense account.

**Q: Can I update account mappings after transactions have already been exported?**

**A:** Yes. Updated mappings apply to all future exports. Transactions that have already been exported to QBO are not retroactively changed; those must be corrected manually in QBO if the original posting was incorrect.

**Q: What is the escrow liability mapping used for?**

**A:** The escrow liability mapping specifies which QBO liability account receives the credit entry when escrow is deducted from a driver settlement. It tracks funds your operation holds on behalf of drivers.

**Q: Is the Tax category mapping required?**

**A:** No. The Tax category is deprecated. Skip this step when configuring your QuickBooks Online account mappings.

**Q: What if I do not see the green checkmark after submitting?**

**A:** Verify that all required account fields have valid QBO account names mapped. If the checkmark does not appear, check that your QBO connection is active under Management > Integrations and reconnect if needed.

**Q: What happens if I update my Chart of Accounts in QuickBooks after setting up mappings?**

**A:** You will need to update your account mappings in Alvys to match. Go to Management > Integrations > QuickBooks Online and update any accounts that have changed.

**Q: How do Specific Account Mappings differ from default mappings?**

**A:** Default mappings apply to all line items in that category unless a Specific Account Mapping overrides them. Specific mappings let you assign a different QBO account for a particular line item type when the default does not apply.

**Q: Why are E-Check fees mapped to a Revenue account?**

**A:** E-Check fees are collected from the payer and recorded as income before the corresponding expense is deducted; mapping them to a Revenue account keeps your QBO ledger consistent with how Alvys processes the transaction.

**Q: Which QBO account type should be used for Escrow mappings?**

**A:** Map the Escrow asset account to a Bank or Other Current Asset account in QBO. Map the Escrow liability account to a Current Liability account to correctly reflect funds held in trust.

**Q: What if I do not have a specific account for Tolls or Fuel in QBO?**

**A:** You can map Tolls and Fuel to your general expense accounts. If no specific account is configured for those categories, Alvys falls back to the default account mapping.

## Go Deeper

* [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys)
* [How to Export and Manage Transactions in QuickBooks Online](/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online)
* [QuickBooks Online: Identifying and Resolving Failed Transactions](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)


# How to Monitor Webhook Deliveries
Source: https://docs.alvys.com/en/help/integrations/how-to-monitor-webhook-deliveries

Use the Delivery Logs panel on a webhook to see every delivery attempt, filter by outcome, read the error returned by your endpoint, and export the history.

<Note>
  Every webhook subscription keeps a log of its delivery attempts. Open a webhook from Settings and use the Delivery Logs panel to see what was sent, whether it arrived, and what your endpoint returned when it failed.
</Note>

## Overview

When Alvys sends an event to your webhook endpoint, the result is recorded. The **Delivery Logs** panel on a webhook's detail page shows each attempt with its outcome, so you can tell the difference between "Alvys never sent it" and "your endpoint rejected it" without asking anyone to check a server log.

A health indicator on the same page flags an endpoint that has started failing, which is usually the first sign that something changed on the receiving side — an expired certificate, a moved URL, a deploy that broke a handler.

Also known as: webhook logs, delivery history, webhook failures, webhook troubleshooting.

## Before You Start

* Your account needs the Alvys Public API enabled, and you need access to the **Webhooks** section under Settings.
* At least one webhook subscription must exist. Logs are recorded per subscription, so a webhook created today has no history yet.
* Delivery logs are retained according to the standard Alvys data retention policy. Export anything you need to keep for an audit trail.

## Steps

1. Open your webhook subscriptions.

   * Go to **Settings → API → Webhooks**.
   * The page lists the webhook subscriptions configured for your account.
2. Open the webhook you want to inspect.

   * Click the webhook to open its detail page.
   * The **Delivery Logs** panel opens alongside the webhook's configuration.
3. Read the delivery history.

   Each entry in the panel shows:

   * **Event type** — which event Alvys attempted to deliver.
   * **Status** — a badge reading Success, Failed, or Skipped.
   * **Timestamp** — when the attempt was made.
   * **Error message** — what your endpoint returned, shown only when the attempt failed.

   The list loads a page of entries at a time, so scroll or page through for older attempts.
4. Narrow the list to what you are investigating.

   * Use the status filter to show **All**, **Success**, **Skipped**, or **Failed**.
   * Filtering to Failed is the fastest way to see whether failures share one event type or one time window.
5. Export the history if you need it outside Alvys.

   * Use **Export .CSV** or **Export .JSON** at the bottom of the logs panel.

<Warning>
  The export covers the entries matching your **current filters and the pages already loaded** — not the entire history. Apply the status filter you want and load the range you need *before* exporting, or you will get a partial file.
</Warning>

## Result

You can see the outcome of every delivery attempt on the subscription, tell whether a failure came from Alvys or from your endpoint, and hand a developer an exported log instead of a description.

## Understanding the statuses

| Status      | What it means                                                                                                                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Success** | Alvys delivered the event and your endpoint accepted it.                                                                                          |
| **Failed**  | Alvys delivered the event and your endpoint returned an error. The error message column shows what it returned.                                   |
| **Skipped** | Alvys did **not** attempt delivery, because the subscription was disabled or paused at the moment the event was generated. This is not a failure. |

A run of **Skipped** entries almost always means the subscription was turned off — including automatically, after repeated failures. Check whether the webhook is still enabled before investigating the endpoint.

## Webhook health and automatic disabling

The webhook detail page shows a health indicator so you can spot a degrading endpoint at a glance rather than by reading the log.

If a webhook keeps failing, Alvys disables it automatically and emails your Partner Admins. Once that happens the subscription stops attempting deliveries, and subsequent events are recorded as Skipped. Fix the endpoint, then re-enable the subscription.

## Troubleshooting

### Every recent delivery shows Failed

1. Read the error message on one of the failed entries — it is what your endpoint returned, so it usually names the problem directly.
2. Confirm the endpoint URL on the webhook is still correct and reachable from outside your network.
3. Check whether the failures all start at the same timestamp. A clean cut-off usually points to a change on the receiving side rather than to Alvys.

### Deliveries show Skipped and nothing is arriving

1. Check whether the subscription is enabled. A paused or automatically disabled webhook records Skipped rather than attempting delivery.
2. Check with your Partner Admins for an email about the webhook being disabled after repeated failures.
3. Re-enable the subscription once the endpoint is fixed.

### The log is empty

1. Confirm the subscription has existed long enough for a matching event to have occurred.
2. Confirm the webhook is subscribed to the events you expect to see. No matching event means no delivery attempt, and so no log entry.

### An export is missing rows you can see on screen

Apply your filters and page through to load the entries you want first. The export only includes what your current filters and loaded pages cover.

## FAQs

**Q: Can I replay a failed delivery from this screen?**

**A:** Not currently. Export the failed entries and re-trigger the events from your own system.

**Q: Does a Skipped entry mean the delivery failed?**

**A:** No. Skipped means Alvys did not attempt the delivery at all, because the subscription was disabled or paused when the event was generated.

**Q: Will I be told when a webhook stops working?**

**A:** Yes. Partner Admins are emailed automatically when a webhook is disabled after repeated failures. The health indicator on the webhook's detail page also reflects its current state.

**Q: How far back do the logs go?**

**A:** Delivery logs follow the standard Alvys data retention policy. Export the logs you need to retain beyond that.

**Q: Does the export include the full history?**

**A:** No — only the entries matching your current filters and the pages you have loaded.

## Go Deeper

* [Alvys API](/en/help/integrations/alvys-api)


# Business Central: Prerequisites
Source: https://docs.alvys.com/en/help/integrations/how-to-prepare-business-central-before-connecting-to-alvys

Prepare Business Central for the Alvys accounting sync: company architecture, licensing, chart of accounts, posting groups, tax setup, journals, and 1099s.

<Note>
  Before connecting Alvys to Microsoft Dynamics 365 Business Central (also called BC, Microsoft BC, or BC setup), you must configure seven areas in your BC environment: company architecture, licensing and permissions, chart of accounts, posting groups, tax setup, journal batch configuration, and IRS 1099 setup (if applicable). Completing these steps in order ensures transactions sync accurately and prevents errors after the integration goes live.
</Note>

## Overview

Before you connect Alvys to Business Central, your BC environment must be configured (prepared) to receive and post data from Alvys. This article walks through seven prerequisite areas. Skipping or partially completing any of these areas can cause sync failures, "Out of Balance" invoice errors, or record-locking issues after the integration is active.

## Before You Start

**Required role:** Configuring the accounting integration in Alvys requires the **"CompanyProfileManager"** permission, available to users with the Admin, Partner Admin, or Support role.

**Prerequisites before beginning:**

* You have administrator or equivalent setup access in your Business Central environment.
* You have determined your organizational structure: whether each Alvys subsidiary maps to a separate BC company (Option A) or whether you are using the Binary Stream Multi-Entity Management (MEM) add-on with multiple legal entities sharing one BC database (Option B).
* The integration user account in BC has been created and is available for permission assignment.
* You are not yet live on the Alvys integration. Changing company architecture after the integration is active carries significant data reconciliation risk.

## Steps

1. Company Setup and Architecture.

The first and most critical step is defining how your organizational subsidiaries are structured in Business Central. Choose the option that matches your organizational structure.

**Option A: Separate Companies (standard BC setup)**

In this setup, each subsidiary is an independent environment with its own private data. Each Alvys subsidiary maps directly to its own Business Central company on a 1:1 basis. Transactions for one subsidiary cannot mix with another.

1. In the BC search bar, type **Companies** and select the link.
2. Select **New > Create New Company**.

For more information on creating companies in BC, see: [Create New Companies in Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/about-new-company)

During Alvys integration setup, select the target company name to link the correct subsidiary.

**Option B: Multi-Entity Management (MEM add-on)**

This option uses the Binary Stream Multi-Entity Management (MEM) extension, which allows multiple legal entities, subsidiaries, or branches to operate within a single BC company database. Each transaction is tagged with an Entity Code to identify the subsidiary.

1. Search for **Multi-Entity Management Setup** and confirm it is enabled.
2. Search for **MEM Entity Setup** and add each subsidiary as a new line.
3. Assign a Global Dimension (typically Dimension 1) to represent your entities.
4. Search for **MEM User Security Setup** and assign the User ID to every entity code that Alvys will use.

   For more information on the MEM extension, see: [Multi-Entity Management Overview (Binary Stream)](https://binarystream.com/multi-entity-management-in-microsoft-dynamics-365-going-beyond-the-business-central-core/)

   During Alvys integration setup with MEM: enable the **Subsidiary** checkbox, then manually link each Alvys subsidiary to the specific MEM Entity Code defined in BC.
5. Licensing and Permissions.

The integration user in BC requires a specific license type and a set of permissions to allow Alvys to read and write financial data.

**Licensing requirements**

Only full user licenses support the read/write API access required by Alvys. Supported license types are Dynamics 365 Business Central Essentials and Dynamics 365 Business Central Premium. A Team Member license is not supported: Microsoft restricts this license to read-only access for most financial tables. Alvys needs to write data (create sales invoices and purchase invoices), so a Team Member license cannot authorize the API connection.

**Permissions checklist**

The integration user must have access to: Login Access, Local Permission, Customers, Vendors, Items, Sales Invoices, Purchase Invoices, General Ledger Entries, and Dimensions.

**Recommended permission sets**

Add the following four permission sets to the integration user's User Card in BC:

1. **"D365 BUS FULL ACCESS"**: the primary set for full read/write/modify access to business data.
2. **"D365 AUTOMATION"**: required for allowing external API calls from Alvys to execute tasks in the background.
3. **"LOCAL"**: provides regional-specific database access required for posting logic.
4. **"LOGIN"**: the base set required to access the BC environment.

   **Configuration steps:**
5. In BC, search for **Users** and select the integration user.
6. Scroll to the **User Permission Sets** tab.
7. Add all four permission sets listed above.
8. Ensure the **Company** column is left blank so the permissions apply to all companies and entities.
9. Chart of Accounts.

   Alvys requires active General Ledger (G/L) accounts in BC to post revenue and expenses. These accounts must exist and be configured for direct posting before the first sync.
10. In BC, search for **Chart of Accounts**.
11. Select **New** to create accounts for Freight Revenue and Carrier Expense.
12. Set **Income/Balance** to **Income Statement** for revenue and expense accounts.
13. Ensure **Direct Posting** is toggled on so the API can post to these accounts.
14. Posting Groups.

    Posting groups are rules assigned to each customer or vendor that tell Business Central which account category to use when a transaction is posted. Even when Alvys sends a specific account, BC checks the posting group to confirm the transaction is valid.

    Configure posting groups for your customers and vendors before connecting the integration. For more information, see: [Setting Up Posting Groups](https://learn.microsoft.com/en-us/dynamics365/business-central/finance-posting-groups)
15. Tax Setup.

    Business Central calculates tax for the data sent by Alvys. Tax must be configured in BC before connecting; missing or incomplete tax configuration causes "Out of Balance" errors on invoices.
16. Search for **Tax Groups** and create a code (for example, TAXABLE).
17. Search for **Tax Areas** and define the regions where you operate.
18. Link the Tax Group and Tax Area to your Customer and Vendor cards under the **Invoicing** tab.
19. Journal Batch Setup.

    BC includes a native DEFAULT batch for general journals. Creating a dedicated ALVYS batch is strongly recommended, though not strictly required. A dedicated batch prevents record-locking conflicts with manual users and ensures clear traceability for all automated transactions posted by Alvys.
20. Search for **General Journal Batches**.
21. Select **New** and name the batch **ALVYS**.
22. Ensure a **No. Series** is assigned so BC can auto-generate document numbers.
23. Confirm the integration user account has explicit permission to post within this specific journal batch.
24. IRS 1099 Setup (US companies only).

    This step applies only to US companies that work with carriers subject to IRS 1099 reporting. If this does not apply to your organization, skip this step.
25. Search for **1099 Form Boxes** and ensure codes such as NEC-01 are active.
26. Open the **Vendor Card** for the applicable carrier and navigate to the **Payments** tab.
27. Select the correct code in the **IRS 1099 Code** field.

## Result

After completing all applicable steps, your Business Central environment is ready to connect to Alvys. You will have:

* A confirmed company architecture (separate companies or MEM) with subsidiaries configured.
* An integration user with the correct license and all four permission sets assigned.
* G/L accounts active and set to allow direct posting.
* Posting groups configured for your customers and vendors.
* Tax Groups and Tax Areas defined and linked to customer and vendor cards.
* A dedicated ALVYS journal batch (recommended) with a No. Series assigned.
* IRS 1099 codes configured on vendor cards (if applicable).

You can now proceed to connection and settings configuration in Alvys under Management > Integrations.

## Troubleshooting

### Permission set error when syncing an invoice

This error occurs when the **"D365 AUTOMATION"** or **"D365 BUS FULL ACCESS"** permission sets are missing from the integration user, or when the **Company** column on the User Card is not left blank.

**Step 1:** Search for **Users** in BC and open the integration user's record.

**Step 2:** Scroll to the **User Permission Sets** tab and verify that **"D365 BUS FULL ACCESS"**, **"D365 AUTOMATION"**, **"LOCAL"**, and **"LOGIN"** are all listed.

**Step 3:** Check the **Company** column for each permission set. If a company name is listed, clear it so the permissions apply to all entities.

**Step 4:** Re-attempt the sync from Alvys (Management > Integrations > select the Business Central integration > sync).

If the error persists after all four sets are assigned with a blank Company field, contact Alvys support and provide the exact error message.

### Out of Balance error on invoices

This error occurs when the tax calculated by Business Central differs from the total sent by Alvys, most commonly because Tax Groups or Tax Areas are not configured or are not linked to the customer or vendor card.

**Step 1:** Search for **Tax Groups** in BC and confirm at least one code (for example, TAXABLE) is active.

**Step 2:** Search for **Tax Areas** and confirm the regions where you operate are defined.

**Step 3:** Open the **Customer Card** or **Vendor Card** for the affected record and navigate to the **Invoicing** tab. Confirm a Tax Group and Tax Area are assigned.

**Step 4:** Re-attempt the sync from Alvys.

If the error persists after tax configuration is confirmed, contact Alvys support and provide the affected customer or vendor name.

### Record-locking errors on journal entries

This error occurs when the DEFAULT general journal batch is in use by a manual user at the same time Alvys attempts to post an automated entry.

**Step 1:** Search for **General Journal Batches** in BC.

**Step 2:** Confirm an **ALVYS** batch exists. If it does not, create it per step 6 above.

**Step 3:** Confirm the integration user has permission to post to the ALVYS batch.

**Step 4:** In Alvys, go to Management > Integrations > select the Business Central integration > confirm the journal batch is set to ALVYS rather than DEFAULT.

If record-locking errors continue after switching to a dedicated batch, contact Alvys support.

### Integration user cannot log in to BC

This error occurs when the **"LOGIN"** permission set is missing or when the integration user's account does not have access to the specific BC company being integrated.

**Step 1:** Search for **Users** in BC and open the integration user.

**Step 2:** Confirm the **"LOGIN"** permission set is listed under **User Permission Sets** with a blank Company column.

**Step 3:** Confirm the user has access to the target company. If using MEM, confirm the user is assigned to all relevant entity codes in **MEM User Security Setup**.

If the user still cannot log in after permissions are confirmed, contact Alvys support.

## FAQs

**Q: How do I know whether to use Separate Companies or Multi-Entity Management (MEM)?**

**A:** Use Separate Companies if each subsidiary operates independently with its own accounting, users, and reporting. Use MEM if you want multiple legal entities operating inside one shared environment with centralized users and reporting. If you are using the Multi-Entity Management extension by Binary Stream, you must configure each Alvys subsidiary to map to a specific MEM Entity Code during Alvys setup.

**Q: Can I switch from Option A (Separate Companies) to Option B (MEM) after the integration is live?**

**A:** Switching architectures after the integration is live requires a full re-mapping of all entities, customers, and vendors, and can lead to significant data reconciliation issues in your General Ledger. Finalize your organizational structure in BC before connecting Alvys.

**Q: Does Alvys support asset dimensions if I am not using the MEM add-on?**

**A:** Yes. Even in a standard 1:1 company setup, you can still map Alvys assets to BC Dimensions (such as trucks or drivers) for granular reporting. You will not need a Subsidiary dimension to identify the legal entity itself, because the ledger is already entity-specific.

**Q: I have a Team Member license; why can't I use it for the integration?**

**A:** Microsoft restricts Team Member licenses to read-only access for most financial tables. Because Alvys needs to write data (create Sales Invoices and Purchase Invoices), a Business Central Essentials or Premium license is required to authorize the API connection.

**Q: Do I really need a dedicated ALVYS General Journal Batch?**

**A:** While you can use the DEFAULT batch, a dedicated ALVYS batch prevents record-locking errors. If a user has the DEFAULT batch open while Alvys attempts to post an automated entry, the transaction may fail. A separate batch provides a clean lane for API traffic.

**Q: How does Alvys handle sales tax?**

**A:** Alvys sends the line-item data, but Business Central is the source of truth for tax calculations. You must have Tax Groups and Tax Areas configured in BC. If the tax calculated by BC differs from the total sent by Alvys, the invoice may sit in an Out of Balance status.

**Q: Are all Chart of Accounts and companies required to be set up before exporting transactions?**

**A:** Yes. Your G/L accounts, Posting Groups, and Dimensions must be fully configured in BC before the first sync. Alvys cannot post to an account or a company that does not yet exist in the BC environment.

## Go Deeper

* [How to connect Business Central to Alvys and configure settings](/en/help/integrations/how-to-connect-business-central-to-alvys-and-configure-settings)
* [Business Central Integration Collection](/en/help/integrations/business-central-integration-collection)


# NetSuite: Prerequisites
Source: https://docs.alvys.com/en/help/integrations/how-to-prepare-netsuite-before-connecting-to-alvys

Prepare NetSuite for the Alvys integration: enable SuiteTalk REST, create the integration role and user, and generate Token-Based Authentication keys.

<Note>
  Before connecting Alvys to NetSuite, your NetSuite environment must be properly prepared: the correct features, roles, users, and credentials must be configured, or the integration will fail to authenticate or export transactions.
</Note>

### Overview

Before configuring (setting up) the Alvys and NetSuite integration, your NetSuite environment must be properly prepared. Most integration failures result from misconfigured features, roles, users, or improper subsidiary access.

Alvys connects to NetSuite using **Token-Based Authentication (TBA)** through **SuiteTalk REST Web Services**. This secure authentication method allows encrypted API communication without storing user credentials. OAuth 2.0 is not used.

### Before You Start

**Required role:** Configuring the accounting integration in Alvys requires the **"CompanyProfileManager"** permission, available to the Admin, Partner Admin, or Support role. On the NetSuite side, a NetSuite Administrator (or a role with equivalent permissions) is needed only during setup to enable features, create roles, and generate tokens.

**Prerequisites:**

* An active NetSuite account with Administrator-level access
* Access to Setup, Users/Roles, and Integrations in NetSuite
* If your organization uses NetSuite OneWorld, all subsidiaries must be created and configured before starting

<Info>
  💡 **Important:** Do not use your personal Administrator login for the live integration. During setup you will create a dedicated integration role and user specifically for Alvys. Your Administrator account is used only to prepare the system, not to run the integration long-term.
</Info>

### Steps

#### Enable required NetSuite features

The required features are: REST Web Services, SOAP Web Services, Token-Based Authentication (TBA), and SuiteScript.

**Required Features**

* **REST Web Services** – Allows NetSuite to share data with Alvys
* **SOAP Web Services** – Recommended to ensure compatibility with all supported record types
* **Token-Based Authentication (TBA)** – Allows secure system access without using a password
* **SuiteScript** – While Alvys does not deploy custom scripts in your account, SuiteScript is required for NetSuite’s REST and SOAP Web Services to function properly, including internal searches and record queries executed by the integration.

  <Info>
    💡 **Important:** OAuth 2.0 is not required for this integration. Alvys authenticates exclusively using Token-Based Authentication (TBA).
  </Info>

1. Log in to NetSuite using your administrator account.
2. Navigate to **Setup > Company > Enable Features**.

   <img alt="NetSuite menu: Setup > Company > Enable Features" />

   *NetSuite menu: Setup > Company > Enable Features*
3. Open the **SuiteCloud** tab.

   <img alt="Selecting the SuiteCloud tab" />

   *Selecting the SuiteCloud tab*
4. In the **SuiteTalk (Web Services)** section, enable **SOAP Web Services** and **REST Web Services**.

<Note>
  <img alt="SuiteTalk (Web Services) section" />

  *SuiteTalk (Web Services) section*

  <img alt="SOAP and REST Web Services enabled" />

  *SOAP and REST Web Services enabled*
</Note>

1. In the **Manage Authentication** section, enable **Token-Based Authentication (TBA)**.

   <img alt="Enabling Token-Based Authentication" />

   *Enabling Token-Based Authentication*
2. In the **SuiteCloud** tab, locate **SuiteScript** and enable it.

   <img alt="Enabling Client and Server SuiteScript" />

   *Enabling Client and Server SuiteScript*
3. Click **Save**.

<Warning>
  **Important:** Missing any of these features may cause authentication failures or prevent transaction data from being exported correctly.
</Warning>

#### Create a dedicated integration role

A dedicated role separates automated API access from human administrator accounts and restricts permissions to only what is necessary.

1. Navigate to **Setup > Users/Roles > Manage Roles**, then click **New**.

   <img alt="Creating a new role under Manage Roles" />

   *Creating a new role under Manage Roles*
2. Enter a descriptive name such as **"Alvys Integration Role"**.
3. Assign **Subsidiary Access**: if using OneWorld, assign access to all subsidiaries used in Alvys and enable **Cross-Subsidiary Record Viewing**.

   <img alt="Setting subsidiary access and cross-subsidiary viewing" />

   *Setting subsidiary access and cross-subsidiary viewing*
4. Optionally, restrict the role to **Web Services Only** to prevent login through the NetSuite interface.

   <img alt="Restricting the role to Web Services Only" />

   *Restricting the role to Web Services Only*
5. Click **Save**.

#### Assign permissions to the integration role

**Setup permissions** (all Full Access unless noted):

REST Web Services, SOAP Web Services, Login Using Access Tokens, SuiteScript, Accounting Lists, Custom Fields, Custom Item Fields, Custom Body Fields, Custom Column Fields, Custom Transaction Fields, Custom Entity Fields, Custom Record Types, Custom Segments, Custom Lists, Other Lists, Deleted Records, Manage Accounting Periods (View), Financial Institution Records

<Note>
  <img alt="Setup permissions tab on the role" />

  *Setup permissions tab on the role*
</Note>

**Transaction permissions** (all Full Access):

Invoice, Bills, Customer Payments, Pay Bills, Vendor Credits, Credit Memos, Customer Deposit, Make Journal Entry

<Note>
  <img alt="Transactions permissions tab on the role" />

  *Transactions permissions tab on the role*
</Note>

**Important:** If any transaction permissions are missing, exports may fail even if authentication is successful.

<Note>
  **List permissions:**

  Accounts (Full), Address List in Search (Full), Contacts (Full), Customers (Full), Vendors (Full), Employees (View), Employee Record (View), Expense Categories (Full), Payment Methods (Full), Currency (Full), Items (Full), Perform Search (Full), Custom Record Entries (Full), Classes (Full), Departments (Full), Locations (Full), Subsidiaries (View), Contact-Subsidiary relationship (View), Companies (Full), Tax Records (View), Documents and Files (Full)
</Note>

<img alt="Lists permissions tab on the role" />

*Lists permissions tab on the role*

#### Create a dedicated integration user

1. Navigate to **Lists > Employees**, then select **New** (or choose an existing service account).

   <img alt="Creating the integration user (Lists > Employees > New)" />

   *Creating the integration user (Lists > Employees > New)*
2. Assign the **Alvys Integration Role** under the Roles section.

   <img alt="Assigning the Alvys Integration Role to the user" />

   *Assigning the Alvys Integration Role to the user*
3. Click **Save**.

<Note>
  💡 Admin account: used only to enable features, create roles, create integration records, and generate tokens. The dedicated integration user (employee record or service account) is used by Alvys to authenticate via REST/TBA.
</Note>

#### Generate integration credentials

Alvys requires five credentials: Account ID, Consumer Key, Consumer Secret, Token ID, Token Secret.

**Locate your Account ID:** In the NetSuite URL before "[app.netsuite.com](http://app.netsuite.com/)." Example: in `https://123456.app.netsuite.com`, the Account ID is **123456**. Sandbox accounts include a suffix such as "\_SB1."

**Create the integration record:**

1. Navigate to **Setup > Integrations > Manage Integrations**, then click **New**.

   <img alt="Creating a new integration record (Manage Integrations > New)" />

   *Creating a new integration record (Manage Integrations > New)*
2. Enter a descriptive name such as **"Alvys TMS Integration"**.
3. Enable **Token-Based Authentication**.

   <img alt="Enabling Token-Based Authentication on the integration" />

   *Enabling Token-Based Authentication on the integration*
4. Click **Save**.
5. Copy the **Consumer Key** and **Consumer Secret**.

   <Warning>
     ⚠️ **Important:** The Consumer Key and Consumer Secret are displayed only once. Store them securely.
   </Warning>

   **Generate access tokens:**
6. Go to **Setup > Users/Roles > Access Tokens**, then click **New**.

   <img alt="Creating a new access token (Access Tokens > New)" />

   *Creating a new access token (Access Tokens > New)*
7. Select:

   * **Application Name:** "Alvys TMS Integration"
   * **User:** the dedicated integration user
   * **Role:** the dedicated integration role
8. Click **Save**.
9. Copy the **Token ID** and **Token Secret**.

<Warning>
  ⚠️ **Important:** The Token ID and Token Secret are displayed only once.
</Warning>

#### Confirm a complete Chart of Accounts

All required income, expense, asset, liability, and clearing accounts must exist before exporting transactions. See Oracle documentation: [Creating Accounts](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1440518.html).

1. Log in with a role that has accounting permissions.
2. Go to **Lists > Accounting > Accounts**, then click **New**.
3. Select the account **Type**.
4. Enter the **Account Name**.
5. If using account numbers, enter a number (account numbering must be enabled under **Setup > Accounting > Accounting Preferences**).
6. Optionally assign a parent account or subsidiary (for OneWorld users).
7. Click **Save**.

<Warning>
  ⚠️ **Important:** All required accounts must be created before pushing transactions from Alvys.
</Warning>

#### Configure subsidiaries (OneWorld accounts only)

See Oracle documentation: [Creating Subsidiary Records](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N272471.html).

**To create a subsidiary:**

1. Navigate to **Setup > Company > Subsidiaries**.
2. Click **New**.
3. Enter the **Name** of the subsidiary.
4. Assign a **Base Currency**.
5. Select the **Parent Subsidiary** if applicable.
6. Assign a **Chart of Accounts**.
7. Complete tax settings.
8. Click **Save**.

   **To assign the Alvys Integration Role access to the subsidiary:**
9. Go to **Setup > Users/Roles > Manage Roles** and select the Alvys Integration Role.
10. Click **Edit**.
11. Find the **Subsidiary Access** section.
12. Set access to **All** (recommended) or select only the subsidiaries used in Alvys.
13. Enable **Cross-Subsidiary Record Viewing**.
14. Click **Save**.

### Result

Your NetSuite environment is ready to connect to Alvys. You have enabled required features, created a dedicated role with the required permissions, created a dedicated integration user, generated all five credentials, confirmed your Chart of Accounts, and (if using OneWorld) configured subsidiary access.

Proceed to enter these credentials in **Management > Integrations**.

### Troubleshooting

#### Integration fails to authenticate

**Step 1:** Confirm that REST Web Services, SOAP Web Services, Token-Based Authentication, and SuiteScript are all enabled under **Setup > Company > Enable Features > SuiteCloud**.

**Step 2:** Confirm the integration record has Token-Based Authentication enabled under **Setup > Integrations > Manage Integrations**.

**Step 3:** Confirm the Consumer Key, Consumer Secret, Token ID, and Token Secret were copied correctly. If any value was lost, regenerate the credentials.

**Step 4:** Confirm the token was created with the correct Application Name, User, and Role.

#### Transaction exports fail after successful authentication

**Step 1:** Confirm the integration role includes all required Transaction permissions with Full access.

**Step 2:** Confirm all required Setup and List permissions are present.

**Step 3:** Confirm role permissions have not been modified since the token was generated.

**Step 4:** Confirm all required accounts exist in the Chart of Accounts.

#### Transactions fail for a specific subsidiary

**Step 1:** Confirm the Alvys Integration Role has access to that subsidiary under **Setup > Users/Roles > Manage Roles > \[Alvys Integration Role] > Subsidiary Restrictions**.

**Step 2:** Confirm **Cross-Subsidiary Record Viewing** is enabled.

**Step 3:** Confirm the subsidiary has a Base Currency and Chart of Accounts assigned.

#### Token was lost after creation

Delete the existing integration record or access token and repeat the credential generation step. Update Alvys with the new credentials.

<Warning>
  ⚠️ Common causes of integration failures: required features not enabled, token created under the wrong role, missing transaction or list permissions, subsidiary not assigned to the role, role permissions modified after token generation, or required accounts not created in NetSuite. Any of these will cause authentication or export failures.
</Warning>

## FAQs

**Q: What level of NetSuite access is required to set up the Alvys integration?**

**A:** An Administrator-level account is required only during setup. The integration itself uses a dedicated integration user.

**Q: Can I use my personal Administrator login for the live integration?**

**A:** No. A dedicated integration user and role must be created to separate API access from human accounts.

**Q: Which NetSuite features must be enabled for Alvys to connect?**

**A:** REST Web Services, SOAP Web Services, Token-Based Authentication (TBA), and SuiteScript must all be enabled. OAuth 2.0 is not required.

**Q: What happens if required NetSuite features are not enabled?**

**A:** Missing features can cause authentication failures or prevent transaction data from being exported correctly.

**Q: What permissions are required for the integration role?**

**A:** The role requires permissions across Setup, Transaction, and List categories, including full access to Web Services, SuiteScript, accounting lists, customers, vendors, items, and all relevant transaction types.

**Q: Should the integration role be restricted to Web Services only?**

**A:** Yes. This enhances security by preventing login through the NetSuite interface.

**Q: How do I create the integration user?**

**A:** Create a new employee record (or use a service account) and assign the dedicated integration role.

**Q: What credentials does Alvys require to connect to NetSuite?**

**A:** Account ID (Realm ID), Consumer Key, Consumer Secret, Token ID, and Token Secret.

**Q: Where can I find my NetSuite Account ID / Realm ID?**

**A:** The Account ID is in the NetSuite URL before "[app.netsuite.com](http://app.netsuite.com/)." Sandbox accounts include a suffix such as "\_SB1."

**Q: Can tokens be regenerated if lost?**

**A:** Yes, but you must regenerate them in NetSuite. Each value is shown only once at time of creation.

**Q: Are all Chart of Accounts and subsidiaries required before exporting transactions?**

**A:** Yes. All required accounts must exist and subsidiaries must be fully configured before exporting.

**Q: What are common causes of integration failures?**

**A:** Required features not enabled, tokens created under the wrong role, missing transaction or list permissions, subsidiaries not assigned to the role, role permissions modified after token generation, or required accounts not created in NetSuite.

**Q: Is SuiteScript required for the integration?**

**A:** Yes. SuiteScript must be enabled to allow NetSuite's REST and SOAP Web Services to function properly.

**Q: Can I limit the integration role to selected subsidiaries?**

**A:** Yes, but all subsidiaries used in Alvys must be included; otherwise, transaction exports to those subsidiaries will fail.

**Q: Does the integration support OAuth 2.0 authentication?**

**A:** No. Alvys uses only Token-Based Authentication (TBA) via SuiteTalk REST Web Services.

### Go Deeper

* [NetSuite: Authentication and Settings Configuration in Alvys](/en/help/integrations/netsuite-authentication-and-settings-configuration-in-alvys)
* [NetSuite Integration Collection](/en/help/integrations/netsuite-integration-collection)


# QuickBooks Desktop: Prerequisites
Source: https://docs.alvys.com/en/help/integrations/how-to-prepare-quickbooks-desktop-before-connecting-to-alvys

Prepare QuickBooks Desktop for Alvys: verify Windows and QBD version, install the Web Connector, and ready your company file and Chart of Accounts for sync.

<Note>
  Before connecting Alvys to QuickBooks Desktop, your accounting team must verify that four software components are present in the correct environment, and that your QuickBooks company file and Chart of Accounts are ready to receive mapped transactions.
</Note>

## Overview

Connecting Alvys to QuickBooks Desktop requires four separate components working together in the same environment. Skipping any preparation task will cause the connection to fail or produce sync errors after the first authorization.

This article covers understanding the four required components, choosing the setup type that matches your office environment, verifying software compatibility, and preparing your QuickBooks company file and Chart of Accounts before you begin. These steps are Windows-only; the QuickBooks Desktop integration is not available on Mac.

## Before You Start

**Required role:** **"Admin"**, **"Partner Admin"**, or **"Support"** (requires the **"CompanyProfileManager"** permission)

**Prerequisites:**

* Windows operating system: QuickBooks Desktop runs on Windows only
* QuickBooks Desktop installed on the machine that will handle syncing
* Administrator access to that Windows machine
* An active QuickBooks company file (.QBW) for the subsidiary you plan to integrate

## Steps

**Before you begin:** While this guide mentions several software components, you do not need to download or install anything yet. All necessary installation links and files are provided step-by-step in the next article: How to connect QuickBooks Desktop to Alvys and configure settings.

1. **Understand the four integration components.** The QuickBooks Desktop integration uses four components that must all be present in the same environment:

   * **QuickBooks Desktop (QBD)** is the accounting application installed on your Windows machine. It holds your Chart of Accounts, customer and vendor records, and all financial transactions.
   * **QuickBooks Web Connector (QBWC)** is a background application that bridges Alvys and QuickBooks Desktop. It is typically installed automatically when you install QuickBooks Desktop. If it is not installed, download it from Intuit's support site.
   * **Web Connector configuration file (QWC)** is a file Alvys generates for each subsidiary you integrate. It tells the Web Connector the Alvys application name, your unique owner ID, and the identifier for your company file. You download this file from Alvys during setup.
   * **QuickBooks company file (QBW)** is the database that stores all company data, including your Chart of Accounts. This is the file QuickBooks opens when you log in.

All four must be in the same environment. If any one of them is elsewhere, syncing will not work.

<Note>
  <img alt="Notion Image" />
</Note>

1. **Choose your setup type.** Three setup types are supported. Identify which applies to your office before proceeding.

   * **Single-user (local desktop):** One person uses QuickBooks on a single Windows computer. QuickBooks Desktop, the Web Connector, and the company file all live on that machine. This is the simplest configuration.
   * **Multi-user (office network):** Multiple users share one company file stored on a central server or shared drive. Install the Web Connector on the machine that hosts the company file, not on individual workstations. Alvys syncs through that host machine.
   * **Remote desktop or cloud-hosted (for example, Rightworks or Ace Cloud):** QuickBooks is hosted remotely and accessed via a remote desktop session. Upload both the Web Connector and the QWC file to the remote environment. The company file must be open in that remote session during initial connection.

     <img alt="Notion Image" />
2. **Verify software compatibility.** Before downloading the QWC file from Alvys, confirm the following:

   * **Supported QuickBooks Desktop editions:** Enterprise, Plus, Accountant, Premier, or Pro. To check your edition, open QuickBooks Desktop and press F2 (or Fn + F2) to open the Product Information window.
   * **Windows administrator rights:** Your Windows account on the sync machine must have administrator rights. Without them, you cannot authorize the Web Connector connection.
   * **Single User Mode:** When you add the QWC file to the Web Connector during setup, QuickBooks must be in Single User Mode and the company file must be open. Multi-User Mode blocks the authorization prompt from appearing.

     <img alt="Notion Image" />
3. **Prepare your QuickBooks company file.**
4. Open QuickBooks Desktop on the designated sync machine.
5. Open the company file (.QBW) you plan to integrate with Alvys.
6. Confirm the correct company name appears at the top of the QuickBooks window.
7. Go to File > Switch to Single-user Mode if the option is available.
8. If you have multiple subsidiaries in Alvys, each requires its own separate integration setup. Open each subsidiary's company file separately when setting up that subsidiary.

If you do not yet have a QuickBooks company file, create one first: Launch QuickBooks Desktop and click **Create a new company** from the **No Company Open** window. If a file is already open, go to **File** > **New Company**. Select **Express Start** to get started quickly or **Detailed Start** for a complete setup. Enter your company name, select **Transportation/Trucking** as the industry (this pre-configures a Chart of Accounts suited for trucking), and select your business type (for example, LLC, S-Corp, or Corporation). Click **Create Company** and save when prompted.

<Note>
  <img alt="Notion Image" />
</Note>

1. **Verify your Chart of Accounts.** Alvys maps transactions to accounts in your QuickBooks Chart of Accounts during the configuration wizard. Accounts that do not exist in QuickBooks cannot be selected during mapping, so create any missing accounts before starting. At minimum, your Chart of Accounts must include:

   * **Accounts Receivable:** for customer invoices
   * **Accounts Payable:** for carrier and driver bills
   * **Income:** at least one income account for revenue transactions
   * **Expense:** at least one expense account for cost transactions

If your company uses account numbers in QuickBooks, enable them before mapping: go to Edit > Preferences > Accounting > Company Preferences and check **Use account numbers**. Account numbers must be enabled before you begin mapping in Alvys.

If you have subaccounts, select the **Show lowest subaccount only** checkbox. This shortens the subaccount details when you use it in your transactions.

To add a missing account to your Chart of Accounts, follow these steps in QuickBooks Desktop:

1. Select the **Company**, **Lists**, or **Accountant** menu, then select **Chart of Accounts**.
2. From the **Account** dropdown, select **New**.
3. Select an account type, then select **Continue**.
4. Complete the account details.
5. Select **Save & Close**.

<Note>
  <img alt="Notion Image" />
</Note>

## Result

When all five steps are complete, your QuickBooks environment is ready for connection. Proceed to "How to connect QuickBooks Desktop to Alvys and configure settings" to download the QWC file, authorize the Web Connector, and configure your integration settings.

## Troubleshooting

### Authorization prompt does not appear when adding the QWC file

**Step 1:** Confirm QuickBooks Desktop is open and you are logged in as the Admin user.

**Step 2:** Confirm QuickBooks is in Single User Mode. Go to File > Switch to Single-user Mode if the option is available.

**Step 3:** Check your Windows taskbar for a minimized or background QuickBooks window containing the authorization prompt.

**Step 4:** If the prompt still does not appear, close and reopen QuickBooks, then retry adding the QWC file.

### Cannot see the Alvys Integrations page

**Step 1:** Confirm your user role is **"Admin"**, **"Partner Admin"**, or **"Support"**.

**Step 2:** Navigate to Management > Integrations. If the Integrations option is not visible, your account does not have the **"CompanyProfileManager"** permission. Contact your Alvys account admin to review your role assignment. If your role is correct and the page is still inaccessible, contact Alvys support.

<Note>
  <img alt="Screenshot showing the integrations page with the Accounting section opened." />

  \*Screenshot showing the integrations page with the Accounting section opened. \*
</Note>

## FAQs

**Q: Can I use QuickBooks Desktop on a Mac?**

**A:** No. QuickBooks Desktop is Windows-only. The Web Connector that powers this integration also requires Windows. If your team uses Macs exclusively, consider the QuickBooks Online integration instead.

**Q: Which QuickBooks Desktop editions are supported?**

**A:** Enterprise, Plus, Accountant, Premier, and Pro are supported. To check your edition, open QuickBooks Desktop and press F2 (or Fn + F2) to open the Product Information window.

**Q: Can I connect multiple subsidiaries to QuickBooks Desktop?**

**A:** Yes. Each subsidiary is configured separately. Open the specific subsidiary's company file in QuickBooks before setting it up in Alvys. Each subsidiary requires its own QWC file downloaded from Alvys.

**Q: Does every computer in our office need the Web Connector installed?**

**A:** No. Only the designated sync machine needs the Web Connector. For multi-user setups, this is typically the machine hosting the company file. Installing the Web Connector on more than one machine for the same company file causes duplicate transactions and record-locking errors.

**Q: Does my company file need to be open when I add the QWC file?**

**A:** Yes. Your QuickBooks company file must be open when you add the QWC file to the Web Connector. QuickBooks requires an open file to display the authorization prompt that grants Alvys permission to exchange data.

**Q: What is Single User Mode and when do I need it?**

**A:** Single User Mode means only one user is accessing the company file at a time. You must switch to Single User Mode before adding the QWC file because the authorization prompt requires this mode to appear. You can return to Multi-User Mode after authorization is complete.

**Q: Our QuickBooks is hosted remotely. What do I do differently?**

**A:** Upload both the Web Connector application and the QWC file to your remote environment before starting setup. Complete all connection steps inside the remote desktop session where QuickBooks is running.

**Q: Are account numbers required in my Chart of Accounts?**

**A:** No, account numbers are optional. If your Chart of Accounts already uses account numbers, enable that preference in QuickBooks before mapping accounts in Alvys. If you are not using account numbers, no action is needed.

## Go Deeper

[How to connect QuickBooks Desktop to Alvys and configure settings](/en/help/integrations/how-to-connect-quickbooks-desktop-to-alvys-and-configure-settings)


# Sage Intacct: Prerequisites
Source: https://docs.alvys.com/en/help/integrations/how-to-prepare-sage-intacct-before-connecting-to-alvys

Prepare Sage Intacct for Alvys: enable Web Services, create a dedicated Web Services user, and authorize the Alvys sender ID before running setup.

<Note>
  Before connecting Sage Intacct to Alvys, you must enable Web Services in your Sage account, create a Web Services user with the correct permissions, and authorize the Alvys application. Completing these steps in Sage prepares the connection wizard in Alvys to authenticate and sync data correctly.
</Note>

## Overview

Alvys connects to Sage Intacct using the Sage Web Services API. Before you start the connection wizard in Alvys, a Sage administrator must finish a series of configuration tasks in Sage Intacct. These tasks are a one-time setup. Once they are done, the same configuration supports all future Alvys subsidiaries connecting to that Sage entity.

## Features Not Supported

The following capabilities are not available in the Sage Intacct integration:

* **Custom Dimensions (Platform Apps):** Sage Platform Apps Custom Dimensions are not supported. Only the 11 standard Sage dimension types (such as Location, Department, and Class) are available in Alvys. If you have configured custom dimensions through the Sage Platform Apps framework, those will not appear in the Alvys connection settings.
* **Spend Management:** Sage Spend Management data is not synced by this integration.
* **Payment Export:** Payments cannot be exported from Alvys to Sage through this integration.
* **Historical Data Migration:** Existing transactions in Sage or Alvys are not migrated when you connect. Only new transactions created after the connection is established will sync.
* **Payroll Integration:** Payroll data is not included in this integration.

<Note>
  <img alt="Screenshot showing Custom Dimensions unavailable or error state in Sage Intacct connection settings in Alvys." />

  *Screenshot showing Custom Dimensions unavailable or error state in Sage Intacct connection settings in Alvys.*
</Note>

## Alvys Requirements

Before starting the integration setup, ensure the following items are configured in Alvys.

### Alvys Subsidiaries

At least one subsidiary must be set up in Alvys before you can configure the Sage Intacct integration. Each integration connection is tied to a specific subsidiary. If you have multiple subsidiaries, you will set up the integration for one subsidiary first. Once that is complete, you can configure additional subsidiaries using the original setup as a template to save time.

### External Account IDs (Recommended)

During setup, Alvys links customers, carriers, and drivers to their corresponding records in Sage Intacct using one of two methods:

* **External Accounting ID matching (recommended):** Alvys matches records using the External Accounting ID assigned to each profile, which should map directly to the corresponding Customer ID or Vendor ID in Sage Intacct.
* **Name matching:** If an External Accounting ID is not provided, Alvys will attempt to match records by name. While supported, this method is less reliable and can result in mismatches if names are not identical between the two systems. Name matching is case-insensitive but may produce unexpected results if multiple entities in Sage Intacct share the same name.

For the smoothest integration experience, set up External Accounting IDs on your Customer, Carrier, and Driver profiles for the relevant subsidiary in Alvys before activating the integration.

### Where to Set External Accounting IDs

* **Customers:** Open the customer/broker profile, then access the External Accounting ID dialog.
* **Carriers:** Open the carrier profile, then access the External Accounting ID dialog.
* **Drivers:** Open the driver profile, then access the External Accounting ID dialog.

When setting the External Accounting ID, make sure you configure it for the correct entity or subsidiary; the one tied to the Sage Intacct integration you're setting up. IDs are subsidiary-specific, so a value set for the wrong entity will not be matched during sync.

## Before You Start

Before beginning, confirm the following:

* You must have administrator access to both your Sage Intacct account and Alvys.
* Only **"Admin"**, **"Partner Admin"**, and **"Support"** users in Alvys can access Settings > Connections > Sage Intacct to run the connection wizard. Confirm the person completing the setup has one of these roles before proceeding.
* Have your Sage company credentials ready, including your Sage Company ID, the Web Services user ID you will create in Step 2, and that user's password.

## Steps

1. **Enable the Web Services subscription in Sage.** In Sage Intacct, go to Company > Subscriptions and confirm that Web Services is enabled. If it is not listed as active, contact your Sage account administrator to activate it before continuing. The connection to Alvys cannot be established without this subscription.
2. **Create a dedicated Web Services user in Sage.** Create a user in Sage Intacct specifically for the Alvys integration. Using a dedicated user (rather than a personal login) keeps the integration stable if individual user accounts change or are deactivated. Set the user type to Business User and enable Web Services access for that user.
3. **Add Alvys to Authorized Client Applications in Sage.** Alvys communicates with Sage using the sender ID **AlvysMPP**. You must authorize this sender before Alvys can authenticate with your Sage account.
4. In Sage Intacct, go to Company > Web Services Authorizations.
5. Click Add.
6. Enter the Sender ID: **AlvysMPP**.
7. Click Save.
8. Confirm that **AlvysMPP** now appears in the authorized list.
9. **Assign Web Services role permissions in Sage.** The Web Services user created in Step 2 must have "All" access for each of the following Sage modules. Go to the user's assigned role in Sage and set the permission level to "All" for each module listed below:

   * Administration
   * Company
   * Cash Management
   * General Ledger
   * Accounts Payable
   * Platform Services
   * Accounts Receivable
   * Inventory Control
   * Order Entry
   * Fixed Assets Management

     Incomplete permissions on any module will cause export or sync failures after the connection is established. For example, if Accounts Payable is not set to "All," AP bills for carrier and driver settlements will not post to Sage.
10. **Gather your Sage connection credentials.** Before starting the Alvys connection wizard, collect the following from Sage Intacct:

    * Company ID
    * User ID (the dedicated Web Services user created in Step 2)
    * Password for that user

      You will enter these credentials in the Alvys connection wizard at Settings > Connections > Sage Intacct.
11. **(Optional) Plan your dimension mapping.** If you plan to use Sage dimensions (such as Location, Department, or Class) to tag Alvys transactions, identify the dimension types you will use before connecting. You can configure dimension mappings after the connection is established at Settings > Connections > Sage Intacct. This step is not required to complete the initial connection.
12. **(Optional) Plan your custom field mapping.** If you want to pass additional Alvys load or trip data to Sage custom fields, identify which Sage custom fields you will map before connecting. You can configure custom field mappings after the connection is established at Settings > Connections > Sage Intacct. This step is not required to complete the initial connection.
13. **Confirm user access in Alvys.** Only **"Admin"**, **"Partner Admin"**, and **"Support"** users in Alvys can access Settings > Connections > Sage Intacct to run the connection wizard. Confirm the person completing the setup has one of these roles before navigating to Alvys to begin.

## Result

When all required steps above are complete, your Sage Intacct account is ready for the Alvys connection wizard. Navigate to Settings > Connections > Sage Intacct in Alvys to begin the connection. Steps 6 and 7 are optional and can be completed at any time after the connection is established.

## FAQs

**Q: Do I need to create a new Sage user specifically for Alvys, or can I use an existing user?**

**A:** It is strongly recommended to create a dedicated Web Services user for Alvys. Using a personal user account risks breaking the integration if that user's credentials change or the account is deactivated.

**Q: What is the Sender ID I need to enter in Sage?**

**A:** The Sender ID for Alvys is **AlvysMPP**. Enter this exactly as shown when adding an entry in Company > Web Services Authorizations in Sage.

**Q: What happens if I do not set "All" permissions on a Sage module?**

**A:** The integration will connect, but transactions related to that module will fail to export. For example, if Accounts Payable is not set to "All," AP bills for carrier and driver settlements will not post to Sage.

**Q: Can multiple Alvys subsidiaries connect to the same Sage entity?**

**A:** Yes. Multiple Alvys subsidiaries can connect to the same Sage entity. Each subsidiary is configured separately in the Alvys connection wizard.

**Q: What if Web Services is not available in my Sage subscription?**

**A:** Web Services must be enabled in your Sage Intacct subscription before connecting to Alvys. Contact your Sage account manager or Sage support to add the Web Services module to your subscription.

**Q: Which Alvys roles can complete the connection setup?**

**A:** **"Admin"**, **"Partner Admin"**, and **"Support"** users can access Settings > Connections > Sage Intacct to complete the connection wizard.

## Go Deeper

* [Connecting Sage Intacct to Alvys and Configuring Settings](/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings)


# Business Central: Resolve failed exports
Source: https://docs.alvys.com/en/help/integrations/how-to-resolve-business-central-transaction-export-errors

Find and fix loads, trips, e-checks, and paystubs that failed to export to Business Central using the Error Transactions page in Alvys accounting.

<Note>
  The Error Transactions page shows load, trip, e-check, and paystub records that failed to export to Business Central, along with the error details needed to identify and fix each issue.
</Note>

## Overview

When a transaction fails to sync to Business Central, it appears on the Error Transactions page (also called the error transactions log) with a description of the failure. From this page you can review the error details, correct the underlying record in Alvys, and re-sync the transaction without re-entering data.

## Before You Start

You must have the **"Billing"** permission to access the Error Transactions page. Users with the **"Admin"**, **"Biller"**, **"Support"**, or **"Partner Admin"** role have this permission.

The Business Central integration must be connected and active before transactions can appear on this page.

## Steps

1. **Open the Error Transactions page.** Go to Accounting > Error Transactions in the Alvys navigation menu.

<Note>
  <img alt="Error Transactions page overview." />

  *Error Transactions page overview.*
</Note>

The table shows all transactions that have failed to export to Business Central. Each row includes the following columns:

1. **Identify whether the transaction can be re-synced.** The following transaction types support direct re-sync from the Error Transactions page: Loads, Trips, E-checks, and Paystubs. For carrier settlements, summary invoices, and driver pay, corrections and re-syncs must be performed directly from their respective pages in Alvys.
2. **Correct the underlying record.** Read the Error Message column to identify the cause of the failure. Fix the source record in Alvys before attempting to re-sync. Common error types and their resolutions are listed in the Troubleshooting section below.
3. **Re-sync the transaction.** To re-sync an individual transaction:
4. Right-click the corrected transaction row.
5. Select **Sync Transaction** from the context menu.
6. Confirm when prompted.

<Note>
  <img alt="Sync Transaction context menu." />

  *Sync Transaction context menu.*
</Note>

Alvys sends the transaction to Business Central again. If the correction resolved the issue, the Status column updates to **Resolved**.

To re-sync all transactions in the list at once, right-click and select **Sync All Transactions**. Use this only after all transactions have been corrected and are ready for export. Transactions that still require corrections will be skipped.

## Result

Once a re-sync is successful, the transaction Status changes to **Resolved** and the row is removed from the active error list. The record is posted in Business Central as expected.

## Variations

**Marking a transaction as synced manually:** Use **Mark as Synced** when a transaction has already been resolved outside of Alvys (for example, entered directly in Business Central) and should be removed from the error list without being re-sent. Right-click the row, select **Mark as Synced**, and confirm. This action cannot be undone. The transaction is marked **Resolved** in Alvys and will not be re-sent to Business Central.

<Note>
  <img alt="Mark as Synced option." />

  *Mark as Synced option.*
</Note>

**Non-re-syncable transaction types:** Deductions, accessorial revenue, fuel charges, tolls, accounting invoices, escrow transactions, carrier statements, and driver statements cannot be re-synced from the Error Transactions page. To correct these, open the source record in Alvys (such as the carrier settlement or driver statement) and make corrections there.

## Troubleshooting

### Resource Not Found

Business Central cannot locate a record that Alvys references, such as a General Ledger account, dimension value, or item number that has been deleted or renamed in Business Central.

**Error message:** Resource not found for the segment 'purchaseInvoice' or 'salesInvoice'

<Note>
  <img alt="Resource Not Found error example." />

  * Resource Not Found error example. \*
</Note>

**Step 1:** Check the Error Message column for the name of the missing resource.

**Step 2:** Open Business Central and confirm the referenced resource still exists and is active.

**Step 3:** If the resource was deleted or renamed, update the account mapping in Alvys to point to the correct Business Central record, then re-sync the transaction from the Error Transactions page.

Contact Alvys Support with the transaction reference number and the full error message if the resource exists in Business Central but the error persists.

### Record Already Exists

Business Central has detected a duplicate document number matching the transaction Alvys is attempting to post.

**Error message:** The record in table Sales Header already exists. Identification fields and values: Document Type='Invoice',No.='\[Invoice Number]'

<Note>
  <img alt="Record Already Exists error example." />

  *Record Already Exists error example.*
</Note>

**Step 1:** Open Business Central and search for the document number shown in the Reference column.

**Step 2:** If the record already exists in Business Central and is correct, use **Mark as Synced** in Alvys to remove the transaction from the error list.

**Step 3:** If the record in Business Central is incorrect, delete it in Business Central first, then re-sync from Alvys.

If you are unsure which record to keep, contact Alvys Support before making changes in Business Central.

**Step 4:** Confirm the result: verify in Business Central that the Purchase Invoice or Sales Invoice appears with the correct document number after the re-sync completes.

### Duplicate Dimension Set

Two or more dimension values conflict for the same transaction line, causing Business Central to reject the posting.

**Error message:** The dimension set line already exists. Check existing dimension set lines and the default dimension set lines on the parent.

<Note>
  <img alt="Duplicate Dimension Set error example." />

  *Duplicate Dimension Set error example.*
</Note>

**Step 1:** Review the dimension configuration in Business Central for the account referenced in the transaction.

**Step 2:** Resolve the conflicting dimension values in Business Central.

**Step 3:** Re-sync the transaction from the Error Transactions page.

Contact Alvys Support with the transaction reference number if the dimension conflict cannot be identified from the error message.

**Step 4:** Confirm success: verify in Business Central that the Purchase Invoice or Sales Invoice has been created with the correct dimensions applied.

### Failed Export of Zero-Valued Transaction

The transaction total is zero and Business Central is configured to reject zero-value postings.

**Error message:** A digit was expected at position 3 in '(ID)'.

<Note>
  <img alt="Zero-Valued Transaction error example" />

  *Zero-Valued Transaction error example*
</Note>

**Step 1:** Open the source record in Alvys and verify whether the zero value is correct.

**Step 2:** If the zero value is a data error, correct the record and re-sync.

**Step 3:** If the zero value is intentional and should not be posted to Business Central, use **Mark as Synced** to remove it from the error list.

### Manual Numbering Required

The Business Central number series for the transaction type is set to manual, and Alvys is not sending a document number.

**Error message:** You may not enter numbers manually. If you want to enter numbers manually, please activate Manual Nos. in No. Series. CorrelationId: \[Unique ID]

<Note>
  <img alt="Manual Numbering Required error example." />

  *Manual Numbering Required error example.*
</Note>

**Step 1:** Open Business Central and navigate to the number series configuration for the transaction type shown in the error.

**Step 2:** Set the number series to automatic, or ask your Business Central administrator to update the numbering settings.

**Step 3:** Re-sync the transaction from the Error Transactions page once the number series is updated.

If the number series cannot be changed, contact Alvys Support to discuss an alternative configuration.

## FAQs

**Q: What does the Status column show?**

**A:** The Status column shows **Failed** for transactions that have not yet been successfully re-synced, or **Resolved** for transactions that have been successfully synced or manually marked as synced.

**Q: Can I re-sync a transaction without first fixing the underlying issue?**

**A:** You can trigger a re-sync, but Business Central will reject the transaction again and it will remain on the page with a **Failed** status. Always correct the underlying issue before re-syncing.

**Q: What is the difference between Sync Transaction and Sync All Transactions?**

**A:** Sync Transaction re-syncs a single selected transaction. Sync All Transactions attempts all transactions in the list at once; transactions that still require corrections will be skipped.

**Q: When should I use Mark as Synced instead of Sync Transaction?**

**A:** Use Mark as Synced when the transaction has already been posted to Business Central outside of Alvys, or when it should not be sent to Business Central at all. This removes the transaction from the error list without re-syncing.

**Q: Can a transaction reappear after being marked as Resolved?**

**A:** A transaction marked **Resolved** will not automatically reappear. If the same source record is modified and exported again later, a new failure entry may appear for the updated version.

**Q: Why can't I re-sync deductions, tolls, or accessorial revenue from this page?**

**A:** These transaction types must be corrected and re-synced from their source pages in Alvys, such as the load detail or settlement page, because the correction requires editing the original record.

**Q: Is there a way to see previously resolved errors?**

**A:** The Error Transactions page displays both **Failed** and **Resolved** transactions. Filter by Status to view only resolved items.

**Q: What should I do if a transaction fails repeatedly with the same error after re-syncing?**

**A:** Verify that the correction addresses the specific error type in the Troubleshooting section. If the error persists, contact Alvys Support with the transaction reference number and the full error message.

**Q: Do I need to take any action in Business Central after a successful re-sync?**

**A:** No. When a re-sync is successful, the transaction is posted to Business Central automatically and the Status in Alvys updates to **Resolved**.

## Go Deeper

* [Business Central Transaction Export](/en/help/integrations/business-central-transaction-export-and-modification-workflow)


# Business Central: Account mappings
Source: https://docs.alvys.com/en/help/integrations/how-to-set-up-business-central-account-mappings

Map Alvys revenue, expense, fuel, and toll transactions to Business Central GL accounts so exported invoices, bills, and paystubs post correctly.

<Note>
  Account mappings connect Alvys transaction types to Business Central General Ledger accounts, ensuring every exported transaction posts to the correct account. This article covers required default accounts and optional specific mappings for individual transaction categories.
</Note>

### Overview

Account mappings tell Business Central where to post each type of transaction exported from Alvys. There are two levels of mapping: default account mappings, which apply to all transactions of a given type if no more specific mapping exists, and specific account mappings, which apply to individual transaction categories such as fuel, tolls, or specific accessorials.

**Synonyms:** account mapping, GL mapping, General Ledger mapping, account setup, chart of accounts mapping.

### Before You Start

You must have the **"CompanyProfileManager"** permission. Users with the **"Admin"**, **"Support"**, or **"Partner Admin"** role have this permission.

The Business Central connection must already be authenticated before configuring account mappings. Open the account mappings dialog from Integrations > Accounting > Business Central.

### Steps

1. **Open the account mappings dialog.** Navigate to Accounting > Integrations and open the Business Central integration settings. Proceed to the account mappings step in the setup dialog.
2. **Configure Default Account Mappings.**

<Note>
  <img alt="Image showing Default Account Mappings section overview." />

  \*Image showing Default Account Mappings section overview. \*
</Note>

Default accounts are required and serve as primary fallback accounts for any transactions that are not explicitly mapped to a specific account. These mappings ensure transactions can always be exported successfully and prevent errors caused by unmapped accounts. Four default accounts are required before the integration can be saved.

<Note>
  <img alt="Image showing the Revenue and Expense account settings" />

  \*Image showing the Revenue and Expense account settings \*
</Note>

When Revenue is selected, both an Accounts Receivable account and a Default Revenue account must be mapped. From an invoice perspective, each individual invoice line item, such as customer linehaul, fuel surcharge, or accessorial charges, is posted to the mapped revenue account. The accumulated invoice total is then posted to the Accounts Receivable account, which represents the amount owed by the customer.

<Note>
  <img alt="Image showing Revenue default account mapping flow." />

  \*Image showing Revenue default account mapping flow. \*
</Note>

When Expense is selected, both an Accounts Payable account and a Default Expense account must be mapped. From a bill perspective, each bill line item, such as driver pay rates, carrier linehaul, fuel, or toll charges, is posted to the mapped expense account. The total bill amount is then posted to the Accounts Payable account, which represents the amount owed to the vendor or carrier.

<Note>
  <img alt="Image showing Expense default account mapping flow" />

  *Image showing Expense default account mapping flow*
</Note>

This mirrors how Business Central processes transactions: revenue and expense amounts are recorded at the line-item level, while the total balance due from customers is tracked in Accounts Receivable and the total amount owed to vendors is tracked separately in Accounts Payable.

<Info>
  💡 Once the default accounts are configured, they function as fallback accounts. If specific accounts are not set up for individual transaction types, such as fuel surcharges or specialized trip rates, the system automatically uses the default revenue or expense accounts to ensure the transaction exports successfully.
</Info>

<Warning>
  ⚠️ Users must map default accounts to the correct accounts in the Business Central **Chart of Accounts**. Selecting an account with the wrong type, for example mapping an Expense account to a Revenue field, will cause export errors.
</Warning>

If you do not have any specific accounts created in Business Central, once you have configured the default accounts you can click through the remaining integration steps, then click Save. Your integration will be successfully added.

### Specific Account Mappings

Specific account mapping provides granular control over which Business Central accounts each transaction line-item posts to. This feature is optional but recommended if you have dedicated accounts for individual transaction types in your Business Central Chart of Accounts.

For each transaction category, you can map a default account specific to that category. If you have created a dedicated default account for a category, such as a Default Load Account, map it there. This ensures all transactions within that category are posted consistently. If you do not have a category-specific default account, the system will fall back to the general default revenue or expense account configured in the integration. Below is a detailed explanation of the transaction categories and specific line items available for mapping.

#### Configure Load mappings

<Note>
  <img alt="Image showing Load account mapping step" />

  *Image showing Load account mapping step*
</Note>

The Load category represents **revenue transaction line items** that appear on customer invoices. Each line item on a load, such as linehaul or fuel surcharge, can be mapped to a specific Business Central account if one exists.

If you have dedicated accounts in your Business Central Chart of Accounts, such as **Customer Linehaul** or **Customer Fuel Surcharge**, map each line item accordingly. If you only have a general account for load revenue, map it to the **Default Load Account**.

#### Configure Trip mappings

<Note>
  <img alt="Image showing Trip account mapping step" />

  *Image showing Trip account mapping step*
</Note>

The Trip category represents **expense transaction line items** that appear on bills. Each line item, such as driver pay rates or carrier linehaul, can be mapped to a specific Business Central account if one exists. If you have dedicated accounts in your Business Central Chart of Accounts, such as Carrier Linehaul or individual Driver Rate accounts, map each line item accordingly. If you only have a general account for trip expenses, map it to the Default Trip Account. If neither category-specific nor default trip accounts are available, the integration will fall back to the general default expense account configured in a prior step.

Trips can be associated with internal assets, subsidiary carriers only, or external carriers. For trips using internal assets (company drivers or owner-operators), the trip category line items on the bill represent driver rates. For trips using subsidiary or external carriers, the trip category line items on the trip bill represent carrier rates.

#### Configure Accessorial mappings

Accessorials represent additional charges or fees that can be applied to both customers (revenue) and drivers or carriers (expense). As such, they can impact both revenue and expense accounts in Business Central.

<Note>
  <img alt="Image showing Accessorial account mapping revenue and expense views" />

  *Image showing Accessorial account mapping revenue and expense views*
</Note>

The list of accessorial types available for mapping is pulled from the custom accessorials configured by the tenant in Alvys. To configure custom accessorials, refer to the following Help Center article: [Custom Accessorials ](/en/help/loads-trips/how-to-create-and-add-accessorials). Each accessorial type includes two columns for mapping. The Revenue column is used to map the account for income generated from the accessorial when charged to customers. The Expense column is used to map the account for costs associated with the accessorial when charged to drivers or carriers.

Once the list is displayed, you can map each accessorial line item to its corresponding Business Central account if dedicated accounts exist. However, if your accounting process only includes a general revenue account and a general expense account for all accessorials, you may map those to the Default Accessorial Account option.

<Note>
  <img alt="Image showing Default Accessorial account mapping item for revenue and expense views" />

  *Image showing Default Accessorial account mapping item for revenue and expense views*
</Note>

#### Configure E-Check mappings.

An e-check (also called an electronic check) is a digital payment issued to a driver or external carrier as an alternative to a physical check. Map each e-check type to a Business Central account if one exists.

<Note>
  <img alt="Image showing E-Check account mapping for revenue and expense views" />

  *Image showing E-Check account mapping for revenue and expense views*
</Note>

The E-Check category itself includes a default revenue account and a default expense account, which are used if specific accounts are not assigned. Each individual e-check type has its own revenue and expense columns for mapping. The revenue column represents the e-check fee charged to drivers or carriers and is recorded as income for the company.

The e-check fee is configured by the tenant based on the E-check type from the [company profile](https://app.alvys.com/#/manage/company-profile) and can have a minimum, maximum, or percentage-based value.

<Note>
  <img alt="Image showing E-Check fee configuration in company/ tenant profile" />

  *Image showing E-Check fee configuration in company/ tenant profile*
</Note>

<Note>
  <img alt="Image showing E-Check fee mapping in revenue column" />

  *Image showing E-Check fee mapping in revenue column*
</Note>

The expense column represents the actual e-check amount issued to the driver or carrier.

E-check fees are treated as revenue because, although they appear as an expense on a driver or carrier bill, they reimburse the company and are therefore considered income.

<Warning>
  ⚠️ A bill can fail to export if it includes e-checks with fees and the revenue account for the e-check fee is not mapped, especially when the configuration is set to export expenses only. This can be resolved by mapping the e-check fee to a specific e-check revenue account or by using Alvys’ default e-check revenue account.
</Warning>

<Info>
  💡 When e-checks are issued to a driver or an external carrier, an associated accessorial may also be created for the driver and the customer. Any accessorials associated with e-checks should be mapped under the Accessorials category if the specific accounts exist.
</Info>

#### Configure Driver Deductions Mappings

Alvys provides a predefined list of deduction types. If you have specific accounts in your Business Central chart of accounts for any of these deduction types, you can map them accordingly. If you only have a general account for all driver deductions, you may map it to the **Default Deduction Account**.

<Note>
  <img alt="Image showing Deduction account mapping" />

  *Image showing Deduction account mapping*
</Note>

#### Configure Fuel mappings.

The Fuel category includes fuel transactions, such as diesel, linked to drivers or owner-operators. Each fuel type can be mapped to a specific Business Central account if one exists. If no specific account exists but a Default Fuel Account exists, the transaction will use the Default Fuel Account. If neither a specific nor a Default Fuel Account exists, the transaction will fall back to the Default Expense Account configured in the default account mapping.

<Note>
  <img alt="Image showing Fuel account mapping" />

  *Image showing Fuel account mapping*
</Note>

#### Configure Toll mappings.

Map toll charge line items to a dedicated Business Central account if one exists. If no specific Toll account is mapped, toll transactions fall back to the Default Expense account.

<Note>
  <img alt="Image showing Toll account mapping" />

  *Image showing Toll account mapping*
</Note>

<Warning>
  ⚠️ The Tax category is deprecated. Please skip this step.

  <img alt="Notion Image" />
</Warning>

The Tax mapping category is no longer in active use. Tax line items are handled through other transaction categories. No action is required on this step unless instructed by Alvys Support.

#### Configure Escrow mappings.

Escrow accounts hold funds on behalf of drivers. These accounts are created on driver profiles, and deposits or withdrawals are reflected when driver statements or paystubs are generated.

<Note>
  <img alt="Image showing Escrow account mapping" />

  *Image showing Escrow account mapping*
</Note>

When mapping Escrow accounts, if specific Escrow accounts exist in your Business Central Chart of Accounts for one or more Escrow account types, map those accounts. If no specific account exists but a **Default Escrow Account** exists for the Escrow category, map to the default. If neither exists, the transaction will fall back to the **Default Liability Account**.

<Info>
  💡 Escrow account mappings must be linked to a **liability account** in Business Central because these funds are held temporarily on behalf of drivers and do not represent a company expense.
</Info>

#### Save and complete setup.

After all required account mappings are configured, click **Save** to complete the integration setup. A green checkmark confirms the integration is active.

<Note>
  <img alt="Image showing Active business Central Integration" />

  *Image showing Active business Central Integration*
</Note>

### Result

After saving, the Business Central integration is active and Alvys begins exporting transactions to the configured General Ledger accounts. Each transaction type routes to the most specific account available, falling back to the relevant default account if no specific mapping has been set.

### Troubleshooting

#### Green checkmark does not appear after saving

**Step 1:** Verify that all four required default accounts (A/R, A/P, Default Revenue, Default Expense) have been mapped before clicking Save.

**Step 2:** Confirm that each mapped account exists in Business Central and is active.

**Step 3:** Check that accounts are mapped to the correct type: A/R and Default Revenue for revenue transactions; A/P and Default Expense for expense transactions. Mapping an account to the wrong type prevents the integration from activating.

If the green checkmark still does not appear after verifying the above, contact Alvys Support.

#### Export errors appear after saving account mappings

A transaction export error after completing setup typically means a required account has been deleted or deactivated in Business Central since the mapping was saved. Open the Error Transactions page at Accounting > Error Transactions to view the specific error and identify which account needs to be updated.

## FAQs

**Q: What if I don’t see the green checkmark after submitting the integration setup?** \*\*A: \*\*Refresh the Alvys Integrations page. If the green checkmark still does not appear next to Business Central, reopen the integration dialog, reconnect using the Login button, confirm all settings and mappings, and click Save. If the issue persists, contact Alvys Support.

**Q: What happens if I update my Chart of Accounts in Business Central later?**

**A:** Account mappings in Alvys can be updated at any time. Open the Business Central integration dialog, navigate to the account mapping step, select the updated G/L account from the dropdown, and save the integration to apply the changes.

**Q: What are default account mappings, and why are they required?**

**A:** Default account mappings act as fallback G/L accounts for transactions not explicitly mapped to a specific line item. They ensure that all revenue (Sales Invoices) and expenses (Purchase Invoices) exported to Business Central post successfully, preventing sync errors due to unmapped financial data.

**Q: When should I use specific account mappings?**

**A:** Specific account mappings are recommended when dedicated Business Central G/L accounts exist for individual transaction types, such as fuel surcharges, driver pay, or detention. These provide granular control over your General Ledger, ensuring consistent and accurate financial reporting for different revenue and cost streams.

**Q: What happens if a required default account is mapped incorrectly?**

A: Mapping a default account to the wrong type such as using an Expense G/L account for a Revenue line will cause export errors in Business Central.

**Q: Can I skip setting up specific accounts and rely only on default accounts?**

A: Yes. If specific G/L accounts do not exist for every line item, transactions will fall back to the default accounts configured during setup. This allows the integration to function successfully without needing a highly granular Chart of Accounts.

**Q: How do escrow transactions need to be mapped in Business Central?**

A: Escrow accounts must be linked to a Liability account in Business Central. Because escrow funds are temporary holdings for drivers or carriers and not company expenses, mapping them to an expense account will misstate your financial statements and cause reconciliation issues.

**Q: Can I map both revenue and expense lines for accessorials?**

A: Yes. Each accessorial type in the mapping step includes a Revenue column for customer charges and an Expense column for carrier or driver costs. If dedicated G/L accounts do not exist for a specific accessorial, they can be mapped to the Default Accessorial Account.

**Q: What should I do if I only have general accounts for deductions, fuel, or tolls?**

A: If dedicated G/L accounts do not exist for specific categories like deductions, fuel, or tolls, map these transaction lines to the corresponding default account configured during the setup process. This ensures the transactions still export to Business Central under a broader category.

### Go Deeper

* [Business Central: Transaction Export and Modification Workflow](/en/help/integrations/business-central-transaction-export-and-modification-workflow)
* [Business Central: Identifying and Resolving Failed Transactions](/en/help/integrations/how-to-resolve-business-central-transaction-export-errors)
* [Business Central Integration Collection](/en/help/integrations/business-central-integration-collection)


# NetSuite: Account & item mappings
Source: https://docs.alvys.com/en/help/integrations/how-to-set-up-netsuite-account-and-item-mappings-in-alvys

Configure NetSuite default account, specific account, and item mappings during Alvys integration setup so every exported invoice and bill posts correctly.

<Note>
  This article explains how to configure default account mappings, specific account mappings, and item mappings during NetSuite integration setup in Alvys (a one-way export from Alvys to NetSuite), ensuring all transactions export to the correct NetSuite Chart of Accounts.
</Note>

## Overview

Accurate account mapping is essential so that every transaction exported from Alvys to NetSuite posts to a valid account. The NetSuite integration supports three kinds of configuration: default account mappings, specific account mappings, and item mappings. You configure these during step 3 of the NetSuite integration setup wizard.

## Before You Start

Complete NetSuite authentication and settings configuration before mapping accounts. See [NetSuite: Authentication and Settings Configuration in Alvys](/en/help/integrations/netsuite-authentication-and-settings-configuration-in-alvys).

You must be signed in as an **"Admin"**, **"Partner Admin"**, or **"Support"** user to access Management > Integrations. Before enabling item mappings, confirm that all required items already exist in your NetSuite account.

## Steps

1. **Set up default account mappings.** Default accounts are required and serve as the primary fallback for any transactions not explicitly mapped to a specific account.

<Note>
  <img alt="Default Mapping options for Accounts Payable and Receivables within the Netsuite integration settings." />

  \*Default Mapping options for Accounts Payable and Receivables within the Netsuite integration settings. \*
</Note>

<Note>
  <img alt="Account Types that can be mapped" />

  *Account Types that can be mapped*
</Note>

**When Revenue is selected,** map both:

<Note>
  <img alt="Receivable and revenue mapping options" />

  *Receivable and revenue mapping options*
</Note>

**When Expense is selected,** map both:

<Note>
  <img alt="Expense and Payable mapping options" />

  *Expense and Payable mapping options*
</Note>

**Important:** Once default accounts are configured, they function as fallback accounts. If specific accounts are not set up for individual transaction types, the integration automatically uses the default revenue or expense account.

**Important:** You must map default accounts to the correct accounts in the NetSuite Chart of Accounts. Selecting an account with the wrong type will cause export errors.

If you do not have any specific accounts created in NetSuite, once you have configured the default accounts you can click through the remaining integration steps, then click **Save**.

1. **Configure specific account mappings (optional).** Specific account mapping provides granular control over which NetSuite accounts each transaction line item posts to.

   * **Load:** The Load category represents revenue transaction line items on customer invoices.

<Note>
  <img alt="Specific account mapping options for revenue transactions" />

  *Specific account mapping options for revenue transactions*
</Note>

Map each line item to its dedicated account. If only a general account exists, map it to the **Default Load Account**.

<Note>
  <img alt="Specific account mapping options for expense transactions" />

  *Specific account mapping options for expense transactions*
</Note>

Trips can be associated with internal assets, subsidiary carriers, or external carriers. For trips using internal assets, line items represent driver rates. For trips using subsidiary or external carriers, line items represent carrier rates. Map each line item accordingly or use the **Default Trip Account** as fallback.

<Note>
  <img alt="Accessorial Mappings" />

  *Accessorial Mappings*
</Note>

The list of accessorial types is pulled from custom accessorials configured in Alvys. See [Custom Accessorials](/en/help/loads-trips/how-to-create-and-add-accessorials). Each accessorial type has two columns: Revenue (customer charges) and Expense (driver or carrier costs).

<Note>
  <img alt="Default Accessorial Account Mapping" />

  *Default Accessorial Account Mapping*
</Note>

<Note>
  <img alt="E-Check account mappings" />

  *E-Check account mappings*
</Note>

The E-Check category includes a default revenue account and a default expense account. Each individual e-check type has its own Revenue and Expense columns. The Revenue column maps the e-check fee charged to drivers or carriers (recorded as income for the company). The Expense column maps the actual e-check amount issued.

The e-check fee is configured in the company profile (Management > Company Profile) and can have a minimum, maximum, or percentage-based value.

<Note>
  <img alt="Notion Image" />

  <img alt="Company Profile E-check fee configuration" />

  *Company Profile E-check fee configuration*
</Note>

<Note>
  <img alt="Mapping for specific E-Check type" />

  * Mapping for specific E-Check type\*
</Note>

**Important:** A bill can fail to export if it includes e-checks with fees and the revenue account for the e-check fee is not mapped, even when the configuration is set to export expenses only. Map the e-check fee to a specific e-check revenue account or to the default e-check revenue account.

When e-checks are issued to a driver or an external carrier, an associated accessorial may also be created for the driver and the customer. Any accessorials associated with e-checks should be mapped under the Accessorials category if the specific accounts exist.

<Note>
  <img alt="Deductions Mapping options" />

  *Deductions Mapping options*
</Note>

<Note>
  <img alt="Fuel Account Mappings" />

  *Fuel Account Mappings*
</Note>

<Note>
  <img alt="Toll Account Mapping" />

  *Toll Account Mapping*
</Note>

<Warning>
  ⚠️ **Important:** The Tax category is deprecated. Skip this step if it appears in the interface.

  <img alt="Notion Image" />
</Warning>

<Note>
  <img alt="Escrow Account Mappings" />

  *Escrow Account Mappings*
</Note>

**Important:** Escrow account mappings must be linked to a liability account in NetSuite because these funds are held temporarily on behalf of drivers and do not represent a company expense.

1. **Configure item mappings (optional).** Item mappings allow each transaction line exported from Alvys to be associated with a specific NetSuite item rather than posting directly to a general ledger account. The **Use Existing Items** setting must be enabled.

   How item mappings differ from account mappings:

   * Default Account Mapping: fallback GL accounts for unmapped lines.
   * Specific Account Mapping: dedicated GL accounts per line type.
   * Item Mapping (Use Existing Items): each line is mapped to a NetSuite item; the revenue or expense account used is determined by the configuration of that item in NetSuite.

     **Important:** When Use Existing Items is enabled, default account mapping options are disabled. Any line item not mapped to a NetSuite item will cause the transaction export to fail.

     Before mapping items in Alvys, confirm the corresponding items already exist in NetSuite. See [How to Create Items in NetSuite](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N2166469.html).
   * Navigate to Management > Integrations and open the NetSuite integration.
   * In the settings step, enable the **Use Existing Items** toggle.

     <img alt="NetSuite integ settings with “use existing items” selected" />

     *NetSuite integ settings with “use existing items” selected*
   * Proceed to the account mapping step. Each dropdown now shows "Search Items" instead of accounts.

     <img alt="Search Items dropdown menu" />

     *Search Items dropdown menu*
2. For each category (Load, Trip, Accessorials, E-Checks, Deductions, Fuel, Tolls, Escrow), select the appropriate NetSuite item from the dropdown.

   **Important:** Ensure all required NetSuite items exist before enabling item mappings. Verify each item links to the correct revenue or expense account in NetSuite.
3. **Complete the setup.** Once all mappings are configured, click **Done**, then the **Submit** button. A green checkmark will appear next to the integration to confirm it was successfully added.

<Note>
  <img alt="NetSuite integration showing Green Check mark indicating it is successfully mapped." />

  \*NetSuite integration showing Green Check mark indicating it is successfully mapped. \*
</Note>

## Result

After completing this step, all account and item mappings are saved. Transactions exported from Alvys will post to the configured accounts or items according to the fallback order: specific item or account mapping → category-level default → master default revenue or expense account.

## Troubleshooting

### Green checkmark does not appear after submitting

Refresh the Management > Integrations page. If it still does not appear, reopen the integration dialog, use the Login button to reconnect, confirm all settings and mappings are complete, and submit again. If the issue persists, contact Alvys Support.

### Bill fails to export after including e-checks

Map the e-check fee to a specific e-check revenue account or to the default e-check revenue account to resolve this.

### Transaction export fails after enabling Use Existing Items

Review all mapping categories and confirm each line has a corresponding NetSuite item selected. Confirm the items exist in NetSuite before attempting to re-export.

### Account mapping causes export errors

Open the NetSuite integration dialog, navigate to the account mapping step, verify each field is mapped to an account of the correct type, and resubmit.

## FAQs

**Q: What if I don't see the green checkmark after submitting the integration setup?**

**A:** Refresh the Management > Integrations page. If the checkmark still does not appear, reopen the integration dialog, reconnect using the Login button, confirm all settings and mappings, and submit again. If the issue persists, contact Alvys Support.

**Q: What happens if I update my Chart of Accounts in NetSuite later?**

**A:** Account mappings in Alvys can be updated at any time. Open the NetSuite integration dialog, navigate to the account mapping step, select the updated account, and submit.

**Q: What are default account mappings, and why are they required?**

**A:** Default account mappings act as fallback accounts for transactions not explicitly mapped to a specific account. They ensure all revenue and expense transactions export successfully.

**Q: When should I use specific account mappings?**

**A:** When dedicated NetSuite accounts exist for individual transaction types such as fuel surcharges, driver pay, or accessorials.

**Q: What happens if a required default account is mapped incorrectly?**

**A:** Mapping to the wrong type will cause transaction export errors. Always select accounts that match the transaction type.

**Q: Can I skip setting up specific accounts and rely only on default accounts?**

**A:** Yes. Transactions will fall back to the default accounts configured during setup.

**Q: How do escrow transactions need to be mapped in NetSuite?**

**A:** Escrow accounts must be linked to a liability account. Escrow funds represent temporary holdings on behalf of drivers and are not company expenses.

**Q: What is the Use Existing Items feature, and how does it affect account mapping?**

**A:** Use Existing Items links each transaction line to a specific NetSuite item instead of a GL account. When enabled, default account mapping options are disabled.

**Q: What happens if a line item on a transaction is not mapped to a NetSuite item when Use Existing Items is enabled?**

**A:** The transaction export will fail. All relevant lines must be mapped.

**Q: Can I map both revenue and expense lines for accessorials?**

**A:** Yes. Each accessorial type includes a Revenue column for customer charges and an Expense column for driver or carrier costs.

**Q: How are e-checks and fees treated in NetSuite?**

**A:** E-check fees are considered revenue because they reimburse the company. The e-check expense represents the actual amount issued to the driver or carrier.

**Q: What should I do if I only have general accounts for deductions, fuel, or tolls?**

**A:** Map these transaction lines to the corresponding default account to ensure transactions export correctly.

## Go Deeper

* [NetSuite: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-netsuite)
* [NetSuite Integration Collection](/en/help/integrations/netsuite-integration-collection)


# QuickBooks Desktop: Account mappings
Source: https://docs.alvys.com/en/help/integrations/how-to-set-up-quickbooks-desktop-account-mappings-in-alvys

Map your QuickBooks Desktop Chart of Accounts to Alvys revenue and expense categories so QBD invoices and bills post to the right GL account without errors.

<Note>
  Map your QuickBooks Desktop (QBD) Chart of Accounts to Alvys revenue and expense categories (a two-way integration in which Alvys exports invoices and bills to QBD) so that every invoice and bill posts to the correct account without errors.
</Note>

## Overview

Account mapping connects each Alvys transaction type to a specific account in your QuickBooks Desktop (QBD) Chart of Accounts. When Alvys exports an invoice or bill to QBD, it looks up the mapped account for each line item and posts the amount there. Without complete mappings, the Web Connector will fail to sync the transaction.

The integration uses two tiers: default accounts (required, act as fallback for any unmapped transaction) and specific accounts (optional, allow granular control per transaction category). You configure both during the integration setup wizard.

**Important:** This article covers Step 3 of the QuickBooks Desktop integration setup. Complete Steps 1 and 2 before starting here.

## Before You Start

**Required role:** **"Admin"**, **"Partner Admin"**, or **"Support"** (requires the **"CompanyProfileManager"** permission)

**Prerequisites:**

* The QuickBooks Desktop integration must already be connected and the Web Connector active.
* Your QBD Chart of Accounts must be set up in QuickBooks before mapping accounts in Alvys. Alvys pulls the account list directly from QBD.
* You must know which transaction types you selected during configuration (Revenue, Expense, or both).

## Steps

1. **Open the account mappings screen.**
2. Go to **Management > Integrations**.
3. Open the QuickBooks Desktop integration setup wizard.
4. Navigate to the **Account Mappings** step (Step 3 of the wizard).
5. **Map default accounts.** Default accounts are required and act as the primary fallback for any unmapped transaction line items.

<Note>
  <img alt="Default account mapping fields screen." />

  \*Default account mapping fields screen. \*
</Note>

**If Revenue is selected,** map both:

<Note>
  <img alt="Revenue default account mapping fields filled in." />

  *Revenue default account mapping fields filled in.*
</Note>

**If Expense is selected,** map both:

<Note>
  <img alt="Expense default account mapping fields filled in." />

  * Expense default account mapping fields filled in.\*
</Note>

**Important:** Map default accounts to the correct account type in the QBD Chart of Accounts. Selecting an account with the wrong type will cause export errors.

If you do not have any specific accounts created in QBD, once you have configured the default accounts you can click through the remaining steps, then click **Save**.

1. **Map Load accounts (revenue).** The Load category represents revenue transaction line items on customer invoices.

<Note>
  <img alt="Load account mapping screen." />

  *Load account mapping screen.*
</Note>

Map each line item to a dedicated account. If only a general account exists, map it to the **Default Load Account**.

1. **Map Trip accounts (expense).** The Trip category represents expense transaction line items on bills.

<Note>
  <img alt="Trip account mapping screen." />

  *Trip account mapping screen.*
</Note>

Trips can be associated with internal assets, subsidiary carriers, or external carriers:

Map each line item to a dedicated account or use the **Default Trip Account** as fallback.

1. **Map Accessorial accounts (revenue and expense).** Accessorials represent additional charges or fees affecting both customers (revenue) and drivers or carriers (expense).

<Note>
  <img alt="Accessorials mapping screen showing Revenue and Expense columns per type." />

  \*Accessorials mapping screen showing Revenue and Expense columns per type. \*
</Note>

The list is pulled from custom accessorials configured in Alvys. See [Custom Accessorials](/en/help/loads-trips/how-to-create-and-add-accessorials). Each accessorial type has two columns: Revenue (customer charges) and Expense (driver or carrier costs).

<Note>
  <img alt="Accessorials Default Accessorial Account option." />

  *Accessorials Default Accessorial Account option.*
</Note>

1. **Map E-Check accounts (revenue and expense).** An e-check is an electronic check issued to pay a driver or external carrier. E-check fees are treated as revenue because they reimburse the company.

<Note>
  <img alt="E-Check mapping screen." />

  \*E-Check mapping screen. \*
</Note>

<Note>
  <img alt="E-Check fee configuration in company profile." />

  *E-Check fee configuration in company profile.*
</Note>

The E-Check category includes a default revenue account and a default expense account. Each individual e-check type has Revenue and Expense columns. The Revenue column maps the e-check fee. The Expense column maps the actual e-check amount.

<Note>
  <img alt="E-check mapping example" />

  *E-check mapping example*
</Note>

**Important:** A bill can fail to export if it includes e-checks with fees and the revenue account for the e-check fee is not mapped, even when the configuration is set to export expenses only.

When e-checks are issued to a driver or carrier, an associated accessorial may also be created. Any accessorials associated with e-checks should be mapped under Accessorials (Step 5) if specific accounts exist.

1. **Map Deduction accounts.** Map each predefined deduction type to a dedicated account, or map all to the **Default Deduction Account**.

   <img alt="Deductions mapping screen showing deduction types." />

   *Deductions mapping screen showing deduction types.*
2. **Map Fuel accounts.** The fallback order for fuel transactions: specific fuel type account → **Default Fuel Account** → **Default Expense Account**.

   <img alt="Fuel category mapping screen with fuel types." />

   *Fuel category mapping screen with fuel types.*
3. **Map Toll accounts.** Only a single default account is provided for toll mapping.

<Note>
  <img alt="Tolls mapping screen with single default account field." />

  \*Tolls mapping screen with single default account field. \*
</Note>

**Important:** The Tax category is deprecated. Skip this step if it appears in the wizard.

<Note>
  <img alt="Deprecated Tax category screen." />

  *Deprecated Tax category screen.*
</Note>

1. **Map Escrow accounts.** Escrow accounts hold funds on behalf of drivers. The fallback order: specific escrow type account → **Default Escrow Account** → **Default Liability Account**.

<Note>
  <img alt="Escrow mapping screen" />

  *Escrow mapping screen*
</Note>

**Important:** Escrow account mappings must be linked to a liability account in QuickBooks Desktop because these funds are held temporarily on behalf of drivers.

1. **Complete the setup.** Once all mappings are configured, click **Done**, then click **Submit**. A green checkmark will appear next to the integration.

<Note>
  <img alt="Done and Submit buttons at end of wizard." />

  * Done and Submit buttons at end of wizard.\*
</Note>

<Note>
  <img alt="Green checkmark next to QuickBooks Desktop integration." />

  *Green checkmark next to QuickBooks Desktop integration.*
</Note>

## Result

A green checkmark appears next to the QuickBooks Desktop integration on the Integrations page. All Alvys transaction types are now connected to the correct accounts in your QBD Chart of Accounts.

## Troubleshooting

### Green checkmark does not appear after clicking Submit

1. Refresh the Alvys Integrations page.
2. If the green checkmark still does not appear, reopen the integration dialog and verify the Web Connector is active and the Company File Path is correct.
3. Re-save the settings by clicking Submit again.
4. If the issue persists, contact Alvys Support.

### Bill fails to export when it includes an e-check

1. Return to the E-Checks section of account mappings (Step 6).
2. Map the e-check fee to a specific e-check revenue account, or select the default e-check revenue account.
3. Save and re-export the bill.

### Export error due to wrong account type

1. Return to the default account mappings (Step 2) and verify that the Accounts Receivable and Default Revenue fields point to Revenue-type accounts.
2. Verify the Accounts Payable and Default Expense fields point to the correct liability and expense account types.
3. Correct any mismatches and save.

### Account does not appear in a mapping dropdown

1. Verify the account exists in your QBD Chart of Accounts.
2. Ensure the Web Connector has run at least one successful sync so the QBD account list is up to date in Alvys.
3. Refresh the mapping screen and check the dropdown again.
4. If the account still does not appear, contact Alvys Support.

## FAQs

**Q: What are default account mappings, and why are they required?**

**A:** Default accounts act as fallback accounts for transactions not explicitly mapped to a specific line item. They ensure all revenue (invoices) and expenses (bills) exported to QuickBooks post successfully.

**Q: Can I skip setting up specific accounts and rely only on default accounts?**

**A:** Yes. Transactions automatically fall back to the default accounts configured in Step 2.

**Q: Why did my bill fail to export when it included an e-check?**

**A:** This happens when the e-check fee is not mapped to a revenue account. Even when exporting expenses only, e-check fees are considered income and must be linked to a revenue account.

**Q: Why must Escrow be mapped to a liability account?**

**A:** Escrow funds are held on behalf of the driver and are not a company expense. Mapping to a liability account ensures financial statements correctly reflect that these funds are owed back to the driver.

**Q: Can I map my customer fuel surcharge and driver fuel expense to the same account?**

**A:** This is not recommended. Map customer-facing fuel surcharges to a Revenue account and driver-facing fuel costs to an Expense account. Mapping to the wrong account type will cause export errors.

**Q: What is the Default Load Account used for?**

**A:** It serves as the primary account for all line items on a customer invoice when you do not want to break out individual line items into separate QuickBooks accounts.

**Q: How do I map accessorials that I created in Alvys?**

**A:** Alvys pulls your custom accessorials list directly into the mapping screen. You will see two columns for each accessorial: one for Revenue (when you charge a customer) and one for Expense (when you pay a driver or carrier).

## Go Deeper

* [QuickBooks Desktop: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-quickbooks-desktop)

  <img alt="Notion Image" />


# QuickBooks Desktop: Resolve failed exports
Source: https://docs.alvys.com/en/help/integrations/identifying-and-resolving-failed-quickbooks-desktop-transaction-exports

Locate failed QuickBooks Desktop exports, decode QBWC error codes like 1039 and 3140, then retry or clear transactions from the Alvys Error Transactions page.

<Note>
  This article explains how to find transactions that failed to export to QuickBooks Desktop, understand why they failed, and resolve them using the options on the Error Transactions page.
</Note>

## Overview

QuickBooks Desktop (QBD) is a two-way integration: Alvys pushes invoices, bills, and other financial records to QuickBooks Desktop through the QuickBooks Web Connector (QBWC). When Alvys exports these records and the Web Connector encounters a problem, the affected transaction is placed on the Error Transactions page in Alvys rather than being silently lost. From this page you can review the error code and message for each failed export, retry the sync, or mark a transaction as resolved without re-syncing. This guide walks through locating failed exports, interpreting why they did not go through, and clearing them.

## Symptom

One or more of the following conditions is present:

* Transactions appear on the Error Transactions page (Accounting > Error Transactions) in Alvys.
* An error code such as QBWC1039, QBWC1088, Error 3140, or Error 3070 appears in the Error Code or Error Message column.
* The banner at the top of the Error Transactions page shows a count of transactions that have not yet been synced to QuickBooks Desktop.
* A transaction was previously exported but reappeared on the Error Transactions page after a QuickBooks Desktop version change.

## Cause

Each error code indicates a distinct cause.

### QBWC1039: Duplicate name already exists in QuickBooks

QBWC1039 occurs when QuickBooks rejects a record because the External Accounting Name in Alvys already exists in another list in QuickBooks Desktop. QuickBooks does not allow duplicate names across its lists (customers, vendors, employees, and others). For example, if a customer is named "ABC Trucking" in Alvys and a vendor with the same name already exists in QuickBooks, the sync fails with this error.

A related variant of QBWC1039 occurs when a QuickBooks Desktop company file already contains a registration for the Alvys application. This happens when you add the Alvys Web Connector (.QWC) file to the Web Connector program and a registration for that application already exists in the file. Selecting "Remove" in the Web Connector deletes only the scheduler; it does not remove the application registration from the QuickBooks company file itself.

### QBWC1088: QuickBooks company file is not open

QBWC1088 occurs when the Web Connector cannot verify the status of an integration because the QuickBooks company file is not open. This error also occurs during initial connection setup when the company file is not open at the time the Application Certificate prompt should appear.

### Error 3140: Invalid or missing account

Error 3140 occurs when a transaction references a QuickBooks account that does not exist in the company file or that was entered incorrectly in the Alvys account mappings.

### Error 3070: Field length exceeded

Error 3070 occurs when a value in the transaction exceeds the maximum field length allowed by QuickBooks Desktop, most often triggered by a customer name, class name, or description that is longer than QuickBooks will accept.

### \$0 transaction appearing on Error Transactions page

If the **Ignore Zero Valued Transactions** setting was previously enabled and was then disabled, any original \$0 transactions that were previously skipped are reprocessed. If a transaction now has a non-zero value and the export does not complete successfully, it appears on the Error Transactions page.

### Transactions reappearing after a QuickBooks version change

If you upgrade or downgrade your QuickBooks Desktop version, the Web Connector registration becomes mismatched. Transactions that previously synced correctly may reappear on the Error Transactions page.

## Resolution

### Navigate to the Error Transactions page

Go to **Accounting > Error Transactions** in Alvys. The page displays all transactions that have failed to export, with columns: Entity Type, Transaction Id, Transaction Type, User Name, Class, Name, Reference Number, PO Number, Account, Description, Error Message, Error Code, Date Created, and Transaction Total.

A banner at the top shows the total count and dollar value of unsynced transactions.

<Note>
  <img alt="Screenshot of the Error Transactions page in Alvys showing the column layout and the unsynced transactions banner." />

  *Screenshot of the Error Transactions page in Alvys showing the column layout and the unsynced transactions banner.*
</Note>

### Resolving QBWC1039: Duplicate name in QuickBooks

1. Note the name referenced in the Error Message column.
2. Open QuickBooks Desktop and search for that name across all list types (Customers, Vendors, Employees, Other Names).
3. Determine whether the duplicate is the same entity or a different entity that shares the name. If the same entity, merge or delete the duplicate. If different entities, rename one so the names no longer conflict.
4. Return to the Error Transactions page in Alvys, select the transaction, and select **Retry sync**.

   Resolving the QBWC1039 duplicate Web Connector registration variant:
5. Open QuickBooks Desktop and sign in as an Administrator.
6. Press F2 or Ctrl + 1 to open the Product Information window and confirm the company file details.
7. In the QuickBooks Web Connector program, locate the Alvys entry and select "Remove." This removes the scheduler only.
8. Download a new .QWC file from Alvys (Management > Integrations > QuickBooks Desktop) and add it back to the Web Connector. When the Application Certificate window appears in QuickBooks Desktop, select "Yes, whenever this QuickBooks company file is open."
9. Run the Web Connector sync and confirm the transactions process without error.

<Note>
  <img alt="Screenshot of the QuickBooks Web Connector showing the Alvys entry with the Remove button." />

  *Screenshot of the QuickBooks Web Connector showing the Alvys entry with the Remove button.*
</Note>

### Resolving QBWC1088: Company file not open

1. Open QuickBooks Desktop and open the company file connected to Alvys.
2. If this is an initial connection setup, confirm the Application Certificate window appears in QuickBooks Desktop after adding the .QWC file. If the prompt does not appear, close the Web Connector, ensure QuickBooks Desktop is open with the correct company file, and re-add the .QWC file.
3. Run the Web Connector sync. Confirm the connection completes and the transactions on the Error Transactions page clear.

### Resolving Error 3140: Invalid account

1. Note the account name referenced in the Error Message column.
2. Open QuickBooks Desktop and go to **Lists > Chart of Accounts**. Verify the account exists and its name exactly matches what is configured in Alvys.
3. In Alvys, go to Management > Integrations > QuickBooks Desktop and review the Account Mappings. Correct any account names that do not match.
4. Return to the Error Transactions page, select the affected transaction(s), and select **Retry sync**.

### Resolving Error 3070: Field length exceeded

1. Note the field referenced in the Error Message column.
2. In Alvys, locate the load or entity referenced by the Reference Number and shorten the value that exceeded the limit. QuickBooks Desktop limits most name fields to 41 characters and description fields to 4,095 characters.
3. Return to the Error Transactions page, select the affected transaction(s), and select **Retry sync**.

### Resolving \$0 transactions that reappeared

1. Locate the \$0 transaction on the Error Transactions page.
2. If the transaction has no value and does not need to be in QuickBooks, select it and select **Mark as synced**.
3. If the transaction should be exported, verify the **Ignore Zero Valued Transactions** setting in Management > Integrations > QuickBooks Desktop, then select **Retry sync**.

### Resolving transactions that reappeared after a QuickBooks version change

1. In the QuickBooks Web Connector, remove the existing Alvys entry.
2. Download a new .QWC file from Management > Integrations > QuickBooks Desktop in Alvys.
3. Open QuickBooks Desktop with the correct version and the correct company file. Add the new .QWC file to the Web Connector. When prompted in QuickBooks Desktop, grant Alvys access by selecting "Yes, whenever this QuickBooks company file is open."
4. Run the Web Connector sync and confirm the transactions process correctly.

### Using Sync all and Mark as synced

At any time, you can use the following actions on the Error Transactions page:

* **Sync all:** Select the **Sync all** button (top right) to attempt re-export of all transactions currently on the Error Transactions page.
* **Retry sync:** Select a single transaction and select **Retry sync** in the bulk action bar to re-export that specific transaction.
* **Mark as synced:** Select one or more transactions and select **Mark as synced** in the bulk action bar to dismiss them without exporting to QuickBooks Desktop. Use this when a transaction was resolved directly in QuickBooks Desktop or is no longer needed.

<Note>
  <img alt="Screenshot showing the Sync Transaction and Mark as Synced context menu options on the Error Transactions page." />

  *Screenshot showing the Sync Transaction and Mark as Synced context menu options on the Error Transactions page.*
</Note>

## Troubleshooting

If the steps above did not resolve the error:

* Confirm the QuickBooks Web Connector is running and connected to the correct company file.
* Confirm the Alvys integration settings under Management > Integrations > QuickBooks Desktop match the active QuickBooks company file.
* Check the Error Message column on the Error Transactions page for additional detail beyond the error code.

If none of the verified causes apply, contact Alvys Support with the error code, the error message text, and the Reference Number of the affected transaction.

## FAQs

**Q: What is the difference between "Retry sync" and "Sync all"?**

**A:** Retry sync re-exports a single selected transaction. Sync all attempts to re-export every transaction currently on the Error Transactions page at once.

**Q: What does "Mark as synced" do?**

**A:** Mark as synced removes the selected transaction(s) from the Error Transactions page without sending them to QuickBooks Desktop. Use this when the transaction was already entered directly in QuickBooks or when it does not need to be exported.

**Q: Why does selecting "Remove" in the QuickBooks Web Connector not fully remove the Alvys connection?**

**A:** Selecting "Remove" deletes only the scheduler: the rule that tells the Web Connector when to run. The application registration inside the QuickBooks company file is not removed. To fully re-register, add a new .QWC file and grant access again through the Application Certificate window.

**Q: Why did transactions reappear on the Error Transactions page after I upgraded QuickBooks Desktop?**

**A:** When the QuickBooks Desktop version changes, the company file registration can become mismatched with the Web Connector entry. Remove the old Web Connector entry, download a new .QWC file from Alvys, and re-add it with the correct QuickBooks version open.

**Q: Can I export the Error Transactions list?**

**A:** Yes. On the Error Transactions page, select the Export table button (top right) and choose "Export all as CSV" or "Export all as Excel."

**Q: Why does a \$0 transaction appear on the Error Transactions page?**

**A:** If the Ignore Zero Valued Transactions setting was previously enabled and then disabled, Alvys reprocesses transactions that were previously skipped. Use Mark as synced if it does not need to be exported, or Retry sync if it should be.

## Go Deeper

* [QuickBooks Desktop: Connection and Configuration Settings](/en/help/integrations/how-to-connect-quickbooks-desktop-to-alvys-and-configure-settings)
* [QuickBooks Desktop: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-quickbooks-desktop)


# MyCarrierPackets (MCP) Integration
Source: https://docs.alvys.com/en/help/integrations/mycarrierpackets-mcp-integration

Sync MyCarrierPackets (MCP) carrier compliance, insurance, and W9 data into Alvys every five minutes and block non-compliant carriers from being added to loads.

<Note>
  Connect MyCarrierPackets (MCP) to Alvys to automatically sync carrier compliance data — including insurance coverage, W9 information, and carrier profile details — so Alvys can block non-compliant carriers from being added to loads.
</Note>

## What This Integration Does

MyCarrierPackets (MCP) is a carrier compliance management platform. When connected to Alvys, it automatically pulls carrier compliance data from your MyCarrierPackets monitoring list into Alvys every 5 minutes whenever there are changes.

Once the integration is active, Alvys checks each carrier's MCP compliance status when you add them to a load. If a carrier has an unacceptable compliance status, Alvys will prevent them from being added to the load.

## Prerequisites

Before connecting MyCarrierPackets to Alvys, you need:

* An active MyCarrierPackets account with access to the Integration Tools tab
* Admin or Partner Admin access in Alvys to configure integrations under Management > Integrations

## Connect / Authenticate

### Create API credentials in MyCarrierPackets

Log in to [MyCarrierPackets](https://mycarrierpackets.com/) and navigate to the Integration Tools tab. Click the Add Integration button and fill out the fields to create your API credentials.

<img alt="MyCarrierPackets Integration Tools tab showing the Add Integration button." />

\*MyCarrierPackets Integration Tools tab showing the Add Integration button. \*

<img alt="MyCarrierPackets Add Integration form with fields filled in." />

*MyCarrierPackets Add Integration form with fields filled in.*

Save your API credentials. You will need them in the next step.

### Enter your credentials in Alvys

Navigate to [Integrations](https://app.alvys.com/#/manage/integrations) in Alvys. Expand the Compliance section and click the pencil icon on the MyCarrierPackets integration box.

<img alt="Alvys Integrations page showing the Compliance section with the MyCarrierPackets integration box and pencil icon." />

*Alvys Integrations page showing the Compliance section with the MyCarrierPackets integration box and pencil icon.*

In the dialog box that appears, enter your MyCarrierPackets API credentials and click Save.

<img alt="Alvys dialog box for entering MyCarrierPackets credentials with Save button." />

*Alvys dialog box for entering MyCarrierPackets credentials with Save button.*

### Request a manual sync for existing carriers (if applicable)

If you already have carriers on your MyCarrierPackets monitoring list at the time you connect the integration, contact Alvys support to perform a manual sync. This imports all existing monitored carriers into Alvys. If your monitoring list is empty, skip this step — carriers will sync automatically once you start monitoring them in MyCarrierPackets.

## Field & Data Mapping

The integration imports the following carrier information from MyCarrierPackets into Alvys:

**Carrier profile**

* Name
* MC number and DOT number
* Address
* Contact information

  **Insurance coverage**
* Coverage type
* Policy number
* Issue and expiration dates
* Limit amount
* Underwriter (insurance agency)

  **W9 information**
* SSN (where available)
* TIN (where available)

Note: the integration imports only the information extracted from documents such as insurance certificates and W9 forms. The actual documents are not imported.

## Sync Behavior

* Compliance data syncs from MyCarrierPackets to Alvys every 5 minutes when there are changes to a carrier's compliance status in MyCarrierPackets.
* Sync is one-way: data flows from MyCarrierPackets into Alvys only. Changes made in Alvys do not update MyCarrierPackets.
* Only carriers on your MyCarrierPackets monitoring list are synced to Alvys. Carriers not on your monitoring list will not appear with MCP compliance data in Alvys.

## Add Carriers to Your Monitoring List

If your MyCarrierPackets monitoring list is empty when you first connect the integration, follow these steps to start monitoring carriers:

Log in to MyCarrierPackets and select Carrier Search in the left sidebar. Search for the carrier you want to add to your monitoring list.

<img alt="MyCarrierPackets Carrier Search page in the left sidebar." />

*MyCarrierPackets Carrier Search page in the left sidebar.*

<img alt="MyCarrierPackets carrier search results." />

*MyCarrierPackets carrier search results.*

Select the carrier to view their profile, then click the Start Monitoring button. The carrier will be added to your monitoring list and their compliance data will sync to Alvys.

<img alt="MyCarrierPackets carrier profile with the Start Monitoring button." />

*MyCarrierPackets carrier profile with the Start Monitoring button.*

<img alt="MyCarrierPackets carrier added to monitoring list confirmation." />

*MyCarrierPackets carrier added to monitoring list confirmation.*

## Verify It's Working

After saving your credentials and activating the integration, confirm the connection is working:

Navigate to the Carriers page in Alvys and search for a carrier that is on your MyCarrierPackets monitoring list. Select the carrier to open their profile and check the MCP status field. If the MCP status field shows compliance data, the integration is active.

<img alt="Alvys Carriers page search results showing a carrier." />

*Alvys Carriers page search results showing a carrier.*

<img alt="Alvys carrier profile showing the MCP status field with compliance data." />

*Alvys carrier profile showing the MCP status field with compliance data.*

When you add a carrier to a load, Alvys automatically checks whether the carrier is compliant with MCP requirements. If the carrier has an unacceptable compliance status, Alvys will prevent them from being added to the load.

## Troubleshooting

### MCP status field is empty on a carrier profile

**Step 1:** Confirm the carrier is on your MyCarrierPackets monitoring list. Only carriers you are actively monitoring in MyCarrierPackets will sync to Alvys.

**Step 2:** Wait up to 5 minutes after adding a carrier to your monitoring list for the first sync to complete.

**Step 3:** If the carrier is on your monitoring list and the MCP status field remains empty after 5 minutes, contact Alvys support to confirm the integration credentials are saved correctly and request a manual sync if needed.

### Carrier cannot be added to a load

**Step 1:** Open the carrier's profile in Alvys and check the MCP status field.

**Step 2:** If the MCP status shows a non-compliant status, the carrier must resolve their compliance issue in MyCarrierPackets before they can be added to a load. The compliance restriction is applied by Alvys based on the data synced from MyCarrierPackets.

**Step 3:** After the carrier's compliance status is updated in MyCarrierPackets, wait up to 5 minutes for the updated status to sync to Alvys, then retry adding the carrier to the load.

## Limits / Unsupported

* The integration does not import actual insurance documents, W9 forms, or other compliance documents — only the data extracted from them.
* The integration is one-way. You cannot push carrier data from Alvys to MyCarrierPackets.
* Carriers not on your MyCarrierPackets monitoring list are not synced and will have no MCP compliance data in Alvys.

## FAQs

**Q: How often does compliance data update in Alvys?**

**A:** Compliance data syncs from MyCarrierPackets to Alvys every 5 minutes when there are changes to a carrier's compliance status.

**Q: What happens if I try to add a non-compliant carrier to a load?**

**A:** If a carrier has an unacceptable compliance status in MyCarrierPackets, Alvys will prevent them from being added to the load.

**Q: Do I need to manually add each carrier to MyCarrierPackets?**

**A:** Yes. You need to search for and start monitoring each carrier in the MyCarrierPackets portal. Once you are monitoring a carrier, their compliance data automatically syncs to Alvys.

**Q: Can I see the actual insurance documents in Alvys?**

**A:** No. The integration imports only the information extracted from documents such as insurance certificates and W9 forms. The actual documents are not imported.

**Q: I already had carriers monitored in MyCarrierPackets before connecting the integration. Will they sync automatically?**

**A:** No. If you already have carriers on your MyCarrierPackets monitoring list at the time you connect the integration, contact Alvys support to perform a manual sync that will import all existing monitored carriers into Alvys.

## Go Deeper

* [Why Am I Seeing an Override Authorization Error When Assigning a Carrier?](/en/help/loads-trips/override-authorization-error-when-assigning-a-carrier)
* [RMIS Integration](/en/help/integrations/rmis-integration)


# NetSuite: Connect & configure
Source: https://docs.alvys.com/en/help/integrations/netsuite-authentication-and-settings-configuration-in-alvys

Authenticate NetSuite in Alvys with Token-Based Authentication, then configure transaction types, subsidiaries, dimensions, and export settings before mapping.

<Note>
  This article explains how to authenticate the NetSuite integration in Alvys using Token-Based Authentication and how to configure all transaction, dimension, and operational settings after connecting.
</Note>

## Overview

NetSuite is a two-way integration in which Alvys exports financial transactions to NetSuite. The integration connects Alvys to NetSuite so financial records (customer invoices, driver bills, carrier bills, fuel expenses, toll expenses, and customer payments) are automatically sent from Alvys to NetSuite. Setting up the connection involves three stages: authentication, settings configuration, and account mapping. This guide covers authentication and settings configuration. For account mapping, see the NetSuite: Account Mapping article.

Before starting this article, complete all steps in the NetSuite Prerequisites article.

## Prerequisites

Complete the following before configuring authentication in Alvys:

* A dedicated integration role and user must be created in NetSuite with all required permissions (see NetSuite Prerequisites)
* The following five credentials must be generated and saved: Account ID (also called Realm ID), Consumer Key, Consumer Secret, Token ID, and Token Secret
* Your Alvys account must have the **"CompanyProfileManager"** permission to access Management > Integrations. This permission is available to users with the Admin, Support, or Partner Admin role.

If your organization uses multiple subsidiaries, this integration requires the NetSuite OneWorld edition.

## Connect / Authenticate

Alvys connects to NetSuite using Token-Based Authentication (TBA) exclusively. TBA uses OAuth 1.0 and requires five credential fields: Account ID (Realm ID), Consumer Key, Consumer Secret, Token ID, and Token Secret. Alvys does not support OAuth 2.0 for the NetSuite integration.

### Open the NetSuite integration

1. In Alvys, select your username in the bottom-left corner.
2. Select **Management** from the menu, then navigate to **Integrations**.
3. Select the subsidiary you want to configure.
4. Select the edit icon next to NetSuite.

<Note>
  <img alt="Management Menu with Integrations page highlighted" />

  *Management Menu with Integrations page highlighted*

  <img alt="Integrations page with Accounting section highlighted" />

  *Integrations page with Accounting section highlighted*

  <img alt="NetSuite Integration in Accounting Area of Integrations page" />

  *NetSuite Integration in Accounting Area of Integrations page*
</Note>

### Enter your credentials

1. In the dialog that opens, enter all five credential fields:

   * **Account ID** (also called Realm ID): your NetSuite account number
   * **Consumer Key**: generated when creating the integration record in NetSuite
   * **Consumer Secret**: generated alongside the Consumer Key
   * **Token ID**: generated when creating the access token in NetSuite
   * **Token Secret**: generated alongside the Token ID
2. Select **Save** to validate the credentials. If validation is successful, the wizard advances to the next step.

<Note>
  <img alt="Screenshot showing the credential entry dialog for the NetSuite integration with all five fields visible." />

  *Screenshot showing the credential entry dialog for the NetSuite integration with all five fields visible.*
</Note>

<Warning>
  ⚠️ If you use NetSuite OneWorld with multiple subsidiaries, enabling the Subsidiaries setting in the configuration will add a subsidiary mapping step to the setup wizard. Complete that mapping before saving. Complete the integration for one subsidiary at a time.
</Warning>

### Configure settings

After credentials are saved, configure the transaction types, dimension mappings, and operational settings described in the Field & Data Mapping and Sync Behavior sections below.

## Field & Data Mapping

### Accounts Receivable Settings

**Transactions Type:** Controls which financial transaction types are exported. Sub-options are Revenue (exports customer invoices) and Expense (exports driver and carrier bills). Enable only the transaction types you intend to export.

<Warning>
  ⚠️ Your selection here takes precedence over all other configuration settings. Enable only the options you intend to export to NetSuite.
</Warning>

**Use Existing Customers:** When enabled, Alvys matches customers and brokers to NetSuite records using an Accounting ID instead of name. To configure: navigate to each customer or broker profile in Alvys, locate the **External Accounting ID** field, select the subsidiary, enter the customer's ID from NetSuite, and select **Save**.

**Export Customer Payments:** When enabled, customer payments recorded manually against a load or uploaded via a factoring integration are exported to NetSuite. Partial payments are not exported; payment is sent only when the total paid amount equals the total billable amount. After enabling this setting, you will be prompted to select a deposit account.

**Reference Number Prefix:** Applies a prefix to transaction reference numbers in NetSuite. This helps identify transactions that originated from Alvys.

**Custom Field:** Supports mapping the Load Order Number from a load to a NetSuite custom field on customer invoices.

**Shared Billing (Intercompany Billing):** Used when a load is invoiced by one subsidiary (Invoice As) and tendered by another subsidiary (Tender As), and both subsidiaries have separate accounting integrations configured. This setting must be enabled on both subsidiaries.

**Equipment Types:** Maps Alvys equipment types to custom fields in NetSuite.

### Accounts Payable Settings

**Ignore Driver Bills:** Prevents export of all driver bills to NetSuite. Typically used when driver pay is managed in an external payroll system.

**Single Bill for Driver Statement:** When enabled, all charges for a driver are consolidated into a single bill per driver statement. When disabled, individual trip bills are exported when the customer invoice is generated.

**Generate Carrier Invoice Separately:** Applies to brokerage-type trips with an external carrier. When enabled, the system waits for a document of type "Carrier Invoice" to be uploaded to the trip before exporting the carrier bill.

**Process Statement by Tax Category:** When enabled, only bills for 1099 drivers are exported to NetSuite; W-2 driver bills are excluded. Requires Single Bill for Driver Statement to also be enabled.

**Pay Subsidiary Carrier:** When enabled, instead of billing the driver on paystub generation, the system bills the subsidiary carrier on invoice generation.

**Ignore Zero Valued Transactions:** Excludes invoices and bills with a total value of zero from export.

**Create Vendor Using 1099 Tax Company:** When enabled, vendors are created in NetSuite using the Tax Company Name and Address from the driver profile's Tax Information section, for drivers classified as 1099.

**Carrier Statements:** Must be enabled to export carrier statements as bills when generating a Carrier Statement from the Carrier Settlements module.

**Export Company Fuel Expense:** When enabled, exports fuel transactions where fuel was not deducted from the driver to NetSuite as bills. Exports run daily at 6:30 AM UTC.

<Warning>
  ⚠️ If this setting was not previously enabled, past fuel transactions will not be exported automatically when you turn it on.
</Warning>

**Export Company Toll Expense:** When enabled, exports toll transactions where the toll was not deducted from the driver to NetSuite as bills. Exports run daily at 7:30 AM UTC.

<Warning>
  ⚠️ If this setting was not previously enabled, past toll transactions will not be exported automatically when you turn it on.
</Warning>

### Dimension Settings

**Subsidiaries:** Each Alvys subsidiary must be mapped to the corresponding NetSuite subsidiary. This is mandatory for NetSuite OneWorld accounts. Selecting the Subsidiaries checkbox creates an additional subsidiary mapping step in the integration wizard.

**Fleets:** Alvys fleets can be mapped to Classes, Departments, or Locations in NetSuite. Only one classification type can be used per fleet at a time. Selecting the Fleets checkbox creates an additional fleet mapping step in the integration wizard.

## Sync Behavior

### Incompatible setting combinations

The following settings cannot be enabled at the same time:

**Single Bill for Driver Statement** is incompatible with: Ignore Driver Bills, Pay Subsidiary Carrier.

**Process Statement by Tax Category** requires Single Bill for Driver Statement and is incompatible with: Ignore Driver Bills, Pay Subsidiary Carrier.

**Pay Subsidiary Carrier** is incompatible with: Single Bill for Driver Statement, Process Statement by Tax Category, Create Vendor Using 1099 Tax Company, Ignore Driver Bills.

**Ignore Driver Bills** is incompatible with: Single Bill for Driver Statement, Process Statement by Tax Category, Create Vendor Using 1099 Tax Company.

**Create Vendor Using 1099 Tax Company** requires Single Bill for Driver Statement and is incompatible with: Pay Subsidiary Carrier, Ignore Driver Bills.

### Export schedules

Fuel expense exports run daily at 6:30 AM UTC. Toll expense exports run daily at 7:30 AM UTC. All other transactions are exported at the time of invoice or bill generation.

## Verify It's Working

After completing authentication and settings configuration:

1. Generate a test invoice or bill in Alvys.
2. Navigate to **Management > Integrations** and check the integration status. A status of **Partial** indicates that required fields (such as Classes or account mappings) are not yet completed.
3. Confirm the transaction appears in NetSuite under the expected customer or vendor record.

## Recommended Settings by Operation Type

### Carrier operations

For companies that primarily operate as carriers, the following settings are typically enabled: Revenue, Expense, Single Bill for Driver Statement, Export Company Fuel Expense, Export Company Toll Expense, Custom Field, and Export Customer Payments.

<Note>
  <img alt="Screenshot showing the recommended settings for carrier operations." />

  *Screenshot showing the recommended settings for carrier operations.*
</Note>

### Broker operations

For companies that primarily operate as freight brokers, the following settings are typically enabled: Revenue, Expense, and Generate Carrier Invoice Separately.

<Note>
  <img alt="Screenshot showing the recommended settings for broker operations." />

  \*Screenshot showing the recommended settings for broker operations. \*
</Note>

## Troubleshooting

### Integration status shows Partial after saving credentials

The integration requires Classes to be mapped in addition to the five credential fields. Complete the fleet and class mappings, or verify that the Subsidiaries and Fleets mappings are fully configured.

### Carrier bill was not created for a brokerage trip

If Generate Carrier Invoice Separately is enabled, the carrier bill is not created until a document of type "Carrier Invoice" is uploaded to the trip. Upload a Carrier Invoice document to the trip, then select **Regenerate Invoice** on the load.

### Past fuel or toll transactions did not export after enabling the setting

Enabling Export Company Fuel Expense or Export Company Toll Expense does not retroactively export past transactions. Only new transactions created after the setting is enabled will be exported.

### Customer payments are not exporting to NetSuite

Partial payments are not exported. Payment is sent to NetSuite only when the total amount paid equals the total billable amount on the load. Verify that a deposit account is selected in the Export Customer Payments configuration.

## Limits / Unsupported

* OAuth 2.0 is not supported. Only OAuth 1.0 Token-Based Authentication (TBA) is supported.
* Partial customer payments are not exported; only full payments are sent to NetSuite.
* Past fuel and toll transactions are not retroactively exported when the corresponding settings are first enabled.
* Only one classification type (Classes, Departments, or Locations) can be used per fleet mapping at a time.

## FAQs

**Q: Does Alvys support OAuth 2.0 for the NetSuite integration?**

**A:** No. Alvys connects to NetSuite using OAuth 1.0 Token-Based Authentication (TBA) only.

**Q: What are the five credential fields required to connect NetSuite to Alvys?**

**A:** Account ID (Realm ID), Consumer Key, Consumer Secret, Token ID, and Token Secret. All five must be entered and saved before the integration can authenticate.

**Q: Why does the integration show a Partial status even after I entered my credentials?**

**A:** A Partial status indicates that Classes are not yet mapped. Complete the fleet and class mappings and check the status again.

**Q: Can I use Single Bill for Driver Statement and Ignore Driver Bills at the same time?**

**A:** No. These two settings are incompatible.

**Q: What is cross-subsidiary billing and when should I enable it?**

**A:** Cross-subsidiary billing (Shared Billing or Intercompany Billing) applies when a load is invoiced by one subsidiary and tendered by another, and both subsidiaries have separate accounting integrations. This setting must be enabled on both subsidiaries involved.

**Q: Does the NetSuite integration require OneWorld?**

**A:** OneWorld is required only if your organization uses multiple subsidiaries in NetSuite.

**Q: What happens if Use Existing Customers is enabled but no NetSuite customer ID is set on the customer profile?**

**A:** The invoice will fail to sync. A valid NetSuite Customer ID must be entered in the External Accounting ID field on the customer or broker profile in Alvys.

**Q: Are customer payments exported to NetSuite automatically?**

**A:** Yes, when Export Customer Payments is enabled. Payments are exported every five minutes once the total amount paid equals the full invoice amount. Partial payments are not exported.

**Q: Should customer payments be recorded in Alvys or NetSuite?**

**A:** Although exporting payments from Alvys is supported, it is generally recommended to record payments directly in NetSuite and allow them to sync back to Alvys.

## Go Deeper

* [NetSuite Prerequisites](/en/help/integrations/how-to-prepare-netsuite-before-connecting-to-alvys)
* [NetSuite: Account Mapping](/en/help/integrations/how-to-set-up-netsuite-account-and-item-mappings-in-alvys)
* [NetSuite: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-netsuite)
* [NetSuite: Identifying and Resolving Failed Transactions](/en/help/integrations/transactions-failed-to-sync-to-netsuite)


# NetSuite: Overview
Source: https://docs.alvys.com/en/help/integrations/netsuite-integration-collection

Every article for setting up, using, and troubleshooting the Oracle NetSuite accounting integration with Alvys, ordered by the recommended configuration path.

<Note>
  This collection gathers every article for configuring, using, and troubleshooting the NetSuite integration in Alvys. Follow the recommended order to get started, or jump to a specific topic using the links below.
</Note>

## Overview

The NetSuite integration connects Alvys with Oracle NetSuite to export invoices, bills, and credits and synchronize payment status. This collection is organized in the recommended setup sequence. If you are configuring the integration for the first time, start with Article 1 and follow the articles in order.

## Articles in This Collection

### 1. NetSuite: Prerequisites

This article guides you through the prerequisites for integrating NetSuite with Alvys, including enabling required features, creating a dedicated integration role and user, generating authentication credentials, and preparing your system for connection.

[NetSuite: Prerequisites](/en/help/integrations/how-to-prepare-netsuite-before-connecting-to-alvys)

### 2. NetSuite: Authentication and Settings Configuration in Alvys

This article provides a guide to setting up and configuring the NetSuite integration in Alvys. It explains how to authenticate the connection, configure transaction export settings, and map subsidiaries and fleets.

[NetSuite: Authentication and Settings Configuration in Alvys](/en/help/integrations/netsuite-authentication-and-settings-configuration-in-alvys)

### 3. NetSuite: Account Mappings (Default, Specific, and Item Mappings)

This article explains default, specific, and item account mappings for the NetSuite integration and how each level controls how Alvys routes line items to the correct NetSuite General Ledger accounts.

[NetSuite: Account Mappings (Default, Specific, and Item Mappings)](/en/help/integrations/how-to-set-up-netsuite-account-and-item-mappings-in-alvys)

### 4. NetSuite: Transaction Export and Modification Workflow

This article explains how Alvys exports invoices and bills to NetSuite, including how subsidiaries, customers, vendors, and drivers are linked, and how exported transactions can be modified while maintaining data integrity.

[NetSuite: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-netsuite)

### 5. Alvys Payment Synchronization for Accounting Integrations

This article explains how Alvys synchronizes customer and vendor payments with accounting systems including NetSuite, QuickBooks Online, QuickBooks Desktop, and Business Central. It covers supported export and import workflows, transaction status updates, and important considerations for deposit accounts.

[Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)

### 6. NetSuite: Identifying and Resolving Failed Transactions

This article explains how to identify and resolve failed NetSuite transaction exports using the Error Transactions page in Alvys. It outlines common error messages, their causes, and step-by-step resolution guidance, and clarifies which transactions can be re-synced directly and when to contact Alvys support.

[NetSuite: Identifying and Resolving Failed Transactions](/en/help/integrations/transactions-failed-to-sync-to-netsuite)

## Go Deeper

* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)


# Connect Orbcomm Cargowatch to Alvys
Source: https://docs.alvys.com/en/help/integrations/orbcomm-cargowatch-integration

Connect Orbcomm Cargowatch to Alvys with XML credentials to pull real-time GPS locations from your trucks and trailers into the Asset Map and dispatch board.

<Warning>
  **This integration is retired.** Orbcomm retired its older CargoWatch connection, and Alvys has moved to the newer [Orbcomm Platform integration](/en/help/integrations/connecting-orbcomm-platform-to-alvys). If you are setting up Orbcomm for the first time, use Orbcomm Platform instead. This page remains for reference if you still have the legacy CargoWatch card in your account.
</Warning>

<Note>
  Connect Orbcomm Cargowatch to Alvys to pull real-time GPS location data from your Orbcomm-equipped trucks and trailers automatically, giving you live asset visibility on the Asset Map and in dispatch planning.
</Note>

## Overview

Orbcomm Cargowatch (also called the Orbcomm ELD or telematics integration) is a telematics solution that provides real-time GPS tracking for trucks and trailers. Once connected, Alvys automatically pulls location data from your Orbcomm-equipped assets, making that data visible on the Asset Map and available for dispatch planning.

<Warning>
  ⚠️ Orbcomm Cargowatch uses XML credentials (a username and password). If your Orbcomm account uses the newer RESTful API, you are on Orbcomm Platform, not Orbcomm Cargowatch. Check with your Orbcomm representative if you are unsure which version you have.
</Warning>

## Prerequisites

Before you begin, you need XML credentials from Orbcomm: a username and a password.

Contact Orbcomm at [customer.care@orbcomm.com](mailto:customer.care@orbcomm.com) and request XML credentials. Keep these credentials ready for the connection step below.

You also need the Orbcomm Unit number and Gateway ID for each truck or trailer you want to track. These are available in your Orbcomm portal or by request from Orbcomm support.

## How to connect

* Click your profile icon in the lower left corner of Alvys.
* Select the subsidiary you want to configure and click the **Integrations** tab.
* Expand the **ELD** section. Locate the **Orbcomm Cargowatch** card and click the pencil icon to open the configuration.

<Note>
  <img alt="Image showing the ELD section with the Orbcomm Cargowatch card and pencil icon." />

  *Image showing the ELD section with the Orbcomm Cargowatch card and pencil icon.*
</Note>

* Enter your XML credentials. Enter your Orbcomm Cargowatch **XML Username** and **Password**, then click **Save**. Alvys validates your credentials automatically. If the credentials are accepted, the integration becomes active.

<Note>
  <img alt="Image showing the XML Username and Password fields for Orbcomm Cargowatch configuration." />

  *Image showing the XML Username and Password fields for Orbcomm Cargowatch configuration.*
</Note>

## What syncs

Orbcomm sends GPS location data to Alvys for each asset that has been mapped. The data includes the asset's current location coordinates, which Alvys uses to update the Asset Map and to support dispatch planning. Alvys does not send data back to Orbcomm. Location data flows one way: from Orbcomm into Alvys.

Only assets that have been explicitly mapped to an Orbcomm Unit number and Gateway ID will appear on the Asset Map.

### Map assets for location tracking

After connecting, you need to tell Alvys which Orbcomm Unit ID and Gateway ID correspond to each truck or trailer.

* Go to **Assets** in the left navigation and select **Trucks** or **Trailers**.

<Note>
  <img alt="Image showing the Assets section with the Trucks and Trailers options in the left menu." />

  *Image showing the Assets section with the Trucks and Trailers options in the left menu.*
</Note>

* Double-click the asset you want to configure, then scroll down to the **ELD Integrations** section and click **Add Integration**.
* Select **Orbcomm** from the dropdown.
* Enter the **Orbcomm Unit #** in the Integration ID field and the **Gateway ID** in the Gateway ID field, then click **Save**.

<Note>
  <img alt="Image showing the ELD Integrations section with the Add Integration dialog, Orbcomm selected, and the Unit # and Gateway ID fields." />

  \*Image showing the ELD Integrations section with the Add Integration dialog, Orbcomm selected, and the Unit # and Gateway ID fields. \*
</Note>

Repeat this process for each truck or trailer you want to track. After saving, the asset should begin appearing on the Asset Map within a few minutes if the integration is active.

<Warning>
  ⚠️ Only assets with a mapped Orbcomm Unit number and Gateway ID will appear on the Asset Map; assets that are not mapped in Alvys will not receive location updates regardless of the integration being active.
</Warning>

## Troubleshooting

### Asset is not appearing on the Asset Map after mapping

1. Confirm the Orbcomm Unit number and Gateway ID entered in Alvys exactly match what is shown in your Orbcomm portal. A mismatch will prevent location data from being received.
2. Confirm the integration is active by checking the Orbcomm Cargowatch card in the ELD section under Integrations. It should show a connected state.
3. If the asset still does not appear, contact Orbcomm support to confirm the unit is transmitting location data from the vehicle.
4. If location data is transmitting from Orbcomm but the asset is still missing from the Asset Map in Alvys, contact Alvys Support.

### Cannot find the Orbcomm Unit number or Gateway ID

Your Orbcomm Unit numbers and Gateway IDs are available in your Orbcomm portal. If you cannot locate them, contact Orbcomm at [customer.care@orbcomm.com](mailto:customer.care@orbcomm.com).

## FAQs

**Q: Where do I find my Orbcomm Unit numbers and Gateway IDs?**

**A:** Your Orbcomm Unit numbers and Gateway IDs are available in your Orbcomm portal. You can also request them from Orbcomm support at [customer.care@orbcomm.com](mailto:customer.care@orbcomm.com).

**Q: Can I track both trucks and trailers with Orbcomm Cargowatch?**

**A:** Yes. You can configure Orbcomm Cargowatch tracking for both trucks and trailers by adding the integration to each asset individually.

**Q: What is the difference between Orbcomm Cargowatch and Orbcomm Platform?**

**A:** Orbcomm Cargowatch uses XML credentials (a username and password) and connects via an older API. Orbcomm Platform uses the newer RESTful API with different credentials. Check with your Orbcomm representative to confirm which version your account uses.

**Q: Does Alvys send any data back to Orbcomm?**

**A:** No. Location data flows one way: from Orbcomm into Alvys. Alvys does not send data to Orbcomm.


# Post Loads to DAT Load Board
Source: https://docs.alvys.com/en/help/integrations/post-loads-to-dat-load-board

Post brokerage loads to the DAT load board directly from Alvys, either manually from a load's detail page or automatically on a recurring auto-sync schedule.

<Note>
  Connect your DAT account to Alvys and post brokerage loads directly to the DAT load board without leaving your TMS, either manually from a load's detail page or automatically on a set interval.
</Note>

## Overview

The DAT load board integration (also referred to as DAT posting or the DAT marketplace integration) lets brokerage teams post loads to DAT directly from Alvys. Once the integration is configured for a subsidiary, any user with the **"MarketplacePostLoads"** permission can post a load to DAT using the Post Shipment button on the load detail page. When auto-sync is enabled, eligible loads post automatically on a recurring schedule without manual action.

After a load is posted, the load board displays a "Posted To: DAT" label and the DAT icon on the load, so your team can see posting status at a glance.

## Prerequisites

Before you can connect DAT to Alvys, you need two things from DAT directly:

* A DAT Load Board license with API access. Standard DAT accounts do not include API access by default. You must have a license that covers REST API usage.
* Integration credentials from DAT's technical support team. Contact DAT at [techsupportteamleads@dat.com](mailto:techsupportteamleads@dat.com) to request your integration credentials. Include the following details as they appear in your DAT account: your company name, main contact name and phone number, a unique identifier such as your MC number or address, and confirmation that you need REST API access.

You will also need to provide a service account email. This is a dedicated email address used only for the integration, not a personal login. If you do not already have one, DAT recommends creating a new email account that is not already registered with DAT.

Once DAT confirms your credentials are ready, you can proceed with setup in Alvys.

## How to connect

1. Open the Integrations section.

   * Click the person icon in the bottom left corner of Alvys and select Integrations.
2. Select your subsidiary and find the DAT card.

   * Choose the subsidiary you are setting this integration up for.
   * Scroll to the Loadboard section and click the DAT card to open the configuration form.
3. Enter your credentials, filling in the following fields, then click Save to apply your settings.

   * **Service account email:** The dedicated email DAT set up for your integration.
   * **Username:** An email address under your DAT account that will be used to post loads.
   * **Service account password:** The password DAT provided for your service account.
   * **Default posting email:** The email that will appear in the comments on your posted loads. This can be the same as your username.

     <img alt="DAT card in the Loadboard section of the Integrations page." />

     *DAT card in the Loadboard section of the Integrations page.*

     <img alt="DAT Add Integration credentials form." />

     *DAT Add Integration credentials form.*

## What syncs

The following fields from your Alvys load are sent to DAT when a load is posted: origin and destination addresses, equipment type, pickup date, load board rate, default posting email, and username (used as the posting account on DAT).

Only brokerage loads are eligible for posting. Loads tendered as a carrier type are not posted to DAT; if a previously posted load's tender type changes to carrier, the posting is automatically removed. Only loads in an **Open**, **Quoted**, or **Reserved** status are posted. Loads in any other status are not eligible.

There are two ways loads reach the DAT load board:

* **Auto-sync:** When auto-sync is enabled, Alvys sends eligible loads to DAT automatically on a recurring schedule. Loads that meet the criteria (brokerage type, **Open**/**Quoted**/**Reserved** status, positive weight) are included in each sync run. If an existing posting's lane, equipment type, period, or rate has changed, the posting is updated. If a load is no longer eligible, its posting is removed.
* **Manual post:** You can post any individual load at any time by opening the load's detail page and clicking Post Shipment. This option is available regardless of whether auto-sync is on or off.

After a load is posted, the load board displays a "Posted To: DAT" label and the DAT icon on that load's row.

<img alt="Auto-sync toggle" />

\*Auto-sync toggle \*

<img alt="Post Shipment button on a load detail page." />

*Post Shipment button on a load detail page.*

<img alt="'Posted To: DAT' label and DAT icon on the load board." />

*"Posted To: DAT" label and DAT icon on the load board.*

To confirm the integration is working:

1. Open a brokerage load in **Open**, **Quoted**, or **Reserved** status with a positive weight.
2. Click Post Shipment on the load detail page.
3. Confirm the load board shows the "Posted To: DAT" label and the DAT icon on that load.

If the button does not appear or the posting does not go through, see Troubleshooting below.

<Note>
  📋 Limits and unsupported: Only brokerage loads are posted to DAT — loads tendered as a carrier type are not eligible. · Loads must have a positive weight to be included in auto-sync. · The integration is configured per subsidiary; each subsidiary requires its own DAT credentials. · There is no bulk-delete option for removing multiple postings at once.
</Note>

## Troubleshooting

### Post Shipment button is not visible on a load

1. Confirm the user has the **"MarketplacePostLoads"** permission enabled. Without this permission, the posting controls do not appear.
2. Confirm the load is a brokerage load. Loads tendered as a carrier type are not eligible for DAT posting and will not show Post Shipment.
3. Confirm the load is in **Open**, **Quoted**, or **Reserved** status. Loads in any other status are not eligible for posting.

### Load does not appear on DAT after posting

1. Confirm the DAT credentials saved in Integrations are correct. An invalid service account email, username, or password will cause posting to fail silently.
2. Confirm the load has a positive weight value. Loads with zero or missing weight are excluded from DAT postings.
3. If credentials are correct and the load meets all eligibility criteria, contact Alvys support and reference the load number so the technical team can investigate the posting response from DAT.

### Auto-sync is not posting loads

1. Confirm auto-sync is enabled on the DAT card in Integrations.
2. Confirm there are eligible loads in **Open**, **Quoted**, or **Reserved** status with a positive weight. If no loads meet the criteria, the sync run completes without posting anything.
3. If auto-sync appears enabled and eligible loads exist but are not posting, contact Alvys support.

## FAQs

**Q: What if I don't have a DAT Load Board license?**

**A:** You need a Load Board license and a service account with API access from DAT before you can set up this integration. Contact DAT directly to acquire them.

**Q: Can I post loads if auto-sync is disabled?**

**A:** Yes. You can always manually post individual loads using the Post Shipment button on the load detail page, regardless of your auto-sync settings.

**Q: What happens if a user does not have posting permission?**

**A:** Without the **"MarketplacePostLoads"** permission enabled, the user will not see the option to post loads to DAT. An admin must enable this permission in the user's settings.

**Q: Can I post loads from multiple subsidiaries?**

**A:** Yes, but each subsidiary must have its own DAT credentials configured separately in the Integrations section.

## Go Deeper

* [Marketplace](/en/help/integrations/alvys-carrier-marketplace)


# QuickBooks Desktop: Overview
Source: https://docs.alvys.com/en/help/integrations/quickbooks-desktop-integration-collection

Every article for setting up, using, and troubleshooting the QuickBooks Desktop integration with Alvys via the QBWC, ordered by recommended configuration path.

<Note>
  This collection covers all articles for configuring, using, and troubleshooting the QuickBooks Desktop (QBD) integration with Alvys. Follow the recommended order to get started, or jump to a specific topic using the links below.
</Note>

## Overview

The QuickBooks Desktop integration connects Alvys to QBD through the QuickBooks Web Connector. This collection contains six articles covering prerequisites, connection setup, account mappings, transaction export logic, payment synchronization, and error resolution. Each article builds on the previous one; completing them in order is recommended for new setups.

### 1. QuickBooks Desktop: Prerequisites

**Purpose:** This article outlines the essential architectural decisions and environment requirements before initiating the integration. It covers the four core software components (Web Connector, QWC, QBW), selecting your setup type (Single-User, Multi-User, or Hosted), system access requirements, and the mandatory structure for the Chart of Accounts.

**Article:** [QuickBooks Desktop: Prerequisites (Start Here)](/en/help/integrations/how-to-prepare-quickbooks-desktop-before-connecting-to-alvys)

### 2. Connection and Configuration Settings in Alvys

**Purpose:** This guide provides step-by-step instructions for establishing the technical bridge between Alvys and QBD using the QuickBooks Web Connector. It explains how to download the configuration files, authorize the security handshake, and configure operational toggles such as Revenue/Expense exports, Driver Bill logic, and Subsidiary/Fleet mapping.

**Article:** [QuickBooks Desktop: Connection and Configuration Settings](/en/help/integrations/how-to-connect-quickbooks-desktop-to-alvys-and-configure-settings#h_02b9cb1deb)

### 3. Account Mappings (Default and Specific)

**Purpose:** This article explains how to link Alvys transaction line items to your QuickBooks Chart of Accounts. It covers mandatory default fallback accounts (A/R, A/P, Revenue, Expense) as well as granular mappings for Load, Trip, Accessorials, E-checks, Deductions, Fuel, Tolls, and Escrow.

**Article:** [QuickBooks Desktop: Account Mappings](/en/help/integrations/how-to-set-up-quickbooks-desktop-account-mappings-in-alvys)

### 4. Transaction Export and Modification Workflow

**Purpose:** This article details the logic Alvys uses to route data to QBD based on the Invoice As and Tender As fields. It explains how customers and vendors are automatically created or linked and provides the workflow for modifying, regenerating, or reverting transactions once they have been exported.

**Article:** [QuickBooks Desktop: Transaction Export and Modification Workflow](/en/help/integrations/how-to-export-and-modify-transactions-in-quickbooks-desktop)

### 5. Alvys Payment Synchronization

**Purpose:** This article explains the synchronization of payments between Alvys and QuickBooks Desktop. It outlines how transaction statuses are updated and provides clarity on which modules (such as Driver Settlements) support sync and which require manual updates (such as Carrier Settlements). Note: Customer Payment Export is not supported for QuickBooks Desktop.

**Article:** [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)

### 6. Identifying and Resolving Failed Transactions

**Purpose:** This troubleshooting guide explains how to use the Error Transactions page in Alvys to manage the export queue. It provides specific resolution steps for common Web Connector errors (like QBWC1039) and data-related errors (like Duplicate Names or Edit Sequence issues).

**Article:** [QuickBooks Desktop: Identifying and Resolving Failed Transactions](/en/help/integrations/identifying-and-resolving-failed-quickbooks-desktop-transaction-exports)


# QuickBooks Online: Resolve failed transactions
Source: https://docs.alvys.com/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions

Fix failed QuickBooks Online exports in Alvys: resolve duplicate document numbers, name conflicts, invalid account types, and closed-period rejection errors.

<Note>
  This article explains how to locate failed QuickBooks Online transactions in Alvys and how to resolve the most common QBO API rejections, including duplicate document numbers, duplicate name conflicts, invalid account types, and closed accounting period errors.
</Note>

## Overview

A transaction sent from Alvys to QuickBooks Online can be rejected by QBO when the data conflicts with QBO's rules. This guide (also covering QBO sync failures and export errors) shows you how to find each failed export in the[ Error Transactions queue](https://app.alvys.com/#/accounting/error-help), interpret the QBO error message, correct the underlying issue, and re-export so the invoice or bill records successfully. The page is accessible from the “**Accounting**” menu by selecting Error Transactions within Alvys.

<Note>
  <img alt="Image showing Alvys error Transactions Page" />

  \*Image showing Alvys error Transactions Page \*
</Note>

## Symptom

A transaction exported from Alvys to QuickBooks Online has failed. The transaction appears in the Error Transactions queue in Alvys with an error message from QBO, and the corresponding invoice or bill is not visible in QBO.

## Cause

QBO rejects an export when the transaction contains data that conflicts with QBO's rules. The most common causes are:

* Duplicate document numbers: a QBO customer already has an invoice with the same invoice number.
* Duplicate name conflicts: Alvys attempted to create a new customer or vendor in QBO but a record with that name already exists (possibly a different type or with special characters).
* Invalid account type: the QBO account mapped in Alvys is not the correct type for that transaction (for example, an income account was mapped where an expense account is required).
* Closed accounting period: the transaction date falls within a period that has been closed in QBO.

## Resolution

### Open the Error Transactions queue

Navigate to Management > Integrations in Alvys. Locate the Error Transactions section (also called the Error Queue). This view lists every failed export with the error message returned by QBO.

**The Error Transactions page includes the following columns:**

* **Entity Type:** The type of Alvys transaction that failed to export, showing where the transaction originated. Examples include Load, Trip, Paystub, Deduction, Accessorial Revenue, Toll, Fuel, Escrow, E-check, and Accounting Invoice.
* **Transaction Type:** How the record is classified in the external accounting system, such as Invoice, Bill, Credit Memo, Vendor Credit, or Journal Entry.
* **Class:** The subsidiary associated with the transaction.
* **Error Message**: The message returned by QBO explaining why the transaction failed.
* \*\*Status: \*\*The current state of the transaction, such as Failed or Resolved.
* **Reference**: Additional identifiers to link the transaction, such as load number, summary invoice number, or trip number.
* **Transaction Total**: The total amount of the transaction.
* **Date Created**: The date the transaction was first attempted to be exported.

### Read the error message and apply the matching fix

Click on a failed transaction to view the full QBO error message. Match the message to the appropriate resolution below.

### Resolving duplicate document numbers

This error means a QBO customer already has an invoice with the number Alvys tried to push. Alvys uses the Alvys load number as the invoice number when QBO's Custom transaction numbers setting is enabled.

1. In QBO, find the existing invoice with the duplicate number and determine whether it is a valid transaction or a prior import error.
2. If the existing QBO invoice is a duplicate or error, void or delete it in QBO.
3. Return to Alvys, select the failed transaction in the Error Queue, and click **Re-export**.

If the QBO invoice with that number is a legitimate transaction that happens to share the same number, you must change the invoice number on the Alvys load before re-exporting. Open the load, edit the invoice number, and then re-export.

### Resolving duplicate name conflicts

This error means QBO rejected the creation of a new customer or vendor because a record with the same name already exists, possibly under a different entity type or with a slight name variation.

<Note>
  <img alt="Image displaying the Error Transactions page with the duplicate document error for a transaction" />

  \*Image displaying the Error Transactions page with the duplicate document error for a transaction \*
</Note>

1. In QBO, search the Customer and Vendor lists for a record with the same or similar name.
2. Determine the correct entity type. If the record exists as a customer but Alvys is trying to create it as a vendor (or vice versa), you may need to adjust the Invoice As or Tender As field in Alvys to match the exact QBO name.
3. Once the QBO record is resolved, return to Alvys and click **Re-export** on the failed transaction.

### Resolving invalid account type errors

This error means the account mapped in Alvys for this line item type is not the correct QBO account type (for example, a bank account or equity account was selected instead of an income or expense account).

<Note>
  <img alt="Image displaying the Error Transactions page with the invalid account error for transactions." />

  *Image displaying the Error Transactions page with the **invalid account** error for transactions.*
</Note>

1. Navigate to Management > Integrations > Account Mappings in Alvys.
2. Locate the mapping for the line item type mentioned in the error message and change it to the correct QBO account type.
3. Return to the Error Queue, select the failed transaction, and click **Re-export**.

### Resolving closed accounting period errors

This error means the transaction date falls within an accounting period that has been closed in QBO.

<Note>
  <img alt="Image displaying the Error Transactions page with the closed accounting period error for transactions" />

  *Image displaying the Error Transactions page with the **closed accounting period** error for transactions*
</Note>

1. Log in to QBO and navigate to Settings > Advanced > Accounting.
2. Review the closing date. If you can open the period (remove the closing date or move it to an earlier date), do so.
3. Return to Alvys, select the failed transaction, and click **Re-export**.

If you cannot open the accounting period, you may need to adjust the transaction date on the load in Alvys to fall within an open period before re-exporting. Contact your accounting team to determine the correct resolution for your books.

### Resolving Object Not Found errors (Error 610)

This error means the transaction was successfully sent to QuickBooks Online at an earlier time but the record was later deleted or merged in QBO.

<Note>
  <img alt="Image displaying the Error Transactions page with the Object Not Found error for transactions" />

  *Image displaying the Error Transactions page with the **Object Not Found** error for transactions*
</Note>

Contact Alvys Support and include the load number and error message. Support will reset the transaction so a new record can be sent to QBO.

### Resolving transaction linking errors (Error 620)

This error occurs when a payment cannot be linked to an invoice because the customer name on the payment does not exactly match the customer name on the invoice in QuickBooks Online.

<Note>
  <img alt="Image displaying the Error Transactions page with the transaction linking error  for transactions" />

  \*Image displaying the Error Transactions page with the \**transaction linking error \*\* for transactions*
</Note>

Contact [Alvys Support](mailto:support@alvys.com) and include the load number and error message. Support will resync the payment after the names are aligned. You cannot resolve this error from the Error Transactions page.

### Resolving invalid reference ID errors (Error 2500)

This error means the general ledger account referenced in the transaction was deleted or made inactive in QuickBooks Online after the account mapping was configured in Alvys.

1. In QBO, go to **Settings > Chart of Accounts**.
2. Find the account referenced in the error message and reactivate it.
3. Return to Alvys, select the failed transaction in the Error Queue, and retry the sync.

### Resolving business validation errors (Error 6000)

This error typically means the account mapped for Customer Deposits in Alvys is not the correct account type in QuickBooks Online. QBO requires this account to be either **Bank** or **Other Current Asset** type.

1. In QBO, go to **Settings > Chart of Accounts** and verify that the Customer Deposits account is set to the **Bank** or **Other Current Asset** type.
2. In Alvys, go to **Management > Integrations > Account Mappings** and update the Customer Deposits mapping if needed.
3. Contact Alvys Support to resync the affected transaction.

### Re-export the transaction

After resolving the underlying issue, select the corrected transaction in the Error Queue and click **Re-export**. Alvys resubmits the transaction to QBO.

**Supported Transaction Types That Can Be Re-Synced from Error Transactions**

Not all transactions can be automatically re-synced from this page. Currently, only the following entity types can be re-synced:

* **Load**
* **Trip**
* **E-check**
* **Paystub**

### Verify in QBO

Log in to QBO and confirm the invoice or bill now appears under the correct customer or vendor with the expected amounts and reference numbers.

## Clearing an error transaction you already fixed in QuickBooks Online

If you corrected a transaction directly inside QuickBooks Online rather than re-syncing it from Alvys, you can mark it as resolved in Alvys to remove it from the Error Transactions list.

Select the transaction in the Error Transactions list, right-click, and select **Mark as Synced**. Confirm the action when prompted. The transaction is removed from the Error Transactions queue.

## Troubleshooting

### The error persists after applying the resolution steps

If the error continues after following the resolution steps above:

* Confirm the QBO integration is still connected at Management > Integrations. If the connection shows as expired or disconnected, reconnect the integration and retry the export.
* Confirm the account mappings are saved correctly and that no mapping references a QBO account that has been deactivated or deleted in QBO.
* If the error message is not covered by the cases above or the same error appears after re-exporting, contact Alvys Support and include the load number, the exact QBO error message, and the steps already taken.

## FAQs

**Q: Where can I see a list of all transactions that failed to sync with QuickBooks?**

**A:** Go to Accounting > Error Transactions. This page shows every failed export along with the error message returned by QBO, the transaction total, and the associated load or trip reference number.

**Q: Which transactions can I re-sync from the Error Transactions page?**

**A:** Only Load, Trip, E-check, and Paystub transactions can be re-synced directly. Other types, including Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice (summary invoice), Escrow, Carrier Statement, and Driver Statement, cannot be re-synced from this page and must be corrected in their respective modules.

**Q: What should I do if I fixed an error manually inside QuickBooks Online?**

**A:** Select the transaction in the Error Transactions list, right-click, and choose Mark as Synced. This removes it from the queue without re-syncing from Alvys.

**Q: How do I resolve "Error 6430: Invalid Account Type"?**

**A:** The account type mapped in Alvys for that line item does not match what QBO expects. Verify the account type in QBO Chart of Accounts, update the mapping in the Alvys Integrations page, and re-sync the transaction.

**Q: What causes the "Duplicate Name Exists" error (Code 6240)?**

**A:** QBO requires globally unique names across all entity types. If a name already exists under a different entity type, add a distinguishing suffix in QBO (such as " (Vendor)") and retry.

**Q: Why am I getting an "Account Period Closed" error (Code 6200)?**

**A:** The transaction date falls within a period that has been locked in QBO. Either change the closing date in QBO (Settings > Advanced) to open the period, or update the transaction date in Alvys to fall within an open period.

**Q: What does "Object Not Found" (Error 610) mean?**

**A:** The transaction was previously sent to QBO but the record was later deleted or merged there. Contact Alvys Support to reset and resend the transaction.

**Q: Why can't a payment be linked to an invoice (Error 620)?**

**A:** The customer name on the payment does not exactly match the customer name on the invoice in QBO. Contact Alvys Support to resync after the names are aligned.

**Q: What should I do if I see "Invalid Reference ID" (Error 2500)?**

**A:** The general ledger account was deleted or made inactive in QBO after the mapping was configured. Reactivate the account in QBO Chart of Accounts and then retry the sync in Alvys.

**Q: Why did my invoice payment fail with a "Business Validation Error" (Code 6000)?**

**A:** The Customer Deposits account is not set to the Bank or Other Current Asset type in QBO. Update the account type in QBO Chart of Accounts, update the mapping in Alvys if needed, and contact Alvys Support to resync.

## Go Deeper

* [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys)
* [How to Map Accounts for QuickBooks Online](/en/help/integrations/how-to-map-accounts-for-quickbooks-online)
* [How to Export and Manage Transactions in QuickBooks Online](/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online)


# QuickBooks Online: Overview
Source: https://docs.alvys.com/en/help/integrations/quickbooks-online-integration-overview

Overview of the two-way QuickBooks Online integration with Alvys: export invoices and carrier bills to QBO and sync payment status back for AR and AP tracking.

<Note>
  Alvys integrates with QuickBooks Online (QBO) to sync invoices and carrier bills from Alvys into QBO and to receive payment status updates back into Alvys; this article explains what the integration does, what you need to set up in QBO before connecting, and where to find each configuration step.
</Note>

## Overview

The Alvys and QuickBooks Online integration creates a two-way accounting connection between your transportation management system and your accounting platform. Alvys exports customer invoices and carrier bills to QBO automatically once a load is processed for billing. Payment status then syncs back from QBO to Alvys so your team can see updated receivables and payables without manual data entry.

This article covers what the integration does, the QBO plan and account requirements you must meet before connecting, and links to every configuration step in the recommended setup order. Related terms: QuickBooks Online, QBO accounting sync, TMS accounting integration, invoice and bill export.

## Where to Find It

To access the QuickBooks Online integration settings, navigate to Management > Integrations in Alvys. You need the **"CompanyProfileManager"** permission to access and configure this page. This permission is available to users with the Admin, Support, or Partner Admin role.

## Key Concepts

**What syncs from Alvys to QBO**

Alvys pushes two types of transactions to QuickBooks Online:

* Customer invoices: created when a load is invoiced in Alvys and matched to the corresponding customer record in QBO.
* Carrier and vendor bills: created when a load's carrier payable or driver settlement is finalized in Alvys.

**What syncs from QBO back to Alvys**

When a payment is recorded in QBO against an invoice or bill, QBO returns the payment status to Alvys. This keeps your Alvys receivables and payables current without requiring duplicate data entry.

**QBO plan requirements**

QuickBooks Online offers four plan types: Simple Start, Essentials, Plus, and Advanced. The plan you use determines which Alvys features are available.

QBO Simple Start is not recommended for Alvys users. While it allows customer invoicing, it does not include the Accounts Payable module. Because the Bills feature is restricted on Simple Start, Alvys cannot sync carrier payables, driver settlements, or vendor obligations on this plan. Only the revenue side of your loads would be tracked.

QBO Essentials is the minimum required plan for a functional Alvys integration. It includes the Manage Bills feature, which allows Alvys to sync both customer invoices and carrier or vendor payables.

QBO Plus and QBO Advanced are the recommended plans for growing fleets and brokerages. These tiers support Location and Class Tracking, which are used in Alvys to segment financial data by terminal, department, or business division such as asset versus brokerage operations.

**Chart of Accounts preparation**

Before connecting Alvys to QBO, your Chart of Accounts must include the accounts Alvys will post transactions to. At a minimum, confirm you have accounts established for:

* Accounts Receivable: for customer invoicing.
* Accounts Payable: for carrier and vendor obligations.
* Income accounts: categorized for linehaul, fuel surcharges, and accessorials.
* Expense accounts: categorized for purchased transportation and driver settlements.

**Custom transaction numbers**

If you want QBO invoices to use your Alvys load numbers, you must enable the Custom transaction numbers toggle in QBO before connecting. This setting is in QBO at Settings (Gear Icon) > Account and Settings > Sales > Sales form content. Set Custom transaction numbers to ON. If this is left off, QBO ignores Alvys numbering and assigns its own sequential invoice numbers. This toggle applies to sales forms only; for bills, QBO allows Alvys to push the load ID or settlement ID into the reference number field without a separate toggle.

**Closed accounting periods**

If your QBO books are closed for a specific period, QBO will block Alvys from syncing any invoice or bill dated within that closed timeframe. Check your closing date in QBO at Settings > Advanced > Accounting before initiating exports.

**Custom fields**

Custom fields are available on all QBO plans. The number of custom fields you can create varies by subscription level.

## How to Use It

The QBO integration is set up and managed through a series of configuration steps. Complete them in the following order:

1. [QuickBooks Online Prerequisites (Start Here)](/en/help/integrations/quickbooks-online-prerequisites): configure your QBO plan, chart of accounts, open accounting periods, and custom transaction numbers before connecting.
2. [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys): authorize the OAuth connection between Alvys and QBO, and configure revenue and expense sync settings, driver bill consolidation, carrier invoice requirements, and subsidiary or fleet mapping.
3. [How to Map Accounts for QuickBooks Online](/en/help/integrations/how-to-map-accounts-for-quickbooks-online): link Alvys transaction line items to your QBO Chart of Accounts using both default fallback accounts and specific mappings for loads, trips, accessorials, and other line items.
4. [How to Export and Manage Transactions in QuickBooks Online](/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online): understand how Alvys routes data to QBO, how customers and vendors are matched or created in QBO, and the protocols for modifying or reverting exported transactions.
5. [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations): understand how manual and factoring-based payments export to QBO and how QBO payment records sync back to Alvys.
6. [QuickBooks Online: Identifying and Resolving Failed Transactions](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions): manage the export queue and resolve common QBO API errors.

## Settings and Permissions

Access to the Integrations page requires the **"CompanyProfileManager"** permission. Users without this permission will not see the Integrations option in their account menu. This permission is available to users with the Admin, Support, or Partner Admin role.

Only one QBO company file can be connected per Alvys legal entity. If your organization has multiple legal entities in Alvys, each entity must be connected to its corresponding QBO company file separately.

## Limits and Behavior

* The integration requires QBO Essentials or higher. Simple Start does not support the Accounts Payable module and cannot receive carrier bills or driver settlements from Alvys.
* Transactions dated within a closed QBO accounting period will be blocked by QBO and will not sync. Open the relevant period in QBO first, then re-export the affected transactions from Alvys.
* If Custom transaction numbers is not enabled in QBO before the connection is made, QBO will assign its own sequential numbers to invoices and will not use Alvys load numbers.
* Location and Class Tracking, used to map Alvys subsidiaries and fleets to QBO segments, requires QBO Plus or QBO Advanced.

## FAQs

**Q: Which QuickBooks Online plan is the minimum requirement for the Alvys integration?**

**A:** QBO Essentials is the minimum required plan because it includes the Manage Bills feature. Simple Start allows customer invoicing but does not support the Accounts Payable module needed to sync carrier payables and driver settlements.

**Q: Why are QBO Plus and Advanced recommended over Essentials?**

**A:** QBO Plus and Advanced support Location and Class Tracking, which are used in Alvys to segment financial data by terminal, department, or business division such as asset versus brokerage operations.

**Q: What accounts must be in my Chart of Accounts before syncing?**

**A:** At a minimum you must have accounts for Accounts Receivable, Accounts Payable, Income (for linehaul, fuel surcharges, and accessorials), and Expense accounts (for purchased transportation and driver settlements).

**Q: Are custom fields supported on all QBO plans?**

**A:** Yes, custom fields are available on all QBO plans. The number of fields you can create varies depending on your subscription level.

**Q: Does the Custom Transaction Numbers setting apply to bills as well as invoices?**

**A:** No. The Custom transaction numbers toggle applies to sales forms only. For bills, QBO allows Alvys to push the load ID or settlement ID into the reference number field without a separate toggle.

**Q: What happens if my QBO accounting period is closed when Alvys tries to export a transaction?**

**A:** QBO will block the export and the transaction will appear in the Error Transactions page in Alvys. Open the relevant period in QBO at Settings > Advanced > Accounting, then re-export the transaction from Alvys. If you cannot open the period and the error persists, contact Alvys Support.

## Go Deeper

* [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys)
* [How to Map Accounts for QuickBooks Online](/en/help/integrations/how-to-map-accounts-for-quickbooks-online)
* [How to Export and Manage Transactions in QuickBooks Online](/en/help/integrations/how-to-export-and-manage-transactions-in-quickbooks-online)
* [QuickBooks Online: Identifying and Resolving Failed Transactions](/en/help/integrations/quickbooks-online-identifying-and-resolving-failed-transactions)


# QuickBooks Online: Prerequisites
Source: https://docs.alvys.com/en/help/integrations/quickbooks-online-prerequisites

Prepare your QuickBooks Online account for the Alvys sync: plan type, admin access, chart of accounts, class tracking, and QBO invoice settings.

<Note>
  Before connecting Alvys to QuickBooks Online, complete these account configurations in QuickBooks Online. Skipping these steps can cause sync errors, mismatched data, or a failed connection after the integration is active.
</Note>

## Overview

This article covers the account-level configurations required in QuickBooks Online before connecting to Alvys. Complete all five areas below. Each section describes a setting or condition that must be in place for the integration to work correctly.

## QuickBooks Online Plan Types

Not all QuickBooks Online plans support the features required for the Alvys integration.

* **Simple Start** does not include the Accounts Payable module and is not recommended for use with Alvys.
* **Essentials** is the minimum supported plan. It includes the "Manage Bills" feature required for the Alvys integration.
* **Plus** and **Advanced** are recommended. These plans support Location and Class Tracking, which enables more detailed financial reporting in QuickBooks Online.

## Administrative Access

You must have Admin credentials for your QuickBooks Online account to complete the integration setup. Non-admin access does not have the permissions required to configure account settings or connect third-party integrations.

<Note>
  <img alt="Error screen when non-admin user tries to add the integration" />

  *Error screen when non-admin user tries to add the integration*
</Note>

## Chart of Accounts Preparation

Before connecting to Alvys, confirm that your QuickBooks Online Chart of Accounts includes the following accounts at minimum:

* **Accounts Receivable:** For customer invoicing.
* **Accounts Payable:** For carrier and vendor obligations.
* **Income Account:** Categorized for Linehaul, Fuel Surcharges, and Accessorials.
* **Expense Account:** Categorized for Purchased Transportation (Brokerage costs) and Driver Settlements.

If any of these accounts are missing, create them in QuickBooks Online before connecting.

### How to create an account in QuickBooks Online?

* Navigate to the Chart of Accounts section in QuickBooks Online.

<Note>
  <img alt="Screenshot showing the Chart of Accounts navigation in QuickBooks Online (via All Apps or Accounting menu)" />

  *Screenshot showing the Chart of Accounts navigation in QuickBooks Online (via All Apps or Accounting menu)*
</Note>

* Click **New**.

<Note>
  <img alt="Screenshot showing the green New button in the QuickBooks Online Chart of Accounts view" />

  * Screenshot showing the green New button in the QuickBooks Online Chart of Accounts view\*
</Note>

* Enter the account details: select the account Category and enter a Name.
* Click **Save and Close** to confirm the account.

## Validate Open Accounting Periods

Confirm that your accounting periods are open for the dates you plan to sync. In QuickBooks Online, navigate to Settings > Advanced > Accounting and review the Closing Date field. If a closing date is set that covers recent periods, transactions from those periods may not sync correctly.

## Custom Transaction Numbers

Alvys sends its own transaction numbers when syncing invoices to QuickBooks Online. For these numbers to be preserved, Custom Transaction Numbers must be turned on in QuickBooks Online.

<Note>
  <img alt="Screenshot showing the Custom Transaction Numbers toggle in QuickBooks Online under Settings > Account and Settings > Sales > Sales form content." />

  *Screenshot showing the Custom Transaction Numbers toggle in QuickBooks Online under Settings > Account and Settings > Sales > Sales form content.*
</Note>

To enable Custom Transaction Numbers:

1. In QuickBooks Online, navigate to Settings > Account and Settings > Sales.
2. Under Sales form content, locate the **Custom transaction numbers** toggle.
3. Turn Custom transaction numbers **On**.
4. Click **Save**.

<Warning>
  ⚠️ If Custom transaction numbers is turned off, QuickBooks Online ignores the transaction numbers sent by Alvys and assigns its own sequential numbers instead. Turn this setting on before connecting Alvys to avoid numbering mismatches.
</Warning>

## FAQs

**Q: Which QuickBooks Online plan is the minimum requirement for the Alvys integration?**

**A:** Essentials is the minimum supported plan. It includes the "Manage Bills" feature required for the integration. Simple Start does not include Accounts Payable and is not recommended.

**Q: Why is QuickBooks Online Plus or Advanced recommended?**

**A:** Plus and Advanced plans support Location and Class Tracking, which enables more detailed financial reporting in QuickBooks Online when syncing from Alvys.

**Q: What accounts must I have in my Chart of Accounts before connecting?**

**A:** At minimum, you need Accounts Receivable, Accounts Payable, Income accounts (Linehaul, Fuel Surcharge, Accessorials), and Expense or Cost of Goods Sold accounts (Purchased Transportation, Driver Settlements).

**Q: Does the Custom Transaction Numbers setting apply to Bills as well as Sales forms?**

**A:** No. The Custom Transaction Numbers setting only applies to Sales forms such as invoices. Bills use the Reference Number field automatically.

**Q: Are custom fields in QuickBooks Online supported across all plans?**

**A:** Custom fields are available across QuickBooks Online plans, but the number of custom fields available may vary by subscription.

## Go Deeper

* [How to Connect and Configure QuickBooks Online in Alvys](/en/help/integrations/how-to-connect-and-configure-quickbooks-online-in-alvys)
* [QuickBooks Online Integration Overview](/en/help/integrations/quickbooks-online-integration-overview)


# RMIS Integration
Source: https://docs.alvys.com/en/help/integrations/rmis-integration

Sync RMIS carrier compliance data — safety ratings, insurance, authority, and certifications — into Alvys so you can vet carriers without leaving the platform.

<Note>
  Connect RMIS to Alvys to automatically sync carrier compliance data — including safety ratings, insurance, authority information, certification status, and payment methods — so you can validate carrier compliance without leaving Alvys.
</Note>

## What This Integration Does

RMIS (also known as Risk Management Innovative Solutions, provided by TSI) connects to Alvys to automatically import carrier compliance data. Once active, you can view carrier safety ratings, insurance, and authority information directly from the carrier profile in Alvys without switching to RMIS.

The integration also imports carrier certification status and pay-to payment methods, reducing manual data entry during carrier onboarding.

## Prerequisites

Before connecting RMIS to Alvys, you need:

* An active RMIS account with integration credentials from TSI
* Admin or Partner Admin access in Alvys to configure integrations under Management > Integrations
* API credentials (Client ID and Password) provided by RMIS/TSI — you must request these by email before configuring the integration in Alvys

## Connect / Authenticate

### Request integration credentials from TSI

Send a request to TSI at [tsi@truckstop.com](mailto:tsi@truckstop.com) asking them to provide account integration credentials. Once you receive your Client ID and Password, proceed to the next step.

### Configure the RMIS integration in Alvys

Navigate to [Integrations](https://app.alvys.com/#/manage/integrations) in Alvys. Find the RMIS integration in the Compliance section and click the pencil icon to open the configuration settings.

<img alt="Alvys Integrations page showing the Compliance section with the RMIS integration box" />

\*Alvys Integrations page showing the Compliance section with the RMIS integration box \*

Enter your Client ID and Password provided by RMIS/TSI, then select which subsidiaries should use the integration. Click Save to complete the setup.

### Test the integration

After saving your credentials, verify that data is syncing correctly:

Update a carrier in RMIS and wait approximately 10 minutes. If the carrier is added or updated in Alvys, the integration is working correctly.

### Request a Delta push for existing carriers

Once the integration is active, send an additional email to [tsi@truckstop.com](mailto:tsi@truckstop.com) requesting that all existing carriers be pushed to the Delta overnight. This will import all your existing RMIS carriers into Alvys. Without this step, only new or updated carriers will sync going forward.

## Field & Data Mapping

The integration imports the following carrier information from RMIS into Alvys:

**Carrier profile**

* Name
* MC number and DOT number
* Address
* Contact information

  **Insurance coverage**
* Coverage type
* Policy number
* Issue and expiration dates
* Limit amount
* Underwriter (insurance agency)

  **W9 information**
* SSN (where available)
* TIN (where available)

  **Pay-to information**
* Factoring company (when IsFactoring is true)
* Pay-to name and address

Important: pay-to data is only imported if the carrier is being imported into Alvys for the first time. If the carrier was manually created in Alvys or is being updated, payment information is not imported and must be manually updated in Alvys.

## Sync Behavior

* After a carrier is updated in RMIS, changes take approximately 10 minutes to appear in Alvys.
* Sync is one-way: data flows from RMIS into Alvys only. Changes made in Alvys do not update RMIS.
* The Delta push (requested from TSI after initial setup) imports all existing RMIS carriers into Alvys overnight. Without it, only new or updated carriers sync going forward.
* Pay-to information is only imported on first-time carrier import. It is not overwritten on subsequent updates.

## Verify It's Working

After completing setup and the Delta push, confirm the connection is working:

Navigate to the Carriers page in Alvys and open a carrier profile. If carrier safety ratings, insurance, and authority information appear on the profile, the integration is active.

## Troubleshooting

### Carrier updates not appearing in Alvys

**Step 1:** Confirm you have waited at least 10 minutes after updating the carrier in RMIS. The sync interval is approximately 10 minutes.

**Step 2:** Verify the integration credentials (Client ID and Password) were entered correctly in Alvys under Management > Integrations > RMIS.

**Step 3:** If the carrier still does not appear after 10 minutes, contact Alvys support to confirm the integration is active and credentials are valid.

### Existing carriers not appearing after setup

**Step 1:** Confirm you sent a Delta push request to [tsi@truckstop.com](mailto:tsi@truckstop.com) after activating the integration. The Delta push is required to import all existing RMIS carriers into Alvys.

**Step 2:** The Delta push runs overnight. Wait until the following day after sending the request to TSI before expecting all carriers to appear in Alvys.

**Step 3:** If carriers are still not appearing after the overnight Delta push, contact Alvys support.

### Payment information is not updated on a carrier profile

**Step 1:** Confirm whether the carrier was manually created in Alvys before the RMIS integration was connected. Pay-to information is only imported when a carrier is first imported from RMIS. If the carrier already existed in Alvys, payment information must be updated manually.

**Step 2:** Update the carrier's payment details manually in Alvys if needed.

## Limits / Unsupported

* Pay-to information is only imported on first-time carrier import from RMIS. It is not overwritten on subsequent syncs or for carriers that already exist in Alvys.
* The integration is one-way. You cannot push carrier data from Alvys to RMIS.
* The integration syncs approximately every 10 minutes, not in real time.

## FAQs

**Q: How long does it take for carrier updates to sync?**

**A:** After updating a carrier in RMIS, wait approximately 10 minutes for the changes to appear in Alvys.

**Q: What happens to carriers I created manually in Alvys?**

**A:** If a carrier already exists in Alvys when you set up RMIS, their profile will be updated with compliance data, but payment information will not be overwritten. You will need to update payment details manually if needed.

**Q: Why do I need to request a Delta push from TSI?**

**A:** The Delta push ensures all your existing RMIS carriers are imported into Alvys overnight. Without this step, only new or updated carriers will sync going forward.

**Q: Can I see safety ratings directly in Alvys?**

**A:** Yes. Once the integration is active, you can view carrier safety ratings, insurance, and authority information directly from the carrier profile in Alvys without switching to RMIS.

## Go Deeper

* [Why Am I Seeing an Override Authorization Error When Assigning a Carrier?](/en/help/loads-trips/override-authorization-error-when-assigning-a-carrier)
* [MyCarrierPackets (MCP) Integration](/en/help/integrations/mycarrierpackets-mcp-integration)


# Sage Intacct: Account mappings
Source: https://docs.alvys.com/en/help/integrations/sage-intacct-account-mappings

Configure Sage Intacct account mappings in Alvys so AR invoices and AP bills post to the right GL account using the three-level category and default fallback.

<Note>
  Account mappings (also called GL mappings or chart-of-accounts mappings) tell Alvys which Sage Intacct GL accounts to use when exporting AR invoices and AP bills. Mappings are organized by transaction category, and Alvys uses a three-level fallback to find the correct account for each line item.
</Note>

## Overview

When Alvys exports a transaction to Sage Intacct, it needs to know which GL account each line item belongs to. You configure this by mapping Alvys transaction types to Sage GL accounts in the Account Mappings section.

If a specific mapping is not set for a line item, Alvys falls back to the category default, then to the master default in the Default category. The Default category mapping is required: it must be configured before any transactions can export successfully.

**When Alvys sends a transaction to Sage, it decides which account to record it under by checking three levels in order:**

* **Specific match (most exact):** If the exact transaction type has its own account assigned, for example, an accessorial like \*Detention, \*Alvys uses that account.
* **Category default:** If no specific account is set, Alvys uses the default account for that category (for example, the **Accessorials** default).
* **Master default (backup):** If the category default isn't set either, Alvys falls back to the master **Default** account.

<Check>
  💡 Complete the setup wizard first (see \[2️⃣ **Sage Intacct: Connection and Settings Configuration**]). Configure the default account mappings during Step 3 (AP), Step 4 (AR), and complete specific mappings any time after setup from the **Account Mappings** tab.
</Check>

## Where to Find It

Go to Settings > Connections > Sage Intacct. Select the subsidiary whose mappings you want to configure. Click the Account Mappings tab.

## Key Concepts

### The Three-Level Fallback

When Alvys exports a line item, it looks for a GL account in this order:

1. Specific Item mapping: the mapping for that exact transaction type (for example, Loaded Miles under Trip).
2. Category Default: the default account set for that category (for example, the default Trip account).
3. Master Default: the Default Revenue Account (for AR) or Default Expense Account (for AP) in the Default category.

If no mapping exists at any level, the transaction will not export and will appear in Accounting > Error Transactions.

### GL Account Dropdown Format

When selecting a GL account, accounts appear in the format "Account ID - Account Name" and are grouped by account type. You must select from the accounts already configured in your Sage entity; Alvys does not create GL accounts.

### Default Category (Required)

The Default category contains the master fallback accounts for all transactions:

* \*\*Default Revenue Account: \*\*used for any AR line item that has no specific or category-level mapping.
* **Default Expense Account:** used for any AP line item that has no specific or category-level mapping.

These accounts must be mapped before any transactions can export. They cannot be cleared once set.

<Note>
  <img alt="Screenshot of the Default Account Mappings" />

  \*Screenshot of the Default Account Mappings \*
</Note>

## How to Use It

### Setting a Mapping

1. Expand the account category accordion you want to configure.
2. Click "Add Mapping" next to the line item you want to map.
3. Select the GL account from the dropdown. Accounts are shown as "Account ID - Account Name" grouped by account type.

<Note>
  <img alt="Image showing expanded account category" />

  \*Image showing expanded account category \*
</Note>

1. The mapping saves automatically. No Save button is required.

### Clearing a Mapping

To remove a specific mapping, click the X next to the mapped account. The Default Revenue Account and Default Expense Account in the Default category cannot be cleared; they are always required.

<Note>
  <img alt="Image showing expanded account category wth “Clear Selection” option" />

  *Image showing expanded account category wth “Clear Selection” option*
</Note>

## Account Categories

### Default (Required)

Contains the master fallback accounts for all transactions:

* Default Revenue Account (AR): fallback for any AR line item without a specific or category-level mapping.
* Default Expense Account (AP): fallback for any AP line item without a specific or category-level mapping.

This category must be fully mapped before enabling any sync. It cannot be left unmapped.

### Load (AR Only)

The Load category controls how load-level revenue line items on customer invoices are recorded in Sage Intacct. When Alvys exports an invoice, each line item representing a charge on the load is mapped using this category.

**Mappable items:**

* **Load** (default): The fallback GL account used for any load-level revenue line item that does not match one of the more specific items below.
* **Customer Linehaul:** The base linehaul charge billed to the customer. This is typically the largest portion of the invoice and represents your freight transportation revenue.
* **Fuel Surcharge:** The fuel surcharge (FSC) line item billed to the customer, often calculated as a percentage of linehaul or as a per-mile rate.

### Trip (AP Only)

The Trip category controls how trip-level cost line items on carrier and driver bills are recorded in Sage Intacct. In Alvys, a load can have one or more trips. Each trip represents a leg of the shipment, and the costs associated with that trip (such as driver pay rates and carrier rates) are mapped to GL accounts using this category.

<Note>
  <img alt="Image showing the Trip category" />

  *Image showing the Trip category*
</Note>

**Mappable items:**

* **Trip (default):** The fallback account used for any trip-level cost that isn't specifically mapped below.
* **Carrier Linehaul:** The base linehaul rate paid to a carrier for hauling a trip. This is the main carrier cost on brokerage loads.
* **Driver Payment:** The linehaul payment amount paid to a company driver for a trip.

  In addition to the items above, all trip-based driver pay types from your pay policies are automatically included in this category. These represent the different ways drivers can be paid per trip:
* **Per Trip:** A flat rate paid for each trip.
* **% of Trip Value:** A percentage of the total trip revenue.
* **Total Miles:** A rate based on total miles driven (loaded plus empty).
* **Loaded Miles:** A rate based on loaded miles only.
* **Empty Miles:** A rate based on empty (deadhead) miles only.
* **Per Stop:** A rate paid for each stop on the trip.
* **% of Fuel Surcharge:** A percentage of the customer's fuel surcharge.
* **% of Line Haul:** A percentage of the customer's linehaul rate.
* **Service Fee:** A flat service fee applied to the trip.
* **Per Load:** A flat rate paid per load.
* **Per Customer Stop:** A rate paid for each customer stop.
* **Per Hour:** An hourly rate for the trip.
* **Mileage Per Diem:** A per diem amount based on mileage.
* **Per Mile:** A rate paid for each mile driven.
* **% of Line Haul Deduction:** A trip-level deduction taken as a percentage of the linehaul.
* **% of Trip Value Deduction:** A trip-level deduction taken as a percentage of the trip value.

### Driver Statement Expenses (AP Only)

The Driver Statement Expenses category covers statement-level driver compensation, which includes recurring pay items that appear on a driver's settlement but are not tied to a specific trip.

<Note>
  <img alt="Image showing the Driver Statement Expenses Category" />

  *Image showing the Driver Statement Expenses Category*
</Note>

**Mappable items:**

* **Driver Statement Expense (default):** The fallback account used for any statement-level expense that isn't specifically mapped below.
* **Minimum Pay:** The minimum guaranteed pay for a statement period. If a driver's trip-based earnings fall below this amount, the difference is added as a Minimum Pay line item.
* **Bonus:** Bonus payments added to driver settlements, such as safety, referral, or performance bonuses.
* **Per Day:** A daily rate paid to the driver for each active day in the statement period.
* **Daily Per Diem:** A daily allowance for meals and incidental expenses, paid per day.
* **Statement Per Diem:** A per diem allowance paid once per statement period rather than daily.

<Check>
  💡 If your company does not use driver settlements or does not have the **Include driver bills** setting enabled in AP, this category will not be used.
</Check>

### Accessorials (AR and AP)

The Accessorials category covers additional charges beyond the base linehaul and fuel surcharge—charges for services like detention, layover, lumper fees, TONU (truck order not used), and any other accessorial types your company has defined in Alvys.

**Mappable items:**

* **Accessorial** \*\*(default) \*\*: The fallback GL account for any accessorial charge not specifically mapped below.
* **Your custom accessorial types:** Every accessorial type you have created in Alvys (such as Detention, Layover, Lumper, Stop-off, or TONU) appears as a mappable item. These are pulled dynamically from your company's accessorial list.

Since this category applies to both AP and AR, the mapping table shows two GL account columns — one for AP (what you pay carriers/drivers for that accessorial) and one for AR (what you charge customers for that accessorial). You can map each side to different GL accounts.

<Note>
  <img alt="Image showing the Accessorials Category" />

  *Image showing the Accessorials Category*
</Note>

**Example:** You might map Detention on the AR side to a "Detention Revenue" account and Detention on the AP side to a "Detention Expense" account.

<Check>
  💡 If you add a new accessorial type in Alvys, it will automatically appear in this category. Until you assign it a specific GL account, it falls back to the Accessorial default.
</Check>

### E-checks (AR and AP)

The E-checks category covers electronic check transactions. E-checks in Alvys are used for various payment types that flow through electronic check processing.

<Note>
  <img alt="Image showing the E-checks Category" />

  *Image showing the E-checks Category*
</Note>

**Mappable items:**

* **E-Check** *(default)* : The fallback GL account for any e-check transaction not specifically mapped below.
* **Your custom e-check types** : Every accessorial type you have created in Alvys appears as a mappable item, pulled dynamically from your company's e-check type list.

Like Accessorials, this category supports both AP and AR with separate GL account columns for each side.

### Deductions (AP Only)

The Deductions category covers amounts deducted from driver settlements recurring charges like insurance premiums, cash advances, equipment leases, IFTA fees, and other withholdings.

<Note>
  <img alt="Image showing the Deductions Category" />

  *Image showing the Deductions Category*
</Note>

**Mappable items:**

**Deduction** *(default)* : The fallback GL account for any deduction not specifically mapped below.

**Alvys Predefined Deduction Types**. Common deduction types include:

* Cash advance / Cash advance repayment
* Insurance (health, liability, cargo, etc.)
* IRP (International Registration Plan) fees
* IFTA (International Fuel Tax Agreement) fees
* Equipment lease / Equipment purchase
* Fuel card advances
* Loan repayments
* Occupational accident insurance
* Plate fees
* ELD fees
* Toll charges

### Fuel (AP Only)

The Fuel category includes fuel transactions (such as diesel) linked to drivers or owner-operators. Each fuel type can be mapped to a specific GL account in Sage Intacct. If no specific account is mapped but a **Default Fuel Account** is configured, the transaction will use the Default Fuel Account. If neither a specific account nor a Default Fuel Account is configured, the transaction will fall back to the **Default Expense Account** set in the Default category.

<Note>
  <img alt="Image showing the Fuel Category" />

  *Image showing the Fuel Category*
</Note>

**Mappable items:**

* **Fuel** (default): The fallback GL account for any fuel transaction type not specifically mapped below.
* **Truck Diesel:** Standard diesel fuel purchases for trucks.
* **Reefer Diesel:** Diesel fuel for refrigerated trailer units.
* **Dyed Diesel:** Off-road or tax-exempt diesel fuel.
* **Gas:** Gasoline purchases.
* **Natural Gas:** Natural gas (CNG/LNG) fuel purchases.
* **Propane:** Propane fuel purchases.
* **DEF Fluid:** Diesel Exhaust Fluid (required for emissions systems).
* **Oil:** Oil and lubricant purchases.
* **Other Fuel:** Any fuel type not covered by the specific categories above.
* **Cash Advance:** Cash advances issued through fuel cards.
* **Cash Advance Fee:** Processing fees for fuel card cash advances.
* **Maintenance:** Maintenance charges processed through fuel cards.
* **Parking:** Parking charges processed through fuel cards.
* **Scales:** Weigh station scale charges processed through fuel cards.
* **Misc Truck Expense:** Miscellaneous truck-related expenses processed through fuel cards.
* **Misc Non Truck Expense:** Miscellaneous non-truck expenses processed through fuel cards.
* **Fee:** General fuel card fees.

### Toll (AP Only)

The Tolls category provides a single default account for toll mapping. If you have a dedicated GL account for tolls in your Sage Intacct chart of accounts, you can map it here. All toll transactions from services such as EFS, Comdata, and Compass are exported to this single GL account. Otherwise, all toll expenses will be sent to the **Default Expense Account**.

<Note>
  <img alt="Image showing the Toll Category" />

  *Image showing the Toll Category*
</Note>

## Settings & Permissions

Only Admins, Partner Admins, and Support users can configure account mappings. Access is at Settings > Connections > Sage Intacct. No additional permission assignment is required beyond holding one of those roles.

## Limits & Behavior

* Each line item type can have only one GL account mapped at a time.
* Mappings apply to all transactions for that subsidiary going forward. Existing exported transactions in Sage are not affected when a mapping changes.
* The Default Revenue Account and Default Expense Account cannot be cleared once set. To change them, click the X and immediately re-map to a different account.
* If a transaction fails to export because no mapping is found at any fallback level, it appears in Accounting > Error Transactions. Set the correct mapping, then re-sync the transaction from that screen.

## Best Practices

* **Start simple, then refine.** Set the master Default accounts for AP and AR first. Export a few test transactions and verify they land in the correct accounts. Then add category-level and item-level mappings as needed.
* **Use category defaults for broad coverage.** If all accessorial charges go to the same GL account, simply set the Accessorials default. You do not need to map each accessorial type individually.
* **Review after adding new types.** When you create a new accessorial type, deduction type, or e-check type in Alvys, it will automatically appear in the relevant mapping category. Until you assign it a specific GL account, it falls back to the category default.
* **AP and AR mappings are independent.** Changing an AP mapping does not affect AR, even for shared categories such as Accessorials. Configure each side according to your accounting requirements.
* **Map high-volume fuel types individually.** Truck Diesel, Cash Advance, and Maintenance are typically the highest-volume fuel card transaction types. Mapping them to specific GL accounts simplifies reconciliation with your fuel card vendor statements.

## FAQs

**Q: What happens if I do not map a specific transaction type?**

**A:** Alvys falls back to the category default, then to the Default Revenue Account (AR) or Default Expense Account (AP). If no fallback exists at any level, the transaction will fail to export and appear in Accounting > Error Transactions.

**Q: Can I use the same GL account for multiple transaction types?**

**A:** Yes. You can assign the same Sage GL account to as many transaction types as needed.

**Q: Why is a GL account missing from the dropdown?**

**A:** The GL account dropdown shows accounts pulled from your connected Sage entity. If an account is not visible, it may not exist in that entity or may be inactive. Verify the account is active in Sage Intacct, then return to Account Mappings. If the account is active in Sage but still does not appear, contact Alvys support.

**Q: Does changing a mapping affect already-exported transactions?**

**A:** No. Changing a mapping applies to future exports only. Previously exported transactions in Sage are not affected.

**Q: Can I clear the Default Revenue Account or Default Expense Account?**

**A:** No. These two accounts in the Default category are always required and cannot be cleared once set. To change them, click the X and immediately re-map to a different account.

**Q: When does Alvys use the Fuel two-level fallback?**

**A:** For fuel transactions, Alvys first looks for a mapping for the specific fuel card provider. If none is found, it uses the Default Fuel Account set for the Fuel category. If no Default Fuel Account is set, it falls back to the Default Expense Account in the Default category.

**Q: What are all the driver rate types I can map under Trip?**

**A:** The 16 driver rate types available under the Trip category are: Flat, Loaded Miles, Empty Miles, Loaded Miles Stop, Empty Miles Stop, Detention, Layover, Loaded Miles/Stop, Empty Miles/Stop, Loaded FSC, Empty FSC, Loaded Miles Advance, Empty Miles Advance, Loaded Miles Advance Stop, Empty Miles Advance Stop, Other.

## Go Deeper

* [How to configure dimension and custom field mappings for Sage Intacct](/en/help/integrations/how-to-configure-dimension-and-custom-field-mappings-for-sage-intacct)
* [How to Connect Sage Intacct to Alvys and Configure Settings](/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings)
* [Sage Intacct: Payments and Error Transactions](/en/help/integrations/sage-intacct-payments-and-error-transactions)
* [Sage Intacct Integration Collection](/en/help/integrations/sage-intacct-integration-collection)


# Sage Intacct: Overview
Source: https://docs.alvys.com/en/help/integrations/sage-intacct-integration-collection

Every article for setting up, using, and troubleshooting the two-way Sage Intacct integration with Alvys, ordered by recommended configuration sequence.

<Note>
  This collection (Sage Intacct integration hub, setup guide, and troubleshooting index) gathers every article for configuring, using, and resolving issues with the Sage Intacct integration in Alvys. Follow the recommended order to get started, or jump to specific topics using the links below.
</Note>

## Overview

The Sage Intacct integration connects Alvys with Sage Intacct using the Sage Web Services API. Alvys exports customer invoices (AR), vendor bills (AP), and credit memos to Sage Intacct. Payment status syncs back from Sage Intacct to Alvys on a scheduled basis.

This collection is organized in the recommended setup sequence. If you are configuring the integration for the first time, start with Article 1 and follow the articles in order through Article 5. Articles 6 cover dimensions and custom fields; read them when those features are relevant to your setup.

## Articles in This Collection:

### 1. How to Prepare Sage Intacct Before Connecting to Alvys?

This article outlines the essential prerequisites you must complete in Sage Intacct before starting the integration. It guides you through enabling Web Services, authorizing the Alvys Sender ID, creating a dedicated Web Services Role and User, configuring required GL accounts, and preparing your Alvys profiles with External Accounting IDs to ensure error-free data synchronization.

[How to Prepare Sage Intacct Before Connecting to Alvys](/en/help/integrations/how-to-prepare-sage-intacct-before-connecting-to-alvys)

### 2. How to Connect Sage Intacct to Alvys and Configure Settings?

This article walks you through the step-by-step setup wizard to securely connect Alvys to Sage Intacct. It details how to select your subsidiary, decide between posting to matching child entities or a single top-level parent entity, authenticate your credentials, and establish default operational settings for both Accounts Payable (AP) and Accounts Receivable (AR) modules.

[How to Connect Sage Intacct to Alvys and Configure Settings](/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings)

### 3. Sage Intacct: Account Mappings

This article explains how Alvys routes line items on bills and invoices to the correct Sage Intacct General Ledger (GL) accounts. It covers the hierarchical three-level fallback mapping logic (Specific Item Mapping, Category Default, and Master Default) and provides an explicit breakdown of the nine distinct account categories used for tracking linehauls, fuel surcharges, accessorials, deductions, and expenses.

[Sage Intacct: Account Mappings](/en/help/integrations/sage-intacct-account-mappings)

### 4. Sage Intacct: Transaction Export and Modification

This article covers the end-to-end workflows for exporting customer invoices (AR) and vendor bills (AP), including individual, batch, and summary invoice configurations. It explains how Alvys resolves matching records via accounting IDs or name rollbacks and details the process for safely modifying, reverting, or regenerating transactions depending on whether they are in a Draft, Posted, or Paid state in Sage Intacct.

[Sage Intacct: Transaction Export and Modification](/en/help/integrations/sage-intacct-transaction-export-and-modification)

### 5. Sage Intacct: Payments and Error Transactions

This article details how payment records synchronize in a one-way flow from Sage Intacct back into Alvys using an automatic 12-hour sync and an 8-day lookback window. It also covers how to use the Alvys Error Transactions page to identify, correct, and retry failed transaction exports, alongside step-by-step fixes for common connection, mapping, and dimension alignment errors.

[Sage Intacct: Payments and Error Transactions](/en/help/integrations/sage-intacct-payments-and-error-transactions)

### 6. How to Configure Dimension and Custom Field Mappings for Sage Intacct?

This article is the step-by-step configuration guide for dimensions and custom fields. It walks through all four phases of setup: creating dimension values in Sage Intacct, mapping those dimensions in Alvys, creating custom fields in Sage Intacct, and mapping custom fields in Alvys. Use this article when you are ready to configure these settings.

[How to configure dimension and custom field mappings for Sage Intacct](/en/help/integrations/how-to-configure-dimension-and-custom-field-mappings-for-sage-intacct)

## Go Deeper

* [Alvys Payment Synchronization for Accounting Integrations](/en/help/integrations/alvys-payment-synchronization-for-accounting-integrations)


# Sage Intacct: Payments & error transactions
Source: https://docs.alvys.com/en/help/integrations/sage-intacct-payments-and-error-transactions

Track Sage Intacct payment sync into Alvys every 12 hours and use the Error Transactions page to identify, fix, and re-sync failed AR and AP exports.

<Note>
  This article (covering Sage Intacct payment sync, the Error Transactions queue, and re-sync troubleshooting) explains how Sage Intacct payments import into Alvys, how to use the Error Transactions page to identify and fix failed exports, and how to re-sync transactions after resolving the underlying issue.
</Note>

## Overview

After Alvys exports transactions to Sage Intacct, payments recorded in Sage are automatically imported back into Alvys on a 12-hour schedule. If a transaction fails to export — for example because a customer record cannot be matched or a GL account is not mapped — it appears in Accounting > Error Transactions with an error message. You can fix the underlying issue and re-sync eligible transaction types directly from that page.

## Where to Find It

* Error Transactions: Accounting > Error Transactions
* Payment sync status and connection settings: Settings > Connections > Sage Intacct

  <img alt="Accounting menu with Error Transactions highlighted" />

  *Accounting menu with Error Transactions highlighted*

## Key Concepts

### Payment Import

Sage Intacct payments import into Alvys automatically every 12 hours. Each import run looks back 8 days in Sage to catch any payments that were recorded since the last sync.

**Note:** The 8-day lookback window means payments recorded more than 8 days before the import run will not be imported automatically. If you need to bring in older payments, contact Alvys support with the specific payment dates and subsidiary name.

Each imported payment includes: payment amount, payment date, payment method, check number, reference number, and note/memo. Alvys deduplicates payments by Sage detail ID, so the same payment will not import twice even if it falls within the lookback window of multiple import runs.

Payment import is not supported for the following transaction types: Summary Invoicing, Carrier Settlements, Driver Settlements.

### Error Transactions

The Error Transactions page shows all transactions that failed to export from Alvys to Sage. Each row in the table includes the date, a reference identifier, the entity type, a description, the amount, the current status, the error message from Sage, and available actions (such as re-sync).

Entity types that can appear in Error Transactions: Load, Trip, E-check, Paystub, Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice, Carrier Statement, Driver Statement, Escrow.

### Which Transactions Can Be Re-Synced

After fixing the root cause of a failure, you can re-sync the following entity types directly from Accounting > Error Transactions: Load, Trip, E-check, Paystub.

The following entity types cannot be re-synced from Error Transactions and must be resolved through other means: Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice, Carrier Statement, Driver Statement.

<img alt="Error Transactions table with Sage export error messages" />

*Error Transactions table with Sage export error messages*

## How to Use It

### Viewing and Filtering Error Transactions

Go to Accounting > Error Transactions. The page shows all failed transactions for your connected subsidiaries. Use the filters to narrow by date range, entity type, or status.

### Re-Syncing a Transaction

1. Identify the error message in the Error Message column to understand why the transaction failed.
2. Fix the underlying issue (for example: add the missing GL account mapping, create the Sage customer or vendor record, correct the payment terms).
3. Return to Accounting > Error Transactions, find the transaction, and click the re-sync action.
4. Alvys will attempt to re-export the transaction. If it succeeds, the row is removed from Error Transactions. If it fails again, the error message updates with the new failure reason.

   <img alt="Re-syncing transactions with Retry sync and Mark as synced" />

   *Re-syncing transactions with Retry sync and Mark as synced*

### Checking Payment Sync Status

Go to Settings > Connections > Sage Intacct. The connection page shows the current sync status for each subsidiary. Sync states are: Active, Paused, Not set up.

<img alt="Retry sync button on the Error Transactions page" />

*Retry sync button on the Error Transactions page*

## Settings & Permissions

Accounting > Error Transactions is accessible to any non-Driver user with the **"Billing"** permission.

## Limits & Behavior

* Payment import runs every 12 hours with an 8-day lookback window.
* Deduplication is based on Sage detail ID: the same payment will not import twice.
* Payment import is not supported for Summary Invoicing, Carrier Settlements, or Driver Settlements.
* Only Load, Trip, E-check, and Paystub transactions can be re-synced from Error Transactions.
* Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice, Carrier Statement, and Driver Statement transactions cannot be re-synced from this page.

## Troubleshooting

### Connection not initializing

1. Verify that your Sage Intacct Web Services credentials (Company ID, User ID, and password) are correct. In Sage, confirm the Web Services user account is active.
2. Confirm that AlvysMPP is listed in Company > Web Services Authorizations in Sage.
3. Confirm that Web Services is enabled in your Sage subscription.
4. If all of the above are correct and the connection still does not initialize, contact Alvys support with your subsidiary name and the error message shown.

   <img alt="Error Transactions with the Sync all button highlighted" />

   *Error Transactions with the Sync all button highlighted*

### Customer or vendor not matched

Alvys could not find a matching customer (for AR) or vendor (for AP) in Sage.

1. Open the customer or carrier record in Alvys.
2. Check whether a Sage Customer ID or Vendor ID is set. If not, enter the correct Sage ID to enable direct matching.
3. If no Sage ID is set, verify that the customer or carrier name in Alvys exactly matches the name in Sage Intacct. Any difference in spacing, capitalization, or punctuation will cause a mismatch.
4. If the customer or vendor does not exist in Sage, create it in Sage Intacct, then re-sync the transaction from Error Transactions.

### GL account not mapped

A required GL account mapping is missing for a transaction line item type.

1. Go to Settings > Connections > Sage Intacct and open the Account Mappings tab for the subsidiary.
2. Identify the category and line item type referenced in the error message.
3. Add the missing mapping. If the Default category is not mapped, map it first: it is required for all exports.
4. Return to Accounting > Error Transactions and re-sync the transaction.

### Dimension value cannot be resolved

Alvys could not find the expected dimension value in Sage for an exported transaction.

1. Go to Settings > Connections > Sage Intacct and open the Dimensions tab for the subsidiary.
2. Verify that the dimension value referenced in the error exists and is active in Sage Intacct.
3. If the dimension type supports Active Non-Posting status (Department, Location, Class, Customer, Vendor, or Project), verify that the value is set to an appropriate posting status for your use case.
4. Re-sync the transaction from Error Transactions after correcting the dimension value.

### Required custom field value is missing

A Sage custom field is mapped to an Alvys field, but the Alvys field is empty on the load or trip record.

1. Open the load or trip record and verify that the Alvys field mapped to the Sage custom field has a value.
2. If the field is a Custom Load Reference or Custom Trip Reference, confirm the reference field has been populated on the record.
3. Once the value is added, re-sync the transaction from Error Transactions.

### Custom field value exceeds maximum character length

The value of the mapped Alvys field is longer than the maximum character length configured for the Sage custom field.

1. Go to Settings > Connections > Sage Intacct and open the Custom Fields tab for the subsidiary.
2. Check the Chars column for the affected field to see the character limit.
3. Shorten the value in the Alvys field to within the limit, or adjust the character limit in the custom field mapping if appropriate.
4. Re-sync the transaction from Error Transactions.

### Payment term is not valid

The payment term assigned to a customer or carrier in Alvys does not exist in Sage Intacct.

1. Open the customer or carrier record in Alvys and note the payment term assigned.
2. In Sage, confirm that exact payment term exists under the payment terms configuration.
3. Either add the payment term to Sage or update the customer or carrier record in Alvys to use an existing Sage payment term. Alternatively, set a valid Default Payment Terms value in the Advanced Settings of the Sage Intacct connection.
4. Re-sync the transaction from Error Transactions.

### Invoice or bill cannot be modified because payments are applied

A payment has already been applied to the transaction in Sage, preventing modification.

1. In Sage Intacct, locate the transaction and remove the applied payment.
2. Return to Alvys and make the necessary changes to the invoice or bill.
3. Re-sync or re-export the transaction from Alvys. Alvys will create the appropriate reversal and post the corrected transaction.

### AP bill requires manual reversal

The AP bill is in a state in Sage (Posted or Selected) that prevents Alvys from automatically reversing it.

1. In Sage Intacct, locate the AP bill.
2. Manually create a reversal entry for the AP bill in Sage.
3. Once the reversal is complete, return to Alvys and re-sync the transaction from Accounting > Error Transactions.

### Transactions are not exporting or payments are not importing

Syncing has stopped or is paused for this subsidiary.

1. Go to Settings > Connections > Sage Intacct and find the subsidiary.
2. Check the Primary Sync toggle. If it is set to Paused, enable it.
3. Verify that the individual sync toggles for the relevant transaction type (for example, Export AR Invoices or Export AP Bills) are enabled.
4. If the connection status shows Not set up, the subsidiary may have been disconnected. Reconnect through the connection wizard.
5. If all toggles are active and syncing still is not occurring, contact Alvys support with your subsidiary name and the date since transactions stopped exporting.

## FAQs

**Q: How often does Alvys import payments from Sage Intacct?**

**A:** Payments import every 12 hours. Each import run looks back 8 days in Sage to capture any payments recorded since the previous sync.

**Q: Will Alvys import the same payment twice if it falls within multiple sync windows?**

**A:** No. Alvys deduplicates payments by Sage detail ID. Each unique Sage payment is imported only once regardless of how many sync cycles it falls within.

**Q: Which transaction types support payment import from Sage?**

**A:** Payment import is supported for AR invoices (load invoices and e-checks). Payment import is not supported for Summary Invoicing, Carrier Settlements, or Driver Settlements.

**Q: Which transaction types can I re-sync from Error Transactions?**

**A:** You can re-sync Load, Trip, E-check, and Paystub transactions. Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice, Carrier Statement, and Driver Statement transactions cannot be re-synced from this page.

**Q: What does the Error Message column tell me?**

**A:** The Error Message column shows the reason the transaction failed to export, such as a missing GL account mapping, unmatched customer or vendor, or invalid payment term. Use this message to identify and fix the underlying issue before re-syncing.

**Q: Can I see Error Transactions even if I do not have Sage Intacct connected?**

**A:** The Error Transactions page is visible to any non-Driver user with the **"Billing"** permission, regardless of whether a Sage Intacct connection is set up. Transactions only appear on this page if a Sage connection is configured and a transaction has failed to export.

**Q: How do I handle a failed transaction type that cannot be re-synced?**

**A:** For Deduction, Accessorial Revenue, Fuel, Toll, Accounting Invoice, Carrier Statement, and Driver Statement failures, you will need to resolve the issue manually in Sage or contact Alvys support for guidance on the specific failure.

## Go Deeper

* [Sage Intacct: Account Mappings](/en/help/integrations/sage-intacct-account-mappings)
* [Sage Intacct: Transaction Export and Modification](/en/help/integrations/sage-intacct-transaction-export-and-modification)
* [How to Connect Sage Intacct to Alvys and Configure Settings](/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings)


# Sage Intacct: Export & modify transactions
Source: https://docs.alvys.com/en/help/integrations/sage-intacct-transaction-export-and-modification

Understand how Alvys exports AR invoices, AP bills, and driver or carrier settlements to Sage Intacct, matches records, and handles post-export modifications.

<Note>
  This article (covering Sage Intacct transaction export, record matching, and post-export modification) explains how Alvys exports AR invoices, AP bills, and settlement transactions to Sage Intacct, how customer and carrier records are matched in Sage, and how to modify transactions that have already been exported.
</Note>

## Overview

When Alvys exports transactions to Sage Intacct, it matches each AR transaction to a Sage customer record and each AP transaction to a Sage vendor record. If a match is not found, the transaction fails and appears in Accounting > Error Transactions. Once exported, the way Alvys handles a modification depends on the transaction's current state in Sage.

## Sync Controls

The integration provides two **(2)** levels of sync control that must both be enabled for transactions to flow to Sage Intacct.

### Master Sync Toggle

At the top of the integration settings page, the **Sync Active / Sync Paused** toggle controls the overall integration. When paused, no transactions are exported to Sage Intacct. Neither AR invoices nor AP bills will flow, regardless of their individual sync settings.

<Note>
  Shows an active integration dashboard with the **Sync active** toggle enabled and statuses highlighted as **Active**.

  <img alt="Notion Image" />
</Note>

The integration status badge next to the toggle displays one of three (3) states:

* **Active** (green): Sync is running.
* **Paused** (gray): Sync is disabled.
* **Not Set Up** (orange): The setup wizard has not been completed.

<Note>
  <img alt="Displays the integration sidebar list tracking multiple connections categorized by statuses like Active, Not set up, and Paused." />

  *Displays the integration sidebar list tracking multiple connections categorized by statuses like **Active**, **Not set up**, and **Paused**.*
</Note>

### AR and AP Sync Toggles

Within the integration settings, the **Accounts Receivable** and **Accounts Payable** sections each have their own independent sync toggle, located in the accordion header of their respective sections.

<Note>
  <img alt="Shows the accounting integration toggles confirming that both AP sync and AR sync are active." />

  *Shows the accounting integration toggles confirming that both **AP sync** and **AR sync** are active.*
</Note>

Both the master sync and the individual section sync must be enabled for transactions to flow. For example:

* **Master sync on, AR sync on, AP sync off:** Only customer invoices are exported. Vendor bills are not.
* **Master sync on, AR sync off, AP sync on:** Only vendor bills are exported. Customer invoices are not.
* **Master sync off:** Nothing is exported, regardless of the AR or AP toggle states.

<Check>
  💡 If you attempt to disable the last remaining active sync (for example, turning off AR sync when AP sync is already off), Alvys will prompt you to use the master sync toggle instead. This ensures you always have a single, clear control for fully pausing the integration.

  <img alt="Displays a 'Disable sync?' confirmation modal alerting the user that AP sync is already disabled, highlighting the final Disable confirmation action." />

  *Displays a "Disable sync?" confirmation modal alerting the user that AP sync is already disabled, highlighting the final **Disable** confirmation action.*
</Check>

## Subsidiary Determination for Transaction Exports

When a transaction is exported from Alvys to Sage Intacct, Alvys must determine which subsidiary's integration should handle the export. This determines which Sage entity receives the transaction, which GL accounts are used, and which dimension and custom field mappings apply.

### Customer Invoices and the Invoice As Field

Customer invoices are exported to Sage based on the subsidiary specified in the **Invoice As** field on the load. The Invoice As field determines which Alvys subsidiary "owns" the revenue for that load, and therefore which Sage integration handles the invoice export.

<Note>
  <img alt="Features the customer load details page with a blue outline focusing on the Invoice Customer As configuration dropdown." />

  *Features the customer load details page with a blue outline focusing on the **Invoice Customer As** configuration dropdown.*
</Note>

If the Invoice As subsidiary has an active Sage Intacct integration with AR sync enabled, the invoice is exported to that subsidiary's connected Sage entity. If the Invoice As subsidiary does not have an active integration, the invoice is not exported.

<Check>
  💡 You can verify which subsidiary a load will invoice under by checking the **Invoice As** field on the load detail page. This field is set when the load is created and can be changed before the invoice is exported.
</Check>

### Carrier Bills and the Tender As Field

Carrier bills are exported based on the **Tender As** field on the load. The Tender As field determines which subsidiary is responsible for paying the carrier, and therefore which Sage integration handles the bill export.

<Note>
  <img alt="Shows carrier dispatch metrics with a blue outline highlighting that the load is being Tendered As Alvys Brokerage." />

  *Shows carrier dispatch metrics with a blue outline highlighting that the load is being Tendered As Alvys Brokerage.*
</Note>

*\[Heading 4 not supported]*

For carriers operating with dual authority, the operational mode is automatically determined based on the Tender As subsidiary. Users can manually change the operational mode to Carrier or Broker, which may affect how bills are categorized and exported to Sage Intacct.

<Note>
  <img alt="Displays the operational advanced settings module with the mode toggle set specifically to Carrier." />

  *Displays the operational advanced settings module with the mode toggle set specifically to Carrier.*
</Note>

### Driver Bills and the Driver Subsidiary Field

Every driver in Alvys is assigned to a subsidiary, which represents the business unit that driver belongs to. When a driver statement is generated, the resulting vendor bill is sent to Sage Intacct based on the driver's subsidiary, not the subsidiary used to invoice or tender the load.

<Note>
  <img alt="Shows a driver's employment summary card with a blue box emphasizing its assigned Subsidiary as Alvys Inc." />

  *Shows a driver's employment summary card with a blue box emphasizing its assigned Subsidiary as Alvys Inc.*
</Note>

## Customer Matching, Creation, and Accounting Fields

Before Alvys can export an invoice to Sage Intacct, it must **find or create** the corresponding customer record in Sage. This section explains how Alvys matches customers and brokers to Sage records, what happens when no match is found, and which fields from the customer profile in Alvys are used during that process.

### Customer External Accounting ID (Primary match)

The External Accounting ID on the customer or broker profile in Alvys is the primary field used to identify the corresponding customer in Sage Intacct. When an invoice is exported, Alvys searches Sage for a customer whose ID matches this value. If a match is found, the invoice is linked to that customer.

<Note>
  <img alt="A minimal interface view displaying the External Accounting ID heading and its clickable 'View All' action link." />

  *A minimal interface view displaying the External Accounting ID heading and its clickable "View All" action link.*
</Note>

If the External Accounting ID is set but no matching customer exists in Sage and auto-creation is disabled, the export fails with an error asking you to either correct the ID in Alvys or enable auto-creation.

### Name matching fallback

If no External Accounting ID is set and **Name Matching Fallback** is enabled in your AR settings, Alvys searches Sage by the customer's **External Accounting Name** (or company name if no External Accounting Name is set). If exactly one match is found, Alvys uses that record. If multiple customers in Sage share the same name, the export fails with an error. To resolve this, set the External Accounting ID on the customer profile so the system can identify the correct record.

<Warning>
  ⚠️ When an External Accounting ID is provided, Alvys does not fall back to name matching, even if the ID is not found in Sage. This ensures precise matching and prevents accidental linkage to the wrong customer. If the ID is incorrect, correct it on the customer profile in Alvys.
</Warning>

### Auto-creation

When no match is found by either method (**Primary Id** or **Name Matching**):

If **Auto Create Customer** is enabled, Alvys creates a new customer in Sage using the **External Accounting Name** (or Customer name if not set), contact information, invoicing address, and payment terms from the customer profile. If disabled, the export fails with an error stating that no matching customer was found.

<Note>
  <img alt="Displays accounts receivable parameters with a green highlight around the checked Auto create customer option." />

  *Displays accounts receivable parameters with a green highlight around the checked Auto create customer option.*
</Note>

### External Accounting Name vs. Invoicing Name

The Invoicing Name (previously called Billing Name) controls how the customer or broker appears on invoices generated within Alvys. It does **not** affect the customer record in Sage Intacct and is not used during invoice exports. The customer’s External Accounting Name is used to identify a customer or broker in Sage Intacct. The customer name sent to Sage is determined by the **External Accounting Name, or if that is not set, the company name on the customer profile.**

<Note>
  <img alt="Displays a customer profile header with a green box framing the Alvys Customer name alongside its unknown credit status." />

  *Displays a customer profile header with a green box framing the **Alvys Customer** name alongside its unknown credit status.*

  <img alt="Shows the Invoicing Info pane with green highlights around the section header and the configured External Accounting Name ('Alvys Acct')." />

  *Shows the **Invoicing Info** pane with green highlights around the section header and the configured **External Accounting Name** ("Alvys Acct").*
</Note>

### Customer/Broker Payment Terms

The Payment Terms field on the customer profile defines how many days a customer has to pay an invoice, calculated from the invoice date. When an invoice is exported, Alvys sends the corresponding payment term (for example, "Net 25") to Sage Intacct. If that term does not exist in your Sage environment, Alvys retries using **Net 30** as a fallback. If Net 30 also does not exist, the export fails.

<Note>
  <img alt="Features the Invoicing Info panel emphasizing the Payment Terms field which is set to 'Net 25'." />

  *Features the **Invoicing Info** panel emphasizing the **Payment Terms** field which is set to "Net 25".*
</Note>

Make sure the payment terms you use in Alvys have matching entries in Sage Intacct. Common terms such as Net 15, Net 30, Net 60, and Net 90 are typically set up by default in Sage.

### Setting Up AR Payment Terms in Sage Intacct

**To add or verify payment terms in Sage Intacct:**

Go to **Accounts Receivable → Setup → More** and click **Add** next to **Terms**.

<Note>
  <img alt="Illustrates system navigation within the Accounts Receivable setup tab, highlighting the path to configure billing Terms." />

  *Illustrates system navigation within the **Accounts Receivable** setup tab, highlighting the path to configure billing **Terms**.*
</Note>

Enter a name that matches what Alvys will send (for example, **Net 30**), and add a description.

Set the due date calculation by entering the number of days in the **Day** field and selecting **AR sales invoice** or **AP purchase invoice date** from the dropdown.

<Note>
  <img alt="Displays the AR terms information form window for creating a 'Net 30' term, highlighting the input block and the upper right Save button." />

  * Displays the **AR terms information** form window for creating a "Net 30" term, highlighting the input block and the upper right **Save** button.\*
</Note>

Click **Save**.

## Carrier and Vendor Matching, Creation, and Accounting Fields

Before Alvys can export a bill to Sage Intacct, it must find or create the corresponding vendor record in Sage. This section explains how Alvys matches carriers, drivers, and factoring companies to Sage vendor records, what happens when no match is found, and which fields from the carrier and driver profiles in Alvys are used during that process.

### External Accounting ID (primary match)

The **External Accounting ID** on the carrier or driver profile is the primary identifier used to locate the corresponding vendor in Sage Intacct. When set, Alvys searches Sage for a vendor whose ID matches this value. If a match is found, the bill is linked to that vendor.

<Check>
  💡 If no External Accounting ID is set and Name Matching Fallback is enabled in your AP settings, Alvys searches Sage using the carrier's External Accounting Name (or company name if not set). If multiple vendors share the same name, the export fails. Set the External Accounting ID on the carrier profile to resolve this.
</Check>

### Carrier link strategy

The “**Link existing carriers by”** setting in your AP configuration provides an additional matching strategy. When configured, Alvys can use the carrier's External Id, MC number or DOT number to look up a matching vendor in Sage before falling back to name matching.

<Note>
  <img alt="Shows the Link existing carriers by dropdown menu open, presenting identifier options like External ID, MC Number, and USDOT Number." />

  *Shows the **Link existing carriers by** dropdown menu open, presenting identifier options like External ID, MC Number, and USDOT Number.*
</Note>

### Name matching fallback

If no match has been found and **Name Matching Fallback** is enabled in your AP settings, Alvys searches Sage by the carrier's **External Accounting Name** (or carrier name if not set). If exactly one match is found, Alvys uses that record. If multiple vendors share the same name, the export fails with an error asking you to set the External Accounting ID on the carrier profile.

<Note>
  <img alt="Features a checked option for the Name Matching Fallback toggle, which enables automated fallback matching by name when primary identifiers miss." />

  *Features a checked option for the **Name Matching Fallback** toggle, which enables automated fallback matching by name when primary identifiers miss.*

  <img alt="Displays a carrier's general contact profile with a green box spotlighting the assigned External Accounting Name ('AL Ext Carrier')." />

  *Displays a carrier's general contact profile with a green box spotlighting the assigned **External Accounting Name** ("AL Ext Carrier").*
</Note>

The External Accounting Name takes priority. If it differs from an existing Sage vendor name, even if the carrier name in Alvys matches, Alvys will create a new vendor using the External Accounting Name.

### Auto-creation

When no match is found by either method (Primary Id or Name Matching):

If **Auto Create Vendor** is enabled, Alvys creates a new vendor in Sage using the External Accounting Name (or carrier/driver name if not set), contact information, address, and payment terms. If **Auto Create Vendor** is disabled, the export fails with an error stating that no matching vendor was found.

### Driver Name and 1099 Tax Details

Drivers, including company drivers and owner-operators, may operate as 1099 independent contractors. These drivers have additional tax fields on their profiles, including Tax Company Name, Tax Company Address, and Tax Identification Number.

<Note>
  <img alt="Shows the structured corporate Tax Information data section containing identification numbers, classification type, and the company address." />

  *Shows the structured corporate **Tax Information** data section containing identification numbers, classification type, and the company address.*
</Note>

When a driver statement is exported as a bill, Alvys determines which information to use for the vendor record:

* If the driver is classified as a 1099 contractor and has a **Tax Company Name** on file, Alvys uses the 1099 tax company information (name, tax ID, address, email, and phone) to create the vendor. The tax company name becomes the vendor name in Sage.
* If the driver does not have 1099 tax information configured, Alvys uses the driver's own name and contact details for the vendor record.

### Carrier Payment Terms

When exporting a bill, Alvys resolves the carrier's payment terms in the following order:

* If the carrier has a factoring company with payment terms configured, those terms are used.
* If no factoring terms apply, the carrier's own payment terms (Terms in Days) are used.
* If the carrier does not have Terms in Days set, Alvys uses the default payment terms configured for that payment type in your company subsidiary settings.
* If none of the above are set, Alvys defaults to 30 days.

  *\[Heading 4 not supported]*

To avoid export failures, create the necessary payment terms in Sage Intacct before exporting bills.

In Sage Intacct, go to Accounts Payable, then **Setup → More** and click **Add** next to **Terms**.

<Note>
  <img alt="Illustrates navigation inside the application's side menu under Accounts Payable, focusing on the Setup menu row for managing Terms." />

  *Illustrates navigation inside the application's side menu under **Accounts Payable**, focusing on the **Setup** menu row for managing **Terms**.*
</Note>

Set the Name to match the format Alvys sends (for example, "Net 30", "Net 45", "Net 60").

<Check>
  💡 At minimum, create a "**Net 30**" payment term. This is the fallback Alvys uses when a carrier's specific term does not exist in Sage.
</Check>

<Note>
  <img alt="Displays the AP terms information form window for a 'Net 30' term, highlighting the core configuration fields and the top-right Save button." />

  *Displays the **AP terms information** form window for a "Net 30" term, highlighting the core configuration fields and the top-right **Save** button.*
</Note>

Set the due date calculation to the corresponding number of days.

Save the payment term.

### Carrier Factoring Companies

When an external carrier has a factoring company set as their payment method, Alvys handles the factoring company setup in Sage Intacct as part of vendor creation.

<Note>
  <img alt="Shows the Remittance section with green highlights on the 'Factoring Company' payment method selection and its detailed address profile." />

  *Shows the Remittance section with green highlights on the "Factoring Company" payment method selection and its detailed address profile.*
</Note>

This only applies when the carrier's vendor record does not already exist in Sage Intacct. If Alvys finds an existing vendor (matched by Sage ID, MC/DOT number, or name), it updates that vendor rather than creating a new one.

The **Create Factoring Companies As** setting in your Accounts Payable configuration controls how the factoring company is represented in Sage Intacct:

* **Contact**: The factoring company is added as a Pay To contact on the carrier's vendor record. No separate vendor is created.
* **Vendor**: The factoring company is created as its own vendor record in Sage Intacct.

<Note>
  <img alt="Displays the Create factoring companies as setting dropdown menu with 'Contact' actively selected." />

  *Displays the Create factoring companies as setting dropdown menu with "Contact" actively selected.*
</Note>

## Where to Find It

Transaction exports are triggered from these sections:

* AR invoices: Accounting > Invoicing
* Carrier settlement bills: Accounting > Carrier Settlements
* Driver settlement bills: Accounting > Driver Settlements
* Failed and re-syncable transactions: Accounting > Error Transactions

## How to Use It

### Individual Load Invoices Export

Before generating the invoice, confirm the following:

* The correct customer is assigned to the load.
* The **Invoice As** field on the load is set to a subsidiary with an active Sage Intacct integration and AR sync enabled.

  <img alt="Features a load detail page, highlighting its Released status badge and the Invoice Customer As selection dropdown menu." />

  *Features a load detail page, highlighting its Released status badge and the Invoice Customer As selection dropdown menu.*
* The load is in **Released** status. Loads in earlier statuses (Queued, Dispatched, In Transit) cannot be invoiced.
* The customer has an **External Accounting ID** set on their profile (recommended), or the External Accounting Name or company name matches a customer record in Sage Intacct

  <img alt="Displays a customer invoicing overview layout with a blue box framing the configured External Accounting Name ('Alvys Acct')." />

  *Displays a customer invoicing overview layout with a blue box framing the configured **External Accounting Name** ("Alvys Acct").*
* The customer's **Payment Terms** exist in your Sage environment (for example, Net 30).

### Step-by-Step: Generate an Individual Invoice

Navigate to the load you want to invoice by searching for the load number or selecting it from the load board.

On the **Load Details** page, verify the load status is **Released**.

Review the charges on the load to confirm they are correct.

Click the **Generate Invoice** button below the Money Box.

<Note>
  <img alt="Shows money box buttons with a green box highlighting the clickable Generate Invoice action." />

  *Shows money box buttons with a green box highlighting the clickable **Generate Invoice** action.*
</Note>

The load status changes from **Released** to Queued.

<Note>
  <img alt="Displays a minimal status line confirming that Load  has successfully entered the Queued state" />

  \*Displays a minimal status line confirming that \**Load \*\* has successfully entered the **Queued** state*
</Note>

The invoice is automatically queued for export to Sage Intacct. No additional action is required to trigger the export.

*\[Heading 4 not supported]*

The invoice appears in Sage Intacct under **Accounts Receivable → Transactions → AR Invoices**.

<Note>
  <img alt="Features the Invoices data table ledger with green highlights surrounding the specific invoice number ('1084738') and its Posted status state." />

  *Features the **Invoices** data table ledger with green highlights surrounding the specific invoice number ("1084738") and its **Posted** status state.*

  <img alt="Shows the comprehensive transaction view for Invoice -- 1084738, with a green frame calling attention to the main system document header." />

  *Shows the comprehensive transaction view for **Invoice -- 1084738**, with a green frame calling attention to the main system document header.*
</Note>

If auto-post is enabled in your AR settings (**Autopost Invoices”**), the invoice is posted automatically. Otherwise, it appears as a draft in Sage.

<Warning>
  ⚠️ If the export fails, the transaction appears on the \*\*Accounting → \*\*[Error Transactions](https://app.alvys.com/accounting/error-transactions) page in Alvys. Review the error message, correct the issue and retry the sync.
</Warning>

The **PO Number Mapping** setting in your AR configuration controls which value appears in the PO Number / Reference Number field on exported invoices. It can use either the load's order number (default) or the load's PO number.

<Note>
  <img alt="Displays a breakdown panel from the invoice transaction view with a green box outlining the specific mapped Reference number ('ALO76674')." />

  *Displays a breakdown panel from the invoice transaction view with a green box outlining the specific mapped **Reference number** ("ALO76674").*

  <img alt="Shows a completed load details pane with a green box highlighting the mapped PO # ('ALPO65563')" />

  *Shows a completed load details pane with a green box highlighting the mapped PO # ("ALPO65563")*
</Note>

### Batch Invoice Export

The Invoicing page in Alvys is located under \*\*Accounting > \*\*[Invoice](https://app.alvys.com/#/accounting/invoicing) in the left navigation menu.

<Note>
  <img alt="Shows the side navigation menu with the Invoice option selected under the Accounting dropdown." />

  *Shows the side navigation menu with the Invoice option selected under the Accounting dropdown.*
</Note>

This page allows users to create invoices for multiple loads across one or more customers simultaneously. Each selected load is processed as an individual AR invoice, and exporting to Sage Intacct is triggered automatically when the invoices are generated. This approach enables faster and more efficient invoicing while ensuring accurate transaction records for each load.

<Note>
  <img alt="Displays the billing dashboard with a green box outlining the selected Released status filter tab." />

  *Displays the billing dashboard with a green box outlining the selected Released status filter tab.*
</Note>

From the Released tab, select the loads for which you want to generate invoices. Ensure that the customer being invoiced is correct. If an External Accounting Name is configured, it must match the corresponding customer record in Sage Intacct. If no External Accounting Name is configured, the standard customer or broker name must match the customer record.

<Note>
  <img alt="Displays an Invoice Summary popup listing three selected customer loads and their respective billing amounts." />

  *Displays an Invoice Summary popup listing three selected customer loads and their respective billing amounts.*

  <img alt="Shows billing execution controls with a green box highlighting the blue Generate Invoice button." />

  *Shows billing execution controls with a green box highlighting the blue Generate Invoice button.*
</Note>

Additionally, the Invoice As subsidiary on each load must be correctly configured, as this determines which specific Sage Intacct entity receives the transaction data. After verifying these details, invoices can be generated using the Generate Invoice option, which creates the invoices and exports them to Sage Intacct. Alternatively, the “**Create and Send**” option generates the invoices, exports them to Sage Intacct, and sends them to the customer according to the invoicing method configured for that customer.

Once exported, the AR invoices are recorded in Sage Intacct under the corresponding customer and can be located in **Accounts Receivable > AR Invoices.**

<Note>
  <img alt="Features the main Invoices ledger table with a green outline framing the successfully generated invoice numbers." />

  *Features the main Invoices ledger table with a green outline framing the successfully generated invoice numbers.*
</Note>

<Check>
  💡 If the invoice was not exported due to an error, the issue can be reviewed on the Error Transactions page\*\* (Accounting > **[Error Transactions](https://app.alvys.com/accounting/error-transactions)**)\*\*. Additional information about the Error Transactions page and how to interpret error details is provided in the error resolution documentation.
</Check>

### Summary Invoice Export

Summary invoicing consolidates multiple loads for a customer into a single invoice. The Summary Invoicing page can be accessed from Accounting > [Summary Invoicing](https://app.alvys.com/#/accounting/summary-invoicing). For more information on configuring customers for summary invoicing, see the [Summary Invoicing help center article](/en/help/accounting-settlements/how-to-use-summary-invoicing).

*\[Heading 4 not supported]*

* The customer's **Invoice Type** must be set to **Summary** on their customer profile. Customers set to individual invoicing will not appear in the Summary Invoicing module.

<Note>
  <img alt="Displays the customer profile overlayed by the Invoicing settings modal, with green boxes highlighting the entry link and the active Summary invoice type radio button." />

  *Displays the customer profile overlayed by the Invoicing settings modal, with green boxes highlighting the entry link and the active Summary invoice type radio button.*
</Note>

* The loads to be included must be in **Released** or **TONU** status.
* The customer must have an External Accounting ID or matching name in Sage Intacct.

### Step-by-Step: Generate a Summary Invoice

Navigate to **Accounting → Summary Invoicing** from the main navigation menu.

**Select a customer** from the left panel. The right panel populates with all available loads for that customer in **Released** or **TONU** status.

<Note>
  <img alt="Shows the batch invoicing screen with a green box selecting Summary Inv Customer to pull up their associated un-invoiced loads." />

  *Shows the batch invoicing screen with a green box selecting Summary Inv Customer to pull up their associated un-invoiced loads.*
</Note>

Review the loads in the right panel. Check or uncheck individual loads to include or exclude them from the invoice.

Choose one of two options:

* **Create a Draft**: Generates a draft summary invoice that you can review before finalizing. The draft appears under the **Drafts** tab in the Previous Invoices section.
* \*\*Generate Invoice: \*\* Generates and finalizes the summary invoice immediately.

<Note>
  <img alt="Features the final workflow execution buttons providing options to Generate Invoice or Add to Draft." />

  *Features the final workflow execution buttons providing options to Generate Invoice or Add to Draft.*
</Note>

If you created a draft, navigate to the **Drafts** tab, review the invoice, and click **Generate Invoice.**

Once generated, the included loads change status from **Released** to **Queued.**

<Note>
  <img alt="Shows a generated summary invoice document (S1000063) consolidating multiple line-item loads into a single statement." />

  *Shows a generated summary invoice document (S1000063) consolidating multiple line-item loads into a single statement.*
</Note>

*\[Heading 4 not supported]*

The summary invoice appears in Sage Intacct as a single AR invoice with each load's charges as separate line items.

<Note>
  <img alt="Displays the transaction view for Invoice -- S1000063 belonging to 'Summary Inv Customer,' highlighting its Posted status block." />

  *Displays the transaction view for Invoice -- S1000063 belonging to "Summary Inv Customer," highlighting its Posted status block.*
</Note>

### Carrier Bill Export from Load Invoicing

When you generate a customer invoice for a load that has an external carrier assigned, the carrier's AP bill may also be exported at the same time. The behavior depends on two settings in your AP configuration: **Export Carrier Statements** and **Send Carrier Invoice Upon Upload**.

<Note>
  <img alt="Shows configuration checkboxes outlined in green for enabling carrier invoice exports upon upload and exporting carrier statements." />

  *Shows configuration checkboxes outlined in green for enabling carrier invoice exports upon upload and exporting carrier statements.*
</Note>

### How the Settings Work Together

When both settings are off, the carrier bill exports automatically when the customer invoice is generated. No carrier invoice document is required.

When **Send Carrier Invoice Upon Upload** is on but **Export Carrier Statements** is off, the carrier bill exports automatically as soon as a carrier invoice document is uploaded to the trip. The customer invoice does not need to be generated first.

When **Export Carrier Statements** is on, carrier bills do not export from load invoicing regardless of the **Send Carrier Invoice Upon Upload** setting. Carrier bills are managed exclusively through the Carrier Settlements module.

### Step by Step: Carrier Bill Export via Load Invoicing (When Applicable)

Navigate to the **Load Details** page for a **Released load** with an external carrier.

If your settings require a carrier invoice document, go to the trip level details for the carrier's trip, upload the carrier's invoice document, and enter the **carrier invoice number** when prompted.

<Note>
  <img alt="Shows a segment of the load action menu bar highlighting the selection of the Docs tab." />

  *Shows a segment of the load action menu bar highlighting the selection of the Docs tab.*

  <img alt="Displays a document staging panel where a PDF file is designated as a Carrier Invoice type and is ready for upload." />

  *Displays a document staging panel where a PDF file is designated as a Carrier Invoice type and is ready for upload.*

  <img alt="Features the Carrier Invoice Upload modal with a green box framing the designated invoice number ('AL7676INV')." />

  *Features the Carrier Invoice Upload modal with a green box framing the designated invoice number ("AL7676INV").*
</Note>

If your configuration triggers carrier bill export at this point (see above), the AP bill is automatically queued for export to Sage Intacct.

### After Export

The carrier's AP bill appears in Sage Intacct under **Accounts Payable > Bills**. The carrier invoice number inputted during submission is used as the sage intacct reference number field and also included in the memo field.

<Note>
  <img alt="Displays the full ledger sheet for Bill 1000276, emphasizing the mapped reference number and automated trip description blocks in green frames." />

  *Displays the full ledger sheet for Bill 1000276, emphasizing the mapped reference number and automated trip description blocks in green frames.*
</Note>

If auto post is enabled (**Autopost Bills**), the bill is posted automatically. Otherwise, it remains in draft state or submitted state (if **bill approval** is enabled in sage intacct). If the export fails, the error appears on the \*\*Accounting > \*\*[Error Transactions](https://app.alvys.com/accounting/error-transactions)[ page](https://app.alvys.com/accounting/error-transactions) in Alvys.

<Check>
  💡 If your team prefers to review and batch carrier payments before exporting, enable **Export Carrier Statements** and use the Carrier Settlements module instead. This gives you a consolidated view and lets you generate a single AP bill per carrier with multiple trips as line items.
</Check>

## Exporting Carrier Bills: Carrier Settlements Module

The Carrier Settlements module provides a centralized view for managing carrier payments and exporting AP bills. Instead of exporting one bill per trip from the load, this module consolidates multiple trips into a single AP bill per carrier statement.

### Prerequisites:

* **Export Carrier Statements** must be enabled in your AP settings (Settings → Connections → Sage Intacct → Accounts Payable section).

  <img alt="Shows the Export Carrier Statements checkbox option checked, enabling multiple trips to be combined as line items on a single bill." />

  *Shows the Export Carrier Statements checkbox option checked, enabling multiple trips to be combined as line items on a single bill.*
* The carrier must have an External Accounting ID or matching name in Sage Intacct.
* Trips must have reached a billable status.

### Step-by-Step: Generate and Export a Carrier Statement

From the main navigation menu, go to \*\*Accounting → \*\*[Carrier Settlements](https://app.alvys.com/accounting/carrier-settlements).

On the **Carrier Settlements** home page, click on a **carrier's name** to view their pending trips.

<Note>
  <img alt="Features a filtered open payables list with a green box highlighting a row for VIPER FREIGHT LLC showing two pending trips." />

  *Features a filtered open payables list with a green box highlighting a row for VIPER FREIGHT LLC showing two pending trips.*
</Note>

Review the list of trips available for settlement. Each row shows trip details, amounts, and status.

Select the trips you want to include in the statement by checking the boxes next to each trip then select the **Approve Selected Trips** button.

<Note>
  <img alt="Shows a carrier's trip settlement workspace with a green outline framing two selected trips and the corresponding Approve Selected Trips action button." />

  *Shows a carrier's trip settlement workspace with a green outline framing two selected trips and the corresponding Approve Selected Trips action button.*
</Note>

Click **Generate Statement** to create the carrier settlement.

<Note>
  <img alt="Displays the statement compilation panel for the carrier with a green frame focusing on the blue Generate Statement execution button." />

  *Displays the statement compilation panel for the carrier with a green frame focusing on the blue Generate Statement execution button.*
</Note>

The system generates a single AP bill in Sage Intacct with each selected trip as a line item. Select the statement to view the statement details, the accounting sync status will be displayed.

<Note>
  <img alt="Shows the statement ledger for Viper Freight LLC with a green box in the right panel highlighting a successful Accounting Sync status." />

  *Shows the statement ledger for Viper Freight LLC with a green box in the right panel highlighting a successful Accounting Sync status.*

  <img alt="Displays the external ledger sheet for Bill 1000026, with green boxes highlighting the bill identifier, vendor name, and statement description." />

  *Displays the external ledger sheet for Bill 1000026, with green boxes highlighting the bill identifier, vendor name, and statement description.*
</Note>

## Exporting Driver Bills

Driver statements generate AP bills in Sage Intacct for driver compensation. Driver bill export always operates in single bill mode. All trips, deductions, and credits included in a driver statement are consolidated into a single AP bill.

### Driver Filtering Settings

Two settings in your AP configuration control which driver bills are exported:

\*\*Include Driver Bills: \*\* Master toggle for all driver bill export. When disabled, no driver statements are exported to Sage, regardless of other settings.

\*\*1099 Drivers Only: \*\* When enabled, only statements for drivers classified as 1099 independent contractors are exported. Statements for W2 employee drivers are excluded.

These settings are found in **Settings → Connections → Sage Intacct → Accounts Payable** section.

<Note>
  <img alt="Shows system configuration checkboxes for export settings, specifically outlining options to Include driver bills and filter by 1099 drivers only." />

  *Shows system configuration checkboxes for export settings, specifically outlining options to Include driver bills and filter by 1099 drivers only.*
</Note>

### Driver Settlements Module

The [Driver Settlements module](/en/help/accounting-settlements/driver-settlements-faq) is the modern workflow for managing driver payments. It provides a more structured process with draft statements, predefined pay periods, approval workflows, and bulk actions.

*\[Heading 4 not supported]*

From the main navigation menu, go to \*\*Accounting → \*\*[Driver Settlements](https://app.alvys.com/accounting/driver-settlements).

On the **Open** tab, click on a **driver's name** to view their pending transactions.

<Note>
  <img alt="Features a driver settlement list with a green box focusing on the active overview data row for company driver." />

  *Features a driver settlement list with a green box focusing on the active overview data row for company driver.*
</Note>

Review the list of available transactions (trips, deductions, credits, reimbursements).

**Select the items** you want to include in this statement by checking the boxes next to each transaction.

<Note>
  <img alt="Displays an expanded table view of a driver's assigned Trips, framing their corresponding statuses, load numbers, and net income values within a green border." />

  *Displays an expanded table view of a driver's assigned Trips, framing their corresponding statuses, load numbers, and net income values within a green border.*
</Note>

**Choose the pay period** for this statement from the pay period dropdown.

<Note>
  <img alt="Features a payroll summary panel with a green box outlining the active Pay period drop-down date selection field." />

  *Features a payroll summary panel with a green box outlining the active Pay period drop-down date selection field.*
</Note>

Click **Approve** to move the selected transactions into a draft statement. The statement moves to the **Drafts** tab.

<Note>
  <img alt="Shows the driver settlement workspace with a green frame emphasizing the blue Approve 3 Items button on the bottom right." />

  *Shows the driver settlement workspace with a green frame emphasizing the blue Approve 3 Items button on the bottom right.*
</Note>

When ready, click **Generate Statement** to finalize the statement.

<Note>
  <img alt="Displays the finalized payroll calculation summary sheet, highlighting the Approve 3 Items action button to process the driver's statement." />

  *Displays the finalized payroll calculation summary sheet, highlighting the Approve 3 Items action button to process the driver's statement.*
</Note>

The finalized statement moves to the **Statements** tab and the AP bill is automatically queued for export to Sage Intacct.

<Note>
  <img alt="Displays the processed statements dashboard for driver, showing that Statement #1000028 has been successfully generated, processed, and synced to accounting." />

  *Displays the processed statements dashboard for driver, showing that Statement #1000028 has been successfully generated, processed, and synced to accounting.*

  <img alt="Shows the external accounting platform entry for Bill 1000028, with green highlights calling out the bill identifier, driver name, and its finalized Submitted state." />

  *Shows the external accounting platform entry for Bill 1000028, with green highlights calling out the bill identifier, driver name, and its finalized Submitted state.*
</Note>

### Modifying an Exported Transaction

How Alvys handles a change to an exported transaction depends on its current state in Sage:

* **Draft:** Alvys updates the transaction directly in Sage with the new values.
* **Posted:** Alvys creates a reversal entry in Sage and posts a new corrected transaction automatically.
* **Paid or Partially Paid:** You must Remove the payment from the transaction in Sage first. Once the payment is removed, Alvys can apply the reversal and post the corrected transaction.
* **Closed:** This state is a Sage-side restriction; the transaction period has been closed and cannot be modified from Alvys. Contact Alvys support with the load number and the error message if a transaction is stuck in Closed state.
* **Selected:** Alvys cannot automatically reverse a transaction in Selected state. Manually reverse the transaction in Sage Intacct, then re-sync it from Accounting > Error Transactions in Alvys.

## Settings & Permissions

Access to transaction export pages is controlled by Alvys permissions:

* Accounting > Invoicing requires **"Billing"** and **"Invoice"** permissions.
* Accounting > Carrier Settlements requires **"Billing"** and **"ViewCarrierRate"** permissions.
* Accounting > Driver Settlements requires Driver Settlements to be enabled for your account, plus the **"Billing"** and **"PayDriver"** permissions.
* Accounting > Error Transactions requires the **"Billing"** permission.

## Limits & Behavior

* Transactions in Closed state in Sage cannot be modified from Alvys; they require Alvys support to resolve.
* Transactions in Selected state require a manual reversal in Sage before re-syncing from Alvys.
* If a customer or carrier cannot be matched to a Sage record, the transaction fails and appears in Error Transactions.
* The Driver Settlement feature must be enabled on your account for Accounting > Driver Settlements to be available.
* Alvys does not automatically create Sage customer or vendor records; all matching is against existing records in Sage.

## Key Concepts

### Customer and Carrier Matching

Alvys matches exported AR transactions to Sage customers in this order:

1. By Customer ID set on the Alvys customer record (if configured)
2. By exact customer name match in Sage
3. If no match is found: the transaction fails and appears in Error Transactions; the customer must be created or linked in Sage before re-syncing

   For AP transactions, Alvys matches to Sage vendors in this order:
4. By Vendor ID set on the Alvys carrier record (if configured)
5. By exact carrier name match in Sage
6. By MC number
7. If no match is found: the transaction fails; the vendor must be created or linked in Sage before re-syncing

## Troubleshooting

### AR invoice did not export to Sage

Verify that the customer record in Alvys has a valid match in Sage by Customer ID or exact name. Verify that a GL account is mapped for the invoice line item types. Check Accounting > Error Transactions for the specific failure reason.

### AP bill did not export to Sage

Verify that the carrier record in Alvys has a valid vendor match in Sage by Vendor ID, exact name, or MC number. Check Accounting > Error Transactions for the specific failure reason.

### Payment terms are not appearing on exported invoices

Verify that Payment Terms are configured on the customer or carrier record in Alvys. If no record-level terms are set, verify that a Default Payment Terms value is configured in the Advanced Settings of the Sage Intacct connection.

### Driver Settlements section is not visible

Accounting > Driver Settlements requires the DriverSettlement feature to be enabled on your account. Verify that your user has the **"Billing"** and **"PayDriver"** permissions in Alvys.

## FAQs

**Q: What happens if a customer in Alvys does not have a matching record in Sage?**

**A:** The AR invoice will fail to export and appear in Accounting > Error Transactions. Create the customer in Sage or set the Sage Customer ID on the Alvys customer record, then re-sync the transaction from Error Transactions.

**Q: Can Alvys automatically create Sage customer or vendor records?**

**A:** No. Alvys matches to existing records in Sage. If a matching record does not exist, the transaction fails. You must create the customer or vendor in Sage manually.

**Q: What is the difference between a Posted and a Closed transaction in Sage?**

**A:** A Posted transaction has been journalized in Sage but can still be reversed by Alvys automatically. A Closed transaction has been closed for the accounting period and cannot be modified; Alvys support is required.

**Q: What should I do if a transaction is in Selected state in Sage?**

**A:** Manually reverse the Selected transaction in Sage Intacct, then return to Alvys and re-sync the transaction from Accounting > Error Transactions.

**Q: Does Alvys export driver settlement transactions to Sage?**

**A:** Yes, if the DriverSettlement feature is enabled on your account and the export driver settlements toggle is enabled in AP Settings.

**Q: What controls whether an AR invoice is split by subsidiary in Sage?**

**A:** The Invoice As field on the Alvys invoice determines whether it exports as a single entity invoice or is split by subsidiary.

**Q: Can I re-sync a failed transaction after fixing the underlying issue?**

**A:** Yes. After fixing the root cause, go to Accounting > Error Transactions and re-sync the transaction.

**Q: What permissions are required to export AR invoices?**

**A:** You need both the **"Billing"** and **"Invoice"** permissions in Alvys.

**Q: When does Alvys export carrier AP bills — immediately on upload or on a schedule?**

**A:** This depends on AP settings. If "Send carrier invoice upon upload" is enabled, the AP bill exports immediately when the carrier invoice is uploaded. If "Export Carrier Statements" is also enabled, a combined carrier statement AP bill is exported in addition to the individual bill.

## Go Deeper

* [Sage Intacct: Account Mappings](/en/help/integrations/sage-intacct-account-mappings)
* [Sage Intacct: Payments and Error Transactions](/en/help/integrations/sage-intacct-payments-and-error-transactions)
* [How to Connect Sage Intacct to Alvys and Configure Settings](/en/help/integrations/how-to-connect-sage-intacct-to-alvys-and-configure-settings)


# NetSuite: Resolve failed syncs
Source: https://docs.alvys.com/en/help/integrations/transactions-failed-to-sync-to-netsuite

Resolve NetSuite export failures in Alvys: duplicate records, unknown customer or vendor names, subsidiary mismatches, and internal ID conflicts on re-syncs.

<Note>
  When one or more transactions fail to export from Alvys to NetSuite (also called NS sync failures, accounting export errors, or failed sync), they appear on the Error Transactions page. This article explains how to identify the cause of each failure and resolve it so the transaction syncs successfully.
</Note>

## Symptom

One or more transactions did not sync from Alvys to NetSuite. The failed transactions appear on the Error Transactions page (Accounting > Error Transactions) with an error message describing why the export failed. Affected transactions are not recorded in NetSuite until the error is resolved and the transaction is successfully re-synced.

## Cause

Transactions fail to sync when NetSuite rejects the export. Common rejection reasons include duplicate records, unrecognized customer or vendor names, multiple matching entities, mismatched subsidiary assignments, and internal ID conflicts on previously zero-valued transactions. Each failure is logged with a specific error message and error code to help identify the root cause.

## Resolution

### Error Transactions page overview

The Error Transactions page (Accounting > Error Transactions) is a centralized list of all transactions that failed to export from Alvys to NetSuite or another connected accounting system.

<Note>
  <img alt="The Error Transactions page (Accounting > Error Transactions)" />

  *The Error Transactions page (Accounting > Error Transactions)*
</Note>

### The Error Transactions page includes the following columns:

* **Entity Type:** The type of Alvys transaction that failed to export, showing where the transaction originated. Examples include Load, Trip, Paystub, Deduction, Accessorial Revenue, Toll, Fuel, Escrow, E-check, and Accounting Invoice.
* **Transaction Type:** How the record is classified in the external accounting system, such as Invoice, Bill, Credit Memo, Vendor Credit, or Journal Entry.
* **Class:** The subsidiary associated with the transaction.
* **Error Message**: The message returned by the external accounting system explaining why the transaction failed.
* \*\*Status: \*\*The current state of the transaction, such as Failed or Resolved.
* **Reference**: Additional identifiers to link the transaction, such as load number, summary invoice number, or trip number.
* **Transaction Total**: The total amount of the transaction.
* **Date Created**: The date the transaction was first attempted to be exported.

### Supported Transaction Types That Can Be Re-Synced from Error Transactions

Not all transactions can be automatically re-synced from this page. Currently, only the following entity types can be re-synced:

* **Load**
* **Trip**
* **E-check**
* **Paystub**

  Before re-syncing, ensure that any necessary corrections have been made to the transaction. To re-sync:

1. Select one or more transactions from the Error Transactions page.
2. Right-click to reveal the context menu options **“Sync Transaction”** or **“Sync All Transactions.”**
3. Click **Sync Transaction** and confirm the action in the prompt.

<Note>
  <img alt="Context menu with the Sync Transaction option" />

  *Context menu with the Sync Transaction option*
</Note>

Use **Sync All Transactions** only if all transactions in the Error Transactions list are ready for export. Any transactions that still require corrections will be skipped.

### The following entity types cannot be re-synced from the Error Transactions page:

* Deduction
* Accessorial Revenue
* Fuel
* Toll
* Accounting Invoice (same as a summary invoice)
* Escrow
* Carrier Statement
* Driver Statement

For **carrier settlements, summary invoices, and driver pay**, corrections and re-syncs must be performed directly from their respective pages rather than from the general Error Transactions page.

### Clearing an Error Transaction Manually Fixed in the External System

If a transaction has been manually corrected in the external accounting system and no longer requires action in Alvys, it can be cleared from the Error Transactions page:

1. Select one or more transactions from the Error Transactions page.
2. Right-click to reveal the context menu option **“Mark as Synced.”**
3. Click **Mark as Synced** and confirm the action in the prompt.

<Note>
  <img alt="Context menu with the Mark as Synced option" />

  *Context menu with the Mark as Synced option*
</Note>

Only mark a transaction as synced if the issue is fully resolved. This action cannot be undone.

### Duplicate Record error on export

**Error message:** "DuplicateRecord: An attempt to create a duplicate record has been detected. The external id of the transaction matches an already existing transaction."

**Cause:** A record (invoice or bill) already exists in NetSuite with the same transaction number or External ID. NetSuite prevents creation of duplicate records.

<Note>
  DuplicateRecord: An attempt to create a duplicate record has been detected. The external id of the transaction matches an already existing transaction.

  <img alt="DuplicateRecord error in the Error Message column" />

  *DuplicateRecord error in the Error Message column*
</Note>

1. Search for the duplicate in NetSuite using Global Search or the transaction list. Search by transaction number, External ID, or the vendor or customer name associated with the transaction.
2. Resolve the conflict using one of the following approaches:

   * If the existing NetSuite record is valid and correct: the transaction has already been recorded. Go to the Error Transactions page in Alvys, select the transaction, right-click, and choose **Mark as synced** to clear it from the error list.
   * If the existing NetSuite record is incorrect or was created as a test: delete it in NetSuite, then proceed to the next step.
3. Go to Accounting > Error Transactions in Alvys. Select the transaction, right-click, and click **Retry sync**. Confirm the action in the prompt.
4. Verify in NetSuite that the transaction was created successfully and is linked to the correct customer, vendor, and subsidiary.

If the error persists after completing these steps, proceed to **If That Didn't Work** below.

### Customer not found in NetSuite

**Error message:** "CustomerNotFound: Customer not found for name '\[Customer Name]' and id '\[Customer ID]'"

**Cause:** Alvys cannot locate the customer in NetSuite using the NetSuite customer ID. This error is triggered when the "Use Existing Customers" setting is enabled and the External Accounting ID field in Alvys is missing, contains an incorrect ID, or points to a customer that no longer exists in NetSuite.

1. Verify that the customer exists and is active in NetSuite for the relevant subsidiary. To find the NetSuite customer ID, open the customer record in NetSuite; the ID appears in the page URL in the format: `https://[netsuite-url]/app/common/entity/custjob.nl?id=12345`.
2. In Alvys, open the customer or broker profile. Enter the correct NetSuite customer ID in the External Accounting ID field for the relevant subsidiary. Save the record.
3. Go to Accounting > Error Transactions. Select the transaction, right-click, and click **Retry sync**. Confirm the action in the prompt.
4. Verify in NetSuite that the invoice was created and is linked to the correct customer and subsidiary.

### Multiple entities found with the same name

**Error message:** "MultipleItems: Multiple items found. Multiple vendors found for name '\[Entity Name]'"

**Cause:** Alvys found more than one record in NetSuite with the same name and cannot determine which one to attach the transaction to. For bills, the entity is a vendor. For invoices, the entity is a customer.

1. Determine the transaction type: invoices use a customer as the entity; bills use a vendor.
2. Locate the duplicate entity records in NetSuite:

   * For customers: navigate to Lists > Relationships > Customers and search for the entity name.
   * For vendors: navigate to Lists > Relationships > Vendors and search for the entity name.
3. Resolve the duplicates. The recommended approach is to rename the duplicate records so each entity name is unique in NetSuite. This allows Alvys to identify the correct entity on retry.
4. Go to Accounting > Error Transactions. Select the transaction, right-click, and click **Retry sync**. Confirm the action in the prompt.
5. Verify in NetSuite that the transaction was created and is linked to the correct entity.

### Invalid combination of entity and subsidiary

**Error message:** "UnknownError: Error while accessing a resource. Invalid combination of entity and subsidiary."

**Cause:** The customer or vendor linked to the transaction is not assigned to the subsidiary being used. NetSuite requires each entity record to be explicitly assigned to the subsidiary referenced on the transaction.

<Note>
  UnknownError: Error while accessing a resource. Invalid combination of entity and subsidiary.

  <img alt="UnknownError: invalid combination of entity and subsidiary" />

  *UnknownError: invalid combination of entity and subsidiary*
</Note>

For bills, the entity is a vendor. For invoices, the entity is a customer.

1. Identify the transaction type to determine the entity type: invoices use a customer; bills use a vendor.
2. In NetSuite, open the entity record and check the Subsidiary field:

   * For customers: navigate to Lists > Relationships > Customers and open the customer record.
   * For vendors: navigate to Lists > Relationships > Vendors and open the vendor record.
3. Correct the subsidiary assignment in NetSuite. Edit the entity record and add or assign the correct subsidiary. Save the record. If your NetSuite account uses multi-subsidiary entities, verify that Multi-Subsidiary Customers or Multi-Subsidiary Vendors is enabled under Setup > Company > Enable Features > OneWorld.
4. Go to Accounting > Error Transactions. Select the transaction, right-click, and click **Retry sync**. Confirm the action in the prompt.
5. Verify in NetSuite that the transaction was created and is linked to the correct entity and subsidiary.

### Failed export of an updated zero-valued transaction

**Error message:** "UnknownError: Unknown error. An unexpected error occurred. Error ID: \[Sample Id]"

**Cause:** The transaction was originally zero-valued (\$0.00) while the "Ignore Zero Valued Transactions" setting was enabled in Alvys. Because the transaction was ignored at the time, NetSuite has no record of it. When the transaction was later updated to a non-zero value and an export was attempted, NetSuite rejected the export due to internal ID or edit sequence conflicts.

<Note>
  UnknownError: Unknown error. An unexpected error occurred. Error ID: \[Sample Id]

  <img alt="UnknownError: unexpected error with an Error ID" />

  *UnknownError: unexpected error with an Error ID*
</Note>

1. Identify the affected transaction. Confirm that it was originally \$0.00 and has since been updated to a non-zero value.
2. This error cannot be resolved manually. Contact Alvys Support and provide the following:

   * Load Number
   * Full error message
   * Error ID (shown in the error message)

## If That Didn't Work

If a transaction continues to fail after following the resolution steps above, check the following before contacting support:

* Confirm the correction was saved in NetSuite before retrying. Changes in NetSuite sometimes require a moment to propagate before a retry will succeed.
* Confirm the transaction is a supported entity type (Load, Trip, E-check, or Paystub). Unsupported types cannot be retried from the Error Transactions page and must be corrected from their source page.
* Review the Error Message and Error Code columns on the Error Transactions page. A changed error message after retry indicates the original issue was resolved but a new issue was introduced.

If the error persists and none of the causes above apply, contact Alvys Support. Provide the transaction's Error Message, Error Code, Transaction Id, and Load Number (if applicable) so the team can investigate.

## Related

* [NetSuite Integration Collection](/en/help/integrations/netsuite-integration-collection)

## FAQs

**Q: What is the Error Transactions page used for?**

**A:** It is a centralized view of transactions that failed to sync from Alvys to NetSuite or another connected accounting system. It allows users to review error messages, identify the cause of each failure, correct the underlying issue, and retry eligible transactions.

**Q: Where can I access the Error Transactions page?**

**A:** Navigate to Accounting > Error Transactions.

**Q: How do I manually clear an error for a transaction that has already been fixed in NetSuite?**

**A:** Select the transaction on the Error Transactions page, right-click, choose **Mark as synced**, and confirm. Only use this option if the issue is fully resolved. This action cannot be undone.

**Q: Can all failed transactions be re-synced from the Error Transactions page?**

**A:** No. Only Load, Trip, E-check, and Paystub entity types can be re-synced directly from this page. Other entity types must be corrected and re-synced from their respective source pages.

**Q: Why don't I see the Retry sync option for a record?**

**A:** The Retry sync option is only available for supported entity types. If the transaction is a Deduction, Fuel, Toll, Escrow, Summary Invoice (Accounting Invoice), Carrier Statement, Accessorial Revenue, or Driver Statement, it must be re-synced from the page where that record originates.

**Q: What should I do if I manually fixed the transaction in NetSuite?**

**A:** Select the transaction on the Error Transactions page, right-click, and choose **Mark as synced**. This removes the transaction from the error list and marks it as resolved. This action cannot be undone.

**Q: What causes a Duplicate Record error?**

**A:** A transaction already exists in NetSuite with the same transaction number or External ID. NetSuite prevents the creation of duplicate records.

**Q: How do I resolve a Customer Not Found error?**

**A:** Verify that the customer exists and is active in NetSuite and that the correct NetSuite customer ID is entered in the External Accounting ID field in the customer or broker profile in Alvys. After correcting, retry syncing from the Error Transactions page.

**Q: What does the Multiple Items Found error mean?**

**A:** NetSuite found more than one customer or vendor with the same name and could not determine which one to attach the transaction to. Rename the duplicate records in NetSuite so each entity name is unique, then retry.

**Q: Why am I seeing "Invalid combination of entity and subsidiary"?**

**A:** The customer or vendor assigned to the transaction is not linked to the subsidiary used on that transaction in NetSuite. The entity record must be explicitly assigned to the correct subsidiary in NetSuite before the export will succeed.

**Q: Can subsidiary-related errors be fixed in Alvys?**

**A:** No. Subsidiary assignments must be corrected in NetSuite by updating the customer or vendor record to include the correct subsidiary.

**Q: What causes the UnknownError for updated zero-valued transactions?**

**A:** The transaction was originally \$0.00 while the "Ignore Zero Valued Transactions" setting was enabled, then later updated to a non-zero value. NetSuite rejects the export due to internal ID or edit sequence conflicts because no record was created for the transaction when it was first processed.

**Q: Can I fix zero-valued transaction errors myself?**

**A:** No. Contact Alvys Support and provide the Load Number, the full error message, and the Error ID shown in the error message.

**Q: When should I contact Alvys Support?**

**A:** Contact Alvys Support if a transaction continues to fail after you have applied the relevant resolution steps, if the error message is unclear and does not match any of the scenarios above, or if you encounter an UnknownError that cannot be resolved through standard troubleshooting.


# TruckStop Load Board Integration
Source: https://docs.alvys.com/en/help/integrations/truckstop-load-board-integration

Integrate Truckstop with Alvys for seamless load posting. Follow this guide to set up, troubleshoot, and ensure a smooth workflow.

<Note>
  The TruckStop integration (also called the TruckStop load board integration) connects your Alvys account to the TruckStop load board so you can post and manage loads directly from Alvys. Setup requires authenticating with your TruckStop account credentials through the Integrations page.
</Note>

## Overview

Alvys integrates with TruckStop to allow users to post loads from Alvys directly to the TruckStop load board. This is a one-way integration: load data flows from Alvys to TruckStop. Once connected, users with the **"TruckStop"** permission can post, update, and remove load listings on TruckStop without leaving Alvys.

TruckStop is also known as [Truckstop.com](http://truckstop.com/) and is part of the Truckstop Group. It is one of the major digital freight marketplace platforms used for load board services.

## Prerequisites

Before connecting TruckStop, confirm the following:

* Your Alvys user account has the **"TruckStop"** permission assigned. If you do not have this permission, contact your administrator.
* You have active TruckStop account credentials (username and password).
* Your TruckStop account has the permissions required to connect third-party integrations. If you are unsure, contact TruckStop support.
* You have your default posting email address available. This is the email TruckStop will use to route load posting notifications.

## How to connect?

1. Open the Integrations page. Navigate to **Management > Integrations** in Alvys. Locate TruckStop in the Load Board Integrations section.
2. Remove an existing integration if it is not working. If TruckStop is already listed but not functioning correctly, remove and re-add the integration. Authentication tokens can become stale or invalid over time; removing and reconnecting refreshes the connection. To remove, find TruckStop in the list and click **Deactivate**. Save your TruckStop login credentials before doing this: you will need them to reconnect. Once deactivated, the integration will be removed from the list.
3. Add the TruckStop integration. Select **TruckStop** from the list, enter your default posting email address, then click **Save**.
4. Authenticate with TruckStop. A new window will open, redirecting you to the TruckStop login page. Enter your TruckStop username and password. If prompted, complete any additional verification steps such as multi-factor authentication. Approve any access requests to allow Alvys to connect to your TruckStop account.
5. Confirm the integration is working. After authenticating, you will be redirected back to the Alvys Integrations page. Check the status of TruckStop in the list. If the status shows **Integrated**, the setup is complete.

## What syncs?

When you post a load from Alvys to TruckStop, the load details, including origin, destination, equipment type, and rate, are sent to TruckStop and displayed on the load board. The default posting email you entered during setup is used by TruckStop to route carrier responses and notifications for that load.

This integration is one-way: Alvys pushes load data to TruckStop. TruckStop does not send load data back into Alvys. Any changes made to a load in Alvys after posting must be updated in Alvys; those updates will sync to the TruckStop listing.

To verify the integration is working after completing setup:

1. Navigate to **Management > Integrations** and confirm TruckStop shows a status of **Integrated**.
2. Post a load to TruckStop from within Alvys.
3. Log in to your TruckStop account directly and confirm the load appears in your listings.

<Note>
  📋 TruckStop does not send load data back into Alvys; carrier responses and bookings must be managed in your TruckStop account. · Only users with the **"TruckStop"** permission can interact with TruckStop-powered features in Alvys. · Each subsidiary that should have access to TruckStop load posting must have the integration configured separately within its own settings.
</Note>

## Troubleshooting

### Incorrect credentials error

Reset your TruckStop password and attempt the authentication step again.

### Redirect not working during authentication

Clear your browser cache or switch to an incognito window. Ensure your browser is not blocking popups for the Alvys domain.

### Stuck on authentication screen

Verify that your TruckStop account has the permissions needed to authorize third-party integrations. Contact TruckStop support if the account settings need to be adjusted.

### Integration status does not show Integrated after setup

Check that the authentication completed successfully and that you were redirected back to the Alvys Integrations page. If the status still does not update, deactivate the integration and repeat the setup steps. If the issue persists, contact Alvys Support.

### Browser extension interfering with authentication

Some browser extensions (including ad blockers or security tools) can block the TruckStop authentication redirect. Disable extensions temporarily and retry.

## FAQs

**Q: What is the default posting email used for?**

**A:** The default posting email is used when posting loads to TruckStop. TruckStop uses this address to route carrier notifications and responses to the correct contact on your team.

**Q: Why do I need to remove and re-add the integration if it is not working?**

**A:** Authentication tokens can become stale or invalid over time. Removing and re-adding the integration refreshes the connection and resolves most authentication issues.

**Q: Can I use the same TruckStop account for multiple subsidiaries?**

**A:** Yes, but you must configure the integration settings for each subsidiary separately within Alvys. Each subsidiary that needs access to TruckStop load posting requires its own integration setup.

**Q: How do I know if my loads are successfully posting to TruckStop?**

**A:** After integration is complete, verify successful posts by logging in to your TruckStop account directly and checking your load listings. You can also monitor load responses in Alvys.

## Go Deeper

* [Alvys Carrier Marketplace](/en/help/integrations/alvys-carrier-marketplace)


# Connecting to Google Sheets
Source: https://docs.alvys.com/en/api/guides/alvys-data-import-template-quick-setup-guide

Import live Alvys loads, trips, customers, drivers, carriers, and invoices into Google Sheets using the Public API template, with no coding required.

(Public API → Google Sheets)

Quickly connect your Alvys account and import live operational data — **Loads, Trips, Customers, Drivers, Carriers, Invoices, and more** — directly into **Google Sheets**.
No coding or manual exports required.

***

## ⚙️ Step 1. Download the Alvys API → Google Sheets Import Template

Click the link below to make your own copy of the file in Google Sheets:

<Note>
  `<Anchor label="👉 **Make a Copy in Google Drive**" target="_blank" href="https://docs.google.com/spreadsheets/d/11HyDR1nf8U0MNahMPUp6_e5XpkDGeJIBXs7W5oBlVCA/copy">`👉 **Make a Copy in Google Drive**`</Anchor>`
</Note>

<Image />

* Once you click “**Make a copy**”,
  * The file will be added to your own Google Drive.
  * The attached Apps Script functionality will also be copied.
  * You can immediately open and start using it in Google Sheets.

<Warning>
  Make a Copy in Google Drive. The first time you open it, Google Sheets will ask you to grant permissions.
  Click Continue → Allow all — this enables the secure connection to the Alvys Public API.
  You may need to reload the file once after granting access.
</Warning>

1. <Image />

   After granting access, reload the file once if requested.
2. After saving, you’ll see the **Welcome Sheet**.

> “This file connects directly to the Alvys Public API.
> Use it to import live operational data — including Loads, Trips, Customers, Drivers, Carriers, and more — directly into Google Sheets.”

***

## 🔑 **Step 2. Get Your Client Credentials**

Your credentials are available in your Alvys portal:
🔗 [**Alvys Portal → API Access page**](https://app.alvys.com/#/manage/public-api)

Copy your:

* **Client ID**
* **Client Secret**
* **Tenant ID**

<Warning>
  Important: Make sure your application credentials have all required **read permissions.**
  Missing read scopes will result in incomplete or failed imports.
</Warning>

Then in the Google Sheet:

<Image />

1. Go to **Alvys → Configure…**
2. Paste your credentials and click **Save**

✅ Your credentials are stored privately in your file.

<Note>
  The Client Secret is hidden from view after saving and securely stored within the sheet’s script properties.
  Collaborators who use the file can see imported data, but only the file owner or editors with Apps Script access could technically view stored credentials.
</Note>

***

## 🔄 **Step 3. Import Your Data**

Use the **Alvys** menu in the top toolbar to start importing.

<Image />

`<Table>`

<thead>
  <tr>
    <th>
      Action
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      **📦 Full Import (🧹 Full replace)**
    </td>

    <td>
      Loads all records from scratch and replaces existing data.
    </td>
  </tr>

  <tr>
    <td>
      **🔁 Sync (Incremental update)**
    </td>

    <td>
      Imports only records changed since the last sync (using `updatedAt`
      and `daysBack `).
    </td>
  </tr>
</tbody>

`</Table>`

Each dataset (*Loads*, *Trips*, *Customers*, *Drivers*, *Carriers*, etc.) appears in its own tab.
Check the **Log** tab for import time, status, and record count.

***

## 🕒 **Step 4. (Optional) Enable Automatic Sync**

To keep your Loads and Trips updated automatically:

1. Go to **Alvys → Configure Auto Sync…**
2. Choose how often it should run (e.g., every 6 hours).
3. A background trigger will fetch records updated within the past *(Frequency + 1 hour)*.

***

## 💡 **Tips & Notes**

* ✅ Use **Full Import** the first time you connect.
* ⚡ Then switch to **Incremental Sync** for faster updates.
* 🔐 Your credentials stay private in your own sheet.
* ⏳ The sidebar may take **2–6 seconds** to open — that’s normal.
* ⚠️ For large data imports, run each entity (Loads, Trips, Customers, etc.) manually and one at a time — wait for each to finish before starting another.
* ⚠️ Google Sheets has a fixed runtime limit defined by Google. If you’re importing high-volume data, allow each import to complete or split the process into smaller batches.


# Authenticate with the Alvys Public API
Source: https://docs.alvys.com/en/api/guides/authentication-1

Authenticate with the Alvys Public API using the OAuth 2.0 Client Credentials flow, including creating client apps, requesting tokens, and scopes.

This page explains how to authenticate with the Alvys Public API using the OAuth 2.0 Client Credentials flow.

By leveraging OAuth 2.0, developers can empower their applications to seamlessly interact with Alvys' API on behalf of their users. This guide outlines the authentication process and provides detailed instructions on obtaining access tokens through direct application integration.

<Info>
  Getting API Access

  * Existing Alvys customers can obtain API access by contacting their account representative.
  * Independent Software Vendors (ISV) should contact the Alvys Partnership team.
</Info>

### 🔐 Creating Client Application Credentials

Follow these steps to create your credentials in the Alvys Admin Portal:

1. Navigate to **Admin → API Access**
2. Click **Create New Application**
3. Fill out the **Name** and **Description**
4. Select your desired **permissions** (scopes)
5. Set an optional **expiration date** for the credentials
6. Click **Generate**

   <img alt="" />

After creation, your **Client ID** and **Client Secret** will be shown, along with the scopes included for token generation. Customers can generate up to 10 sets of client credentials, but only newly generated ones can be edited.

<Warning>
  These values are sensitive and must be stored securely—avoid sharing them publicly or exposing them in front-end code.
</Warning>

<img alt="" />

These credentials are used to request an access token via the issue token endpoint.

### Construct Authorization Request

Construct a URL with the following parameters in the request body:

1. `client_id`: The unique identifier assigned to your application by Alvys.
2. `client_secret`: The confidential token provided by Alvys upon application registration.
3. `audience`: Must be `"https://api.alvys.com/public/"`.
4. `grant_type`: The type of grant flow to use. **Must be `client_credentials`**

### 🔐 New Token Endpoint

All new token requests must now use the following endpoint:

### Token URL

```
https://auth.alvys.com/oauth/token

```

### Request Body (JSON)

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}

```

<Tip>
  When including a "scope" field in the token request body, please note:

  * The returned token will **always include all scopes** that have been granted to your client application, regardless of what you specify in the scope field.
  * Therefore, including a `scope` field in the request **does not override or limit the access** defined by your assigned permissions in the issued token.
  * The only functional effect of providing a `scope` field is that the token request will fail (unauthorized) if you include any scope that has not been granted to your client.
  * If the `scope` field is omitted, the token will still include **all scopes** granted to your application.
</Tip>

Either format may be used (JSON or Form-Encoded); both will return the same token and enforce scopes identically.

### Curl JSON Content-Type Example

```bash theme={null}
curl --request POST \
     --url 'https://auth.alvys.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "audience": "https://api.alvys.com/public/",
       "grant_type": "client_credentials"
     }'

```

### Curl Form-Encoded Format Example

```bash theme={null}
curl --request POST \
     --url https://auth.alvys.com/oauth/token \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data 'client_id=YOUR_CLIENT_ID' \
     --data 'client_secret=YOUR_CLIENT_SECRET' \
     --data 'audience=https://api.alvys.com/public/' \
     --data 'grant_type=client_credentials'

```

The token you receive will include a scope claim (e.g. `"load:read trip:create"`), and our Public API enforces those scopes on every request. Use the resulting access token in your API request headers:

```
Authorization: Bearer YOUR_ACCESS_TOKEN

```

> The `client_id` and `client_secret` are created in the Alvys Admin Portal under API Access.

### Postman Token Request Example:

<img alt="" />

**Each client credential’s token is restricted to the exact scopes you assign, ensuring it can only access those corresponding API endpoints.**

***

<Warning>
  ***Note***

  *Some write endpoints are already published in the [API Reference](/en/api/reference/loads/update-load)—for example, load updates and load notes. Other `create`, `update`, and `delete` scopes may still lack a matching partner endpoint; check the API Reference for what is available today.*
</Warning>

***

### 🔒 Scope Claim

**Important:** Legacy tokens generated through the previous `/api/authentication/{tenant_id}/token` authentication flow do not include the `scope` claim. These tokens will temporarily remain valid and behave as if all read-only scopes are granted, but this is only supported during the transition period. All clients must migrate to the new flow by **July 31, 2025** to avoid disruption.

New tokens now follow a fine-grained permissions model, ensuring each application only has access to the specific API features it was granted.

Example:

```
"scope": "load:read driver:create"

```

Scopes control access to API endpoints and must be selected when creating your application in the Admin Portal.

### Available Scopes

| Entity               | Permission           | Description                           |
| -------------------- | -------------------- | ------------------------------------- |
| Accessorials         | `accessorial:read`   | View accessorial types                |
| Accessorials         | `accessorial:create` | Raise an accessorial or post a credit |
| Customers            | `customer:read`      | View customer records                 |
| Customers            | `customer:create`    | Add a customer                        |
| Customers            | `customer:update`    | Edit customer details                 |
| Customers            | `customer:delete`    | Remove a customer                     |
| Deductions           | `deduction:read`     | View deductions                       |
| Deductions           | `deduction:create`   | Create a deduction or a driver credit |
| Deductions           | `deduction:delete`   | Delete a deduction                    |
| Drivers              | `driver:read`        | View driver profiles                  |
| Drivers              | `driver:create`      | Add new driver                        |
| Drivers              | `driver:update`      | Edit driver info                      |
| Drivers              | `driver:delete`      | Remove a driver                       |
| Fuel                 | `fuel:read`          | View fuel records                     |
| Fuel                 | `fuel:create`        | Add fuel transaction                  |
| Fuel                 | `fuel:update`        | Update fuel entry                     |
| Fuel                 | `fuel:delete`        | Delete fuel record                    |
| Invoices             | `invoice:read`       | View invoices                         |
| Invoices             | `invoice:create`     | Create invoice                        |
| Invoices             | `invoice:update`     | Edit invoice                          |
| Invoices             | `invoice:delete`     | Delete invoice                        |
| Loads                | `load:read`          | Retrieve load info                    |
| Loads                | `load:create`        | Create a load                         |
| Loads                | `load:update`        | Update a load                         |
| Loads                | `load:delete`        | Delete a load                         |
| Maintenance          | `maintenance:read`   | View maintenance data                 |
| Maintenance          | `maintenance:create` | Log maintenance event                 |
| Maintenance          | `maintenance:update` | Edit maintenance record               |
| Maintenance          | `maintenance:delete` | Remove maintenance record             |
| Tolls                | `toll:read`          | View toll data                        |
| Tolls                | `toll:create`        | Log toll                              |
| Tolls                | `toll:update`        | Update toll entry                     |
| Tolls                | `toll:delete`        | Delete toll entry                     |
| Trailers             | `trailer:read`       | View trailer info                     |
| Trailers             | `trailer:create`     | Register trailer                      |
| Trailers             | `trailer:update`     | Edit trailer record                   |
| Trailers             | `trailer:delete`     | Remove trailer                        |
| Trips                | `trip:read`          | View trip details                     |
| Trips                | `trip:create`        | Create trip                           |
| Trips                | `trip:update`        | Update trip                           |
| Trips                | `trip:delete`        | Cancel/delete trip                    |
| Trucks               | `truck:read`         | View truck info                       |
| Trucks               | `truck:create`       | Register truck                        |
| Trucks               | `truck:update`       | Update truck record                   |
| Trucks               | `truck:delete`       | Remove truck                          |
| Users                | `user:read`          | View users                            |
| Users                | `user:create`        | Add new user                          |
| Users                | `user:update`        | Modify user                           |
| Users                | `user:delete`        | Remove user                           |
| Visibility           | `visibility:read`    | Access tracking data                  |
| Visibility           | `visibility:create`  | Trigger visibility update             |
| Visibility           | `visibility:update`  | Modify visibility data                |
| Visibility           | `visibility:delete`  | Remove tracking entry                 |
| Dispatch Preferences | `dispatch:read`      | View dispatch rules                   |
| Dispatch Preferences | `dispatch:update`    | Update dispatch preferences           |
| Carriers             | `carrier:read`       | View carrier profiles                 |
| Carriers             | `carrier:create`     | Add a new carrier                     |
| Carriers             | `carrier:update`     | Update carrier details                |
| Carriers             | `carrier:delete`     | Remove a carrier from records         |
| Subsidiaries         | `subsidiary:read`    | List and read subsidiaries            |

<Note>
  `subsidiary:read` is not granted by any other scope, and API clients issued before it existed do not carry it. Grant it to the client before calling the [subsidiaries endpoints](/en/api/reference/subsidiaries/list-subsidiaries).
</Note>

<br />

***

### 🧪 Troubleshooting

* ✅ Double-check your `client_id`, `client_secret`, and `audience`
* ✅ Ensure scopes are correctly assigned in API Access- Admin Portal
* ✅ Validate that the client is active and not expired
* ✅ Use only supported content types: `application/json` or `application/x-www-form-urlencoded`
* For technical support: `<support@alvys.com>`


# Authentication and Global Permissions
Source: https://docs.alvys.com/en/api/guides/authentication-2

Configure Power BI parameters, retrieve an Alvys API access token, and set global permissions so subsequent queries authenticate against the Public API.

To interact with the Alvys API, you must first retrieve an access token using your API credentials. This token is required for authenticating all subsequent API queries.

## Authentication

### **Create an Access Token Query**:

* Open Power BI Desktop and go to **Home > Transform Data**.

<img alt="" />

**Setup API Credentials in Manage Parameters**

* In Power BI, go to the top ribbon, select **Transform Data > Manage Parameters**.
* **Ensure You Have the Following Parameters**:
  * `client_id`: The client ID provided by Alvys.
  * `client_secret`: The client secret provided by Alvys.
* **Create New Parameters if Not Present**:
  * If these parameters are not already available:
    * Click **New** to create a new parameter.
    * Use the exact names: `client_id` and `client_secret`.
* Replace the **Current Value** of each parameter with your respective credentials.

> ❗️ Important: Ensure the parameter names match exactly as defined here. If you use different names, you must update them in the `AccessToken` query accordingly.

* Once you've entered your credentials, click **OK** and then **Close & Apply** to save the changes.

<img alt="" />

<br />

* **Add a New Blank Query**:

To add a new query, you have two options:

1. **From the Ribbon**: Go to **Home > New Source > Blank Query**.

   <img alt="" />

   <br />

2. **From the Queries Pane**: Right-click on any existing query (or in the empty space under the list of queries) and select **New Query > Blank Query**.

   <img alt="" />

   <br />

<br />

1. Rename the query to `AccessToken`. In the **Queries Pane**, right-click on the newly created query and select **Rename**.

> ❗️ 📢 **Use exactly this name. The name will be referenced by other queries that require this token for authentication.**

<img alt="" />

<br />

* In the Advanced Editor, add the code below.

```
let  
    // Define the token endpoint  
    url = "https://auth.alvys.com/oauth/token",

// URL-encode the client_secret, NOTE: should be used parameters Name for client_secret)
    
encodedClientSecret = Uri.EscapeDataString(client_secret),

// Construct the form data as a URL-encoded string
formData = "client_id=" & client_id & "&" &
           "client_secret=" & encodedClientSecret & "&" &
           "audience=" & Uri.EscapeDataString("https://api.alvys.com/public/") & "&" &
           "grant_type=client_credentials",

// Make the POST request
binaryFormData = Text.ToBinary(formData),
response = Web.Contents(url, [
    Headers = [
        #"Content-Type" = "application/x-www-form-urlencoded"
    ],
    Content = binaryFormData
]),

// Parse the JSON response to extract the token
jsonResponse = Json.Document(response),
accessToken = jsonResponse[access_token]

in  
    accessToken
```

Save and close the query.

* **Expected Result**: The `AccessToken` query will return the `accessToken`, which can be dynamically used in other API queries.

<img alt="" />

<br />

### Authentication and Global Permissions

The first time you attempt to connect to the Alvys API in Power BI, you will be prompted to authenticate. Follow these steps to configure the required settings:

1. Choose **Anonymous** for the Web API connection.
2. **Click Connect.** Once these settings are selected, click **Connect** to proceed.

<img alt="" />

3. **Privacy Level**: Click on the Data source settings > Global permissions > Edit permissions > in the Privacy Level dropdown, ensure the privacy level is set appropriately (e.g., Organizational or Public) for your environment.

<img alt="" />

<br />

> Note: You might be prompted to repeat this process for other endpoints if they are accessed for the first time. Ensure the same settings are applied for consistency across all queries.


# Available MCP Tools
Source: https://docs.alvys.com/en/api/guides/available-mcp-tools

Catalog of tools exposed by the Alvys MCP server, grouped by domain (loads, drivers, trips, invoices) with tier, scope, and permission requirements.

This page lists every tool the Alvys [MCP server](/en/api/guides/mcp) exposes to AI agents. Each tool maps 1:1 to an Alvys Public API capability and requires a specific permission (scope). Your token must carry that scope for the call to succeed.

**Tool tiers**

* **Read** — retrieve data. Always available.
* **Write** — create or update data. Disabled during beta.

Scopes use the `{resource}:{action}` convention and match the [Public API scope catalog](/en/api/guides/authentication-1#available-scopes). Assign them to your application in **Admin → API Access**.

<Warning>
  During beta, the server is **read-only**. Write tools (marked below) are disabled.
</Warning>

***

## Conventions

The MCP tool surface mirrors the Public API request/response shapes so calls port 1:1 between the two.

**Paging.** All search tools accept `page` (0-based, default `0`) and `pageSize` (default `25`, max `100`). Responses echo the request `page` back so agents can drive their own pager. `page=-1` (or any negative value) is rejected with `[invalid_params]`.

<Warning>
  **Breaking (2026-07-23):** paging is now 0-based, matching the Public API. Callers that previously sent `page=1` to get the first page must now send `page=0`. See the [changelog](/en/api/changelog).
</Warning>

**Array filters.** Filters that map to `/search` array fields on the Public API (`statuses`, `status`, `loadNumbers`, `orderNumbers`, `mcNumbers`, `dotNumbers`, `tripNumbers`, `driverIds`, and so on) are declared as **arrays** on the tool. Pass one or many values in a single call.

**Date ranges.** Date-range filters are objects: `{ start, end }` in ISO-8601 (e.g. `{ "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" }`). The parameter names match the Public API — `createdDateRange`, `pickupDateRange`, `deliveryDateRange`, `invoicedDateRange`, `paidDateRange`, `transactionRange`. Legacy split-string parameters (`createdFrom` / `createdTo`, `pickupFrom` / `pickupTo`, etc.) are no longer accepted.

**Strict arguments.** Unknown keys — misspellings, unsupported filters, or parameters that no longer exist — are **rejected** with `[invalid_params]`. The error message names the rejected keys and the valid parameter list so an agent can self-correct in one round trip. Nested keys inside a date range or array element are validated too. Missing required arguments and wrong-type values (for example `page: "not-an-int"`) also return structured `[invalid_params]` errors naming the parameter — for both tools and prompts.

<Info>
  Why: previously, the MCP SDK bound arguments by name and silently discarded unknown ones. `customers_search name="Colortech"` returned the full unfiltered customer list because `name` isn't a valid filter on that tool. That silent-drop behavior is gone — you now get an actionable error instead of a confidently-wrong result.
</Info>

**Tool annotations.** Each tool advertises MCP `annotations` safety hints that mirror the Read / Write / Destructive tiers on this page: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Your MCP client can use these hints to decide whether to ask a human before running a tool. During beta, every exposed tool is read-only and sets `readOnlyHint: true` (and `destructiveHint: false`).

Example rejection:

```json theme={null}
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "[invalid_params] Unknown parameter(s) for customers_search: 'name'. Valid parameters: createdDateRange, page, pageSize, statuses. Unknown parameters are rejected instead of silently ignored so a misspelled filter cannot return unfiltered results."
    }
  ]
}
```

***

## Loads

| Tool              | Tier | Scope       | Description                                                                                                |
| ----------------- | ---- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `loads_search`    | Read | `load:read` | Search loads by `status`, `loadNumbers`, `orderNumbers`, and/or `customerId`. Provide at least one filter. |
| `loads_get_by_id` | Read | `load:read` | Fetch a single load including stops, charges, and assignment.                                              |

## Trips

| Tool                            | Tier  | Scope         | Description                                                                                                                                                                                                                          |
| ------------------------------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `trips_search`                  | Read  | `trip:read`   | Search trips by `status`, `loadNumbers`, `tripNumbers`, `pickupDateRange`, and/or `deliveryDateRange`. Provide at least one filter; a date range alone is sufficient.                                                                |
| `trips_get_by_id`               | Read  | `trip:read`   | Fetch a single trip including its ordered stops.                                                                                                                                                                                     |
| `trips_record_arrival`          | Write | `stop:update` | Record an arrival event on a trip stop.                                                                                                                                                                                              |
| `trips_record_departure`        | Write | `stop:update` | Record a departure event on a trip stop. Server enforces that an arrival must exist first.                                                                                                                                           |
| `trips_update_stop_appointment` | Write | `stop:update` | Update the appointment (or FCFS window) on a trip stop. `scheduleType` must be `APPT` or `FCFS`; `appointmentDate` is required for `APPT`, `windowBegin` for `FCFS`.                                                                 |
| `trips_assign`                  | Write | `trip:update` | Assign a carrier, and optionally drivers and equipment, to a trip. Resolve ids first through the search tools. Assigns without dispatching, and recalculates mileage and rate. `driver1Id` is required when `driver2Id` is provided. |

## Drivers

| Tool                    | Tier | Scope         | Description                                                                                                                                        |
| ----------------------- | ---- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drivers_search`        | Read | `driver:read` | Search drivers by `name` and/or ELD duty `status` (array). Provide at least one filter. Duty states are ELD telemetry, not dispatch availability.  |
| `drivers_get_by_id`     | Read | `driver:read` | Fetch a single driver record.                                                                                                                      |
| `drivers_events_search` | Read | `driver:read` | Fetch ELD / duty event history over a date range for one or more drivers (`driverIds` array). Returns raw events, not an Hours-of-Service verdict. |

## Carriers

| Tool                       | Tier  | Scope            | Description                                                                                           |
| -------------------------- | ----- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `carriers_search`          | Read  | `carrier:read`   | Search carriers by `status`, `mcNumbers`, and/or `dotNumbers`. Provide at least one filter.           |
| `carriers_get_by_id`       | Read  | `carrier:read`   | Fetch a single carrier including insurance and authority data.                                        |
| `carriers_documents_get`   | Read  | `carrier:read`   | List documents on file for a carrier.                                                                 |
| `carriers_set_status`      | Write | `carrier:update` | Change a carrier's status (e.g. activate after onboarding).                                           |
| `carriers_document_upload` | Write | `carrier:update` | Upload a carrier onboarding document. Send the file as base64; the decoded file must be 5 MB or less. |

## Customers

| Tool                  | Tier  | Scope             | Description                                                                                                                                                                                                                 |
| --------------------- | ----- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customers_search`    | Read  | `customer:read`   | Search customers by `statuses` (array; defaults to Active, Inactive, Disabled) and/or `createdDateRange`. Results are ordered oldest-first by record-creation date. There is no `name` filter — page and match client-side. |
| `customers_get_by_id` | Read  | `customer:read`   | Fetch a single customer including contacts and billing address.                                                                                                                                                             |
| `customers_create`    | Write | `customer:create` | Create a new customer.                                                                                                                                                                                                      |

## Trucks & Trailers

| Tool                   | Tier | Scope          | Description                                                                                                                                                                                                                                                                       |
| ---------------------- | ---- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trucks_search`        | Read | `truck:read`   | Search trucks (power units) by `truckNumber` and/or `status` (array). Provide at least one filter.                                                                                                                                                                                |
| `trucks_get_by_id`     | Read | `truck:read`   | Fetch a single truck by id.                                                                                                                                                                                                                                                       |
| `trucks_events_search` | Read | `truck:read`   | Fetch truck events (maintenance, schedule, availability) for one or more trucks over a date range. Pass `truckIds` (array of Alvys truck ids, not unit numbers) and a `startDate`; `endDate` is optional. Returns a flat event list — an empty list means no events in the range. |
| `trailers_search`      | Read | `trailer:read` | Search trailers by `trailerNumber` and/or `status` (array). Provide at least one filter.                                                                                                                                                                                          |
| `trailers_get_by_id`   | Read | `trailer:read` | Fetch a single trailer by id.                                                                                                                                                                                                                                                     |

## Invoices, Fuel & Payments

| Tool                               | Tier  | Scope            | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | ----- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoices_search`                  | Read  | `invoice:read`   | Search invoices by `customerId`, `status`, `loadNumbers`, and/or `orderNumbers`, optionally narrowed by `invoicedDateRange` / `paidDateRange`. Provide at least one non-date filter — date ranges narrow results but do not count on their own. `invoicedDateRange` filters on invoice-record creation date (includes `Draft`), so pair it with a status filter for billed-amount questions. |
| `invoices_get_by_id`               | Read  | `invoice:read`   | Fetch a single invoice including line items.                                                                                                                                                                                                                                                                                                                                                 |
| `fuel_transactions_search`         | Read  | `fuel:read`      | Query fuel transactions by `truckNumber` and/or `transactionRange`. Provide at least one filter.                                                                                                                                                                                                                                                                                             |
| `invoices_record_carrier_payment`  | Write | `invoice:update` | Record a payment to a carrier against a trip. Idempotent on `referenceNumber`. When payments fully cover the carrier payable, the trip transitions to `Completed`.                                                                                                                                                                                                                           |
| `invoices_record_customer_payment` | Write | `invoice:update` | Record a payment received from a customer against a load. Idempotent on `referenceNumber`.                                                                                                                                                                                                                                                                                                   |
| `invoices_record_financing`        | Write | `invoice:update` | Record a factoring / financing transaction against a load. Idempotent on `referenceNumber`.                                                                                                                                                                                                                                                                                                  |

## Accessorials & Credits

Accessorials are extra charges raised on a load or trip. Credits reduce what is owed. Both use the same reference data: call `accessorials_list_types` first to get the `typeId`, the `rateType` ids that type allows, and the `rateUom` ids valid for each of those rate types.

| Tool                           | Tier  | Scope                | Description                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------ | ----- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accessorials_list_types`      | Read  | `accessorial:read`   | List the tenant's accessorial types — the reference data every accessorial create needs. Returns each type's `Id`, `Name`, whether it `RequiresStop`, and the `RateTypes` it allows with their permitted units of measure. Pass `includeDeleted=true` to also return soft-deleted types, which are reference data only and cannot be charged against. |
| `accessorials_create_driver`   | Write | `accessorial:create` | Create a driver accessorial — an extra amount paid to a driver on a trip (detention, layover, extra stop). `rate` must be greater than zero. Set `applyDriverRate=true` to apply the driver's configured fee percentage to the rate you pass.                                                                                                         |
| `accessorials_create_customer` | Write | `accessorial:create` | Create a customer accessorial — an extra amount billed to the customer on a load. `rate` must be greater than zero.                                                                                                                                                                                                                                   |
| `accessorials_create_carrier`  | Write | `accessorial:create` | Create a carrier accessorial — an extra amount paid to a carrier on a brokerage trip. `rate` must be greater than zero.                                                                                                                                                                                                                               |
| `credits_create_customer`      | Write | `accessorial:create` | Post a customer accessorial credit, reducing what the customer owes on a load. `rate` must be a negative value.                                                                                                                                                                                                                                       |
| `credits_create_carrier`       | Write | `accessorial:create` | Post a carrier accessorial credit on a brokerage trip, reducing what the carrier is owed. `rate` must be a negative value.                                                                                                                                                                                                                            |

There is no driver credit tool. A driver credit is a different object from an accessorial — a settlement record rather than a charge on a trip — and is created through the Public API with [Create driver credit](/en/api/reference/credits/create-driver-credit), which uses the `deduction:create` scope.

### Rate type and unit of measure

`rateType` and `rateUom` are sent as ids, and the valid combinations come from `accessorials_list_types` for the type you are charging.

| `rateType` | Meaning  | Valid `rateUom` ids                |
| ---------- | -------- | ---------------------------------- |
| `1`        | Flat     | `0` only                           |
| `2`        | Weight   | `0` kg, `2` lbs, `4` tons, `5` cwt |
| `3`        | Distance | `0` miles, `1` km                  |
| `4`        | Volume   | `0` gallons, `2` bushels           |
| `5`        | Time     | `0` minutes, `1` hours, `2` days   |
| `6`        | Per Unit | `0` only                           |

`quantity` must be greater than zero, except with a Flat `rateType`, which bills the rate once and forces quantity to `1`.

Pass `stopId` when the accessorial type returns `RequiresStop: true`.

### Idempotency on accessorial and credit writes

Every create tool accepts an optional `externalId` — your own key for the record, unique within your tenant. Send the same value on a retry and the original record is returned instead of a second one being created. Omit it and a retry creates a second record.

* Keys are case-sensitive and compared after trimming surrounding whitespace.
* A retry must ask for the same work: the same `rate`, `quantity`, `rateType`, `rateUom`, and (for driver accessorials) `applyDriverRate`, plus the same trip or load, accessorial type, stop, and driver. Reusing a key with any of those changed is refused with `409`.
* `notes` is not compared. A retry with a corrected note returns the original unchanged.
* A key stays spent after the accessorial is deleted, and cannot be reused across kinds (driver, customer, carrier).

<Warning>
  These tools move money. Create only after a human has confirmed the amount. A `503` means the record could not be confirmed, not that it was not created — if you sent an `externalId`, retry the identical request; if you did not, confirm whether the record exists before retrying.
</Warning>

## Visibility & Tracking

| Tool                          | Tier | Scope             | Description                                |
| ----------------------------- | ---- | ----------------- | ------------------------------------------ |
| `visibility_inbound_history`  | Read | `visibility:read` | Fetch inbound tracking events for a load.  |
| `visibility_outbound_history` | Read | `visibility:read` | Fetch outbound tracking events for a load. |

## Deductions

| Tool                   | Tier | Scope            | Description                                                                                                                                                             |
| ---------------------- | ---- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deductions_search`    | Read | `deduction:read` | Search deductions for a `driverId`, `truckId`, or `ownerOperatorId`. Provide at least one. Pass `includePaid=true` to also return paid deductions (default: open only). |
| `deductions_get_by_id` | Read | `deduction:read` | Fetch a single deduction by id.                                                                                                                                         |

## Tenders

| Tool                     | Tier  | Scope           | Description                                                                                                                            |
| ------------------------ | ----- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `tenders_search`         | Read  | `tender:read`   | Search inbound tenders by `status` (array), `loadNumber`, and/or `shipmentId`.                                                         |
| `tenders_get_by_id`      | Read  | `tender:read`   | Fetch a single inbound tender.                                                                                                         |
| `tenders_create`         | Write | `tender:create` | Create (ingest) a new inbound tender. Requires at least two stops.                                                                     |
| `tenders_accept`         | Write | `tender:update` | Accept an inbound tender, linking each stop to a company. `stopCompanyLinks` must contain at least two entries.                        |
| `tenders_accept_updates` | Write | `tender:update` | Accept all pending updates on a tender. Set `applyAllChangesToLoad` to true to apply them to the linked load as well.                  |
| `tenders_reject`         | Write | `tender:update` | Reject an inbound tender. Provide `reasonCode` and `reasonDescription`; set `cancelLinkedLoad` to true to also cancel the linked load. |
| `tenders_accept_cancel`  | Write | `tender:update` | Accept a tender cancellation.                                                                                                          |

***

## Error handling

Tool calls return a structured error when they cannot complete. Common cases:

| Condition               | What it means                                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`invalid_params`**    | The call carries an unknown parameter key or an out-of-range value (e.g. `page=-1`). The message names the rejected keys and the tool's valid parameter list — read it and retry with a corrected argument shape. |
| **Missing scope**       | Your token does not carry the tool's required permission. Add the scope in **Admin → API Access** and re-issue the token.                                                                                         |
| **Write tool disabled** | The tool is a write/destructive action disabled during beta.                                                                                                                                                      |
| **Rate limited**        | You exceeded the per-token request limit. Back off and retry.                                                                                                                                                     |
| **Response too large**  | The result exceeded the size cap. Narrow your search filters or paginate.                                                                                                                                         |

## Related

<CardGroup>
  <Card title="Model Context Protocol" href="/en/api/guides/mcp" icon="plug">
    Overview and connection setup for the Alvys MCP server.
  </Card>

  <Card title="Authentication" href="/en/api/guides/authentication-1" icon="key">
    Create credentials and issue access tokens with the right scopes.
  </Card>
</CardGroup>


# Base URL
Source: https://docs.alvys.com/en/api/guides/base-url

Production base URL, path format, and version segment used for all Alvys Public API HTTP requests to integrations.alvys.com endpoints.

You can access all our APIs through HTTP requests to URLs:

`https://integrations.alvys.com/api/p/v{version}/<controller>`

For example: `https://integrations.alvys.com/api/p/v1/loads/search`


# Connecting to Power BI
Source: https://docs.alvys.com/en/api/guides/connecting-power-bi-to-alvys-public-api-guide

Connect Power BI to the Alvys Public API using POST search endpoints for advanced filtering, dynamic queries, and reporting on loads, drivers, and more.

Connecting Power BI to Alvys Public API Guide

## **Introduction**

This guide focuses on connecting **Power BI** to the **Alvys Public API** using **POST methods** for advanced data searches. POST requests enable detailed filtering, date ranges, and status-based queries, offering more dynamic interaction than basic GET requests. You'll learn to set up advanced queries in Power BI to retrieve data efficiently from the Alvys Public API.

### **Getting Started**

This guide walks you through connecting Power BI to the Alvys Public API for dynamic data retrieval. It includes preconditions, setup steps, query examples, and a downloadable [Alvys Public API.pbix file](/en/api/guides/importing-the-preconfigured-alvys-public-apipbix-file). While the focus is on establishing the connection, you'll be ready to create reports and visualizations afterward.

By following this guide, you will retrieve an access token from the Alvys API, use it to interact with endpoints like Loads and Drivers, and create advanced Power BI queries for dynamic data retrieval.

<Info>
  What You Will Find in This Guide

  * **Preconditions and Requirements**: What you need to get started.
  * **Detailed Step-by-Step Instructions**: From generating the token to querying data endpoints.
  * **Common Queries and Examples**: Loads, Drivers, Fuel, and more.
</Info>

❓ Why Do We Need These Queries for Connecting Power BI to the Alvys Public API?

Currently, Power BI supports connecting to APIs using the **GET method** through a simple web connection, making it straightforward to retrieve data. However, the **POST method**, essential for handling more advanced queries like the Search endpoints in the Alvys Public API, requires additional setup and customization.

This guide focuses on configuring data retrieval using the **POST method**, enabling users to perform more detailed and powerful searches.

<br />

<Warning>
  Pre-requisites
</Warning>

Before you begin, ensure the following:

1. **Alvys API Credentials**:
   * **Client ID**: A unique identifier for your API client.
   * **Tenant ID**: Represents your account/organization in Alvys.
   * **Client Secret**: A secure key that acts as a password for API authentication.\
     These credentials can be found in the Alvys Platform under **Profile > Management > API**.

<img alt="" />

<br />

2. **Power BI Desktop Installed**: Ensure you have the latest version of **Power BI Desktop**.
   * [Download Power BI](https://powerbi.microsoft.com/desktop/).
3. **Power BI - Settings**:
   * Disable privacy checks to avoid Formula.Firewall errors:
     * Go to **File > Options and Settings > Options > Privacy (Current File)**.
     * Select **Ignore Privacy Levels and potentially improve performance**.

<img alt="" />

<br />

4. An **API Token is Mandatory**: To authenticate every request to the Alvys API, a valid access token is required. In this guide, we will show you how to automatically generate this token and pass it to subsequent queries. Using the credentials provided earlier (your `tenant_id`, `client_id`, and `client_secret`), we will create an `access_token` in our first query, which will then allow us to access other API endpoints.

### **API Queries Available in This Guide**

You will find Power BI query examples for the following API endpoints:

* **Loads Search**: Retrieve a list of loads with filtering options.
* **Drivers Search**: Query driver details by status or fleet.
* **Fuel Search**: Access fuel transaction history.
* **Invoices Search**: Query invoice details by date or status.
* **Maintenance Search**: Access maintenance records.
* **Toll Search**: Retrieve toll transaction details.
* **Trailers Search**: Query trailer status and fleet data.
* **Trips Search**: Retrieve trip data.
* **Trucks Search**: Query truck details by fleet or registration.
* **Customer Search**: Retrieve active customer details.
* **Visibility Search**: Query visibility logs or errors.

<br />

### Retrieving Alvys Public API Data using Advanced Queries

You have two options to get started: you can follow this guide to create your own queries step by step, or you can import the preconfigured `Alvys Public API.pbix` file, which includes default queries. However, if you choose to import the file, you'll need to replace the credentials in the `AccessToken` query with your own API credentials. Both options are described below.


# Create Power BI queries against the Alvys API
Source: https://docs.alvys.com/en/api/guides/create-queries-and-retrieve-data-from-the-alvys-api

Build Power BI M queries that call Alvys search endpoints like loads, drivers, and fuel to pull filtered records with your access token for reporting.

Once you have the AccessToken, you can use it to query various API endpoints.

### **Loads Search API:`/api/p/v{version}/loads/search`**

1. **Create a New Query** for the `Loads Search` Endpoint:
   * Add a new query and give it a descriptive name, such as `Loads Search`, to easily identify its purpose.
   * Open the query in **Advanced Editor** and paste the following code:

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/loads/search",

    // Define the body of the POST request
    requestBody = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 200,
        ""dateRange"": {
            ""startDate"": ""2023-09-09T13:09:30.788Z"",
            ""endDate"": ""2024-09-09T13:09:30.788Z""
        },
        ""status"": [""Open""]
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Define headers with authorization token
    headers = [
        #"Authorization" = "Bearer " & accessToken,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = requestBody
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response)
in
    jsonResponse

```

**Save and close the query.**

**Expected Result**:

* The `Loads Search` query will retrieve data from the Alvys API and display the **Loads table** in Power BI.
* You can explore additional details in the query results:
  * On the **right-hand pane**, click to expand the JSON response to view total results, nested objects, or other relevant details from the API.

<img alt="" />

<br />

> This query allows you to dynamically retrieve customer data filtered by their statuses or created date range. Modify the request body as needed to include additional filters or adjust the search criteria for more specific results.

<br />

### **Drivers Search API:`/api/p/v{version}/drivers/search`**

1. **Create a New Query** for the `Drivers Search` Endpoint:
   * Add a new query in Power BI and name it descriptively, such as `Drivers Search`, to clearly identify its purpose.
   * Open the query in the **Advanced Editor** and paste the following code:

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/drivers/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 50,
        ""status"": [
            ""OFF DUTY""
        ],
        ""name"": """",
        ""employeeId"": """",
        ""fleetName"": """",
        ""isActive"": true
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    drivers = jsonResponse[Items],
    // Convert the list to a table
    driversTable = Table.FromList(drivers, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Expanded Column1" = Table.ExpandRecordColumn(driversTable, "Column1", {"Id", "PhoneNumber", "Name", "Type", "Status", "Notes", "CreatedAt"}, {"Driver.Id", "Driver.PhoneNumber", "Driver.Name", "Driver.Type", "Driver.Status", "Driver.Notes", "Driver.CreatedAt"})
in
    #"Expanded Column1"

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Drivers Search` query will successfully retrieve data from the Alvys API and display the **Drivers table** in Power BI.

> This query allows you to filter drivers dynamically based on their status or other parameters in the request body. Modify the query as needed to adjust filtering criteria, such as fleet name or active status.

<br />

### **Fuel Search API:`/api/p/v{version}/fuel/search`**

**Create a New Query** for the `Fuel Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Fuel Search`, to easily identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/fuel/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""fuelCardNumber"": """",
        ""truckNumber"": """",
        ""transactionRange"": {
            ""start"": ""2022-07-29T15:33:17.224Z"",
            ""end"": ""2025-07-29T15:33:17.224Z""
        }
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    fuelTransactions = jsonResponse[Items],
    // Convert the list to a table
    fuelTransactionsTable = Table.FromList(fuelTransactions, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedFuelTransactions = Table.ExpandRecordColumn(fuelTransactionsTable, "Column1", {"Id", "FuelCardNumber", "TruckNumber", "TransactionDate", "Amount", "Location", "CreatedAt"}, {"Id", "FuelCardNumber", "TruckNumber", "TransactionDate", "Amount", "Location", "CreatedAt"})
in
    expandedFuelTransactions

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Fuel Search` query will successfully retrieve data from the Alvys API and display the **Fuel Transactions table** in Power BI.

> This query allows you to filter and retrieve fuel transaction data dynamically, using parameters like fuel card number, truck number, and transaction date range. Adjust the query body to refine your search criteria as needed.

<br />

### **Invoice Search API:`/api/p/v{version}/invoices/search`**

**Create a New Query** for the `Invoice Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Invoice Search`, to identify its purpose clearly.
* Open the query in the **Advanced Editor** and paste the following code:

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/invoices/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""invoicedDateRange"": {
            ""start"": ""2023-08-02T09:53:34.251Z"",
            ""end"": ""2024-08-02T09:53:34.251Z""
        },
        ""paidDateRange"": {
            ""start"": ""2023-08-02T09:53:34.251Z"",
            ""end"": ""2024-08-02T09:53:34.251Z""
        },
        ""status"": [""Paid""],
        ""customerId"": """"
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    invoices = jsonResponse[Items],
    // Convert the list to a table
    invoicesTable = Table.FromList(invoices, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    #"Expanded Column1" = Table.ExpandRecordColumn(invoicesTable, "Column1", {"Id", "Number", "Type", "Status", "CreatedDate", "InvoicedDate", "DueDate", "PaidDate", "Total", "AmountPaid", "RemainingBalance", "OverPaymentAmount", "IsSubmitted", "LastSendDate", "Vendor", "Customer", "LineItems", "Loads", "Payments"}, {"Id", "Number", "Type", "Status", "CreatedDate", "InvoicedDate", "DueDate", "PaidDate", "Total", "AmountPaid", "RemainingBalance", "OverPaymentAmount", "IsSubmitted", "LastSendDate", "Vendor", "Customer", "LineItems", "Loads", "Payments"})
in
    #"Expanded Column1"

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Invoice Search` query will retrieve data from the Alvys API and display the **Invoices table** in Power BI.

> This query provides dynamic filtering options like date ranges, status, and customer ID to fetch specific invoice data. You can adjust the request body to include additional filters or parameters as needed.

<br />

### **Maintenance Search API:`/api/p/v{version}/maintenance/search`**

**Create a New Query** for the `Maintenance Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Maintenance Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/maintenance/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""dateRange"": {
            ""start"": ""2021-01-23T13:36:42.021Z"",
            ""end"": ""2024-08-23T13:36:42.021Z""
        }
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    maintenanceItems = jsonResponse[Items],
    // Convert the list to a table
    maintenanceTable = Table.FromList(maintenanceItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedMaintenance = Table.ExpandRecordColumn(maintenanceTable, "Column1", {"Id", "Date", "Description", "TruckNumber", "Status", "Cost", "CreatedAt"}, {"Id", "Date", "Description", "TruckNumber", "Status", "Cost", "CreatedAt"})
in
    expandedMaintenance

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Maintenance Search` query will retrieve data from the Alvys API and display the **Maintenance Records table** in Power BI.

> This query allows you to filter and retrieve maintenance records dynamically based on date ranges or other parameters. You can modify the request body to adjust the search criteria or include additional filters as needed.

<br />

### **Toll Search API:`/api/p/v{version}/tolls/search`**

**Create a New Query** for the `Toll Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Toll Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/tolls/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""dateRange"": {
            ""start"": ""2021-07-23T14:48:05.234Z"",
            ""end"": ""2024-07-23T14:48:05.234Z""
        }
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    tollsItems = jsonResponse[Items],
    // Convert the list to a table
    tollsTable = Table.FromList(tollsItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedTolls = Table.ExpandRecordColumn(tollsTable, "Column1", {"Id", "Date", "Amount", "Location", "TruckNumber", "CreatedAt"}, {"Id", "Date", "Amount", "Location", "TruckNumber", "CreatedAt"})
in
    expandedTolls

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Toll Search` query will retrieve data from the Alvys API and display the **Toll Transactions table** in Power BI.

> This query enables you to dynamically retrieve toll transaction data based on date ranges or other parameters. You can adjust the request body to refine your search criteria as needed.

***

### **Trailer Search API:`/api/p/v{version}/trailers/search`**

**Create a New Query** for the `Trailer Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Trailer Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/trailers/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 50,
        ""status"": [""Active""],
        ""trailerNumber"": """",
        ""fleetName"": """",
        ""vinNumber"": """"
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    trailersItems = jsonResponse[Items],
    // Convert the list to a table
    trailersTable = Table.FromList(trailersItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedTrailers = Table.ExpandRecordColumn(trailersTable, "Column1", {"Id", "TrailerNumber", "Status", "FleetName", "VinNumber", "CreatedAt"}, {"Id", "TrailerNumber", "Status", "FleetName", "VinNumber", "CreatedAt"})
in
    expandedTrailers

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Trailer Search` query will retrieve data from the Alvys API and display the **Trailers table** in Power BI.

> This query allows you to dynamically retrieve trailer data based on status, fleet name, or trailer number. Adjust the request body to include additional filters or refine your search criteria as needed.

***

### **Trips Search API:`/api/p/v{version}/trips/search`**

**Create a New Query** for the `Trips Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Trips Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/trips/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""status"": [""Covered""]
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    tripsItems = jsonResponse[Items],
    // Convert the list to a table
    tripsTable = Table.FromList(tripsItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedTrips = Table.ExpandRecordColumn(tripsTable, "Column1", {"Id", "Status", "DriverName", "TruckNumber", "LoadNumber", "StartDate", "EndDate", "CreatedAt"}, {"Id", "Status", "DriverName", "TruckNumber", "LoadNumber", "StartDate", "EndDate", "CreatedAt"})
in
    expandedTrips

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Trips Search` query will retrieve data from the Alvys API and display the **Trips table** in Power BI.

> This query allows you to dynamically retrieve trip data based on parameters like status or pagination. Adjust the request body to include additional filters or refine your search criteria as needed.

***

### **Trucks Search API:`/api/p/v{version}/trucks/search`**

**Create a New Query** for the `Trucks Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Trucks Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/trucks/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""status"": [""Active""],
        ""truckNumber"": """",
        ""fleetName"": """",
        ""vinNumber"": """",
        ""isActive"": true,
        ""registeredName"": """"
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    trucksItems = jsonResponse[Items],
    // Convert the list to a table
    trucksTable = Table.FromList(trucksItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedTrucks = Table.ExpandRecordColumn(trucksTable, "Column1", {"Id", "TruckNumber", "Status", "FleetName", "VinNumber", "IsActive", "RegisteredName", "CreatedAt"}, {"Id", "TruckNumber", "Status", "FleetName", "VinNumber", "IsActive", "RegisteredName", "CreatedAt"})
in
    expandedTrucks

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Trucks Search` query will retrieve data from the Alvys API and display the **Trucks table** in Power BI.

> This query allows you to dynamically retrieve truck data based on parameters like status, fleet name, or VIN. Adjust the request body to include additional filters or refine your search criteria as needed.

***

### **User Search API:`/api/p/v{version}/users/search`**

**Create a New Query** for the `User Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `User Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/users/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""keyword"": """"
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    usersItems = jsonResponse[Items],
    // Convert the list to a table
    usersTable = Table.FromList(usersItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedUsers = Table.ExpandRecordColumn(usersTable, "Column1", {"Id", "Name", "Email", "Role", "Status", "CreatedAt"}, {"Id", "Name", "Email", "Role", "Status", "CreatedAt"})
in
    expandedUsers

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `User Search` query will retrieve data from the Alvys API and display the **Users table** in Power BI.

> This query allows you to dynamically retrieve user data based on filters such as keywords or pagination. You can adjust the request body to include specific search criteria to refine your results further.

***

### **Customer Search API:`/api/p/v{version}/customers/search`**

**Create a New Query** for the `Customer Search` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Customer Search`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/customers/search",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 100,
        ""statuses"": [""Active""],
        ""createdDateRange"": {}
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    customersItems = jsonResponse[Items],
    // Convert the list to a table
    customersTable = Table.FromList(customersItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedCustomers = Table.ExpandRecordColumn(customersTable, "Column1", {"Id", "Name", "Status", "CreatedAt"}, {"Id", "Name", "Status", "CreatedAt"})
in
    expandedCustomers

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Customer Search` query will retrieve data from the Alvys API and display the **Customers table** in Power BI.

> This query allows you to dynamically retrieve customer data filtered by their statuses or created date range. Modify the request body as needed to include additional filters or adjust the search criteria for more specific results.

***

### **Visibility Outbound Errors API:`/api/p/v{version}/visibility/outbound/errors`**

**Create a New Query** for the `Visibility Outbound Errors` Endpoint:

* Add a new query in Power BI and name it descriptively, such as `Visibility Errors`, to clearly identify its purpose.
* Open the query in the **Advanced Editor** and paste the following code:

<br />

```
let
    // Define the API endpoint URL
    url = "https://integrations.alvys.com/api/p/v1/visibility/outbound/errors",

    // Define the body of the POST request
    body = Text.ToBinary("{
        ""page"": 0,
        ""pageSize"": 10,
        ""timeRange"": {
            ""start"": ""2024-11-05T16:58:54.450Z"",
            ""end"": ""2024-11-11T16:58:54.450Z""
        }
    }"),

    // Retrieve the access token from AccessToken query
    accessToken = AccessToken,

    // Construct the Authorization header
    authorizationHeader = "Bearer " & accessToken,

    // Define the headers
    headers = [
        #"Authorization" = authorizationHeader,
        #"Content-Type" = "application/json"
    ],

    // Make the POST request
    response = Web.Contents(url, [
        Headers = headers,
        Content = body
    ]),

    // Parse the JSON response
    jsonResponse = Json.Document(response),
    // Extract the items from the response
    errorsItems = jsonResponse[Items],
    // Convert the list to a table
    errorsTable = Table.FromList(errorsItems, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    // Expand the table to show all relevant fields
    expandedErrors = Table.ExpandRecordColumn(errorsTable, "Column1", {"Id", "ErrorMessage", "Timestamp", "ErrorDetails"}, {"Id", "ErrorMessage", "Timestamp", "ErrorDetails"})
in
    expandedErrors

```

Save the query and close the Advanced Editor.

**Expected Result**

* The `Visibility Outbound Errors` query will retrieve data from the Alvys API and display the **Errors table** in Power BI.
* You can explore the following columns in the result:
  * **Id**: Unique identifier for each error record.
  * **ErrorMessage**: Description of the error.
  * **Timestamp**: The time the error occurred.
  * **ErrorDetails**: Additional details about the error, if available.

> This query allows you to dynamically retrieve outbound error data for visibility operations based on a specified time range. Modify the request body to adjust the date range, page size, or other parameters for tailored results.


# Dates & Timestamps
Source: https://docs.alvys.com/en/api/guides/dates-timestamps

How the Alvys API represents dates, timezone-aware datetimes, and UTC datetimes using the RFC 3339 string format, with serialization examples for each type.

Alvys handles various temporal data types for representing dates and times and uses the [RFC 3339](https://tools.ietf.org/html/rfc3339) format to represent timestamps as strings. These types include:

* **Date Only**: Represents a specific day in the calendar (without time), defined by year, month, and day. Example: `2024-07-04 (July 4, 2024)`.
* **Date Time (Timezone Aware)**: Represents a datetime value that includes a specific timezone offset from Coordinated Universal Time (UTC), based on the user's entered timezone. Example: `2024-07-04T17:24:53-07:00`\
  (`July 4, 2024, at 5:24:53 PM`, 7 hours behind UTC).
* **Date Time (UTC)**: Refers to a datetime value that is standardized to Coordinated Universal Time (UTC), without any local time zone information or offset. This ensures that the datetime is consistently represented regardless of the local time zone. Example: `2024-07-04T17:24:53Z` (`July 4, 2024, at 5:24:53 PM` in UTC)

## Serialization Formats

* **Date Only**: Serialized as `yyyy-MM-dd`. Example: `2024-07-04`.
* **Date Time (timezone aware)**: Serialized as `yyyy-MM-ddTHH:mm:ss±HH:mm` including the offset from UTC. Example: `2024-07-04T17:24:53-07:00`.
* **Date Time (UTC)**: Serialized as `yyyy-MM-ddTHH:mm:ssZ` in UTC. Example: `2024-07-04T17:24:53Z`.

## RFC 3339

The current version of Alvys APIs uses the [RFC 3339](https://tools.ietf.org/html/rfc3339) format for timestamps. RFC 3339 is a widely adopted standard for representing date and time as strings.

Here is a basic example:

```
2024-07-04T17:24:53Z
```

The above timestamp refers to `July 4, 2024 5:24:53 PM` in Coordinated Universal Time (UTC).

## Unix Timestamps

Unix timestamps represent the number of seconds that have elapsed since the Unix epoch, which is 00:00:00 UTC on 1 January 1970. Unix timestamps are useful for ensuring consistent time representation across different systems and platforms, as they are unaffected by time zones or daylight saving time.

Examples:

* **Date Only to Unix Timestamp:** Date: `2024-07-04`, Unix Timestamp: `1720147200`
* **Date Time (Timezone Aware) to Unix Timestamp:** Date Time: `2024-07-04T17:24:53-07:00`, Unix Timestamp: `1720172693`
* **Date Time (UTC) to Unix Timestamp:** Date Time: `2024-07-04T17:24:53Z`, Unix Timestamp: `1720172693`


# EDI integrations
Source: https://docs.alvys.com/en/api/guides/edi-integrations

Connect external EDI providers and build bi-directional TMS integrations by mapping EDI 204, 214, 210, and 990 transactions to Alvys tender REST APIs and webhook events.

This guide shows EDI providers, middleware vendors, and advanced customers how to build bi-directional integrations between an external EDI connection and the Alvys TMS. It explains how to translate classic EDI transactions (204, 990, 214, 210) into Alvys REST calls and webhook-driven lifecycle events, and outlines the integration patterns required to build reliable, production-grade EDI integrations with Alvys.

Alvys provides a set of public REST APIs and event-driven webhooks designed to help external EDI providers, middleware platforms, and customers build custom EDI integrations into the Alvys TMS. These interfaces enable you to programmatically:

* Create and manage inbound tenders (EDI 204) via REST
* Receive near real-time shipment lifecycle updates (EDI 214) via webhooks
* Fetch invoice details after submission (EDI 210) via REST + invoice events

These APIs are intended to let partners translate between classic EDI transactions (204/214/210/990/997) and Alvys-native objects and workflows (tenders, tender updates, cancellations, acceptance workflows, status events, and invoices).

<Note>
  **Getting API access**

  * Existing Alvys customers can obtain API access by contacting their account representative.
  * Independent Software Vendors (ISVs) should contact the Alvys Partnership team.
</Note>

## API workflow guide (EDI → Alvys mapping)

This section maps common EDI workflows to the corresponding Alvys Public API endpoints. It is intended for EDI providers and middleware vendors who translate inbound and outbound EDI transactions into Alvys-native tender and shipment operations.

Use this guide as a decision table when implementing integrations:

* Identify the EDI transaction or business intent (e.g., new tender, update, cancel, accept).
* Call the appropriate REST endpoint to express that intent to Alvys.
* Rely on Alvys webhooks to confirm the authoritative outcome of the operation.
* Emit outbound EDI (990/214/210/997) only after the corresponding Alvys state change is confirmed.

### Design principles

* **REST expresses intent; webhooks confirm outcome.**
  A successful REST response indicates the request was received, not that the workflow is complete.
* **Expect retries and duplicates.**
  EDI networks frequently resend transactions. Always use Idempotency-Key for unsafe POSTs and deduplicate webhook deliveries by EventId.
* **Model state explicitly.**
  Tenders may be pending, accepted, rejected, cancelled, expired, or awaiting update approval. Do not assume immediate state transitions.
* **Treat Alvys as the system of record.**
  When conflicts arise, reconcile by fetching the tender (GET /tenders/:tenderId) and honoring the returned state and ETag.

The table below outlines the canonical mapping between EDI workflows and Alvys Public API operations, along with important integration considerations for each step.

| EDI workflow (common)                                 | Typical direction              | When to call (trigger)                                                                             | Alvys Public API endpoint(s)                               | Primary purpose in Alvys                                | Integration notes (idempotency / concurrency)                                                                                                                                                           |
| ----------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **204\_00 — New Load Tender**                         | Shipper → Carrier (via vendor) | You receive a new 204 and want it represented as an inbound tender in Alvys                        | `POST /api/p/v{version}/tenders`                           | Create an inbound tender record                         | Use `Idempotency-Key` to prevent duplicate creates (EDI resends are common). Validate required fields before calling.                                                                                   |
| **204\_04 — Tender Change / Update**                  | Shipper → Carrier              | You receive a 204 update (appointments, stops, rate, equipment, references) for an existing tender | `POST /api/p/v{version}/tenders/update`                    | Submit a change-set against an existing tender          | Treat updates as “pending” until applied/accepted (implementation-dependent). Use `Idempotency-Key` for safe retry. If the route requires concurrency, include `If-Match` with the current `ETag`.      |
| **204\_01 — Cancel Tender**                           | Shipper → Carrier              | You receive a cancellation for an existing tender                                                  | `POST /api/p/v{version}/tenders/cancel`                    | Request cancellation of a tender                        | Use `Idempotency-Key` to avoid duplicate cancel requests. If cancellation must be concurrency-protected, include `If-Match` with the current `ETag`.                                                    |
| **990 — Accept Tender (carrier acceptance)**          | Carrier → Shipper              | Carrier acceptance occurs in Alvys and you need to reflect/confirm acceptance in your integration  | `POST /api/p/v{version}/tenders/{tenderId}/accept`         | Mark tender accepted (optionally attach/link to a load) | **Requires** current `ETag` + `If-Match` (optimistic concurrency) if enabled. A vendor should only “drive” acceptance via API if the workflow is designed for it (vs. acceptance happening only in UI). |
| **990 — Reject Tender**                               | Carrier → Shipper              | Carrier rejects tender and you must record that disposition                                        | `POST /api/p/v{version}/tenders/{tenderId}/reject`         | Mark tender rejected with a reason                      | Typically **requires** `ETag` + `If-Match`. Ensure your rejection reason mapping matches the shipper’s implementation guide expectations.                                                               |
| **204\_04 acceptance — Apply/Accept Pending Updates** | Carrier → Shipper              | A tender has pending updates that must be applied/accepted                                         | `POST /api/p/v{version}/tenders/{tenderId}/accept-updates` | Apply pending change-set(s) to the tender               | Typically **requires** `ETag` + `If-Match`. If updates are partial/selected, ensure you pass the intended change identifiers (if supported).                                                            |
| **204\_01 confirmation — Accept/Confirm Cancel**      | Carrier → Shipper              | Cancellation is requested and must be confirmed/accepted in workflow                               | `POST /api/p/v{version}/tenders/{tenderId}/accept-cancel`  | Confirm tender cancellation (workflow-dependent)        | Typically **requires** `ETag` + `If-Match`. Only applicable if cancellation is a two-step workflow (request → confirm).                                                                                 |
| **Lookup — Get Tender by ID**                         | Vendor internal utility        | You need full canonical tender state (or to reconcile after retries/conflicts)                     | `GET /api/p/v{version}/tenders/{tenderId}`                 | Retrieve the tender (optionally with includes)          | Capture `ETag` for subsequent state changes (`If-Match`). Use `If-None-Match` for cache-friendly polling/reconciliation if supported.                                                                   |
| **Lookup — Search Tenders**                           | Vendor internal utility        | You need to find tenders by external reference, status, or time window                             | `POST /api/p/v{version}/tenders/search`                    | Search tenders using rich filters                       | Prefer searching by your **external tender identifier** to correlate EDI → Alvys. Useful for replay/recovery jobs and operational dashboards.                                                           |

### Troubleshooting

* Double-check your `client_id`, `client_secret`, and `audience`
* Ensure scopes are correctly assigned in **API Access** in the Admin Portal
* Validate that the client is active and not expired
* Use only supported content types: `application/json` or `application/x-www-form-urlencoded`
* For technical support: [support@alvys.com](mailto:support@alvys.com)

## Related resources

* [Tender API reference](/en/api/reference/tenders/get-tender) — the REST endpoints referenced in the mapping table above
* [Webhooks overview](/en/api/reference/webhooks/overview) — subscribe to the lifecycle events that confirm each state change


# Getting Started with Alvys
Source: https://docs.alvys.com/en/api/guides/getting-started

Get started with the Alvys Public API: create client credentials, request an OAuth access token, and make your first authenticated API call.

This page will help you get started with Alvys. You'll be up and running in a jiffy!

<Note>
  **As of June 2025, Alvys** has updated how we issue access tokens, bringing **improved security** and a **more fine-grained permission model**. The core OAuth 2.0 flow remains the same, but the token request endpoint has changed. The legacy `/authentication/{tenant_id}/token`-based method will be deprecated soon.
</Note>

<br />

### Create Client Application

To begin, create a new application from the Alvys Admin page. This will allow you to generate a `client_id` and `client_secret`.

* `client_id`: The unique identifier assigned to this application or caller.
* `client_secret`: A confidential token also provided by Alvys upon application registration.

***

### Getting an Access Token

Once you’ve created your credentials, you’ll use them to retrieve a bearer token. This token is then passed in the `Authorization` header of every API request.

#### Prerequisites

Before requesting an access token, ensure you have the following:

* **Client ID** and **Client Secret** (from the Admin Portal)
* The **API Audience**: `https://api.alvys.com/public/`
* The correct **`grant_type`**: `client_credentials`

### Token URL (Current)

```text theme={null}
https://auth.alvys.com/oauth/token
```

### Request Body

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}
```

For detailed information, please visit our [Authentication](/en/api/guides/authentication-1) page.


# Import the preconfigured Alvys Public API.pbix file
Source: https://docs.alvys.com/en/api/guides/importing-the-preconfigured-alvys-public-apipbix-file

Download and import the Alvys Public API.pbix file into Power BI Desktop, then update the tenant, client ID, and client secret parameters to connect.

If you prefer to use a preconfigured file, you can import the `Alvys Public API.pbix` file, which contains all the queries described in this guide, including the `AccessToken` query. This file simplifies the setup process by providing ready-to-use queries for interacting with the Alvys Public API.

> ⬇️ Download: [Alvys Public API.pbix](https://drive.usercontent.google.com/u/0/uc?id=1ZdsauFy8KY9nHg1vykq5fNv4vE1Yl1Pq\&export=download)

<br />

### **Steps to Use the Preconfigured File**

1. **Download and Open the File**:
   * Obtain the `Alvys Public API.pbix` file from the source above.
   * Open it in Power BI Desktop.
2. **Update the `AccessToken` Query**:
   * Click on **Transform Data** from the top menu.
   * In the Transform Data view, go to the Parameters (Manage Parameters option or click on these rows from query list) and update the following with your credentials: `tenant_id`, `client_id`, `client_secret`.

     <img alt="" />
   * Go to File > Apply Changes.
3. **Save and Refresh**:
   * After updating the credentials, save the changes and refresh the queries.

     <img alt="" />
   * The file will now fetch data dynamically using your credentials.
4. Whenever you wish to refresh the token, simply select the "Access token" query and click the refresh preview button.
5. To load and see data in the tables:
   * In the Queries list, right-click on each relevant query (e.g., Loads Search, Invoices Search, etc.)
   * Click on "Enable Load" to Report *(or Properties Select Enable Load to Report)*.

     <img alt="" />
6. To apply the changes, click on "Apply" or "Close & Apply" from the top-left of the Power Query window, or go to File > "Apply Changes".


# Alvys MCP server for AI agents
Source: https://docs.alvys.com/en/api/guides/mcp

Connect AI agents directly to Alvys through the Model Context Protocol (MCP) server — a governed, authenticated gateway to the Alvys Public API.

Integrate Alvys capabilities using the **Model Context Protocol (MCP)** server.

The MCP server provides a set of tools that AI agents can use to interact with the Alvys APIs. You can use the MCP tools as a **developer** wiring an assistant into your workflow, as a **business owner** looking for financial insights or operational data, or as a **platform** connecting your own agents to perform tasks across dispatch, tracking, and settlement.

Unlike raw API integration, the MCP server gives your AI client a single, discoverable, and permissioned surface. Every tool call is authenticated with your Alvys credentials, scoped to your tenant, and audited — so agents get exactly the access you grant them, and nothing more.

<Warning>
  **Internal Beta**

  The Alvys MCP server is currently in **beta**. Access is granted on request — contact your account representative (existing customers) or the Alvys Partnership team (ISVs). During beta, the server exposes **read-only** tools.
</Warning>

## What is MCP?

Model Context Protocol is an open standard that gives AI assistants a live connection to external tools and data. Think of it like a USB port for AI — instead of pasting data into a chat window, your AI client connects directly to Alvys and can search, read, and (where permitted) act on your operational data in real time.

The Alvys MCP server sits in front of the [Alvys Public API](/en/api/guides/getting-started). It adds the safety properties an AI tool surface requires:

* **Authentication** — every request carries an Auth0 bearer token; unauthenticated calls are rejected.
* **Tenant isolation** — your company is resolved from the token itself, never from agent input.
* **Per-tool permissions** — each tool requires a specific scope (for example `load:read`), enforced on every call.
* **Read / Write / Destructive classification** — write and destructive tools are gated and off by default.
* **Auditing & rate limits** — every tool call is logged and throttled.

## Who it's for

| You are…                   | Use MCP to…                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| A **developer**            | Give Claude, Cursor, or a custom agent live access to loads, trips, drivers, and carriers without hand-writing API calls.                |
| A **business owner / ops** | Ask an AI assistant natural-language questions about your operation — open loads, invoice status, driver availability, tracking history. |
| A **platform / ISV**       | Connect your agents to Alvys to automate dispatch, carrier onboarding, tracking, and settlement workflows.                               |

***

## Connecting to Alvys's MCP Server

The Alvys MCP server is a **remote MCP server** that speaks the MCP Streamable HTTP transport. You connect by pointing your MCP client at the server URL and authenticating with Auth0.

### Server URLs

| Environment    | MCP Server URL              |
| -------------- | --------------------------- |
| **Production** | `https://mcp.alvys.com/mcp` |

### Protocol version support

**You do not need to pick a protocol version, and there is nothing to configure.** MCP clients and servers negotiate the revision automatically on connect, so your client uses the newest revision both sides understand.

The Alvys MCP server implements MCP revision **`2026-07-28`** and still accepts these earlier revisions:

| MCP revision | Supported | Notes                                                                                  |
| ------------ | --------- | -------------------------------------------------------------------------------------- |
| `2026-07-28` | ✅         | Current. Sessionless — the revision travels on each request.                           |
| `2025-11-25` | ✅         | Negotiated via the `initialize` handshake.                                             |
| `2025-06-18` | ✅         | Negotiated via the `initialize` handshake.                                             |
| `2025-03-26` | ✅         | Negotiated via the `initialize` handshake.                                             |
| `2024-11-05` | ✅         | Negotiated via the `initialize` handshake. Deprecated by MCP, but still accepted here. |

<Note>
  **If your client works today, it keeps working.** Upgrading the server to `2026-07-28` did not drop support for any revision. You do not need to update your client, change your configuration, or migrate to a different URL.
</Note>

Practical implications:

* **Older clients** — no action. Your client negotiates an earlier revision and behaves exactly as before.
* **Newer clients** — no action. Your client negotiates `2026-07-28` and gets the newer protocol features automatically.
* **The tools, scopes, and URL are identical across revisions.** The negotiated revision changes protocol mechanics, not what your agent can do.

If a client fails to connect, the protocol revision is very unlikely to be the cause — check authentication and organization selection first (see the two options below), then contact [support@alvys.com](mailto:support@alvys.com).

There are two ways to authenticate, depending on your client.

### Option 1 — Interactive login (recommended for AI apps)

Best for human-facing clients that support remote MCP servers with OAuth — **Claude**, **Claude Code**, **ChatGPT**, **Cursor**, and **Codex**.

You add the server URL once and your client discovers the login flow automatically via the server's OAuth metadata (`/.well-known/oauth-protected-resource/mcp`). No client secret is stored in your MCP client — the interactive flow uses OAuth 2.1 with PKCE.

#### Set up your AI tool

Pick your client below. Every path ends the same way: a browser window opens to the Alvys login where you sign in and, if prompted, select your **organization**. Your client exchanges that session for a token scoped to your company and permissions, and can then list and call any tool your account is permitted to use.

<Tabs>
  <Tab title="Claude">
    1. Go to [Connectors settings](https://claude.ai/settings/connectors).
    2. Select **Add custom connector**.
    3. Enter the connector details:
       * **Name** — `Alvys`
       * **URL** — `https://mcp.alvys.com/mcp`
    4. Select **Add**, then complete the Alvys login when prompted.
    5. In a chat, open the attachments menu (**+**) and enable the Alvys connector.
  </Tab>

  <Tab title="Claude Code">
    1. Add the server:

       ```bash theme={null}
       claude mcp add --transport http alvys https://mcp.alvys.com/mcp
       ```

    2. Run `/mcp` in Claude Code and select **alvys** to start the login. A browser window opens to the Alvys login on first use.
  </Tab>

  <Tab title="ChatGPT">
    Custom MCP servers are configured in the ChatGPT desktop app.

    1. Open **Settings → MCP servers → Add server**.
    2. Fill in the server details:
       * **Name** — `Alvys`
       * **Type** — **Streamable HTTP**
       * **URL** — `https://mcp.alvys.com/mcp`
    3. Select **Save**, then **Restart**.
    4. Select **Authenticate** and complete the Alvys login.

    <Note>
      The ChatGPT desktop app, Codex CLI, and the Codex IDE extension share one config file (`~/.codex/config.toml`), so this setup carries across all three.
    </Note>
  </Tab>

  <Tab title="Cursor">
    1. Open the command palette with <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows).

    2. Search for **Open MCP settings** and select **Add custom MCP**.

    3. In `mcp.json`, add the Alvys server:

       ```json theme={null}
       {
         "mcpServers": {
           "alvys": {
             "url": "https://mcp.alvys.com/mcp"
           }
         }
       }
       ```

    4. Reload Cursor and complete the Alvys login when prompted.
  </Tab>

  <Tab title="Codex">
    1. Add the Alvys server to `~/.codex/config.toml`:

       ```toml theme={null}
       [mcp_servers.alvys]
       url = "https://mcp.alvys.com/mcp"
       auth = "oauth"
       ```

    2. Start the login flow:

       ```bash theme={null}
       codex mcp login alvys
       ```

    A browser window opens to the Alvys login. Codex stores the resulting credentials and reuses them on later runs.
  </Tab>
</Tabs>

### Option 2 — Machine-to-machine (headless automation)

Best for **server-to-server agents** and back-end automation with no human in the loop. This flow reuses the same OAuth 2.0 **client-credentials** mechanism as the Alvys Public API.

1. Create (or reuse) an Alvys API application in **Admin → API Access** to get a `client_id` and `client_secret`. Select the scopes matching the tools you intend to call. See [Authentication](/en/api/guides/authentication-1) for the full walkthrough.

2. Request an access token:

   ```bash theme={null}
   curl --request POST \
        --url 'https://auth.alvys.com/oauth/token' \
        --header 'Content-Type: application/json' \
        --data '{
          "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET",
          "audience": "https://api.alvys.com/public/",
          "grant_type": "client_credentials"
        }'
   ```

3. Point your MCP client at the server URL and pass the token in the `Authorization` header:

   ```
   Authorization: Bearer YOUR_ACCESS_TOKEN
   ```

The token's `scope` claim determines which tools you can call, and its organization claim scopes every call to your company's data.

<Info>
  Your `client_id` and `client_secret` are sensitive. Store them securely and never expose them in front-end code. Tokens are scoped to exactly the permissions granted to your application.
</Info>

### Verifying the connection

Once connected, ask your MCP client to **list available tools**, or issue an MCP `tools/list` call. You should see the Alvys tools grouped by domain (loads, trips, drivers, carriers, and more). For the full catalog, see [Available MCP Tools](/en/api/guides/available-mcp-tools).

A raw transport check (returns the server's tool list over Streamable HTTP):

```bash theme={null}
curl -sD - -X POST https://mcp.alvys.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

***

## Permissions & safety

The MCP server enforces the **same scope model** as the Public API. Each tool declares a required permission using the `{resource}:{action}` convention — for example `load:read`, `carrier:update`, or `tender:create`. A tool call fails if your token lacks the scope.

Tools are classified into three tiers:

| Tier            | Examples                                                            | Availability         |
| --------------- | ------------------------------------------------------------------- | -------------------- |
| **Read**        | `loads_search`, `drivers_get_by_id`, `visibility_inbound_history`   | Always available     |
| **Write**       | `tenders_create`, `trips_assign`, `invoices_record_carrier_payment` | Disabled during beta |
| **Destructive** | cancel / void actions                                               | Disabled by default  |

Additional guardrails applied to every call:

* **Tenant isolation** — your company is derived from your token's organization claim; agents cannot target another tenant.
* **Rate limiting** — per-token request throttling protects your account and the platform.
* **Response size caps** — oversized responses are rejected to keep results within an AI client's context window.
* **Audit logging** — every tool call is recorded with the caller, tenant, and trace id.

## Guided prompts

Beyond individual tools, the server ships **guided prompts** — multi-step workflows an agent can follow end to end:

| Prompt                         | What it does                                                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_and_cover_load_v1`       | Find an open load and cover it with a carrier via a tender.                                                                                             |
| `dispatch_driver_v1`           | Check driver availability (including an 8-day ELD lookback for the federal 70-hour/8-day HOS window) and assign a driver, truck, and trailer to a trip. |
| `carrier_onboarding_v1`        | Look up a carrier by MC/DOT, review documents, upload the packet, and activate.                                                                         |
| `settlement_reconciliation_v1` | Reconcile a load's invoices, deductions, and carrier/customer payments.                                                                                 |
| `track_shipment_v1`            | Pull inbound and outbound tracking history for a shipment.                                                                                              |

## Next steps

<CardGroup>
  <Card title="Available MCP Tools" href="/en/api/guides/available-mcp-tools" icon="plug">
    Browse the full catalog of tools, grouped by domain, with the scope each one requires.
  </Card>

  <Card title="Authentication" href="/en/api/guides/authentication-1" icon="key">
    Full walkthrough of creating credentials and issuing access tokens.
  </Card>

  <Card title="Getting Started" href="/en/api/guides/getting-started" icon="rocket">
    New to the Alvys API? Start here.
  </Card>
</CardGroup>

<Note>
  **Need access or help?**

  * Existing Alvys customers: contact your account representative.
  * ISVs / partners: contact the Alvys Partnership team.
  * Technical support: [support@alvys.com](mailto:support@alvys.com)
</Note>


# Need more support?
Source: https://docs.alvys.com/en/api/guides/need-more-support

Reach the Alvys Support team from the in-app Intercom widget, review past conversations, check system status, and see support hours and response times.

### Getting Help in Alvys

Alvys uses Intercom to support customers directly inside the platform. You can reach our Support team anytime by clicking the Intercom widget in the bottom-right corner of any Alvys screen—no need to leave the app or open your email.

* From the Intercom widget, you can:
* Send a message to the Alvys Support team
* View past conversations
* See what’s new in the product
* Preview upcoming features on our roadmap
* Check the current system status

We may also share important product updates or announcements there from time to time.

If our team replies while you’re offline, we’ll email a copy of the conversation to the email address associated with your Alvys account. You can reply directly from email or continue the conversation in Intercom—whatever works best for you.

### Response Times

We do our best to respond as quickly as possible. During busier periods, response times may be slightly longer, but every message is reviewed by our team.

For the fastest response, we recommend contacting us while logged into Alvys using the Intercom widget.

**Support hours:**
Monday–Friday, 10:00 AM–6:00 PM Pacific Time

For additional details, please refer to our [Terms of Service](https://alvys.com/terms).


# Alvys developer documentation overview
Source: https://docs.alvys.com/en/api/guides/overview

Start here to explore Alvys Public API guides, authentication, versioning, rate limits, webhooks, and integration references for developers.

<CardGroup>
  <Card title="Getting Started" icon="house">
    Check out the Guides section for:

    * [Getting Started with Alvys](/en/api/guides/getting-started)
    * [Authentication](/en/api/guides/authentication-1)
    * [Versioning](/en/api/guides/versioning)
  </Card>

  <Card title="Stay Informed" icon="circle-question">
    Keep up with changes and announcements regarding API features, guides, and tools.

    * [Changelog](/en/api/changelog)
    * [Contact Us](https://alvys.com/resources/contact)
  </Card>
</CardGroup>


# Power BI Template File: Fast Setup Guide
Source: https://docs.alvys.com/en/api/guides/power-bi-template-file-fast-setup-guide

Fast-setup guide for the Alvys Public API.pbix template — load prebuilt queries, sample reports, and parameters into Power BI Desktop in minutes.

If you prefer to use a preconfigured file, you can import the `Alvys Public API.pbix` file, which contains all the latest queries, parameters, and sample reports to get you started quickly.

> ⬇️ Download: [Alvys Public API.pbix](https://drive.usercontent.google.com/u/0/uc?id=1ZdsauFy8KY9nHg1vykq5fNv4vE1Yl1Pq\&export=download)

***

#### **Steps to Get Started**

1. **Download and Open the File:**

   * Download the `Alvys Public API.pbix` file from the link above.
   * Open it in Power BI Desktop.

2. **Update Connection Parameters:**

   * Click on **Transform Data** from the top menu.
   * In the Transform Data view, go to **Manage Parameters** or select the parameter rows in the query list.

     <img alt="" />
   * Update your `tenant_id`, `client_id`, and `client_secret` with your organization’s credentials (required for new Authentication flow).\
     *Note: Only newly generated credentials—with proper API scopes—are allowed in the new authentication flow. Legacy credentials will not work.*
   * *(The legacy authentication method will no longer be supported soon.)*

3. **Authenticate and Refresh:**

   * Select the `AccessToken` query and ensure a token is returned.

   * If prompted, click **Edit Credentials**, choose **Anonymous**, and click **Connect** with new endpoint `https://auth.alvys.com/oauth/token.`

   > ⚠️ Troubleshooting Authentication
   >
   > * Click on the AccessToken query.
   > * It should retrieve the authentication token automatically.
   > * If you see an "unauthorized" error or are prompted for credentials:
   >   * Click Edit Credentials
   >     * In the window that opens, select Anonymous authentication.
   >     * Confirm and click Connect.
   >     * After connecting, try refreshing the query again.

   * In Power Query, use **Refresh Preview** > **Refresh All** to refresh all queries with the new token and updated credentials.

     <img alt="" />

   <br />

   > 🚧 Troubleshooting:
   >
   > If you see a “Formula.Firewall” or privacy error, go to File > Options and settings > Options > Privacy, and set to “Ignore the Privacy Levels.” This allows Power BI to combine data from multiple queries.

4. **Enable and View Data:**

   * In the Queries list, right-click any query you want to include in the report (e.g., Loads, Users, etc.).
   * For Loads and Trips, you will see multiple queries (e.g., 1 Loads - Search ALL, 2 Loads - Get Recent Updates, 3 Loads).
     * Important: Only the “final” combined query (usually 3 Loads or 3 Trips) should be enabled for load to the report. The “1” and “2” queries are used for data processing and should remain disabled after initial data validation.
     * Tip: If this is your first time setting up, you can temporarily enable the “1” and “2” queries to check the data. Once everything is working, disable them to keep your model clean and fast.
     * Right-click and select **Enable Load** to Report (or go to Properties and check "**Enable Load to Report**") for the queries you want visible in the report.
   * <img alt="" />

5. **Apply Changes:**

   * Click **Close & Apply** in Power Query or go to **File > Apply Changes**.

6. **Explore Your Data and Reports**

   * In the Data view (left sidebar), you’ll see all your loaded tables along with a “DAX Report” table containing basic DAX formulas—these are included to help you quickly analyze or summarize your data.

     <img alt="" />
   * In the Report view (top icon on the left), you’ll find a sample weekly summary visualization and other quick-start report pages—these give you an instant overview and examples for analyzing your customer data.
   * To view your data, click any table in Data view to see all fields and records—then sort or filter columns directly to explore, check for errors, or find specific information; tip: sorting and filtering make it easy to spot updates or issues.
   * In the Model view (bottom icon on the left), you can review or adjust relationships between tables.\
     Tip: For accurate analysis, make sure to set a relationship between Loads (1) and Trips () using the LoadNumber field.

     <img alt="" />
   * To update your data, go to Data view and click the three dots (...) next to a table to select Refresh data, or use Refresh all tables from the main menu to update everything; tip: refresh regularly to ensure you see the latest API data and parameter changes.

     <img alt="" />

   <br />

   <br />

***

*For more details or troubleshooting, see the instructions inside the file or contact your support team.*


# Public roadmap
Source: https://docs.alvys.com/en/api/guides/public-roadmap

Track Alvys initiatives currently in development, view features moving toward release, and follow the live public roadmap embedded from Notion.

At Alvys, we believe in building with transparency. Our public roadmap highlights the initiatives we've committed to and are actively working on today. This is not a full view of every idea or future possibility — it's a focused snapshot of the projects that are currently in motion and will soon make their way into the platform. We'll keep this page updated so you can follow along with the progress of key features and improvements as they move from development to release.

<Card title="View the Alvys public roadmap" icon="map" href="https://alvys.notion.site/Public-Roadmap-21ba5b0d388a8062abc8e7895c6abb57">
  Opens the live roadmap in Notion.
</Card>

<iframe />


# Rate Limits
Source: https://docs.alvys.com/en/api/guides/rate-limits

Global per-token and per-organization request limits for the Alvys Public API, endpoint-specific caps, and how to handle HTTP 429 too-many-requests errors.

Alvys APIs employ rate limits to ensure fair usage and protect our infrastructure from excessive requests, preventing potential abuse and maintaining consistent performance. This document outlines the global and endpoint-specific rate limits applied to API usage. If you exceed any of the rate limits described below, Alvys will respond with a 429 error code.

<Info>
  Ad-Hoc Rate Limit Changes

  **Note:** Alvys reserves the right to adjust rate limits as necessary to protect our system. Although changes are infrequent, we aim to provide prior notice whenever possible.
</Info>

## Global Rate Limits

These limits apply to all API endpoints, with some endpoints having more restrictive limits. Refer to the "Endpoint-Level Rate Limits" section for specific details.

* **Per token**: Each API access token may make up to 10 API requests per second
* **Per organization**: Each organization may make up to 50 API requests per second

In other words, a single API token can only make 10 requests per second. An organization may have multiple API tokens, but collectively, an organization can only make 50 requests per second.

## Endpoint-Level Rate Limits

Some endpoints have specific rate limits to manage traffic and ensure fair usage. These limits override the global rate limits where specified. For endpoints without specific rules, default rate limits apply as outlined below. The table provides details on rate limits, periods, responses, and actions taken when limits are exceeded.

#### Key Definitions

* **Rate Limit:** The maximum number of requests allowed within the specified period.
* **Period:** The duration in which the rate limit applies. For example, "1 minute" means the limit resets every minute.
* **Response:** The HTTP status code returned when the rate limit is exceeded.
* **Action:** The action taken when the rate limit is exceeded, typically resulting in blocking further requests until the period resets.

| **Endpoint**                                   | **Threshold**              | **Period**    | **Response**              | **Action** |
| ---------------------------------------------- | -------------------------- | ------------- | ------------------------- | ---------- |
| **Default (All other endpoints)**              | **10 requests per minute** | **3 minutes** | **429 Too Many Requests** | **Block**  |
| GET /api/p/v\{version}/drivers/\{id}           | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/drivers                 | 5 requests per minute      | 1 minute      | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/drivers/search         | 10 requests per minute     | 1 minute      | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/drivers/events/search  | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/fuel/\{id}              | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/fuel/search            | 5 requests per minute      | 1 minute      | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/invoices                | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/invoices/search        | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/loads                   | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/loads/search           | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/maintenance/\{id}       | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/maintenance/search     | 10 requests per minute     | 1 minute      | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/tolls/\{id}             | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/tolls/search           | 10 requests per minute     | 1 minute      | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/trailers/\{id}          | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/trailers                | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/trailers/search        | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/trailers/events/search | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/trips                   | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/trips/search           | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/trucks/\{id}            | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/trucks                  | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/trucks/search          | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/trucks/events/search   | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |
| GET /api/p/v\{version}/users/list              | 5 requests per minute      | 3 minutes     | 429 Too Many Requests     | Block      |
| POST /api/p/v\{version}/users/search           | 10 requests per minute     | 3 minutes     | 429 Too Many Requests     | Block      |

#### Default Rate Limiting Rules

For all endpoints without specific rate limits defined, the following default rate limiting rules apply:

* **Rule Name:** Default Rate Limiting
* **URL Path:** `/api/*`
* **Threshold:** 10 requests per minute
* **Burst:** 1 request in the first second
* **Action:** Block
* **Period:** 3 minutes
* **Response:** 429 Too Many Requests
* **Custom Response:** Include `Retry-After: 60` header

## Handling Rate Limits

When an application exceeds the specified rate limit, the API will respond with a **429 Too Many Requests** status code. The response includes a `Retry-After` header, indicating the time in seconds before the client can retry the request. Respecting this header is essential to avoid further rate limiting and ensure continued access to the API.

#### Example Response Header

| Header      | Description                                                                |
| :---------- | :------------------------------------------------------------------------- |
| Retry-After | Suggested wait time (in seconds) before retrying (e.g., `Retry-After: 60`) |

You should respect the Retry-After header to properly delay further requests and avoid triggering additional rate limits. Adhering to these rate limits helps maintain the stability and reliability of Alvys API services. For further inquiries or support, please contact our technical support team.


# Response Codes
Source: https://docs.alvys.com/en/api/guides/response-codes

HTTP status codes returned by the Alvys Public API — 2XX success, 4XX client errors, and 5XX server errors — with descriptions of each error code.

All API requests will respond with an appropriate HTTP status code. Your API client should handle each response class differently:

* **2XX** Successful responses
* **4XX** Client error responses indicate an issue with the request, such as missing parameters or invalid value. Modify the request before retrying.
* **5XX** Server error responses indicate a temporary issue on Alvys' side. Retry the request after some time. *If issues persist, please reach out to support for further assistance.*

## Error Codes

Alvys uses conventional HTTP response codes to indicate the success or failure of an API request. Below is a table of error codes to help you debug. The error response body may include an error message, but avoid hard-coding against specific messages, as Alvys reserves the right to change the error message without auto-incrementing the API version. Only use error messages for debugging purposes.

| Status Code | Description                                                                                                                                                                                                                                                                                                                       |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | **Bad Request** - General client error, possibly malformed data. Common error messages include: "Configuration limit exceeded" (e.g., system limits on creating more objects like users, drivers, and documents). Contact Support to request increases.                                                                           |
| 401         | **Unauthenticated** - The access token is missing or invalid. A mistyped or unknown path does **not** produce 401.                                                                                                                                                                                                                |
| 403         | **Permission Denied** - You do not have access to the requested resource.                                                                                                                                                                                                                                                         |
| 404         | **Not Found** - The request path does not match a published endpoint, or a path parameter does not match a resource (for example, `id` in `/drivers/\{id}`). A well-formed list or search that matches no records is **not** a 404 — see [No results is not an error](#no-results-is-not-an-error).                               |
| 405         | **Method Not Allowed** - The API endpoint does not accept that HTTP method.                                                                                                                                                                                                                                                       |
| 415         | **Unsupported Media Type** - The request's `Content-Type` is not supported by this endpoint. Only `application/json` and `application/x-www-form-urlencoded` are accepted.                                                                                                                                                        |
| 429         | **Too Many Requests** - The client has reached or exceeded a rate limit, a usage limit, or the server is overloaded. See [Rate Limits](/en/api/guides/rate-limits) for suggestions on retry patterns.                                                                                                                             |
| 5XX         | **Internal Server Errors** - something went wrong with Alvys' servers. These responses are likely momentary errors (e.g., temporary unavailability), and as a result, requests should be retried using exponential backoff. Note that the body of these responses follows the `application/problem+json` (ProblemDetails) format. |

## No results is not an error

List and search endpoints return **200 OK** with an empty collection when a well-formed query matches no records. Treat an empty `Items` array (or an empty list) as a successful empty result — not as a missing route, missing credential scope, or missing resource.

* **Paged search / list** — Response shape stays the same. `Items` is `[]`, and paging fields (`Page`, `PageSize`, `Total`) still reflect the request and the query's match count. Do not branch on `404` to mean "nothing matched."
* **Document lists** — When the parent resource exists but has no attachments, the endpoint returns **200** with `[]`. **404** still means the parent id is missing or not visible to your credential.

This applies across carriers, customers, drivers, fuel, invoices, loads, locations, maintenance, tolls, trailers, trips, trucks, users, and visibility outbound errors (including the related document-list routes).


# Timestamps
Source: https://docs.alvys.com/en/api/guides/timestamps

How the Alvys API returns UTC timestamps in ISO 8601 / RFC 3339 format and when localized stop-time values with timezone offsets are used instead.

Alvys primarily uses two formats for handling date-time values in its system:

* Standard Timestamps (UTC-based):
  * Stored in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) compliant [RFC 3339](https://tools.ietf.org/html/rfc3339) format using `DateTimeOffset` objects.
  * Always returned in Coordinated Universal Time (UTC).
* Localized Timestamps for Specific Use Cases
  * In some instances, such as location normalization, timestamps are returned in the local stop time of the event.
  * These timestamps include the appropriate timezone offsets to maintain accuracy.

<br />

## Examples of Date Time Conversions

<Info>
  Note

  The examples below will be in Python3 programming language, please install the following dependencies before executing the functions.

  [pytz](https://pypi.org/project/pytz/)\
  [dateutil](https://dateutil.readthedocs.io/en/stable/)\
  [datetime](https://pypi.org/project/DateTime/)
</Info>

The function below will convert the date-time in RFC 3339 format to the specified timezone.\
Function Usage: `convert\_timezone('2025-01-27T07:06:25Z', 'US/Eastern')`

```python theme={null}
def convert_timezone(time_value, target_time_zone):
    """
    Converts time in RFC 3339 format into the specified timezone.
    :param time_value: time in RFC 3339 (Example: '2020-01-27T07:06:25Z')
    :param target_time_zone: Example 'US/Central', 'US/Pacific' etc.)
    :return: converted time in string format

    Function Usage: convert_timezone('2025-01-27T07:06:25Z', 'US/Eastern')
    """
    parsed_t = dp.parse(time_value)
    time_in_seconds = parsed_t.timestamp()
    fmt = '%Y-%m-%d %H:%M:%S %Z%z'
    target_zone = pytz.timezone(target_time_zone)
    time_from_utc = datetime.fromtimestamp(time_in_seconds, tz=timezone.utc)
    time_from = time_from_utc.astimezone(target_zone)
    time_from.strftime(fmt)
    time_to_utc = datetime.fromtimestamp(time_in_seconds, tz=timezone.utc)
    converted_time = time_to_utc.astimezone(tz=pytz.timezone(target_time_zone))
    return converted_time
```


# Versioning
Source: https://docs.alvys.com/en/api/guides/versioning

How the Alvys Public API uses semantic versioning, the current v1.0 release, and how to include the version segment in your API request paths.

## How Versioning Works

Alvys uses a versioning system to manage changes in our API, especially when those changes are not backward-compatible. This approach ensures that your applications can continue to operate reliably, even as we introduce new features and improvements. Our versions follow a semantic versioning format, marked as v\{major}.\{minor}.\{patch} (e.g., v1.2.0). Below are the key highlights of our versioning strategy:

* When new endpoints are added to the API, they are accessible by all existing API versions by default. This ensures that new features can be adopted without requiring immediate changes to version numbers.
* Integrations using OAuth 2.0 will automatically use the latest API version when obtaining an access token, unless a specific version is specified in the request header.

## Current API Version

* Version in Use: `v1.0` is the only released version, and all API requests must use it. This ensures compatibility and access to the latest features and functionality supported in the `v1` version of our API.
* Example: `GET /api/p/v1/{resource}`\
  *Replace `{resource}` with the specific endpoint you are calling, such as `drivers`, `loads`, etc.*

### Understanding Semantic Versioning

* **Major Version** (for example `v1`): Introduced for backward-incompatible changes. Examples include removing or renaming fields, changing response structures, or altering existing functionality that could break existing integrations.
* **Minor Version** (`v1.1`, `v1.2`): Used for backward-compatible feature additions or enhancements that do not break existing functionality. Examples include adding new optional parameters or endpoints.
* **Patch Version** (`v1.0.1`, `v1.0.2`): Issued for backward-compatible bug fixes or minor changes that do not affect API functionality.

## Changing API Versions

There are two ways API versions can be selected or changed:

* **Route Parameters** - For specified endpoints, you are required to provide the version key in the route, e.g., `/api/{controller}/{version}/action`.
* **HTTP Header** - Versions can be overridden by providing the `api-version` HTTP header with your request. We recommend always passing this header value for your API requests to confirm your integration is using the intended API version.

#### Example URL Format

* Basic endpoint with version in URL: `https://integrations.alvys.com/api/p/v1/drivers`
* To explicitly set the version via HTTP header:

  ```http theme={null}
  GET /drivers
  Host: integrations.alvys.com
  api-version: v1
  ```

## Backwards Incompatible Changes

Alvys uses major version changes for the API for any of the following types of changes:

* Adding required request body fields, request body field values, or query parameters.
* Removing allowed request body fields, request body field values, query parameters, or query parameter values.
* Reducing documented rate limits per endpoint, per token, or per organization.
* Renaming request/response body fields, request body field values, query parameters, or query parameter values.
* Renaming or removing valid values for enumerated fields (e.g., different options for types of safety events).
* Changing the data type of a field (e.g., from string to int).
* Changing the nested JSON structure of requests/responses.
* Changing the expected payload of a response (e.g., returning active and inactive drivers versus just active).
* Deprecating access to certain endpoints.

## Backwards Compatible Changes

Alvys does not version the API for the following types of changes. This list is not exhaustive and explains the most common non-breaking changes:

* Changing the error message of an API endpoint's error.
* Changing the structure of a field's string value returned in a response body.
* Introducing additional optional (nullable) structure fields.


# Alvys API
Source: https://docs.alvys.com/en/api/index

Alvys Public API v1.0 documentation for logistics and transportation management, covering loads, drivers, authentication, webhooks, and MCP tools.

<div>
  <div>
    <div />

    <div />

    <div>
      <div>
        Public REST API · v1.0
      </div>

      # Alvys API

      <p>
        Unlock the full potential of your logistics operations with the Alvys API.
      </p>

      <div>
        <button type="button" aria-label="Search the API documentation">
          <svg>
            <path />

            <path />
          </svg>

          <span>Search the API docs…</span>
          <kbd>⌘K</kbd>
        </button>
      </div>

      <div>
        <a href="/en/api/guides/getting-started">
          Get Started

          <svg>
            <path />
          </svg>
        </a>

        <a href="/en/api/reference/authentication">
          API Reference
        </a>
      </div>
    </div>
  </div>
</div>

<div>
  <div>
    <h2>Start here</h2>
    <p>Quick paths for first-time integrators and existing customers.</p>
  </div>

  <CardGroup>
    <Card title="Getting Started" icon="rocket" href="/en/api/guides/getting-started">
      Create client credentials, request an access token, and make your first authenticated call.
    </Card>

    <Card title="Authentication" icon="key" href="/en/api/guides/authentication-1">
      Use OAuth 2.0 Client Credentials to issue scoped access tokens.
    </Card>

    <Card title="Versioning" icon="code-branch" href="/en/api/guides/versioning">
      Learn how the Alvys API is versioned and how to include the version in requests.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>Explore the API</h2>
    <p>Endpoints and events covering every core Alvys entity.</p>
  </div>

  <CardGroup>
    <Card title="Loads" icon="truck-fast" href="/en/api/reference/loads/get-load">
      Retrieve, search, and update loads across your fleet.
    </Card>

    <Card title="Trips" icon="route" href="/en/api/reference/trips/get-trip">
      Track trip lifecycle, stops, arrivals, and departures.
    </Card>

    <Card title="Tenders" icon="handshake" href="/en/api/guides/edi-integrations">
      Map EDI 204 / 990 / 214 / 210 workflows to Alvys REST + webhooks.
    </Card>

    <Card title="Drivers" icon="id-card" href="/en/api/reference/drivers/list-drivers">
      Manage driver records, documents, and events.
    </Card>

    <Card title="Carriers & Customers" icon="building" href="/en/api/reference/carriers/search-carriers">
      Search carriers and customers; upload documents; record payments.
    </Card>

    <Card title="Webhooks" icon="bolt" href="/en/api/reference/webhooks/overview">
      Subscribe to entity events with HMAC-signed delivery and retries.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>Guides</h2>
    <p>Hands-on walkthroughs for common data and BI workflows.</p>
  </div>

  <CardGroup>
    <Card title="Connecting to Power BI" icon="chart-column" href="/en/api/guides/connecting-power-bi-to-alvys-public-api-guide">
      Query the Alvys Public API from Power BI and refresh reports automatically.
    </Card>

    <Card title="Connecting to Google Sheets" icon="table" href="/en/api/guides/alvys-data-import-template-quick-setup-guide">
      Pull Alvys data into a preconfigured Google Sheets template.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>AI & Agents</h2>
    <p>Connect AI assistants and agents to Alvys through the MCP server.</p>
  </div>

  <CardGroup>
    <Card title="MCP Server" icon="plug" href="/en/api/guides/mcp">
      Give AI agents a governed, authenticated gateway to the Alvys Public API.
    </Card>

    <Card title="Available MCP Tools" icon="toolbox" href="/en/api/guides/available-mcp-tools">
      Browse every tool the MCP server exposes, with its tier and required scope.
    </Card>
  </CardGroup>
</div>

<div>
  <div>
    <h2>Stay informed</h2>
    <p>Follow releases and enhancements to the Public API.</p>
  </div>

  <CardGroup>
    <Card title="Changelog" icon="clock-rotate-left" href="/en/api/changelog">
      Recent additions to the Public API, webhooks, and integrations.
    </Card>

    <Card title="Contact" icon="envelope" href="https://alvys.com/resources/contact">
      Talk to your Alvys account representative or the Partnership team.
    </Card>
  </CardGroup>
</div>


# Authentication reference
Source: https://docs.alvys.com/en/api/reference/authentication

API reference for OAuth 2.0 Client Credentials authentication on the Alvys Public API — token endpoints, client app setup, and available scopes.

This page explains how to authenticate with the Alvys Public API using the OAuth 2.0 Client Credentials flow.

By leveraging OAuth 2.0, developers can empower their applications to seamlessly interact with Alvys' API on behalf of their users. This guide outlines the authentication process and provides detailed instructions on obtaining access tokens through direct application integration.

<Info>
  Getting API Access

  * Existing Alvys customers can obtain API access by contacting their account representative.
  * Independent Software Vendors (ISV) should contact the Alvys Partnership team.
</Info>

### 🔐 Creating Client Application Credentials

Follow these steps to create your credentials in the Alvys Admin Portal:

1. Navigate to **Admin → API Access**
2. Click **Create New Application**
3. Fill out the **Name** and **Description**
4. Select your desired **permissions** (scopes)
5. Set an optional **expiration date** for the credentials
6. Click **Generate**

   <img alt="" />

After creation, your **Client ID** and **Client Secret** will be shown, along with the scopes included for token generation. Customers can generate up to 10 sets of client credentials, but only newly generated ones can be edited.

<Warning>
  These values are sensitive and must be stored securely—avoid sharing them publicly or exposing them in front-end code.
</Warning>

<img alt="" />

These credentials are used to request an access token via the issue token endpoint.

<Tip>
  Want to try it right now? [Get an access token](/en/api/reference/token) runs this request in the playground and hands you a token you can paste straight into any other endpoint on this reference.
</Tip>

### Construct Authorization Request

Construct a URL with the following parameters in the request body:

1. `client_id`: The unique identifier assigned to your application by Alvys.
2. `client_secret`: The confidential token provided by Alvys upon application registration.
3. `audience`: Must be `"https://api.alvys.com/public/"`.
4. `grant_type`: The type of grant flow to use. **Must be `client_credentials`**

### 🔐 New Token Endpoint

All new token requests must now use the following endpoint:

### Token URL

```
https://auth.alvys.com/oauth/token

```

### Request Body (JSON)

```json theme={null}
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}

```

<Tip>
  When including a "scope" field in the token request body, please note:

  * The returned token will **always include all scopes** that have been granted to your client application, regardless of what you specify in the scope field.
  * Therefore, including a `scope` field in the request **does not override or limit the access** defined by your assigned permissions in the issued token.
  * The only functional effect of providing a `scope` field is that the token request will fail (unauthorized) if you include any scope that has not been granted to your client.
  * If the `scope` field is omitted, the token will still include **all scopes** granted to your application.
</Tip>

Either format may be used (JSON or Form-Encoded); both will return the same token and enforce scopes identically.

### Curl JSON Content-Type Example

```bash theme={null}
curl --request POST \
     --url 'https://auth.alvys.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "audience": "https://api.alvys.com/public/",
       "grant_type": "client_credentials"
     }'

```

### Curl Form-Encoded Format Example

```bash theme={null}
curl --request POST \
     --url https://auth.alvys.com/oauth/token \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data 'client_id=YOUR_CLIENT_ID' \
     --data 'client_secret=YOUR_CLIENT_SECRET' \
     --data 'audience=https://api.alvys.com/public/' \
     --data 'grant_type=client_credentials'

```

The token you receive will include a scope claim (e.g. `"load:read trip:create"`), and our Public API enforces those scopes on every request. Use the resulting access token in your API request headers:

```
Authorization: Bearer YOUR_ACCESS_TOKEN

```

> The `client_id` and \`client\_secret are created in the Alvys Admin Portal under API Access.

### Postman Token Request Example:

<img alt="" />

**Each client credential’s token is restricted to the exact scopes you assign, ensuring it can only access those corresponding API endpoints.**

***

<Warning>
  ***Note***

  *Some write endpoints are already published in the [API Reference](/en/api/reference/loads/update-load)—for example, load updates and load notes. Other `create`, `update`, and `delete` scopes may still lack a matching partner endpoint; check the API Reference for what is available today.*
</Warning>

***

### 🔒 Scope Claim

**Important:** Legacy tokens generated through the previous `/api/authentication/{tenant_id}/token` authentication flow do not include the `scope` claim. These tokens will temporarily remain valid and behave as if all read-only scopes are granted, but this is only supported during the transition period. All clients must migrate to the new flow by **July 31, 2025** to avoid disruption.

New tokens now follow a fine-grained permissions model, ensuring each application only has access to the specific API features it was granted.

Example:

```
"scope": "load:read driver:create"

```

Scopes control access to API endpoints and must be selected when creating your application in the Admin Portal.

### Available Scopes

| Entity               | Permission           | Description                   |
| -------------------- | -------------------- | ----------------------------- |
| Customers            | `customer:read`      | View customer records         |
| Customers            | `customer:create`    | Add a customer                |
| Customers            | `customer:update`    | Edit customer details         |
| Customers            | `customer:delete`    | Remove a customer             |
| Drivers              | `driver:read`        | View driver profiles          |
| Drivers              | `driver:create`      | Add new driver                |
| Drivers              | `driver:update`      | Edit driver info              |
| Drivers              | `driver:delete`      | Remove a driver               |
| Fuel                 | `fuel:read`          | View fuel records             |
| Fuel                 | `fuel:create`        | Add fuel transaction          |
| Fuel                 | `fuel:update`        | Update fuel entry             |
| Fuel                 | `fuel:delete`        | Delete fuel record            |
| Invoices             | `invoice:read`       | View invoices                 |
| Invoices             | `invoice:create`     | Create invoice                |
| Invoices             | `invoice:update`     | Edit invoice                  |
| Invoices             | `invoice:delete`     | Delete invoice                |
| Loads                | `load:read`          | Retrieve load info            |
| Loads                | `load:create`        | Create a load                 |
| Loads                | `load:update`        | Update a load                 |
| Loads                | `load:delete`        | Delete a load                 |
| Maintenance          | `maintenance:read`   | View maintenance data         |
| Maintenance          | `maintenance:create` | Log maintenance event         |
| Maintenance          | `maintenance:update` | Edit maintenance record       |
| Maintenance          | `maintenance:delete` | Remove maintenance record     |
| Tolls                | `toll:read`          | View toll data                |
| Tolls                | `toll:create`        | Log toll                      |
| Tolls                | `toll:update`        | Update toll entry             |
| Tolls                | `toll:delete`        | Delete toll entry             |
| Trailers             | `trailer:read`       | View trailer info             |
| Trailers             | `trailer:create`     | Register trailer              |
| Trailers             | `trailer:update`     | Edit trailer record           |
| Trailers             | `trailer:delete`     | Remove trailer                |
| Trips                | `trip:read`          | View trip details             |
| Trips                | `trip:create`        | Create trip                   |
| Trips                | `trip:update`        | Update trip                   |
| Trips                | `trip:delete`        | Cancel/delete trip            |
| Trucks               | `truck:read`         | View truck info               |
| Trucks               | `truck:create`       | Register truck                |
| Trucks               | `truck:update`       | Update truck record           |
| Trucks               | `truck:delete`       | Remove truck                  |
| Users                | `user:read`          | View users                    |
| Users                | `user:create`        | Add new user                  |
| Users                | `user:update`        | Modify user                   |
| Users                | `user:delete`        | Remove user                   |
| Visibility           | `visibility:read`    | Access tracking data          |
| Visibility           | `visibility:create`  | Trigger visibility update     |
| Visibility           | `visibility:update`  | Modify visibility data        |
| Visibility           | `visibility:delete`  | Remove tracking entry         |
| Dispatch Preferences | `dispatch:read`      | View dispatch rules           |
| Dispatch Preferences | `dispatch:update`    | Update dispatch preferences   |
| Carriers             | `carrier:read`       | View carrier profiles         |
| Carriers             | `carrier:create`     | Add a new carrier             |
| Carriers             | `carrier:update`     | Update carrier details        |
| Carriers             | `carrier:delete`     | Remove a carrier from records |

***

### 🧪 Troubleshooting

* ✅ Double-check your `client_id`, `client_secret`, and `audience`
* ✅ Ensure scopes are correctly assigned in API Access- Admin Portal
* ✅ Validate that the client is active and not expired
* ✅ Use only supported content types: `application/json` or `application/x-www-form-urlencoded`
* For technical support: `<support@alvys.com>`


# Get carrier
Source: https://docs.alvys.com/en/api/reference/carriers/get-carrier

GET /api/p/v{version}/carriers/{id}
Retrieve a single carrier record by ID from Alvys, including MC and DOT numbers, contact details, insurance, safety data, and payment terms.

The Get Carrier by ID endpoint retrieves detailed information for a specific carrier or subsidiary using its unique ID. This is helpful when you need a complete view of a single entity, including address, MC and DOT numbers, insurance information, and current status.

***

### Request Parameters

The following parameter is required in the URL path:

| **Parameter** | **Type** | **Required** | **Description**                         |
| ------------- | -------- | ------------ | --------------------------------------- |
| version       | String   | Yes          | The version of the API being requested. |
| id            | String   | Yes          | The unique identifier of the carrier.   |

### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/carriers/{id}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

```

Replace `{version}` with the API version number, `{Id}` with the actual carrier ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

### Response Parameters

The response contains a list of carriers or subsidiaries matching the search criteria, each represented by the following parameters:

| **Parameter**                | **Type**           | **Description**                                                                                                                                          |
| ---------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                           | String (UUID)      | The unique identifier of the carrier or subsidiary.                                                                                                      |
| Name                         | String             | The name of the carrier or subsidiary.                                                                                                                   |
| Address                      | Object             | The address details (Street, City, State, ZipCode).                                                                                                      |
| Address.Street               | String             | The street of the carrier’s address.                                                                                                                     |
| Address.City                 | String             | The city of the carrier’s address.                                                                                                                       |
| Address.State                | String             | The state of the carrier’s address.                                                                                                                      |
| Address.ZipCode              | String             | The zip code of the carrier’s address.                                                                                                                   |
| McNum                        | String             | The MC (Motor Carrier) number.                                                                                                                           |
| UsDotNum                     | String             | The USDOT number.                                                                                                                                        |
| ExternalName                 | String             | External/QuickBooks name for accounting integration. Null if not set.                                                                                    |
| ExternalAccountReference     | String             | External/QuickBooks account reference. Null if not set or not available.                                                                                 |
| Type                         | String             | Type of the entity (e.g., Carrier, Subsidiary).                                                                                                          |
| Status                       | String             | Current status of the carrier or subsidiary (e.g., Pending, Active, Packet Sent, Packet Completed, Do Not Load, Expired Insurance, Interested, Invited). |
| ExternalComplianceStatus     | String             | External compliance certification status (e.g., RMIS or MCP). Null if not set.                                                                           |
| CreatedAt                    | String (Date-Time) | The creation date of the carrier/subsidiary record.                                                                                                      |
| CreatedBy                    | String             | The user who created the carrier. Null if not set.                                                                                                       |
| Source                       | String             | Source of carrier data (e.g., import, manual). Null if not set.                                                                                          |
| UpdatedAt                    | String (Date-Time) | The date and time of the last update. Null if not set.                                                                                                   |
| Notes                        | Array of Objects   | A list of notes about the carrier. Null or empty if not set.                                                                                             |
| SalesAgentId                 | String             | The assigned sales agent ID. Null if not set.                                                                                                            |
| ExternalIds                  | Array of Objects   | External ID settings mapped from all external accounting ID settings. Null if none set.                                                                  |
| PaymentMethod                | String             | Payment method for the carrier (e.g., "Factoring Company", "Direct Deposit", "Check"). Null if not set.                                                  |
| FactoringCompany             | Object             | Factoring company details if the carrier uses factoring. Null if not using factoring.                                                                    |
| PaymentProvider              | Object             | Payment provider integration mapped to this carrier (e.g. TriumphPay). Null if not set.                                                                  |
| Contacts                     | Array of Objects   | Carrier contacts (name, email, phone, mobile, title). Null or empty if the carrier has no contacts.                                                      |
| InsuranceInfo                | Array of Objects   | A list of insurance policies associated with the carrier.                                                                                                |
| InsuranceInfo.Type           | String             | The type of insurance (e.g., Auto, Cargo, General, Workers Compensation).                                                                                |
| InsuranceInfo.PolicyNumber   | String             | The insurance policy number.                                                                                                                             |
| InsuranceInfo.IssueDate      | String (Date-Time) | The issue date of the insurance policy.                                                                                                                  |
| InsuranceInfo.ExpirationDate | String (Date-Time) | The expiration date of the insurance policy.                                                                                                             |
| InsuranceInfo.Amount         | Number             | The coverage amount of the insurance policy.                                                                                                             |
| InsuranceInfo.Agent          | Object             | Information about the insurance agent.                                                                                                                   |
| InsuranceInfo.Agent.Company  | String             | The name of the agent’s company.                                                                                                                         |
| InsuranceInfo.Agent.Name     | String             | The name of the insurance agent.                                                                                                                         |
| InsuranceInfo.Agent.Contact  | Object             | Contact details for the insurance agent (name, email, phone, mobile, title).                                                                             |
| InsuranceInfo.Notes          | String             | Notes associated with the insurance policy.                                                                                                              |

### Example Response

```json theme={null}
    {
      "Id": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0",
      "Name": "EVENT PRO LOGISTICS",
      "Address": {
        "Street": "3749 E 150 S",
        "City": "TIPTON",
        "State": "IN",
        "ZipCode": "46072"
      },
      "McNum": "63504",
      "UsDotNum": "4204692",
      "Type": "Subsidiary",
      "Status": "Active",
      "CreatedAt": "2024-04-02T08:42:31.269118+00:00"
       "InsuranceInfo": [
        {
          "Type": "Auto",
          "PolicyNumber": "2445",
          "IssueDate": "2024-11-14T00:00:00+00:00",
          "ExpirationDate": "2030-11-14T00:00:00+00:00",
          "Amount": 0.0,
          "Agent": {
            "Company": "PG Company",
            "Name": ""
          },
          "Notes": ""
        }
      ]
    }
```

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Get carrier settlement statement
Source: https://docs.alvys.com/en/api/reference/carriers/get-carrier-settlement-statement

GET /api/p/v{version}/carrier-settlement-statements/{number}
Retrieve a finalized carrier settlement statement from Alvys by statement number, including per-trip breakdown, line items, payments, and totals.

The Get Carrier Settlement Statement endpoint returns a single finalized carrier settlement statement by its statement number, including its per-trip breakdown, line items, payments, and totals.

Only settled statements are returned. If the statement does not exist, or is deleted/failed, the endpoint responds with `404 Not Found`.

This endpoint requires the `carrier:read` scope.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |
| number    | Number | Yes      | The statement number to retrieve.       |

### Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/carrier-settlement-statements/1042' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

Returns a single statement object with the same shape as each item in the Search Carrier Settlement Statements response. Monetary values are objects of the form `{ "Amount": <number>, "Currency": <ISO 4217 numeric code, may be null> }`.

| Parameter       | Type               | Description                                                                                                                                                                                                                                                          |
| --------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Number          | Number             | The statement number.                                                                                                                                                                                                                                                |
| Status          | String             | The statement status (e.g. `Processed`, `Paid`).                                                                                                                                                                                                                     |
| StatementDate   | String (Date-Time) | The statement date.                                                                                                                                                                                                                                                  |
| RemittanceDate  | String (Date-Time) | The scheduled remittance date. Null if not set.                                                                                                                                                                                                                      |
| SubsidiaryId    | String             | The subsidiary the statement belongs to.                                                                                                                                                                                                                             |
| Payee           | Object             | Who gets paid: `Type` (`Carrier` or `FactoringCompany`), `Id`, `Name`, `McNumber`, `DotNumber`.                                                                                                                                                                      |
| RemitTo         | String             | The resolved remit-to name. Null if not set.                                                                                                                                                                                                                         |
| PaymentProvider | String             | The payment provider (e.g. `Standard`, `TriumphPay`).                                                                                                                                                                                                                |
| NetAmount       | Money              | The statement net (payable) amount.                                                                                                                                                                                                                                  |
| PaidAmount      | Money              | The amount paid so far.                                                                                                                                                                                                                                              |
| RemainingAmount | Money              | The amount still outstanding.                                                                                                                                                                                                                                        |
| Trips           | Array of Objects   | Per-trip breakdown, each with `TripId` (stable unique trip identifier, always present), `TripNumber`, `LoadNumber`, `Origin`, `Destination`, pickup/delivery + invoice fields, trip totals, and an `Items` array (`Description`, `Type`, `Amount`, `AccountingTag`). |
| Payments        | Array of Objects   | Recorded payments: `Id`, `Amount`, `PaymentDate`, `PaymentMethod`, `ReferenceNumber`, `CheckNumber`.                                                                                                                                                                 |

### Example Response

```json theme={null}
{
  "Number": 1042,
  "Status": "Processed",
  "StatementDate": "2026-06-15T12:00:00+00:00",
  "RemittanceDate": "2026-06-20T00:00:00+00:00",
  "SubsidiaryId": "a1b2c3d4-0000-0000-0000-000000000001",
  "Payee": {
    "Type": "FactoringCompany",
    "Id": "f1a2b3c4-5555-6666-7777-888899990000",
    "Name": "Factor LLC",
    "McNumber": null,
    "DotNumber": null
  },
  "RemitTo": "Factor LLC",
  "PaymentProvider": "TriumphPay",
  "NetAmount": { "Amount": 1150.00, "Currency": 840 },
  "PaidAmount": { "Amount": 1150.00, "Currency": 840 },
  "RemainingAmount": { "Amount": 0.00, "Currency": 840 },
  "Trips": [
    {
      "TripId": "b2c3d4e5-1111-2222-3333-444455556666",
      "TripNumber": "TRIP-1",
      "LoadNumber": "L-55021",
      "Origin": "Chicago, IL",
      "Destination": "Atlanta, GA",
      "NetAmount": { "Amount": 1150.00, "Currency": 840 },
      "LineHaulAmount": { "Amount": 1000.00, "Currency": 840 },
      "AccessorialsAmount": { "Amount": 150.00, "Currency": 840 },
      "Items": [
        { "Description": "Line Haul", "Type": "LineHaul", "Amount": { "Amount": 1000.00, "Currency": 840 }, "AccountingTag": "Carrier Rate" }
      ]
    }
  ],
  "Payments": [
    {
      "Id": "c3d4e5f6-2222-3333-4444-555566667777",
      "Amount": { "Amount": 1150.00, "Currency": 840 },
      "PaymentDate": "2026-06-21T00:00:00+00:00",
      "PaymentMethod": "ACH",
      "ReferenceNumber": "REF-9001",
      "CheckNumber": null
    }
  ]
}
```

<br />

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.


# List carrier documents
Source: https://docs.alvys.com/en/api/reference/carriers/list-carrier-documents

GET /api/p/v{version}/carriers/{carrierId}/documents
List all uploaded documents attached to a specific carrier by carrier ID, including contracts, W-9s, insurance certificates, and operating authority filings.

Retrieve all uploaded documents associated with a specific **Carrier** by its unique `carrierId`.

### Request Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| version   | String | Yes      | API version to use.               |
| carrierId | String | Yes      | Unique identifier of the carrier. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/carriers/{carrierId}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{carrierId}` with the actual carrier ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                         |
| -------------- | ------- | ------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                  |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix). |
| AttachmentType | string  | Type of document (e.g., Carrier Agreement, Carrier Authority).      |
| AttachmentSize | integer | Size of the file in bytes.                                          |
| UploadedAt     | string  | UTC timestamp when the file was uploaded (ISO 8601).                |
| ParentId       | string  | Identifier of the parent entity (`carrierId`).                      |
| ParentType     | string  | Entity type the document is attached to (`Carrier`).                |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.       |
| DownloadUrl    | string  | Time-limited link (10 minutes) to download the document.            |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl`.                          |

***

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "a314c7cd-0000a-1111-0000-06406a9e000a",
    "AttachmentPath": "CarrierAuthority-1759237626.pdf",
    "AttachmentType": "Carrier Authority",
    "AttachmentSize": 170225,
    "UploadedAt": "2025-09-30T13:07:07+00:00",
    "ParentId": "1111111-956d-4511-a1ed-4b9072sder55f",
    "ParentType": "Carrier",
    "UploadedBy": "10000000eecc0000e90d7173f4ece0e00",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/CarrierAuthority-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T13:17:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **carrierId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Search carrier settlement statements
Source: https://docs.alvys.com/en/api/reference/carriers/search-carrier-settlement-statements

POST /api/p/v{version}/carrier-settlement-statements/search
Search finalized carrier settlement statements in Alvys with paginated POST filters by date range, carrier, statement number, and amount.

The Search Carrier Settlement Statements endpoint returns a paged list of finalized carrier settlement statements (the "Statements" tab), each with its per-trip breakdown, line items, payments, and totals. It mirrors the in-app carrier "Statements List and Items" report and is intended for external reporting.

Only settled statements are returned - deleted and failed statements are excluded. Each statement identifies its payee (the carrier directly, or a factoring company when the carrier is factored).

For carriers, `Failed` and `Deleted` are lifecycle statuses, so those statements are excluded from the export. This differs from driver settlement statements, where a `Failed` status reflects a downstream step failure on an otherwise-finalized statement, which is returned.

This endpoint requires the `carrier:read` scope.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

### Request Body

| Parameter                | Type               | Required | Description                                                                                           |
| ------------------------ | ------------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| Page                     | Number             | Yes      | The page number for pagination (starts from 0).                                                       |
| PageSize                 | Number             | Yes      | The number of results per page. Must be greater than 0 and cannot exceed 100.                         |
| StatementDateRange       | Object             | Yes      | The inclusive statement-date window to filter on. Both bounds are treated as whole UTC calendar days. |
| StatementDateRange.Start | String (Date-Time) | Yes      | Start of the range (inclusive).                                                                       |
| StatementDateRange.End   | String (Date-Time) | Yes      | End of the range (inclusive). Required - an open-ended range is rejected.                             |
| CarrierId                | String (UUID)      | No       | Filter to a single carrier.                                                                           |
| SubsidiaryId             | String (UUID)      | No       | Filter to a single subsidiary.                                                                        |

### Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/carrier-settlement-statements/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 0,
  "PageSize": 50,
  "StatementDateRange": {
    "Start": "2026-06-01T00:00:00Z",
    "End": "2026-06-30T00:00:00Z"
  },
  "CarrierId": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0"
}'
```

### Response Parameters

The response is a paged envelope. Each item is a finalized statement. Monetary values are objects of the form `{ "Amount": <number>, "Currency": <ISO 4217 numeric code, may be null> }`.

| Parameter                                                         | Type               | Description                                                                                          |
| ----------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| Page                                                              | Number             | The current page number.                                                                             |
| PageSize                                                          | Number             | The number of items per page.                                                                        |
| Total                                                             | Number             | The total number of matching statements across all pages.                                            |
| Items                                                             | Array of Objects   | The statements on this page.                                                                         |
| Items\[].Number                                                   | Number             | The statement number.                                                                                |
| Items\[].Status                                                   | String             | The statement status (e.g. `Processed`, `Paid`).                                                     |
| Items\[].StatementDate                                            | String (Date-Time) | The statement date.                                                                                  |
| Items\[].RemittanceDate                                           | String (Date-Time) | The scheduled remittance date. Null if not set.                                                      |
| Items\[].SubsidiaryId                                             | String             | The subsidiary the statement belongs to.                                                             |
| Items\[].Payee                                                    | Object             | Who gets paid: `Type` (`Carrier` or `FactoringCompany`), `Id`, `Name`, `McNumber`, `DotNumber`.      |
| Items\[].RemitTo                                                  | String             | The resolved remit-to name. Null if not set.                                                         |
| Items\[].PaymentProvider                                          | String             | The payment provider (e.g. `Standard`, `TriumphPay`).                                                |
| Items\[].NetAmount                                                | Money              | The statement net (payable) amount.                                                                  |
| Items\[].PaidAmount                                               | Money              | The amount paid so far.                                                                              |
| Items\[].RemainingAmount                                          | Money              | The amount still outstanding.                                                                        |
| Items\[].Trips                                                    | Array of Objects   | Per-trip breakdown.                                                                                  |
| Items\[].Trips\[].TripId                                          | String             | The stable unique trip identifier (always present).                                                  |
| Items\[].Trips\[].TripNumber                                      | String             | The trip number.                                                                                     |
| Items\[].Trips\[].LoadNumber                                      | String             | The load number.                                                                                     |
| Items\[].Trips\[].Origin / Destination                            | String             | Trip origin and destination. Null if not set.                                                        |
| Items\[].Trips\[].PickedUpAt / DeliveredAt                        | String (Date-Time) | Pickup and delivery timestamps. Null if not set.                                                     |
| Items\[].Trips\[].InvoiceNumber / InvoiceDueDate                  | String             | Carrier invoice number and due date. Null if not set.                                                |
| Items\[].Trips\[].NetAmount / LineHaulAmount / AccessorialsAmount | Money              | Trip-level totals.                                                                                   |
| Items\[].Trips\[].Items                                           | Array of Objects   | Trip line items: `Description`, `Type`, `Amount`, `AccountingTag`.                                   |
| Items\[].Payments                                                 | Array of Objects   | Recorded payments: `Id`, `Amount`, `PaymentDate`, `PaymentMethod`, `ReferenceNumber`, `CheckNumber`. |

### Example Response

```json theme={null}
{
  "Page": 0,
  "PageSize": 50,
  "Total": 1,
  "Items": [
    {
      "Number": 1042,
      "Status": "Processed",
      "StatementDate": "2026-06-15T12:00:00+00:00",
      "RemittanceDate": "2026-06-20T00:00:00+00:00",
      "SubsidiaryId": "a1b2c3d4-0000-0000-0000-000000000001",
      "Payee": {
        "Type": "Carrier",
        "Id": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0",
        "Name": "Acme Carrier",
        "McNumber": "MC123456",
        "DotNumber": "4204692"
      },
      "RemitTo": "Acme Carrier LLC",
      "PaymentProvider": "Standard",
      "NetAmount": { "Amount": 1150.00, "Currency": 840 },
      "PaidAmount": { "Amount": 0.00, "Currency": 840 },
      "RemainingAmount": { "Amount": 1150.00, "Currency": 840 },
      "Trips": [
        {
          "TripId": "b2c3d4e5-1111-2222-3333-444455556666",
          "TripNumber": "TRIP-1",
          "LoadNumber": "L-55021",
          "Origin": "Chicago, IL",
          "Destination": "Atlanta, GA",
          "PickedUpAt": "2026-06-12T09:00:00+00:00",
          "DeliveredAt": "2026-06-14T16:00:00+00:00",
          "InvoiceNumber": "INV-1042",
          "InvoiceDueDate": "2026-07-14T00:00:00+00:00",
          "NetAmount": { "Amount": 1150.00, "Currency": 840 },
          "LineHaulAmount": { "Amount": 1000.00, "Currency": 840 },
          "AccessorialsAmount": { "Amount": 150.00, "Currency": 840 },
          "Items": [
            { "Description": "Line Haul", "Type": "LineHaul", "Amount": { "Amount": 1000.00, "Currency": 840 }, "AccountingTag": "Carrier Rate" },
            { "Description": "Detention", "Type": "Accessorial", "Amount": { "Amount": 150.00, "Currency": 840 }, "AccountingTag": "Detention" }
          ]
        }
      ],
      "Payments": []
    }
  ]
}
```

<br />

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# Search carriers
Source: https://docs.alvys.com/en/api/reference/carriers/search-carriers

POST /api/p/v{version}/carriers/search
Search Alvys carriers with paginated POST filters — MC and DOT number, name, status, insurance expiration, safety rating, and lane preferences.

The Search Carriers API endpoint helps users retrieve carrier or subsidiary details efficiently by filtering through available data using IDs, MC numbers, DOT numbers, and Status. This functionality provides quick access to essential carrier information without needing to query the full dataset.

***

### Request Parameters

The following parameter is required in the URL path:

| **Parameter** | **Type** | **Required** | **Description**                         |
| ------------- | -------- | ------------ | --------------------------------------- |
| version       | String   | Yes          | The version of the API being requested. |

***

### Request Body

The request body must include the following parameters:

| **Parameter** | **Type**                | **Required**  | **Description**                                                                                                                                                                                                                       |
| ------------- | ----------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page          | Number                  | Yes           | The page number for pagination (starts from 0).                                                                                                                                                                                       |
| PageSize      | Number                  | Yes           | The number of results per page. PageSize must be greater than 0 and cannot be greater than 200.                                                                                                                                       |
| Status        | Array of Strings        | Conditionally | Filter by carrier or subsidiary status (e.g., Pending, Active, Packet Sent, Packet Completed, Do Not Load, Expired Insurance, Interested, Invited). This field is required if the other conditionally required fields are left empty. |
| Ids           | Array of Strings (UUID) | Conditionally | Filter by specific carrier or subsidiary IDs. This field is required if the other conditionally required fields are left empty.                                                                                                       |
| McNumbers     | Array of Strings        | Conditionally | Filter by MC (Motor Carrier) numbers. This field is required if the other conditionally required fields are left empty.                                                                                                               |
| DotNumbers    | Array of Strings        | Conditionally | Filter by USDOT numbers. This field is required if the other conditionally required fields are left empty.                                                                                                                            |

At least one filter field (`Status`, `Ids`, `McNumbers`, `DotNumbers`) must be provided along with pagination fields.

### Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/carriers/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 0,
  "PageSize": 100,
  "Status": ["Active", "Pending", "Do Not Load"],
  "Ids": ["2e17c4d3-202d-4f27-b2fa-711c57435c5b"],
  "McNumbers": ["1269221"],
  "DotNumbers": ["4204692"]
}'
```

### Response Parameters

The response contains a list of carriers or subsidiaries matching the search criteria, each represented by the following parameters:

| **Parameter**                | **Type**           | **Description**                                                                                                                                          |
| ---------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                         | Number             | The current page number.                                                                                                                                 |
| PageSize                     | Number             | The number of items per page.                                                                                                                            |
| Total                        | Number             | The total number of matching items.                                                                                                                      |
| Id                           | String (UUID)      | The unique identifier of the carrier or subsidiary.                                                                                                      |
| Name                         | String             | The name of the carrier or subsidiary.                                                                                                                   |
| Address                      | Object             | The address details (Street, City, State, ZipCode).                                                                                                      |
| Address.Street               | String             | The street of the carrier’s address.                                                                                                                     |
| Address.City                 | String             | The city of the carrier’s address.                                                                                                                       |
| Address.State                | String             | The state of the carrier’s address.                                                                                                                      |
| Address.ZipCode              | String             | The zip code of the carrier’s address.                                                                                                                   |
| McNum                        | String             | The MC (Motor Carrier) number.                                                                                                                           |
| UsDotNum                     | String             | The USDOT number.                                                                                                                                        |
| ExternalName                 | String             | External/QuickBooks name for accounting integration. Null if not set.                                                                                    |
| ExternalAccountReference     | String             | External/QuickBooks account reference. Null if not set or not available.                                                                                 |
| Type                         | String             | Type of the entity (e.g., Carrier, Subsidiary).                                                                                                          |
| Status                       | String             | Current status of the carrier or subsidiary (e.g., Pending, Active, Packet Sent, Packet Completed, Do Not Load, Expired Insurance, Interested, Invited). |
| ExternalComplianceStatus     | String             | External compliance certification status (e.g., RMIS or MCP). Null if not set.                                                                           |
| CreatedAt                    | String (Date-Time) | The creation date of the carrier/subsidiary record.                                                                                                      |
| CreatedBy                    | String             | The user who created the carrier. Null if not set.                                                                                                       |
| Source                       | String             | Source of carrier data (e.g., import, manual). Null if not set.                                                                                          |
| UpdatedAt                    | String (Date-Time) | The date and time of the last update. Null if not set.                                                                                                   |
| Notes                        | Array of Objects   | A list of notes about the carrier. Null or empty if not set.                                                                                             |
| SalesAgentId                 | String             | The assigned sales agent ID. Null if not set.                                                                                                            |
| ExternalIds                  | Array of Objects   | External ID settings mapped from all external accounting ID settings. Null if none set.                                                                  |
| PaymentMethod                | String             | Payment method for the carrier (e.g., "Factoring Company", "Direct Deposit", "Check"). Null if not set.                                                  |
| FactoringCompany             | Object             | Factoring company details if the carrier uses factoring. Null if not using factoring.                                                                    |
| PaymentProvider              | Object             | Payment provider integration mapped to this carrier (e.g. TriumphPay). Null if not set.                                                                  |
| Contacts                     | Array of Objects   | Carrier contacts (name, email, phone, mobile, title). Null or empty if the carrier has no contacts.                                                      |
| InsuranceInfo                | Array of Objects   | A list of insurance policies associated with the carrier.                                                                                                |
| InsuranceInfo.Type           | String             | The type of insurance (e.g., Auto, Cargo, General, Workers Compensation).                                                                                |
| InsuranceInfo.PolicyNumber   | String             | The insurance policy number.                                                                                                                             |
| InsuranceInfo.IssueDate      | String (Date-Time) | The issue date of the insurance policy.                                                                                                                  |
| InsuranceInfo.ExpirationDate | String (Date-Time) | The expiration date of the insurance policy.                                                                                                             |
| InsuranceInfo.Amount         | Number             | The coverage amount of the insurance policy.                                                                                                             |
| InsuranceInfo.Agent          | Object             | Information about the insurance agent.                                                                                                                   |
| InsuranceInfo.Agent.Company  | String             | The name of the agent’s company.                                                                                                                         |
| InsuranceInfo.Agent.Name     | String             | The name of the insurance agent.                                                                                                                         |
| InsuranceInfo.Agent.Contact  | Object             | Contact details for the insurance agent (name, email, phone, mobile, title).                                                                             |
| InsuranceInfo.Notes          | String             | Notes associated with the insurance policy.                                                                                                              |

### Example Response

```json theme={null}
{
  "Page": 0,
  "PageSize": 100,
  "Total": 1,
  "Items": [
    {
      "Id": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0",
      "Name": "EVENT PRO LOGISTICS",
      "Address": {
        "Street": "3749 E 150 S",
        "City": "TIPTON",
        "State": "IN",
        "ZipCode": "46072"
      },
      "McNum": "63504",
      "UsDotNum": "4204692",
      "Type": "Subsidiary",
      "Status": "Do Not Load",
      "CreatedAt": "2024-04-02T08:42:31.269118+00:00",
      "InsuranceInfo": [
        {
          "Type": "Auto",
          "PolicyNumber": "2445",
          "IssueDate": "2024-11-14T00:00:00+00:00",
          "ExpirationDate": "2030-11-14T00:00:00+00:00",
          "Amount": 0.0,
          "Agent": {
            "Company": "PG Company",
            "Name": ""
          },
          "Notes": ""
        }
      ]
    }
  ]
}
```

<br />

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# Set carrier status
Source: https://docs.alvys.com/en/api/reference/carriers/set-carrier-status

PATCH /api/p/v{version}/carriers/{carrierId}/status
Update a carrier or subsidiary status in Alvys by carrier ID via the Public API, transitioning between active, inactive, blocked, and pending states.

Changes the status of an existing carrier. On success the endpoint returns `204 No Content`; the carrier's new optimistic-concurrency token is returned on the `ETag` response header.

This endpoint supports **optional** optimistic concurrency. When you send the carrier's current `ETag` in an `If-Match` header, a change made by someone else since you read the record fails with `412 Precondition Failed` instead of overwriting it — refetch with GET to obtain a fresh token and retry. When you omit the header the write is last-writer-wins.

<Note>
  Status changes are not supported for owner-operator carriers. A request against one returns `422 Unprocessable Entity`, not `404` — the carrier exists, but its type has no status to transition.
</Note>

***

### Status Codes

| Status | Meaning                                                                                     |
| ------ | ------------------------------------------------------------------------------------------- |
| 204    | The carrier status was updated.                                                             |
| 400    | The request body was malformed or the status value was not recognized.                      |
| 401    | The request was not authenticated.                                                          |
| 403    | The caller lacks permission to update carriers.                                             |
| 404    | No carrier with the given `carrierId` exists.                                               |
| 412    | The supplied `If-Match` token did not match the current record. Refetch with GET and retry. |
| 422    | The carrier is an owner-operator, whose status cannot be changed.                           |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.


# Upload carrier document
Source: https://docs.alvys.com/en/api/reference/carriers/upload-carrier-document

POST /api/p/v{version}/carriers/{carrierId}/document
Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific **carrier**. Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`, `image/gif`
* **Allowed Document Types:** Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents

***

### Parameters

| Parameter   | In   | Type   | Required | Description                      |
| ----------- | ---- | ------ | -------- | -------------------------------- |
| `carrierId` | path | string | Yes      | Unique identifier of the carrier |
| `version`   | path | string | Yes      | API version (e.g., `1.0`)        |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG). Max size 25 MB.                         |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/carriers/{carrierId}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@Carrier_Agreement.pdf" \
  -F "DocumentType=Carrier Agreement"
```

***

### Response Body

| Name             | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (e.g., `1757343192`) |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                 |
| `AttachmentSize` | integer | Size of the file in bytes                                                 |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded (ISO 8601)                       |
| `ParentId`       | string  | Identifier of the parent entity (the `{carrierId}`)                       |
| `ParentType`     | string  | Entity type the document is attached to (`Carrier`)                       |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "b7a2d8c1-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "Carrier_Agreement-1757343192.pdf",
  "AttachmentType": "Carrier Agreement",
  "AttachmentSize": 3145728,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "b7a000c1-005e-0000-a4ee-45ca5e00000a",
  "ParentType": "Carrier"
}
```

<br />

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **carrierId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Create customer
Source: https://docs.alvys.com/en/api/reference/customers/create-customer

POST /api/p/v{version}/customers
Create a new customer record in Alvys with company profile, billing address, contacts, credit terms, and default rate agreements for future loads.

The Create Customer endpoint adds a new business company (a Customer or a Broker/3PL) to your account. On success it returns the created record together with the optimistic-concurrency token (`ETag`) you will need for any later update or delete. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

Per-tenant, per-`Type` uniqueness is enforced on `CompanyNumber`, `ExternalId`, and `(Name + Zip)`. A request that would create a duplicate is rejected with `409 Conflict` and the identifier of the existing customer.

***

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The version of the API. |

***

### Request Body

The request body accepts the following fields. Only `Name` is required.

| Field                  | Type            | Required | Description                                                                      |
| ---------------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
| Name                   | String          | Yes      | The customer name. Must be 200 characters or fewer.                              |
| Type                   | String          | No       | The customer type. One of "Customer" or "Broker/3PL".                            |
| CompanyNumber          | String          | No       | A reference/registration number for the company. Must be 32 characters or fewer. |
| Status                 | String          | No       | The customer status. One of "Active" or "Inactive".                              |
| BillingAddress         | Object          | No       | The billing address of the customer.                                             |
| BillingAddress.Street  | String          | No       | The street line of the billing address.                                          |
| BillingAddress.City    | String          | No       | The city of the billing address.                                                 |
| BillingAddress.State   | String          | No       | The state of the billing address.                                                |
| BillingAddress.Zip     | String          | No       | The postal code of the billing address.                                          |
| BillingAddress.Country | String          | No       | ISO country code of the billing address. Defaults to "US".                       |
| Email                  | Array of String | No       | A list of email addresses associated with the customer.                          |
| Phone                  | Array of String | No       | A list of phone numbers associated with the customer.                            |
| Fax                    | String          | No       | The fax number of the customer.                                                  |
| ExternalId             | String          | No       | An external reference identifier. Must be 100 characters or fewer.               |

***

### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/customers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Name": "Acme Logistics",
  "Type": "Broker/3PL",
  "CompanyNumber": "ACME-001",
  "Status": "Active",
  "BillingAddress": {
    "Street": "123 Main St",
    "City": "Dallas",
    "State": "TX",
    "Zip": "75201",
    "Country": "US"
  },
  "Email": ["billing@acme.example"],
  "Phone": ["+1-214-555-0100"],
  "ExternalId": "EXT-ACME-001"
}'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token.

***

### Response Fields

A successful request returns the created customer. The optimistic-concurrency token is returned both on the HTTP `ETag` response header and in the `ETag` body field, so you can use it on a follow-up `If-Match` without an extra GET.

| Field                  | Type               | Description                                             |
| ---------------------- | ------------------ | ------------------------------------------------------- |
| Id                     | String             | The unique identifier of the created customer.          |
| ETag                   | String             | The optimistic-concurrency token for the new record.    |
| Name                   | String             | The name of the customer.                               |
| CompanyNumber          | String             | The company number of the customer.                     |
| Type                   | String             | The type of customer ("Customer" or "Broker/3PL").      |
| Status                 | String             | The raw persisted status of the customer.               |
| BillingAddress         | Object             | The billing address of the customer.                    |
| BillingAddress.Street  | String             | The street line of the billing address.                 |
| BillingAddress.City    | String             | The city of the billing address.                        |
| BillingAddress.State   | String             | The state of the billing address.                       |
| BillingAddress.ZipCode | String             | The postal code of the billing address.                 |
| Email                  | Array              | A list of email addresses associated with the customer. |
| Phone                  | Array              | A list of phone numbers associated with the customer.   |
| Fax                    | String             | The fax number of the customer.                         |
| DateCreated            | String (Date-Time) | The date and time when the customer was created.        |
| DateModified           | String (Date-Time) | The date and time of this write.                        |
| InvoicingInformation   | Object             | The invoicing information for the customer.             |
| ExternalId             | String             | The external identifier associated with the customer.   |

***

### Example Response

**201 Created**

```json theme={null}
{
  "Id": "01fec4d332ed49ff96595c8d4434ea96",
  "ETag": "\"00000000-0000-0000-0000-000000000001\"",
  "Name": "Acme Logistics",
  "CompanyNumber": "ACME-001",
  "Type": "Broker/3PL",
  "Status": "Active",
  "BillingAddress": {
    "Street": "123 Main St",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "75201"
  },
  "Email": ["billing@acme.example"],
  "Phone": ["+1-214-555-0100"],
  "Fax": null,
  "DateCreated": "2025-09-08T19:38:34.529Z",
  "DateModified": "2025-09-08T19:38:34.529Z",
  "InvoicingInformation": null,
  "ExternalId": "EXT-ACME-001"
}
```

***

### Status Codes

| Status | Meaning                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 201    | The customer was created.                                                                                                                  |
| 400    | The request body failed validation.                                                                                                        |
| 401    | The request was not authenticated.                                                                                                         |
| 403    | The caller lacks permission to create customers.                                                                                           |
| 409    | A customer with the same `CompanyNumber`, `ExternalId`, or `(Name + Zip)` already exists. The response includes the existing `customerId`. |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# Delete customer
Source: https://docs.alvys.com/en/api/reference/customers/delete-customer

DELETE /api/p/v{version}/customers/{id}
Delete a customer record by ID from your Alvys tenant using the Public API, permanently removing the customer profile, contacts, and associated metadata.

The Delete Customer endpoint soft-deletes (deactivates) a business company. It sets the customer's `Status` to `Inactive`; the record stays visible on GET and search. To reactivate it, send a PATCH with `Status: Active`. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

This endpoint uses optimistic concurrency. You must send the customer's current `ETag` in an `If-Match` header. The token is returned on the `ETag` response header of a GET, and in the body of a create/update response. If the token does not match the current record the request fails with `412 Precondition Failed`; refetch with GET to obtain a fresh value and retry.

***

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| version   | String | Yes      | The version of the API.                |
| id        | String | Yes      | The unique identifier of the customer. |

The following header is required:

| Header   | Required | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| If-Match | Yes      | The current `ETag` of the customer being deleted. |

***

### Example CURL Request

```bash theme={null}
curl --location --request DELETE 'https://integrations.alvys.com/api/p/v1/customers/01fec4d332ed49ff96595c8d4434ea96' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'If-Match: "00000000-0000-0000-0000-000000000002"'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token and `If-Match` with the customer's current `ETag`.

***

### Response

On success the endpoint returns `204 No Content` with an empty body.

***

### Status Codes

| Status | Meaning                                                                                     |
| ------ | ------------------------------------------------------------------------------------------- |
| 204    | The customer was deactivated.                                                               |
| 401    | The request was not authenticated.                                                          |
| 403    | The caller lacks permission to delete customers.                                            |
| 404    | No customer with the given `id` exists.                                                     |
| 409    | The operation conflicted with the current state of the record.                              |
| 412    | The supplied `If-Match` token did not match the current record. Refetch with GET and retry. |
| 428    | The `If-Match` header is required but was not provided.                                     |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# List customers
Source: https://docs.alvys.com/en/api/reference/customers/list-customers

GET /api/p/v{version}/customers
List customer records in your Alvys tenant with pagination, returning company profiles, billing addresses, credit terms, and default rate agreements.

The endpoint for retrieving customer details allows you to access a single customer record by providing either the customer ID or the company number. At least one of these parameters (`id` or `companyNumber`) must be included in the request, ensuring flexibility and ease of use. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are conditionally required in the URL:

| Parameter     | Type   | Required    | Description                                                                             |
| ------------- | ------ | ----------- | --------------------------------------------------------------------------------------- |
| id            | String | Conditional | The unique identifier of the customer. Either `id` or `companyNumber` must be provided. |
| companyNumber | String | Conditional | The company number of the customer. Either `companyNumber` or `id` must be provided.    |

***

#### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/customers?id=01fec4d332ed49ff96595c8d4434ea96' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

OR

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/customers?companyNumber=DLA87FOVA22060' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token. Use either `id` or `companyNumber` as required.

### Response Fields

The following fields are included in the response:

| Field                                   | Type               | Description                                                                                                                                              |
| --------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                                      | String             | The unique identifier of the customer.                                                                                                                   |
| Name                                    | String             | The name of the customer.                                                                                                                                |
| CompanyNumber                           | String             | The company number of the customer. A customer-provided reference or registration number for their company.                                              |
| Type                                    | String             | The type of customer (e.g., "Customer" or  "Broker/3PL").                                                                                                |
| Status                                  | String             | The status of the customer. Either "Active" or "Inactive".                                                                                               |
| BillingAddress                          | Object             | The billing address of the customer.                                                                                                                     |
| BillingAddress.Street                   | String             | The street address of the billing location.                                                                                                              |
| BillingAddress.City                     | String             | The city of the billing address.                                                                                                                         |
| BillingAddress.State                    | String             | The state of the billing address.                                                                                                                        |
| BillingAddress.ZipCode                  | String             | The postal code of the billing address.                                                                                                                  |
| Email                                   | Array              | A list of email addresses associated with the customer.                                                                                                  |
| Phone                                   | Array              | A list of phone numbers associated with the customer.                                                                                                    |
| Fax                                     | String             | The fax number of the customer.                                                                                                                          |
| DateCreated                             | String (Date-Time) | The date and time when the customer was created.                                                                                                         |
| InvoicingInformation                    | Object             | The invoicing information for the customer.                                                                                                              |
| InvoicingInformation.Address            | Object             | The address used for invoicing.                                                                                                                          |
| InvoicingInformation.Address.Street     | String             | The street address for invoicing.                                                                                                                        |
| InvoicingInformation.Address.City       | String             | The city of the invoicing address.                                                                                                                       |
| InvoicingInformation.Address.State      | String             | The state of the invoicing address.                                                                                                                      |
| InvoicingInformation.Address.ZipCode    | String             | The postal code of the invoicing address.                                                                                                                |
| InvoicingInformation.EmailAddresses     | Array              | Email addresses used for invoicing.                                                                                                                      |
| InvoicingInformation.PhoneNumber        | String             | The phone number used for invoicing.                                                                                                                     |
| InvoicingInformation.InvoicingName      | String             | The name used for invoicing.                                                                                                                             |
| InvoicingInformation.InvoicingNameAlias | String             | The alias for the invoicing name.                                                                                                                        |
| InvoicingInformation.PaymentType        | String             | The payment type for invoicing.                                                                                                                          |
| InvoicingInformation.PaymentTermsInDays | Integer            | The payment terms, in days.                                                                                                                              |
| ExternalId                              | String             | The external identifier associated with the customer.                                                                                                    |
| Contacts                                | Array              | A list of contacts associated with the customer.                                                                                                         |
| SalesAgentId                            | String             | The identifier of the assigned sales agent.                                                                                                              |
| Notes                                   | Array              | A list of notes related to the customer.                                                                                                                 |
| References                              | Array              | An optional list of custom references associated with the customer. Only values whose reference definition includes the Public API surface are returned. |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Search customers
Source: https://docs.alvys.com/en/api/reference/customers/search-customers

POST /api/p/v{version}/customers/search
Search Alvys customers with paginated POST filters — name, status, billing city and state, credit terms, sales rep, and default rate agreements.

The endpoint for searching customers allows you to retrieve a paginated list of customer records based on specific filters and criteria. It requires specifying mandatory parameters like page number, page size, and statuses in the request body, ensuring precise and efficient querying. Optional filters such as date range provide additional control over the search results. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Body Parameters

The following parameters are available in the request body:

| Parameter              | Type               | Required | Description                                                                                                                                                                                                                                          |
| ---------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                   | Integer            | Yes      | The page number for pagination.                                                                                                                                                                                                                      |
| PageSize               | Integer            | Yes      | The number of records to retrieve per page.                                                                                                                                                                                                          |
| Statuses               | Array              | Yes      | List of customer statuses to filter by. Allowed values (case-sensitive): `"Active"`, `"Inactive"`, `"Disabled"`, `"On Hold"`, `"Do Not Use"`. Filtering by `"Inactive"` also returns customers whose stored status is `"On Hold"` or `"Do Not Use"`. |
| CreatedDateRange       | Object             | No       | The date range for filtering created customers.                                                                                                                                                                                                      |
| CreatedDateRange.Start | String (Date-Time) | No       | The start date for filtering.                                                                                                                                                                                                                        |
| CreatedDateRange.End   | String (Date-Time) | No       | The end date for filtering.                                                                                                                                                                                                                          |

***

#### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/customers/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 0,
  "PageSize": 100,
  "Statuses": ["Active"],
  "CreatedDateRange": {
    "Start": "2024-11-08T19:38:34.529Z",
    "End": "2024-11-08T19:38:34.529Z"
  }
}'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token. Adjust the `page`, `pageSize`, and date range as needed.

### Response Fields

The following fields are returned in the response:

| Field                                   | Type               | Description                                                                                                                                                                |
| --------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                                    | Integer            | The current page number of the response.                                                                                                                                   |
| PageSize                                | Integer            | The number of records returned per page.                                                                                                                                   |
| Total                                   | Integer            | The total number of customer records available.                                                                                                                            |
| Id                                      | String             | The unique identifier of the customer.                                                                                                                                     |
| Name                                    | String             | The name of the customer.                                                                                                                                                  |
| CompanyNumber                           | String             | The company number of the customer. A customer-provided reference or registration number for their company.                                                                |
| Type                                    | String             | The type of customer (e.g., "Customer" or "Broker/3PL").                                                                                                                   |
| Status                                  | String             | The status of the customer. Responses publish `"Active"` or `"Inactive"` only — stored values such as `"On Hold"`, `"Do Not Use"`, or `"Disabled"` appear as `"Inactive"`. |
| BillingAddress                          | Object             | The billing address of the customer.                                                                                                                                       |
| BillingAddress.Street                   | String             | The street address of the billing location.                                                                                                                                |
| BillingAddress.City                     | String             | The city of the billing address.                                                                                                                                           |
| BillingAddress.State                    | String             | The state of the billing address.                                                                                                                                          |
| BillingAddress.ZipCode                  | String             | The postal code of the billing address.                                                                                                                                    |
| Email                                   | Array              | A list of email addresses associated with the customer.                                                                                                                    |
| Phone                                   | Array              | A list of phone numbers associated with the customer.                                                                                                                      |
| Fax                                     | String             | The fax number of the customer.                                                                                                                                            |
| DateCreated                             | String (Date-Time) | The date and time when the customer was created.                                                                                                                           |
| InvoicingInformation                    | Object             | The invoicing information for the customer.                                                                                                                                |
| InvoicingInformation.Address            | Object             | The address used for invoicing.                                                                                                                                            |
| InvoicingInformation.Address.Street     | String             | The street address for invoicing.                                                                                                                                          |
| InvoicingInformation.Address.City       | String             | The city of the invoicing address.                                                                                                                                         |
| InvoicingInformation.Address.State      | String             | The state of the invoicing address.                                                                                                                                        |
| InvoicingInformation.Address.ZipCode    | String             | The postal code of the invoicing address.                                                                                                                                  |
| InvoicingInformation.EmailAddresses     | Array              | Email addresses used for invoicing.                                                                                                                                        |
| InvoicingInformation.PhoneNumber        | String             | The phone number used for invoicing.                                                                                                                                       |
| InvoicingInformation.InvoicingName      | String             | The name used for invoicing.                                                                                                                                               |
| InvoicingInformation.InvoicingNameAlias | String             | The alias for the invoicing name.                                                                                                                                          |
| InvoicingInformation.PaymentType        | String             | The payment type for invoicing.                                                                                                                                            |
| InvoicingInformation.PaymentTermsInDays | Integer            | The payment terms, in days.                                                                                                                                                |
| ExternalId                              | String             | The external identifier associated with the customer.                                                                                                                      |
| Contacts                                | Array              | A list of contacts associated with the customer.                                                                                                                           |
| SalesAgentId                            | String             | The identifier of the assigned sales agent.                                                                                                                                |
| Notes                                   | Array              | A list of notes related to the customer.                                                                                                                                   |
| Notes.id                                | String             | The unique identifier of the note.                                                                                                                                         |
| Notes.Description                       | String             | The description of the note.                                                                                                                                               |
| Notes.NoteType                          | String             | The type of the note.                                                                                                                                                      |
| Notes.Time                              | String (Date-Time) | The time the note was created.                                                                                                                                             |
| Notes.User                              | String             | The user who created the note.                                                                                                                                             |
| References                              | Array              | An optional list of custom references associated with the customer. Only values whose reference definition includes the Public API surface are returned.                   |

### Rate Limits

All endpoints are subject to rate limits to ensure stability and performance. For more information, refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Update customer
Source: https://docs.alvys.com/en/api/reference/customers/update-customer

PATCH /api/p/v{version}/customers/{id}
Partially update a customer record by ID in Alvys, changing only the supplied fields such as billing address, credit terms, contacts, or default rates.

The Update Customer endpoint applies a partial update (RFC 7396 JSON Merge Patch) to an existing business company. Send only the fields you want to change; omitted fields keep their persisted values. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

This endpoint uses optimistic concurrency. You must send the customer's current `ETag` in an `If-Match` header. The token is returned on the `ETag` response header of a GET, and in the body of a create/update response. If the token does not match the current record the request fails with `412 Precondition Failed`; refetch with GET to obtain a fresh value and retry.

***

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| version   | String | Yes      | The version of the API.                |
| id        | String | Yes      | The unique identifier of the customer. |

The following header is required:

| Header   | Required | Description                                       |
| -------- | -------- | ------------------------------------------------- |
| If-Match | Yes      | The current `ETag` of the customer being updated. |

***

### Request Body

All fields are optional. Provide only the fields you want to change.

| Field                  | Type            | Required | Description                                                                       |
| ---------------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
| Name                   | String          | No       | The customer name. Must be 200 characters or fewer. Cannot be blank when present. |
| Type                   | String          | No       | The customer type. One of "Customer" or "Broker/3PL".                             |
| CompanyNumber          | String          | No       | A reference/registration number for the company. Must be 32 characters or fewer.  |
| Status                 | String          | No       | The customer status. One of "Active" or "Inactive".                               |
| BillingAddress         | Object          | No       | The billing address of the customer.                                              |
| BillingAddress.Street  | String          | No       | The street line of the billing address.                                           |
| BillingAddress.City    | String          | No       | The city of the billing address.                                                  |
| BillingAddress.State   | String          | No       | The state of the billing address.                                                 |
| BillingAddress.Zip     | String          | No       | The postal code of the billing address.                                           |
| BillingAddress.Country | String          | No       | ISO country code of the billing address. Defaults to "US".                        |
| Email                  | Array of String | No       | A list of email addresses associated with the customer.                           |
| Phone                  | Array of String | No       | A list of phone numbers associated with the customer.                             |
| Fax                    | String          | No       | The fax number of the customer.                                                   |
| ExternalId             | String          | No       | An external reference identifier. Must be 100 characters or fewer.                |

***

### Example CURL Request

```bash theme={null}
curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1/customers/01fec4d332ed49ff96595c8d4434ea96' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "00000000-0000-0000-0000-000000000001"' \
--data-raw '{
  "Status": "Inactive"
}'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token and `If-Match` with the customer's current `ETag`.

***

### Response Fields

A successful request returns the updated customer. The new optimistic-concurrency token is returned on the `ETag` response header and in the `ETag` body field.

| Field                  | Type               | Description                                             |
| ---------------------- | ------------------ | ------------------------------------------------------- |
| Id                     | String             | The unique identifier of the customer.                  |
| ETag                   | String             | The optimistic-concurrency token after the update.      |
| Name                   | String             | The name of the customer.                               |
| CompanyNumber          | String             | The company number of the customer.                     |
| Type                   | String             | The type of customer ("Customer" or "Broker/3PL").      |
| Status                 | String             | The raw persisted status of the customer.               |
| BillingAddress         | Object             | The billing address of the customer.                    |
| BillingAddress.Street  | String             | The street line of the billing address.                 |
| BillingAddress.City    | String             | The city of the billing address.                        |
| BillingAddress.State   | String             | The state of the billing address.                       |
| BillingAddress.ZipCode | String             | The postal code of the billing address.                 |
| Email                  | Array              | A list of email addresses associated with the customer. |
| Phone                  | Array              | A list of phone numbers associated with the customer.   |
| Fax                    | String             | The fax number of the customer.                         |
| DateCreated            | String (Date-Time) | The date and time when the customer was created.        |
| DateModified           | String (Date-Time) | The date and time of this update.                       |
| InvoicingInformation   | Object             | The invoicing information for the customer.             |
| ExternalId             | String             | The external identifier associated with the customer.   |

***

### Example Response

**200 OK**

```json theme={null}
{
  "Id": "01fec4d332ed49ff96595c8d4434ea96",
  "ETag": "\"00000000-0000-0000-0000-000000000002\"",
  "Name": "Acme Logistics",
  "CompanyNumber": "ACME-001",
  "Type": "Broker/3PL",
  "Status": "Inactive",
  "BillingAddress": {
    "Street": "123 Main St",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "75201"
  },
  "Email": ["billing@acme.example"],
  "Phone": ["+1-214-555-0100"],
  "Fax": null,
  "DateCreated": "2025-09-08T19:38:34.529Z",
  "DateModified": "2025-09-09T11:02:10.118Z",
  "InvoicingInformation": null,
  "ExternalId": "EXT-ACME-001"
}
```

***

### Status Codes

| Status | Meaning                                                                                     |
| ------ | ------------------------------------------------------------------------------------------- |
| 200    | The customer was updated.                                                                   |
| 400    | The request body failed validation.                                                         |
| 401    | The request was not authenticated.                                                          |
| 403    | The caller lacks permission to update customers.                                            |
| 404    | No customer with the given `id` exists.                                                     |
| 409    | The update would collide with another customer's unique values.                             |
| 412    | The supplied `If-Match` token did not match the current record. Refetch with GET and retry. |
| 428    | The `If-Match` header is required but was not provided.                                     |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# Get an access token
Source: https://docs.alvys.com/en/api/reference/token

POST /oauth/token
Exchange your client credentials for an access token using the OAuth 2.0 Client Credentials flow.

This endpoint lives on the Alvys authorization server (`https://auth.alvys.com`), not on the API host — the playground targets it directly. It takes no bearer token of its own; the credentials in the body *are* the authentication.

Accepts either `application/json` or `application/x-www-form-urlencoded`. Both return the same token and enforce scopes identically.

Create the Client ID and Secret in the Alvys Admin Portal under **Admin → API Access**. See [Authentication](/reference/authentication) for the full walkthrough and the scope catalog.

Use this page to get a token, then paste it into the **Authorization** field on any other endpoint in this reference to send authenticated requests.

<Info>
  This endpoint is on the Alvys authorization server, `https://auth.alvys.com` — not the API host. It is the one endpoint that takes no bearer token: the `client_id` and `client_secret` in the body *are* the authentication.
</Info>

Create your Client ID and Secret in the Alvys Admin Portal under **Admin → API Access**. [Authentication](/en/api/reference/authentication) covers the setup walkthrough, the scope catalog, and the migration off the legacy `/api/authentication/{tenant_id}/token` flow.

<Warning>
  Your Client Secret is a credential. Anything you type into the playground is sent to the live production authorization server, so use credentials you are willing to exercise — and never paste a secret into a shared screen or recording.
</Warning>

### Using the token

The response's `access_token` goes on every Public API request:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Tokens are valid for the `expires_in` window returned with them. Cache the token for that period rather than requesting a new one per call — the token endpoint is rate limited and will return `429` if you request one per API call.

The `scope` claim on the returned token lists what it may do, and the Public API enforces those scopes on every request. A token always carries every scope granted to your client application; see [Available Scopes](/en/api/reference/authentication#available-scopes) for the full list.


# Apex Capital Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/apex-capital-factoring-integration

This guide will help you integrate Apex Capital with Alvys. Follow the steps below to set up your NOA and configure the Apex integration.

<Note>
  Apex Capital connects to Alvys via OAuth (Apex Connect API) to automate invoice submission and report processing for factoring clients. Also known as Apex Connect, Apex Capital factoring, invoice factoring.
</Note>

## What This Integration Does

Alvys connects to Apex Capital using the Apex Connect API with OAuth authentication. When a factoring batch is submitted in Alvys, the integration sends invoice data directly to Apex Capital and automatically uploads the invoice document for each load in the batch to Apex Capital. Users then log in to the Apex Capital portal to download Purchase Reports and Payment Reports as CSV files, which are uploaded back into Alvys to update load records.

The integration supports two report types: Purchase Reports (confirm which invoices Apex Capital has purchased and at what advance amount) and Payment Reports (record payments received from Apex Capital against factored invoices).

Status updates in Alvys depend on report uploads; there is no automated nightly sync.

## Prerequisites

* Active account with Apex Capital
* Notice of Assignment text provided by Apex Capital
* Admin, Partner Admin, or Support role to access Management > Integrations and complete the OAuth setup
* **"Billing"** permission to submit batches and upload Purchase Reports and Payment Reports

## Connect / Authenticate

Setup requires two parts: configuring your Notice of Assignment in Company Profile, then activating the Apex Capital integration in Management > Integrations.

### Part 1: Configure Your Notice of Assignment

1. Navigate to Management > Company Profile.
2. Select the subsidiary that will use the Apex Capital integration. In the Document Configuration section, click the blue **(+)** button. The Manage Important Info window opens.
3. In the drop-down menu, select **Notice of Assignment**. Copy and paste the Notice of Assignment text provided by Apex Capital into the text box.
4. Click the blue **Save** button.

<Note>
  <img alt="Document Configuration section of Company Profile with the Manage Important Info window for adding the Notice of Assignment" />

  *Document Configuration section of Company Profile with the Manage Important Info window for adding the Notice of Assignment*
</Note>

### Part 2: Configure the Apex Capital Integration

1. Navigate to Management > Integrations.
2. Expand the **Factoring** section. Click the “**Inactive**” button next to **Apex Capital**.

<Note>
  <img alt="Integrations page with the Factoring section expanded and the Inactive button next to Apex Capital" />

  \*Integrations page with the Factoring section expanded and the Inactive button next to Apex Capital \*
</Note>

1. Click the blue **Save** button. A message appears: "You will now be redirected to Apex to login in order to complete the integration."
2. Sign in using your Apex Capital credentials. The integration is active immediately after login.

Note: To configure additional subsidiaries, repeat Part 1 and Part 2 for each subsidiary.

## Field & Data Mapping

When a batch is submitted, Alvys sends the following invoice data to Apex Capital: load number, debtor, invoice amount, and advance amount. Alvys automatically uploads the invoice document for each load to Apex at the time of batch submission.

If a broker has no existing record in Apex Capital, Alvys automatically registers them using the MC number or company name.

<Warning>
  ⚠️ Waypoint stops are not supported for Apex Capital batches. Loads that include waypoint stops cannot be included in a batch.
</Warning>

**Purchase Report CSV columns:** Buy, Inv, Debtor, Amount, Advance, InvDate

**Payment Report CSV columns:** Check, PostDate, Debtor, Inv., Amount, Type

## Sync Behavior

Alvys submits invoice batches to Apex Capital through the API. Purchase Report and Payment Report data flows back into Alvys through manual CSV uploads from the Apex Capital portal. There is no automated nightly sync; load status updates in Alvys depend entirely on report uploads.

## Upload Your Purchase Report

1. Log in to the Apex Capital portal and navigate to the Purchase Schedule Report page at: [https://amp.apexcapitalcorp.com/m3clients/InvoiceQuery.do](https://amp.apexcapitalcorp.com/m3clients/InvoiceQuery.do)
2. Find the schedule number for your batch. To locate it, navigate to **Reports > Factoring** in Alvys and find the submitted batch.
   <Note>
     <img alt="Alvys Reports > Factoring page showing the submitted batch and its schedule number" />

     \*Alvys Reports > Factoring page showing the submitted batch and its schedule number \*
   </Note>
   ys Reports > Factoring page showing the submitted batch and its schedule number \*
3. Enter that number in the Schedule Number field on the Apex Capital portal, select .csv as the export format and click Submit
   <img alt="Apex Capital portal Purchase Schedule Report query with the Schedule Number field" />
   *Apex Capital portal Purchase Schedule Report query with the Schedule Number field*
4. Select **.csv** as the export format. Click **Submit**. Download the file to your device.
5. In Alvys, navigate to **Reports > Factoring**. Select the batch. Click the blue **Upload Purchase Report** button located in the **bottom right corner** of the Factoring Reports page.
   <Note>
     <img alt="Alvys Factoring Reports page with the blue Upload Purchase Report button in the bottom right corner" />

     \*Alvys Factoring Reports page with the blue Upload Purchase Report button in the bottom right corner \*
   </Note>
   \*Alvys Factoring Reports page with the blue Upload Purchase Report button in the bottom right corner \*
6. Drag and drop the CSV file into the upload area, or click to select it from your device.
   <Note>
     <img alt="File drag-and-drop upload area on the Upload Purchase Report dialog" />

     \*File drag-and-drop upload area on the Upload Purchase Report dialog \*
   </Note>
   \*File drag-and-drop upload area on the Upload Purchase Report dialog \*
7. Click **Upload**.

<Note>
  <img alt="Upload button on the Purchase Report upload dialog" />

  *Upload button on the Purchase Report upload dialog*
</Note>

## Upload Your Payment Report

1. Log in to the Apex Capital portal and navigate to the Payment Report page at: [https://amp.apexcapitalcorp.com/m3clients/PaymentQuery.do](https://amp.apexcapitalcorp.com/m3clients/PaymentQuery.do)
2. Enter the payment period. Select **.csv** as the report type. Click **Submit**. Download the file to your device.
   <Note>
     <img alt="Apex Capital portal Payment Report query showing the payment period and .csv report type" />

     *Apex Capital portal Payment Report query showing the payment period and .csv report type*
   </Note>
   *Apex Capital portal Payment Report query showing the payment period and .csv report type*
3. In Alvys, navigate to **Reports > Factoring**. Select the batch. Click the **Upload Report** button.
   <Note>
     <img alt="Alvys Factoring Reports page showing the Upload Report button" />

     *Alvys Factoring Reports page showing the Upload Report button*
   </Note>
   *Alvys Factoring Reports page showing the Upload Report button*
4. Drag and drop the CSV file into the upload area, or click to select it from your device.
   <Note>
     <img alt="File drag-and-drop upload area on the Upload Report dialog" />

     *File drag-and-drop upload area on the Upload Report dialog*
   </Note>
   *File drag-and-drop upload area on the Upload Report dialog*
5. Click **Upload**.
   <Note>
     <img alt="Upload button on the Payment Report upload dialog" />

     \*Upload button on the Payment Report upload dialog \*
   </Note>
   \*Upload button on the Payment Report upload dialog \*
6. Do not close this page until the report has finished processing. Depending on file size, this can take from a few seconds to a few minutes.

<Note>
  <img alt="Factoring Reports page after payment report processing completes, showing updated load records" />

  *Factoring Reports page after payment report processing completes, showing updated load records*
</Note>

## Verify It's Working

After submitting a batch, log in to the Apex Capital portal and confirm the batch appears in the Purchase Schedule Report at [https://amp.apexcapitalcorp.com/m3clients/InvoiceQuery.do](https://amp.apexcapitalcorp.com/m3clients/InvoiceQuery.do).

After uploading a Purchase Report, verify in Reports > Factoring in Alvys that the invoice amounts and advance amounts on the batch match the values in the uploaded file.

After uploading a Payment Report, verify that the relevant load records in Alvys reflect updated payment status as expected.

## Troubleshooting

### Batch submission fails

1. Confirm the broker record has either an MC number or a registered company name. Alvys looks up the broker in Apex Capital by MC number first, then by company name. If neither is present on the broker record, the batch cannot proceed.
2. Confirm the load does not include waypoint stops. Waypoint stops are not supported for Apex Capital batches and will prevent submission.
3. Confirm the subsidiary is connected to Apex Capital with valid OAuth credentials. Navigate to Management > Integrations, expand the Factoring section, and verify that Apex Capital shows an active connection. If the connection is not active, complete the OAuth login described in Connect / Authenticate above.

### Upload Purchase Report or Upload Report button is not visible

1. Confirm your account has the **"Billing"** permission. Without this permission, the upload buttons are not displayed.
2. Navigate to Reports > Factoring and confirm the batch appears in the list. If the batch is not visible, confirm it was submitted successfully in Accounting > Factoring Upload.
3. If the batch was submitted successfully but does not appear in Reports > Factoring, contact Alvys support.

### Integration does not appear as active after setup

1. Confirm that you completed the redirect to Apex Capital and signed in with your Apex Capital credentials. The integration is not active until the OAuth login step is completed. Return to Management > Integrations, click the pencil icon next to Apex Capital, and repeat the login step.
2. Contact Alvys support if the integration still does not appear as active after completing the login step.

## Limits / Unsupported

Waypoint stops are not supported. Loads that include waypoint stops cannot be included in an Apex Capital factoring batch.

Purchase Report and Payment Report data is not synced automatically; both require manual CSV download from the Apex Capital portal and upload into Alvys.

The integration must be configured separately for each subsidiary that will use Apex Capital factoring.

## FAQs

**Q: What is a Notice of Assignment?**

**A:** A Notice of Assignment is a document that informs your customers that their receivables have been assigned to a factoring company. Apex Capital provides the text, which you copy into Management > Company Profile during setup.

**Q: How long does it take for the integration to start working after setup?**

**A:** The integration is active immediately after you sign in with your Apex Capital credentials during the OAuth step.

**Q: Can I use the Apex Capital integration with multiple subsidiaries?**

**A:** Yes. Repeat the full setup in both Management > Company Profile and Management > Integrations for each subsidiary that will use the integration.

**Q: What happens if a broker is not already registered in Apex Capital?**

**A:** Alvys automatically registers the broker in Apex Capital using the MC number on the broker record. If no MC number is present, Alvys uses the company name instead.

**Q: Where do I find the schedule number for a submitted batch?**

**A:** Navigate to Reports > Factoring in Alvys. The schedule number is displayed on the batch record.


# BestPass Toll Integration
Source: https://docs.alvys.com/en/help/integrations/bestpass-toll-integration

Connect BestPass to Alvys to import toll transactions nightly through the new REST API and link each transponder to the correct truck in your fleet.

<Note>
  Automatically import BestPass toll transactions into Alvys nightly by connecting your BestPass account and linking each transponder to its corresponding truck.
</Note>

## Overview

BestPass is a toll tracking integration (toll transponder sync, toll transaction import) that automatically imports toll transactions for your fleet assets into Alvys nightly. BestPass migrated from a legacy SOAP API to a new REST API, labeled **"BestPass new"** in Alvys. This article covers the current **"BestPass new"** version only.

The integration is one-way: data flows from BestPass into Alvys only. Setup requires two actions: adding an Alvys contact to your BestPass account, and linking each BestPass transponder to its corresponding truck in Alvys.

## Prerequisites

**Before you begin:**

* You must have an active BestPass account with admin access to add contacts.
* You must have your BestPass Account ID available.
* You must have access to the Alvys Management > Integrations page.

## How to connect

1. Log in to your BestPass account portal.
2. Navigate to the Contacts section and add [integrations@alvys.com](mailto:integrations@alvys.com) as a contact. BestPass requires this contact before Alvys can authenticate and retrieve your toll data.
3. In Alvys, click your username in the upper left corner and select **Integrations** (or navigate to **Management** and select the **Integrations** tab).
4. Go to the **Tolls** section and click the pencil icon next to **BestPass new**.

<Note>
  <img alt="This image shows the Alvys Integrations page with the Tolls section expanded and the BestPass new pencil icon visible." />

  *This image shows the Alvys Integrations page with the Tolls section expanded and the BestPass new pencil icon visible.*
</Note>

1. Enter your **BestPass Account ID** in the integration settings field.
2. Select which subsidiaries you want this integration to apply to.
3. Click **Save** at the bottom.

   **For toll transactions to be attributed to the correct truck, each BestPass transponder must be linked to its corresponding truck in Alvys:**
4. From the blue toolbar on the left, navigate to **Assets** and select **Trucks**.
5. Find and select the truck that corresponds to the transponder you want to add.
6. Scroll down to the **Pass Details** section.
7. Select whether or not to deduct tolls from driver pay.
8. Choose **BestPass new** in the **Issued By** field.
9. Enter the transponder ID in the **Pass Number** field.
10. Click **Add Pass**.

<Note>
  <img alt="The truck profile in Alvys with the Pass Details section expanded, showing the Issued By field set to BestPass new and a Pass Number field" />

  *The truck profile in Alvys with the Pass Details section expanded, showing the Issued By field set to BestPass new and a Pass Number field*
</Note>

Repeat the transponder steps for all trucks that use BestPass transponders.

<Info>
  💡 **Tip:** Transponder IDs are typically associated with trucks because the transponder device is physically mounted in the truck. · You can add pass details to other asset types if your setup requires it.
</Info>

## What syncs

* Toll data updates automatically each night via the BestPass REST API.
* New toll transactions appear in Alvys the day after they occur.
* There is no manual upload step once the integration is configured and transponder IDs are added.
* The integration is one-way: data flows from BestPass into Alvys only.

### To confirm the sync is working:

1. From the Alvys toolbar, select **Reports** and navigate to the **Toll Report**.
2. Enter at least one search parameter (such as a date range or truck) and click **Search**.
3. Confirm that toll transactions appear for your assets.

<Note>
  <img alt="The Alvys Toll Report page with search criteria entered and toll transactions displayed in the results" />

  *The Alvys Toll Report page with search criteria entered and toll transactions displayed in the results*
</Note>

<Warning>
  ⚠️ Toll data imports once per night. **·** Real-time or on-demand imports are not supported. **·** Transactions from today will not appear until the following day.
</Warning>

## Troubleshooting

### Toll transactions not appearing in the Toll Report

1. Confirm that [integrations@alvys.com](mailto:integrations@alvys.com) has been added as a contact in your BestPass account. If this step was missed, the integration cannot authenticate with BestPass.
2. Verify that the BestPass Account ID entered in Alvys is correct. Go to Management > Integrations > Tolls > BestPass new and confirm the Account ID.
3. Verify that transponder IDs are correctly entered on each truck's Pass Details section in Alvys. The Pass Number must match the transponder ID exactly as it appears in BestPass.
4. Check the date range on the Toll Report. Transactions import nightly, so transactions from today will not appear until the following day.
5. If none of the above resolves the issue, contact Alvys support.

### Integration shows BestPass but not BestPass new

* The original BestPass integration used a legacy SOAP API that is being phased out. Locate **BestPass new** in the Tolls section of Integrations. If you previously set up the legacy integration, complete the new setup steps in this article to migrate to the REST API version.

## FAQs

**Q: What is the difference between BestPass and BestPass new?**

**A:** BestPass new uses the updated REST API, which is the current supported version. The legacy SOAP API integration (labeled simply "BestPass") is being phased out. New setups must use BestPass new.

**Q: Why do I need to add \[**[integrations@alvys.com](mailto:integrations@alvys.com)**] to my BestPass account?**

**A:** This email address allows Alvys to authenticate and access your toll data through the REST API. It is required for the integration to function.

**Q: How often does toll data update in Alvys?**

**A:** The integration automatically updates toll data nightly via API. New transactions appear the following day.

**Q: Do I need to add transponder IDs for trailers?**

**A:** Transponder IDs are typically associated with trucks because that is where the transponder device is mounted. However, you can add pass details to any asset type in Alvys if your setup requires it.

**Q: Can I use BestPass for multiple subsidiaries?**

**A:** Yes. During setup, you can select which subsidiaries the integration applies to before clicking Save.


# Capital Depot Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/capital-depot-factoring-integration

Use the manual Capital Depot factoring workflow in Alvys: generate a batch invoice file, submit it to Capital Depot, then upload purchase and payment reports.

<img alt="Company Profile page showing subsidiary selection" />

*Company Profile page showing subsidiary selection*

<Note>
  Capital Depot is a manual, non-API factoring integration. Alvys generates a batch invoice file that you download and send to Capital Depot manually. Capital Depot returns Purchase and Payment reports, which you upload into Alvys to update load statuses.
</Note>

## What This Integration Does

Capital Depot is a manual, non-API factoring integration (also called Capital Depot factoring or manual invoice factoring). Alvys generates a batch invoice file that you download and send to Capital Depot manually. Capital Depot then provides Purchase and Payment reports, which you upload into Alvys to update load statuses. No data transfers automatically between Alvys and Capital Depot. Synonyms: invoice factoring, accounts receivable financing.

## Prerequisites

* Active account with Capital Depot
* Notice of Assignment text provided by Capital Depot
* Admin, Partner Admin, or Support access to configure the Notice of Assignment
* **"Billing"** permission to submit batches and upload reports

## Connect / Authenticate

### Configure Your Notice of Assignment

1. Navigate to Management > Company Profile. Select the subsidiary that will use the Capital Depot integration.
2. In the **Document Configuration** section, click the blue **(+)** button. The Manage Important Info window opens.

   <img alt="Document Configuration section showing the blue (+) button" />

   *Document Configuration section showing the blue (+) button*
3. In the drop-down menu, select **Notice of Assignment**. Copy and paste the Notice of Assignment text provided by Capital Depot.
4. Click the blue **Save** button.

## Field & Data Mapping

Alvys generates a batch file containing invoice data for the selected loads. You download this file from Alvys and send it to Capital Depot. Capital Depot provides CSV templates for the Purchase Report and Payment Report. The templates are available as downloads from the Alvys help article for Capital Depot.

**Purchase Report template file:** Purchase\_Report.csv

**Payment Report template file:** Payments\_Report.csv

## Sync Behavior

All data exchange with Capital Depot is manual. Load statuses update as follows:

* After batch submission in Alvys: loads move to **Invoiced**
* After Purchase Report upload: loads move to **Financed**
* After Payment Report upload: loads move to **Completed**

## Submit and Download a Batch

1. Navigate to **Accounting > Factoring Upload**. All loads must have a **Queued** status with invoicing method set to factoring.
2. Select the correct subsidiary.
3. Select the loads to include in the batch.

   <img alt="Load selection screen on the Factoring Upload page" />

   *Load selection screen on the Factoring Upload page*
4. Click **Submit Batch**. Wait until the submission completes. Do not close this page or navigate away during submission; doing so may disrupt the process. Loads automatically move to **Invoiced** status when submission is complete.
5. Navigate to **Reports > Factoring**. Find the submitted batch and click the download button to download the batch file.

   <img alt="Reports > Factoring page showing the submitted batch with the download button" />

   *Reports > Factoring page showing the submitted batch with the download button*
6. Send the downloaded batch file to Capital Depot.

## Upload Your Purchase Report

1. Obtain the completed Purchase Report from Capital Depot. Complete the **Purchase\_Report.csv** template using the data provided by Capital Depot. Ensure the report includes all invoices in the batch.
2. Navigate to **Reports > Factoring**. Select the batch.
3. Click the **Upload Purchase Report** button. Upload the completed file.

   <img alt="Reports > Factoring page with the Upload Purchase Report button visible" />

   *Reports > Factoring page with the Upload Purchase Report button visible*
4. After upload, loads move to **Financed** status. This indicates that Capital Depot has received payment for the invoices.

## Upload Your Payment Report

1. Obtain the completed Payment Report from Capital Depot. Complete the **Payments\_Report.csv** template using the data provided by Capital Depot.
2. Navigate to **Reports > Factoring**. Select the batch.
3. Click the **Upload Payment Report** button. Upload the completed file.

   <img alt="Reports > Factoring page with the Upload Payment Report button visible" />

   *Reports > Factoring page with the Upload Payment Report button visible*
4. After upload, loads move to **Completed** status. Customer payment is applied to the load.

## Verify It's Working

After submitting a batch, confirm that the selected loads have moved from **Queued** to **Invoiced** status in Alvys. After uploading the Purchase Report, confirm loads show **Financed**. After uploading the Payment Report, confirm loads show **Completed**.

## Troubleshooting

### Loads did not move to Invoiced after batch submission

1. Confirm you did not navigate away from Accounting > Factoring Upload before the submission completed. If the loads still show **Queued**, return to Accounting > Factoring Upload and resubmit the batch.
2. Confirm the loads had **Queued** status and invoicing method set to factoring before submission. Only loads meeting both conditions appear in the batch list.
3. Contact Alvys support if loads remain in **Queued** after resubmitting.

### Upload Purchase Report or Upload Payment Report button is not visible

1. Confirm you have the **"Billing"** permission in Alvys.
2. Navigate to **Reports > Factoring** and confirm the batch appears in the list. If the batch is not visible, confirm the batch was submitted from **Accounting > Factoring Upload**.
3. Contact Alvys support if the batch was submitted but does not appear in **Reports > Factoring**.

## Limits / Unsupported

Capital Depot does not support automated data transfer. All batch submissions and report uploads require manual action. There is no API connection between Alvys and Capital Depot.

## FAQs

**Q: Where do I get the CSV templates for the Purchase and Payment reports?**

**A:** Alvys provides both templates (Purchase\_Report.csv and Payments\_Report.csv). Download them from the Alvys help article for Capital Depot.

**Q: What happens to load statuses after each step?**

**A:** Loads move to **Invoiced** after you submit the batch, to **Financed** after you upload the Purchase Report, and to **Completed** after you upload the Payment Report.

**Q: Do I need to send the batch file to Capital Depot, or does Alvys do that automatically?**

**A:** You must download the batch file from **Reports > Factoring** and send it to Capital Depot manually. Capital Depot does not have a direct API connection to Alvys.

<img alt="Load status progression showing Queued, Invoiced, Financed, and Completed statuses" />

*Load status progression showing Queued, Invoiced, Financed, and Completed statuses*


# Comdata Fuel & Checks Integration
Source: https://docs.alvys.com/en/help/integrations/comdata-fuel-checks-integration

Connect Comdata to Alvys to import fuel card transactions from FTP and issue e-checks to drivers for advances, lumpers, and repairs from Alvys.

<Note>
  Set up the Comdata fuel and checks integration to import fuel transactions and issue e-checks to drivers directly within Alvys.
</Note>

## Overview

The Comdata integration connects Alvys to the Comdata fuel card and check issuance platform (fuel transaction import, e-check issuance). Once connected, Alvys can import fuel transactions from Comdata and let you issue e-checks to drivers directly within Alvys.

The integration is one-way for fuel: data flows from Comdata into Alvys. Check issuance sends a request from Alvys to Comdata. Setup has two phases: requesting credentials from Comdata, and entering those credentials in Alvys.

## Prerequisites

Before you begin:

* Your subsidiaries must be set up in Alvys before configuring the integration.
* You must contact Comdata to obtain integration credentials. Alvys cannot generate these credentials.
* If you also need fuel transactions imported (not just check issuance), you must specifically request FTP fuel server credentials from Comdata in addition to the web services credentials.

## How to connect

1. Email your Comdata representative or **[regionalfleettrr@comdata.com](mailto:regionalfleettrr@comdata.com)** to request credentials for connecting to Comdata web services. In your email, specify that you need credentials to connect to the Comdata web services, and (if you also need fuel transactions imported) that you also need credentials for the Comdata fuel FTP server.
2. Wait to receive your files from Comdata. You will receive an Excel file containing web services credentials, and a separate file containing FTP fuel access credentials (only if fuel import was requested).
3. In Alvys, navigate to **Management** and click the blue **Integrate** button.
4. In the pop-up window, click the **Integration Type** drop-down menu and select **Comdata**.
5. Enter the web services credentials (required for all setups) using the mapping below:

   * **Customer ID** (Alvys) = Customer ID (Comdata), a 5-digit numeric value
   * **Account Code** (Alvys) = Account Code (Comdata)
   * **Sign on Name** (Alvys) = Host/Network SignOn Name (Comdata)
   * **Security Info** (Alvys) = Security Info (Comdata)
   * **Username** (Alvys) = WSS SignOn Name (Comdata)
   * **Password** (Alvys) = WSS SignOn Password (Comdata)
   * **Secondary Password** (Alvys) = Host/Network SignOn Password (Comdata)
6. If fuel import is included, also enter the FTP fuel credentials:

   * **Fuel Username** (Alvys) = FTP User Name (Comdata)
   * **Fuel Password** (Alvys) = FTP Password (Comdata)
   * **File Prefix** (Alvys) = as provided by Comdata
7. Select which subsidiaries this integration should apply to.
8. Click **Save**.

   If you are using the fuel transaction import feature, fuel transactions are matched to drivers using fuel card numbers. Each driver who uses a Comdata fuel card must have their card number added to their driver profile in Alvys:
9. Navigate to **Assets** and select **Drivers**.
10. Double-click a driver from the list to open their profile.
11. Find the **Fuel Card Numbers** field near the driver's name and click the plus sign.
12. In the pop-up window, enter the fuel card number and select **Comdata** as the fuel card provider.
13. Check the applicable boxes if you want to deduct fuel from driver pay or if fuel is discounted.
14. Click **Save**.

Repeat the fuel card steps for all drivers who have Comdata fuel cards.

<Info>
  💡 For check issuance (e-checks), no additional driver-level mapping is required. · Checks are issued on demand from within Alvys once the integration is connected.
</Info>

## What syncs

* Fuel transactions are imported automatically from Comdata via FTP on a scheduled basis once FTP credentials are configured.
* Check issuance is performed on demand from within Alvys.
* The integration is one-way for fuel: data flows from Comdata into Alvys. Check issuance sends a request from Alvys to Comdata.

  To confirm the integration is working:

1. Navigate to **Reports** and select **Fuel Report**.
2. Set a date range that includes recent dates when Comdata fuel transactions occurred.
3. Confirm that transactions appear and are linked to the correct drivers.

For check issuance, navigate to the driver's pay section and attempt to issue a check to confirm the connection is working.

## Troubleshooting

### Fuel transactions not appearing in the Fuel Report

1. Confirm the FTP fuel credentials are entered correctly in the Comdata integration settings. Fuel import requires the FTP credentials in addition to web services credentials.
2. Confirm that fuel card numbers are added to each driver's profile in Alvys and that Comdata is selected as the provider.
3. Verify that the date range on the Fuel Report matches the dates the transactions occurred.
4. If none of the above resolves the issue, contact Alvys support.

### Credentials rejected during setup

The credentials provided by Comdata are case-sensitive. Confirm you are entering each value exactly as it appears in the files Comdata sent. If credentials continue to be rejected, contact Comdata directly to verify the credentials are correct and active.

### Check issuance not working after setup

Confirm that the web services credentials (not just the FTP credentials) are entered correctly in the integration settings. Check issuance uses the web services connection, not the FTP connection.

## FAQs

**Q: How long does it take to receive credentials from Comdata?**

**A:** Response times vary, but you should typically receive your credentials within a few business days of contacting Comdata.

**Q: What if I only need check functionality and not fuel imports?**

**A:** When emailing Comdata, simply do not request the fuel FTP server credentials. You will only need the web services credentials, and you do not need to fill in the Fuel Username, Fuel Password, or File Prefix fields in Alvys.

**Q: Can I use the same Comdata integration for multiple subsidiaries?**

**A:** Yes. During setup you can select which subsidiaries should use the Comdata integration.

**Q: Do I need to add fuel card numbers before the integration starts working?**

**A:** For fuel transactions to be attributed to the correct drivers, yes. The system matches imported transactions to drivers based on fuel card numbers. Set these up before the first import runs to avoid unmatched transactions.


# Compass Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/compass-fuel-integration

Import Compass Payment Services fuel card transactions into Alvys through a manual CSV upload to apply driver fuel deductions and update the Fuel Report.

<Note>
  Compass Payment Services connects to Alvys through a manual CSV upload process. Download fuel card transaction data from the Compass portal and upload it into Alvys to apply fuel deductions and maintain fuel records. Also referred to as Compass fuel card import.
</Note>

## Overview

The Compass fuel integration (Compass Payment Services, fuel card import, manual CSV upload) connects Compass fuel card data with Alvys. This is a manual import process: you download a CSV file from the Compass portal and upload it into Alvys. Alvys then matches each transaction to the correct driver using the fuel card number stored on their profile.

Use this integration to track fuel expenses, apply fuel deductions to driver pay, and maintain accurate fuel records in your Fuel Report. The integration is one-way: data flows from Compass into Alvys only.

## Prerequisites

Before setting up this integration, confirm the following:

* You have access in Alvys to manage Integrations ([https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)).
* You have login credentials for the Compass Payment Services portal at [cps.compasspaymentservices.com](http://cps.compasspaymentservices.com/).
* Your subsidiaries are already configured in Alvys.

## How to connect

1. In Alvys, select your Username in the bottom-left corner and click the integrations page ([https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)).
2. In the integrations list, expand the **Fuel** category.
3. Click the gray “Inactive” button next to **Compass**.
4. Confirm the correct subsidiaries are selected, then click **Save**.

<Info>
  💡 No API credentials are required for the Compass integration. Enabling the integration registers Compass as an available upload type in the [Fuel Report.](https://app.alvys.com/assets/fuel)
</Info>

**For Alvys to attribute transactions to the correct driver, each driver must have their Compass fuel card number on their profile:**

1. From the Alvys toolbar, go to **Assets** and select **Drivers**.
2. Find and open a driver profile.
3. In the first section, click the plus sign next to **Fuel Card Numbers**.

<Note>
  <img alt="This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted" />

  *This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted*
</Note>

1. Enter the fuel card number for this driver.
2. Select **Compass** in the provider dropdown.
3. Set the deduct fuel and discounted fuel checkboxes if applicable.
4. Click **Save**.
5. Repeat the fuel card steps for each driver who has a Compass fuel card.

<Note>
  <img alt="This image shows the fuel card number entry popup with the Compass provider selected and the deduct fuel checkbox visible." />

  *This image shows the fuel card number entry popup with the Compass provider selected and the deduct fuel checkbox visible.*
</Note>

### To download fuel transactions from Compass:

* Log in to the Compass portal at [cps.compasspaymentservices.com](http://cps.compasspaymentservices.com/).
* Open the **Dashboard**.
* In the Transactions section, select **Export CSV**.

  <img alt="This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section." />

  *This image shows the Compass portal Dashboard with the Export CSV option highlighted in the Transactions section.*
* Select your date range and click **Export**.
* Save the CSV file to your device.

<Note>
  <img alt="This image shows the date range selector and Export button in the Compass portal." />

  *This image shows the date range selector and Export button in the Compass portal.*
</Note>

**To upload the file to Alvys (confirm each driver's Compass fuel card number is saved first):**

From the Alvys toolbar, go to \*\*Assets \*\*and select **Fuel Report**.

<Note>
  <img alt="This image shows the Fuel Report page with the Transaction File Upload button visible." />

  *This image shows the Fuel Report page with the Transaction File Upload button visible.*
</Note>

Click the vertical ellipsis icon **(⋮)** next to the “**Add** \*\*Transaction” \*\*button.

<Note>
  <img alt="Image showing ellipsis icon next to “Add Transaction” button" />

  *Image showing ellipsis icon next to “Add Transaction” button*
</Note>

Select the “**Import Report**” option.

<Note>
  <img alt="Image showing Import Report option" />

  *Image showing Import Report option*
</Note>

**Select Compass** as the integration type.

Upload the CSV file you downloaded from the Compass portal.

Click the “Save” button

<Note>
  <img alt="Image showing ”Upload Fuel Report” form with Integration type and Add report input fields." />

  *Image showing ”Upload Fuel Report” form with Integration type and Add report input fields.*
</Note>

After the upload completes, use the Transaction Date range filter in the Fuel Report to review the imported transactions.

## What syncs

The Compass integration is a manual, one-way sync from Compass into Alvys. After uploading a Compass CSV, Alvys maps transaction data as follows:

* Fuel card number on the CSV is matched against the digits stored in the driver's profile. Transactions are attributed to the driver whose fuel card number matches.
* Transaction date, amount, and gallons are imported into the Fuel Report.
* If the fuel card number on a transaction does not match any driver profile, the transaction will not be attributed to a driver. Add or correct the card number on the driver profile, then re-upload the file.
* Alvys detects duplicate transactions by transaction ID and will not import duplicates.
* There is no automatic or scheduled sync for this integration.

<Warning>
  ⚠️ This integration does not support automatic or scheduled imports. · Transactions with a card number not matching any driver profile will not be attributed to a driver. · Alvys does not write data back to Compass.
</Warning>

## Troubleshooting

### Driver fuel transactions not appearing after upload

1. Open the driver profile in **Assets > Drivers** and confirm a Compass fuel card number is saved under Fuel Card Numbers.
2. Verify the card number matches what appears in the Compass CSV export. Alvys matches on the exact digits stored in the profile.
3. Re-upload the CSV after correcting the card number. Alvys will not import a transaction already imported with the same transaction ID, so if the original upload was rejected entirely, a fresh upload of the same file will work.
4. If transactions are still missing after correcting the card number, contact Alvys support.

### Upload fails or returns an error

1. Confirm you selected **Compass** (not another provider) in the Integration Type dropdown before uploading.
2. Confirm the file is a CSV downloaded directly from the Compass portal. Modified or reformatted files may not parse correctly.
3. Contact Alvys support if the error persists after verifying the file and integration type.

## FAQs

**Q: What happens if I upload the same file twice?**

**A:** Alvys detects duplicate transactions by transaction ID and will not import them again. Re-uploading the same file is safe.

**Q: How often should I upload fuel transaction reports?**

**A:** This depends on your reporting and settlement schedule. Most teams upload weekly or monthly to keep fuel data current.

**Q: What if a driver's transactions are not showing up after upload?**

**A:** Confirm the driver has the correct Compass fuel card number on their profile under Assets > Drivers. Alvys matches transactions to drivers using that number. If the number is missing or incorrect, add or correct it and re-upload the file.

**Q: Do I need API credentials to set up this integration?**

**A:** No. The Compass integration does not require API credentials. You only need to activate it in Management > Integrations and then upload CSV files manually.


# Compass Funding Solutions Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/compass-funding-solutions-factoring-integration

Submit invoice batches from Alvys to Compass Funding Solutions via FTP, then upload purchase reports from the client portal to update load factoring status.

<Note>
  Compass Funding Solutions connects to Alvys via FTP to automate invoice batch submission. Purchase reports are downloaded from the Compass Funding client portal and uploaded into Alvys. Synonyms: Compass Funding, Compass factoring.
</Note>

## What This Integration Does

Compass Funding Solutions is an FTP-based factoring integration. Alvys submits invoice batches to Compass Funding via FTP using your client username and password. You then download the purchase report from the Compass Funding client portal and upload it into Alvys to update load statuses. Synonyms: Compass Funding, Compass factoring.

## Prerequisites

* Active account with Compass Funding Solutions
* Client username and password from the Compass Funding client portal
* Admin, Partner Admin, or Support access to configure the integration
* **"Billing"** permission to submit batches and upload reports

## Connect / Authenticate

* Navigate to Management > Integrations.
* Select **Factoring** from the list of integration types to filter the list.
* Click the pencil icon next to **Compass Funding** to open the integration configuration.
* Select the desired subsidiary. The Add Integration dialog appears with fields for your username and password.

<Note>
  <img alt="Notion Image" />
</Note>

* Enter your Compass Funding username and password. Click the blue **Save** button. Repeat the subsidiary selection and credential entry steps for each subsidiary if needed.

## Field & Data Mapping

Alvys generates a batch file containing invoice data for the selected loads and submits it to Compass Funding via FTP. No manual data entry is required for the batch file.

## Sync Behavior

Batch submission is initiated manually from Accounting > Factoring Upload. Purchase report data returns via manual upload from the Compass Funding client portal. There is no automated nightly sync.

## Submit a Batch

* Navigate to **Accounting > Factoring Upload**.
* Select the correct subsidiary from the subsidiary selector.

<Note>
  <img alt="Notion Image" />
</Note>

* Select the loads to include in the batch.

<Note>
  <img alt="Notion Image" />
</Note>

* Click the blue **Submit Batch** button.
* Wait until the submission is complete. The system will notify you when the batch submission has finished. Do not close this page or navigate away before the notification appears; doing so may disrupt the submission.

<Note>
  <img alt="Notion Image" />
</Note>

## Upload Your Purchase Report

* Download the purchase report for the submitted batch from the Compass Funding client portal.
* In Alvys, navigate to **Reports > Factoring** under the Operational Reports section.

<Note>
  <img alt="Notion Image" />
</Note>

<Note>
  <img alt="Notion Image" />
</Note>

* Find the respective batch and select it. Click the blue upload button in the **lower-right corner** of the page.
* Drag and drop the report file into the upload area, or click to select it from your device.

<Note>
  <img alt="Notion Image" />
</Note>

* Click **Upload**.

Repeat this process for each subsidiary if you submitted batches for multiple subsidiaries.

## Verify It's Working

After submitting a batch, confirm the batch appears in the Compass Funding client portal. After uploading the purchase report, verify that load statuses have updated in Alvys as expected.

## Troubleshooting

### Batch submission does not complete

1. Confirm you did not navigate away from Accounting > Factoring Upload before the system completion notification appeared. If you did, return to the page and check whether the loads still show a pre-submission status.
2. Confirm the subsidiary has valid FTP credentials configured. Navigate to Management > Integrations, locate Compass Funding, and verify the username and password are saved.
3. Contact Alvys support if the batch continues to fail after confirming credentials.

### Upload button is not visible on the Factoring report page

1. Confirm you have the **"Billing"** permission. Users without this permission cannot see the upload button.
2. Confirm the batch appears in Reports > Factoring. If it does not appear, confirm the batch was submitted from Accounting > Factoring Upload and that the system completion notification was received before navigating away.
3. Contact Alvys support if the batch was submitted and the notification was received, but the batch does not appear in Reports > Factoring.

## Limits / Unsupported

* Separate credentials must be configured for each subsidiary. One set of credentials cannot cover multiple subsidiaries.
* Compass Funding does not support Payment Report uploads through this integration. Only Purchase Reports are uploaded in Alvys.
* There is no automated or scheduled sync. All batch submissions and report uploads are initiated manually.

## FAQs

**Q: Where do I download the purchase report?**

**A:** Download the purchase report from the Compass Funding client portal for the submitted batch. Then upload it to Alvys from Reports > Factoring.

**Q: Can I use one set of credentials for multiple subsidiaries?**

**A:** No. Each subsidiary requires its own username and password configured separately in Management > Integrations.

**Q: What happens if I navigate away during batch submission?**

**A:** Navigating away before the system sends a completion notification may disrupt the submission. Wait on the Accounting > Factoring Upload page until the notification appears before moving to another page.

**Q: Do I need to repeat the upload process for each subsidiary?**

**A:** Yes. If you submitted batches for multiple subsidiaries, download the purchase report for each subsidiary from the Compass Funding client portal and upload each one separately in Reports > Factoring.

<img alt="Notion Image" />


# EDI Overview
Source: https://docs.alvys.com/en/help/integrations/edi-overview

Understand how Alvys exchanges EDI load tenders, tender responses, status updates, and invoices with your trading partners, and where each setting lives.

<Note>
  **Applies to:** Admin · Partner Admin · Support

  **Module:** Management > EDI & Visibility

  EDI (Electronic Data Interchange) lets Alvys automatically exchange load tenders, tender responses, shipment status updates, and freight invoices between your system and your customers' systems, eliminating manual document handling.
</Note>

## Overview

Electronic Data Interchange, also known as EDI, is a standardized method for exchanging business documents between computer systems without manual data entry. Alvys uses EDI to receive load tenders from customers, send tender responses, transmit shipment status updates, and submit freight invoices automatically.

By automating these exchanges, you reduce manual tasks, minimize data entry errors, speed up communication with major shippers and brokers, and meet the digital communication standards required by large trading partners. EDI integrations in Alvys scale as your business grows, allowing you to connect with additional trading partners without increasing manual workload.

EDI integrations in Alvys are configured per customer. Once an EDI connection is active for a customer, incoming tender documents flow directly into the Alvys Tenders board where users with the **"ParticipateInTender"** permission can review and act on them.

## Where to Find It?

Navigate to the [EDI & Visibility page](https://app.alvys.com/#/manage/integrations) by clicking your username in the bottom-left corner and selecting**EDI & Visibility**, or by copying and pasting the following URL into your browser: [https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations).

<Note>
  <img alt="Image showing navigation to EDI & Visibility Page" />

  *Image showing navigation to EDI & Visibility Page*
</Note>

This section is accessible to users with the Admin, Partner Admin, or Support role.

Individual customer EDI settings, including auto-acceptance and auto-update rules, are configured on each customer record under **Companies > Customers**.

The Tenders board is accessible from **Loads and Trips > Tenders** and requires the **"ParticipateInTender"** permission.

## Key Concepts

### Transaction Sets

Alvys supports the following EDI transaction sets:

* **204:** Inbound motor carrier load tender. A customer sends a 204 to offer a load to your company.
* **213:** Cancellation of a previously sent 204 tender.
* **990:** Tender response. Alvys sends a 990 to accept or decline a 204 tender.
* **214:** Shipment status update. Alvys sends a 214 to report pickup, delivery, and in-transit events back to the customer.
* **210:** Freight invoice. Alvys sends a 210 to submit an invoice for a completed load.
* **997:** Functional acknowledgment. Confirms receipt of a transmitted document.

### Tender Lifecycle

When a customer sends a 204, the tender appears on the Tenders board. A user with the **"ParticipateInTender"** permission can accept or decline the tender. If accepted, Alvys sends a 990 back to the customer. As the load progresses, Alvys sends 214 status updates. After delivery, a 210 invoice can be transmitted.

### Auto-Acceptance

Auto-acceptance allows Alvys to automatically accept inbound 204 tenders for a specific customer without manual review. This setting is configured per customer record and requires the **"EditCustomer"** permission to enable or disable.

### Auto-Update Settings

Auto-update settings control which EDI events Alvys sends automatically, including 214 status updates triggered by load activity.

## How to Use It?

For step-by-step instructions on configuring EDI features, see the related articles in the Go Deeper section below.

## Settings and Permissions

Access to the EDI & Visibility settings page under Management requires the Admin, Partner Admin, or Support role.

Enabling or disabling auto-acceptance on a customer record requires the **"EditCustomer"** permission.

Viewing and acting on tenders on the Tenders board requires the **"ParticipateInTender"** permission.

EDI connections are configured by the Alvys team during customer onboarding. To add or modify an EDI connection for a customer, contact Alvys support and provide the customer name and the type of integration needed. If you have confirmed the connection is already set up for that customer and it is still not working, contact Alvys support.

## Limits and Behavior

EDI connections are configured per customer. The specific transaction sets available depend on the EDI configuration established with each customer; not all customers support every transaction set.

Inbound 204 tenders with missing or incomplete stop data are quarantined when received. A quarantined tender does not appear as actionable on the Tenders board. A tender is quarantined when it is missing a pickup stop, missing a delivery stop, or when a stop address does not include a city and state. The customer must send a corrected 204 to resolve the quarantine.

## FAQs

**Q: Where do incoming load tenders appear?**

**A:** Inbound tenders appear on the Tenders board at Loads and Trips > Tenders. You must have the **"ParticipateInTender"** permission to access this board.

**Q: Can Alvys automatically accept tenders without manual review?**

**A:** Yes. Auto-acceptance can be enabled per customer on the customer record. See the linked article in Go Deeper for setup steps.

**Q: What happens if a customer cancels a tender after it has been accepted?**

**A:** The customer sends a 213 cancellation. Alvys processes the cancellation and updates the load accordingly.

**Q: Who can configure the EDI & Visibility settings page?**

**A:** The EDI & Visibility settings page under Management is accessible to users with the Admin, Partner Admin, or Support role.

**Q: Why is a tender quarantined on the Tenders board?**

**A:** A tender is quarantined when the inbound 204 message is missing required stop data. The three conditions that cause quarantine are: a missing pickup stop, a missing delivery stop, or a stop address that does not include a city and state. The customer must send a corrected 204 to resolve the issue.

**Q: How does an EDI connection get set up for a new customer?**

**A:** EDI connections are configured by the Alvys team during customer onboarding. Contact Alvys support to request a new connection or a change to an existing one.

## Go Deeper

* [How to enable EDI tender auto-acceptance for a customer](/en/help/integrations/how-to-enable-edi-tender-auto-acceptance-for-a-customer)
* [How to configure EDI Auto Update Settings](/en/help/integrations/how-to-configure-edi-auto-update-settings)


# EFS Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/efs-fuel-integration

Set up the EFS (WEX) fuel card integration in Alvys for automatic daily API imports or manual CSV uploads, plus e-check issuance for driver payments.

<Note>
  This article explains how to set up the EFS (WEX) fuel card integration in Alvys, configure automatic daily imports or manual CSV uploads, and add EFS fuel card numbers to driver profiles.
</Note>

## Overview

The EFS integration connects your EFS (WEX) fuel card (fuel network) account to Alvys to import fuel transactions either automatically through the API or manually by CSV upload. EFS also supports e-check issuance for driver payments such as advances, lumper fees, and repairs. Automatic imports run daily at 1 AM and pull the last 2 days of transactions. Manual imports use a CSV file you download from the EFS site and upload to Alvys.

The integration provides two services in Alvys:

* **Fuel management:** Imports fuel transaction data from EFS into the Alvys Fuel Report. This can be set up as an automatic daily API import or as a manual CSV upload.
* **E-check service:** Enables secure digital payment issuance directly from Alvys. E-checks can be used for driver advances, lumper fees, repair costs, and similar expenses.

<Info>
  💡 EFS is sometimes referred to as EFS WEX, the EFS fuel card, or the EFS fuel network.
</Info>

## Prerequisites

Before configuring EFS in Alvys, confirm the following:

* You have **"Admin"**, **"Support"**, or **"Partner Admin"** access in Alvys (set on your user role in the Company Profile).
* For the **automatic API import**: you must first add Alvys as a Data Share Partner on EFS and obtain API credentials from EFS support. These credentials are different from your regular EFS login.
* For the **manual CSV import**: no API credentials are required. You only need access to the EFS site to download transaction reports.
* Your drivers have been added to Alvys with their EFS fuel card numbers.

## How to connect

### Automatic API import

The automatic import requires credentials that EFS generates specifically for API access. Your standard EFS username and password cannot be used.

1. Add Alvys as a Data Share Partner on EFS. Download and follow the EFS Data Sharing Instructions PDF provided in the original EFS article on [help.alvys.com](https://help.alvys.com/). This document walks you through adding Alvys Inc as a data share partner in your EFS account.
2. Request API credentials from EFS support. After adding Alvys as a data share partner, email EFS support at [EFSWEX-customersoftwaresupport@wexinc.com](mailto:EFSWEX-customersoftwaresupport@wexinc.com) to request API credentials. Include the following in your email body, substituting your company's details:

   * **Customer name:** your company name as registered with EFS.
   * **Username:** will be created by EFS.
   * **Password:** will be created by EFS.
   * **Carrier ID:** visible in your EFS eManager portal.
   * **Contract ID:** ask EFS if unknown (found under Select Program > Credit Management > Available Credit).
   * **Master Contract ID:** ask EFS if unknown.
3. Enter the EFS credentials in Alvys once EFS replies:

   * Click your username in the bottom left corner of Alvys, then select **Management**.
   * Go to the **Integrations** section.
   * Scroll to the **Fuel Cards** drop-down and select the “Inactive” button next to **EFS**.

<Note>
  <img alt="This image shows the EFS integration configuration form in Alvys with fields for username, password, contract ID, master contract ID, carrier ID, and subsidiary selection." />

  *This image shows the EFS integration configuration form in Alvys with fields for username, password, contract ID, master contract ID, carrier ID, and subsidiary selection.*
</Note>

### Manual CSV import

The manual import does not require API credentials. Set up a separate integration entry using the EFS CSV option.

1. Click your username in the bottom left corner of Alvys, then select **Management**.
2. Go to the **Integrations** section.
3. Scroll to the **Fuel Cards** drop-down and select **EFSCSV**.
4. Select the subsidiary you want to integrate with.
5. Click **Save**.

<Note>
  <img alt="This image shows the Integrations section in Alvys Management with EFSCSV integration" />

  *This image shows the Integrations section in Alvys Management with EFSCSV integration*
</Note>

<Info>
  💡 The automatic API path and the manual EFS CSV path are separate integration entries and can be used together.
</Info>

### Add EFS fuel card numbers to driver profiles

This applies to both automatic and manual imports.

1. From the blue Alvys toolbar, select **Assets**, then choose **Drivers**.
2. Double-click a driver from the list to open their profile.
3. Find the **Fuel Card Numbers** field next to the driver's name and click the plus sign.
4. Enter the full fuel card number, select **EFS** as the fuel card provider, and check the applicable boxes for deduct fuel or discounted fuel if needed.
5. Click **Save**.
6. Repeat for each driver with an EFS fuel card.

<Note>
  <img alt="This image shows: a driver profile in Alvys with the “Add Fuel Card” form wit the following input fields: Card Number, Deduct from Owner Operator and Provider field with EFS selected." />

  *This image shows: a driver profile in Alvys with the “Add Fuel Card” form wit the following input fields: Card Number, Deduct from Owner Operator and Provider field with EFS selected.*
</Note>

### Manual import only: download and upload the EFS transaction file

* Log in to the EFS site and download the fuel transactions report in Excel format.
* When exporting, ensure the following options are selected: **Show Full Card Number**, **Show Transaction Time**, and **Show Discount Amount**.
* Save the file to your device. Alvys provides a template file that shows the expected format (EFS Fuel template.xlsx); the template link is available in the Factoring Reports section on Alvys.
* From the Alvys toolbar, go to \*\*Assets \*\*and select **Fuel Report**.

<Note>
  <img alt="This image shows the Fuel Report page with the Transaction File Upload button visible." />

  *This image shows the Fuel Report page with the Transaction File Upload button visible.*
</Note>

* Click the vertical ellipsis icon **(⋮)** next to the “**Add** \*\*Transaction” \*\*button.

<Note>
  <img alt="Image showing ellipsis icon next to “Add Transaction” button" />

  *Image showing ellipsis icon next to “Add Transaction” button*
</Note>

* Select the “**Import Report**” option.

<Note>
  <img alt="Image showing Import Report option" />

  *Image showing Import Report option*
</Note>

* In the pop-up window, select **EFSCSV** from the **Integration Type** drop-down menu.

<Note>
  <img alt="Image showing ”Upload Fuel Report” form with Integration type and Add report input fields." />

  *Image showing ”Upload Fuel Report” form with Integration type and Add report input fields.*
</Note>

* Upload the CSV file you downloaded from the Compass portal.
* Click the “Save” button
* Once the upload completes, use the **Transaction Date** range filter in the Fuel Report to review imported transactions.

## What syncs

The EFS integration imports fuel transaction data from EFS into the Alvys Fuel Report and, separately, enables e-check issuance.

* **Automatic import:** Fuel data imports daily at 1 AM, pulling all transactions from the past 2 days since the integration was configured. Transactions are automatically matched to the corresponding trucks and drivers in Alvys.
* **Manual import:** There is no automatic sync. You download a transaction file from the EFS site and upload it to Alvys whenever you need to import transactions.
* **Matching:** Alvys matches fuel transactions to driver profiles using the full EFS fuel card number stored on the driver's profile. Each driver must have their EFS card number entered before transactions can be matched. The manual CSV must include the full card number, transaction time, and discount amount columns.

<Warning>
  ⚠️ The automatic import pulls only the last 2 days of transactions; use the manual EFS CSV import to backfill older data.

  API credentials are generated by EFS and cannot be reused from other integrations or your standard EFS portal login.

  The manual CSV import requires the EFS-formatted Excel export; custom or reformatted files are not supported.
</Warning>

## Troubleshooting

### Fuel transactions are not appearing after the automatic import

Confirm the following: the green check mark appears next to the EFS integration in Management, the driver profile has the correct full EFS fuel card number entered, and EFS is selected as the provider. If the integration was set up recently, the first import runs at 1 AM the following day.

### Fuel transactions are not appearing after a manual CSV upload

Verify the exported file includes the **Show Full Card Number**, **Show Transaction Time**, and **Show Discount Amount** columns. If any of these columns are missing, export the file again from EFS with all three options enabled, then re-upload. Confirm drivers have the correct EFS card number in their profiles.

### The EFS credentials are rejected when saving the integration

The credentials entered in the Alvys integration form must be the API credentials provided by EFS support ([EFSWEX-customersoftwaresupport@wexinc.com](mailto:EFSWEX-customersoftwaresupport@wexinc.com)). Your regular EFS portal login credentials cannot be used here. If you do not have API credentials, contact EFS support to request them.

## FAQs

**Q:** Do I need both the automatic and manual EFS integrations?

**A:** No. Set up the automatic API integration if you want daily imports without manual steps. Set up the manual EFS CSV integration if you prefer to control when transactions import, or if you need to backfill historical data. You can use both if needed.

**Q:** How often does the automatic import run?

**A:** The automatic import runs once daily at 1 AM, pulling all transactions from the past 2 days.

**Q:** Can I use my regular EFS login credentials for the API integration?

**A:** No. The username and password for the Alvys EFS integration are API credentials that EFS generates specifically for this integration. Contact EFS support at [EFSWEX-customersoftwaresupport@wexinc.com](mailto:EFSWEX-customersoftwaresupport@wexinc.com) to request them.

**Q:** What happens if a driver's fuel card number is entered incorrectly?

**A:** If the card number in Alvys does not match the card number on the imported transaction, the transaction will not be matched to that driver. Correct the card number on the driver's profile and re-import or re-upload the transaction data.

**Q:** What is the EFS e-check service used for?

**A:** The EFS e-check service allows you to issue digital payments to drivers directly from Alvys. It is used for expenses such as driver advances, lumper fees, and repair costs. E-check setup is configured separately from the fuel import integration.


# Fleetrock — Maintenance Integration
Source: https://docs.alvys.com/en/help/integrations/fleetrock-maintenance-integration

Connect Fleetrock to Alvys as a two-way maintenance integration to sync repair orders and scheduled maintenance alerts into the Dispatch Planner.

<Note>
  Two-way maintenance integration: Fleetrock pushes repair order updates to Alvys via webhook and Alvys imports open repair orders on activation.
</Note>

## Overview

Fleetrock is a fleet maintenance management platform that connects with Alvys to keep your repair orders and scheduled maintenance items in sync. It is also known as a fleet maintenance integration, repair order integration, or maintenance tracking integration.

Connecting Fleetrock to Alvys allows your team to view and manage repair orders directly in Alvys without switching to the Fleetrock portal. When a repair order is updated in Fleetrock, Alvys reflects the change automatically. Alvys also receives scheduled maintenance alerts from Fleetrock, which appear in the Dispatch Planner so dispatchers can see upcoming service needs alongside load assignments.

## Prerequisites

Before connecting, confirm you have the following:

* An active Fleetrock account with API access.
* Your Fleetrock API credentials (username and password from Fleetrock).
* The **"Admin"** or **"Partner Admin"** role in Alvys. These roles can access **Management > Integrations**.

## How to connect

* Open the Maintenance integrations: go to **Management > Integrations > Maintenance** in the top navigation.

<Note>
  <img alt="Image showing Maintenance integration drop down." />

  *Image showing Maintenance integration drop down.*
</Note>

* Find Fleetrock in the list and click the “Inactive” status to open the configuration dialog.

<Note>
  <img alt="Image showing Fleetrock integration card with inactive status, on the Alvys integrations page" />

  \*Image showing Fleetrock integration card with inactive status, on the Alvys integrations page \*
</Note>

* Enter the Login URL supplied by Fleetrock. For example: [https://www.fleetrock.com](https://www.fleetrock.com/). **Please note that tenants who are reseller partners may have a different login URL.**

<Note>
  <img alt="Image showing the Alvys “Configure Integration” form for the Fleetrock integration with the login URL and the Username input fields" />

  \*Image showing the Alvys “Configure Integration” form for the Fleetrock integration with the login URL and the Username input fields \*
</Note>

* Enter the Username (e.g., **Alvyscustomer**). Only the owner or primary account should be used. This can be found in Fleetrock under Settings > Users.

<Note>
  <img alt="Image showing Fleetrock Settings page with User details" />

  \*Image showing Fleetrock Settings page with User details \*
</Note>

* \*\*Generate the API Key. \*\*In Fleetrock, go to the Settings menu, then select API. Enter ‘Alvys’ as the description and make sure to \*\*uncheck \*\*the ‘Use JSON Web Tokens (JWT)’ box, as the integration will not work if it is checked. Click “**Generate Key**” and copy the API key from the grey input field into the Alvys integration setup.

<Note>
  <img alt="Image showing Fleetrock Settings page with API details" />

  *Image showing Fleetrock Settings page with API details*
</Note>

* Select the appropriate Subsidiary for the integration.

<Note>
  <img alt="Image showing the Alvys “Configure Integration” form for the Fleetrock integration with the “API key' and the “Subsidiaries” input fields" />

  \*Image showing the Alvys “Configure Integration” form for the Fleetrock integration with the “API key" and the “Subsidiaries” input fields \*
</Note>

* **Select the Default Asset Group**. Asset Groups in Fleetrock are required for asset creation and help organize units. A default group ensures new assets from Alvys are properly created and categorized in Fleetrock. Groups can be created and managed in Fleetrock by navigating to the **Assets** tab and selecting the **Groups** button.

<Note>
  <img alt="Image showing the Default Asset Group dropdown during the Alvys Fleetrock integration configuration." />

  *Image showing the Default Asset Group dropdown during the Alvys Fleetrock integration configuration.*
</Note>

* \*\*Link Fleetrock and Alvys for Automatic Updates. \*\*Fleetrock uses webhooks to send real-time data to Alvys. Copy the webhook URL provided by Alvys. Within Fleetrock, navigate to the Settings page and select Webhooks. Enable the webhook by selecting the "**Enable**" checkbox. Paste the webhook URL provided by Alvys into the "**Endpoint URL**" field.

<Note>
  <img alt="Image showing “Setup Webhooks” dialog with webhook details such as secret key and webhook URL" />

  \*Image showing “Setup Webhooks” dialog with webhook details such as secret key and webhook URL \*
</Note>

* Copy the secret key from Alvys and enter it into the "**Webhook Secret**" field.
* Select choose "**All**." for the **Send Events input** field, then Click "**Send Test Webhook**" to verify the connection.

<Note>
  <img alt="Image showing Fleetrock settings user interface for Webhook Setup." />

  *Image showing Fleetrock settings user interface for Webhook Setup.*
</Note>

* A success message will confirm correct setup. Finally, select "**Update**" to save the webhook configuration.

<Note>
  <img alt="Image showing successful configuration of webhooks in Fleetrock" />

  \*Image showing successful configuration of webhooks in Fleetrock \*
</Note>

* Navigate back to Alvys and select the Activate button.

<Note>
  <img alt="Image showing “Activate” button in final step of the Fleetrock integration configuration." />

  *Image showing “Activate” button in final step of the Fleetrock integration configuration.*
</Note>

* The integration will now show as active

<Note>
  <img alt="Image showing active Fleetrock integration" />

  *Image showing active Fleetrock integration*
</Note>

## Asset Creation and Syncing with Fleetrock

When the integration with Fleetrock is first activated, Alvys does not create new assets in Fleetrock for units that exist only in Alvys. However, if an asset exists in both systems with the same VIN, the integration will automatically sync those records. After the integration is enabled, any new assets (trucks and trailers) created in Alvys will automatically be created in Fleetrock. This process eliminates duplicate data entry, keeps Fleetrock aligned with your current fleet information, and ensures maintenance schedules are correctly applied to the right assets.

**Fields Synced from Alvys to Fleetrock:**

* Truck/Trailer Number (Unit Number)
* License Number
* License State (Registration State)
* License (Registration Expiration)
* VIN - Once a valid VIN is provided, additional details such as make, model, and year will be automatically populated by Fleetrock under the **VIN Data** tab for the corresponding truck or trailer
* Status (Active/Inactive).

<Warning>
  ⚠️ Changes made to\*\* assets\*\* directly in Fleetrock will **not** sync back to Alvys. (**Alvys is the source of truth**)

  If an asset is deleted in Alvys, its status will be set to **Inactive** in Fleetrock. If that asset is re-created in Alvys using the same VIN, Fleetrock will detect the match and change the status back to **Active**
</Warning>

## What syncs / data flow

Repair order statuses are mapped between Fleetrock and Alvys as follows:

| Fleetrock status | Alvys status |
| ---------------- | ------------ |
| Not Started      | Open         |
| In Progress      | In Progress  |
| Waiting          | In Progress  |
| Finished         | Completed    |
| Invoiced         | Completed    |
| Paid             | Completed    |

Scheduled maintenance items from Fleetrock are also synced to Alvys. These appear as upcoming service reminders in the Dispatch Planner.

Fleetrock sends updates to Alvys automatically via webhook whenever a repair order is created or its status changes. You do not need to manually refresh or re-sync. Scheduled maintenance data is sent from Fleetrock to Alvys once daily at 5:00 AM Eastern Time.

VIN matching is used to link repair orders in Fleetrock to the correct truck in Alvys. The truck's VIN in Alvys must match the VIN in Fleetrock for repair orders to appear on the correct asset.

## How to view repair orders in Alvys

A Repair Order (also known as a Work Order) is a formal request to perform maintenance or repairs on a unit such as a truck or trailer.

Once the Fleetrock integration is enabled, **Alvys will automatically import any repair orders from Fleetrock** that are either **Not Started** or **In Progress**. These repair orders are imported into Alvys as **Asset Events**.

* Go to the Asset List (Truck List or Trailer List) in Alvys
* Select the **Asset Events** tab on the record. All active and completed repair orders synced from Fleetrock will appear here.
* Click a repair order to view its line items, status, and service history as reported by Fleetrock.

<Note>
  <img alt="Image showing sample truck profile, “Asset Events” tab with Work Order details" />

  *Image showing sample truck profile, “Asset Events” tab with Work Order details*
</Note>

## How scheduled maintenance appears in the Dispatch Planner

The Dispatch Planner displays upcoming scheduled maintenance from Fleetrock in a dedicated column. Dispatchers can see:

* The truck that has upcoming service.
* The type of service scheduled.
* The due date or mileage threshold for the service.
* The current status of any active repair order for that truck.

  This allows dispatchers to plan load assignments around maintenance needs before they become urgent.

  <Warning>
    **Limits / unsupported:**

    * Only repair orders with Not Started or In Progress status are imported at activation.
    * Scheduled maintenance syncs once daily (5:00 AM Eastern Time), not in real time.
    * VIN matching is required, repair orders will not link to a truck if the VIN does not match.
    * The JWT option must remain unchecked; JWT authentication is not supported for this integration.
  </Warning>
* Only repair orders with Not Started or In Progress status are imported at activation.
* Scheduled maintenance syncs once daily (5:00 AM Eastern Time), not in real time.
* VIN matching is required, repair orders will not link to a truck if the VIN does not match.
* The JWT option must remain unchecked; JWT authentication is not supported for this integration.

## Troubleshooting

### Repair orders are not appearing after activation

1. Confirm the **JWT** option was **UNCHECKED** when you saved the credentials. If JWT was checked, the connection will not authenticate correctly. Re-enter your credentials with JWT unchecked.
2. Verify that the repair orders in Fleetrock have a status of Not Started or In Progress. Only these two statuses are imported during the initial activation.
3. Check that the truck VINs in Alvys match the VINs in Fleetrock exactly. A VIN mismatch will prevent repair orders from appearing on the correct truck.

### A repair order status change in Fleetrock is not updating in Alvys

1. Confirm the Fleetrock webhook is active. Webhook connectivity is required for real-time updates. If the webhook was disrupted, contact Fleetrock to verify the webhook is pointed to the correct Alvys endpoint.
2. Check the status mapping above — some Fleetrock statuses map to the same Alvys status (for example, Finished, Invoiced, and Paid all map to Completed).

### Scheduled maintenance is not showing in the Dispatch Planner

Scheduled maintenance data syncs once daily at 5:00 AM Eastern Time. If you added a new maintenance schedule in Fleetrock today, it will appear in Alvys the following morning. If it does not appear after 24 hours, contact Alvys support.

## FAQs

**Q: Why are some repair orders missing after I connected Fleetrock?**

**A:** Only repair orders with a Not Started or In Progress status in Fleetrock are imported when you first activate the integration. Repair orders in other statuses (such as Finished, Invoiced, or Paid) are not imported at activation. They will appear in Alvys as Fleetrock sends future webhook updates.

**Q: What happens when I mark a repair order as Paid in Fleetrock?**

**A:** Fleetrock sends a webhook update to Alvys. The repair order status in Alvys updates to Completed.

**Q: Can dispatchers see which trucks need maintenance before assigning loads?**

**A:** Yes. Upcoming scheduled maintenance from Fleetrock appears in the Dispatch Planner so dispatchers can factor service needs into load assignments.

**Q: What does "JWT must be unchecked" mean?**

**A:** During setup, there is an option labeled JWT in the credentials form. This option must be left unchecked. If it is checked, Fleetrock's authentication will not work and the integration will fail to connect.

**Q: What happens if I delete an asset in Alvys?**

A: t becomes Inactive in Fleetrock. If you recreate the asset with the same VIN, Fleetrock will set it back to Active.

**Q: Why don’t I see the Maintenance Status in Alvys right after creating a scheduled maintenance in Fleetrock?**

**A:** Scheduled maintenance data is sent by Fleetrock to Alvys daily at 5 AM EST, so changes won’t show immediately.

**Q: What about accounting? How do Fleetrock invoices/POs make it to external accounting systems?**

A: Fleetrock supports an integration with QuickBooks Online (QBO). If a customer doesn’t use QBO, they’ll need to build their own accounting integration.


# FourKites Inbound Integration
Source: https://docs.alvys.com/en/help/integrations/fourkites-inbound-integration

Connect Alvys to FourKites to push assigned load and carrier data into tracking cards, so brokerage teams start inbound visibility without double entry.

<Note>
  Connect Alvys to FourKites (also called 4Kites) to initiate and manage inbound carrier tracking from your load board, creating and updating tracking cards automatically without manual double entry.
</Note>

## What This Integration Does?

The FourKites Inbound Integration (also called FourKites inbound, 4Kites tracking, carrier tracking cards, or inbound visibility) lets brokerage teams push load and carrier data from Alvys into FourKites to create and update tracking cards. Once connected, you can start a tracking request on any load that has an assigned carrier, review pre-populated load details in a tracking form, and monitor the status of each tracking request directly on the load details page.

This is a one-way integration: data flows from Alvys to FourKites. Alvys sends load cards, stop details, carrier information, and reference numbers to FourKites. Location updates from FourKites are not returned to Alvys.

The integration is configured per subsidiary and requires a FourKites API key.

## Prerequisites

Before connecting, make sure you have:

* An active FourKites account with API access.
* A FourKites API key (obtain this from your FourKites account settings or your FourKites account manager).
* Admin, Partner Admin, or Support role in Alvys.
* At least one subsidiary configured in Alvys that you want to enable for this integration.

## Connect / Authenticate

This setup is completed once per subsidiary. You can enable multiple subsidiaries using the same API key if your FourKites account covers all of them.

1. Open the EDI & Visibility settings. Select your user profile in the bottom-left corner of Alvys, then select **EDI & Visibility**.
2. Locate FourKites Inbound in the list of available integrations and select it to open the configuration form.
3. Enter your API key. In the configuration form, enter the FourKites API Key you obtained from FourKites.
4. Select subsidiaries. Choose which subsidiaries you want to enable for this integration. Each subsidiary you select will use the API key you entered.
5. Save and verify. Select **Save**. Alvys will validate your credentials against FourKites. If the key is valid, the integration status updates to confirm the connection is active. If validation fails, double-check the API key and try again.

## Field & Data Mapping

The following data is sent from Alvys to FourKites when a tracking request is created or updated:

Alvys sends the load number as the primary identifier on the FourKites card. The order number and PO number are sent as reference numbers attached to the shipment. The load customer name and customer ID are sent as tags on the FourKites card, linking the Alvys load customer to the corresponding customer in FourKites.

For each pickup and delivery stop, Alvys sends the stop address (address line 1, address line 2, city, state, country), the scheduled appointment window (earliest and latest appointment times in the stop's local time zone), the stop type (pickup or delivery), and the stop name. Waypoint stops are not supported by FourKites and are not sent.

Carrier tracking details are sent only when provided: truck number, trailer number, and driver phone number. The carrier name field in FourKites is optional; Alvys does not automatically populate it because FourKites has no dedicated carrier name identifier that maps reliably to Alvys carrier records.

## Sync Behavior

**Alvys sends data to FourKites in the following scenarios:**

* When you select the FourKites Tracking button on a load and submit the tracking form, Alvys creates a new shipment in FourKites. If a previous tracking request for the same trip was stopped earlier, Alvys reuses the existing record and updates it rather than creating a duplicate.
* When load details change after a tracking request is active, you can re-open the tracking form and update the card. Alvys sends the updated information to FourKites.
* When you stop a tracking request on the load details page, Alvys removes the corresponding shipment from FourKites and records the status as stopped.

<Warning>
  ⚠️ FourKites does not send location or status updates back to Alvys. The tracking status visible in Alvys reflects the state of the request that Alvys created, not live location data from FourKites.
</Warning>

## Verify It's Working

**After initiating a tracking request on a load:**

1. On the load details page, confirm the tracking status indicator shows Ready to Track. If it shows Error, see the Troubleshooting section below.
2. Select the link that appears on the load details page to open the FourKites card directly. Confirm the load number, stop addresses, and reference numbers are correct in FourKites.
3. In FourKites, verify that the correct stops appear as pickup and delivery with the scheduled appointment windows.

## Troubleshooting

### Tracking status shows Error after creating a request

1. Open the load in Alvys and check that all pickup and delivery stops have a complete address (address line 1, city, state, and country are required). Waypoint stops are not sent to FourKites.
2. Check that the FourKites API key in EDI & Visibility settings is still valid. API keys can be rotated or changed in your FourKites account. Re-enter the key and save if it has changed.
3. If stops have addresses and the API key is valid, contact Alvys support with the load number and the error message shown on the load details page.

### FourKites card does not show the correct customer

* FourKites does not have a dedicated customer field. Alvys passes the load customer name and ID as tags on the FourKites shipment. If the card is not associating with the correct FourKites customer, connect the Alvys customer ID to the FourKites customer directly in your FourKites account settings.

### Tracking button is not visible on the load

* The FourKites Inbound Integration must be active for the subsidiary associated with the load. Confirm the subsidiary is enabled in EDI & Visibility settings. If the subsidiary is enabled and the button is still not visible, contact Alvys support.

### Integration does not appear in EDI & Visibility settings

* The EDI & Visibility page is accessible to Admin, Partner Admin, and Support roles only. If you do not see this menu option, your role does not include access. Contact your company Admin to configure the integration.

## Limits / Unsupported

* Location updates from FourKites are not returned to Alvys. The integration is one-way (Alvys to FourKites only).
* Waypoint stops are not supported. Only pickup and delivery stop types are sent to FourKites.
* The carrier name field in FourKites is not automatically populated by Alvys. You may enter it manually in the tracking form.
* The integration is configured per subsidiary. A subsidiary that is not enabled will not show the FourKites Tracking button on loads.
* If a load does not use order numbers or PO numbers, those reference fields will be empty on the FourKites card. The card will still be created using the load number.

## FAQs

**Q: Do I need to enter the carrier name when starting a tracking request?**

**A:** No. The carrier name field is optional. FourKites accepts the request without it, and the load card is created successfully. You can add the carrier name manually in the tracking form if needed.

**Q: Does Alvys receive live location updates back from FourKites?**

**A:** No. This integration sends data from Alvys to FourKites only. Live location coordinates and delivery status updates in FourKites are visible in FourKites directly; they are not returned to the Alvys load details page.

**Q: Why do I need to set up the integration separately for each subsidiary?**

**A:** The integration is configured at the subsidiary level so that tracking settings are segmented correctly for each business unit. This gives you control over which subsidiaries send load data to FourKites and which do not.

**Q: Can I use the same FourKites API key for multiple subsidiaries?**

**A:** Yes. You can enter the same API key and enable multiple subsidiaries in a single configuration save.

**Q: What happens if I stop a tracking request in Alvys?**

**A:** Alvys sends a removal request to FourKites, which removes the shipment from FourKites. The tracking status in Alvys updates to reflect that tracking was stopped.

**Q: My workflow does not use order numbers or PO numbers. Will the FourKites integration still work?**

**A:** Yes. If a load does not use order numbers or PO numbers, those reference fields will be empty on the FourKites card. The card is still created and updated using the load number.

## Go Deeper

* [FourKites Outbound Integration](/en/help/integrations/fourkites-outbound-integration)


# FourKites Outbound Integration
Source: https://docs.alvys.com/en/help/integrations/fourkites-outbound-integration

Send real-time location updates and shipment milestones from Alvys to FourKites so customers can track outbound loads directly in their FourKites portal.

<Note>
  Share real-time load location and status updates from Alvys to FourKites so customers can track shipments in their FourKites portal without contacting your team.
</Note>

## Overview

Share real-time load location and status updates from Alvys to **FourKites** (also called 4Kites) so customers can track shipments in their FourKites portal without contacting your team.

Synonyms: FourKites outbound, 4Kites, outbound visibility, customer tracking, location sharing, shipment milestones.

The FourKites Outbound integration connects Alvys to FourKites using basic authentication credentials provided by FourKites. Once connected and activated for a customer, Alvys automatically sends location updates and shipment milestones to FourKites based on the sharing preferences you configure for that customer.

This integration enables your customers who use FourKites to receive real-time visibility into load progress, including location coordinates, delivery status, and delivery confirmation.

This is a one-way integration. Data flows in one direction, from Alvys to FourKites.

## Prerequisites

Before setting up this integration you will need:

* An active FourKites account.
* Basic authentication credentials (username and password) from FourKites. Contact [support@fourkites.com](mailto:support@fourkites.com) to request these credentials.
* The Alvys Customer ID for each customer you want to activate data sharing for.
* Admin, Partner Admin, or Support access in Alvys.

## How to connect

Open the integration settings.

Navigate to **Management > EDI & Visibility** in Alvys. Select the subsidiary you want to configure and click the pencil icon.

<Note>
  <img alt="Management > EDI & Visibility page with subsidiary selector and pencil icon" />

  *Management > EDI & Visibility page with subsidiary selector and pencil icon*
</Note>

Enter FourKites credentials.

Enter the username and password provided by FourKites, select the subsidiaries to enable, and click **Save**.

<Note>
  <img alt="FourKites credentials entry showing username, password, and subsidiary selection" />

  *FourKites credentials entry showing username, password, and subsidiary selection*
</Note>

Find the Alvys Customer ID.

Open a customer profile in Alvys from any load where the customer has been set, or from **Companies > Customers**. The Alvys Customer ID is the long identifier in the address bar of the customer profile page.

For example, in the address `https://app.alvys.com/#/companies/affa5b56ceaeb45dc44z9af3cf855e8c6c12b/edit`, the Alvys Customer ID is `affa5b56ceaeb45dc44z9af3cf855e8c6c12b`.

Link the customer in FourKites.

Add the Alvys Customer ID to the Customer Bill-to codes in the FourKites customer settings. You can do this at [app.fourkites.com/self-service/carrier/customers](http://app.fourkites.com/self-service/carrier/customers) following the instructions in the FourKites Connect Carrier Flow guide, or provide the Alvys Customer ID to the FourKites contact who gave you your integration credentials.

<Note>
  <img alt="Customer profile address bar showing the location of the Alvys Customer ID" />

  *Customer profile address bar showing the location of the Alvys Customer ID*
</Note>

Configure sharing preferences for the customer.

On the right side of the customer profile in Alvys, find the **FourKites** banner under integration settings and click it to open sharing preferences.

<Note>
  <img alt="Customer profile showing the FourKites banner in the integration settings" />

  *Customer profile showing the FourKites banner in the integration settings*
</Note>

Adjust your sharing preferences and click **Save**.

<Note>
  <img alt="FourKites sharing preferences panel with the eight location sharing options" />

  *FourKites sharing preferences panel with the eight location sharing options*
</Note>

## What syncs

When a load is shared with FourKites, Alvys sends the following data:

* The Alvys Customer ID is used by FourKites to identify which customer this load is shared with. The load order number is submitted as the bill of lading value. The load PO number is submitted as the load identifier. Last known location coordinates, city, state, and country are included. Delivery status is sent as confirmed or not confirmed. Delivery time from the empty time at the last location is included when the load reaches a delivered state.
* Location updates are sent to FourKites automatically based on the sharing preferences configured for each customer. Each customer has eight sharing preference options:
* **Dispatched or Covered status:** Sends updates when the load is in **Dispatched** or **Covered** status and it is two hours or less before the scheduled pickup.
* **Dispatched status and 1st stop is marked as Arrived:** Starts sending updates when an arrival time has been recorded at the first stop.
* **Load In Transit:** Sends updates for loads in **In Transit** status.
* **Load Delivered:** Sends updates for loads in **Delivered** status. This option must be enabled to notify FourKites when a load has been delivered.
* **ELD:** Parses location information from ELD sources you have integrated with FourKites.
* **Outside Tracking Check Call:** Sends location updates from third-party tracking sources that support stop status events.
* **Location from the Driver App:** Sends location updates when the driver assigned to the trip is using the Alvys Driver Companion app.
* **Location from Other Tracking Services:** Sends location from other tracking service providers such as MacroPoint, FourKites tracking, Trucker Tools, or Project44.

### Managing updates per load

You can pause or resume data sharing for a specific load directly from the load detail page. Auto-updates are on by default for loads where the assigned customer has data sharing enabled.

<Note>
  <img alt="FourKites auto-update toggle on a load detail page" />

  *FourKites auto-update toggle on a load detail page*
</Note>

### Verify it is working

1. Open a load assigned to a customer you have activated FourKites sharing for.
2. Confirm that auto-updates are active on the load.
3. Log in to FourKites and confirm the load is receiving location updates.

If the load is not appearing in FourKites or is not receiving updates, review the Troubleshooting section below.

## Troubleshooting

### No updates are reaching FourKites for a customer

1. Confirm the FourKites Outbound integration credentials are saved correctly in **Management > EDI & Visibility**.
2. Confirm the customer profile in Alvys has sharing preferences configured. The FourKites banner must be visible in the customer profile integration settings.
3. Confirm the Alvys Customer ID is linked to the correct customer in FourKites.
4. Confirm at least one sharing preference option is enabled for the customer.
5. If updates are still not reaching FourKites after confirming the above, contact Alvys support.

### FourKites banner is not visible on a customer profile

1. Confirm the FourKites Outbound integration is set up and saved in **Management > EDI & Visibility** for the subsidiary associated with the customer.
2. Confirm the customer is assigned to the subsidiary that has FourKites enabled.
3. If the banner is still not appearing after confirming the above, contact Alvys support.

## Limits and unsupported

* Data flows from Alvys to FourKites only. FourKites cannot update load status or modify any data in Alvys.
* The integration must be configured separately for each subsidiary.

## FAQs

**Q: Can I pause updates for a specific load without disabling the integration?**

**A:** Yes. You can pause or resume data sharing for individual loads directly from the load detail page. Auto-updates are on by default for loads where the customer has sharing enabled.

**Q: Why is the FourKites banner not visible on a customer profile?**

**A:** The FourKites banner appears only when the FourKites Outbound integration is configured in **Management > EDI & Visibility** for the subsidiary that the customer belongs to. Confirm the integration setup and that the customer is assigned to the correct subsidiary.

**Q: Which sharing preferences should I enable?**

**A:** This depends on your customer's requirements. Most carriers enable Load In Transit, Load Delivered, and Location from the Driver App at minimum. Contact your FourKites account representative for guidance on which options your customer requires.

## Go Deeper

* [FourKites Inbound Integration](/en/help/integrations/fourkites-inbound-integration)


# How to configure EDI Auto Update Settings
Source: https://docs.alvys.com/en/help/integrations/how-to-configure-edi-auto-update-settings

Configure automatic EDI 214 status updates in Alvys for location heartbeats, appointments, arrivals, departures, and ETA on each customer profile.

<Note>
  Configure which EDI events Alvys sends automatically to a customer, including location updates (heartbeats), appointment times, arrivals, departures, and estimated delivery time (ETA). Also known as automatic EDI updates, auto-send EDI, EDI 214 settings, and EDI status updates.
</Note>

## Overview

Auto Update Settings control when and how Alvys automatically sends EDI 214 (Shipment Status Update) messages to a customer's system. These settings live on each customer's company profile and let you configure what gets shared, when, and based on what data sources.

You can enable automatic sharing for five types of events: location updates (heartbeats), appointments, arrivals, departures, and estimated delivery time (ETA). Each type has its own toggle and sub-options so you can tailor the behavior per customer.

## Before You Start

You need the **"EditCustomer"** permission to configure Auto Update Settings on a customer record. Admin, Partner Admin, and Office Admin users have this permission by default. Other users can be granted **"EditCustomer"** by an Admin.

The customer must also have an active EDI integration configured. Auto Update Settings only appear and apply to customers with an active EDI connection.

## Steps

\*\*Open the customer record. \*\*Navigate to **Companies > Customers** and open the company profile for the customer you want to configure.

**Open Auto Update Settings**. On the customer profile, find the **Auto Update Settings** section in the right-hand sidebar and click it to open the settings panel.

<Note>
  <img alt="Auto Update Settings section in the customer profile right-hand sidebar." />

  *Auto Update Settings section in the customer profile right-hand sidebar.*
</Note>

**Configure Location Updates** (Heartbeat / EDI 214). Enable the **Auto Send** toggle for Location Updates to allow Alvys to automatically send location updates via EDI.

<Note>
  <img alt="Location Updates Auto Send toggle and sub-options." />

  *Location Updates Auto Send toggle and sub-options.*
</Note>

After enabling the toggle, configure the following sub-options:

* **Location sources to share:** Choose which sources Alvys will use for location data: Alvys Check Calls; ELD integrations (for example, Samsara, Motive, Geotab); Alvys Driver App; inbound tracking integrations (for example, MacroPoint, Project44).
* **Sharable trip statuses:** Select which load statuses will trigger location updates: **Dispatched or Covered Before Pickup**, **Dispatched After 1st Pickup**, **In Transit**, **Delivered**.
* **Location submission frequency:** Set how often Alvys sends location updates. Options range from every 5 minutes to once per day.
* **Configure Appointments.** Enable the **Auto Send** toggle for Appointments to send appointment EDI updates automatically.

<Note>
  <img alt="Appointments Auto Send toggle and trigger options." />

  *Appointments Auto Send toggle and trigger options.*
</Note>

Choose the trigger option:

* **On Load Accepted:** Sends the appointment EDI immediately when the load is accepted.
* **On Stop Updated:** Sends the appointment EDI only when the appointment time is updated at a stop.

  <Info>
    💡 Use "On Stop Updated" if appointment times are confirmed separately after load acceptance.
  </Info>
* \*\*Configure Arrivals. \*\*Enable the **Auto Send** toggle for Arrivals to send arrival EDI updates automatically when a truck arrives at a stop.

<Note>
  <img alt="Arrivals Auto Send toggle and additional options." />

  *Arrivals Auto Send toggle and additional options.*
</Note>

Additional options for Arrivals:

* **Send Late Arrivals Automatically:** Enable this to auto-send even when the truck arrives late. When enabled, select a Late Reason Code.
* **Grace Period:** Enable this to treat arrivals within a set window as on time. Set the grace window (15 minutes to 2 hours) and select a Reason Code for arrivals within that window.
* Configure Departures. Enable the **Auto Send** toggle for Departures to send departure EDI updates automatically when the truck leaves a stop.

<Note>
  <img alt="Departures Auto Send toggle and additional options." />

  *Departures Auto Send toggle and additional options.*
</Note>

**Additional options for Departures follow the same logic as Arrivals:**

* **Send Late Departures Automatically** (with Reason Code)
* **Grace Period** (with Reason Code and interval selection)

Configure Estimated Delivery (ETA). Enable the **Auto Send** toggle for ETA to send estimated delivery updates automatically.

<Note>
  <img alt="ETA Auto Send toggle and frequency/trigger options." />

  *ETA Auto Send toggle and frequency/trigger options.*
</Note>

Set the **ETA submission frequency**: how often Alvys sends ETA updates. Options range from every 5 minutes to once per day. Additional triggers for ETA:

* **On ETA Updated:** Sends an update when the ETA changes.
* **On ETA Late:** Sends an update when the ETA is after the appointment time. When enabled, select a Reason Code.
* Save the settings. After configuring each event type, save the settings panel to apply the changes.

## Result

After saving, Alvys will automatically send EDI 214 updates to the customer for the event types you enabled. Updates are sent whenever a qualifying event occurs on a load assigned to this customer.

## Variations

**Disabling a setting:** To turn off any auto-send behavior, return to the customer record, open Auto Update Settings, disable the relevant toggle, and save.

**Configuring for multiple customers:** Auto Update Settings are per customer. Repeat these steps for each customer that requires different settings.

## Troubleshooting

### Auto Update Settings section is not visible on the customer profile

1. Confirm the customer has an active EDI integration. The Auto Update Settings section only appears for customers with an active EDI connection.
2. Confirm you have the **"EditCustomer"** permission. Contact your Admin if you need this permission adjusted.
3. If the Auto Update Settings section is still not visible after confirming both of the above, contact Alvys support and provide the customer name and your user role.

### EDI updates are not being sent after enabling a setting

1. Confirm the **Auto Send** toggle for the relevant event type is enabled and the customer record has been saved.
2. Confirm the load is assigned to the customer where the setting is configured.
3. For location updates, confirm at least one location source is selected and the relevant load status is included in the sharable trip statuses list.
4. If updates are still not being sent after confirming all of the above, contact Alvys support and provide the customer name, event type, and load number.

## FAQs

**Q:** Do Auto Update Settings apply to all loads or only specific ones?

**A:** Auto Update Settings apply to all loads where the customer assigned to the load matches the customer profile where the settings are configured.

**Q:** Can I configure different settings for different customers?

**A:** Yes. Auto Update Settings are configured per customer record. Each customer can have different settings for location updates, appointments, arrivals, departures, and ETA.

**Q:** What EDI transaction type does Alvys use for automatic status updates?

**A:** Alvys sends EDI 214 (Shipment Status Update) messages for the event types enabled in Auto Update Settings.

**Q:** Do I need to set up all five event types?

**A:** No. You can enable any combination of the five event types. Enable only the types relevant to your agreement with the customer.

## Go Deeper

* EDI Overview
* [How to enable EDI tender auto-acceptance for a customer](/en/help/integrations/how-to-enable-edi-tender-auto-acceptance-for-a-customer)


# How to configure Trucker Tools Outbound Tracking Updates
Source: https://docs.alvys.com/en/help/integrations/how-to-configure-trucker-tools-outbound-tracking-updates

Configure Trucker Tools outbound tracking on each customer profile in Alvys so automated location updates and check calls are sent whenever loads dispatch.

<Note>
  Send automated tracking updates from Trucker Tools directly to your customers by configuring outbound notifications on each customer profile. Also called Trucker Tools outbound tracking, outbound check calls, or customer tracking emails.
</Note>

## Overview

When you use Trucker Tools for inbound load tracking, you can also send tracking updates automatically to your customers. Configure this once on the customer's profile in Alvys, and the settings apply every time you start a Trucker Tools tracking request on a load for that customer.

Streamline your workflows by setting this up once per customer so updates go out automatically without any manual steps during dispatch.

## Before You Start

* The Trucker Tools inbound integration must be active on your account. See [Trucker Tools Inbound Integration](/en/help/integrations/trucker-tools-inbound-integration).
* A customer profile must already exist in Alvys for the customer you are configuring.

## Steps

1. Navigate to the customer profile and open Auto Updates. In Alvys, open the profile for the customer you want to configure. Go to the **Auto Updates** section and locate the **TruckerTools** card.

   <img alt="Customer profile Auto Updates section with the TruckerTools card." />

   *Customer profile Auto Updates section with the TruckerTools card.*
2. Enable outbound updates. Select the checkbox to enable outbound tracking updates for this customer. The checkbox defaults on or off based on the customer's existing TruckerTools outbound setting. Then configure the following:

   * **Contacts:** Select one or more customer contacts who will receive email notifications.
   * **Email Interval:** Set how often the customer receives tracking email updates.

     <img alt="TruckerTools outbound checkbox enabled with Contacts and Email Interval fields." />

     *TruckerTools outbound checkbox enabled with Contacts and Email Interval fields.*
3. Map the load number. Under **Map Load Number**, choose which load identifier TruckerTools should use in customer communications: **Order #**, **PO #**, or **Alvys Load #**. If needed, enter an optional **Shipper ID** in the field provided.
4. Start a tracking request on the load. When you create or update a Trucker Tools tracking request on a load for this customer, the settings from the customer profile apply automatically to determine how outbound updates are sent. In the tracking form, select **Open Customer Profile in New Tab** if you need to review or update these settings without leaving the load.

<Note>
  <img alt="TruckerTools outbound checkbox enabled with Contacts and Email Interval fields." />

  *TruckerTools outbound checkbox enabled with Contacts and Email Interval fields.*
</Note>

## Result

Trucker Tools sends tracking update emails to the selected customer contacts at the interval you set. The load identifier you mapped appears in the subject and body of those emails, allowing your customers to match updates to their orders.

## FAQs

**Q: Do I need to configure outbound updates on every load, or just once per customer?**

**A:** Configure it once on the customer profile. Every time you start a Trucker Tools tracking request on a load for that customer, those settings apply automatically. You can update the profile settings at any time.

**Q: Can I disable outbound updates for one customer without turning off the integration?**

**A:** Yes. Open the customer's profile, go to Auto Updates, and uncheck the TruckerTools checkbox. This disables outbound updates for that customer only and does not affect other customers or the inbound tracking integration.

**Q: What happens if I do not configure an Email Interval?**

**A:** The Email Interval sets how frequently Trucker Tools sends tracking emails to the customer. Confirm this field has a value before starting a tracking request to ensure updates are delivered.

## Go Deeper

* [Trucker Tools Inbound Integration](/en/help/integrations/trucker-tools-inbound-integration)


# Connect Trackensure to Alvys
Source: https://docs.alvys.com/en/help/integrations/how-to-connect-trackensure-to-alvys

Connect Trackensure ELD to Alvys with an API key to pull live truck locations and driver Hours of Service clocks into the Asset Map and dispatch views.

<Note>
  Connect your Trackensure ELD account to Alvys to pull live truck locations and driver hours of service (HOS) clocks into Alvys automatically.
</Note>

## What This Integration Does

The Trackensure integration connects your Trackensure account to Alvys so that truck location and driver HOS data flow into Alvys automatically. Once connected and mapped, dispatchers can view live truck positions and driver remaining drive time directly in Alvys without switching between systems.

## Prerequisites

Before connecting:

* You have an active Trackensure account with API access enabled.
* You have your Trackensure API key, available in your Trackensure account settings.
* You have the truck number for each truck you want to track, exactly as it appears in Trackensure.
* You have the User ID for each driver you want to track. User IDs are listed on the Drivers page in your Trackensure account.
* Your role in Alvys is Admin, Partner Admin, or Support.

## How to connect

1. Go to **Management > Company Profile > Integrations tab** in Alvys.
2. Locate the Trackensure integration, enter your API key in the field provided, and click **Save**.

<Note>
  <img alt="Integrations tab in Alvys showing the Trackensure section with the API key field and Save button." />

  * Integrations tab in Alvys showing the Trackensure section with the API key field and Save button.\*
</Note>

Alvys confirms the connection once the key is accepted. If the connection fails, verify the API key is correct and active in your Trackensure account settings.

After connecting, map each truck and driver in Alvys to the corresponding record in Trackensure. Each asset must be mapped individually; there is no bulk mapping option.

**Mapping trucks**

1. Go to **Management > Fleets > Trucks** and open the truck record you want to map.
2. In the ELD Integration section, select **Trackensure** from the provider dropdown.
3. In the Integration ID field, enter the truck number exactly as it appears in Trackensure.
4. Click **Save**.

<Note>
  <img alt="Truck record in Alvys showing the ELD Integration section with Trackensure selected, the Integration ID field, and the Save button." />

  \*Truck record in Alvys showing the ELD Integration section with Trackensure selected, the Integration ID field, and the Save button. \*
</Note>

Repeat for each truck you want to track.

**Mapping drivers**

1. Go to **Management > Drivers** and open the driver record you want to map.
2. In the ELD Integration section, click **Add ELD**.

<Note>
  <img alt="Driver record in Alvys showing the ELD Integration section with the Add ELD button.T rackensure Drivers page showing the User ID column listing the ID for each driver." />

  *Driver record in Alvys showing the ELD Integration section with the Add ELD button.T rackensure Drivers page showing the User ID column listing the ID for each driver.*
</Note>

1. Select **Trackensure** from the dropdown.
2. Locate the driver's User ID in Trackensure. Go to the Drivers page in your Trackensure account. The User ID column shows the ID for each driver.

<Note>
  <img alt="Trackensure menu showing Drivers page." />

  *Trackensure menu showing Drivers page.*

  <img alt="Trackensure Drivers page showing the User ID column listing the ID for each driver." />

  *Trackensure Drivers page showing the User ID column listing the ID for each driver.*
</Note>

1. Copy the User ID and paste it into the Integration ID field in Alvys.
2. Click **Save**.

Repeat for each driver you want to track.

## What syncs

Once trucks and drivers are mapped, Alvys pulls data from Trackensure automatically. The following data syncs from Trackensure to Alvys:

* Truck GPS location
* Driver HOS clocks: break, cycle, drive, and shift remaining time

Data refreshes on Alvys's standard polling interval, not in real time.

## Troubleshooting

### Truck location not showing in Alvys

Confirm the truck is powered on and has an active GPS signal in Trackensure. Verify the Integration ID in Alvys matches the truck number in Trackensure exactly: go to **Management > Fleets > Trucks**, open the truck record, and compare the Integration ID to the truck number shown in Trackensure. If neither of those conditions applies, contact Alvys support.

### Driver HOS not showing in Alvys

Confirm the driver has active HOS data in Trackensure. Verify the Integration ID in Alvys matches the driver's User ID in Trackensure exactly: go to **Management > Drivers**, open the driver record, and compare the Integration ID to the User ID shown on the Drivers page in Trackensure. If neither of those conditions applies, contact Alvys support.

## FAQs

**Q: Where do I find my Trackensure driver User IDs?**

**A:** Go to the Drivers page in your Trackensure account. The User ID column displays the ID for each driver. Copy the value exactly and paste it into the Integration ID field in the driver record in Alvys.

**Q: Can I track both truck locations and driver HOS with this integration?**

**A:** Yes. The Trackensure integration supports both truck location tracking and driver HOS clock data in Alvys. Both sync automatically once trucks and drivers are mapped.

**Q: What happens if I enter an incorrect API key?**

**A:** Alvys will not be able to connect to Trackensure and the integration will not be active. Return to **Management > Company Profile > Integrations tab**, re-enter the correct API key, and click **Save**.

## Go Deeper

* Setting Up ELD / Telematics Integrations


# How to enable EDI tender auto-acceptance for a customer
Source: https://docs.alvys.com/en/help/integrations/how-to-enable-edi-tender-auto-acceptance-for-a-customer

Enable EDI tender auto-acceptance for a customer in Alvys so matching load tenders convert into loads automatically based on the lane criteria you define.

<Note>
  EDI tender auto-acceptance automatically accepts incoming load tenders that match your configured lane criteria, converting them directly into loads without manual review. Also called auto-accept tenders or automated tender acceptance.
</Note>

## Overview

When your company receives a high volume of load tenders via EDI from shippers and trading partners, manually reviewing and accepting each one is time-consuming. The auto-acceptance feature lets you define lane criteria so that matching tenders are accepted and built into loads automatically. Tenders that do not match your criteria remain on the Tenders board for manual review, giving you full control over edge cases.

Auto-acceptance is configured per customer and requires two things to be in place before the toggle can be turned on: an active EDI integration for that customer and a default fleet selected on their Company Details page.

## Before You Start

Before enabling auto-acceptance, confirm the following:

* The customer already has an active EDI integration set up in Alvys. You can verify this under **Management > EDI & Visibility**.
* You have the Admin or Partner Admin role. Only users with these roles can access Management and modify customer EDI settings.
* At least one fleet has been created in your company account to serve as the default fleet for auto-accepted loads.

## Steps

**Verify the customer's EDI integration is active.**

In the main navigation, go to **Management > EDI & Visibility**.

Locate the customer whose auto-acceptance you want to enable.

Confirm the integration status shows as active. If the integration is not active, auto-acceptance cannot be enabled and the toggle will not appear on the Company Details page.

<Note>
  <img alt="Management > EDI & Visibility page showing customer integration status as active" />

  *Management > EDI & Visibility page showing customer integration status as active*
</Note>

**Open the customer's Company Details page. From Management > EDI & Visibility, open the customer record to go to their Company Details page.**

**Set a Default Fleet.**

On the Company Details page, locate the **Default Fleet** field.

Click the field and choose a fleet from the suggested list.

Save your selection. The auto-acceptance toggle remains unavailable until a default fleet is set. Once a default fleet is saved, the toggle becomes active and can be switched on or off.

<Note>
  <img alt="Company Details page showing the Default Fleet field and the Auto-Accept Tender toggle in its unavailable state" />

  *Company Details page showing the Default Fleet field and the Auto-Accept Tender toggle in its unavailable state*
</Note>

**Turn on the auto-acceptance toggle.**

On the Company Details page, find the **Auto-Accept Tender** toggle.

Switch the toggle on.

Once enabled, qualifying tenders received for this customer will be automatically accepted and converted to loads without any manual action required.

<Note>
  <img alt="Company Details page with Default Fleet set and the Auto-Accept Tender toggle switched on" />

  *Company Details page with Default Fleet set and the Auto-Accept Tender toggle switched on*
</Note>

## Result

After enabling auto-acceptance, tenders received for this customer that match your lane-defined zip-to-zip criteria are automatically accepted and built into loads. Tenders that do not match your criteria remain on the Tenders board for manual review. If a location is unknown during the auto-acceptance process, you will be prompted to select a location or company profile before the load can be dispatched.

## Variations

* **Turning off auto-acceptance:** Return to the customer's Company Details page and switch the **Auto-Accept Tender** toggle off. Auto-acceptance stops immediately; new tenders for this customer will then require manual review on the Tenders board.
* **Changing the default fleet:** Return to the Company Details page and update the **Default Fleet** field. The new fleet will apply to subsequent auto-accepted tenders.

## Troubleshooting

### Auto-acceptance toggle is not visible on Company Details

1. Confirm the customer has an active EDI integration. Go to **Management > EDI & Visibility** and check the customer's integration status. The toggle only appears when an active EDI integration exists for that customer.
2. If the integration is active and the toggle is still not visible, contact Alvys support.

### Auto-accepted tenders are flagged with an error

When auto-acceptance fails for a tender, the tender is not accepted and appears highlighted in red on the Tenders board with an error message indicating the cause.

1. Go to the Tenders board.
2. Apply the **Auto-Acceptance Error** filter to see only flagged tenders.
3. Review each flagged tender. Common causes include an unknown pickup or delivery location, a lane that does not match your configured zip-to-zip criteria, or a validation error on the tender data.
4. For each flagged tender, either accept or reject the load manually after resolving the issue. If the location is unknown, you will be prompted to select a location or company profile before dispatching.
5. If the error message does not clearly indicate the cause and you cannot resolve it manually, contact Alvys support with the tender ID and the error message shown.

<Note>
  <img alt="Tenders board with Auto-Acceptance Error filter applied, showing flagged tenders highlighted in red" />

  *Tenders board with Auto-Acceptance Error filter applied, showing flagged tenders highlighted in red*
</Note>

## FAQs

**Q: What happens to tenders that do not meet my auto-acceptance criteria?**

**A:** They remain on the Tenders board for manual review, giving you full control over which loads to accept.

**Q: Can I turn off auto-acceptance for a specific customer without affecting other customers?**

**A:** Yes. The auto-acceptance toggle is configured per customer on their Company Details page. Turning it off for one customer has no effect on others.

**Q: Why do some tenders fail auto-acceptance even when the toggle is on?**

**A:** Common reasons include an unknown pickup or delivery location, a tender that does not match your configured zip-to-zip lane criteria, or a validation error in the tender data. These tenders are flagged in red on the Tenders board with an error message.

**Q: Does auto-acceptance work without an active EDI integration?**

**A:** No. The auto-acceptance toggle only appears and can only be enabled when the customer has an active EDI integration. If no integration is active, the toggle will not be visible on the Company Details page.

**Q: Is a default fleet required to enable auto-acceptance?**

**A:** Yes. The auto-acceptance toggle cannot be switched on until a default fleet is selected on the customer's Company Details page. The default fleet is used to build the load when a tender is auto-accepted.

## Go Deeper

* EDI Overview


# How to Manage Fuel in Alvys
Source: https://docs.alvys.com/en/help/integrations/how-to-manage-fuel-in-alvys

This article walks you through the general fuel workflow, from integration setup to report uploads and how it all ties into your drivers.

## Overview

Fuel is one of the biggest recurring expenses in trucking. This article walks you through the complete fuel workflow in Alvys (fuel card setup, fuel transaction import, fuel deductions, fuel reporting): connecting your fuel card provider, linking cards to drivers, and importing fuel transactions, either automatically or by manual upload.

Alvys supports fuel card integrations with providers like EFS, Comdata, TCS, QuikQ (Love's), and Compass, offering automatic and manual fuel uploads, deductions, and reporting tied directly to your drivers. This guide covers the end-to-end fuel workflow: from connecting your provider to importing transactions into the Fuel Report.

## Before you start

Before setting up fuel management in Alvys:

* You must have active fuel card credentials from your provider (EFS, Comdata, TCS, QuikQ/Love's, or Compass).
* Some providers (such as QuikQ and EFS) require you to contact their support team and request API credentials or enable partner access before the Alvys integration will work. Complete that step with your provider before proceeding.
* Fuel cards must be linked to individual drivers before transaction matching will work.
* All users can connect integrations, link fuel cards, and import fuel transactions.

## Steps

### Connect your fuel provider

1. Go to **Management > Integrations**.
2. Select the **Fuel** category.
3. Find your provider and click the **Pencil** (edit) button.
4. Enter the required credentials provided by your fuel card company.
5. Choose the **subsidiaries** this provider should apply to.
6. Click **Save**.

<Note>
  <img alt="Upload fuel-provider-integration-setup.gif here. This image shows the Integrations page with the Fuel category selected, the pencil icon being clicked, and the credential entry form being completed and saved" />

  *Upload fuel-provider-integration-setup.gif here. This image shows the Integrations page with the Fuel category selected, the pencil icon being clicked, and the credential entry form being completed and saved*
</Note>

For provider-specific setup steps, refer to the integration guide for your provider (EFS, Comdata, TCS, QuikQ/Love's, or Compass).

### Link fuel cards to drivers

Once the integration is active, Alvys must know which driver is using which fuel card. Transactions are matched to drivers using card numbers, so this step must be completed before importing.

1. Go to **Assets > Drivers**.
2. Select a driver and open their profile.
3. Click the **Fuel Card Numbers +** button.
4. Enter the following:

   * The **fuel card number** (some providers like TCS require only partial numbers, such as the last 4 digits, so check your provider's formatting guidelines).
   * The **provider** (for example: Comdata, EFS, Love's).
   * Whether fuel should be **discounted** or **deducted** from the driver's pay. Note: discount information is imported directly from your fuel provider and cannot be set to a custom value within Alvys.
5. Click **Save**.
6. Repeat for all drivers using fuel cards.

<Note>
  <img alt="This image shows a driver profile open with the Fuel Card Numbers + button clicked" />

  *This image shows a driver profile open with the Fuel Card Numbers + button clicked*
</Note>

### Import fuel transactions

You can bring fuel data into Alvys in two ways: **automatic sync** (if your provider supports it) or **manual import** from a provider report file.

Manual file import is available when you have an active integration for **Compass**, **TCS**, **Pilot Flying J**, or **EFS (CSV upload)**. Download the transaction report from your provider's portal first, then import it from the Fuel page.

1. Go to **Assets** and open **Fuel**.
2. Click the **⋮** menu in the page header (next to **Add Transaction**).
3. Select **Import Report**.
4. Choose your **Integration type** (for example, Compass or TCS).
5. Optional: check **Update existing transactions if duplicates are found** when you are re-importing a file and want Alvys to update matching transactions instead of creating duplicates.
6. Upload your CSV or Excel file and follow the import assistant to map your file columns to Alvys fields.
7. Review any warnings or errors, then finish the import.

### Map columns to the fuel import template

After you upload your file, Alvys opens an import assistant where you match each column in your provider report to an Alvys template field. You only need to complete this mapping the first time you import a given file layout; Alvys can reuse your mapping on later uploads.

The fuel import template has 16 Alvys fields. Some require you to **map** a column from your file (even when individual cells are blank). Others only need a value on each row when your file includes that data.

| Template field          | Map a file column? | Value required on every row? | Notes                                                                                                                                                                                           |
| ----------------------- | ------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transaction date**    | Yes                | Yes                          | Must be a valid date. Time is accepted when your file includes it.                                                                                                                              |
| **Net amount**          | Yes                | Yes                          | The charge for the line. Rows with zero or no amount are skipped at import.                                                                                                                     |
| **State**               | Yes                | No                           | Map this field even if your file has no state column — leave cells blank when state is missing. If you provide a value, use a US, Canadian, or Mexican state code or name (not a full address). |
| **Product / fuel type** | Yes                | No                           | Picklist in the import assistant. Blank values import as **Misc Truck Expense** (you see a warning).                                                                                            |
| **Quantity (gal)**      | Yes                | No                           | Gallons purchased. Blank values import as zero.                                                                                                                                                 |
| **Truck stop / chain**  | Yes                | No                           | Merchant or stop name. Map the column even when some rows are blank.                                                                                                                            |
| **Card number**         | No                 | No                           | Used to match a driver or truck. Rows without a card number still import but may not link to a driver.                                                                                          |
| **Transaction ID**      | No                 | No                           | Provider reference number. Helps detect duplicates and supports re-import updates.                                                                                                              |
| **Driver name**         | No                 | No                           | Informational only. Driver matching uses the card number on the driver profile.                                                                                                                 |
| **Unit / vehicle #**    | No                 | No                           | Used to match a truck when the card number does not match.                                                                                                                                      |
| **Price / gallon**      | No                 | No                           | Per-gallon price when your file includes it.                                                                                                                                                    |
| **Discount**            | No                 | No                           | Provider discount amount when your file includes it.                                                                                                                                            |
| **Fee**                 | No                 | No                           | Additional fees when your file includes them.                                                                                                                                                   |
| **City**                | No                 | No                           | City where the purchase occurred.                                                                                                                                                               |
| **Store / location #**  | No                 | No                           | Provider location identifier when available.                                                                                                                                                    |
| **Country**             | No                 | No                           | Defaults to **US** when not provided.                                                                                                                                                           |

<Tip>
  **Errors** block a row from importing (for example, an invalid date, unparseable amount, or invalid state value). **Warnings** let the row import but flag something to review (missing card number, blank fuel type, duplicate transaction, or zero amount).
</Tip>

<Tip>
  If your file has no state column, still map **State** in the template and leave those cells empty. If your file has no truck stop name column, map **Truck stop / chain** to the closest available column or an empty column so the template is complete.
</Tip>

<Note>
  <img alt="This image shows the Fuel Report page with the page actions menu open" />

  *Fuel page with the header actions menu*
</Note>

<Note>
  <img alt="Image showing Import Report option" />

  *Import Report in the page actions menu*
</Note>

Alvys matches imported transactions to drivers using the fuel card numbers on driver profiles. Rows without a matching card number still import, but they are not linked to a driver until you add or correct the card number and re-import (with **Update existing transactions** checked if you are updating the same file).

For provider-specific download and upload steps, see the integration guide for your fuel card company (Compass, TCS, QuikQ/Love's, or EFS).

If your provider supports automatic upload (such as EFS or Love's), Alvys can pull transactions daily on a scheduled basis, typically around 1 to 2 AM EST. Once enabled:

<Warning>
  ⚠️ Alvys scans for duplicate transactions during automatic import. · Manual changes made directly in your provider's portal between import jobs may cause Alvys to not recognize a transaction, which can result in a near-duplicate being imported. · Review your Fuel Report after each import to catch any duplicates.
</Warning>

## Result

After completing these steps:

* Your fuel provider is connected and active for the selected subsidiaries.
* Each driver's fuel card is linked to their profile.
* Fuel transactions appear on **Assets > Fuel**, matched to the correct drivers where card numbers align.
* If automatic sync is enabled, transactions are imported daily without manual action.

## Variations

Fuel providers use different time formats: some store transactions in UTC, others in local time. Alvys standardizes all transaction times to UTC but displays them in your local time zone based on your user profile settings. This keeps filtering and reporting accurate when working with multiple providers across time zones.

If you notice transactions appearing to fall outside your expected date range, expand your date filter by plus or minus one day to catch edge-case transactions.

## Troubleshooting

### Transactions are not appearing in the Fuel Report

1. Confirm the driver's fuel card number is entered correctly under their profile (Assets > Drivers > fuel card). Check the formatting your provider requires (partial vs. full card number).
2. Confirm the integration credentials are saved under Management > Integrations > Fuel for the correct subsidiary.
3. For automatic sync, allow up to 24 hours after enabling the integration for the first transactions to appear.
4. For manual imports, confirm you selected the correct **Integration type**, mapped all required template fields (**Transaction date**, **Net amount**, **State**, **Product / fuel type**, **Quantity (gal)**, and **Truck stop / chain**), and uploaded a file from that provider's portal.
5. If none of the above applies, contact Alvys support with the provider name, affected card number, and the date range of the missing transactions.

### Duplicate transactions appear in the Fuel Report

This occurs when manual changes are made directly in the provider portal between automatic import jobs. Alvys does scan for duplicates programmatically, but provider-side changes made between imports can result in near-duplicates being imported.

Review and delete the duplicate entry from the Fuel Report. If duplicates continue to appear, contact Alvys support.

## FAQs

**Q: Which fuel providers does Alvys integrate with?**

**A:** Alvys integrates with EFS, Comdata, TCS, QuikQ (Love's), and Compass. Each provider has its own setup requirements, so refer to the provider-specific integration guide for credential and access details.

**Q: Does Alvys support both automatic and manual fuel transaction imports?**

**A:** Yes. Providers such as EFS and Love's support automatic daily sync. Compass, TCS, Pilot Flying J, and EFS (CSV) support manual imports from **Assets > Fuel** using **Import Report**.

**Q: Can I connect multiple fuel providers at the same time?**

**A:** Yes. You can connect multiple providers under Management > Integrations > Fuel, assigning each to the applicable subsidiaries.

**Q: What happens if a fuel card transaction cannot be matched to a driver?**

**A:** If the card number on the transaction does not match any card number on a driver profile, the transaction is not linked to a driver. Alvys may still match a truck using **Unit / vehicle #**. Confirm card numbers and unit numbers are correct on driver and truck profiles, then re-import or contact Alvys support.

**Q: Can I re-import the same fuel file to fix or update transactions?**

**A:** Yes. Use **Import Report** again and check **Update existing transactions if duplicates are found**. Alvys updates matching rows instead of creating duplicates. Transactions that are already paid or settled on a driver statement are not overwritten. Leave the box unchecked if you only want to add new rows.

**Q: Is a state or province required on every imported fuel row?**

**A:** No. You must map the **State** template field, but individual rows can leave state blank. If you provide a state value, it must be a valid US, Canadian, or Mexican state code or name — full addresses in the state column are rejected.

**Q: Can I set a custom fuel discount rate in Alvys?**

**A:** No. Discount information is imported directly from your fuel provider. It is not possible to set a custom discount value within Alvys.


# How to set up and use factoring in Alvys
Source: https://docs.alvys.com/en/help/integrations/how-to-set-up-and-use-factoring-in-alvys

This article explains how factoring works in Alvys on a general level, including setup, invoicing, batch submission, and status tracking.

<img alt="Factoring on Alvys article banner" />

*Factoring on Alvys article banner*

<Note>
  This article explains the complete 10-step workflow for setting up and using factoring in Alvys, from configuring your Notice of Assignment and connecting your provider through generating invoices, submitting batches, and uploading purchase and payment reports.
</Note>

## Overview

Factoring in Alvys lets you sell your outstanding invoices to a third-party factoring company for faster payment. This article covers the complete setup and workflow: configuring your Notice of Assignment, adding the Factoring invoicing method, connecting your provider, generating invoices, submitting batches, and uploading purchase and payment reports. Also referred to as invoice factoring, accounts receivable financing, invoice funding, and FTP batch submission.

Factoring is a financial arrangement in which you sell your outstanding invoices to a factoring company. The factoring company advances most of the invoice value upfront and collects payment from your customers directly. Alvys supports the complete factoring lifecycle: from initial setup through load delivery, invoice generation, batch submission, and payment reconciliation, regardless of which factoring provider you use.

## Prerequisites

Confirm the following before beginning:

* You hold an Admin, Partner Admin, or Support role to configure Company Profile settings and manage integrations (items 1–3).
* You hold the **"Billing"** permission to release loads, generate invoices, submit batches, and upload reports (items 4–10).
* Your subsidiaries are created in Alvys before configuring the integration. Each subsidiary that uses factoring must be configured separately.
* You have the Notice of Assignment text from your factoring company. Your provider supplies the exact wording.
* You have the credentials or login information required by your factoring provider. The credential type varies by provider; refer to the dedicated integration article for your provider for details.

## Steps

1. **Configure your Notice of Assignment.** The Notice of Assignment (NOA) declares to your customers that your factoring company has the right to collect payment on your behalf. It must appear on every invoice submitted through factoring.

   * Click the Profile button in the upper right corner and select Management to open your Company Profile.
   * In the Document Configuration section, click the plus sign (+) button. The Manage Important Info window will appear.
   * In the drop-down menu, select Notice of Assignment.
   * Paste the NOA text provided by your factoring company into the text box.
   * Click Save.
2. **Add the Factoring invoicing method.** Factoring must be selected as the invoicing method before loads can be submitted to a factoring company. You can set this at the subsidiary level (applies to all customers under that subsidiary) or override it for a specific customer.

   * To set the invoicing method globally for a subsidiary: go to Company Profile and open Invoicing Settings.
   * Set the delivery method to Factoring Company.
   * Enable AutoMerge. AutoMerge is required when using factoring: it automatically combines the Invoice, Proof of Delivery, and Rate Confirmation into a single file, which factoring companies require as the submission format.
   * Click Save.
   * To set the invoicing method for a specific customer: open the customer's profile, go to the Invoicing tab, set the invoicing method to Factoring Company for that customer, and click Save.

     <img alt="Screenshot showing the Factoring Company invoicing method selection in Alvys settings" />

     *Screenshot showing the Factoring Company invoicing method selection in Alvys settings*
3. **Connect to your factoring provider.**

   * Navigate to Management and open the Integrations page.
   * Under the Factoring section, locate your provider.
   * Click the pencil icon next to your provider's name to open the configuration window.
   * Follow the provider-specific steps to enter credentials or complete authentication. Refer to the dedicated article for your factoring provider for detailed steps.

     Alvys currently supports the following factoring providers and connection types: Apex Capital (API) · OTR Solutions (API) · Saint Johns Capital Factoring (API) · TAFS (API) · TruFunding (API) · Capital Depot (Manual / Download) · Wex FleetOne (Manual / Download) · WinFactor FTP (FTP) · Compass Funding Solutions (FTP) · RTS (FTP) · Sunbelt Finance (FTP) · Triumph (FTP) · Wex FleetOne FTP (FTP).
4. **Create and deliver a load.** Create a load in Alvys and assign a carrier. Move the load through its standard lifecycle until it reaches **Delivered** status. Collect all required documents (Proof of Delivery and Rate Confirmation) before proceeding.
5. **Release the load.** Once the load is delivered and all documents are received, move the load to **Released** status. **Released** indicates the load is ready for invoicing.
6. **Generate the invoice.**

   * Open the released load.
   * Click Generate Invoice. Alvys merges the required documents (Customer Rate Confirmation, Proof of Delivery, and Invoice) into a single file. The load moves to **Queued** status, meaning the invoice has been created and the load is ready for submission to your factoring company.

     <img alt="Load in Queued status after generating the invoice" />

     *Load in Queued status after generating the invoice*
7. **(Optional) Run a credit check.** Some API-based integrations support broker credit checks; OTR Solutions and Saint Johns Capital Factoring are two examples. Credit checks may run automatically at invoice time if the previous check is older than 24 hours. You can also trigger a check manually from the Customer Profile or from the Load Details page. Loads with a declined credit check may be blocked from batch submission depending on your provider's configuration.
8. **Submit the batch to your factoring company.**

   * Navigate to Accounting > Factoring Upload.
   * Select the Subsidiary for which you are submitting.
   * Select all loads in **Queued** status that you want to include in the submission.
   * Click Submit Batch.
   * Do not close this page or navigate away until the submission completes. Navigating away during submission may interrupt the process.

     How submission works depends on your provider type: for API providers (Apex Capital, TAFS, OTR Solutions, Saint Johns Capital Factoring, TruFunding) Alvys submits the data directly to your provider through the integration · for FTP providers (WinFactor, Triumph, Wex FleetOne FTP, Compass Funding Solutions, RTS, Sunbelt Finance) Alvys transmits the batch file to your factoring company automatically via FTP · for manual providers (Capital Depot, Wex FleetOne) Alvys generates a batch file that you download and submit to your provider yourself.
9. **Upload your Purchase Report.** After your factoring company finances the invoices, download the purchase report from your factoring portal and upload it to Alvys to update the load statuses.

   * Download the purchase report from your factoring provider's portal. The report name and export steps vary by provider; refer to your provider-specific integration article for the exact location and file format.
   * Go to Reports > Financial Reports > Factoring.
   * Click the Upload Purchase Report button in the bottom right corner of the page.
   * Drag and drop the report file onto the upload area, or click the area to select the file from your device.
   * Click Upload.
   * Do not close the page until processing is complete. Processing may take several seconds to a few minutes depending on file size. Loads included in the purchase report will be updated to **Financed** status.
10. **Upload your Payment Report.** When the customer or broker pays the factoring company in full, download the payment report from your factoring portal and upload it to Alvys to mark the loads as fully settled.

    * Download the payment report from your factoring provider's portal. Refer to your provider-specific integration article for the exact report name and steps.
    * Go to Reports > Financial Reports > Factoring.
    * Click the Upload Payment Report button.
    * Drag and drop the file onto the upload area, or click the area to select the file from your device.
    * Click Upload.
    * Do not close the page until processing is complete. Loads included in the payment report will be updated to **Completed** status.

## Result

After completing the full workflow, your load will have moved through these statuses in order:

* **Released:** The load is delivered and all documents are received; the load is ready for invoicing.
* **Queued:** The invoice has been generated; the load is ready for submission to the factoring company.
* **Invoiced:** The invoice has been submitted to the factoring company or directly to the customer.
* **Financed:** The factoring company has purchased and funded the invoice.
* **Completed:** Full payment has been received and the factoring cycle is closed for that load.

For provider-specific differences, including credential types, FTP setup, report names, portal navigation, schedule number lookup (Apex Capital), and reference number requirements (Wex FleetOne FTP), refer to the dedicated integration article for your factoring company.

## Troubleshooting

### Load does not appear in Factoring Upload

1. Confirm the load status is **Queued**. Only loads in **Queued** status appear in the Factoring Upload queue. If the load has not had an invoice generated, generate the invoice first.
2. Confirm the load's invoicing method is set to Factoring Company. Check the customer's Invoicing tab in their profile, or check Invoicing Settings in Company Profile for the subsidiary.
3. Confirm you have selected the correct subsidiary on the Factoring Upload page. Submissions are per subsidiary.
4. Contact Alvys support if none of the above reasons apply.

### Batch submission fails or does not complete

1. Stay on the Factoring Upload page for the full duration of the submission. Closing the page or navigating away during submission will interrupt the process.
2. Check your integration status in Management > Integrations. If the integration is inactive or credentials have expired, re-enter your credentials and retry.
3. For FTP providers, confirm with your factoring company that the FTP server is available and your credentials are still valid.
4. Contact Alvys support if the submission continues to fail after checking credentials.

### Purchase or Payment Report upload does not process

1. Confirm the file format matches what your provider requires. Most providers require a .csv file; check your provider-specific integration article for the required format.
2. Confirm you downloaded the report from the correct page in your factoring provider's portal. Each provider uses a specific page or report type for purchase and payment data; refer to your provider-specific integration article for the exact location and export steps.
3. Contact Alvys support if the upload continues to fail after checking the file and source.

## FAQs

**Q:** What do I need to do to switch to a different factoring company?

**A:** Open your current integration in Management > Integrations and click Deactivate to remove the existing connection. Then follow the setup items (configure NOA, add the Factoring invoicing method, and connect to your provider) to configure your new factoring provider.


# How to update a stop with shared EDI timestamps ?
Source: https://docs.alvys.com/en/help/integrations/how-to-update-a-stop-with-shared-edi-timestamps

Manage EDI stop updates directly from the stop card. Record your operational times while streamlining what gets communicated to shippers.

<Note>
  On EDI-enabled loads, Alvys shows separate timestamp fields for your internal operational record and the timestamp shared externally with the shipper via EDI. Use the shared fields to control what gets communicated to the shipper without affecting your operational load record.
</Note>

## Overview

On EDI-enabled loads, changing a stop's status to **Arrived**, **Picked Up**, or **Empty** reveals two sets of timestamp fields on the stop card: one for your operational record inside Alvys, and one for the timestamp shared externally with the shipper over EDI (outbound visibility, EDI 214).

The fields interact in a specific way: updating your operational arrival or departure time automatically refreshes the corresponding shared EDI time. Updating the shared EDI time does not change your operational time. This protects your internal load record while giving you full control over what gets communicated to the shipper.

Synonyms: EDI stop update, share arrival, share departure, outbound visibility, stop card EDI fields, EDI 214 update.

## Before you start

Before using the shared EDI timestamp fields, confirm the following:

* The load must have an active EDI integration for its assigned customer. The share arrival and share departure fields appear only on loads where outbound visibility sharing is enabled. If the fields are not visible, the load is not EDI-enabled for that customer.
* Your account must have the **"EDI Share"** permission. This permission is located in the Tendering category of the user permissions panel (Management > Company Profile > Users). Without it, the EDI sharing fields do not appear on the stop card even if the load is EDI-enabled.
* Waypoints are not included in EDI updates. The share arrival and share departure fields appear only at pickup and delivery stops.

## How to update a stop

* Open the load. Go to **Loads and Trips** and open the load you need to update.
* Open the stop card. Expand the Trips / Stops section and click the pickup or delivery stop you want to update.
* Change the stop status to **Arrived**. Two additional sections appear below the standard arrival timestamp:

**Arrived:** Your operational arrival time, saved to the Alvys load record.

**Share Arrival:** The timestamp sent to the shipper via EDI. Pre-filled from your operational arrival time.

**Reason:** Pre-filled based on your EDI integration's configuration (default is Normal Status). Adjust if the situation requires a different code.

<Note>
  <img alt="Stop card showing the Arrived status with Share Arrival fields and Reason dropdown" />

  *Stop card showing the Arrived status with Share Arrival fields and Reason dropdown*
</Note>

**Enter timestamps and save:**

* Enter the **Arrived** date and time (your operational record).
* Review the **Share Arrival** date and time. Adjust it if the time you want to communicate to the shipper differs from your operational time.
* Confirm or change the **Reason**.
* Click **Save**.

The operational arrival time is saved to the load record in Alvys. The shared EDI timestamp is transmitted to the shipper. Both timestamps are stored independently: the operational time is visible internally in Alvys, and the shared time is included in the EDI message sent to the shipper.

## Variations

### Depart from a stop

Change the stop status to **Picked Up** (at a pickup stop) or **Empty** (at a delivery stop). Departure fields appear below the standard departure timestamp:

* **Departed:** Your operational departure time.
* **Share Departure:** The timestamp sent to the shipper via EDI. Pre-filled from your operational departure time.
* **Reason:** Pre-filled from your integration's configuration.
* Enter the **Departed** date and time, review or adjust the **Share Departure** date and time, confirm the **Reason**, and click **Save**.

<Note>
  <img alt="Stop card showing the Share Departure fields" />

  *Stop card showing the Share Departure fields*
</Note>

### Skip directly to Picked Up or Empty

If you change a stop's status from **Covered** directly to **Picked Up** or **Empty**, both arrival and departure fields appear together. Enter the actual times for arrival and departure, review or adjust both shared EDI times, and click **Save**.

<Note>
  <img alt="Stop card showing both Share Arrival and Share Departure fields together" />

  *Stop card showing both Share Arrival and Share Departure fields together*
</Note>

## Troubleshooting

### Share Arrival and Share Departure fields are not visible on the stop card

1. Confirm the load is EDI-enabled. These fields appear only on loads where outbound visibility sharing is active for the assigned customer. Check the customer's company profile to confirm EDI integration is configured and enabled.
2. Confirm your account has the **"EDI Share"** permission. Go to Management > Company Profile > Users, open your user profile, scroll to the Tendering permissions section, and verify **"EDI Share"** is checked. Contact your Admin if you need the permission granted.
3. Confirm the stop is a pickup or delivery stop, not a waypoint. EDI timestamp fields do not appear on waypoints.
4. If the load is EDI-enabled, your permission is confirmed, and the stop is a pickup or delivery stop, but the fields still do not appear, contact Alvys support.

### Shared EDI time did not update after saving

1. Confirm the stop status change was saved successfully. Refresh the stop card and verify the new status is displayed.
2. If the shared EDI time still reflects the previous value after refreshing, allow a few minutes for the EDI message to process, then check again. If the issue persists after waiting, contact Alvys support.

## FAQs

**Q: Do I need to fill in both the operational time and the shared EDI time?**

**A:** The operational Arrived or Departed date and time is required. The shared EDI time is pre-filled from your operational entry and can be left as-is or adjusted before saving.

**Q: What happens if I change the operational arrival or departure time?**

**A:** The shared EDI time updates automatically to match the new operational time.

**Q: What happens if I change only the shared EDI time?**

**A:** The operational time remains unchanged. Only the timestamp sent to the shipper over EDI is updated.

**Q: Can I still use the manual EDI update panel?**

**A:** Yes, the manual EDI update panel is still available. For most stop updates on EDI-enabled loads, using the stop card fields directly is faster and keeps your operational and EDI records in sync.

**Q: Does this apply to waypoints?**

**A:** No. Waypoints are not included in EDI updates. Share Arrival and Share Departure fields appear only at pickup and delivery stops.

**Q: What is the Reason field for?**

**A:** The Reason field sets the shipment status reason code included in the EDI message sent to the shipper. It is pre-filled based on your integration's default configuration (typically Normal Status). Adjust it when the situation requires a specific code.

## Go Deeper

* [How to configure EDI Auto Update Settings](/en/help/integrations/how-to-configure-edi-auto-update-settings)


# iPass Toll Integration
Source: https://docs.alvys.com/en/help/integrations/ipass-toll-integration

Import iPass toll transactions into the Alvys Toll Report by uploading a CSV from your iPass account; Alvys matches charges to trucks via transponder ID.

<Note>
  The iPass toll integration lets you import toll transaction data from your iPass account into the Alvys Toll Report by downloading a CSV file from iPass and uploading it to Alvys.
</Note>

## Overview

The iPass toll integration lets you import toll transaction data from your iPass account into the Alvys Toll Report so you can view and manage toll charges (toll transponder activity) alongside your fleet operations. This is a one-way, manual import: you download a CSV file from your iPass account and upload it to Alvys. Alvys matches toll transactions to trucks using the transponder ID stored in each truck's Pass Details.

<Info>
  💡 This integration is sometimes called the iPass toll transponder import, toll feed, or toll CSV upload. · There is no automatic or scheduled sync between iPass and Alvys.
</Info>

## Prerequisites

Before configuring this integration, confirm the following:

* You have **"Admin"**, **"Support"**, or **"Partner Admin"** access in Alvys (set on your user role in the Company Profile).
* Your trucks have been added to Alvys.
* You have access to your iPass account and can download CSV transaction files.
* You have the transponder ID for each iPass device assigned to your trucks.

## How to connect

1. Click your username in the bottom left corner of Alvys, then select **Management**.
2. Select the subsidiary you want to integrate with iPass.
3. Click the blue **Integrate** button.
4. Scroll down to the **Tolls** section.
5. Select **iPass** from the list of integrations.
6. Select all subsidiaries that will use iPass for toll tracking.
7. Click **Save**.
8. Add a transponder ID to each truck so toll data is attributed to the correct asset:
9. From the blue Alvys toolbar, select **Assets**, then choose **Trucks**.
10. Find and click the truck that uses the transponder you want to add.
11. Scroll down to the **Pass Details** section.
12. Select whether or not to deduct tolls for this truck.
13. Choose **iPass** in the **Issued By** field.
14. Enter the transponder ID in the **Pass Number** field.
15. Click **Add Pass**.
16. Repeat for every truck that uses an iPass transponder.
17. Upload a toll report from iPass:
18. Log in to your iPass account and download a CSV file of your toll transaction data.
19. From the blue Alvys toolbar, select **Reports**, then navigate to **Toll Report**.
20. Click the blue upload button on the Toll Report page.
21. In the pop-up window, add the CSV file from your iPass account.
22. Upload the file. Once the upload completes successfully, the transactions appear in your Toll Report filtered by the date range of the uploaded file.

## What syncs

The iPass integration imports toll transaction data from your iPass account into the Alvys Toll Report.

* **Direction:** One-way, iPass to Alvys, via manual CSV upload. No data syncs automatically.
* **Matching:** Alvys matches toll transactions from the uploaded CSV to trucks using the transponder ID stored in the Pass Details section of each truck's profile. The transponder ID in Alvys must match the transponder ID in the iPass CSV export exactly for transactions to be correctly attributed.
* **File format:** Only standard iPass CSV export files are supported. Custom or reformatted files may not upload correctly.

<Warning>
  ⚠️ Transponder IDs must be entered individually on each truck's profile; bulk assignment is not supported. · Toll transactions whose transponder ID in the CSV does not match a truck profile in Alvys will not be attributed to any asset. · Alvys detects and skips duplicate transactions, so re-uploading the same file does not create duplicate charges.
</Warning>

## Troubleshooting

### Toll transactions are not appearing after upload

Confirm that each truck involved in the transactions has a transponder ID entered in its Pass Details section and that **iPass** is selected as the provider. The transponder ID in Alvys must match the ID in the iPass CSV file exactly.

### iPass does not appear as an option in the Integrations list

Confirm the iPass integration is active for the correct subsidiary in Management > Integrations > Tolls. If iPass is not listed, contact Alvys support; the integration may need to be enabled for your account.

### The CSV file fails to upload

Confirm the file is a standard CSV export from your iPass account and has not been reformatted or modified. If the file structure has been changed, re-export from iPass and upload the original file.

## FAQs

**Q: Is the iPass integration automatic or manual?**

**A:** The iPass integration is manual. You download a CSV from your iPass account and upload it to Alvys whenever you want to import toll data.

**Q: How often should I upload toll reports?**

**A:** This depends on your business needs and settlement schedule. Many teams upload weekly or monthly to keep toll data current for driver settlements and accounting.

**Q: What happens if I upload the same toll transactions twice?**

**A:** Alvys detects duplicate transactions and does not import them again, so there is no risk of duplicate toll charges from re-uploading the same file.

**Q: Can I add transponder IDs to trailers as well as trucks?**

**A:** Yes. While transponders are typically mounted on trucks, you can add Pass Details to any asset type in Alvys if needed.

**Q: Where do I find the transponder ID for my trucks?**

**A:** The transponder ID is the ID number printed on the iPass transponder device or visible in your iPass account under your asset or device list.


# Connect KSK ELD to Alvys
Source: https://docs.alvys.com/en/help/integrations/ksk-eld-eld-telematics-integration

Connect KSK ELD to Alvys to pull live truck locations and driver Hours of Service into dispatch, using a KSK API token for one-way telematics sync.

<Note>
  KSK ELD is a telematics provider that connects with Alvys to bring real-time truck locations and Hours of Service (HOS) status into your dispatch workflow. This integration is also known as KSK ELD, electronic logging device, or fleet tracking.
</Note>

## What This Integration Does

Connecting KSK ELD to Alvys allows your dispatch team to view current truck locations and driver HOS remaining-time clocks without leaving Alvys.

Trailer tracking and IFTA mileage are not supported by KSK ELD. Only truck assets with KSK ELD devices will appear in tracking.

## Prerequisites

Before connecting, confirm you have the following:

* An active KSK ELD account with API access
* Your KSK ELD API key
* The Admin, Partner Admin, or Support role in Alvys

## How to connect

### Step 1: Generate an API token in KSK ELD

1. Log into your KSK ELD account.
2. Go to **Management > API Tokens**.
3. Click **Generate Token**.
4. Enter **"Alvys Integration"** as the token name and click **OK**.
5. Copy the token. You will need it in the next step.

### Step 2: Connect KSK ELD in Alvys

1. Click your profile icon in the lower-left corner of Alvys to open **Company Profile**.
2. Select the subsidiary you want to configure and click the **Integrations** tab.
3. Expand the **ELD** section and click the pencil icon on the KSK ELD card.
4. Enter your KSK ELD API token and click **Save**.
5. Alvys will validate your credentials. Once confirmed, the integration status changes to active.

   After connecting, the following data is pulled from KSK ELD into Alvys:

   * **Truck location:** Current GPS coordinates for each truck with a KSK ELD device
   * **HOS clocks:** Remaining time values for each driver's HOS limits — these are countdown clocks showing time remaining

Additional detail data such as odometer readings and fuel levels is also pulled when the device's identifier is a numeric value. If the device uses a non-numeric identifier, basic location and HOS data will still display; only the additional detail fields (odometer, fuel) may not appear.

## Map assets in Alvys

After connecting, link each truck or trailer in Alvys to its KSK ELD asset ID so location data flows correctly.

1. Go to **Assets** in the left menu and select **Trucks** or **Trailers**.
2. Double-click the asset you want to configure.
3. Scroll down to the **ELD Integrations** section and click **Add Integration**.
4. Select **KSK ELD** from the dropdown.
5. Find your KSK ELD asset ID from the URL when viewing that asset in your KSK ELD account. For example, if the URL is [app.kskeld.com/client/vehicle/25236](http://app.kskeld.com/client/vehicle/25236), the ID is **25236**.
6. Enter the asset ID in the **Integration ID** field and click **Save**.

Repeat for each truck or trailer you want to track.

## Map drivers in Alvys

To view driver Hours of Service in loads and the Dispatch Planner, link each driver to their KSK ELD driver ID.

1. Go to **Assets** in the left menu and select **Drivers**.
2. Double-click the driver you want to configure.
3. Find the **ELD Providers** section and click **Add ELD**.
4. Select **KSK** from the dropdown.
5. Find your KSK ELD driver ID from the URL when editing that driver in your KSK ELD account. For example, if the URL is [app.kskeld.com/client/driver/25236/details](http://app.kskeld.com/client/driver/25236/details), the driver ID is **25236**.
6. Enter the driver ID in the **Integration ID** field and click **Save**.

Repeat for each driver who uses KSK ELD for their Hours of Service.

## What syncs

Alvys requests updated data from KSK ELD on a regular basis. Truck locations and HOS clocks reflect the most recent values reported by the device.

* **Truck location:** Current GPS coordinates for each truck with a KSK ELD device.
* **HOS clocks:** Remaining-time countdown values for each driver's HOS limits.
* **Odometer and fuel level:** Pulled only for devices with numeric identifiers.

To confirm the integration is working, go to **Loads**, open a load that has a driver and truck assigned, and look for the truck location on the map or in the asset tracking section. If the integration is active and the truck has a KSK ELD device, the current location should be visible. The remaining-time HOS values should appear next to the driver's name or in the driver detail panel.

## Troubleshooting

### Truck location is not showing

Confirm the truck has a KSK ELD device installed and powered on. Verify the API key in Alvys matches the one provided by KSK ELD — go to Management > Integrations and re-enter the key if needed. Check that the integration status shows as active.

### HOS clocks are blank

Confirm the driver is logged in to the KSK ELD device for their current shift. Verify the device is actively transmitting to KSK ELD's servers.

### Odometer or fuel level is not showing

KSK ELD returns additional detail data (odometer, fuel level) only for devices with numeric identifiers. If the device uses a non-numeric identifier format, this detail will not display. Basic location and HOS data will still be available.

<Warning>
  ⚠️ Trailer tracking is not supported — only trucks. · IFTA mileage reporting is not available through KSK ELD. · Odometer and fuel level detail may not display for devices with non-numeric identifiers.
</Warning>

## FAQs

**Q: Can I track trailers with KSK ELD?**

**A:** No. KSK ELD does not return trailer data. Only truck assets are supported through this integration.

**Q: Why is odometer data not showing for one of my trucks?**

**A:** Odometer and fuel level detail data is available only for devices with numeric identifiers. If a specific truck's device uses a non-numeric ID, those additional fields will not display. Basic location and HOS data will still appear for that truck.

**Q: Is IFTA mileage available?**

**A:** No. IFTA mileage is not supported by KSK ELD and is not available in Alvys through this integration.

## Go Deeper

* Setting Up ELD / Telematics Integrations


# MacroPoint Inbound Visibility: Tracking Data Not Appearing
Source: https://docs.alvys.com/en/help/integrations/macropoint-inbound-visibility-tracking-data-not-appearing

Troubleshoot missing MacroPoint Inbound tracking data by checking Descartes portal delivery settings, per-load tracking status, and recent visibility events.

<Note>
  If MacroPoint Inbound is configured but tracking data is not appearing on a load, verify that the MacroPoint portal is configured to deliver data to Alvys, that tracking is enabled on the specific load, and that a relevant tracking event has occurred.
</Note>

## Overview

MacroPoint Inbound must be configured and tracking must be enabled on each load before data will flow. If tracking data is not appearing in your Load Board, Load Details, or Logs, this article explains expected behavior and how to resolve missing data.

Synonyms: MacroPoint inbound, tracking data missing, no location updates, visibility not appearing, Descartes MacroPoint.

## Troubleshooting

### Tracking data is not appearing in Alvys after enabling MacroPoint Inbound

Cause: The MacroPoint Inbound integration receives data passively. It only processes incoming updates when MacroPoint detects a relevant event and delivers it to Alvys. The integration handles tracking status updates, live location updates, arrival and departure timestamps, and trip status changes triggered by arrival and departure events. Data will not flow unless all of the following conditions are met: the MacroPoint portal has been configured to deliver tracking data to Alvys, tracking is enabled on the specific load, and MacroPoint has detected a relevant location or status event.

<Note>
  <img alt="Load Tracking tab on a load showing active MacroPoint tracking status" />

  *Load Tracking tab on a load showing active MacroPoint tracking status*
</Note>

Resolution:

1. Confirm the MacroPoint portal is configured to deliver data to Alvys via webhooks. The MacroPoint portal must be configured with the correct webhook URLs before any tracking updates can appear. Without correctly configured webhooks, Alvys receives no data from MacroPoint regardless of how the load is configured. Contact your MacroPoint representative or account administrator to confirm the webhook setup is active and pointing to your Alvys account.
2. Enable tracking on the load. The MacroPoint integration must be enabled on each individual load. Open the load, navigate to the **Load Tracking** tab, and confirm tracking is active. Even if the integration is active at the account level, no data appears for loads where tracking has not been turned on.
3. Wait for a relevant event. Tracking data appears only after MacroPoint detects a relevant event such as a stop arrival, departure, or location update from the driver. If the driver has not yet reached a checkpoint or the truck has not moved since tracking was enabled, there may be no data to display yet. Data will appear within the load once MacroPoint sends the update.
4. Refresh and verify tracking is still active. If tracking was working and has since stopped, refresh the load and confirm tracking remains active on both the driver's side and in Alvys. If tracking appears disabled, re-enable it. Collect screenshots or recordings if the issue is intermittent.
5. Review for data errors. If incoming data contains errors such as incorrect timestamps or location mismatches, certain updates may fail. Check the Logs section of the load for any error indicators before escalating.
6. If you have confirmed the MacroPoint portal is configured correctly, tracking is enabled on the load, and a relevant event has occurred but data is still not appearing, contact Alvys support. Include the load number, the time range when data was expected, and any screenshots or recordings of the issue.

## FAQs

**Q: How long does it take for tracking data to appear?**

**A:** Data appears once MacroPoint detects a relevant location event.

**Q: Do I need to enable tracking on every load?**

**A:** Yes. Tracking must be enabled per load.

**Q: What if tracking was working and then stopped?**

**A:** Confirm tracking is still active on the driver's side and in Alvys, collect screenshots or recordings, and contact Alvys support if the issue continues.


# MacroPoint Tracking Integration
Source: https://docs.alvys.com/en/help/integrations/macropoint-tracking-integration

Configure two-way MacroPoint (Descartes) visibility in Alvys for inbound carrier tracking and outbound load status sharing with shippers and trading partners.

<Note>
  The MacroPoint integration enables both inbound and outbound load visibility: inbound tracking pulls carrier location and status updates into Alvys, and outbound tracking automatically shares load location and status data with trading partners who use MacroPoint.
</Note>

## Overview

**MacroPoint** integration provides both inbound and outbound visibility for your loads. Inbound visibility gives you more control over tracking request creation and processing. Outbound visibility automatically shares location and status data with your trading partners who use MacroPoint for tracking.

**Synonyms:** MacroPoint tracking, Descartes MacroPoint, inbound visibility, outbound visibility, two-way visibility, carrier tracking.

MacroPoint integrates with Alvys to provide two-way shipment visibility. Inbound visibility (MacroPoint to Alvys) pulls carrier location updates into Alvys so you can monitor tracking requests directly from the load. Outbound visibility (Alvys to MacroPoint) pushes your load location and status data out to customers who use MacroPoint to track their freight.

This article covers how to set up and use both directions of the MacroPoint integration.

## Prerequisites

Before configuring the MacroPoint inbound integration, you need three credentials from MacroPoint:

* **MacroPoint ID:** your company's MacroPoint account identifier
* **API Password:** used to authenticate tracking requests
* **FTP Password:** used to submit carrier details to MacroPoint via SFTP

Request these credentials by email at [servicedesk@descartes.com](mailto:servicedesk@descartes.com) or by phone at 1-888-544-3844, Option 2.

MacroPoint inbound integration requires a paid plan with MacroPoint. MacroPoint outbound integration only requires the customer receiving the updates to have a paid plan with MacroPoint.

## How to connect

### Inbound: Configure MacroPoint in Alvys

Once you have your MacroPoint credentials, navigate to Management and click the EDI & Visibility tab.

<Note>
  <img alt="Image showing Management > EDI & Visibility tab" />

  *Image showing Management > EDI & Visibility tab*
</Note>

Select the subsidiary you want to integrate with MacroPoint and click the Visibility drop-down menu. Choose MacroPoint Inbound. In the configuration window, enter your MacroPoint ID, API Password, and FTP Password, then click Save.

### Inbound: Configure Webhooks in MacroPoint

To enable MacroPoint to send tracking data to Alvys, configure the following webhook URLs on your MacroPoint Company Preferences page. \*\*Replace \*\*\*\*XXXXX \*\***with your Alvys Tenant ID.**

* **Location Updates:** `https://api.alvys.com/api/macropoint/locationUpdates/XXXXX`
* **Order Status:** `https://api.alvys.com/api/macropoint/orderStatus/XXXXX`
* **Trip Events:** `https://api.alvys.com/api/macropoint/tripEvents/XXXXX`
* **Form Submits:** `https://api.alvys.com/api/macropoint/formSubmits/XXXXX`

Add these URLs to the appropriate settings in your MacroPoint account at the MacroPoint Company Preferences page ([https://macropoint-lite.com/Secure/Company.aspx](https://macropoint-lite.com/Secure/Company.aspx)).

### Inbound: Configure Tracking Defaults

After entering your credentials, you can customize the default behavior of tracking requests. These defaults apply to every new tracking request so you do not need to manually configure each one.

<Note>
  <img alt="Image showing Macropoint Inbound form with Inbound visibility settings" />

  * Image showing Macropoint Inbound form with Inbound visibility settings\*
</Note>

### Outbound: Configure MacroPoint Outbound in Alvys

The outbound visibility service sends location and status data to trading partners across multiple providers. The same service that sends data to MacroPoint also supports Project44 and FourKites. MacroPoint outbound configuration is done within this shared visibility service.

Navigate to **Management > Integrations > Visibility > Outbound**. Enter your MacroPoint ID and Password. Select the relevant subsidiaries for outbound visibility and configure outbound sharing settings such as which locations, statuses, and update frequency to share.

<Note>
  <img alt="Notion Image" />
</Note>

Once configured, automatic updates can be set up directly within the customer profile, similar to the process described in EDI Auto Update Settings.

## What syncs

### Inbound data received from MacroPoint

MacroPoint sends the following data to Alvys via the configured webhook URLs:

* **Location updates:** GPS latitude and longitude, timestamp, data source, and locator information for the carrier's current position
* **Order status:** tracking request status codes and messages
* **Trip events:** stop arrivals and departures with timestamp, location, and event type
* **Form submits:** driver form submissions associated with the tracking request

### Outbound data sent to MacroPoint

Alvys sends the following data outbound to MacroPoint for customer visibility:

* **Location data:** GPS coordinates sourced from ELD, check calls, and inbound tracking updates
* **Load statuses:** the four configurable outbound statuses are **Dispatched or Covered** (before pickup), **Dispatched After 1st Pickup** (when the first stop is arrived), **In Transit**, and **Delivered**

Each status can be toggled on or off in the outbound configuration. Only statuses that are enabled will be shared with the customer's MacroPoint account.

### Inbound sync

MacroPoint polls carrier GPS devices at a configured interval and sends location updates to Alvys. Alvys processes each update and records the carrier's current position, estimated arrival time, and stop arrival or departure events against the active tracking request on the load.

The inbound integration updates the tracking request state when the carrier arrives at or departs from a pickup or delivery stop. These updates are visible on the load's tracking panel.

### Outbound sync

Alvys pushes location and status data to MacroPoint on a scheduled basis. The outbound service reads the current load position from ELD, check calls, or inbound tracking data and transmits it to MacroPoint. Status events (such as when a load moves to **In Transit**) are sent as they occur.

### Verify inbound is working

After configuring MacroPoint inbound and initiating a tracking request on a load:

1. Open the load and click the Tracking option in the Action Ribbon.

   <img alt="Notion Image" />
2. In the tracking request panel, adjust the phone number, track duration, interval, and other request details as needed.
3. Click **Track** to submit the tracking request to MacroPoint and begin monitoring.

<Note>
  <img alt="Image showing Tracking request form" />

  *Image showing Tracking request form*
</Note>

Once the tracking request is active, MacroPoint begins sending location updates to Alvys. You can manage the active request from the Action Ribbon: options to pause, resume, or stop tracking are available there.

<Note>
  <img alt="Image showing Tracking management options on load details page" />

  *Image showing Tracking management options on load details page*
</Note>

### Verify outbound is working

After configuring MacroPoint outbound, open a load that matches one of your enabled outbound statuses (for example, a load in **In Transit** status). Check the customer's MacroPoint account to confirm the load location and status are appearing as expected.

## Troubleshooting

### Tracking request fails to submit

Cause: The MacroPoint ID or API Password entered in Alvys does not match the credentials provided by MacroPoint.

1. Verify that the MacroPoint ID and API Password entered in Alvys match the credentials provided by MacroPoint.
2. If the credentials were recently changed in MacroPoint, update them in Alvys under **Management > EDI & Visibility** on the relevant subsidiary's Visibility configuration.

### Carrier not found in MacroPoint

Cause: MacroPoint requires carrier details to be registered in their system before a tracking request can be accepted. When you initiate a tracking request, Alvys automatically submits carrier details to MacroPoint using the FTP Password configured in the inbound setup.

1. If the carrier registration fails, verify that the FTP Password is entered correctly in the MacroPoint Inbound configuration screen.

### No location updates appearing on the load

Cause: One of the required conditions for inbound data delivery is not met.

1. Confirm the tracking request status is Active, not Pending or Error, on the load's tracking panel.
2. Confirm the webhook URLs are correctly entered in your MacroPoint Company Preferences page with your Alvys Tenant ID replacing XXXXX.
3. Check that MacroPoint is successfully reaching the configured webhook endpoint. If MacroPoint cannot reach Alvys, location updates will not be received regardless of the tracking request status.
4. If none of these conditions apply, contact Alvys support.

### Tracking request validation error at pickup or delivery stop

Cause: MacroPoint requires GPS coordinates (latitude and longitude) on all pickup and delivery stops when creating a tracking request. A stop can have a complete street address but still fail if the address was never geocoded.

1. Verify that each stop address has been geocoded (coordinates assigned) in the company record.
2. If coordinates are missing, edit the stop's company address to trigger geocoding, then retry the tracking request.

### Outbound status not reaching the customer's MacroPoint account

Cause: The relevant load status is not enabled in the outbound configuration, or the load's subsidiary is not selected.

1. Verify that the relevant load status (**Dispatched or Covered**, **Dispatched After 1st Pickup**, **In Transit**, or **Delivered**) is enabled in the outbound visibility configuration under **Management > Integrations > Visibility > Outbound**.
2. Confirm that the subsidiary assigned to the load matches a subsidiary selected in the outbound configuration.
3. If none of these conditions apply, contact Alvys support.

## Limits and unsupported

* Waypoint stops are not supported in MacroPoint tracking requests. Only pickup and delivery stops are included in the trip sheet sent to MacroPoint.
* Outbound visibility sends data for MacroPoint, Project44, and FourKites through the same shared service. Each provider is configured separately within **Management > Integrations > Visibility > Outbound**.
* If a stop's address has not been geocoded (no GPS coordinates assigned), MacroPoint will reject the tracking request with a validation error.

## FAQs

**Q: What is the difference between inbound and outbound visibility?**

**A:** Inbound lets you request and manage carrier tracking from MacroPoint and receive location updates in Alvys. Outbound automatically shares your load location and status data with customers who use MacroPoint to track their freight.

**Q: Do I need a MacroPoint paid plan for both inbound and outbound?**

**A:** Inbound requires your company to have a paid MacroPoint plan. Outbound only requires the customer receiving the updates to have a paid MacroPoint plan.

**Q: Can I pause tracking for individual loads?**

**A:** Yes. Once a tracking request is active, you can pause, resume, or stop it from the Action Ribbon on the load.

**Q: Which statuses does MacroPoint outbound share with customers?**

**A:** MacroPoint outbound can share four load statuses: **Dispatched or Covered**, **Dispatched After 1st Pickup**, **In Transit**, and **Delivered**. Each status can be individually enabled or disabled in the outbound visibility configuration.

**Q: Why is the FTP Password required for inbound setup?**

**A:** Alvys uses the FTP Password to submit carrier details to MacroPoint via SFTP when a tracking request is initiated. Without this credential, MacroPoint cannot register the carrier in their system and tracking requests will fail.

## Go Deeper

[Understanding MacroPoint Inbound Visibility](/en/help/integrations/macropoint-inbound-visibility-tracking-data-not-appearing)


# Connect Master ELD to Alvys
Source: https://docs.alvys.com/en/help/integrations/master-eld-eld-telematics-integration

Connect Master ELD to Alvys to pull real-time truck locations, driver HOS clocks, and fuel data into dispatch through this one-way telematics integration.

<Note>
  Master ELD is a telematics provider that connects with Alvys to pull real-time truck locations, HOS clocks, and fuel data into your dispatch workflow: also known as Master ELD electronic logging device, Master ELD telematics, or Master ELD fleet tracking.
</Note>

## Overview

Master ELD is a telematics provider that connects with Alvys to bring real-time truck locations and Hours of Service (HOS) status into your dispatch workflow. This integration is also referred to as Master ELD electronic logging device, Master ELD telematics, or Master ELD fleet tracking.

Connecting Master ELD to Alvys allows your dispatch team to view current truck locations and driver HOS remaining-time clocks without leaving Alvys.

A key advantage of the Master ELD integration is that HOS data is matched to drivers automatically — no manual driver mapping is required in Alvys.

Trailer tracking and IFTA mileage are not supported by Master ELD. Only truck assets are tracked through this integration.

## Prerequisites

Before connecting, confirm you have the following:

* An active Master ELD account with API access
* Your Master ELD API key
* The **"Admin"** or **"Partner Admin"** role in Alvys

## Getting your Master ELD API key

Before connecting, you need an API key from your Master ELD account. You can generate an API key directly from your Master ELD platform, or contact your Master ELD representative and request one. Once you have the key, proceed with the connection steps below.

## How to connect

Master ELD uses an API key for authentication.

1. Go to **"Management"** > **"Integrations"** in the top navigation.
2. Find **"Master ELD"** in the list of available integrations and click to open it.
3. Enter the API key provided by Master ELD.

   <img alt="Screenshot showing the Master ELD integration card in Alvys with the API Key entry field" />

   *Screenshot showing the Master ELD integration card in Alvys with the API Key entry field*
4. Click **"Save"**. Alvys will verify the key.

## What syncs

The following data is pulled from Master ELD into Alvys:

* **Truck location:** Current GPS coordinates for each truck with a Master ELD device
* **HOS clocks:** Remaining time values for each driver's HOS limits — these are countdown clocks showing time remaining. HOS data is matched to the correct driver automatically using information returned directly from Master ELD; no manual driver ID setup is required in Alvys
* **Fuel level:** Displayed as a percentage when the device reports it

Trailer assets return no data from Master ELD. Trailers will not appear with location or status through this integration. IFTA mileage is not supported by Master ELD and will not be available in Alvys through this integration.

Alvys requests updated data from Master ELD on a regular basis. Truck locations, HOS clocks, and fuel level reflect the most recent values reported by the device. Driver matching for HOS data happens automatically.

What is not supported:

* Trailer tracking is not supported — only trucks
* IFTA mileage reporting is not available through Master ELD
* Battery level data is not displayed in Alvys
* HOS values are remaining-time clocks only

## Troubleshooting

### Truck location is not showing

1. Confirm the truck has a Master ELD device installed and powered on.
2. Verify the API key in Alvys matches the one provided by Master ELD. Go to **"Management"** > **"Integrations"** and re-enter the key if needed.
3. Check that the integration status shows as active.

### HOS clocks are blank or not matched to the correct driver

1. Confirm the driver is logged in to the Master ELD device for their current shift.
2. HOS data and driver matching are handled automatically by Master ELD. If a driver's HOS is not appearing, verify the driver is active in your Master ELD account and assigned to a device.

### Fuel level is not displaying

Master ELD devices report fuel level only when the vehicle's onboard diagnostics support it. If the truck does not have compatible diagnostics, this field will remain blank — this is expected behavior.

## FAQs

**Q: Do I need to manually map drivers to HOS data in Master ELD?**

**A:** No. Master ELD automatically matches HOS data to the correct driver. No manual setup is needed in Alvys.

**Q: Can I track trailers with Master ELD?**

**A:** No. Master ELD does not return trailer data. Only truck assets are supported through this integration.

**Q: Why is fuel level blank for some trucks?**

**A:** Fuel level is only available when the truck's onboard diagnostics system supports reporting it to the ELD device. If the truck does not support this, the fuel field will not display a value.

**Q: Is IFTA mileage available?**

**A:** No. IFTA mileage is not supported by Master ELD and is not available in Alvys through this integration.

## Go Deeper

* Setting Up ELD / Telematics Integrations


# Monarch Tracking Integration
Source: https://docs.alvys.com/en/help/integrations/monarch-tracking-integration

Connect Monarch GPS Insight ELD to Alvys to stream live truck locations to the Asset Map and populate IFTA miles automatically for compliance reporting.

<Note>
  The Monarch GPS Insight integration (also called Monarch Tracking or Monarch ELD) pulls real-time truck location data and IFTA miles from Monarch into Alvys, enabling visibility on the Asset Map and simplified IFTA compliance reporting.
</Note>

## What This Integration Does

Monarch GPS Insight is an Electronic Logging Device (ELD) solution popular among logistics companies operating near the border. Once configured, Alvys pulls real-time truck location data and IFTA miles from Monarch automatically. This gives dispatchers and operations teams live visibility into truck locations on the Load Details page and Asset Map, and populates the IFTA Report with accurate mileage for simplified compliance reporting.

## Prerequisites

Before setting up this integration, obtain your Monarch **Username**, **Password**, and the **Asset ID** for each truck you want to track from Monarch. Asset IDs are available in your Monarch portal. Allow approximately 15 minutes for setup.

## Connect / Authenticate

1. Open your Company Profile. Click your user profile icon in the lower left corner of Alvys. Select the subsidiary you want to configure, then click the **Integrations** tab.
2. Expand the **ELD** section and click the pencil icon on the **Monarch** card.
3. Enter your Monarch **Username** and **Password**. Select the subsidiaries that should use this integration, then click **Save**.

   <img alt="Monarch card in the ELD section of the Company Profile Integrations tab, showing the credential entry form with Username and Password fields" />

   *Monarch card in the ELD section of the Company Profile Integrations tab, showing the credential entry form with Username and Password fields*

Alvys validates your credentials. If everything is correct, the integration becomes active.

## Field & Data Mapping

After the integration is active, link each truck in Alvys to its corresponding Monarch Asset ID to tell Alvys which truck to track.

1. Go to **Assets** in the left navigation menu and select **Trucks**.
2. Double-click the truck you want to configure.
3. Scroll to the **ELD Integrations** section and click **Add Integration**.
4. Select **Monarch** from the dropdown, enter the **Asset ID** provided by Monarch in the Integration ID field, and click **Save**.
5. Repeat this process for each truck you want to track with Monarch.

   <img alt="ELD Integrations section on a truck record showing the Add Integration button and the Monarch Asset ID entry field" />

   *ELD Integrations section on a truck record showing the Add Integration button and the Monarch Asset ID entry field*

## Sync Behavior

Monarch sends location data and IFTA mileage to Alvys automatically at regular intervals once a truck is mapped and the integration is active. No manual sync is required.

## Verify It's Working

### View truck location on a load

Open a load's details page for a load with an assigned truck that has been mapped to Monarch. Real-time truck location data from Monarch appears directly on the Load Details page.

<img alt="Load Details page showing real-time truck location pulled from Monarch for a load with an assigned truck" />

*Load Details page showing real-time truck location pulled from Monarch for a load with an assigned truck*

### View all truck locations on the Asset Map

All truck locations from Monarch appear in a consolidated view on the **Asset Map**, accessible from the left navigation menu.

<img alt="Asset Map showing all Monarch-tracked truck locations in a consolidated view" />

*Asset Map showing all Monarch-tracked truck locations in a consolidated view*

### Generate IFTA reports

Alvys includes IFTA mileage from Monarch automatically in the **IFTA Report**. Access the IFTA Report to view accurate, up-to-date compliance records.

<img alt="IFTA Report showing mileage data populated from Monarch for compliance reporting" />

*IFTA Report showing mileage data populated from Monarch for compliance reporting*

## FAQs

**Q: Why is Monarch particularly popular near the border?**

**A:** Monarch ELDs are particularly popular among logistics companies operating near the border, making this integration essential for streamlined operations and compliance in these regions.

**Q: What features does Monarch provide?**

**A:** Monarch provides real-time truck location tracking and automated IFTA mile tracking for simplified compliance reporting.

**Q: Where do I find my Monarch Asset IDs?**

**A:** Your Monarch Asset IDs should be provided by Monarch or are available in your Monarch portal.


# Connect Motive to Alvys
Source: https://docs.alvys.com/en/help/integrations/motive-eld-telematics-integration

Connect Motive (formerly KeepTruckin) to Alvys via OAuth to pull truck and trailer locations, driver HOS clocks, and IFTA mileage into your dispatch board.

<Note>
  Motive is a telematics and ELD provider that connects with Alvys to bring real-time truck and trailer locations, Hours of Service (HOS) status, and IFTA mileage data into your dispatch workflow. This integration is also known as Motive ELD, KeepTruckin (the former name of Motive), ELD integration, or fleet tracking.
</Note>

## What This Integration Does

Connecting Motive to Alvys gives your dispatch team real-time visibility into truck and trailer locations, driver HOS remaining-time clocks, and IFTA mileage by state, all without leaving Alvys.

With a single connection, Motive supports trucks, trailers, HOS, and IFTA, making it one of the most comprehensive integrations available in Alvys.

## Prerequisites

Before connecting, confirm you have the following:

* An active Motive account
* Permission to authorize Alvys through Motive's OAuth 2.0 flow
  * You will be redirected to Motive to sign in and approve the connection.
* The Admin, Partner Admin, or Support role in Alvys

## How to connect

Motive uses OAuth 2.0 to connect with Alvys. You will be redirected to Motive's website to approve the connection — no API key or password needs to be entered manually.

1. Open Integrations. Click your profile/account menu in the bottom-left corner, then select **Integrations**.
2. Select Motive. In the **ELDs** section, find **Motive** in the list of available integrations, then click it to open the integration details.
3. Authorize via OAuth 2.0. Choose the update frequency for the Motive integration, then click **Save**. When prompted, click **Yes** to continue. You will be redirected to Motive to sign in and approve the connection to Alvys.
4. Return to Alvys. After approving in Motive, you will be returned to Alvys automatically. The integration status will change to active.

## Map assets in Alvys

After connecting, add each truck or trailer's Motive asset ID in Alvys so location data flows correctly.

1. Go to **Assets** in the left menu and select **Trucks** or **Trailers**.
2. Find the asset you want to configure and double-click it to open the Edit Asset page.
3. Scroll down to the **ELD Integrations** section and click **Add Integration**.
4. Click the dropdown and select **Motive**.
5. Find the Motive asset ID from the URL when viewing that asset in the Motive portal. For example, in the URL [https://app.gomotive.com/en-US/#/fleetview/map/vehicle/867351-null-null/867351/live](https://app.gomotive.com/en-US/#/fleetview/map/vehicle/867351-null-null/867351/live), the asset ID is **867351**.
6. Paste the ID into the **Asset ID** field and click **Save**.

Repeat for the rest of your trucks and trailers.

<img alt="Edit Asset page ELD Integrations section with a Motive asset ID entered" />

*Edit Asset page ELD Integrations section with a Motive asset ID entered*

## Add HOS to driver profiles

To sync HOS data from Motive, add the driver's Motive ID to their driver profile in Alvys.

1. Go to **Assets** in the left menu and select **Drivers**.
2. Find the driver you want to configure and double-click their name to open the **Driver** page.
3. On the right side of the screen, find the **ELD Providers** section.
4. Click the dropdown, select **Motive**, and click **Add ELD**.
5. In the **Add Integration** pop-up window, select **Motive** as the integration type and enter the driver's Motive asset ID. You can find this ID in the driver's profile URL in the Motive portal, the same way you find the asset ID for vehicles.
6. Paste the ID into the **Asset ID** field and click **Save**.

   <img alt="Driver profile ELD Providers section with a Motive asset ID entered" />

   *Driver profile ELD Providers section with a Motive asset ID entered*

## What syncs

Alvys requests updated data from Motive on a regular basis. Truck and trailer locations, HOS clocks, and IFTA mileage reflect the most recent values from Motive's servers.

* **Truck location:** Current GPS coordinates for each truck asset.
* **Trailer location:** Current GPS coordinates for each trailer asset.
* **HOS clocks:** Remaining available time for each driver's HOS limits — available-time values showing how much drive time, shift time, or cycle time the driver has remaining.
* **IFTA mileage:** Miles driven by state, presented as a mileage-by-state summary to support fuel tax reporting.

To confirm the integration is working, go to **Loads** and open a load that has both a driver and a truck assigned. Look for the asset location on the map or in the tracking panel; if the integration is active and the asset has a Motive device, the current location should be visible within 15 minutes or more, depending on the update frequency you selected. The available-time HOS values should appear next to the driver's name or in the driver detail panel. IFTA mileage by state is visible in the IFTA reporting section of Alvys; if you have completed trips, state-level mileage should be populated there.

## Troubleshooting

### Truck or trailer location is not showing

Confirm that the asset has a Motive device installed and powered on. Verify that the Motive OAuth 2.0 connection is still active by clicking the profile/account menu in the bottom-left corner, selecting **Integrations**, and checking the integration status. If the connection has expired or been revoked, the status will display as **Needs Attention**. Open the Motive integration and click **Save** to re-authorize through Motive's OAuth 2.0 flow. After re-authorizing, confirm that the integration status shows **Active**.

### HOS clocks are blank

Confirm the driver is logged in to the Motive ELD device for their current shift. Verify the Motive OAuth 2.0 connection is still authorized — an expired or revoked authorization will prevent data from updating.

### IFTA mileage is not showing

Confirm that trips have been completed in Alvys; IFTA mileage is calculated for completed trips. Verify the OAuth 2.0 connection is active. If the connection was revoked in Motive, data will stop syncing.

### The connection failed or was revoked

If the Motive OAuth 2.0 connection is no longer active, click the profile/account menu in the bottom-left corner and select **Integrations**. Find and open **Motive**, then click **Save**. You will be redirected to Motive to re-authorize the connection.

<Warning>
  Connection is managed through OAuth 2.0: if authorization is revoked in Motive, you must reconnect from Alvys. · IFTA data is a mileage-by-state summary; individual trip-level breakdown is not available in Alvys through this integration. · HOS values are available-time clocks (time remaining), not elapsed time.
</Warning>

## FAQs

**Q: Why does connecting Motive redirect me to another website?**

**A:** Motive uses OAuth 2.0 for secure authorization. This means you log in and approve the connection on Motive's own website, so Alvys never handles your Motive credentials directly. After approving, you are returned to Alvys automatically.

**Q: Does Motive support trailer tracking in Alvys?**

**A:** Yes. Motive returns location data for both trucks and trailers. Both asset types will appear in Alvys when devices are installed and active.

**Q: What HOS information does Motive provide?**

**A:** Motive provides available-time HOS values: the amount of drive time, shift time, cycle time, and break time the driver has remaining. These are the time-remaining values for each limit.

**Q: What IFTA data is available from Motive?**

**A:** Motive provides a mileage-by-state summary showing miles driven in each state. This data can be used to support IFTA fuel tax filing. Individual trip-level breakdowns are not available through this integration.

**Q: The Motive integration stopped working. What do I do?**

**A:** The most likely cause is that the OAuth 2.0 authorization was revoked or expired in Motive. Click the profile/account menu in the bottom-left corner and select **Integrations**. Find and open **Motive**, then click **Save**. You will be redirected to Motive to re-authorize the connection.

## Go Deeper

* Setting Up ELD / Telematics Integrations


# OTR Solutions Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/otr-solutions-factoring-integration

Set up the OTR Solutions factoring integration to submit invoice batches, run broker credit checks, and sync purchase status back into Alvys automatically.

## What This Integration Does

OTR Solutions connects to Alvys via a two-way API to automate invoice submission, broker credit checks, and purchase status reporting for factoring clients. Also referred to as OTR factoring or OTR Solutions factoring.

Alvys submits invoice batches and broker credit check requests to OTR Solutions. OTR Solutions returns credit check results in real time and provides purchase status updates that sync back to Alvys nightly or on demand. When a load is funded by OTR Solutions, the load status in Alvys updates to **Financed**.

## Prerequisites

* Active account with OTR Solutions
* Username and password from the OTR Solutions client portal
* USDOT number set on each subsidiary that will submit batches
* MC number set on each customer or broker that will be included in a batch or credit check (a load missing an MC number will fail individually during submission; the rest of the batch proceeds)
* Notice of Assignment text provided by OTR Solutions
* Admin, Partner Admin, or Support access to configure the integration
* **"Billing"** permission to submit batches and access reporting

## Connect & Authenticate

### Configure your Notice of Assignment

1. Navigate to Management > Company Profile.
2. In the General Info tab, locate the Important Information section. Click the **(+)** button. The Manage Important Info pop-up opens.

   <img alt="Manage Important Info pop-up opened from the Important Information section of the General Info tab" />

   *Manage Important Info pop-up opened from the Important Information section of the General Info tab*
3. In the drop-down menu, select **Notice of Assignment**. Copy and paste the Notice of Assignment text provided by OTR Solutions.

   <img alt="Notice of Assignment text pasted into the Manage Important Info field" />

   *Notice of Assignment text pasted into the Manage Important Info field*
4. Click **Save**.

### Configure the OTR Solutions integration

1. Navigate to Management > Integrations.
2. Select the subsidiary you want to configure. Expand the **Factoring** section. Click the pencil icon next to **OTR Solutions**.

   <img alt="Factoring section expanded in Integrations with the OTR Solutions pencil icon" />

   *Factoring section expanded in Integrations with the OTR Solutions pencil icon*
3. Enter the username and password you use to log in to the OTR Solutions client portal.

   <img alt="Credential entry fields for the OTR Solutions integration" />

   *Credential entry fields for the OTR Solutions integration*
4. Click **Save**. The integration is now active for this subsidiary. Repeat steps 1 through 4 for each additional subsidiary.

### How to submit a batch

1. Navigate to Accounting > Factoring Upload. All loads must have a **Queued** status with the invoicing method set to factoring and documents merged.
2. Select the correct subsidiary.

   <img alt="Subsidiary selection on the Factoring Upload page" />

   *Subsidiary selection on the Factoring Upload page*
3. Select the invoices to include in the batch. Confirm the subsidiary's USDOT number is set. Any load whose customer is missing an MC number will fail individually during submission; the rest of the batch will proceed.

   <img alt="Invoice selection on the Factoring Upload page for an OTR Solutions batch" />

   *Invoice selection on the Factoring Upload page for an OTR Solutions batch*
4. Click **Submit Batch**. Wait until the submission completes. Do not close this page or navigate away during submission; doing so may disrupt the process.

## Field & Data Mapping

Alvys sends invoice data to OTR Solutions when a batch is submitted, including the load number, debtor information, invoice amount, MC number, and the merged load document. The subsidiary's USDOT number is included in every invoice submitted. The subsidiary's USDOT number must be set. If a customer's MC number is missing for a specific load, that load's invoice will fail individually; other invoices in the batch will proceed.

## Sync Behavior

Credit check results sync from OTR Solutions to Alvys in real time. Purchase status updates sync from OTR Solutions to Alvys in two ways: automatically through a nightly sync, or on demand by clicking the **SYNC TRANSACTIONS** button in Reports > Factoring. When OTR Solutions reports a load as funded, the load status in Alvys changes to **Financed**. This update can occur through the nightly automated sync or through a manual SYNC TRANSACTIONS run; both mechanisms produce the same result.

### Broker credit checks

OTR Solutions performs broker credit checks to assess factoring eligibility. Credit check results appear as colored icons next to the customer or broker name:

* Green icon: **Approved**
* Red icon: **Not Approved**
* Grey icon: no credit check has been run yet for this broker
* Amber icon: **Call Credit** (contact OTR Solutions to discuss this broker's account)

  You can submit a load to OTR Solutions regardless of the credit check status. The credit check result is informational only and does not block batch submission.

  Alvys automatically triggers a credit check in two situations:
* When a load is created: if the last credit check for that broker was more than 24 hours ago
* When a load reaches **Queued** status: if the last credit check was more than 24 hours ago

  To manually trigger a credit check from a customer or broker profile:

1. Navigate to the customer or broker profile.
2. Confirm that a factoring invoicing method is assigned to the subsidiary where the OTR Solutions integration is configured. Save if changes are needed.
3. Click the refresh icon **(↻)** next to the customer or broker name. A manual trigger always runs the check immediately, regardless of when the last check occurred.

<Note>
  <img alt="Refresh icon next to a customer or broker name to trigger a credit check" />

  *Refresh icon next to a customer or broker name to trigger a credit check*
</Note>

Credit check result icons appear next to the customer or broker name. Green means Approved, red means Not Approved, grey means no credit check has been run yet, and amber means Call Credit (contact OTR Solutions to discuss the broker's account).

<Note>
  <img alt="Credit check result icon shown next to the customer or broker name" />

  *Credit check result icon shown next to the customer or broker name*
</Note>

<Note>
  <img alt="Additional credit check status icons displayed in Alvys" />

  *Additional credit check status icons displayed in Alvys*
</Note>

To manually trigger a credit check from a load details page:

1. Open or create a load. Confirm the customer has a factoring invoicing method assigned to the subsidiary where the OTR Solutions integration is configured.
2. On the load details page, click the refresh icon **(↻)** to trigger a credit check immediately.

<Note>
  <img alt="Refresh icon on the load details page used to trigger a credit check" />

  *Refresh icon on the load details page used to trigger a credit check*
</Note>

To submit a load based on credit check status:

1. Select or create a load with a customer assigned to the subsidiary using the factoring invoicing method.
2. Advance the load to **Released** status.
3. Click **Invoice Load** to generate the invoice.
4. Merge the required documents: Customer Rate Confirmation, Proof of Delivery (POD), and the invoice. The load moves to **Queued** status.
5. Navigate to Accounting > Factoring Upload. Select the load and create a batch.

   <img alt="Load selected on the Factoring Upload page to create an OTR Solutions batch" />

   *Load selected on the Factoring Upload page to create an OTR Solutions batch*
6. Submit the batch. All credit check statuses — Approved, Not Approved, and Call Credit — are permitted for submission.

### Reporting: purchase status

OTR Solutions provides purchase status details for factoring batches. When OTR Solutions funds a load, the load status in Alvys changes to **Financed**. There are two ways to update load statuses from OTR Solutions:

**Nightly automated sync:** Alvys automatically checks and updates purchase status for all invoices that have not yet been updated or funded. This sync runs once per day. No action is required to enable it.

**Manual sync (on demand):** Navigate to Reports > Factoring and select a batch, then click the **SYNC TRANSACTIONS** button in the top right corner of the page.

1. Navigate to Reports > Factoring and select a batch.

<Note>
  <img alt="Batch selected on the Reports > Factoring page" />

  *Batch selected on the Reports > Factoring page*
</Note>

1. Click the **SYNC TRANSACTIONS** button in the top right corner of the page.

   <img alt="SYNC TRANSACTIONS button in the top right corner of the Factoring report page" />

   *SYNC TRANSACTIONS button in the top right corner of the Factoring report page*
2. After the sync runs, any loads that OTR Solutions has funded will move to **Financed** status.

### Examples

<Note>
  <img alt="Factoring report after a sync run" />

  *Factoring report after a sync run*
</Note>

<Note>
  <img alt="Loads showing Financed status following an OTR Solutions sync" />

  *Loads showing Financed status following an OTR Solutions sync*
</Note>

Both the nightly sync and the SYNC TRANSACTIONS button produce the same outcome: loads confirmed as funded by OTR Solutions move to **Financed** status in Alvys.

## Verify It's Working

After submitting a batch, confirm it appears in Reports > Factoring. After a nightly sync or a SYNC TRANSACTIONS run, confirm that funded loads show **Financed** status. Credit check result icons should update within seconds of triggering a check.

## Limits and Unsupported

Fuel card payments are not supported for OTR Solutions. Fuel card functionality is not available through this integration.

## Troubleshooting

### Batch submission fails

1. Confirm the subsidiary's USDOT number is set. Navigate to the subsidiary settings and verify the USDOT number field is populated.
2. Confirm each customer's MC number is set. Navigate to the customer or broker profile and verify the MC number field is populated.
3. Confirm valid OTR Solutions credentials are saved for the subsidiary. Navigate to Management > Integrations, locate OTR Solutions, and verify the username and password are saved.
4. If the batch continues to fail after confirming the items above, contact Alvys support.

### Load status did not change to Financed after sync

1. Confirm the batch was submitted successfully and appears in Reports > Factoring.
2. Click the **SYNC TRANSACTIONS** button to manually trigger an immediate status update for the selected batch.
3. If the load status still does not update, the invoice may not yet be funded in OTR Solutions. Contact OTR Solutions to confirm the funding status on their side.
4. If the load is confirmed as funded in OTR Solutions but the status does not update in Alvys, contact Alvys support.

### Credit check icon does not appear

1. Confirm the customer has a factoring invoicing method assigned to the subsidiary where the OTR Solutions integration is configured.
2. Confirm the integration is active in Management > Integrations.
3. Try triggering a manual credit check using the refresh icon (↻). If the icon still does not appear after a manual trigger, contact Alvys support.

## FAQs

**Q: Can I submit a load if the credit check status is Not Approved or Call Credit?**

**A:** Yes. You can submit a load to OTR Solutions regardless of the credit check status. The result is informational only and does not block batch submission.

**Q: What does the amber Call Credit status mean?**

**A:** Call Credit means OTR Solutions needs more information about the broker before making a decision. Contact OTR Solutions directly to discuss the broker's account.

**Q: How often does the purchase status sync run automatically?**

**A:** The nightly sync runs once per day for all invoices that have not yet been updated or funded. You can also trigger a sync at any time using the SYNC TRANSACTIONS button in Reports > Factoring.

**Q: What is the SYNC TRANSACTIONS button and when should I use it?**

**A:** The SYNC TRANSACTIONS button is located in the top right corner of the Reports > Factoring page. Clicking it triggers an immediate status update for the selected batch, pulling the latest funding information from OTR Solutions. Use it when you want to update load statuses without waiting for the nightly sync. Both the button and the nightly sync can move a load to **Financed** status.

**Q: What triggers an automatic credit check?**

**A:** Alvys automatically triggers a credit check when a load is created or when a load reaches **Queued** status, provided the last credit check for that broker was more than 24 hours ago. Clicking the refresh icon (↻) on the customer profile or load details page always triggers a check immediately, regardless of timing.


# PC Miler Mileage Profiles Integration
Source: https://docs.alvys.com/en/help/integrations/pc-miler-mileage-profiles-integration

Connect PC*MILER to Alvys with your Trimble API credentials and set it as the default mileage source for customer and dispatch mileage profiles.

<Note>
  📋 **Applies to:** Admins · Partner Admins

  **Module:** Management > Integrations · Settings > Mileage Profiles

  **Provider:** PC Miler (Trimble) · **Integration type:** One-way · **Direction:** Alvys queries PC Miler to calculate mileage for loads and trips

  Connect Alvys to PC Miler to create Mileage Profiles that define how mileage is calculated for loads and trips, using parameters such as routing type, toll preferences, hazmat classifications, and PC Miler version, at no additional cost beyond your existing PC Miler subscription.
</Note>

## What This Integration Does

The PC Miler integration enables Alvys to calculate load and trip mileage using PC Miler routing data instead of the default HereMaps provider. Once connected, you can create named Mileage Profiles that define precise routing parameters for different customer or operational needs. These profiles can then be applied at the tenant level or per customer.

Key capabilities this integration provides:

* Precise cost analysis: accurate mileage tracking supports exact transportation cost calculations and financial planning.
* Regulatory compliance: mileage reporting aligned with industry standards reduces the risk of non-compliance.
* Optimized route planning: PC Miler routing data supports fuel-efficient route selection.
* PC Miler version control: when customers require mileage billed to a specific PC Miler version, you can set that version in the profile to eliminate manual adjustments.

Co-Pilot integration is not currently supported. This integration is focused on mileage calculation through PC Miler.

## Prerequisites

* You must have an active PC Miler (Trimble) subscription to obtain API credentials.
* If you are not yet a PC Miler customer, contact Alvys Support to request API credentials on your behalf. Alvys will coordinate with Trimble to obtain them.
* If you are already a PC Miler customer, you can use your existing API credentials to set up the integration.

## Connect / Authenticate

### Navigate to integrations in Alvys

In Alvys, navigate to Management > Integrations. Locate the PC Miler integration option.

### Enter API credentials

Enter your PC Miler API credentials into the designated fields and enable the integration settings.

<img alt="Screenshot of the PC Miler API credentials entry screen in Alvys integrations" />

*Screenshot of the PC Miler API credentials entry screen in Alvys integrations*

<img alt="Screenshot showing the enabled state of PC Miler integration settings" />

*Screenshot showing the enabled state of PC Miler integration settings*

### Change the default mileage source to PC Miler

After saving the integration credentials, you must update the default mileage calculation setting from HereMaps to PC Miler to activate PC Miler routing for your loads.

In Alvys, click the person icon in the lower-left corner of any page and select Settings. Locate the Mileage Profiles section. Change the default mileage calculation setting from HereMaps to PC Miler and save.

## Field & Data Mapping

Mileage profiles define the parameters PC Miler uses when calculating mileage for a load or trip. The configurable parameters for each Mileage Profile are:

* Routing Type: Practical, Shortest, or Fastest
* Toll Roads: Always Avoid, Avoid if Possible, or Allow
* Borders Open: Yes or No
* Use Traffic: Yes or No (applies to Dispatch Mileage only)
* HazMat Types: None, General, Caustic, Explosives, Flammable, Inhalants, Radioactive, HarmfulToWater, or Tunnel (multiple selections allowed)
* PC Miler Version: a specific version number, selectable from a dropdown

Profiles are named by you. It is recommended to include the PC Miler version number in the profile name for easy identification when selecting from a list.

## Sync Behavior

PC Miler mileage is calculated on demand: when a load or trip is created or when mileage is recalculated, Alvys queries the PC Miler API using the parameters defined in the selected Mileage Profile.

Mileage profiles can be assigned at the tenant level (applies to all loads unless overridden) or at the customer level (overrides the tenant default for loads tied to that customer).

## Verify It's Working

After setup, create a test Mileage Profile and assign it to a load. Confirm the mileage displayed on the load reflects PC Miler routing data and not HereMaps. If the mileage source still shows HereMaps, confirm the default mileage setting was changed in Settings > Mileage Profiles.

## Troubleshooting

### Mileage still calculated using HereMaps after setup

**Step 1:** Confirm the default mileage calculation setting was changed from HereMaps to PC Miler in Settings (click the person icon in the lower-left corner, select Settings, and check Mileage Profiles).

**Step 2:** Confirm the API credentials saved in the integration are correct and the integration is in an enabled state.

**Step 3:** Confirm the Mileage Profile you created is assigned to the load or to the customer profile.

### PC Miler version not producing expected mileage

**Step 1:** Confirm the PC Miler Version field in the Mileage Profile is set to the version required by the customer.

**Step 2:** Confirm the Mileage Profile name includes the version number so the correct profile is selected from the list.

If neither of the above steps resolves the issue, contact Alvys Support with the load number, the Mileage Profile name, and the mileage source shown on the load.

## Limits / Unsupported

* Co-Pilot integration is not supported. PC Miler is supported for mileage calculation only.
* The Use Traffic parameter applies to Dispatch Mileage only; it has no effect on Customer Mileage calculations.
* Multiple HazMat types can be selected per profile, but selecting conflicting types may affect routing results from PC Miler.

## FAQs

**Q: Do I need to be an existing PC Miler customer to use this integration?**

**A:** No. If you are not already a PC Miler customer, contact Alvys Support and Alvys will request API credentials on your behalf.

**Q: How do I set a specific PC Miler version for a customer who requires it for billing?**

**A:** When creating a Mileage Profile, select the required version from the PC Miler Version dropdown. Include the version number in the profile name so it is easy to identify when assigning the profile to a load or customer.


# Pilot Flying J Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/pilot-flying-j-fuel-integration

Import Pilot Flying J fuel card transactions into the Alvys Fuel Report by uploading the Excel statement; Alvys matches purchases to drivers by card number.

<Note>
  The Pilot Flying J fuel integration lets you import fuel transaction data from your Pilot Flying J fuel card account into the Alvys Fuel Report by downloading a transaction file from the Pilot Flying J portal and uploading it to Alvys.
</Note>

## What This Integration Does

The Pilot Flying J fuel integration lets you import fuel transaction data from your Pilot Flying J fuel card (fuel network) account into the Alvys Fuel Report. Transactions are matched to driver profiles using each driver's fuel card number. This is a one-way, manual import: you download a transaction report (statement) from the Pilot Flying J Fuel Card portal and upload the Excel file to Alvys. Alvys matches transactions to drivers using the last 3 digits of each fuel card number.

<Info>
  💡 This integration is sometimes called the Pilot Flying J fuel card import, fuel network sync, or fuel transaction upload. · It is manual and one-way (Pilot Flying J to Alvys) with no scheduled or automatic sync.
</Info>

## Prerequisites

Before configuring this integration, confirm the following:

* You have **"Admin"**, **"Support"**, or **"Partner Admin"** access in Alvys (set on your user role in the Company Profile).
* Your drivers have been added to Alvys.
* You have access to the Pilot Flying J Fuel Card portal.
* You know the last 3 digits of each driver's Pilot Flying J fuel card number.

## Connect and Authenticate

1. Click your username in the bottom left corner of Alvys, then select **Management**.
2. Select the subsidiary you want to integrate with Pilot Flying J.
3. Click the blue **Integrate** button.
4. In the pop-up window, open the **Integration Type** drop-down menu.
5. Scroll down to find **PilotFlyingJ** and select it.
6. Select the subsidiary that should use this integration.
7. Click **Save**.
8. Add each driver's fuel card number to their profile so Alvys can match transactions:
9. From the blue Alvys toolbar, select **Assets**, then choose **Drivers**.
10. Find and double-click a driver to open their profile.
11. In the first section of the profile, click the plus sign next to **Fuel Card Numbers**.

    <img alt="Driver profile with the Fuel Card Numbers (+) option highlighted" />

    *Driver profile with the Fuel Card Numbers (+) option highlighted*
12. Enter the fuel card number. For Pilot Flying J manual import, enter only the **last 3 digits** of the fuel card number.

    <img alt="Add Fuel Card Number pop-up with the PilotFlyingJ provider" />

    *Add Fuel Card Number pop-up with the PilotFlyingJ provider*
13. Select **PilotFlyingJ** in the Provider drop-down menu.
14. Check the applicable boxes if you want to deduct fuel or if fuel is discounted for this driver.
15. Click **Save**.
16. Repeat for each driver who has a Pilot Flying J fuel card.
17. Download the fuel transaction report from Pilot Flying J:
18. Log in to the Pilot Flying J Fuel Card portal.
19. Navigate to **Fuel Card > Reporting/Statements > Transactions**.

    <img alt="Pilot portal: Fuel Card > Reporting/Statements > Transactions" />

    *Pilot portal: Fuel Card > Reporting/Statements > Transactions*
20. Choose whether to view the report **By Invoice** or **By Date**, select the period, and click **Search**.
21. After the report generates, click **Export**, select **Excel**, and save the file to your device.

    <img alt="Exporting the transactions report to Excel" />

    *Exporting the transactions report to Excel*
22. Upload the fuel transaction file to Alvys. Before uploading, confirm each driver has the correct fuel card number (last 3 digits) entered in their profile.
23. From the blue Alvys toolbar, select **Reports**, then choose **Fuel Report**.

    <img alt="Alvys toolbar: Reports > Fuel Report" />

    *Alvys toolbar: Reports > Fuel Report*
24. Click the blue **Transaction File Upload** button.
25. In the pop-up window, select **PilotFlyingJ** from the **Integration Type** drop-down menu.

    <img alt="Quick Upload pop-up with PilotFlyingJ as the Integration Type" />

    *Quick Upload pop-up with PilotFlyingJ as the Integration Type*
26. Click the blue button to browse for your file, or drag and drop the Excel file you exported from the Pilot Flying J portal.
27. Upload the file.
28. Once the upload completes, use the **Transaction Date** range filter in the Fuel Report to review the imported transactions.

## Field & Data Mapping

* **Matching key:** Alvys matches transactions to driver profiles using the fuel card number. For Pilot Flying J, only the **last 3 digits** of the fuel card number are used. Each driver profile must have the correct last 3 digits entered, with **PilotFlyingJ** selected as the provider, before you upload a transaction file.
* **File format:** Alvys accepts the standard Fuel Card portal Excel export. Custom or reformatted files are not supported.

## Sync Behavior

The Pilot Flying J integration imports fuel transaction data from your Pilot Flying J Fuel Card account into the Alvys Fuel Report.

* **Direction:** One-way, Pilot Flying J to Alvys, via manual Excel file upload. There is no scheduled or automatic import.

<Warning>
  ⚠️ Only the last 3 digits of the Pilot Flying J fuel card number are used for driver matching. · Entering more or fewer digits will prevent transactions from being matched. · Uploading the same file again may create duplicate entries.
</Warning>

## Verify It's Working

After uploading, use the **Transaction Date** range filter in the Fuel Report to confirm the imported transactions appear and are matched to the correct drivers.

## Troubleshooting

### Fuel transactions are not appearing after upload

Confirm that each driver's fuel card number in Alvys shows the last 3 digits of their Pilot Flying J card and that **PilotFlyingJ** is selected as the provider on the driver's profile. Alvys uses this number to match transactions from the uploaded file to the correct driver.

### The upload pop-up does not show PilotFlyingJ as an option

Confirm the Pilot Flying J integration is active in Management > Integrations. If the integration does not appear, return to the connect steps and reactivate it for the correct subsidiary.

### The Excel file fails to upload

Confirm the file is the unmodified export from the Pilot Flying J portal in Excel format. Modifying the file structure before uploading may cause the import to fail.

## Limits and Unsupported

* Import is manual and one-way (Pilot Flying J to Alvys); there is no scheduled or automatic sync.
* Only the standard Fuel Card portal Excel export is supported. Custom or reformatted files are not supported.
* Only the last 3 digits of the fuel card number are used for matching.

## FAQs

**Q: How many digits of the fuel card number do I enter in the driver profile?**

**A:** For the Pilot Flying J manual import, enter only the last 3 digits of the fuel card number in the driver's profile.

**Q: How often should I upload fuel transaction reports?**

**A:** This depends on your reporting and settlement schedule. Many teams upload weekly or after each billing period.

**Q: What if a driver's transactions are not showing up after I upload the file?**

**A:** Confirm the driver has the correct last 3 digits of their Pilot Flying J fuel card number entered in their profile, and that **PilotFlyingJ** is selected as the provider. If the card number or provider is incorrect, the transactions cannot be matched to that driver.

**Q: Can I upload the same file more than once?**

**A:** Uploading the same file again may result in duplicate entries. Review the Fuel Report before re-uploading to check whether the transactions already appear.


# PrePass Toll Integration
Source: https://docs.alvys.com/en/help/integrations/prepass-toll-integration

Import PrePass toll transactions into Alvys by uploading a Toll Details report; match charges to trucks by transponder ID and deduct tolls from owner-operators.

<Note>
  The PrePass toll integration lets you import toll transaction data from PrePass into Alvys via manual file upload: use it to track toll expenses, reconcile charges, and deduct tolls from owner-operator paystubs.
</Note>

## Overview

The PrePass toll integration lets you import toll transaction data from PrePass into Alvys. This is a manual, one-way import: you download a Toll Details report from the PrePass Reports Portal and upload it into Alvys. Alvys matches each toll transaction to the correct truck using the transponder ID stored in the truck's Pass Details.

Use this integration to track toll expenses across your fleet, reconcile toll charges, and deduct tolls from owner-operator paystubs where applicable. Only owner-operator trucks will see toll deductions on paystubs.

Also known as: PrePass tolls, toll transponder import, toll report upload. PrePass transponder numbers typically start with 77.

## Prerequisites

Before setting up this integration, confirm the following:

* You have Admin, Partner Admin, or Office Admin access in Alvys.
* You have login credentials for your PrePass account at [www.prepass.com](http://www.prepass.com/).
* Your subsidiaries are already configured in Alvys.
* You have the transponder IDs for each truck that uses PrePass.

## How to connect

No API credentials are required for the PrePass integration. Enabling the integration registers PrePass as an available upload type in the Toll Report.

1. Go to **Management** and select the subsidiary you want to integrate with PrePass.
2. Click the blue **Integrate** button.
3. In the integrations list, scroll down to the **Tolls** section.
4. Select **PrePass** from the list.
5. Select all subsidiaries that will use PrePass for tolls.
6. Click the blue **Save** button.

   After enabling the integration, add transponder IDs to each truck so transactions can be attributed:
7. From the Alvys toolbar, go to **Assets** and select **Trucks**.
8. Select the truck that corresponds with the transponder you want to add.
9. Scroll down to the **Pass Details** section.
10. Set whether to deduct tolls using the Deduct Tolls option.
11. Select **PrePass** in the **Issued By** field.
12. Enter the transponder ID in the **Pass Number** field. PrePass transponder numbers typically start with 77.

    <img alt="This image shows the Pass Details section of a truck profile with the Issued By field set to PrePass and the Pass Number field." />

    *This image shows the Pass Details section of a truck profile with the Issued By field set to PrePass and the Pass Number field.*
13. Click **Add Pass** to save.

    Repeat for all trucks that use PrePass transponders.

    Then download the toll transactions from PrePass:
14. Log in to your PrePass account at [www.prepass.com](http://www.prepass.com/).
15. Click **Select** on the corresponding PrePass account.

    <img alt="This image shows the PrePass account selection screen." />

    *This image shows the PrePass account selection screen.*
16. Go to **Reports Portal**.

    <img alt="This image shows the PrePass navigation with the Reports Portal option highlighted." />

    *This image shows the PrePass navigation with the Reports Portal option highlighted.*
17. Go to **Toll Details**.

    <img alt="This image shows the Toll Details section in the PrePass Reports Portal." />

    * This image shows the Toll Details section in the PrePass Reports Portal.\*
18. Enter your date range.

    <img alt="This image shows the date range entry fields in the PrePass Toll Details report." />

    * This image shows the date range entry fields in the PrePass Toll Details report.\*
19. Click **View Report**.

    <img alt="This image shows the View Report button in the PrePass Toll Details screen." />

    *This image shows the View Report button in the PrePass Toll Details screen.*
20. Click the export icon and select your file format.

    <img alt="This image shows the export icon with the CSV option highlighted." />

    *This image shows the export icon with the CSV option highlighted.*
21. Save the file to your device.

    <img alt="This image shows the file save dialog after clicking export from PrePass." />

    *This image shows the file save dialog after clicking export from PrePass.*

    Finally, upload the report to Alvys:
22. From the Alvys toolbar, go to **Reports** and select **Toll Report**.

    <img alt="This image shows the Alvys toolbar with Reports selected and Toll Report highlighted." />

    *This image shows the Alvys toolbar with Reports selected and Toll Report highlighted.*
23. On the Toll Report page, click the blue **upload button** in the bottom right of the screen.

    <img alt="Notion Image" />
24. In the popup, select **PrePass** as the source, add the file, and click **Upload**.

    <img alt="This image shows the upload popup with PrePass selected as the source and the file upload area visible." />

    *This image shows the upload popup with PrePass selected as the source and the file upload area visible.*
25. Once the file uploads successfully, the toll transactions will appear in the Toll Report.

<Note>
  Both the CSV and Excel versions of the PrePass Toll Details report can be uploaded. Export whichever format is easier for you to save from the Reports Portal.
</Note>

## What syncs

After uploading a PrePass report, Alvys maps transaction data as follows:

* The transponder ID on the report is matched against the Pass Number stored in each truck's Pass Details section. Transactions are attributed to the truck whose transponder ID matches, including transactions imported from the Excel version of the report.
* Each transaction is dated from the exit date and time recorded in the PrePass report, not the date you uploaded the file. A report covering an earlier period lands on the days the tolls were actually incurred, so a late upload does not bunch every charge onto the upload date.
* Entry and exit details from the report are imported alongside the transaction, so you can see where each toll was incurred without opening the PrePass portal.
* Transaction date and toll amount are imported into the Toll Report.
* For trucks marked as owner-operator with the Deduct Tolls option enabled, the toll amount is applied as a deduction on the driver's paystub.
* If the transponder ID on a transaction does not match any truck profile, the transaction will not be attributed. Add or correct the transponder ID on the truck profile, then re-upload the file.

The PrePass integration is a manual, one-way sync from PrePass to Alvys. You initiate each import yourself, there is no automatic or scheduled sync, and Alvys does not write data back to PrePass. Only owner-operator trucks see toll deductions on paystubs; company trucks do not.

## Troubleshooting

### Toll transactions not appearing after upload

1. Go to **Assets > Trucks** and open the truck profile. Confirm a PrePass transponder ID is saved in the Pass Details section under Pass Number, and that **PrePass** is selected in the Issued By field.
2. Verify the transponder ID in Alvys matches what appears in the PrePass export.
3. Correct the transponder ID if needed, then re-upload the report.
4. If transactions are still missing after correcting the transponder ID, contact Alvys support.

### Owner-operator toll deductions not appearing on paystub

1. Confirm the truck is associated with an owner-operator driver in Alvys.
2. Confirm the **Deduct Tolls** option is enabled in the truck's Pass Details section.
3. Re-upload the toll report after confirming both settings.
4. Contact Alvys support if deductions are still not appearing.

### Upload fails or returns an error

1. Confirm you selected **PrePass** as the source in the upload popup.
2. Confirm the file is the Toll Details report downloaded from the PrePass Reports Portal.
3. Contact Alvys support if the error persists.

## FAQs

**Q: How do I find my PrePass transponder number?**

**A:** PrePass transponder numbers typically start with 77. You can find them in your PrePass account under your fleet or transponder management section.

**Q: Do all trucks need a transponder ID added in Alvys?**

**A:** Yes. Each truck that uses PrePass must have its transponder ID saved in the Pass Details section of the truck profile.

**Q: Will toll deductions show up on all driver paystubs?**

**A:** No. Only owner-operator trucks with the Deduct Tolls option enabled will have toll amounts deducted on paystubs.

**Q: Which date does an imported toll transaction use?**

**A:** The exit date and time from the PrePass report, not the date you uploaded the file. Uploading a report a few days late still records each toll on the day it was incurred.

**Q: How often should I upload toll transaction reports?**

**A:** This depends on your reporting and reconciliation schedule. Upload frequency should align with your settlement cycle.

**Q: Does this integration support automatic imports?**

**A:** No. Each upload must be initiated manually. The integration is one-way: data flows from PrePass into Alvys only.


# Project44 (P44) Integration
Source: https://docs.alvys.com/en/help/integrations/project44-p44-integration

Push carrier location data from Alvys to Project44 (P44) at scheduled intervals so shippers can monitor freight in transit through outbound visibility.

<Note>
  The Project44 (P44) integration automatically sends carrier location data from Alvys to P44 at configured intervals so shippers can monitor freight in real time; this is an outbound-only integration.
</Note>

## Overview

The Project44 (P44) integration (also referred to as P44 visibility or carrier push tracking) enables Alvys to automatically submit carrier location information to P44 at specific time intervals. P44 is a logistics visibility platform that shippers use to monitor freight in transit. Once connected, Alvys activates automatic location updates on qualifying loads, sending position data to P44's system so shippers can view real-time tracking for their shipments.

This integration is outbound only: Alvys sends data to P44. P44 does not push data back into Alvys.

## Prerequisites

Before setting up the integration in Alvys, the following conditions must be met:

* P44 must create a dedicated integration user for your carrier. This is not a standard P44 portal login. The integration user is scoped by region (for example, North America or Europe) and by the P44 carrier profile. Carriers with multiple SCACs may need separate integration users if those SCACs are tied to different carrier profiles.
* The shipper must enable Carrier Push Tracking for your carrier inside the P44 portal. If the shipper has not enabled this setting, no tracking data will flow regardless of how the integration is configured in Alvys.

To request a dedicated integration user, fill out the [TMS self-serve form](https://support.p-44.com/hc/en-us/requests/new?ticket_form_id=19537289922205) or contact P44 directly. P44 will ask for an email address you manage and the name of at least one shipper customer you want the integration activated for.

## How to connect

1. Add the integration in Alvys.

   * Navigate to Management > Integrations.
   * Select the integration type Visibility and choose Project 44.

<Note>
  <img alt="Image: Screenshot of the Visibility / Project 44 integration selection screen." />

  *Image: Screenshot of the Visibility / Project 44 integration selection screen.*
</Note>

1. Enter credentials. Enter the credentials for the P44-created integration user provided by P44. Do not use a standard P44 portal login — using a regular portal login will cause 401 authentication errors.
2. Save and validate. Save the integration, then proceed to the validation checklist in the What syncs section below to confirm the connection is functioning correctly.

### Configure P44 portal permissions

After the integration user is created by P44, sign in with that integration user (or have P44 manage it) and navigate to User Management in the P44 portal. Locate the OAuth client associated with this user, which is typically labeled with Alvys.

Add the permission Carrier Push Tracking API to that OAuth client. This permission is required for all API calls from Alvys to P44.

If the shipper has not yet enabled Carrier Push Tracking for your carrier in P44, ask them to do so before testing. Without this shipper-side setting, the integration will authenticate successfully but no updates will be received by the shipper.

## What syncs

Alvys sends carrier location updates to P44 tied to the Shipment ID associated with each load. P44 matches incoming location data to the correct shipment record using this identifier.

Event settings and event sources for each customer can be customized within Alvys. Customization controls which location events are sent and from which data source (for example, ELD or GPS).

Once the conditions for sending the initial location update are met for a load, Alvys activates the automatic location update indicator for P44 in Load Details. From that point, Alvys submits location information at regular intervals. Updates can be paused at two levels:

* Per load: disable sending directly from Load Details.
* Per customer: adjust the P44 preferences on the Customer Profile to stop updates for all loads tied to that customer.

### Customize P44 preferences

P44 event settings and event sources can be customized per customer in the Customer Profile. This controls which tracking events are submitted to P44 and from which location source.

<Note>
  <img alt="P44 preferences section in the Customer Profile showing event settings and source controls" />

  *P44 preferences section in the Customer Profile showing event settings and source controls*
</Note>

### Manage automatic location updates

Once initial conditions are met for a load, Alvys activates the automatic location update indicator for P44 in Load Details. You can disable updates for that specific load directly from Load Details.

<Note>
  <img alt="Load Details screen showing the P44 automatic location update indicator and the control to disable it" />

  *Load Details screen showing the P44 automatic location update indicator and the control to disable it*
</Note>

To disable updates at the customer level, repeat the Customize P44 preferences workflow for the relevant Customer Profile.

Use this checklist after setup to confirm the integration is functioning correctly:

* The integration authenticates without 401 errors.
* The Carrier Push Tracking API permission is enabled on the integration user's OAuth client in P44.
* The shipper has enabled Carrier Push Tracking for your carrier in the P44 portal.
* A test shipment's location updates appear in P44 under the correct Shipment ID.

<Note>
  📋 Limits and unsupported: This integration does not support inbound visibility: P44 cannot push data into Alvys. · Co-Pilot integration with P44 is not currently supported. · Carriers with multiple SCACs tied to separate P44 carrier profiles may require separate integration users per profile.
</Note>

## Troubleshooting

### 401 authentication errors

A 401 error means the integration cannot authenticate with P44. Check the following in order:

1. Confirm you are using the dedicated P44 integration user credentials, not a standard portal login.
2. Confirm the integration user's OAuth client in P44 has the Carrier Push Tracking API permission enabled.
3. Confirm the integration user is scoped to the correct region (for example, North America vs. Europe).
4. Ask the shipper to confirm Carrier Push Tracking is enabled for your carrier in their P44 portal.

### Location updates not appearing for the shipper

If authentication succeeds but the shipper cannot see location updates in P44:

1. Confirm the shipper has enabled Carrier Push Tracking for your carrier in P44.
2. Confirm the Shipment ID in Alvys matches what P44 is expecting for the shipment.
3. Check whether updates are disabled at the load or customer level in Alvys.

### ELD telematics conflict

If the carrier also sends telematics data (for example, from Samsara) using a different Shipment ID, P44 prioritizes the ELD source. To resolve this, align the Shipment IDs across both data sources or pause the telematics feed as needed.

### Cross-region account issues

If a carrier operates in one region (for example, EU) but the shipper's P44 account is in another region (for example, North America), P44 may need to mirror the carrier's account across regions. Contact P44 support directly to request this.

If none of the above steps resolve the issue, contact Alvys Support and provide the Shipment ID, the integration user email, and the specific error. Alvys Support will coordinate with P44 as needed.

## FAQs

**Q: Can I use my regular P44 portal login for this integration?**

**A:** No. You must use a dedicated integration user created by P44 specifically for API access. Using a standard portal login will cause 401 errors.

**Q: Why am I getting 401 authentication errors after entering my credentials?**

**A:** Confirm that you used the dedicated integration user credentials (not a regular P44 login), that the Carrier Push Tracking API permission is enabled on the user's OAuth client in P44, and that the shipper has enabled Carrier Push Tracking for your carrier in P44.

**Q: What if my carrier operates in multiple regions?**

**A:** You may need separate integration users scoped to each region, or P44 can mirror your account across regions. Contact P44 to request cross-region mirroring.

**Q: How do I stop location updates for a specific load?**

**A:** Open the load in Load Details and disable the P44 automatic location update indicator. To stop updates for all loads under a customer, adjust the P44 preferences in the Customer Profile.

## Go Deeper

* [How to Set Up and Manage Integrations in Alvys](/en/help/integrations/project44-p44-integration)


# QuikQ (Love's) Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/quikq-love-s-fuel-integration

Activate the QuikQ (Love's) fuel integration to automatically pull Love's Travel Stops fuel card transactions into Alvys twice daily through the QuikQ API.

<Note>
  The QuikQ (Love's) fuel integration connects Love's Travel Stops fuel card data with Alvys using the QuikQ API; once configured, Love's fuel transactions are automatically imported into Alvys twice daily at 1 AM and 2 AM Eastern Time. Also known as Love's fuel integration, QuikQ fuel, Love's Travel Stops fuel card sync, Love's Connect.
</Note>

## Overview

The QuikQ (Love's) fuel integration connects Love's Travel Stops fuel card data with Alvys using the QuikQ API. Unlike manual fuel imports, this integration is automatic: once configured, Love's fuel transactions are imported into Alvys twice daily at 1 AM and 2 AM Eastern Time without any file uploads required.

Use this integration to track Love's fuel expenses, apply fuel deductions to driver pay, and maintain accurate fuel records in your Fuel Report.

Also known as: Love's fuel integration, QuikQ fuel, Love's Travel Stops fuel card sync, Love's Connect.

## Prerequisites

Before setting up this integration, complete the following:

* You have Admin, Partner Admin, or Office Admin access in Alvys.
* You have a QuikQ account with API access enabled. This must be requested separately before setup (see How to connect below).
* You have your Love's QuikQ portal credentials (username and password).
* You have your carrier ID from the Love's portal (used as the Start Code in Alvys).
* Your subsidiaries are already configured in Alvys.

## How to connect

First, request API access from QuikQ. Email [support@quikq.com](mailto:support@quikq.com) and request that API permission be added to your user profile, specifying which user profile needs the permission. Complete this step before attempting to configure the integration in Alvys. You will not be able to authenticate without this permission.

Once you have API access from QuikQ, activate the integration in Alvys:

1. Click your username in the bottom left corner of Alvys, then select **Integrations**.

   <img alt="This image shows the Integrations page in Alvys with the Fuel category" />

   \*This image shows the Integrations page in Alvys with the Fuel category \*
2. Select the subsidiary you want to connect.
3. Expand the **Fuel** category.
4. Click the gray pencil icon next to **QuikQ/Love's**.

   <img alt="This image shows the Fuel category expanded with the QuikQ/Love's pencil icon." />

   *This image shows the Fuel category expanded with the QuikQ/Love's pencil icon.*
5. Enter your credentials:

   * **Start Code:** Your carrier ID from within the Love's portal.
   * **Username:** Your Love's QuikQ portal username.
   * **Password:** Your Love's QuikQ portal password.

<Note>
  <img alt="This image shows the QuikQ/Love's credentials form with fields for Start Code, Username, and Password." />

  *This image shows the QuikQ/Love's credentials form with fields for Start Code, Username, and Password.*
</Note>

<Note>
  <img alt="This image shows where to find the carrier ID in the Love's portal, which is used as the Start Code in Alvys." />

  *This image shows where to find the carrier ID in the Love's portal, which is used as the Start Code in Alvys.*
</Note>

1. Click **Save**.

   Once saved, the integration will begin automatically importing transactions at the next scheduled run (1 AM or 2 AM Eastern Time).

   Next, add fuel card numbers to driver profiles so transactions can be attributed. Each driver must have the last 6 digits of their Love's fuel card number saved on their profile:
2. From the Alvys toolbar, go to **Assets** and select **Drivers**.
3. Find and double-click a driver to open their profile.
4. In the first section, click the plus sign next to **Fuel Card Numbers**.

   <img alt="Notion Image" />
5. Enter the last six (6) digits of the driver's Love's fuel card number.
6. Select **Love's Fuel** as the provider.
7. Set the deduct fuel and discounted fuel checkboxes if applicable.

<Note>
  <img alt="This image shows the Fuel Card Numbers section of a driver profile with the plus sign to add a new card." />

  *This image shows the Fuel Card Numbers section of a driver profile with the plus sign to add a new card.*
</Note>

<Note>
  <img alt="This image shows the fuel card entry popup" />

  *This image shows the fuel card entry popup*
</Note>

1. Click the blue **Save** button.

Repeat for each driver who has a Love's fuel card. After saving driver card numbers, fuel transactions will be automatically attributed starting from the next scheduled import.

## What syncs

After each automatic import, Alvys maps QuikQ transaction data as follows:

* The last 6 digits of the fuel card number on the QuikQ transaction are matched against the last 6 digits stored in each driver's profile. Transactions are attributed to the driver whose card number matches.
* Transaction date, amount, and gallons are imported into the Fuel Report.
* If the card number on a transaction does not match any driver profile, the transaction will not be attributed to a driver. Add or correct the card number on the driver profile; it will be matched on the next automatic import.

The QuikQ integration is an automatic, one-way sync from QuikQ to Alvys. Transactions are imported at 1 AM and 2 AM Eastern Time each day, no manual file upload is required, and Alvys does not write data back to QuikQ.

## Troubleshooting

### Fuel transactions not appearing after integration setup

1. Confirm the integration was saved successfully in **Management > Integrations > Fuel > QuikQ/Love's**.
2. Confirm your QuikQ account has API permission enabled. Contact QuikQ support at [support@quikq.com](mailto:support@quikq.com) to confirm.
3. Wait until after the next scheduled import window (1 AM or 2 AM Eastern Time) and check the Fuel Report again.
4. If transactions are still not appearing, contact Alvys support.

### Driver transactions not attributed correctly

1. Open the driver profile in **Assets > Drivers** and confirm a Love's fuel card number is saved with exactly 6 digits.
2. Confirm the provider is set to **Love's Fuel**.
3. Correct the card number if needed. The next automatic import will match transactions using the updated number.

### Integration credentials rejected

1. Confirm the Start Code is your carrier ID from the Love's portal.
2. Confirm the Username and Password are your Love's QuikQ portal credentials.
3. Confirm API permission is enabled on your QuikQ user profile.
4. Contact Alvys support if credentials are still rejected after confirming all three items above.

## FAQs

**Q: Why do I need API permission before setting up the integration?**

**A:** API permission is required for Alvys to connect to your QuikQ account and retrieve transaction data. Without it, the integration cannot authenticate and import fuel data.

**Q: Do I enter the full fuel card number or just part of it?**

**A:** Enter only the last six (6) digits of the fuel card number when adding it to a driver profile in Alvys.

**Q: How often do fuel transactions import?**

**A:** Transactions are automatically imported twice daily at 1 AM and 2 AM Eastern Time.

**Q: What is the Start Code?**

**A:** The Start Code is your carrier ID from within the Love's portal. It is not the same as your QuikQ username.

**Q: What if a driver's fuel transactions are not showing up?**

**A:** Verify that you entered the correct last 6 digits of their Love's fuel card number and that Love's Fuel is selected as the provider in their driver profile. Transactions will be matched on the next automatic import after you save the correct number.


# Relay Payments Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/relay-payments-fuel-integration

Connect Relay Payments to Alvys to auto-import cardless, digital fuel purchases into the Fuel Report and Pay Drivers page daily at 5 AM Eastern Time.

<Note>
  Relay Payments is a cardless, digital fuel payment system; once connected, all fuel purchases made through Relay are automatically imported into Alvys every day at 5 AM Eastern Time. Also known as Relay fuel integration, cardless fuel, digital fuel payments, Relay Driver ID sync.
</Note>

## Overview

Relay Payments is a cardless, digital fuel payment system that eliminates physical fuel cards. With this integration, all fuel purchases made through Relay are automatically imported into Alvys every day at 5 AM Eastern Time and displayed on the Fuel Report and Pay Drivers pages without manual entry.

This integration requires setup on both the Relay side and in Alvys before transactions begin syncing.

Also known as: Relay fuel integration, cardless fuel, digital fuel payments, Relay Driver ID sync.

## Prerequisites

Before you begin setup in Alvys, complete the following:

* You must have an active Relay Payments account.
* Contact your Relay account representative and request the Alvys fuel integration be enabled for your account. Relay will activate a 16-digit Relay Driver ID for each driver in your Relay portal. This ID functions like a fuel card number in Alvys and links each driver's transactions to their profile.
* Wait for Relay to confirm the integration is active on their side before proceeding.

## How to connect

Once Relay has activated the integration for your account:

1. Click your username in the bottom left corner of Alvys and select **Integrations**.
2. Select the subsidiary you want to connect.
3. Expand the **Fuel Cards** section and locate **Relay**.
4. Click the pencil icon to open the integration settings.
5. Enter the Token ID provided by your Relay account representative.
6. Click **Save**.

   Next, add each driver's Relay Driver ID to their profile so transactions can be attributed:
7. Navigate to **Assets** and select **Drivers**.
8. Find and double-click the driver to open their profile.
9. Click the plus sign next to **Fuel Card Numbers**.
10. Enter the driver's 16-digit Relay Integration ID (provided by Relay in their portal).
11. Select **Relay** as the fuel card provider.
12. Configure the deduction settings for each transaction type as needed.
13. Click **Save**.

<Note>
  <img alt="This image shows the Relay portal displaying the 16-digit Relay Driver ID stored on a driver's profile." />

  *This image shows the Relay portal displaying the 16-digit Relay Driver ID stored on a driver's profile.*
</Note>

Repeat this process for every driver who uses Relay for fuel.

## What syncs

Each Relay Driver ID maps to a specific driver in Alvys. For fuel transactions to be attributed to the correct driver, the Relay Driver ID must be added to that driver's profile in Alvys.

* Alvys imports all Relay transactions automatically every day at 5 AM Eastern Time.
* Imported transactions appear in the **Fuel Report** and the **Pay Drivers** section.
* There is no manual upload step; once the integration is active and driver IDs are configured, transactions sync automatically.

The integration is one-way: data flows from Relay into Alvys only, and Alvys does not send data back to Relay.

## Troubleshooting

### Relay transactions not appearing in the Fuel Report

1. Confirm the integration is active. Go to **Management > Integrations > Fuel Cards > Relay** and verify the Token ID is saved.
2. Confirm the driver's Relay Integration ID is entered correctly in their driver profile. The ID must be the exact 16-digit value from the Relay portal.
3. Check that the date range on the Fuel Report includes the date the transaction occurred. Transactions import at 5 AM Eastern Time, so transactions from today will not appear until the following morning.
4. If none of the above resolves the issue, contact Alvys support.

### Relay Driver IDs not appearing in the Relay portal

The Relay Driver ID is activated by Relay, not Alvys. If the ID is missing from a driver's Relay profile, contact your Relay account representative to confirm activation is complete.

## FAQs

**Q: What makes Relay different from traditional fuel cards?**

**A:** Relay is a cardless, digital payment system that enables real-time transactions without physical cards. This reduces fraud risk and simplifies the payment process for drivers.

**Q: How often do Relay transactions import into Alvys?**

**A:** Transactions are automatically imported daily at 5 AM Eastern Time.

**Q: What is the Relay Driver ID?**

**A:** The Relay Driver ID is a 16-digit identifier that functions like a fuel card number in Alvys. It is assigned by Relay and links each driver's fuel purchases to their profile in both systems.

**Q: Where can I find the Token ID needed for setup?**

**A:** The Token ID is provided by your Relay account representative when they activate the Alvys integration for your account.

**Q: Can I set up the integration before Relay activates it on their side?**

**A:** No. Relay must activate the integration and provide the Token ID before you can complete setup in Alvys. Contact your Relay representative first.


# Requesting an EDI Connection
Source: https://docs.alvys.com/en/help/integrations/requesting-an-edi-connection

Start an EDI setup with a customer or trading partner directly from Alvys.

### Overview

You can kick off an EDI onboarding yourself from the EDI & Visibility page — no need to email support to get started. Fill out a short form with the trading partner and the documents you want to exchange, and Alvys creates the request and hands it to our EDI team to begin setup.

### Submit a request

1. Go to **Manage → EDI & Visibility**.
2. Click **Request EDI**.
3. Complete the form (see **What you’ll enter** below).
4. Click **Submit**. The button stays disabled until every field is valid.

<Note>
  <img alt="Screenshot" />
</Note>

### What you’ll enter

* **Customer** — the company you’re setting up EDI with. Start typing to search for it; if it’s not in Alvys yet, you can add it right from this field.
* **Subsidiary** — the subsidiary this connection is for.
* **SCAC** — your SCAC code (2–4 letters or numbers).
* **Transaction types** — the EDI documents you want to exchange. Select all that apply: 204 (Load Tender), 210 (Invoice), 213 (Status Inquiry), 214 (Shipment Status), 990 (Tender Response), 997 (Acknowledgment).
* **Your contact** — your email, filled in automatically. Add others on your team if you’d like.
* **Trading partner contact** — the email address(es) for the customer’s (or their EDI provider’s) contact. Enter their addresses, not your own.

### Track your connection

After you submit, your new EDI connection appears on the **EDI & Visibility** page as an integration card — the same card as any other integration. Its status shows where it is in onboarding: it starts when your request is submitted, moves through onboarding (for example, **In Progress**), and finishes at **Active** once the connection goes live. Check that card any time to see where things stand — our EDI team handles the setup from here and reaches out to the contacts you provided as needed.


# RTS Financial Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/rts-financial-factoring-integration

Submit invoice batches to RTS Financial via FTP from Alvys, then upload Purchase and Payment reports from the RTS Pro portal to update factored load statuses.

<Note>
  RTS connects to Alvys via FTP to automate invoice batch submission for factoring clients. Purchase and payment reports are downloaded from the RTS Pro portal and uploaded into Alvys to update load statuses. Synonyms: RTS Financial, RTS factoring, RTS Pro.
</Note>

## What This Integration Does

RTS is an FTP-based factoring integration. Alvys submits invoice batches to RTS via FTP. Users then download Purchase and Payment reports from the RTS Pro portal ([rtspro.com](http://rtspro.com/)) and upload them into Alvys to update load statuses. Separate FTP credentials are required for each subsidiary.

## Prerequisites

* Active account with RTS Financial
* FTP credentials issued by RTS (one set per subsidiary; requires signing the Transfer Protocol Server Access Agreement)
* Notice of Assignment text provided by RTS
* Admin, Partner Admin, or Support access to configure the integration
* **"Billing"** permission to submit batches and upload reports

Before requesting FTP credentials, ensure all subsidiaries are set up in Alvys.

## Connect / Authenticate

### Part 1: Configure Your Notice of Assignment

1. Navigate to Management > Company Profile.
2. Select the subsidiary that will use the RTS integration. In the **Document Configuration** section, click the blue plus sign **(+)** button. A new window opens: the Manage Important Info window.
3. In the drop-down menu, select **Notice of Assignment**. Copy and paste the Notice of Assignment text provided by RTS into the text box.
4. Click the blue **Save** button.

### Part 2: Request FTP Credentials from RTS

1. Email your RTS sales representative and request FTP credentials. Note that you need a separate set of credentials for each subsidiary.
2. RTS will ask you to sign the **Transfer Protocol Server Access Agreement**. Sign and return it. Once received, RTS will issue your FTP credentials.
3. Proceed to Part 3 after receiving credentials.

### Part 3: Configure Each Subsidiary in Alvys

1. Navigate to Management > Integrations.

   <img alt="RTS Integration Details page showing subsidiary selector and FTP Factoring section" />

   * RTS Integration Details page showing subsidiary selector and FTP Factoring section\*
2. Select the subsidiary you want to configure. Expand the **FTP Factoring** section. Click the **pencil icon** next to **RTS** to edit the credentials.
3. Enter the FTP credentials provided by RTS. Click the blue **Save** button.

Repeat the steps above for each subsidiary.

## Field & Data Mapping

Alvys generates a batch file containing invoice data for the selected loads and submits it to RTS via FTP. The file format (xlsx or csv) depends on your account configuration with RTS. No field mapping is required on the Alvys side; the file structure matches RTS's expected format.

## Sync Behavior

Batch submission is initiated manually from Accounting > Factoring Upload. There is no automated nightly sync. Load status updates depend on report uploads:

* After batch submission: loads move to **Invoiced**
* After Purchase Report upload: loads move to **Financed**
* After Payment Report upload: loads move to **Completed**

## Submit a Batch

1. In Alvys, navigate to **Accounting > Factoring Upload**. All loads must have a **Queued** status with invoicing method set to factoring before they appear in this list.
2. Select the correct subsidiary.

   <img alt="Subsidiary selector on Factoring Upload page" />

   *Subsidiary selector on Factoring Upload page*
3. Select all invoices you want to include in the batch.

   <img alt="Invoice selection list with checkboxes" />

   *Invoice selection list with checkboxes*
4. Click the **Submit Batch** button.

   <img alt="Submit Batch button" />

   *Submit Batch button*
5. Wait until the submission is complete. Do not close this page or navigate away; doing so may disrupt the submission.

## Upload Your Purchase Report

1. Log in to the RTS Pro portal and navigate to the Purchase History Report page at: [https://rtspro.com/factoring/reports/purchase-history](https://rtspro.com/factoring/reports/purchase-history)
2. Open the respective batch by clicking on it.

   <img alt="Batch list on RTS Pro portal" />

   * Batch list on RTS Pro portal\*
3. Click the **Download** button to save the report in **.xlsx** format to your device.

   <img alt="Download button on RTS Pro portal" />

   *Download button on RTS Pro portal*
4. In Alvys, navigate to **Reports > Factoring**. Find the respective batch.

   <img alt="Alvys Factoring Reports page showing the batch" />

   *Alvys Factoring Reports page showing the batch*
5. Select the batch and click the blue **Upload Purchase Report** button in the **bottom right corner** of the page.

   <img alt="Upload Purchase Report button in bottom right corner" />

   * Upload Purchase Report button in bottom right corner\*
6. Drag and drop the file into the upload area, or click to select it from your device.

   <img alt="Drag-and-drop upload area" />

   *Drag-and-drop upload area*
7. Click **Upload**.

   <img alt="Upload button" />

   * Upload button\*

## Upload Your Payment Report

1. Log in to the RTS Pro portal and navigate to the Payments Report page at: [https://rtspro.com/factoring/reports/payments-report](https://rtspro.com/factoring/reports/payments-report)
2. Enter the payment period, then click **View**.

   <img alt="Payment period input field on RTS Pro portal" />

   * Payment period input field on RTS Pro portal \*
3. Click the **Download** button to save the file to your device.

   <img alt="Download button for payment report" />

   *Download button for payment report*
4. In Alvys, navigate to **Reports > Factoring**. Click the **Upload Report** button.

   <img alt="Upload Report button on Factoring Reports page" />

   *Upload Report button on Factoring Reports page*
5. Drag and drop the file into the blue section, or click to select it from your device.

   <img alt="Drag-and-drop blue upload area" />

   *Drag-and-drop blue upload area*
6. Click **Upload**.

   <img alt="Upload button" />

   * Upload button\*
7. Do not close this page until the report has finished processing. Depending on file size, this can take anywhere from several seconds to a few minutes.

## Verify It's Working

After submitting a batch, confirm that the selected loads have moved to **Invoiced** status in Alvys. After uploading the Purchase Report, confirm loads move to **Financed**. After uploading the Payment Report, confirm loads move to **Completed**.

## Troubleshooting

### Batch submission does not complete

1. Confirm you did not navigate away from the Factoring Upload page before the submission finished. If you did, return to Accounting > Factoring Upload and check whether the loads still show **Queued** status. If so, resubmit the batch.
2. Confirm the subsidiary has valid FTP credentials configured in Management > Integrations. Invalid or missing credentials will prevent submission.
3. If the issue persists after resubmitting with valid credentials, contact Alvys support.

### Upload Purchase Report or Upload Report button is not visible

1. Confirm you have the **"Billing"** permission. Users without this permission cannot see the upload buttons.
2. Navigate to Reports > Factoring and confirm the batch appears in the list. If the batch is not visible, confirm the batch was submitted successfully from Accounting > Factoring Upload.
3. If the batch was submitted successfully but does not appear in Reports > Factoring, contact Alvys support.

### Loads do not advance to Financed after Purchase Report upload

1. Confirm the upload completed without closing the page prematurely. If the page was closed during processing, re-upload the report.
2. Confirm the file uploaded is the **.xlsx** Purchase History Report downloaded from [rtspro.com](http://rtspro.com/). Uploading an incorrect file type will not update load statuses.
3. If loads remain at **Invoiced** after a confirmed successful upload, contact Alvys support.

## Limits / Unsupported

Separate FTP credentials are required for each subsidiary. A single set of credentials cannot be shared across subsidiaries.

The integration does not support automated or scheduled syncs. All batch submissions and report uploads are initiated manually.

## FAQs

**Q: Where do I get my FTP credentials?**

**A:** Email your RTS sales representative to request FTP credentials. RTS will ask you to sign the Transfer Protocol Server Access Agreement before issuing credentials.

**Q: Why do I need separate credentials for each subsidiary?**

**A:** RTS issues credentials at the subsidiary level. Each subsidiary must have its own set of FTP credentials configured in Alvys under Management > Integrations.

**Q: What format does the Purchase Report download in?**

**A:** The Purchase History Report downloads as an **.xlsx** file from the RTS Pro portal.

**Q: What happens if I close the page during a report upload?**

**A:** Closing the page before the upload finishes may interrupt processing. If this happens, return to Reports > Factoring and re-upload the report.

**Q: Can I submit loads from multiple subsidiaries in a single batch?**

**A:** No. Each batch is tied to a single subsidiary. Select the correct subsidiary on the Factoring Upload page before selecting invoices.


# Ryder Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/ryder-fuel-integration

Import Ryder fuel transactions into Alvys by uploading a RyderGyde Fuel Activity Report; Alvys links each charge to a truck by Ryder Vehicle Number.

<Note>
  Import fuel transactions from Ryder by downloading a Fuel Activity Report from the RyderGyde portal and uploading it to Alvys, where transactions are matched to trucks by Ryder Vehicle Number.
</Note>

## What this integration does

The Ryder fuel integration lets you upload a Fuel Activity Report from the RyderGyde app into Alvys, linking fuel transactions to trucks by Ryder Vehicle Number. This is a one-way, manual import: you download a report from RyderGyde and upload it into Alvys. Transactions are matched to trucks based on the Ryder Vehicle Number, not individual fuel cards. All Ryder fuel costs are treated as company expenses and are not deducted from driver pay.

Unlike other fuel integrations, Ryder does not issue fuel cards (fuel network cards) and does not support automatic daily imports.

<Info>
  💡 This integration is sometimes called the RyderGyde fuel report import, Ryder fuel activity upload, or Ryder fuel network import. · Matching is by Ryder Vehicle Number to truck number, with no driver-level fuel card mapping.
</Info>

## Prerequisites

Before you begin, confirm the following:

* You have **"Admin"**, **"Support"**, or **"Partner Admin"** access in Alvys (set on your user role in the Company Profile) and can reach the Management > Integrations page.
* Your trucks in Alvys must have truck numbers that exactly match the Ryder Vehicle Numbers in your Ryder account. If these do not match, transactions will not link to the correct truck.
* You have access to the RyderGyde portal to export fuel reports.

## Connect and authenticate

1. Click your username in the bottom left corner and select **Integrations** (or navigate to **Management** and select the **Integrations** tab).
2. Select the subsidiary you want to integrate with Ryder Fuel.
3. Expand the **Fuel Cards** section and locate **Ryder Fuel**.
4. Click the pencil icon to open the Add Integration window.
5. Click **Save** to activate the integration. No credentials are required for the Ryder integration; enabling it simply activates the ability to upload Ryder fuel reports for that subsidiary.
6. Download the Fuel Activity Report from RyderGyde:
7. Log in to the RyderGyde portal and select **Reports** from the menu.
8. Locate **Fuel** and select **See Report** for the **Spreadsheet** report. Do not select the Interactive report.
9. Set your date criteria. The Dynamic Date option is recommended.
10. Scroll to the bottom and click **Run Report**.
11. Under Report Home, select **Export** and choose **Excel** format. The report must be exported without summary information; the first row of the file must be the column names, not a summary header.

    <img alt="the RyderGyde Report Home screen with the Export option and Excel format selection highlighted" />

    *the RyderGyde Report Home screen with the Export option and Excel format selection highlighted*

    <Info>
      💡 Optional: RyderGyde lets you subscribe to automated report delivery so reports are generated and emailed on a schedule. · Under Report Home select **Subscribe To**, modify the subscription name if needed, open the **Schedule** dropdown and choose a recurring time, select **Excel** for the Delivery Format, select **Send a preview now** to receive a copy immediately, then click **OK**. · Even with a subscription, the first row of the file must be column names and summary information must not be included.
    </Info>
12. Upload the Fuel Activity Report to Alvys:
13. From the Alvys sidebar, navigate to **Reports** and select **Fuel Report**.
14. Click the **Transaction File Upload** button.

    <img alt="the Fuel Report page in Alvys with the Transaction File Upload button visible" />

    *the Fuel Report page in Alvys with the Transaction File Upload button visible*
15. In the pop-up window, select **Ryder Fuel** from the **Integration Type** drop-down menu.

    <img alt="the file upload pop-up with the Integration Type dropdown open and Ryder Fuel selected" />

    *the file upload pop-up with the Integration Type dropdown open and Ryder Fuel selected*
16. Click the blue button to browse for your Ryder Fuel Activity Report file, or drag and drop the file into the window.
17. Click **Upload**. Once uploaded, you can review the imported transactions by selecting a Transaction Date range in the Fuel Report.

## Field and data mapping

* **Matching:** The Ryder Vehicle Number in the exported report must exactly match the truck number in Alvys. There are no fuel card numbers or driver-level mappings for Ryder fuel.
* **Expense handling:** All transactions are recorded as company expenses and are not deducted from driver settlements.
* **Transaction grouping:** Multiple fuel purchases on the same day with the same invoice number are combined into one transaction with multiple line items. Unique transaction IDs are generated using Ryder Vehicle Number + Location ID + Fuel Disbursement Date + Fuel Disbursement Time.

## Sync behavior

The Ryder fuel integration imports fuel transactions from the RyderGyde Fuel Activity Report into the Alvys Fuel Report.

* **Direction:** One-way, RyderGyde to Alvys, via manual file upload. There is no automatic daily import.
* **Expense handling:** All transactions are recorded as company expenses and are not deducted from driver settlements.

## Verify it's working

To confirm a successful import, navigate to **Reports** and select **Fuel Report**, set the Transaction Date range to match the dates in the uploaded file, and confirm that transactions appear linked to the correct trucks. If a transaction does not appear linked to a truck, verify that the truck number in Alvys exactly matches the Ryder Vehicle Number in the report.

## Troubleshooting

### Transactions not linking to trucks

The Ryder Vehicle Number in the exported report does not match the truck number in Alvys. Update the truck number in Alvys to match exactly, then re-upload the report.

### Report upload fails or produces no transactions

The report may include summary information at the top. The first row of the uploaded file must be column names only. Re-export the report from RyderGyde without summary information and try again.

### Fuel transactions not appearing in driver pay

Ryder fuel transactions are always treated as company expenses and are never deducted from driver settlements. This behavior cannot be changed per transaction; it is how the Ryder integration works by design.

## Limits and unsupported

<Warning>
  ⚠️ Automatic daily imports are not supported; all uploads are manual. · Ryder does not issue individual fuel cards, so driver-level fuel card mapping is not used. · All Ryder fuel transactions are company expenses and cannot be deducted from driver pay. · Truck numbers must exactly match Ryder Vehicle Numbers; partial matches will not link transactions.
</Warning>

## FAQs

**Q: Why aren't fuel cards needed for Ryder?**

**A:** Ryder does not issue individual fuel cards like other providers. Transactions are linked to trucks directly through the Ryder Vehicle Number.

**Q: What if my truck numbers don't match the Ryder Vehicle Numbers?**

**A:** Transactions will not link to the correct truck. Update your truck numbers in Alvys to exactly match the Ryder Vehicle Numbers from your Ryder account, then re-upload the report.

**Q: Are fuel costs deducted from driver pay?**

**A:** No. All Ryder fuel transactions are company expenses and are not deducted from driver settlements.

**Q: How often should I upload fuel reports?**

**A:** This depends on your business needs. Setting up a subscription in RyderGyde for weekly or monthly automated report delivery makes the process easier and reduces manual work.

**Q: Can I upload reports for multiple subsidiaries?**

**A:** Yes. When enabling the Ryder Fuel integration, select the subsidiary you want to connect. You can repeat the setup for each subsidiary that uses Ryder fuel.


# Saint Johns Capital Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/saint-johns-capital-factoring-integration

Connect Saint Johns Capital (SJC) to Alvys via a two-way API to submit invoice batches for factoring and run automatic broker credit checks in real time.

<Note>
  Saint Johns Capital connects to Alvys via a two-way API to automate invoice submission and broker credit checks for factoring clients. Synonyms: Saint John Capital, SJC, Saint Johns factoring.
</Note>

## What This Integration Does?

Saint Johns Capital connects to Alvys through a two-way API. When a batch is submitted, Alvys sends invoice data to Saint Johns Capital directly. Saint Johns Capital also performs automatic and manual broker credit checks, returning results to Alvys in real time.

## Prerequisites

* Active account with Saint Johns Capital
* Client ID provided by Saint Johns Capital
* Notice of Assignment text provided by Saint Johns Capital
* Admin, Partner Admin, or Support access to configure the integration
* **"Billing"** permission to submit batches
* MC number set on each customer/broker that will be included in a batch

## Connect / Authenticate

Note: This integration uses an API connection.

### Part 1: Configure Your Notice of Assignment

* Navigate to Management > Company Profile.
* In the **General Info** tab, locate the **Important Information** section. Click the **(+)** button. The Manage Important Info pop-up opens.

<Note>
  <img alt="Company Profile General Info tab showing Important Information section with (+) button" />

  * Company Profile General Info tab showing Important Information section with (+) button\*
</Note>

* In the drop-down menu, select **Notice of Assignment**. Copy and paste the Notice of Assignment text provided by Saint Johns Capital.

<Note>
  <img alt="Manage Important Info pop-up with Notice of Assignment selected and text pasted" />

  \*Manage Important Info pop-up with Notice of Assignment selected and text pasted \*
</Note>

* Click **Save**.

### Part 2: Configure the Saint Johns Capital Integration

* Navigate to Management > Integrations.
* Select the subsidiary you want to configure. Expand the **Factoring** section. Click the “I**nactive**” button to **Saint John Capital**.

<Note>
  <img alt="Integrations page showing Factoring section expanded with Saint John Capital “Inactive” button visible" />

  *Integrations page showing Factoring section expanded with Saint John Capital “**Inactive**” button visible*
</Note>

* Enter your **Client ID** provided by Saint Johns Capital.

<Note>
  <img alt="Add Integration dialog with Client ID field" />

  *Add Integration dialog with Client ID field*
</Note>

* Click the blue **Save** button.

If you have multiple subsidiaries with Saint Johns Capital accounts, repeat the four configuration actions above for each subsidiary.

## Field & Data Mapping

Alvys sends invoice data to Saint Johns Capital, including load number, debtor information, invoice amount, and MC number. Alvys also sends three supporting documents for each invoice: the Bill of Lading (or Rate Confirmation if no Bill of Lading is present), the Rate Confirmation as a separate rate sheet, and the Receipt. Each document type is submitted in a separate field. The customer's MC number must be set in Alvys before a load can be included in a batch.

## Sync Behavior

Credit check results sync automatically from Saint Johns Capital to Alvys. Invoice batch data flows from Alvys to Saint Johns Capital at submission. There is no automated nightly batch sync; load status updates depend on batch submission.

## Submit a Batch

* Navigate to **Accounting > Factoring Upload**. All loads must have a **Queued** status with invoicing method set to factoring.
* Select the correct subsidiary.

<Note>
  <img alt="Subsidiary selector on Factoring Upload page" />

  *Subsidiary selector on Factoring Upload page*
</Note>

* Select the invoices to include in the batch. Ensure the MC number is set for each customer.

<Note>
  <img alt="Load list with checkboxes on Factoring Upload page" />

  *Load list with checkboxes on Factoring Upload page*
</Note>

* Click **Submit Batch**. A pop-up appears.

<Note>
  <img alt="Submit Batch button on Factoring Upload page" />

  * Submit Batch button on Factoring Upload page\*
</Note>

* In the pop-up, select the **Funding Method**: Wire, ACH, Fuel Card, or Visa. Select the **Payment Date** using the calendar.

<Note>
  <img alt="Batch submission pop-up showing Funding Method selector and Payment Date calendar" />

  *Batch submission pop-up showing Funding Method selector and Payment Date calendar*
</Note>

* Confirm the submission. Wait until the process is complete. Do not close this page or navigate away; doing so may disrupt the submission.

## Broker Credit Checks

Saint Johns Capital performs broker credit checks to assess whether a broker is eligible for factoring. Credit check results appear as colored icons next to the customer/broker name:

* Green: Approved
* Red: Declined
* Grey: Unknown (no credit check has been performed yet)

### Automatic Credit Checks

Alvys automatically triggers a credit check in two situations:

* When a load is created: if the last credit check for that broker was performed more than 24 hours ago
* When a load reaches **Queued** status: if the last credit check was more than 24 hours ago

### Manually Trigger a Credit Check from a Customer/Broker Profile

* Navigate to the customer or broker profile.
* Add a factoring invoicing method to the subsidiary where the Saint Johns Capital integration was added, then save. This step is required before the refresh icon (↻) becomes visible.
* Click the refresh icon **(↻)** next to the customer or broker name to trigger a credit check. The credit check result icon updates next to the customer/broker name.

<Note>
  <img alt="Credit check status icons: green (Approved)" />

  *Credit check status icons: green (Approved)*

  <img alt="Credit check status icons: red (Declined)" />

  *Credit check status icons: red (Declined)*

  <img alt="Credit check status icons: grey (Unknown)" />

  * Credit check status icons: grey (Unknown)\*
</Note>

### Manually Trigger a Credit Check from a Load Details Page

* Open or create a load. Confirm the customer has a subsidiary with the factoring invoicing method assigned.
* On the load details page, click the refresh icon **(↻)** to trigger a credit check.

<Note>
  Load details page showing refresh icon (↻)

  <img alt="Notion Image" />
</Note>

### Submit a Load Based on Credit Check Status

1. Select or create a load with a customer assigned to the subsidiary using the factoring invoicing method.
2. Advance the load to **Released** status.
3. Click **Invoice Load** to generate the invoice.
4. Merge the required documents: Customer Rate Confirmation, Proof of Delivery (POD), and the invoice. The load moves to **Queued** status.
5. Navigate to **Accounting > Factoring Upload**. Select the load and submit the batch.

<Note>
  Factoring Upload page with the load selected for batch submission

  <img alt="Notion Image" />
</Note>

## Verify It's Working?

After submitting a batch, confirm that the selected loads have moved from **Queued** status to **Invoiced** status. Credit check results should appear as colored icons next to customer/broker names within a few seconds of triggering a check.

## Troubleshooting

### Batch submission fails?

1. Confirm the customer's MC number is set. Navigate to the customer/broker profile and verify the MC number field is populated. A load cannot be submitted without it.
2. Confirm the subsidiary has a valid Client ID configured in Management > Integrations.
3. Contact Alvys support if the batch continues to fail after confirming the above.

### Credit check icon does not appear?

1. Confirm the customer has a factoring invoicing method assigned to the subsidiary where the Saint Johns Capital integration is configured.
2. Confirm the integration is active in Management > Integrations.
3. Trigger the credit check manually using the refresh icon (↻). If the icon does not appear after confirming both steps above, contact Alvys support.

## Limits / Unsupported

Each subsidiary must have its own Client ID configured separately. A single Client ID cannot apply across multiple subsidiaries.

## FAQs

**Q: What credit check statuses does Saint Johns Capital return?**

**A:** Saint Johns Capital returns three statuses: green (Approved), red (Declined), and grey (Unknown). There is no additional status for this integration.

**Q: What is the Notice of Assignment and where does the text come from?**

**A:** The Notice of Assignment is a document that informs customers that their receivables have been assigned to a factoring company. Saint Johns Capital provides the text when you set up your account with them.

**Q: Can I submit a load even if the credit check status is grey or red?**

**A:** Yes. The credit check status is informational. You can submit a load regardless of the result. Contact Saint Johns Capital directly if you have questions about a specific broker's eligibility.


# Samsara Premium Integration: Setup Guide
Source: https://docs.alvys.com/en/help/integrations/samsara-premium-integration-setup-guide

This is a guide to help you set up the Alvys + Samsara Premium Integration. This integration enables automatic check-in/check-out at stops, bi-directional data sync between Alvys and Samsara, and driver document collection through the Samsara Driver app.

***

### What You Get

With Samsara Premium, your dispatchers and drivers benefit from:

* **Automatic stop check-in and check-out** using Samsara geofences (no manual entry required)
* **Bi-directional data sync** between Alvys and Samsara: dispatched trips in Alvys automatically appear as routes in the Samsara Driver app, and driver updates (BOL numbers, weights, pieces, documents) sync back to Alvys in real time
* **Document collection at stops**: drivers upload required documents (PODs, BOLs, etc.) through the Samsara app and they flow directly into Alvys
* **Real-time route updates**: any changes made by dispatch in Alvys (stop additions, reorders, appointment time changes) are instantly reflected on the driver's Samsara screen

***

### Prerequisites

Before enabling the Premium integration, you must have:

1. **An active Samsara account** with the Samsara Driver app in use by your fleet
2. **The standard Alvys + Samsara ELD integration already connected** (this is the base integration that syncs vehicle locations, HOS, and ELD data)
3. **Drivers linked between both systems**: every driver that will use the Premium integration must be linked to an existing, active driver in Samsara. If a driver ID is missing, the route will not sync. If an Alvys driver is linked to the wrong Samsara driver ID (for example, Alvys driver "Alice" carries Samsara driver "Bob's" ID), the route will show as assigned to the wrong driver in Samsara.
4. **Samsara Premium enabled**: Discuss with your dedicated Customer Success Manager, and they can assist in setting you up.

***

### Step 1: Generate a Samsara API Token

Generate the API token through the Alvys app in the Samsara App Marketplace. This is the recommended approach because the token is created with the exact permissions Alvys needs — you do not need to configure scopes manually.

1. Log in to your **Samsara Dashboard**
2. Open the **App Marketplace**
3. Find and **install the Alvys app**
4. **Generate the API token** from the Alvys app
5. Provide the token to your Alvys implementation contact, or enter it in the Samsara integration settings within Alvys.

***

### Step 2: Configure Geofences in Samsara (Optional)

Geofences are **not required** for the integration, but they improve the accuracy of automatic check-in and check-out. Where a geofence is not configured, Alvys falls back to a default radius of **300 meters** from the location pin.

If you want to fine-tune arrival and departure detection:

1. In the **Samsara Dashboard**, go to **Geofences**
2. Create a geofence for each shipper, consignee, yard, or terminal location your drivers visit
3. Make sure the geofence name or address matches what your dispatchers use in Alvys so the systems can correlate correctly

**Tip:** If you already have geofences configured in Samsara for other purposes (e.g., yard management or visibility), those same geofences will work for auto check-in/check-out. You do not need to recreate them.

***

### Step 3: Verify Driver Matching

For the integration to work correctly, drivers must be linked between the two systems. A trip must have a driver assigned to sync to Samsara. If the assigned driver is not linked a driver in Samsara, the route will not sync; if it points to the wrong Samsara driver, the route will appear assigned to that driver in Samsara.

Your Alvys implementation contact can help you verify that your drivers are properly linked.

***

### Step 4: Define Your Document Requirements

Document collection at stops is **self-serve and configurable** — you can set it up yourself, and your Alvys implementation or support team can guide you if needed. Before go-live, decide:

* **Which document types are required at each stop type** (e.g., pickup stops require a "Depart Pickup" confirmation and a BOL; delivery stops require a "Delivery" confirmation and POD upload)
* **Which fields are mandatory vs. optional** for your drivers to complete before they can close out a stop

The following fields can be captured through the Samsara Driver app and synced back to Alvys:

* Bill of Lading number, Seal number and other references
* Weight
* Commodity description
* Pieces count
* Trailer number
* Detention events
* Notes
* Document uploads (BOLs, PODs, photos)

***

### Step 5: Driver Training

Before go-live, make sure your drivers are prepared:

1. **Install the Samsara Driver app** on their phone or tablet (available on iOS and Android)
2. Drivers will see dispatched routes appear automatically in the Samsara app once a trip is dispatched and assigned to them in Alvys
3. Train drivers on:

* How to view route details and stop instructions
* How to upload documents at each stop
* How to fill out task fields (BOL, seal, weight, pieces, etc.)
* That arrival and departure will be tracked automatically via geofences (no need to manually check in/out at locations with a geofence configured)

**Important:** Document upload can be **required, optional, or not configured at all** — it depends on how you set up your tasks for your tenant's needs. If you make document upload a required task, drivers must complete it to close out a trip, so make sure your team understands which documents are expected at each stop type.

***

### How It Works Day-to-Day

Once everything is configured:

1. A dispatcher **dispatches a trip** in Alvys and assigns a driver
2. Alvys **automatically pushes the route** to Samsara, including all stops, appointment times, reference numbers, and special instructions
3. The driver **sees the route** in their Samsara Driver app with full stop details
4. As the driver arrives at and departs from geofenced locations, **check-in/check-out timestamps sync back to Alvys automatically**
5. The driver **uploads documents and fills out fields** (BOL, weight, pieces, etc.) through the Samsara app
6. All driver-submitted data and documents **sync back to Alvys in real time**
7. If dispatch **makes changes** to the trip in Alvys (adds/removes stops, changes appointment times, reassigns), those changes are **pushed to Samsara immediately**

**In-App Samsara Flow:**

<img alt="Screenshot" />

***

### FAQ

\*\*Do I need to pay Samsara anything extra for this integration?\*\*The Premium integration comes with an additional per load fee. Please contact your Customer Success Representative for details or book a call here!

\*\*Which fields can I configure for the Driver to fill out and submit?\*\*Load References, Stop References, Stop Commodity (fully configurable Units of Measure), Driver Notes, Trailer Number, Documents (BOL, POD, Lumper Receipts, etc.)

\*\*What if a driver does not have the Samsara Driver app?\*\*The driver must have the Samsara Driver app installed and be logged in for routes to appear and for data to sync. Without the app, the integration cannot function for that driver.

\*\*What happens if a geofence is not set up for a location?\*\*Geofences are optional. Where one is not set, Alvys uses a default radius of **300 meters** from the location pin to mark auto check-in/check-out.

\*\*Can I use this if I have split loads?\*\*Yes. Alvys handles splits automatically. Each leg of a split is pushed as a separate route to Samsara, and documents are tied to the load level so nothing is lost during splits or re-dispatching.

\*\*What if a driver ID does not match between Alvys and Samsara?\*\*If the driver ID is missing, the route will not sync. If an Alvys driver is linked to the wrong Samsara driver ID, the route will appear assigned to the wrong driver in Samsara. Contact your Alvys implementation team to resolve any driver ID mismatches before go-live.

***

### Need Help?

Contact your Alvys account representative or reach out to your implementation team to get started with activation and configuration.


# TAFS: Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/tafs-factoring-integration

Submit invoice batches from Alvys to TAFS through the factoring API, approve them in the TAFS portal, and receive daily purchase and payment status updates.

<Note>
  This integration connects Alvys to TAFS via an API to submit invoice batches for factoring and automatically sync purchase and payment statuses back to Alvys each day.
</Note>

## Overview

The TAFS integration (also referred to as the TAFS factoring integration or TAFS API integration) allows you to submit invoice batches directly from Alvys to TAFS for funding. Once a batch is submitted, you approve each invoice in the TAFS portal. Alvys then automatically syncs purchase and payment status updates from TAFS once daily, updating the status of all loads financed or settled through factoring. You can also trigger a manual sync at any time from the Factoring Report page.

Loads submitted for factoring must have a truck assigned and must have a Factoring ID populated on the customer profile before they can be sent.

## Prerequisites

Before configuring this integration, confirm the following:

* You hold an Admin, Partner Admin, or Support role to configure the integration in Management > Integrations.
* You hold the **"Billing"** permission to submit batches from the Factoring Upload page.
* Your subsidiaries are created in Alvys. The TAFS integration is configured per subsidiary.
* You have your TAFS login credentials available. Contact TAFS directly if you do not have credentials.
* The MC Number field is filled out on each customer profile you intend to factor.

## How to connect

### Open the TAFS integration settings

1. Navigate to Management and open the Integrations page.
2. Under the Factoring section, locate TAFS and click the pencil icon.

   <img alt="Screenshot showing the TAFS integration listed under Factoring in Alvys Integrations, with the pencil icon highlighted" />

   *Screenshot showing the TAFS integration listed under Factoring in Alvys Integrations, with the pencil icon highlighted*
3. You will be prompted to enter your TAFS login credentials and to select which subsidiary this integration will be enabled for.
4. Enter your credentials and confirm your subsidiary selection, then save.

### How to populate the Factoring ID

After connecting the TAFS integration, you must resync each customer profile to populate the Factoring ID. Without a Factoring ID, invoices cannot be submitted for that customer.

1. Open the customer's profile in Alvys.
2. Click **Resync**.

   <img alt="Screenshot showing the Resync button on a customer profile in Alvys" />

   *Screenshot showing the Resync button on a customer profile in Alvys*
3. Alvys will attempt to match the customer to a TAFS account and populate the Factoring ID automatically.
4. If the Factoring ID does not populate, confirm that the MC Number field is filled out on the customer profile and that the Customer Name matches the name on record in TAFS exactly. Correct either field if needed and click Resync again.

### How to submit a batch

1. Confirm that all loads you want to submit have a truck assigned and that their customer profiles have a Factoring ID populated.
2. Navigate to Accounting > Factoring Upload.
3. Select the loads you want to include in the batch.
4. Click **Submit Batch**.
5. After the batch is submitted, log in to the TAFS portal and approve each incoming invoice individually. TAFS requires manual approval in its portal before invoices are funded.

### How to sync manually

Alvys performs an automatic daily sync of purchase and payment statuses from TAFS. To trigger a sync immediately without waiting for the daily run:

1. Navigate to Reports > Factoring Report.
2. Click the sync button to start a manual sync.

   <img alt="Screenshot showing the Factoring Report page in Alvys with the sync button" />

   *Screenshot showing the Factoring Report page in Alvys with the sync button*

## What syncs

Alvys matches each load to the correct TAFS account using the Factoring ID on the customer profile. The Factoring ID is populated by resyncing the customer profile after the integration is connected. If Alvys cannot locate the Factoring ID on the first attempt, it falls back to matching on the MC Number field and the Customer Name entered on the customer profile. Both fields must be accurate and must match the values registered in TAFS.

Each load submitted for factoring must also have a truck assigned. Loads without a truck assignment cannot be included in a batch submission.

Alvys automatically syncs purchase and payment status updates from TAFS once each day. This sync updates the status of all loads that have been financed through factoring or settled by the customer. You can also trigger a manual sync from the Factoring Report page at any time.

After connecting and resyncing customer profiles, the Factoring ID field should be populated on each customer profile. After submitting a batch, loads included in the batch should move to **Invoiced** status once the batch is processed. After a daily sync or manual sync, loads financed by TAFS or settled by the customer should reflect updated statuses.

### Limits and unsupported

* Each load submitted for factoring must have a truck assigned. Loads without a truck cannot be included in a batch.
* Invoices cannot be submitted for a customer until the Factoring ID is populated on that customer's profile.
* Purchase and payment report CSV uploads are not available for the TAFS integration. Status updates are handled automatically by the daily sync or by triggering a manual sync.
* The TAFS integration must be configured separately for each subsidiary.

## Troubleshooting

### Factoring ID does not populate after resyncing

1. Confirm that the MC Number field is filled out correctly on the customer profile. The MC Number must match the value on record in TAFS.
2. Confirm that the Customer Name on the Alvys customer profile matches the name registered with TAFS exactly. Correct the name if needed and click Resync again.
3. Contact Alvys support if the Factoring ID still does not populate after verifying both the MC Number and Customer Name.

### Loads cannot be submitted in a batch

1. Confirm that each load in the batch has a truck assigned. TAFS requires a truck on all loads submitted for factoring. Open each load and assign a truck if one is missing.
2. Confirm that the customer profile for each load has a Factoring ID populated. If not, resync the customer profile as described in How to populate the Factoring ID above.
3. Contact Alvys support if loads still cannot be submitted after verifying truck assignment and Factoring ID on each load.

### Statuses are not updating after a sync

1. Confirm that the automatic daily sync has had time to run. The sync runs once each day; wait until the following day if a sync has already completed for today.
2. Navigate to Reports > Factoring Report and trigger a manual sync to update statuses immediately.
3. Contact Alvys support if statuses remain incorrect after a manual sync.

## FAQs

**Q: Why do I need to resync customer profiles after connecting the integration?**

**A:** The Resync step populates the Factoring ID on each customer profile by matching the customer to a TAFS account. Without the Factoring ID, Alvys cannot route invoices to the correct account in TAFS and the submission will fail.

**Q: What do I do after submitting a batch in Alvys?**

**A:** After submitting a batch, log in to the TAFS portal and approve each incoming invoice individually. TAFS requires manual approval in its portal before invoices are funded.

**Q: Can I update load statuses without waiting for the daily sync?**

**A:** Yes. Navigate to Reports > Factoring Report and click the sync button to trigger a manual status sync at any time.

**Q: Why is a load not eligible for batch submission?**

**A:** The two most common reasons are: the load does not have a truck assigned, or the customer profile does not have a Factoring ID populated. Assign a truck to the load and resync the customer profile to resolve either issue.


# TCS Fuel Integration
Source: https://docs.alvys.com/en/help/integrations/tcs-fuel-integration

Import TCS (Transportation Clearinghouse Solutions) fuel card transactions into Alvys via manual CSV upload and apply deductions to driver settlements.

<Note>
  The TCS fuel integration lets you import fuel card transaction data from Transportation Clearinghouse Solutions into Alvys via manual CSV upload: use it to track fuel expenses and apply deductions to driver settlements.
</Note>

## Overview

The TCS fuel integration (Transportation Clearinghouse Solutions, TCS fuel card import, manual CSV upload) connects TCS fuel card data with Alvys. This is a manual import process: you download a Transactions Download CSV from your TCS system and upload it into Alvys. Alvys then matches each transaction to the correct driver using the last 4 digits of the fuel card number stored on their profile.

Use this integration to track fuel expenses, apply fuel deductions to driver pay, and maintain accurate fuel records in your Fuel Report. The integration is one-way: data flows from TCS into Alvys only.

## Prerequisites

Before setting up this integration, confirm the following:

* You have access in Alvys to manage Integrations.
* You have login credentials for your TCS system.
* Your subsidiaries are already configured in Alvys.
* If you need help locating the Transactions Download report in TCS, contact your TCS Sales Representative.

## How to connect

1. Click your username in the bottom left corner of Alvys, then select **Management (**[https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)**)**.
2. Go to the **Integrations** section.
3. Scroll to the **Fuel Cards** drop-down and select the “**Inactive”** button next to **TCS**.

   <img alt="TCS integration card with “Inactive” button highlighted." />

   *TCS integration card with “**Inactive**” button highlighted.*
4. Choose the subsidiary that should use **TCS**.
5. Click the blue “**Save”** button.

<Info>
  💡 No API credentials are required for the TCS integration. Enabling the integration registers TCS as an available upload type in the Fuel Report.
</Info>

**For Alvys to attribute transactions to the correct driver, each driver must have the last 4 digits of their TCS fuel card number saved on their profile:**

1. From the Alvys toolbar, go to **Assets** and select **Drivers**.
2. Find and double-click a driver to open their profile.
3. In the first section, click the plus sign next to **Fuel Card Numbers**.

   <img alt="This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted." />

   *This image shows the Fuel Card Numbers section of a driver profile with the plus sign highlighted.*
4. Enter only the **last 4 digits** of the TCS fuel card number for this driver.

   <img alt="This image shows the fuel card number entry field with a 4-digit number entered." />

   *This image shows the fuel card number entry field with a 4-digit number entered.*
5. Select **TCS** in the Provider dropdown.
6. Set the deduct fuel and discounted fuel checkboxes if applicable.
7. Click **Save**.

Repeat the fuel card steps for each driver who has a TCS fuel card.

### To download fuel transactions from TCS:

1. Log in to your TCS system.
2. Navigate to **Reports**.
3. Scroll down to **Transactions Download**.
4. Select your time period on the right.
5. Download the file to your device as a CSV. If you cannot locate the Transactions Download report, contact your TCS Sales Representative for assistance.

### To upload the file to Alvys (confirm each driver's last 4 fuel card digits are saved first):

* From the Alvys toolbar, go to \*\*Assets \*\*and select **Fuel Report**.

<Note>
  <img alt="This image shows the Fuel Report page with the Transaction File Upload button visible." />

  *This image shows the Fuel Report page with the Transaction File Upload button visible.*
</Note>

* Click the vertical ellipsis icon **(⋮)** next to the “**Add** \*\*Transaction” \*\*button.

<Note>
  <img alt="Image showing ellipsis icon next to “Add Transaction” button" />

  *Image showing ellipsis icon next to “Add Transaction” button*
</Note>

* Select the “**Import Report**” option.

<Note>
  <img alt="Image showing Import Report option" />

  *Image showing Import Report option*
</Note>

* In the pop-up window, select **EFSCSV** from the **Integration Type** drop-down menu.

<Note>
  <img alt="Image showing ”Upload Fuel Report” form with Integration type and Add report input fields." />

  *Image showing ”Upload Fuel Report” form with Integration type and Add report input fields.*
</Note>

* Upload the CSV file you downloaded from the TCS portal.
* Click the “Save” button
* Once the upload completes, use the **Transaction Date** range filter in the Fuel Report to review imported transactions.

## What syncs

The TCS integration is a manual, one-way sync from TCS into Alvys. After uploading a TCS CSV, Alvys maps transaction data as follows:

* The last 4 digits of the fuel card number on the CSV are matched against the last 4 digits stored in each driver's profile. Transactions are attributed to the driver whose card number matches.
* Transaction date, amount, and gallons are imported into the Fuel Report.
* If the card number on a transaction does not match any driver profile, the transaction will not be attributed to a driver. Add or correct the card number on the driver profile, then re-upload the file.
* Alvys detects duplicate transactions automatically and will not import duplicates. Re-uploading the same file is safe.
* There is no automatic or scheduled sync for this integration.

Only the last 4 digits are used because TCS fuel card data in transaction reports uses only the last 4 digits as the identifier.

<Warning>
  ⚠️ This integration does not support automatic or scheduled imports.

  Entering a full card number will prevent correct matching.

  Alvys does not write data back to TCS.
</Warning>

## Troubleshooting

### Driver fuel transactions not appearing after upload

1. Open the driver profile in **Assets > Drivers** and confirm a TCS fuel card number is saved under Fuel Card Numbers. Only the last 4 digits should be entered.
2. Verify the 4-digit card number matches the last 4 digits on the TCS CSV export. Alvys matches on the exact digits stored in the profile.
3. Re-upload the CSV after correcting the card number. Alvys will not re-import a transaction it already has by ID, so if the original upload failed to match, correcting the card number and re-uploading will resolve the match going forward for future transactions.
4. If transactions are still missing, contact Alvys support.

### Upload fails or returns an error

1. Confirm you selected **TCS** (not another provider) in the Integration Type dropdown before uploading.
2. Confirm the file is the Transactions Download CSV from TCS Reports. Modified or reformatted files may not parse correctly.
3. Contact Alvys support if the error persists after verifying the file and integration type.

## FAQs

**Q: Why do I only enter the last 4 digits of the fuel card number?**

**A:** TCS fuel card data in transaction reports uses only the last 4 digits as the identifier. Entering the full card number will prevent correct matching.

**Q: Is the TCS integration automatic or manual?**

**A:** The TCS integration is manual. You download CSV files from TCS Reports and upload them to Alvys periodically.

**Q: What happens if I upload the same transactions twice?**

**A:** Alvys automatically detects duplicate transactions and will not import them again. Re-uploading the same file is safe.

**Q: How often should I upload fuel transaction reports?**

**A:** This depends on your reporting and settlement needs. Many teams upload weekly or monthly to keep fuel data current.

**Q: What if a driver's transactions are not showing up after upload?**

**A:** Confirm the driver has the correct last 4 digits of their TCS fuel card number saved on their profile under Assets > Drivers. If the number is missing or incorrect, add or correct it. Future uploads will then match correctly.


# Triumph Business Capital: Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/triumph-business-capital-factoring-integration

Send invoice batches from Alvys to Triumph Business Capital (TBC) via FTP, then upload Triumph portal purchase and payment reports back for load reconciliation.

## Overview

Send invoice batches from Alvys to Triumph Business Capital via FTP, then upload purchase and payment reports from the Triumph portal back to Alvys for reconciliation. Also referred to as Triumph factoring, Triumph Business Capital factoring, or TBC factoring.

The Triumph Business Capital integration connects Alvys to Triumph's FTP server so you can submit invoice batches for factoring directly from Alvys. After Triumph funds the invoices, you download a purchase report from the Triumph portal and upload it to Alvys. When Triumph processes payment, you download a payment report from [mytriumph.com](http://mytriumph.com/) and upload it to Alvys. These uploads update your factoring records in Alvys for reconciliation.

## Prerequisites

Before configuring the integration, confirm the following:

* Your company has an active factoring agreement with Triumph Business Capital.
* You have at least one subsidiary set up in Alvys. The integration must be configured per subsidiary.
* You have an Admin or Partner Admin role in Alvys to configure the integration in Management > Integrations.
* You have received or will request FTP credentials from Triumph. A separate set of credentials is required for each subsidiary.

## How to connect

### Add your Notice of Assignment

1. Navigate to Company Profile.
2. Locate the **Document Configuration** section of the **General Info** tab. Click the **+** button. The **Manage Important Info** window opens.
3. Select **Notice of Assignment** from the dropdown.
4. Copy and paste the following text exactly as it appears into the Notice of Assignment field:

<Note>
  THIS INVOICE HAS BEEN ASSIGNED TO AND MUST BE PAID DIRECTLY TO, ADVANCE BUSINESS CAPITAL LLC, d/b/a TRIUMPH BUSINESS CAPITAL, P.O. BOX 610028 Dallas, TX 75261-0028, For paperwork requests please email [requests@tbcap.com](mailto:requests@tbcap.com), CLAIMS OR OFFSETS SHOULD BE DIRECTED TO (866) 414-9600, JURISDICTION FOR ANY LEGAL DISPUTES WILL BE IN DALLAS COUNTY, TEXAS
</Note>

5. Click **Save**.

### Request credentials and configure each subsidiary

1. Contact Triumph Business Capital to request FTP credentials. A separate set of credentials is required for each subsidiary you plan to factor through this integration.
2. After receiving credentials, click the **Profile** button in the upper right corner of Alvys and select **Management**.
3. On the Management page, select the subsidiary you are configuring from the left panel. Scroll to the **Integrations** section and click the blue **Integrate** button. The **Add Integration** pop-up opens.
4. Select **Triumph** from the dropdown.
5. Enter the FTP credentials Triumph provided for this subsidiary, then click **Save**.

<img alt="Credential entry form for Triumph FTP integration in the Add Integration pop-up" />

*Credential entry form for Triumph FTP integration in the Add Integration pop-up*

6. Repeat steps 3 through 5 for each additional subsidiary.
7. After configuring all subsidiaries, submit a test batch. Contact your Triumph sales representative to confirm the submission was received successfully.

### How to submit a batch

Users with the **"Billing"** permission can submit invoice batches to Triumph from the Factoring Upload page.

1. Navigate to **Accounting > Factoring Upload**.
2. Select the subsidiary for this batch.

<img alt="Subsidiary selection screen on the Factoring Upload page" />

*Subsidiary selection screen on the Factoring Upload page*

3. Select the invoices you want to include in the batch. Only invoices with a status of **Invoiced** are eligible for submission.

<img alt="Invoice selection on the Factoring Upload page" />

*Invoice selection on the Factoring Upload page*

4. Click **Submit Batch**.

<img alt="Submit Batch button on the Factoring Upload page" />

*Submit Batch button on the Factoring Upload page*

5. Wait for the submission to complete. Do not navigate away from the page until the submission finishes.

### How to upload a purchase report

After Triumph funds your invoices, a purchase report becomes available in the Triumph portal. Download the report and upload it to Alvys for reconciliation.

1. Log in to the Triumph Factoring portal and go to the **Dashboard**.

<img alt="Triumph Factoring portal Dashboard showing the Recent Fundings card" />

*Triumph Factoring portal Dashboard showing the Recent Fundings card*

2. In the **Recent Fundings** card, click the report you want to download.

<img alt="Recent Fundings card in the Triumph Factoring portal with a selectable report" />

*Recent Fundings card in the Triumph Factoring portal with a selectable report*

3. Click **Export Results**, then select **Export to Excel**. Save the file to your device.

<img alt="Export Results menu with Export to Excel option in the Triumph Factoring portal" />

*Export Results menu with Export to Excel option in the Triumph Factoring portal*

4. In Alvys, navigate to **Reports > Factoring**. Click **Upload Purchase Report** in the lower right.

<img alt="Upload Purchase Report button on the Factoring Report page in Alvys" />

*Upload Purchase Report button on the Factoring Report page in Alvys*

5. Drag and drop the exported file onto the upload area, or click to browse and select the file from your device.

<img alt="File drag-and-drop upload area on the Factoring Report page" />

*File drag-and-drop upload area on the Factoring Report page*

6. Click **Upload**.

<img alt="Upload button on the Factoring Report page" />

*Upload button on the Factoring Report page*

7. Do not close the page until processing is complete. Processing may take several seconds to a few minutes depending on the size of the file.

### How to upload a payment report

After Triumph processes payment, a payment report becomes available at [mytriumph.com](http://mytriumph.com/). Download the report and upload it to Alvys for reconciliation.

1. Log in to [mytriumph.com](http://mytriumph.com/). Navigate to **Reports**, then select **Payments Received**.

<img alt="Reports > Payments Received in the Triumph portal menu" />

*Reports > Payments Received in the Triumph portal menu*

2. Adjust the timeframe as needed. Click **Export from Detail View** and select Excel format. Save the file to your device.

<img alt="Exporting the Payments Received report to Excel" />

*Exporting the Payments Received report to Excel*

3. In Alvys, navigate to **Reports > Factoring**. Click **Upload Payment Report**.

<img alt="Upload Payment Report button on the Factoring Report page in Alvys" />

*Upload Payment Report button on the Factoring Report page in Alvys*

4. Drag and drop the exported file onto the upload area, or click to browse and select the file from your device.

<img alt="File drag-and-drop upload area for the payment report" />

*File drag-and-drop upload area for the payment report*

5. Click **Upload**.

<img alt="Upload button for the payment report on the Factoring Report page" />

*Upload button for the payment report on the Factoring Report page*

6. Do not close the page until processing is complete. Processing may take several seconds to a few minutes depending on the size of the file.

## What syncs

When a batch is submitted, Alvys sends the following invoice data to Triumph via FTP: invoice number, invoice amount, debtor name, load reference number, and subsidiary identifier. Triumph uses these fields to create and track the purchase report. No additional field mapping configuration is required in Alvys.

This is a one-way integration. Alvys sends invoice batches outbound to Triumph's FTP server. Triumph does not send data back to Alvys automatically. Purchase reports and payment reports must be downloaded from the Triumph portal and uploaded to Alvys manually.

After submitting your first test batch and uploading reports, confirm the following:

* Contact your Triumph sales representative to verify they received and accepted the FTP batch submission.
* After uploading a purchase report, verify that the corresponding invoices in Alvys reflect the correct factored amounts.
* After uploading a payment report, verify that payment records in Alvys match the amounts in the report.

If invoices do not appear on the Factoring Upload page, confirm they have a status of **Invoiced** in Alvys and that the correct subsidiary is selected.

### Limits and unsupported

* A separate FTP integration must be configured for each subsidiary. One set of FTP credentials cannot cover multiple subsidiaries.
* The integration uses FTP only. No alternative file transfer methods are supported.
* Report uploads (purchase and payment) are manual. There is no automatic sync of report data from the Triumph portal to Alvys.
* Only invoices with a status of **Invoiced** are eligible for batch submission.

## Troubleshooting

### Load not showing on Factoring Upload

1. Confirm the load status is **Queued**.
2. Confirm the load's invoicing settings use **Factoring Upload** as the delivery method.
3. Confirm the invoice and required documents were merged, either automatically or manually.
4. Confirm the load was not already included in another factoring batch.

### "Unable to locate file"

This error usually means the invoice file is no longer available. To resolve it:

1. Review the load number shown in the error message.
2. Open that load in Alvys.
3. Regenerate the invoice.
4. Try submitting the factoring batch again.

### "SFTP Authorization Error — Permission Denied (Password)"

This error usually means the credentials used to set up the integration are incorrect. To resolve it:

1. Review the credentials entered in the factoring integration setup.
2. Confirm the password is correct.
3. If the integration uses FTP/SFTP credentials from the factoring provider, make sure you are using those credentials — not your personal Triumph portal login.

### "Duplicate batch or invoice numbers"

This can happen if the page is refreshed, closed, or reopened while a batch is being submitted.

<Warning>
  This issue cannot be fixed manually. Contact Alvys Support so they can review and adjust the batch if needed.
</Warning>

### Batch submission does not appear in Triumph portal

1. Confirm the FTP credentials entered in Management > Integrations match the credentials Triumph provided for this subsidiary exactly, including capitalization and special characters.
2. Check that you submitted a test batch after initial setup and that Triumph confirmed receipt. If Triumph did not confirm, resubmit and contact your Triumph sales representative.
3. If credentials are correct and Triumph cannot locate the submission, contact Alvys Support.

### Purchase or payment report upload returns an error

1. Confirm the file was exported from the Triumph portal in Excel (.xlsx) format. Files in other formats are not accepted.
2. Confirm the file is not open in another application before uploading.
3. Review the error message. It usually identifies what is missing or incorrect in the file.
4. Make sure the file includes the **load number** as the unique identifier. Without the load number, Alvys cannot match the report to the correct load or update the load as financed or completed.
5. If the upload continues to fail, contact Alvys Support.

### Slow large batch submissions

Large files or batches with a high volume of loads may take longer to upload.

<Tip>
  If the upload is taking too long, try submitting a smaller batch. The Alvys team is also monitoring and improving performance for large batch submissions.
</Tip>

### Invoices do not appear on the Factoring Upload page

1. Confirm the invoices have a status of **Invoiced** in Alvys. Invoices in other statuses are not eligible for batch submission.
2. Confirm the correct subsidiary is selected on the Factoring Upload page. Each subsidiary shows only its own eligible invoices.
3. If invoices are **Invoiced** and the correct subsidiary is selected but invoices still do not appear, contact Alvys Support.

## FAQs

**Q: Why do I need separate FTP credentials for each subsidiary?**

**A:** Triumph Business Capital requires a distinct set of FTP credentials per subsidiary. A single set of credentials cannot cover multiple subsidiaries; each must be configured separately in Management > Integrations.

**Q: What do I do after submitting a test batch?**

**A:** After submitting the test batch, contact your Triumph sales representative to confirm they received and accepted it. Triumph will verify the submission on their end before you proceed with live invoice batches.

**Q: What is the exact Notice of Assignment text required for Triumph Business Capital?**

**A:** The required text is: THIS INVOICE HAS BEEN ASSIGNED TO AND MUST BE PAID DIRECTLY TO, ADVANCE BUSINESS CAPITAL LLC, d/b/a TRIUMPH BUSINESS CAPITAL, P.O. BOX 610028 Dallas, TX 75261-0028, For paperwork requests please email [requests@tbcap.com](mailto:requests@tbcap.com), CLAIMS OR OFFSETS SHOULD BE DIRECTED TO (866) 414-9600, JURISDICTION FOR ANY LEGAL DISPUTES WILL BE IN DALLAS COUNTY, TEXAS.

**Q: How long does it take for a report upload to process?**

**A:** Processing time ranges from a few seconds to a few minutes depending on the size of the file. Do not close the Factoring Report page until processing is complete.


# Trucker Tools Inbound Integration
Source: https://docs.alvys.com/en/help/integrations/trucker-tools-inbound-integration

Track brokerage freight in real time by connecting Trucker Tools to Alvys; driver cell phone location and status updates sync into loads automatically.

<Note>
  Connect Trucker Tools to Alvys to track freight in real time using the driver's cell phone; location and status updates flow from Trucker Tools into Alvys automatically.
</Note>

## Overview

Track your freight in real time by connecting Alvys with **Trucker Tools**. This integration lets brokers monitor every shipment using the driver's cell phone and sends location updates directly into your Alvys account.

**Synonyms**: Trucker Tools tracking, TT visibility, inbound tracking, driver cell phone tracking, real-time freight visibility.

The Trucker Tools integration connects your Alvys account with the Trucker Tools carrier network. When you start tracking on a load, Alvys sends the load details to Trucker Tools, which contacts the assigned driver and begins collecting location and status data. Those updates flow back into Alvys automatically, giving you real-time visibility from pickup to delivery.

This integration tracks freight through the driver's cell phone number. Tracking through electronic logging devices is not supported at this time.

This is a two-way integration. Location and status data flows from Trucker Tools to Alvys, and load details flow from Alvys to Trucker Tools to initiate tracking.

## Prerequisites

Before connecting, make sure you have:

* An active Trucker Tools account with your credentials ready
* Admin or Partner Admin access in Alvys
* A carrier assigned to any load you want to track before you can start tracking

## How to connect?

**Open the integration settings.**

* Select your user profile in the bottom left corner of Alvys, then choose **EDI & Visibility** from the menu. You will see a list of available integrations divided into EDI Tenders and Visibility sections.
* Find **Trucker Tools** under the Visibility section. Select which subsidiary you want to enable this feature for.
* Enter your Trucker Tools credentials. Alvys will verify your credentials and activate the integration once confirmed.

<Note>
  <img alt="Trucker Tools credentials entry screen in the EDI & Visibility settings" />

  * Trucker Tools credentials entry screen in the EDI & Visibility settings\*
</Note>

**Provide the connection addresses to Trucker Tools.**

In the Trucker Tools integration window, copy the two connection addresses shown and send them to your Trucker Tools contact at [david@truckertools.com](mailto:david@truckertools.com) and [integrations@truckertools.com](mailto:integrations@truckertools.com):

* **Location Updates:** `https://api.alvys.com/api/truckerTools/locationUpdates/XXXXX`
* **Order Status:** `https://api.alvys.com/api/truckerTools/statusUpdates/XXXXX`

Replace XXXXX with your Alvys Tenant ID, which is shown in the integration window. Trucker Tools will install these addresses on their end and confirm when complete. This step is required for Trucker Tools to send tracking data back to your Alvys account.

## What syncs?

Once you start tracking a load, Alvys sends the following load details to Trucker Tools: the assigned driver's phone number, stop addresses, stop appointment times, and stop company names. Trucker Tools uses this information to initiate contact with the driver and begin collecting location updates.

Trucker Tools returns location coordinates and order status events to Alvys via the connection addresses set up in the connection steps above.

### Start tracking a load

Open the load details page and go to the **Load Tracking** tab. The load must have a carrier assigned before you can begin tracking.

Review the pre-filled tracking settings that appear based on your previous preferences and the load details. Adjust them as needed, then confirm to start tracking.

<Note>
  <img alt="Load Tracking tab showing the tracking initiation form" />

  *Load Tracking tab showing the tracking initiation form*
</Note>

<Note>
  <img alt="Tracking settings panel with pre-filled options" />

  *Tracking settings panel with pre-filled options*
</Note>

<Note>
  <img alt="Tracking confirmation screen" />

  *Tracking confirmation screen*
</Note>

### Edit or disable tracking

To update or turn off an active tracking request, go to the **Load Tracking** tab on the load details page. Select the option to edit or disable the Trucker Tools tracking request.

<Note>
  <img alt="Edit and disable options in the Load Tracking tab" />

  *Edit and disable options in the Load Tracking tab*
</Note>

### Automatic updates

Your tracking request updates automatically in Trucker Tools when any of the following change on the load: stop company name, stop coordinates, stop address, appointment time, or the driver's phone number. Adding a new stop or splitting a trip also triggers an update.

The tracking request disables automatically if you remove the assigned carrier from the load. This keeps your tracking information accurate and in sync with the current state of the load.

### Verify it is working

Once Trucker Tools confirms the connection addresses are installed, start tracking on a test load and check that the **Trip Location Tracking** section in Alvys shows driver location data flowing in from Trucker Tools. Location and status data should refresh as the driver moves.

<Note>
  <img alt="Trip Location Tracking section showing real-time driver location data" />

  *Trip Location Tracking section showing real-time driver location data*
</Note>

## Troubleshooting

### Tracking does not start after confirming the request

1. Confirm a carrier is assigned to the load. A tracking request cannot start without an assigned carrier.
2. Confirm the assigned driver has a valid cell phone number on the load. Trucker Tools tracks through the driver's cell phone only.
3. If a carrier and driver phone number are present but tracking still does not start, contact Alvys support.

### Location data is not flowing into Alvys

1. Confirm Trucker Tools has installed both connection addresses (Location Updates and Order Status) on their end. Tracking data cannot reach Alvys until this step is complete.
2. Confirm the Tenant ID in each connection address matches your Alvys Tenant ID shown in the integration window.
3. If the connection addresses are installed correctly and data is still not appearing, contact Alvys support.

## Limits and unsupported

* Tracking works through the driver's cell phone number only. Electronic logging device tracking is not supported.
* The connection addresses must be installed by Trucker Tools. You cannot complete this step directly in Alvys.
* A carrier must be assigned to the load before you can start a tracking request.

## FAQs

**Q: What happens to my tracking request if I remove the carrier from the load?**

**A:** The tracking request disables automatically in Trucker Tools when you remove the assigned carrier. You will need to restart tracking after assigning a new carrier.

**Q: Which load changes automatically update my Trucker Tools tracking request?**

**A:** Changes to the stop company name, stop coordinates, stop address, appointment time, or the driver's phone number are sent automatically. Adding a new stop or splitting a trip also triggers an update.

**Q: Can I use this integration to send tracking updates directly to my customers?**

**A:** Yes. The Trucker Tools Outbound Tracking Updates feature lets you send automated updates to your customers from their profile in Alvys. See the article linked below.

## Go Deeper

[How to configure Trucker Tools Outbound Tracking Updates](/en/help/integrations/how-to-configure-trucker-tools-outbound-tracking-updates)


# TruFunding: Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/trufunding-factoring-integration

Set up the TruFunding API factoring integration in Alvys to send invoice batches directly to TruFunding from the Factoring Upload page.

<Note>
  This article explains how to configure the TruFunding API integration in Alvys and submit invoice batches directly to TruFunding from the Factoring Upload page.
</Note>

## What This Integration Does

The TruFunding integration (also called TruFunding factoring or invoice factoring) sends invoice batches from Alvys to TruFunding through an API connection when you submit a batch from the Factoring Upload page. After setup, batch submission works directly from Accounting > Factoring Upload without any manual file transfer or CSV upload required. Synonyms: invoice factoring, accounts receivable financing.

**Provider:** TruFunding · **Integration type:** One-way · **Sync direction:** Alvys to TruFunding (outbound API batch submission).

## Prerequisites

Before configuring this integration, confirm the following:

* You hold an Admin, Partner Admin, or Support role to add the Notice of Assignment and configure integration credentials.
* You hold the **"Billing"** permission to submit batches from the Factoring Upload page.
* Your subsidiaries are created in Alvys. The TruFunding username must be configured for each subsidiary separately.
* You have received your TruFunding username from TruFunding. Contact TruFunding directly if you have not received your credentials.
* You have received the Notice of Assignment text from TruFunding to add to your invoices.

## Connect / Authenticate

**Add your Notice of Assignment.** The Notice of Assignment (NOA) declares to your customers that TruFunding has the right to collect payment on the invoices you factor. It must appear on every invoice submitted through this integration.

* Click the Profile button in the upper right corner and select Management to open your Company Profile.
* In the "**Document Configuration**" section, click the plus sign (+) button. The Manage Important Info window will appear.

<img alt="Image showing Document Configuration on Company/Tenant Profile" />

*Image showing Document Configuration on Company/Tenant Profile*

* In the drop-down menu, select Notice of Assignment.
* Paste the NOA text provided by TruFunding into the text box.
* Click Save.

<img alt="Image showing Document Configuration Form" />

*Image showing Document Configuration Form*

**Configure your TruFunding credentials.**

* Navigate to Management and open the Integrations page ([https://app.alvys.com/#/manage/integrations](https://app.alvys.com/#/manage/integrations)).
* Under the Factoring section, locate TruFunding.
* Select the subsidiary you want to configure.

<img alt="Image showing inactive Tru Funding Integration" />

*Image showing inactive Tru Funding Integration*

* Click the "Inactive" button next to TruFunding.
* Enter your TruFunding username in the field provided.
* Click Save.
* Repeat this process for each subsidiary that will submit batches to TruFunding.

## Field & Data Mapping

This integration uses an API connection. Invoice data is submitted to TruFunding directly through the API when you click Submit Batch in Alvys. No CSV file download or upload is required.

## Sync Behavior

This integration is one-way and outbound. Alvys sends invoice batch data to TruFunding via API when you submit a batch from the Factoring Upload page. Purchase and payment report uploads are not available for this integration.

## How to Submit a Batch

1. Ensure invoices have been generated for the loads you want to factor. Loads must be in **Queued** status to appear in the Factoring Upload queue.
2. Navigate to Accounting > Factoring Upload.
3. Select the subsidiary you are submitting for.
4. Select all loads in **Queued** status that you want to include in the batch.
5. Click Submit Batch.
6. Loads submitted in the batch will update to **Invoiced** status.

<Warning>
  Stay on the Factoring Upload page until the submission completes. Navigating away may interrupt the process.
</Warning>

## Verify It's Working

After submitting a batch, loads included in the batch should move to **Invoiced** status. If a load remains in **Queued** status after submission, confirm that the TruFunding username is correctly configured in Management > Integrations for the relevant subsidiary, then retry.

## Troubleshooting

### Load not showing on Factoring Upload

1. Confirm the load status is **Queued**.
2. Confirm the load's invoicing settings use **Factoring Upload** as the delivery method.
3. Confirm the invoice and required documents were merged, either automatically or manually.
4. Confirm the load was not already included in another factoring batch.

### Batch does not submit or loads remain in Queued status

1. Confirm that the TruFunding username is entered correctly in Management > Integrations for the subsidiary you are submitting for.
2. Confirm you stayed on the Factoring Upload page until the submission completed. Navigating away during submission may interrupt the process. Retry the submission if needed.
3. Contact Alvys support if the batch continues to fail after verifying your credentials.

### "Unable to locate file"

This error usually means the invoice file is no longer available. To resolve it:

1. Review the load number shown in the error message.
2. Open that load in Alvys.
3. Regenerate the invoice.
4. Try submitting the factoring batch again.

   <img alt="Unable to locate file error message during a factoring batch upload" />

   *Unable to locate file error message during a factoring batch upload*

### "SFTP Authorization Error — Permission Denied (Password)"

This error usually means the credentials used to set up the integration are incorrect. To resolve it:

1. Review the credentials entered in the factoring integration setup.
2. Confirm the password is correct.
3. If the integration uses FTP/SFTP credentials from the factoring provider, make sure the customer is using those credentials — not their personal portal login.

   <img alt="SFTP authorization error, permission denied, during a factoring upload" />

   *SFTP authorization error, permission denied, during a factoring upload*

### Loads do not appear in the Factoring Upload queue

1. Confirm the load status is **Queued**. Only loads in **Queued** status appear in the Factoring Upload queue. Generate invoices for any loads that have not yet had invoices created.
2. Confirm the load's invoicing method is set to Factoring Company. Check the customer's Invoicing tab in their profile, or check Invoicing Settings in Company Profile for the subsidiary.
3. Confirm you have selected the correct subsidiary on the Factoring Upload page.
4. Contact Alvys support if none of the above reasons apply.

## Limits / Unsupported

* Purchase and payment report uploads are not available for the TruFunding integration. Load status reconciliation after funding and payment is not handled through Alvys for this provider.
* Each subsidiary requires its own TruFunding username configuration. A single username cannot be shared across multiple subsidiaries.
* Only loads in **Queued** status can be included in a batch submission.

## FAQs

**Q: Do I need to upload a purchase or payment report after TruFunding funds my invoices?**

**A:** No. Purchase and payment report uploads are not supported for the TruFunding integration. Batch submission sends the invoice data to TruFunding, and load status reconciliation after funding is handled outside of Alvys for this provider.

**Q: Where do I find my TruFunding username?**

**A:** Your TruFunding username is provided by TruFunding when you set up your account. Contact TruFunding directly if you have not received it.


# Twilio (New) Integration
Source: https://docs.alvys.com/en/help/integrations/twilio-new-integration

Connect the new Twilio integration to Alvys to power Driver Chat SMS, meet A2P 10DLC compliance, and route messages from the correct subsidiary phone number.

<Note>
  Connect Twilio to Alvys to enable Driver Chat, which allows dispatchers to send and receive SMS messages with drivers directly inside Alvys. All customers must upgrade to the Twilio (New) integration to meet A2P 10DLC compliance requirements and continue using Driver Chat.
</Note>

## Overview

The Twilio (New) integration (also referred to as Twilio V2 or the upgraded Twilio integration) powers Driver Chat in Alvys. Once connected, dispatchers can send and receive text messages with drivers from within the Alvys platform. Twilio routes those messages as SMS to drivers' phones.

This version of the integration adds support for a subsidiary selector, which ensures messages are sent from the correct legal entity when you manage multiple brands or subsidiaries. It also includes an onboarding flow that registers your business with Twilio's A2P 10DLC compliance framework, a requirement for all business texting in the United States.

This is a one-way integration: Alvys sends outbound SMS through Twilio to drivers.

## Prerequisites

Before connecting Twilio (New), you need:

* Admin or Partner Admin access in Alvys.
* A business website with a privacy policy and terms and conditions page that meets Twilio's A2P 10DLC requirements. Review [Twilio's compliance guide](https://help.twilio.com/articles/11847054539547-A2P-10DLC-Campaign-Approval-Best-Practices#h_01KGNGR2MSVFT20XRE1HF4QW29) for what must be included.
* A primary contact person Twilio can reach if issues arise during registration.
* The EIN (Employer Identification Number) for each legal entity you are registering.

## How to connect

Navigate to Twilio (New) in Alvys.

* Log in to Alvys and navigate to Management > Integrations.
* Locate the Twilio (New) integration.

<Note>
  <img alt="Alvys Integrations page showing the Twilio (New) integration tile in the Management > Integrations section." />

  \*Alvys Integrations page showing the Twilio (New) integration tile in the Management > Integrations section. \*
</Note>

Complete the onboarding flow, working through each section in order.

* Choose your area code for your Twilio phone number.
* Set a forwarding number (optional) — calls to your Twilio number will forward to this number.
* Add subsidiaries: select any subsidiaries under your parent company that share the same EIN. For subsidiaries with separate EINs, complete the onboarding flow separately for each entity.

<Note>
  <img alt="Alvys Twilio (New) onboarding flow showing the “Configure Twilio” form subsidiary selector step." />

  \*Alvys Twilio (New) onboarding flow showing the “Configure Twilio” form subsidiary selector step. \*
</Note>

* Provide contact information: enter a primary contact person Twilio can reach if issues arise.
* Add your website, privacy policy, and terms and conditions. These must meet Twilio's A2P 10DLC requirements — see [Twilio's compliance guide](https://help.twilio.com/articles/11847054539547-A2P-10DLC-Campaign-Approval-Best-Practices#h_01KGNGR2MSVFT20XRE1HF4QW29) for exact requirements.

<Note>
  <img alt="Alvys Twilio Step 2 of 4 “Account Contact” form" />

  *Alvys Twilio Step 2 of 4 “Account Contact” form*
</Note>

<Note>
  <img alt="Alvys Twilio Step 3 of 4 “Setup your Business Profile“ form" />

  *Alvys Twilio Step 3 of 4 “Setup your Business Profile“ form*
</Note>

* Monitor the progress tracker. After submitting, a progress tracker appears. All three of the following must turn green before your integration is active: Profile Status, Service Trust Product, and Brand Status. The review and approval timeline is controlled by Twilio and can take up to one month to complete.
* Deactivate the old Twilio integration. Once all three progress tracker steps are green, navigate back to Integrations and deactivate your old Twilio integration. Check all subsidiaries for previously activated old Twilio integrations and remove all of them.

<Warning>
  ⚠️ Previous driver chats will not migrate to the new integration. You will need to start new chats with drivers, and drivers will need to opt back into SMS.
</Warning>

<Warning>
  ⚠️ Migration timing: If you integrated Twilio before May 12, 2025, you must upgrade to the Twilio (New) integration by July 25, 2025 to keep using Driver Chat — after that date, your old Twilio integration will be deactivated. · If you integrated Twilio after May 12, 2025, you are already on the Twilio (New) integration and no further action is required.
</Warning>

## What syncs

The Twilio (New) integration does not sync structured data fields between systems. It routes SMS messages between Alvys and drivers via Twilio's messaging infrastructure. The onboarding flow collects your business profile information (legal entity name, EIN, contact details, website, and policy URLs) and submits it to Twilio for A2P 10DLC registration.

* Messages sent from Alvys Driver Chat are routed outbound through Twilio to drivers' phones via SMS.
* Drivers must opt in to receive messages from your Twilio number. A blue banner appears at the top of the driver chat window if the driver needs to opt in again after the upgrade, and it shows which number the driver should send the opt-in message to.
* Each legal entity (subsidiary) with a different EIN requires a separate Twilio registration and phone number.

  To confirm the integration is working after all three progress tracker steps turn green, navigate to Driver Chat in Alvys, open a conversation with a driver who has opted in to SMS, send a test message, and confirm the driver receives it on their phone. If the driver has not yet opted in, they will see a prompt to send an opt-in message to your Twilio number; once they opt in, messaging will work normally.

  <Warning>
    ⚠️ \*\*Limits and unsupported: \*\*

    * Each legal entity with a separate EIN must be registered independently — you cannot combine subsidiaries with different EINs under a single registration.
    * Previous driver chat history does not migrate.
    * Drivers must re-opt in to SMS after the upgrade.
    * Approval timelines are set by Twilio and can take up to one month.
  </Warning>
* Each legal entity with a separate EIN must be registered independently — you cannot combine subsidiaries with different EINs under a single registration.
* Previous driver chat history does not migrate.
* Drivers must re-opt in to SMS after the upgrade.
* Approval timelines are set by Twilio and can take up to one month.

## Troubleshooting

### Integration shows "needs attention"

Click the "needs attention" status to open the status detail panel.

<Note>
  Twilio (New) integration showing "needs attention" status with a click indicator.

  <img alt="Notion Image" />
</Note>

* Review the status panel to identify which section failed: Profile Status, Service Trust Product, or Brand Status.
* Click the edit icon next to the failed section and resubmit the corrected information to Twilio for additional review.

<Note>
  <img alt="Alvys Twilio (New) edit icon next to a failed section and the resubmission form." />

  \*Alvys Twilio (New) edit icon next to a failed section and the resubmission form. \*

  <img alt="Image displaying “Edit Business Profile” form" />

  *Image displaying “Edit Business Profile” form*
</Note>

Save your changes to resubmit for verification.

### Brand status failed

* Twilio will send an email to your listed contact with instructions to resolve the issue. Follow the instructions in that email, then resubmit through the edit icon in the status panel (see above).

### Driver is not receiving messages

* Check whether a blue banner appears at the top of the driver's chat window in Alvys. If it does, the driver has not yet opted in to the new Twilio number.
* Ask the driver to send the opt-in message to the number shown in the blue banner. Once they opt in, messaging will resume.
* If no blue banner appears and the driver is still not receiving messages, confirm all three progress tracker steps are green in Management > Integrations > Twilio (New). If any step is not green, the integration is not yet active.
* If all steps are green and the driver has opted in but messages are still not being received, contact Alvys support and include your Twilio account details and the affected driver's information.

## FAQs

**Q: What happens if I don't upgrade before July 25, 2025?**

**A:** If you were on the old Twilio integration and did not upgrade, your Twilio integration will be deactivated and you will no longer be able to send or receive messages via Twilio in Alvys.

**Q: Can I register multiple subsidiaries at once?**

**A:** Only if they share the same EIN. For subsidiaries with different EINs, you must complete the onboarding flow separately for each entity.

**Q: I see three green checkmarks on the progress tracker. Am I all set?**

**A:** Three green checkmarks mean Twilio has approved your registration. If you have questions about whether your Driver Chat is fully active, contact Alvys support at [support@alvys.com](mailto:support@alvys.com) for confirmation.

**Q: What happens to previous driver chats after the upgrade?**

**A:** Previous driver chats do not migrate to the new integration. You will need to start new chats with drivers, and drivers must opt back in to SMS.


# Wex FleetOne FTP: Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/wex-fleetone-ftp-factoring-integration

Set up the Wex FleetOne FTP factoring integration in Alvys, add required reference numbers to loads, and submit invoice batches via FTP for AR financing.

<Note>
  This article explains how to set up the Wex FleetOne FTP integration in Alvys, add reference numbers to loads, and submit invoice batches via FTP to Wex FleetOne.
</Note>

## What This Integration Does

The Wex FleetOne FTP integration (also called Wex FleetOne factoring or invoice factoring via FTP) transmits invoice batches from Alvys to Wex FleetOne via FTP when you submit a batch from the Factoring Upload page. Before loads can be submitted, each load must have a reference number assigned. Wex FleetOne provides these reference numbers in a spreadsheet. Loads missing a reference number display a red warning icon in the Factoring Upload queue and cannot be included in a batch until the number is entered. Synonyms: invoice factoring, accounts receivable financing.

<Warning>
  If you previously set up the Wex FleetOne manual (non-FTP) integration, you must remove it before configuring the FTP version. Only one Wex FleetOne integration can be active per subsidiary at a time.
</Warning>

## Prerequisites

Before configuring this integration, confirm the following:

* You hold an Admin or Partner Admin role to add the Notice of Assignment and configure integration credentials.
* You hold the **"Billing"** permission to submit batches from the Factoring Upload page.
* Your subsidiaries are created in Alvys. FTP credentials must be configured separately for each subsidiary that uses Wex FleetOne FTP.
* You have received your FTP host address, username, and password from Wex FleetOne. Contact Wex FleetOne directly if you have not received these credentials.
* You have received the Notice of Assignment text from Wex FleetOne to add to your invoices.
* If you previously set up the Wex FleetOne manual (non-FTP) integration, you must remove it before setting up the FTP version. See Connect / Authenticate below.

## Connect / Authenticate

**Step 1: Add your Notice of Assignment**

The Notice of Assignment (NOA) declares to your customers that Wex FleetOne has the right to collect payment on the invoices you factor. It must appear on every invoice submitted through this integration.

1. Click the Profile button in the upper right corner and select Management to open your Company Profile.
2. In the Document Configuration section, click the plus sign (+) button. The Manage Important Info window will appear.
3. In the drop-down menu, select Notice of Assignment.
4. Paste the NOA text provided by Wex FleetOne into the text box.
5. Click Save.

<img alt="Screenshot showing the Document Configuration section with the plus sign (+) button in Company Profile" />

*Screenshot showing the Document Configuration section with the plus sign (+) button in Company Profile*

<img alt="Screenshot showing the Notice of Assignment text entry dialog in Company Profile" />

*Screenshot showing the Notice of Assignment text entry dialog in Company Profile*

**Step 2: Remove any existing Wex FleetOne integration and configure FTP credentials**

If you previously used the Wex FleetOne manual (non-FTP) integration, you must deactivate it before the FTP integration can be configured. If you have not previously used Wex FleetOne in Alvys, begin at sub-step 3.

1. Navigate to Management and open the Integrations page.
2. Under the Factoring section, locate the existing Wex FleetOne integration and click Deactivate to remove it.
3. Find Wex FleetOne FTP in the Factoring section.
4. In the subsidiary list, click the pencil icon next to the subsidiary you want to configure.
5. Enter the FTP Host, Username, and Password provided by Wex FleetOne.
6. Click Save. Repeat sub-steps 4 through 6 for each additional subsidiary that uses Wex FleetOne FTP.

<img alt="Screenshot showing the Wex FleetOne FTP credential entry form in Alvys Integrations" />

*Screenshot showing the Wex FleetOne FTP credential entry form in Alvys Integrations*

## Field & Data Mapping

Wex FleetOne FTP requires a reference number on each load before that load can be submitted in a batch. Wex FleetOne provides these reference numbers to you in a spreadsheet. You must enter each reference number on the corresponding load in Alvys before submitting.

Batch files are transmitted via FTP in the format expected by Wex FleetOne. No CSV download or manual upload to Wex FleetOne is required after batch submission.

## Sync Behavior

This integration is one-way and outbound. Alvys transmits batch files to Wex FleetOne via FTP when you submit a batch from the Factoring Upload page. Purchase and payment report uploads are not available for this integration.

## How to Add Reference Numbers to Loads

Wex FleetOne provides a reference number for each load in a spreadsheet sent to you by the provider. Each reference number must be entered on the corresponding load in Alvys before that load can be included in a batch submission. Loads missing a reference number will display a red warning icon in the Factoring Upload queue.

1. Obtain the reference number spreadsheet from Wex FleetOne.
2. Open the load in Alvys that corresponds to a reference number in the spreadsheet.
3. Locate the Reference Number field on the load and enter the value from the Wex FleetOne spreadsheet.
4. Save the load. Repeat for each load that needs a reference number before batch submission.

<img alt="Screenshot showing the Reference Number field on a load, and the red warning icon on a load in the Factoring Upload queue indicating a missing reference number" />

*Screenshot showing the Reference Number field on a load, and the red warning icon on a load in the Factoring Upload queue indicating a missing reference number*

## How to Submit a Batch

1. Confirm that all loads you want to submit have a reference number entered. Loads displaying a red warning icon cannot be submitted until a reference number is added.
2. Navigate to Accounting > Factoring Upload.
3. Select the subsidiary you are submitting for.
4. Select all loads in **Queued** status that you want to include in the batch.

<img alt="Screenshot showing the Factoring Upload queue with loads selected and the Submit Batch button" />

*Screenshot showing the Factoring Upload queue with loads selected and the Submit Batch button*

5. Click Submit Batch.
6. Stay on the page until the submission completes. Navigating away during submission may interrupt the FTP transfer. Loads submitted in the batch will update to **Invoiced** status.

<img alt="Screenshot showing the batch submission confirmation and loads updated to Invoiced status after submission" />

*Screenshot showing the batch submission confirmation and loads updated to Invoiced status after submission*

## Verify It's Working

After submitting a batch, loads included in the batch should move to **Invoiced** status. If a load remains in **Queued** status or displays a red warning icon, see the Troubleshooting section below.

## Troubleshooting

### Load not showing on Factoring Upload

1. Confirm the load status is **Queued**.
2. Confirm the load's invoicing settings use **Factoring Upload** as the delivery method.
3. Confirm the invoice and required documents were merged, either automatically or manually.
4. Confirm the load was not already included in another factoring batch.

### Load displays a red warning icon in the Factoring Upload queue

1. The load is missing a required reference number. Obtain the reference number spreadsheet from Wex FleetOne and enter the correct reference number on the load. Save the load and return to the Factoring Upload page; the warning icon should clear and the load can now be submitted.
2. Contact Alvys Support if the warning icon persists after entering the reference number.

### "Unable to locate file"

This error usually means the invoice file is no longer available. To resolve it:

1. Review the load number shown in the error message.
2. Open that load in Alvys.
3. Regenerate the invoice.
4. Try submitting the factoring batch again.

### "SFTP Authorization Error — Permission Denied (Password)"

This error usually means the credentials used to set up the integration are incorrect. To resolve it:

1. Review the credentials entered in the factoring integration setup.
2. Confirm the password is correct.
3. If the integration uses FTP/SFTP credentials from the factoring provider, make sure you are using those credentials — not your personal Wex FleetOne portal login.

### Batch does not submit or loads remain in Queued status

1. Confirm all selected loads have reference numbers entered and no red warning icons are visible. Loads without reference numbers cannot be submitted.
2. Confirm you stayed on the Factoring Upload page until the submission completed. Navigating away during submission may interrupt the FTP transfer. Retry the submission if needed.
3. Verify that the FTP credentials in Management > Integrations are correct for the subsidiary. Re-enter the host, username, and password from Wex FleetOne if needed and retry.
4. Confirm with Wex FleetOne that the FTP server is available and your credentials are active.
5. Contact Alvys Support if the batch continues to fail after verifying credentials.

### "Duplicate batch or invoice numbers"

This can happen if the page is refreshed, closed, or reopened while a batch is being submitted.

<Warning>
  This issue cannot be fixed manually. Contact Alvys Support so they can review and adjust the batch if needed.
</Warning>

### Purchase or payment report upload issues

If a purchase or payment report fails to upload, review the file format and the error message. The message usually identifies what is missing or incorrect.

Make sure the file includes the **load number** as the unique identifier. Without the load number, Alvys cannot match the report to the correct load or update the load as financed or completed.

<Warning>
  Purchase and payment report uploads are listed as unsupported for the Wex FleetOne FTP integration (see Limits / Unsupported below). If you are attempting a report upload for this integration, contact Alvys Support to confirm whether report uploads apply to your configuration before troubleshooting further.
</Warning>

### The FTP integration will not configure because a previous Wex FleetOne integration exists

1. Navigate to Management > Integrations, find the existing Wex FleetOne (non-FTP) integration, and click Deactivate to remove it.
2. Proceed to configure the Wex FleetOne FTP integration as described in Connect / Authenticate above.
3. Contact Alvys Support if the integration cannot be deactivated.

### Slow large batch submissions

Large files or batches with a high volume of loads may take longer to upload.

<Tip>
  If the upload is taking too long, try submitting a smaller batch. The Alvys team is also monitoring and improving performance for large batch submissions.
</Tip>

## Limits / Unsupported

* Purchase and payment report uploads are not available for the Wex FleetOne FTP integration.
* Each subsidiary requires its own set of FTP credentials. A single credential set cannot be shared across multiple subsidiaries.
* Only loads in **Queued** status can be included in a batch submission.
* Loads must have a reference number entered before they can be submitted. Reference numbers are provided by Wex FleetOne in a spreadsheet.

## FAQs

**Q:** Where do I get the reference numbers for my loads?

**A:** Wex FleetOne provides reference numbers in a spreadsheet sent to you directly. Contact Wex FleetOne if you have not received the spreadsheet.

**Q:** What does the red warning icon on a load mean?

**A:** The red warning icon means the load is missing a required reference number. Enter the reference number from the Wex FleetOne spreadsheet on that load, then return to the Factoring Upload page to include it in a batch.

**Q:** Why do I need to remove my existing Wex FleetOne integration before setting up the FTP version?

**A:** Alvys supports two separate Wex FleetOne integrations: a manual (download) version and an FTP version. Only one can be active at a time per subsidiary. If the manual version is already configured, it must be deactivated before the FTP credentials can be entered.


# WinFactor FTP: Factoring Integration
Source: https://docs.alvys.com/en/help/integrations/winfactor-ftp-factoring-integration

Set up the WinFactor FTP factoring integration in Alvys, submit invoice batches via FTP, and upload purchase and payment reports to update load statuses.

<Note>
  This article explains how to set up the WinFactor FTP integration in Alvys, submit invoice batches via FTP, and upload purchase and payment reports to update load statuses through the factoring lifecycle.
</Note>

## What This Integration Does

The WinFactor FTP integration (also called WinFactor factoring or invoice factoring via FTP) transmits invoice batches from Alvys to WinFactor automatically via FTP when you submit a batch from the Factoring Upload page. WinFactor reviews and funds the invoices, then makes purchase and payment reports available in their portal. You download those reports and upload them to Alvys to update the status of factored loads. Synonyms: invoice factoring, accounts receivable financing.

## Prerequisites

Before configuring this integration, confirm the following:

* You hold an Admin, Partner Admin, or Support role to add the Notice of Assignment and configure integration credentials.
* You hold the **"Billing"** permission to submit batches and upload reports.
* Your subsidiaries are created in Alvys. Credentials must be configured separately for each subsidiary that uses WinFactor FTP.
* You have received your FTP host address, username, and password from WinFactor. Contact WinFactor directly if you have not received these credentials.
* You have received the Notice of Assignment text from WinFactor to add to your invoices.

## Connect / Authenticate

1. **Add your Notice of Assignment.** The Notice of Assignment (NOA) declares to your customers that WinFactor has the right to collect payment on the invoices you factor. It must appear on every invoice submitted through this integration.
2. Click the Profile button in the upper right corner and select Management to open your Company Profile.
3. In the Document Configuration section, click the plus sign (+) button. The Manage Important Info window will appear.
4. In the drop-down menu, select Notice of Assignment.
5. Paste the NOA text provided by WinFactor into the text box.
6. Click Save.
7. **Enter your WinFactor FTP credentials.** You must configure FTP credentials for each subsidiary that will submit batches to WinFactor.
8. Navigate to Management and open the Integrations page.
9. Under the Factoring section, find WinFactor FTP.
10. In the subsidiary list, click the pencil icon next to the subsidiary you want to configure.
11. Enter the FTP Host, Username, and Password provided by WinFactor.
12. Click Save.
13. Repeat for each additional subsidiary that uses WinFactor FTP.

    <img alt="Screenshot showing the WinFactor FTP credential entry form in Alvys Integrations" />

    *Screenshot showing the WinFactor FTP credential entry form in Alvys Integrations*

## Field & Data Mapping

WinFactor FTP uses two specific CSV report formats for reconciliation:

* Purchase Report: downloaded from the WinFactor portal as the DetailHistorywithfees CSV. This report contains funded invoice records. When uploaded to Alvys, it moves loads to **Financed** status.
* Payment Report: downloaded from the WinFactor portal as the ReceiptHistoryDetail CSV. This report contains payment records. When uploaded to Alvys, it moves loads to **Completed** status.

Both files must be downloaded from the WinFactor portal in their original CSV format. Do not modify the file before uploading to Alvys.

## Sync Behavior

This integration is one-way and outbound. Alvys transmits batch files to WinFactor via FTP when you submit a batch from the Factoring Upload page. There is no automatic inbound sync from WinFactor to Alvys; purchase and payment reports must be downloaded from the WinFactor portal and uploaded to Alvys manually after each funding and payment event.

## How to Submit a Batch

1. Navigate to Accounting > Factoring Upload.
2. Select the subsidiary you are submitting for.
3. Select all loads in **Queued** status that you want to include in the batch.

   <img alt="Screenshot showing the Factoring Upload queue with Queued loads selected" />

   *Screenshot showing the Factoring Upload queue with Queued loads selected*
4. Click Submit Batch.

   <img alt="Screenshot showing the Submit Batch button" />

   *Screenshot showing the Submit Batch button*
5. Stay on the page until the submission completes. Navigating away during submission may interrupt the FTP transfer.

   <img alt="Screenshot showing the batch submission in progress or success confirmation" />

   *Screenshot showing the batch submission in progress or success confirmation*
6. After submission, loads will update to **Invoiced** status.

   <img alt="Screenshot showing loads updated to Invoiced status after successful batch submission" />

   *Screenshot showing loads updated to Invoiced status after successful batch submission*

## How to Upload Your Purchase Report

After WinFactor funds the invoices in a batch, download the purchase report and upload it to Alvys.

1. Log in to the WinFactor portal and download the DetailHistorywithfees CSV for the relevant funding period.
2. Go to Reports > Financial Reports > Factoring in Alvys.
3. Click the Upload Purchase Report button in the bottom right corner of the page.
4. Select the DetailHistorywithfees CSV file from your device and click Upload. Loads included in the report will update to **Financed** status.

   <img alt="Screenshot showing the Upload Purchase Report button and loads updated to Financed status after upload" />

   *Screenshot showing the Upload Purchase Report button and loads updated to Financed status after upload*

## How to Upload Your Payment Report

When WinFactor confirms payment has been collected, download the payment report and upload it to Alvys.

1. Log in to the WinFactor portal and download the ReceiptHistoryDetail CSV for the relevant payment period.
2. Go to Reports > Financial Reports > Factoring in Alvys.
3. Click the Upload Payment Report button.
4. Select the ReceiptHistoryDetail CSV file from your device.
5. Click Upload. Loads included in the report will update to **Completed** status.

   <img alt="Screenshot showing the Upload Payment Report button and loads updated to Completed status after upload." />

   *Screenshot showing the Upload Payment Report button and loads updated to Completed status after upload.*

## Verify It's Working

After submitting a batch, loads should move to **Invoiced** status within a few minutes of a successful batch submission. If a load remains in **Queued** status after submission, see the Troubleshooting section below. After uploading the purchase report, loads included in the report should move to **Financed** status. After uploading the payment report, loads included in the report should move to **Completed** status.

## Troubleshooting

### Batch does not submit or loads remain in Queued status

1. Confirm you stayed on the Factoring Upload page until the submission completed. Navigating away during submission can interrupt the FTP transfer. Retry the submission if the batch did not complete.
2. Verify that the FTP credentials in Management > Integrations are correct for the subsidiary. Re-enter the host, username, and password from WinFactor if needed and retry.
3. Confirm with WinFactor that the FTP server is available and your credentials are active.
4. Contact Alvys support if the batch continues to fail after verifying credentials.

### Purchase or Payment Report upload does not process or loads do not update

1. Confirm you are uploading the correct file type: the DetailHistorywithfees CSV for the purchase report, the ReceiptHistoryDetail CSV for the payment report.
2. Confirm the CSV file has not been modified or re-saved in a different format before uploading. Upload the file as downloaded from the WinFactor portal.
3. Contact Alvys support if the upload continues to fail.

## Limits / Unsupported

* Automatic inbound sync from WinFactor to Alvys is not supported. Purchase and payment reports must be uploaded manually.
* Each subsidiary requires its own set of FTP credentials. A single credential set cannot be shared across multiple subsidiaries.
* Only loads in **Queued** status can be included in a batch submission.

## FAQs

**Q:** What happens if I navigate away from the Factoring Upload page during submission?

**A:** The FTP transfer may be interrupted and the batch may not complete. Stay on the Factoring Upload page until the submission confirmation appears before navigating away.

**Q:** Which file should I download from WinFactor for the purchase report?

**A:** Download the DetailHistorywithfees CSV from the WinFactor portal. This is the file Alvys expects when you upload a purchase report.

**Q:** Which file should I download from WinFactor for the payment report?

**A:** Download the ReceiptHistoryDetail CSV from the WinFactor portal. This is the file Alvys expects when you upload a payment report.


# April 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/april-2026-releases

April 2026 added a Delivery Logs panel to webhook settings, so you can see every event delivery attempt, filter by outcome, and export the history.

<Note>
  April 2026 was a focused month: webhook subscriptions gained full delivery visibility, with a logs panel, status filters, a health indicator, and CSV or JSON export.
</Note>

## Overview

April brought one change, aimed at anyone who keeps an Alvys webhook pointed at another system. Until now there was no way to see whether an event actually arrived. You can now open any webhook and read its full delivery history — what was sent, whether it succeeded, and what the receiving system said when it failed — without leaving Alvys.

<Update label="April 15, 2026" description="Webhook subscriptions keep a visible record of every delivery attempt, with status filters, a health indicator and CSV or JSON export.">
  ## Delivery Logs for your webhook subscriptions

  Webhook subscriptions now keep a visible record of every delivery attempt. Open **Settings → API → Webhooks**, select a webhook, and the **Delivery Logs** panel lists each attempt with its event type, a Success, Failed, or Skipped status badge, a timestamp, and the error message when something went wrong. A health indicator on the webhook's detail page flags an endpoint that has started to degrade, so you can spot a failing integration before someone downstream reports missing data.

  **What this includes:**

  * A status filter to narrow the list to All, Success, Skipped, or Failed.
  * **Export .CSV** and **Export .JSON** buttons at the bottom of the panel, for audit trails or analysis elsewhere. The export covers the entries matching your current filters, so set the filters first.
  * Email notification to Partner Admins when a webhook is automatically disabled after repeated failures.
  * A "Skipped" status, which means the subscription was disabled or paused at the moment the event fired — not that the delivery failed.

  Replaying a failed delivery from this screen is not part of this release. For now, export the failures and re-trigger the events from your own system.

  This rolls out with the Public API feature set, so the panel appears once your account has access to the Webhooks section under Settings.

  **Learn more:** [How to Monitor Webhook Deliveries](/en/help/integrations/how-to-monitor-webhook-deliveries)
</Update>


# August 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/august-2026-releases

August 2026 retires the legacy Load Creation screen on August 31, made Bill of Lading and Proof of Delivery requirements explicit per subsidiary, added settlement features including negative-balance rollover and off-cycle pay periods, extended Custom References to customers and locations, added Created, Appointments, and Trailer Fleet columns plus a right-click action menu to the Dispatch Planner, kept manual accessorials in place through customer lane contract changes, and began warning you before you double-book a trailer or truck.

<Note>
  August 2026 carries two changes with a deadline attached: the legacy Load Creation screen is switched off for good on August 31, and a Bill of Lading no longer satisfies a Proof of Delivery requirement unless your subsidiary opted in. The month also brought a batch of requested settlement features, new Dispatch Planner columns including Appointments and a right-click menu on a trip, Custom References for customers and locations, manual accessorials that survive a lane contract change, and a warning before you double-book a trailer or truck.
</Note>

## Overview

Two changes in August need something from you rather than just a read. The legacy Load Creation screen is being retired in stages and stops working everywhere on **August 31**, so any team still using it should move across before then. And a Bill of Lading no longer satisfies a Proof of Delivery requirement unless your subsidiary explicitly opted in, which is a settings check rather than a migration.

The rest is additive. Driver pay picked up automatic negative-balance rollover, off-cycle pay periods, saved views, and a rule condition for non-revenue loads. Carrier settlements can be grouped by factoring company. The Dispatch Planner gained Driver Fleet, Truck Fleet, Trailer Fleet, Next planned event, Created, and Appointments columns, and right-clicking a trip now opens a menu of the actions you reach for most. Empty miles now recalculate whenever you change a trip's previous stop. The Reports Library gained Days to Invoice and Lane Profitability, and Custom References now cover customers and locations as well.

Late in the month, dispatch, billing, and company administration all got safer. Alvys now warns you before you assign a trailer or truck that is already committed to another trip, a split trip keeps its trailer instead of dropping it, manual accessorials stay on a load when you apply or change a customer lane contract, registering a subsidiary verifies that you own the MC# or USDOT#, and editing the company profile is limited to Admin, Support, and Partner Admin.

<Update label="August 28, 2026" description="Manual accessorials survive a customer lane contract change, and the Trips grid gains an Appointments column.">
  ## Manual accessorials stay on the load when a lane contract changes

  Applying, changing, or removing a customer lane contract on a load used to clear accessorials that had been added by hand, and operators had to re-enter them. Alvys now removes only the accessorial lines that came from the previous contract template, and leaves manually added lines in place.

  Two details are worth knowing. When the same charge type exists on both a manual line and a contract template, such as two Detention lines, both are kept rather than collapsed into one. And in the invoice and accessorial grid, a manually added line on a contracted load no longer shows **Source = Contract**; that label is now reserved for lines that came from a template.

  The same rules apply when a batch contract refresh runs on loads after you edit a contract. This applies going forward: a line added before this release may still be treated as contract-owned, so check it if an accessorial disappears after a contract change.

  **Learn more:** [How to Create and Add Accessorials](/en/help/loads-trips/how-to-create-and-add-accessorials)

  ## Appointments column on the Dispatch Planner Trips grid

  The Trips grid in Dispatch Planner v2 can now show how many of a trip's stops have a confirmed appointment, so you can see which trips still need calls without opening each one. The column reads as a count with a colored dot: green for **3/3 Confirmed**, yellow for **1/3 Confirmed**, and gray for **0/3 Confirmed**.

  **Appointments** is hidden until you add it from the column picker. Once it is showing, you can sort it to bring the trips still needing calls to the top, or filter to Partial and Unconfirmed. Appointments are still confirmed on the load's details page; this column tells you where to go.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="August 26, 2026" description="Right-clicking a trip in Dispatch Planner v2 opens an action menu, and Trailer Fleet completes the three fleet columns.">
  ## Right-click a trip in the Dispatch Planner for the actions you use most

  Right-clicking a trip in Dispatch Planner v2 now opens a menu of the actions you would otherwise go looking for. It works on the main Trips grid and in the details view, including the Dispatch Assist suggestion rows pinned at the top.

  The menu offers **Open In New Tab** and **Open In New Window** for the load's details page, **Lane Report** to open the lane in the lanes page, **Dispatch** to open the dispatch dialog, **Priority** to set or clear a priority, **View Notes** to open the trip sidebar on the Notes tab, and **Copy** and **Export**.

  Two details worth knowing. **Dispatch** appears only on a trip that can actually be dispatched — a Covered trip with a driver assigned — so its absence is information rather than a fault. And setting Priority from this menu asks you to confirm first, unlike the inline Priority cell, which applies the change straight away; either way it is a load-level value, so it applies to every trip on that load.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)

  ## Fleet columns on the Dispatch Planner Trips grid (August 18, 20, and 26)

  The Trips grid in Dispatch Planner v2 can now show the fleet behind each trip, across three columns. **Driver Fleet** shows the fleet of the driver assigned to the trip, **Truck Fleet** the fleet of the assigned truck, and **Trailer Fleet** the fleet of the assigned trailer. Truck Fleet arrived on August 18, Driver Fleet on August 20, and Trailer Fleet on August 26.

  All three are hidden until you add them from the column picker, and all three can be sorted and filtered by fleet. When a trip is covered by a team of drivers, Driver Fleet shows Driver 1's fleet, the same way the Drivers grid does.

  These are separate from the existing **Fleet** column, which shows the load's own fleet rather than the fleet of the assigned driver, truck, or trailer.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="August 25, 2026" description="The Dispatch Planner Trips grid can show when each trip was created.">
  ## Created column on the Dispatch Planner Trips grid

  The Trips grid in Dispatch Planner v2 can now show when each trip was created, so you can tell at a glance how long a trip has been sitting unassigned. The time appears in your own local time zone, for example 08/25/2026 @ 09:22 CDT.

  **Created** is hidden until you add it from the column picker, and once it is showing you can sort by it and filter it by date.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="August 24, 2026" description="Alvys warns before you double-book a trailer or truck, split trips keep their trailer, subsidiary registration verifies MC# and USDOT# ownership, and company profile edits require Admin, Support or Partner Admin.">
  ## Alvys warns you before you double-book a trailer or truck

  Assign a trailer or truck that is already committed to a dispatched or in-transit trip over the same period, and Alvys now names the trip it is on before the assignment goes through. It is a warning rather than a block, so you can read it and still continue, but you no longer find out afterwards. It works everywhere you assign equipment, including the Manage Assets wizard, the pre-assign trailer dialog, the loads board, and both versions of the Dispatch Planner.

  Routine pre-planning does not set it off. A truck that finishes one trip today and starts another tomorrow is not a conflict.

  **Learn more:** [How to dispatch a load](/en/help/loads-trips/how-to-dispatch-a-load)

  ## Your trailer stays with the load when you split a trip

  Splitting a trip used to drop the trailer from the new leg. Alvys now asks whether to carry it over and keeps it by default. Set a trailer on one leg after a split and Alvys offers to apply it to the other legs of that split, filling in the empty ones and leaving any leg that already has a different trailer alone. Removing a driver or truck no longer takes the trailer with it either; there is a separate **Also remove trailer** checkbox for when you want that.

  **Learn more:** [Optimize - Split Trips & Rearrange Stops](/en/help/loads-trips/optimize-split-trips-rearrange-stops)

  ## A new subsidiary now verifies that you own the MC# or USDOT\#

  Creating a subsidiary includes a step that confirms you own the authority you are registering, before the subsidiary is created. Verified carrier details pre-fill the form, and once a subsidiary is verified its MC# and USDOT# are locked, because those numbers print on rate confirmations and invoices. A correction is a support request from that point on. A number already registered by any Alvys account is refused with the reason shown, and if verification cannot be completed the subsidiary is not created rather than being let through unverified.

  This is rolling out to accounts gradually, so you may not see the step yet.

  **Learn more:** [How to add a USDOT# to a Subsidiary](/en/help/administration/how-to-add-a-usdot-to-a-subsidiary)

  ## Editing the company profile and adding subsidiaries now require Admin, Support, or Partner Admin

  Owner phone, owner email, and operating countries were previously editable by any signed-in user of your company, and so was creating a subsidiary. Both are now limited to **Admin**, **Support**, and **Partner Admin**. Partner Admin can now edit operating countries, which the old check left out by mistake.

  For everyone else those fields are visible but read-only, an empty one reads **Not Set**, and the option to create a subsidiary is hidden rather than failing when you click it. If you are a Biller, Accountant, Dispatcher, or Operation Manager and no longer see **New Subsidiary**, that is the restriction working as intended.

  **Learn more:** [How to add a USDOT# to a Subsidiary](/en/help/administration/how-to-add-a-usdot-to-a-subsidiary)
</Update>

<Update label="August 20, 2026" description="Custom References extend to customers and locations, with new tabs, profile sections and optional grid columns.">
  ## Custom References for customers and locations

  Custom References already existed for loads, trips, stops, drivers, trucks, and trailers. They now cover **customers** and **locations** as well, so your company or facility profiles can carry the identifiers you use — internal account numbers, facility notes, region tags — instead of tucking them into general instructions.

  **What you get:**

  * Two new tabs in **Settings > Custom References**: **Customers** and **Locations**. The create, edit, and disable flow is the same as the other tabs, with the same field types — Text, Date, Select, and Checkbox.
  * A **References** section on each company profile and each location profile, alongside the standard fields, where values are added and edited directly.
  * Optional columns on the Customers and Locations grids — one per reference you choose to show there.
  * Customer and location reference values are available through the Alvys public API.

  **A few limits to know about:**

  * The new grid columns display values but do not yet support sorting or filtering.
  * Reference values are not yet included in the Customers or Locations CSV export.
  * Document surfaces (rate confirmations, Bills of Lading, invoices) do not carry customer or location references, matching how driver, truck, and trailer references already work.

  **Learn more:** [How to Set Up Custom References in Alvys](/en/help/administration/how-to-set-up-custom-references-in-alvys)
</Update>

<Update label="August 17, 2026" description="Driver pay rules can exclude non-revenue loads, legacy Load Creation begins retiring ahead of the August 31 cut-off, and empty miles recalculate on every trip.">
  ## Driver pay rules can exclude non-revenue loads

  Driver pay rate rules can now take account of whether a load is a revenue load or a non-revenue one. If you use non-revenue loads to track repositioning moves, such as sending a driver to collect a preloaded trailer, you can now gate a rate policy so it does not fire on those moves, instead of correcting each statement by hand afterwards.

  This is a new condition in the existing rate rule builder. Your current rules are unchanged until you add it.

  ## Legacy Load Creation is being retired

  The old Load Creation screen is being switched off in stages, and **the last day it works anywhere is August 31**. After that, every account creates loads on the current New Load form.

  Tenants whose users already created loads on the current form during the previous 30 days lost access to the old screen first, on August 17, and more accounts move across each day until the cut-off. If your team still uses the old screen, move them over before August 31 so the change does not arrive mid-shift. Nothing needs to be migrated and no data moves; only the screen you create loads on changes.

  **Learn more:** [How to Create a Load](/en/help/loads-trips/how-to-create-a-load)

  ## Empty miles recalculate when you change a trip's previous stop

  Editing a trip's previous location now recalculates empty miles on **every** trip, and the figure on the page updates as soon as you save.

  Before this, the recalculation only ran on trips whose mileage came from the mileage engine. On a trip with a manually entered or tender-supplied mileage source, or none set, the previous stop changed but empty miles kept the old value or stayed blank. That fed straight through to total empty miles and to per-mile driver pay.

  Two details worth knowing. If the mileage lookup fails, empty miles is cleared rather than left wrong: a blank means "not yet calculated", and re-saving the stop retries it. And a load mileage you entered by hand is still never overwritten by an automatic recalculation.

  **Learn more:** [Mileage Sources and Types](/en/help/loads-trips/mileage-sources-and-types)
</Update>

<Update label="August 13, 2026" description="The Dispatch Planner Drivers grid can show what a driver's next commitment actually is.">
  ## Next planned event column on the Dispatch Planner Drivers grid

  The Drivers grid can now show what a driver's next commitment actually is, not just when it starts. **Next planned event** reads Trip, Hometime, Vacation, Restart, Sick or Emergency, Work order, Repair, or Other, and a dash when there is no next commitment.

  It reads from the same availability window as Next planned at and Available in, so all three describe the same event. The practical use is loading a driver toward home rather than away from it: you can see the driver has Hometime coming up without opening the sidebar. The column sorts and filters like the others.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="August 4, 2026" description="Proof of Delivery and Bill of Lading are separate requirements per subsidiary; a BOL stands in only if you opted in.">
  ## Bill of Lading and Proof of Delivery are now separate requirements

  Alvys used to accept an uploaded **Bill of Lading** in place of a missing **Proof of Delivery** when deciding whether a load could be released or invoiced. That behaviour was built for operations whose BOL carries the delivery signatures, but there was no way to opt out of it — so a subsidiary that genuinely needed a POD could be invoiced on a BOL alone.

  This is now an explicit choice per subsidiary. **Proof of Delivery** remains the required document, with an indented sub-option, **Use Bill of Lading as Proof of Delivery**, beneath it. Turn that on and a BOL can stand in for a missing POD, exactly as before. Leave it off and only an actual POD satisfies the requirement. When both documents are on a load, the POD always takes priority.

  **What you need to know:**

  * The same setting governs AutoMerge, not just the release and invoicing gate — so a BOL is merged into the invoice packet as the POD only when you have opted in.
  * **This changed the default.** Subsidiaries that did not opt in during the notice window moved to strict separation on August 4, which means a load can no longer be released or invoiced on a BOL alone. If releasing or invoicing has started failing on a missing POD, this setting is the first place to look.
  * There was no backfill, so the setting reflects what each subsidiary chose rather than what it used to do implicitly.

  **Learn more:** [Invoicing Settings](/en/help/accounting-settlements/invoicing-settings)
</Update>

<Update label="August 2026" description="Smaller improvements and fixes from across the month in settlements, invoicing and accounting, dispatch, mileage, fuel, reporting, EDI and access.">
  ## Driver Pay & Settlements

  * Negative balances on driver statements can roll over automatically, so you no longer chase them manually each period.
  * Create off-cycle pay periods, and choose pay-period start dates further back when you need more flexibility.
  * Optionally display the remittance date on carrier statements, using a new settings toggle.
  * Accessorial notes now appear on the statement, giving clearer pay context.
  * Transaction modals show rate subtotals, so totals are easier to verify at a glance.
  * Revert a statement when an accounting or payment-provider sync fails, so you can correct and resubmit instead of getting stuck.
  * Triumph vendor payments sync into your ERP automatically.
  * Carrier Settlements can group open items by factoring company, filter by carrier within that view, and optionally restore per-carrier rows for remit-to workflows. Carrier settlement Drafts also refresh immediately after you unapprove items from the sidebar.
  * Truck-specific deductions stay tied to the right truck instead of spilling across a fleet, and deduction rules no longer reappear week after week after Business Central payroll generation.
  * Adding detention or layover to an already-paid load no longer recalculates mileage incorrectly, statement mileage with accessorials is more accurate, and draft statement previews show the correct PDF.
  * You can unmark paid loads in more statuses when a correction is needed, and paid accessorials no longer reappear as unpaid for owner-operators after the New Pay Module migration.
  * Owner-operator statements generate reliably even when an old deduction rule was deleted, and owner statements include the loads you expect.
  * Triumph factoring packets keep the carrier invoice in the combined PDF, lumper audit documents map to the right document type, and factoring remit-to details sync correctly for TriumphPay-paid carriers across accounting integrations.
  * The **Release** action stays available after you upload carrier invoices.
  * When an EFS code has already been issued or used, you can still correct the carrier or driver on the load, and EFS eCheck connect reports permanent faults clearly rather than as a temporary outage.
  * Factoring uploads succeed when the carrier DOT number is set correctly.
  * Settlement dates display correctly for users outside US time zones, pay period filters hide deprecated periods unless they still have an active draft, and your Pay Module column order sticks after you rearrange it.
  * Drivers can view pay stubs and completed loads in the mobile app again.
  * Credit limit updates save without a server error.
  * Save and reuse custom views in Driver Settlements.
  * Bulk-export driver statements into a single ZIP file.
  * Control who can revert a driver statement with a dedicated permission.
  * See hours worked and the dispatcher on the Driver Settlements grid.
  * Invoice and due dates apply across carrier settlement tabs automatically, and carrier invoice and due dates stay consistent between the main page and the carrier profile.
  * Export settlement drafts for manager approval more reliably.
  * Carrier-mode loads no longer appear as settlement-eligible external carriers.
  * Generate carrier settlements without needing Dispatch access.
  * Clear the driver paid label when you need to, and paid-to-driver loads are protected from accidental cancellation.
  * Save edited deductions without re-selecting the date.
  * Generate a statement from a draft more reliably when factoring-company grouping is turned off.
  * Save pay schedules successfully, so new pay periods can be created without errors.
  * A load's paid status reads more clearly, so it is obvious when and why it was marked paid.
  * The rate plan editor uses the full width of the screen while you configure pay.

  ## Invoicing, Billing & Accounting

  * QuickBooks Desktop queued exports now wait in the queue until the Web Connector picks them up, so a slow or offline connector no longer silently drops invoices after a week.
  * QuickBooks Desktop sync is more reliable when adding fuel-provider vendors, sessions no longer stall mid-sync, and payments for completed loads flow into QuickBooks more dependably.
  * Invoiced trips stay Invoiced — the status no longer snaps back to Released unexpectedly.
  * Invoice delivered dates and the invoice numbers in the Load Usage export are more accurate.
  * Shared billing exports every Business Central transaction in your selection, not just the first.
  * You can regenerate an invoice even when an attached file is no longer available, and invoice generation completes without unexpected errors.
  * Export the full set of billing cycles you select on the billing page.
  * **Change Customer** is available on Released loads when you have permission.
  * Duplicate payment entries no longer inflate Amount Paid on invoices, and Aging report exports show accurate totals and grouping.
  * Match customers by company number when syncing invoices to Business Central.
  * Invoice generation no longer gets stuck in Processing.
  * Stuck QuickBooks Desktop invoices clear from Error Transactions more reliably, and QuickBooks Online versus Desktop payment attribution stays accurate.
  * Re-export a posted supplemental to your ERP after it is revised in Alvys.
  * Credit memos raised against a load now carry their original invoice through to your accounting system, so applying a credit is no longer a manual match. Standalone or summary credits with no original invoice are unchanged.
  * In Business Central, a new sales credit memo now reads **Credit Memo** followed by the original Alvys invoice number, matching how sales invoices already read, so Apply Customer Entries is searchable the same way. QuickBooks Online, QuickBooks Desktop, NetSuite, and Sage are unchanged.

  ## Loads & Dispatch

  * See exactly which credentials are blocking a carrier assignment.
  * Create load templates with transit times of up to 30 days, replacing the old 10-day limit.
  * Use custom references on loads in more load statuses.
  * The dispatcher on a load stays put when you edit the load.
  * Assigning a driver in the planner preserves your dispatcher assignment preferences.
  * Location internal notes appear on the load again.
  * View and edit Previous Stop on subsidiary and carrier-only workflows.
  * Sequential dispatch now guards truck and asset overlaps, not only driver overlaps.
  * Available at and Available in on the Dispatch Planner Drivers grid now anchor on the trip a driver actually delivered last, so overlapping trips no longer show a driver free at the wrong place or time.
  * Home time no longer overrides real driver availability in the Dispatch Planner.
  * Longer equipment length options are available when managing assets.
  * Adding a location uses clearer labelling, so it is obvious you are creating a location and not a customer.
  * Cloning a load and generating carrier rate confirmations work even when stop names are missing.
  * You can clear the priority on a completed non-revenue load.
  * Shipper location edits save correctly even when an invoice has already been generated.

  ## Mileage, Routing & Mapping

  * Previous-stop resolution and empty-miles accuracy improve when pickup actuals arrive.
  * Tolls are deducted more reliably.

  ## Fuel

  * IFTA and custom fuel imports are clearer and more forgiving: excluded rows surface as proper partial-success feedback, optional columns stay optional, and common diesel synonyms map to Truck Diesel correctly.
  * Fuel transactions no longer appear as duplicates.
  * Activating Alvys Marketplace works again.
  * Comdata fuel purchases show on the settlement screen.
  * EFS fuel sync is reliable again, and Relay fuel truck numbers populate correctly.
  * IFTA reports sync successfully after you click Sync.

  ## Reporting & Insights

  * Two additions to the Reports Library: **Days to Invoice** and **Lane Profitability**.
  * Custom visualisations support "next" date filters, such as the next 7 or 30 days.
  * Reporting access changed on User Details now applies as expected — including when authoring access is revoked.
  * Commission spreadsheet sync includes the full set of expected data, and driver statements that share the same date now appear correctly.
  * Scheduled report exports send again as expected.

  ## Integrations, EDI & Tracking

  * Stronger EDI 214 and 990 handling for partner workflows, including arrival and location detail, and partner EDI loads more reliably receive stop dates and times.
  * After a successful EDI share, the stop card **Shared update** label refreshes right away, and EDI tender updates preserve consolidated shared and route notes instead of overwriting them.
  * MacroPoint outbound tracking data reaches your customers more reliably.
  * Map routes load consistently on the Asset Map.
  * Rejected 997 acknowledgments are resolved, and 214 mapping is more accurate, including L11 segment filters.
  * Tender 204s that use S5 mapping codes are accepted more reliably.
  * PU numbers are added automatically on BluJay and JBS loads.
  * Armada EDI tenders create with the correct reefer equipment type instead of a 53-foot dry van.
  * Motive ELD integrations reconnect more reliably.
  * FourKites outbound tracking updates keep reaching your customers.
  * Destination whitespace that caused EDI location mismatches is trimmed.
  * Multi-zone return-air temperature readings from ELD data are preserved instead of being dropped.

  ## Companies, Contacts & Access

  * The Profiles card opens against the tenant you are currently viewing, not your first tenant.
  * The permission **Select all** checkbox accurately reflects a partial selection.
  * Legacy driver custom references, such as hire date, are editable again where the underlying record was incomplete.
  * Deleted users leave the Users list right away, with no refresh required.
  * You stay signed in through active workflows. A brief authentication hiccup now retries quietly instead of logging you out and losing in-progress edits, so unexpected logouts should be much rarer.
  * Help Center article images load reliably again.

  ## Search & Imports

  * Truck list imports finish reliably and surface errors instead of hanging silently.
</Update>

## Public API

Integrator-facing changes shipped in August too, including stricter validation of parameters passed to Alvys MCP tools. Those are documented for developers in the [Alvys changelog](/en/api/changelog).


# December 2025 Releases
Source: https://docs.alvys.com/en/help/what-s-new/december-2025-releases

Assignment Preferences replaces Dispatch Preferences in December 2025, adding time-based tracking and trailer type filtering for faster load planning.

<Note>
  December 2025 brought a rename and expansion of Dispatch Preferences into Assignment Preferences, adding time-based tracking and trailer type filtering so you can plan loads faster with more accurate fleet management.
</Note>

## Overview

This release note covers the December 2025 update to assignment planning in Alvys (December release notes, What's New for December 2025), centered on the new Assignment Preferences experience.

<Update label="December 9, 2025" description="Dispatch Preferences becomes Assignment Preferences, with start and end dates for upcoming asset changes and filtering by trailer type.">
  ## Assignment Preferences replaces Dispatch Preferences with new planning capabilities

  **Dispatch Preferences** has been renamed to **Assignment Preferences**. The feature now includes time-based tracking and trailer type filtering to help you plan loads faster and manage your fleet more accurately.

  **What changed:**

  You can see which assets are active and available, so you can view which driver and truck combinations are live and plan assignments into the future.

  You can handle upcoming asset changes by using start and end dates to preassign trucks and manage driver swaps early.

  You can match loads to the right trailer type by filtering trucks by type, which reduces mismatches and improves accuracy.

  This applies to all users who plan and assign loads.

  <Note>
    <img alt="Assignment Preferences screen showing driver-truck combinations and trailer type filtering" />

    *Assignment Preferences screen showing driver-truck combinations and trailer type filtering*
  </Note>

  **Learn more:** [How to set up Assignment Preferences for drivers](/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers)
</Update>


# Discover Shortcuts
Source: https://docs.alvys.com/en/help/what-s-new/discover-shortcuts

With the launch of our new navigation design, we’ve introduced a range of keyboard shortcuts to help you navigate the platform faster and more efficiently.

<Note>
  Keyboard shortcuts let you jump to key areas of the Alvys platform instantly from any screen, without navigating through menus, so you can book loads, check invoices, manage drivers, and more in fewer keystrokes.
</Note>

## Overview

Keyboard shortcuts, also called hotkeys or key commands, are keyboard combinations that navigate directly to a section of the Alvys platform. Instead of clicking through the navigation menu, you press a key combination and Alvys takes you there immediately. Shortcuts work from any screen in the platform as long as the navigation bar is loaded. They are available to all users except Drivers.

## Where to Find It

Shortcuts are platform-wide. There is no dedicated settings page to configure them; they work automatically once you are signed in to the platform.

## Key Concepts

**Windows shortcuts** use the Alt key combined with one or more additional keys.

**Mac shortcuts** use the Command key (shown as the ⌘ symbol) combined with one or more additional keys.

Each shortcut maps to a destination in the platform. Pressing the combination takes you directly to that section. If your role does not have access to a particular section, the shortcut for that section will not navigate there.

## How to Use It

Press the key combination for the action you want. The shortcuts below are organized by destination.

| Destination | Windows     | Mac               |
| ----------- | ----------- | ----------------- |
| Search      | Alt+S       | Command+K         |
| New Load    | Alt+Shift+L | Command+Control+L |
| Loads       | Alt+L       | Command+L         |
| Tenders     | Alt+Shift+I | Command+Shift+S   |
| Invoice     | Alt+I       | Command+I         |
| Reports     | Alt+H       | Command+Shift+H   |
| Companies   | Alt+C       | Command+E         |
| Drivers     | Alt+D       | Command+D         |
| Trucks      | Alt+U       | Command+U         |
| Trailers    | Alt+J       | Command+J         |
| Carriers    | Alt+K       | Command+G         |

## Settings and Permissions

Shortcuts are available to all users except those with the Driver role. No configuration is required to enable them.

Navigating to a section using a shortcut respects the same access rules as the navigation menu. If a user does not have permission to access a section, the shortcut for that section will not complete the navigation.

## Limits and Behavior

Shortcuts work from any screen in the platform while the navigation bar is active.

On Mac, the Command+L shortcut navigates to Loads. If your browser intercepts Command+L (some browsers use it to focus the address bar), the platform shortcut may not fire. Use the navigation menu in that case or adjust your browser shortcut settings.

On Windows, Alt+H navigates to Reports. The same combination is used for the Home shortcut in some legacy navigation configurations; if you see unexpected behavior, use the navigation menu.

## FAQs

**Q: Do shortcuts work on all browsers?**

**A:** Shortcuts work in all major modern browsers. Some browsers have built-in shortcuts that use the same key combinations, which can interfere. If a shortcut does not work, check whether the browser is intercepting that key combination.

**Q: Can I customize the shortcut keys?**

**A:** No. The shortcut key combinations are fixed and cannot be changed by users. If you have feedback or ideas for new shortcuts, contact Alvys support and share your suggestion.

**Q: Why does a shortcut not take me anywhere?**

**A:** If pressing a shortcut does nothing, the most common reasons are: your browser is intercepting the key combination, or your user role does not have access to that section of the platform. If neither of those applies, contact Alvys support.


# February 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/february-2026-releases

February 2026 delivers Custom References for trucks and trailers plus automatic retry logic for outbound EDI 990, 214, and 210 message delivery.

<Note>
  February 2026 brought structured Custom References for trucks and trailers plus automatic retry handling for outbound EDI delivery, so your fleet data stays organized and critical EDI documents reach customers reliably.
</Note>

## Overview

This release recaps the two February 2026 features: Custom References for trucks and trailers, and Outbound EDI Delivery Resilience.

<Update label="February 2026" description="Custom References extends to trucks and trailers, and outbound EDI 990, 214 and 210 messages retry automatically after a customer-side outage.">
  ## Custom References for trucks and trailers

  You can now create up to 20 custom fields for each truck and trailer, letting you capture asset-specific details such as inspection reminders, maintenance intervals, ownership information, lease terms, or utilization status. Centralizing this data keeps your fleet information in one place, minimizes errors, strengthens audit readiness, and reduces manual workload across your operation.

  Custom References give you several capabilities. You can track and report on the operational data that matters by creating up to 20 custom fields per truck and trailer. You can find asset-specific data fast by searching, filtering, and sorting truck and trailer lists using custom references, giving your team instant access to the operational and compliance information needed for proactive oversight and reliable audits. You also get cleaner operations and stronger reporting, because Custom References unify fleet data into a single source of truth that eliminates data silos and manual workarounds, and you can pull custom fields into Custom Reports for real-time, fleet-wide visibility on maintenance, compliance, and asset lifecycle status.

  This affects **Admins**, who can create and edit Custom References. Find this feature in Settings, then Custom References. To set it up, go to Settings, then Custom References, and create or edit your fields there.

  **Learn more:** [How to Set Up Custom References in Alvys](/en/help/administration/how-to-set-up-custom-references-in-alvys)

  ## Automatic retry for outbound EDI delivery

  Outbound EDI Delivery Resilience keeps your operations moving even when customer EDI endpoints face temporary outages. It ensures critical documents, including 990s (Tender Response), 214s (Status Update), and 210s (Invoice), are delivered reliably without increasing manual workload for your team.

  This feature applies automatic retry logic to outbound EDI messages (990, 214, 210) that encounter temporary customer-side delivery failures. No manual intervention is required, because Alvys handles delivery seamlessly in the background on your behalf. All failed delivery attempts are automatically recorded for support visibility and follow-up.

  The benefits are concrete. It minimizes the risk of missed tenders, delayed invoices, or incomplete tracking caused by temporary endpoint outages. It also decreases operational risk and customer friction with a hands-off, resilient approach to EDI communications.

  This enhancement is now live and operates automatically for all outbound 990, 214, and 210 EDI transactions sent from Alvys, with no configuration needed by your team.
</Update>


# January 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/january-2026-releases

January 2026 releases add granular company permissions splitting customer and non-customer access, and Custom Reference fields for drivers.

<Note>
  January 2026 brought two updates focused on data control and operational reporting: granular company permissions that separate customer and non-customer access, and custom reference fields for drivers.
</Note>

## Overview

On January 30ᵗʰ 2026 Alvys released granular company permissions that split create and edit access between customer and non-customer profiles, and extended Custom References so teams can track and report on driver-specific data.

<Update label="January 30, 2026" description="Company create and edit permissions split into Customers and Non-Customers, and Custom References extends to driver records.">
  ## Granular company permissions for customers and non-customers

  Company permissions for creating and editing companies are now separated into two distinct categories, **"Customers"** and **"Non-Customers"**, so you can secure financial data with more precision.

  **What changed:**

  You can now define exactly who can modify Billable Customer profiles, which prevents unauthorized changes to credit terms, billing addresses, and contacts. Your operations team can create and edit Shipper and Receiver locations as needed without exposing your customer database to risk. Aligning user permissions strictly with job functions reduces risk and strengthens your security posture.

  **Why it matters:** data integrity is critical for scalability. Separating these permissions protects your revenue cycle from accidental errors and unauthorized changes, so only the people responsible for financial data handle it.

  Who it affects: this update applies to all users, and the access each user has depends on the company permissions assigned to them. Configuring these permissions requires the **Admin** role.

  **Where to find it:** Settings then User Management then Permissions (Settings > User Management > Permissions).

  Action: review your User Management permissions and assign the **"Customers"** and **"Non-Customers"** access levels to match each user's job function.

  **Learn more:** [Overview of user permissions](/en/help/administration/overview-of-user-permissions)

  ## Custom References for drivers

  Custom References now supports unique fields for Drivers, so your team can define, manage, and report on the exact operational and compliance data your business requires. This centralizes details such as driver certification status, equipment maintenance intervals, and HR or ownership codes in one system instead of scattered notes and siloed spreadsheets.

  **What changed:**

  You can create up to 20 custom fields to track the driver data that is important to your business. You can search, filter, and sort by custom references directly on the Driver lists, so your team can quickly access information without reconciling multiple data sources.

  Use case example: a fleet manager needs to ensure only drivers with up-to-date certifications are assigned to loads requiring specific endorsements. With Custom References, the manager can filter driver records by certification status, verify compliance quickly, and generate reports for audits. This removes manual checks and supports compliance readiness at scale.

  **Who it affects:** this update applies to all users who work with driver records and reporting. Creating and configuring custom references requires the **Admin** role.

  **Where to find it:** Settings then Custom References (**Settings > Custom References**).

  <Note>
    <img alt="Image showing navigation to the custom references page in Alvys" />

    *Image showing navigation to the custom references page in Alvys*
  </Note>

  **Action:** create the driver custom fields your business needs, then use them to filter and report on driver records.

  **Learn more:** [How to Set Up Custom References in Alvys](/en/help/administration/how-to-set-up-custom-references-in-alvys)
</Update>


# July 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/july-2026-releases

July 2026 brought customer credit limits on the Load Details page, a rebuilt Load Templates page, a dedicated Users page with admin MFA reset, and a hard block on assigning unvetted carriers.

<Note>
  July 2026 added customer credit visibility where dispatchers already work, rebuilt Load Templates and User Management, gave you a way to stop unvetted carriers being assigned to loads, and shipped a large batch of requested settlement and dispatch features.
</Note>

## Overview

July's changes cluster around control and visibility. You can now see a customer's credit exposure on the load you are working, stop an unvetted carrier being assigned at all, and manage users from a page of their own. Load Templates was rebuilt with saved views and a smoother path from template to loads, and more than twenty requested features landed in settlements, dispatch, and integrations.

<Update label="July 28, 2026" description="More than twenty requested features shipped across driver settlements, dispatch, invoicing and EDI.">
  **Driver pay & settlements**

  * Organise statements by driver name for cleaner payroll.
  * Broker, customer, and order numbers now appear on driver pay stubs and statements, so drivers can match pay to the right load.
  * Trailer and container numbers show on driver pay statements — helpful for drayage and drop-and-hook work.
  * TONU loads show "TONU" in the description with a clear origin and destination, and reflect origin-to-origin with zero loaded miles.
  * Per Day and Per Diem Per Day items roll up into a single line item instead of one per day.
  * New escrow account types on driver profiles: business escrow, performance bond, and lease depreciation.
  * Tolls appear in the approved items panel on owner-operator statements.
  * A new statement template editor, so you can configure and preview your statement layout side by side.
  * Carrier Settlements is hidden for single-subsidiary carriers, keeping navigation clean.
  * Carrier invoice upload prompts for an invoice number per document and shows which document you are working on.
  * Push a driver or carrier bill even when the accounting sync step was skipped, without reverting to draft.

  **Loads & dispatch**

  * Dispatch Planner rows show the full first-come-first-served pickup and delivery window without opening the trip.
  * Set the Drivers view as your default in Dispatch Planner.
  * Add, edit, or clear the dispatcher directly on trips from the planner.
  * Filter **Available In** by several states at once for regional planning.
  * Stop notes save inline as you edit, with no extra pop-up.

  **Invoicing & accounting**

  * A load's Office or Department carries onto the NetSuite vendor bill for carrier settlements, so costs can be segmented by office.

  **Integrations & EDI**

  * Pepsi EDI tenders map the Order # to the PO # field.
  * A new per-customer control chooses which load reference is sent to tracking providers as the "BOL" match key.

  Requested Public API changes shipped as well, and are written up for developers in the [Alvys changelog](/en/api/changelog).
</Update>

<Update label="July 14, 2026" description="Load Templates is rebuilt with saved views, editing inside the full load creation flow, and bulk creation from a template.">
  ## Load Templates, rebuilt

  The Load Templates page has been rebuilt and is now the only version — the older page is retired. It ships to every account at no extra cost.

  **What this includes:**

  * **Saved views.** Save, name, and recall a filtered and sorted arrangement of the grid, the same way you do on other Alvys grids.
  * **A cleaner default layout.** Columns start as Alert/Issue indicator, Customer, Template Name, Lane, Contract, and Equipment, with more available from the column management sidebar.
  * **Editing inside the load creation flow.** Opening a template for editing now uses the full load creation experience instead of a cramped modal, so you can see and change more.
  * **"Create load & make template."** Build a load and save it as a reusable template in one step.
  * **Bulk creation from a template.** Say how many loads you want and set their dates, and you land on the load board filtered to the loads you just created.

  Templates for multi-trip and split loads are not part of this release, and neither is automated recurring load creation from a template. Both are being looked at separately.

  **Learn more:** [How to Create and Use Load Templates](/en/help/loads-trips/how-to-create-and-use-load-templates)
</Update>

<Update label="July 13, 2026" description="A Match vendors by name checkbox on the Business Central integration lets you match carriers by MC number only.">
  ## Control how carriers are matched in Business Central

  If two carriers share a name but have different MC numbers, a bill could post under the wrong vendor. A new **Match vendors by name** checkbox on the Business Central integration settings puts that under your control.

  It is on by default, matching carriers by MC number and then by name exactly as before, so nothing changes unless you turn it off. Switch it off and Alvys matches by MC number only — when there is no MC-number match it creates a new vendor rather than guessing by name, which keeps same-named carriers distinct.

  One caution: if you are a carrier subsidiary that exports driver statements, leave this setting **on**. Drivers do not have MC numbers and are matched by name, so turning it off can stop Alvys finding the right driver in Business Central. The setting exists only on the Business Central integration.

  **Learn more:** [Business Central: Connect & configure](/en/help/integrations/how-to-connect-business-central-to-alvys-and-configure-settings)
</Update>

<Update label="July 10, 2026" description="A customer's credit limit and outstanding balance now appear on the customer profile and read-only on Load Details.">
  ## See a customer's credit limit and outstanding balance where you work

  You can now record an optional credit limit on a customer and see their outstanding balance at the moment it matters. The credit limit field and a balance visualisation sit in the credit section of the customer profile, and the same visualisation appears — read-only — directly under the customer name on the **Load Details** page, so a dispatcher sees credit standing without navigating away.

  The outstanding balance reflects real exposure rather than only what has been billed: overdue unpaid invoices, plus the current revenue on open, in-transit, and delivered loads that have not been invoiced yet. It recalculates as things change, and once a load is invoiced it is tracked through that invoice instead, so nothing is counted twice.

  **Worth knowing:**

  * This release is visibility only. Alvys does not block, warn, or require approval based on the limit, and there are no notifications when a customer approaches or passes it.
  * A credit limit is optional. Without one you still see the outstanding balance as a standalone figure — you just do not get the progress bar and percentage. A limit of \$0 is treated as unconfigured — Alvys shows the standalone balance with no bar until you enter a positive dollar amount.
  * Who can view credit information and who can change it are controlled by permissions your admin assigns — see the article below.
  * **Credit Limit** and **Outstanding Balance** are also available as fields in Custom Reporting, so you can look at credit standing across your whole customer base.

  **Learn more:** [Customer Credit Limits Explained](/en/help/accounting-settlements/customer-credit-limits-explained)
</Update>

<Update label="July 8, 2026" description="User management moves to its own Settings → Users page, and a Partner Admin can reset a user's MFA from Edit User.">
  ## A dedicated Users page, and admin-assisted MFA reset

  User management has moved out of Company Profile onto its own **Settings → Users** page, rebuilt on the same modern grid used elsewhere in Alvys. The list is searchable and sortable, filters by subsidiary, and lets you set a user's reporting role inline. Adding and editing users keeps everything you had before — identity details, the role and permission grid, multi-tenant access, e-check limits, avatar, subsidiary emails, and deleting a user.

  One capability is genuinely new: a Partner Admin can now reset a user's multi-factor authentication from the Edit User screen. That clears the user's enrolled authenticators so they enrol again at their next sign-in — useful when someone has lost the device holding their authenticator app. A Partner Admin cannot reset another Partner Admin, and those requests still go to Support.

  My Profile has moved to the same new stack, with personal details, integrations, subsidiary emails, favourites and quick actions, notification and email preferences, locale, tenant switching, and self-service password change all unchanged.

  This is available to every account at no extra cost, and rolls out progressively — if you still see the older screens, they are the same pages and your access is unaffected.

  **Learn more:** [How to Add and Manage Users in Alvys](/en/help/administration/how-to-add-and-manage-users-in-alvys) · [My Profile in Alvys](/en/help/getting-started/my-profile-in-alvys)
</Update>

<Update label="July 1, 2026" description="An admin can turn the unvetted-carrier warning into a hard block, choosing exactly which carrier statuses cannot be assigned.">
  ## Block unvetted carriers from being assigned to loads

  Documenting a carrier or adding a carrier quote records that carrier as **pending** — captured, but not onboarded. Previously, assigning a pending carrier only raised a warning you could click past. You can now turn that warning into a hard block.

  A new company setting lets an admin choose exactly which carrier statuses are blocked from being assigned to a load. You can pick any combination of **Pending**, **Do Not Load**, **Expired Insurance**, **Interested**, **Invited**, and **Packet Sent**. Once configured, carriers in those statuses cannot be assigned — there is no override, so a rate confirmation cannot accidentally go to the wrong carrier.

  **Worth knowing:**

  * It is off until your admin turns it on and chooses the blocked statuses, so nothing changes for you by default.
  * Live loads are not disrupted. If a carrier's status changes after they are already assigned and moving — insurance lapsing mid-transit, for example — dispatchers can still edit that load and will see a warning rather than being locked out, so tracking and updates keep flowing. Reassigning does require picking a carrier in an allowed status.
  * The block applies when assigning or changing a carrier on a load, and during bulk import.

  **Learn more:** [How to Block Unvetted Carriers from Load Assignment](/en/help/loads-trips/how-to-block-unvetted-carriers-from-load-assignment)
</Update>

<Update label="July 2026" description="Fixes from across the month in settlements, invoicing and accounting, loads and dispatch, carriers, EDI, fuel, reporting and access.">
  Fixes from across the month, grouped by where you will notice them.

  **Billing & settlements**

  * **Select All** on driver statements selects every statement shown when emailing, and sharing a statement sends only the pay period you selected.
  * Recipient details fill in properly when sharing: the truck statement share modal pre-fills the owner-operator and statement details, and the driver email populates in the **To** field even for owners who do not drive.
  * Adding or removing a driver rate no longer makes the other rate disappear until you refresh, you can edit or exclude a second rate after a partial payment, and you can remove excluded settlement rates even when an item shows as partially paid.
  * A per-load rate added in the money box stays put when a contractor is assigned, and Daily Pay and Daily Per Diem rates survive adding or removing a driver from a rate plan.
  * Items excluded from a settlement no longer show on the driver statement, and duplicate deductions no longer appear on their own.
  * Recurring truck and trailer deductions apply consistently on every settlement.
  * Mileage tiers in rate plans populate as correct, non-overlapping ranges; mileage-based pay shows the right miles rather than \$0; and edited load miles flow through to driver pay automatically.
  * Fuel now credits and deducts correctly on settlements.
  * Statements generate reliably instead of failing on an external accounting sync error or an unexpected fuel transaction, and reverting a statement works rather than sticking in Queued.
  * Loads in a draft statement are locked from driver-pay edits, preventing accidental changes.
  * A load marked paid in the driver money box shows as paid in carrier details.
  * Owner-operator truck settlements no longer show greyed-out Open and Drafts tabs, and the **Settle with Owner Operator** button works again.
  * Driver profile rates display correctly, you can adjust an owner's rate plan to their current rate, and YTD totals on the Driver Profile reflect the correct gross pay.
  * Search in Driver Settlements returns the right results, drivers appear in the Open tab as expected, and statement reports attribute pay to the correct driver or owner-operator.
  * Driver profiles and paystubs open and download without an error, including in the mobile app.
  * Removing a driver from a load that carries an accessorial works.
  * Settlement approval no longer gets stuck when you close the approved-items sidebar, **Unapprove all items** processes as a single action, and empty states and rate-plan editing screens display cleanly.
  * Statement totals no longer include trip value from accessorial-only loads or loads already paid in an earlier period.
  * TONU loads show the correct delivery date and no longer apply per-extra-stop charges to driver pay.
  * External drivers no longer appear selectable in the Custom pay period list, and pay period filters list in date order.
  * Escrow running balances stay accurate while you scroll transaction history.
  * The Paylocity export includes all deduction codes and totals line haul and per diem by driver.
  * Statement emails send from the correct no-reply sender rather than a user's name.
  * Carrier settlements accept a second payment of the same amount, can be resynced when a sync sticks, show uploaded files without a hard refresh, and the Carrier Payments view now shows paid date, check number, and payment method. Factoring loads sent to TAFS process and batch correctly.
  * Factoring uploads no longer stick after a large batch fails, and invoices sent to Triumph over SFTP connect reliably.
  * The money box is visible again for the biller role.

  **Invoicing, accounting & integrations**

  * Internal notes no longer appear on customer invoices, and load notes on the Released/Invoicing screen sort newest first.
  * Invoice generation no longer throws a concurrency error, works when a carrier invoice is attached to the trip, and completes without unexpected errors.
  * A Bill of Lading is no longer required to invoice TONU loads.
  * Trips no longer flip from Invoiced back to Released when an accounting sync hits an error.
  * Bank and asset account pickers are separate, so NetSuite and Business Central bank accounts appear in account mappings, and QuickBooks Online bank accounts appear when configuring customer payment export.
  * The correct **Pay To** is pushed from Alvys into Business Central, and the sync no longer creates duplicate factoring companies.
  * Customer payments applied in NetSuite flow back into Alvys, loads that fail to reach NetSuite surface in the Error Transaction report, and customer invoices export correctly even when a company name exists as both a customer and a carrier.
  * Sage: driver statements stay in sync, bills no longer stick in an error state after manual invoice changes, carrier invoice sync problems surface in the error transaction list instead of failing silently, vendor creation works when a contact of the same name exists, class dimension mappings display after a rename, and fuel and toll exports map truck, class, and related dimensions.
  * Carrier settlement Remit-To details sync to QuickBooks, and the QuickBooks link in onboarding opens the right page.
  * The system prevents creating a duplicate fuel card with the same name and provider.
  * Triumph trip-sync is more reliable, so trip updates are no longer occasionally dropped.

  **Loads & dispatch**

  * You can bulk dispatch trips directly to a driver in the Dispatch Planner without hitting an error.
  * You can resize and minimise columns on the Load Board and other tables.
  * Dispatch Planner no longer shows a stale **Available in** location after a driver is removed, and the **Available In** and **Available At** columns filter and sort correctly, including by date.
  * Load templates behave properly: you can create a load from a template with a pickup date in the past, edit the stop type on an existing template and on stops you add, see reefer temperature fields, and pick from only active location profiles.
  * Saving a note on a load no longer throws an "Access Denied" error or closes the load.
  * Adding and saving a new contact from the load page saves reliably.
  * Rate confirmation handling is more accurate: uploads read the correct year on tender dates, extraction captures the pickup company name and PO reference, and uploads during load creation fail far less often.
  * Cloned loads carry over their charges, so customer revenue is preserved.
  * You can create companies that share a name but have different addresses.
  * Trailer equipment type is retained after a load is split, actions on split trips no longer bounce you back to the main load, and carrier rates on split loads can be edited in the interface.
  * Deleted loads no longer linger on the load board.
  * The driver list keeps your sort and filter selections when you preview a load.
  * Stop notes copied from a company come through as clean text, copy correctly when you change a stop's company, clone a load, or use a template, and long internal notes are fully viewable.
  * Customer contracts pull in consistently on EDI loads, and a rare tender-conflict issue that could leave a duplicate tender on the board is resolved.
  * Arrival and departure validation and provider-form submission errors are fixed.
  * Contracted lanes display consistently on the board and within the lane.
  * Documents upload to Open loads again, and long PO numbers no longer overlap the side panel.
  * Creating a location no longer requires selecting an Office, and Operations reports respect office-based visibility.
  * Stop instructions on a load are editable again.
  * Switching a driver between internal and external updates correctly, and tanker endorsements are recognised so qualified drivers are no longer blocked from assignment.
  * Carrier rate confirmations generate and send without errors.
  * The cancel-subscription button appears only for accounts eligible to use it.

  **Carriers & compliance**

  * Carrier details sync from FMCSA when you search by MC or DOT number.
  * The carrier setup packet works properly when carriers fill it out on a phone.
  * Carriers with expired insurance can no longer be assigned by users without override permission, and insurance expiration dates sync correctly from Highway so valid carriers are not wrongly flagged.
  * Saving an RMIS carrier-compliance integration completes successfully.

  **Driver messaging**

  * Driver chat campaign registrations now submit the required privacy policy and terms links, resolving several rejected campaigns.

  **Integrations, EDI & tracking**

  * EDI status updates that had stopped flowing for certain connections are restored, and the Auto-Updates option is back on attached EDI loads.
  * EDI tenders no longer add an equipment type or trailer length the partner did not send.
  * Tender accessorials map to load references even when qualifiers repeat, and 210 invoices include the street-address segment.
  * Trucker Tools tracking dates no longer revert to a prior year, FourKites matches on the correct order number, and Home Depot EDI invoices process correctly.
  * The public load tracking page returns load details for valid orders.
  * Relay and handoff stops are no longer shared with customers over visibility feeds, so customers see only the stops that concern them.
  * The Samsara Proof of Delivery field can now be mapped.
  * DAT improvements across the board: loads post reliably, authentication failures are resolved, saved credentials persist after a refresh, and posting to previously failing destinations works.
  * The Asset Map reflects current trip assignments instead of old ones, and truck locations update correctly from Verizon Connect.
  * Saved filters on Truck, Driver, and Trailer list views persist when you switch pages, view changes on Assignment Preferences save, and truck and trailer reference dates display on the correct day.

  **Fuel**

  * Fuel card cash advances export to Paylocity as ADV rather than FUEL, transactions map to the correct truck and card, Love's fuel uses the correct discount per unit, and EFS eCheck and fuel login connects reliably.
  * Fuel and toll report exports include only the columns you selected, totals calculate automatically, CSV import issues are fixed, and the fuel report returns accurate results when filtering by transaction date range.
  * The Fuel module shows the correct subsidiary, non-admin users can reach fuel import again, and Partner Admins can delete fuel transactions.

  **Reporting**

  * Cancelled loads are excluded from report exports and revenue totals, and custom reporting dashboard totals no longer undercount.
  * Partner Admins can see invoiced loads in the Custom Loads Report.
  * Gross margin displays even when the value is \$0, the Detailed Financial Report shows correct fuel totals, and the Financial Report calculates trip margin correctly for loads with driver accessorials.
  * The Aging Report's invoicing-method filter works again, and the aging invoices report no longer includes loads already paid in full.
  * The Statement List Report displays truck numbers.
  * The custom report builder no longer shows duplicate Load ID and Trip ID fields, empty cells show a dash instead of a literal "(empty value)", the Late Trips view offers proper date-range options, and the Load Status filter clears its search text after you pick a status.

  **Safety**

  * Safety accident records save correctly when you set Date Reported or Date Completed, and deleting a safety report updates the screen immediately.

  **Companies, contacts & access**

  * Customer phone numbers entered with a leading "1" keep all their digits.
  * Contacts with a missing identifier can be deleted, and Admins can edit the Company Number field on customer profiles.
  * Partner Admins can access customer profiles, and the user details page no longer crashes when a user's tenant record is missing permissions.
  * A permission or role change no longer forces an unexpected sign-out, and a denied response during an active session refreshes your session instead of logging you out.
  * Customer, Location, and Other records open in a new tab again, and company-grid filters persist after a refresh.
  * Broker and customer credit checks return accurate statuses instead of showing everything as declined.
</Update>


# June 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/june-2026-releases

June 2026 shipped 35 requested features, a rebuilt Plan & Billing page, an optional sequential-dispatching rule, and moved Orbcomm ELD tracking to a new connection.

<Note>
  June 2026 was a heavy month for requested features — 35 of them shipped — alongside a rebuilt Plan & Billing page, a new optional rule that keeps a driver on one active trip at a time, and a required move for Orbcomm ELD customers.
</Note>

## Overview

June's theme was your feature requests: 35 of them shipped, concentrated in driver settlements, invoicing, and mileage and routing. The Plan & Billing page was rebuilt so you can manage your payment method and plan yourself, a new opt-in setting stops a driver being dispatched a second load before the first is delivered, and customers using Orbcomm ELD tracking needed to reconnect through a new integration.

<Update label="June 30, 2026" description="The Plan & Billing page is rebuilt: manage your own payment method through the Stripe portal, upgrade or cancel a Foundations plan, and read a rolling 12-month loads chart.">
  * The **Plan & Billing** page has been rebuilt. Your current plan, add-ons, and billing cadence now appear on the page, with a banner showing time remaining if you are in a trial and a resubscribe option if a subscription was cancelled.
  * You can update your payment method yourself. **Manage** on the Payment Method card opens the Stripe Customer Portal, and credit or debit card, ACH bank transfer, and Stripe Link are all supported. If a payment has failed, the button changes to **Update** and is highlighted.
  * If you signed up directly on the Foundations plan, you can now upgrade or cancel from the billing page without contacting your account team.
  * The loads volume chart now covers a rolling 12 months, and you can click into any billing period to see that month's load counts — useful for checking usage against what you were invoiced.
  * The estimated invoice has a cleaner layout, still itemised with subtotals and any discounts, and the page now works on smaller screens. Your last 12 months of invoices remain available as before.

  Access is unchanged: the billing page is for Admins and Partner Admins.
</Update>

<Update label="June 30, 2026" description="A new opt-in Enforce Sequential Dispatching setting stops a driver being dispatched a second trip before the first is delivered.">
  * A new opt-in setting, **Enforce Sequential Dispatching**, stops a driver being dispatched another trip while they already have one in Dispatched or In Transit status. The block lifts once that trip is Delivered. Assigning future loads for planning is deliberately unaffected — only the **Dispatch** action is gated, so you can still plan a driver's week ahead. In Dispatch Planner the Dispatch button is disabled with a tooltip explaining why. The setting is off unless your admin turns it on in tenant settings, and nothing changes for accounts that leave it off.
</Update>

<Update label="June 26, 2026" description="35 requested features shipped, concentrated in driver settlements, invoicing, and mileage and routing.">
  Your feature requests drive the roadmap, and June shipped a large batch of them.

  **Driver pay & settlements**

  * Filter Driver Settlements by truck.
  * Show or hide the trip value on driver statements with a toggle.
  * Zero-dollar driver pay now appears in settlements, so the \$1 workaround is no longer needed.
  * Empty and loaded miles now show on percentage-based pay statements.
  * Search driver statements by load number, and load numbers now appear on settlement line items for easier reconciliation.
  * More columns available in the Driver Settlements module.
  * A merchant column on fuel transactions in open and draft paystubs.
  * Set different driver rates depending on whether a load is for a Customer or a Broker/3PL.
  * Carrier settlements sync payments from your ERP, including a new **Partially Paid** status.

  **Invoicing & billing**

  * The invoice bulk-selection sidebar now shows total revenue and the number of orders selected, updating as you go.
  * Add custom load references — a Route ID, for example — as a filterable column on the invoice page.
  * Right-click to view a load's documents straight from the invoicing board.
  * AutoMerge now considers all like documents when generating an invoice, not just the most recent one.
  * Set a custom date offset for fuel surcharge calculations.
  * Trip value can now be shown on carrier rate confirmations.

  **Dispatch & planning**

  * Block planning for drivers whose credentials are expired or restricted, so non-compliant assignments cannot be made.

  **Mileage, routing & mapping**

  * Generate customer quotes from calculated mileage using your PC\*MILER profile.
  * Look up multi-stop routes with per-leg and total miles, plotted on a map.
  * Support for Rand McNally v19 mileage profiles.
  * The Asset Map now shows each asset's direction of travel, plus new event and weather overlays.

  **Loads, search & imports**

  * Search for a company by its code when building a load.
  * Driver import accepts longer license numbers, for states such as New Jersey and Wisconsin.

  **Integrations & accounting**

  * A new Sage accounting integration.
  * Export all fuel transactions to accounting, with options to include deducted fuel and tolls.
  * A Samsara workflow integration for driver mobile operations.

  Requested changes to the Public API shipped this month too. Those are written up for developers in the [Alvys changelog](/en/api/changelog).
</Update>

<Update label="June 18, 2026" description="Orbcomm retired CargoWatch, so Orbcomm ELD tracking moves to the newer Orbcomm Platform connection and affected accounts must reconnect.">
  ## Orbcomm ELD tracking moves to the Orbcomm Platform connection

  Orbcomm retired its older CargoWatch connection, so Alvys has retired the matching **Orbcomm** integration and moved to the newer **Orbcomm Platform** integration. If your Orbcomm tracking had gone quiet, this is why — the old connection had stopped returning data reliably before it was switched off.

  Reconnecting takes a couple of minutes: go to **Settings → Integrations → Orbcomm**, choose the **Orbcomm Platform** connection, and enter your Orbcomm credentials. ELD and location tracking resume syncing automatically once it is connected. Accounts already on the Orbcomm Platform integration were not affected and needed to do nothing.

  Only accounts using the older connection were affected, and those were contacted directly by email rather than through a general announcement.

  **Learn more:** [Connecting Orbcomm Platform to Alvys](/en/help/integrations/connecting-orbcomm-platform-to-alvys)
</Update>

<Update label="June 2026" description="Fixes from across the month in billing and settlements, invoicing and accounting, loads and dispatch, reporting, tracking, EDI and Alvys Intelligence.">
  Fixes from across the month, grouped by where you will notice them.

  **Billing & settlements**

  * Users with the Biller role can see the Money Box again.
  * Carrier Settlement statements update in real time, with no manual page refresh to see the latest document status.
  * Driver statement summaries no longer inflate mileage and trip totals when accessorials are added to loads paid in an earlier period, and accessorial-only loads no longer add trip value to statement totals.
  * Previously paid loads and deductions no longer reappear under **Driver Settlements → Open**, which removes a double-pay risk.
  * Date filters on Driver Settlements return every matching load in the range, custom reference column choices stay put, and the pay period driver picker scrolls through all drivers without losing your selection when you edit a pay period.
  * The Paylocity payroll export includes all deduction codes that were previously left off.
  * The Driver column is back in the OOPs Trips section, and the driver payment column matches the trip line items.
  * Negative amounts can be entered in fuel discount fields again.
  * Old credits, deductions, and reimbursements with an empty remaining balance can be approved.
  * TONU loads show the correct empty lane.
  * The **+ New Pay Period** option is available again for company drivers.
  * Driver accessorials no longer appear on brokerage trips, matching previous behaviour.
  * Rate Plan contract search finds contracts whose names contain punctuation.
  * Carrier settlement notification emails render with the correct layout, and the "View guide" tooltip on driver settlement deductions stays open long enough to read.
  * TriumphPay audit reconciliation is fixed, so trips no longer stick in "Ready to Audit" and payment batch totals are accurate.

  **Invoicing, accounting & integrations**

  * Sage Intacct syncs correctly for both carrier and vendor records and customer payments, reuses an existing contact instead of failing on a duplicate, brings fuel transactions through, imports payments posted within the lookback window, and now supports driver contractor type in the export.
  * Generating an invoice no longer throws a concurrency error.
  * The Aging Report no longer shows a \$0 balance due once payments have been applied, and loads move to Completed correctly.
  * QuickBooks Online clears a duplicate-name validation error once the name is corrected, and QuickBooks carrier payments mark the trip Completed automatically.
  * The Apex factoring connection is fixed and its token no longer expires each day.
  * Carrier syncs with Highway complete reliably.
  * Trip status updates correctly after a carrier invoice is uploaded.

  **Loads & dispatch**

  * The tender board no longer refreshes every few seconds, so you have time to accept and price a load.
  * Dispatch Planner shows pickup and delivery locations on bulk-imported loads, renders saved view columns consistently, and supports state filtering.
  * Driver Planner shows the **Available in** value consistently for dispatched drivers.
  * Customer autocomplete offers only active accounts.
  * The Request Detention email pre-fills driver check-in and check-out times, total time, and amount.
  * Notes added to shipper and receiver profiles appear across all related loads.
  * Uploading a customer spreadsheet creates the profiles as expected.
  * The Loads page layout stays put when you switch to Trips and back.
  * Loads appear in Samsara after a trip is re-dispatched to a different driver.
  * The customer sales agent field is back on load creation, and the Assignment Preferences page no longer crashes.
  * The Trucks list labels Owner-Operator trucks correctly instead of showing them as Company Owned.
  * The load board shows correct, automatic check calls, and a document name can be reused after the document that had it was deleted.

  **Load posting & marketplace**

  * Posting loads to DAT works reliably again, and connecting a user to the DAT Marketplace succeeds instead of reporting an invalid account.

  **Reporting & imports**

  * Including the Carrier Invoice Number column in a Load custom report no longer corrupts the Excel or CSV export.
  * Report filters work across both pre-built and custom MDN reports, and On-Time Arrivals report times match the times on the loads.
  * Company Name is no longer wrongly flagged as empty when importing Locations or Other Companies.
  * Fuel and toll imports are more forgiving: TCS CSV files upload correctly, Prepass toll uploads report accurate messages instead of false errors, uploads no longer fail on card number or transaction ID errors, decimals work in manual fuel entry, and non-admin users can reach fuel import and update toll transactions again.

  **Asset map & tracking**

  * Inactive assets no longer show as active on the map and can be removed.
  * The trip sidebar shows the correct last-known location source.

  **Maintenance**

  * On the Maintenance board you can pick a date again without being forced to enter an exact time.

  **EDI & tendering**

  * Inbound EDI tenders from certain FTP servers ingest correctly, so status updates flow through without interruption.

  **Alvys Intelligence**

  * The side menu no longer collapses into an unusable state, and your selected model is respected instead of reverting to Auto.
  * The chat box grows as you type a longer prompt, and the Stop button works while a response is streaming.
</Update>


# March 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/march-2026-releases

March 2026 ships Dispatch Planner V2 filtering and notes, automatic driver availability, redesigned Trucks and Trailers tables, and tender webhooks.

<Note>
  March 2026 brought major Dispatch Planner V2 improvements, automatic driver availability calculation, a unified redesign of multiple table pages, and real-time webhooks for tender events.
</Note>

## Overview

This release recap covers Dispatch Planner V2 enhancements (filtering, notes, trip sidebar, references, and bugfixes), smarter automatic driver availability, the rollout of a unified table-page design across Trucks, Trailers, Accounting Error Transactions, and E-Checks, and new webhooks for tender lifecycle events.

<Update label="March 30, 2026" description="Inline column filtering replaces the filter bar, notes move into the Planner sidebars, and the trip sidebar adds ETA, last ping and HOS-aware estimates.">
  ## 82 plus Dispatch Planner improvements shipped in 2026

  Dispatch Planner has improved substantially over the prior two months, with more than 82 improvements shipped so far in 2026. The sections below cover the highlights. The Planner is faster, more reliable, and easier to use day-to-day, and the filtering overhaul alone changes how dispatchers interact with the product. More is in flight, including a timeline view, expanded filters for the Trips and Drivers tables, and continued saved views enhancements. You can start using Dispatch Planner from the Planner area of Alvys.

  ## Completely rebuilt inline column filtering

  The old filter bar has been removed. Planner now uses modern, inline column filters, the same style of filtering people already know from spreadsheets. It is faster, more intuitive, and consistent across every column type.

  **What this includes:**

  * Shareable filter URLs. Bookmark or send a filtered view to a teammate and it loads exactly as you left it.
  * Better text search with more flexible operators and smarter matching.
  * Consistent behavior everywhere. Text, number, date, and set filters all behave the same way.
  * Auto-filtering by driver team. Equipment types in the Trips table now auto-filter when you switch teams.

  Additional filter operators and filters for all remaining columns across the Planner are coming soon.

  ## Notes inside the Planner sidebars

  Dispatchers can now create, edit, and manage notes directly inside the Planner sidebars, without leaving the workflow.

  **What this includes:**

  * Driver notes. A dedicated Notes tab on the driver sidebar, with a quick-launch icon on every driver row.
  * Trip and load notes. The same treatment on the trip sidebar.
  * Notes grouped by time period (Today, Yesterday, This Week, and so on), so recent context is always at the top.

  The old popup modal has been removed. Everything now lives inline.

  ## Smarter trip sidebar

  The trip sidebar now surfaces the information dispatchers need most without digging for it.

  **What this includes:**

  * ETA to next stop, displayed right on the upcoming stop card.
  * Last ping at a glance, in a clean "12 min ago" format that shows just the source (such as Samsara or Driver App).
  * HOS-aware ETAs. ETAs now factor in hours-of-service data via Trimble, with smart fallbacks when HOS data is not available. This is an Alvys Intelligence feature.

  ## Cleaner default grid layout

  Every user now starts with a clean, standardized grid layout.

  ## Load and trip custom references visibility

  Both load custom references and trip custom references are now fully visible in the Planner grid. Customers who tag loads or trips with their own reference codes (such as PO numbers, BOLs, and internal IDs) can see those fields as columns and can filter and sort by them, all without leaving the Planner.

  **Learn more:** [How to Set Up Custom References in Alvys](/en/help/administration/how-to-set-up-custom-references-in-alvys)

  ## New columns and visual improvements

  What this includes:

  * New Last Ping and Number of Stops columns.
  * Tighter row density, putting more data on screen with reduced row heights.
  * Colors and emojis on custom references. You can visually tag trip and load custom references with colors and emojis for at-a-glance organization.

  ## Over 20 Dispatch Planner bug-fixes

  More than 20 bugs were fixed, including wrong trailers, missing driver messages, broken temperature displays, brokerage trips leaking in, and incorrect filter results. The Planner is meaningfully more reliable than it was two months ago.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="March 30, 2026" description="Trucks, Trailers, Accounting Error Transactions and E-Checks move to one unified grid design with shared filters, sorting and actions.">
  ## Unified grid design for Trucks, Trailers, Accounting Error Transactions, and E-Checks

  Table pages across Alvys are transitioning to a unified design. Every table will use the same filters, sorting, column layouts, and actions, which reduces the time your team spends re-learning controls as they move between modules.

  **What is new:**

  * Consistent grid experience. Trucks, Trailers, Accounting Error Transactions, and E-Checks now use the same grid layout, so your team uses the same filters, sorting, and actions everywhere and there is less re-learning when moving between modules.
  * Faster performance. The grids are rebuilt with modern front-end architecture for faster load times and smoother interactions.
  * Faster onboarding. New hires learn one grid pattern and apply it across the entire system, and experienced users move between modules without adjusting.

  You can find the new experience on the Trucks, Trailers, Accounting Error Transactions, and E-Checks pages.

  ## Table page rollout schedule

  Live as of March 30: Trucks, Trailers, Accounting Error Transactions, and E-Checks.

  Coming in April (in development): Safety Accidents, Safety Claims, Safety Roadside Inspections, Maintenance Records, Carriers, and Companies.

  No action is required. Updates roll out automatically and your data stays exactly where it is. If your account has early access enabled, you can check the Trucks and Trailers grids to see the new experience today.
</Update>

<Update label="March 27, 2026" description="Driver availability is calculated automatically from Minimum Available Duration and Average Dwell Time, with four new columns in the Drivers table.">
  ## Automatic driver availability calculation

  Driver availability is now calculated automatically, removing the need for manual PTA tracking and giving planning teams data they can trust. Availability is calculated using two configurable parameters, Minimum Available Duration and Average Dwell Time. Instead of relying on appointment window end times, availability now factors in realistic turnaround, so you see when a driver is actually free rather than only when a load delivers.

  This addressed the top gap that prevented operations from trusting Planner availability data. Local operations need one-hour windows, regional needs 12 hours, and long-haul needs days, so each operation can now define what "available" actually means for them.

  You can find these changes in the Drivers table of Dispatch Planner.

  ## New driver availability columns

  New columns in the Drivers table:

  * Available For, showing how long the driver is available (for example, 14h 30m, or infinity if there is no next commitment).
  * Next Planned At, showing when their next commitment starts.
  * Next Planned In, showing where the next commitment is.
  * Available In (formerly Final Stop), showing where the driver becomes available, synced with the new calculation.

  ## How to configure driver availability settings?

  Settings are available at three levels: Alvys defaults, tenant-level overrides, and fleet-level overrides. Your admin can adjust Minimum Available Duration and Average Dwell Time under Dispatch Planner Settings. Sensible defaults are set, but you will get the most value by tuning these to match how your operation actually runs.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>

<Update label="March 2, 2026" description="Alvys pushes tender lifecycle events to middleware and ERPs in real time over webhooks.">
  ## Real-time webhooks for tender lifecycle events

  With webhooks for tender events, Alvys can now push information to your external systems, such as middleware or ERPs, in real time. This keeps your data in sync whenever a tender is modified.

  **The impact:**

  * Eliminate the tender sync gap. Your internal dashboards and custom ERPs sync with Alvys in real time, so your team never works with outdated data.
  * Act on exceptions fast. Respond to tender status changes or new opportunities when they happen.

  To get started, provide your IT or development team with the setup guide so they can activate real-time tender updates for your systems via webhooks.

  **Learn more:** [Alvys changelog](/en/api/changelog)
</Update>


# May 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/may-2026-releases

May 2026 launched the new Reports and Dashboards experience, renamed Driver 1 and Driver 2 to Primary and Secondary Driver, and added a permission for viewing ACH details.

<Note>
  May 2026 brought the new Reports and Dashboards experience, clearer driver role labels across the whole application, a dedicated permission for ACH banking details, and a new Per Unit accessorial rate type.
</Note>

## Overview

May's biggest change was reporting: dashboards you can use as delivered, then filter, duplicate, and build on. Alongside it, two changes you will notice everywhere — driver roles are now labelled Primary and Secondary instead of Driver 1 and Driver 2, and ACH account and routing numbers are now masked unless a user has been granted permission to see them.

<Update label="May 29, 2026" description="Accessorials gain a Per Unit rate type for count-based charges such as extra stops billed per stop.">
  Accessorials support a new **Per Unit** rate type, joining Flat, Weight, Distance, Volume, and Time. Choose it in the accessorial type settings and the charge is the per-unit rate multiplied by the quantity entered — which is what you want for count-based charges such as extra stops billed at a rate per stop.
</Update>

<Update label="May 26, 2026" description="A View ACH Details permission masks account and routing numbers from users who have not been granted it.">
  A new **View ACH Details** permission controls who can see ACH account and routing numbers, wherever they appear — driver details, carrier payment methods, and carrier packets. Without it, the numbers stay masked. It is enabled by default for the Admin and Partner Admin roles on new users; existing users needed it granted explicitly, and full enforcement began on June 8, 2026. Admins assign it from the Permissions section of the add-user or edit-user screen.
</Update>

<Update label="May 23, 2026" description="Driver 1 and Driver 2 are relabelled Primary Driver and Secondary Driver everywhere in the app; customer-facing documents are unchanged.">
  ## Driver 1 and Driver 2 are now Primary Driver and Secondary Driver

  Driver role labels are consistent across Alvys. Wherever you previously saw **Driver 1** you now see **Primary Driver**, and **Driver 2** is now **Secondary Driver** — the lead driver responsible for the trip, and the co-driver supporting it. The workflow is unchanged; only the wording is clearer.

  **Where you will see it:**

  * Load boards and trip details, including the column headers you sort and filter by.
  * Asset assignment forms, and the error message when the same driver is picked twice.
  * Driver payment screens and rate management, so it is obvious which role a rate or payment belongs to.
  * Dispatch Planner grid columns and menus, and driver profile pages.
  * Driver and load filters, endorsements, event logs, and change history.

  Customer-facing documents are deliberately untouched: invoices, exported reports, and rate confirmations still read "Driver 1" and "Driver 2", so nothing your customers receive changes format.

  **Learn more:** [How to Set Up Assignment Preferences for Drivers](/en/help/assets-fleet/how-to-set-up-assignment-preferences-for-drivers)
</Update>

<Update label="May 1, 2026" description="Reports and Dashboards ships inside Alvys with an Operational and a Financial dashboard ready to use, plus filtering, drill-down and duplication.">
  ## Reports and Dashboards, built into Alvys

  Reporting now lives inside Alvys. Open **Reports** from the left navigation and select **Custom Reports** to find two dashboards ready to use on day one: an **Operational Dashboard** covering execution health, on-time performance, load flow and throughput, utilization, and an exceptions and risk panel; and a **Financial Dashboard** covering financial health, revenue and margin, lane and load profitability, customer profitability ranking, and financial exposure.

  The delivered dashboards are a starting point rather than the whole feature. You can filter them down to a time period, customer, lane, driver, or business segment, drill into any KPI that needs explaining, duplicate a dashboard when your team needs its own variation, and build your own visualizations and metrics for questions the defaults do not answer.

  **Worth knowing:**

  * The delivered dashboards are visible to higher-level roles by default. They are not automatically shared with everyone — an admin shares them with the users or teams who need them.
  * You can schedule a dashboard to arrive on a cadence, or set an alert on it, rather than remembering to check.
  * Reporting is a paid add-on and became available to subscribing accounts on May 1.

  **Learn more:** [Getting Started with Reports and Dashboards](/en/reporting/get-started/getting-started)
</Update>

## Public API

Integrator-facing webhook and endpoint changes also shipped in May. Those are documented for developers in the [Alvys changelog](/en/api/changelog) rather than here.


# November 2025 Releases
Source: https://docs.alvys.com/en/help/what-s-new/november-2025-releases

November 2025 introduces Custom Trip References for trip-level operational data and Dispatch Planner sidebars for faster driver and trip assignments.

<Note>
  In November 2025 Alvys shipped Custom Trip References for tracking and reporting on the trip-level data your business cares about, and a Dispatch Planner sidebars update that makes driver and trip assignment decisions faster.
</Note>

## Overview

This release note covers the two features that went live in November 2025: Custom Trip References (Nov 26) and the Dispatch Planner Sidebars update (Nov 19).

<Update label="November 26, 2025" description="Custom Trip References let you define up to 20 trip-level data fields and report on them from Load Details, the Trips Board and Custom Reports.">
  ## Custom Trip References for tracking trip-level operational data

  Track the trip-level operational details that matter to your unique business. With Custom Trip References, your team can define, manage, and report on operational data exactly as you need it, with no more disparate spreadsheets and notes kept outside of your TMS.

  <Note>
    <img alt="Screenshot of a custom trip reference field on a trip" />

    *Screenshot of a custom trip reference field on a trip*
  </Note>

  **What is new:**

  **Track and report on the trip-level data you need:** Define the data fields your team actually needs with customizable trip references. You can create up to 20 custom trip data references and configure them to appear where your workflows need them.

  **Find trip-level data fast:** Quickly find trip-level data on Load Details, the Trips Board, and Custom Reports.

  **Cleaner operations and reporting:** Replace scattered tracking methods with structured, searchable data. Filter, sort, and report on trip-level details in real time. Improve accuracy with consistent, visible data, so there is no more hunting through disparate notes or spreadsheets to find what you need.

  **Available now in:** Load Details, Trips Board, Custom Reports, the Mobile App for Drivers, Dispatch Planner v2, and Documents (rate cons, BOLs, and trip manifests).

  **Action needed:** Administrator access is required to create and configure references. To set them up, follow the steps in the Setting up custom references help article.

  **Learn more:** [How to Set Up Custom References in Alvys](/en/help/administration/how-to-set-up-custom-references-in-alvys)
</Update>

<Update label="November 19, 2025" description="Dispatch Planner rows open a sidebar in one click, defaulting drivers to the activity view so availability reads at a glance.">
  ## Dispatch Planner sidebars for faster assignment decisions

  Make smarter assignment decisions with one click using the new Dispatch Planner sidebars. Managing dispatch just got simpler: with the new sidebar you can make faster, smarter assignment decisions without leaving the Dispatch Planner workflow.

  **What is new:**

  **One-click access:** Click any trip or driver row to instantly open sidebars, with no more hunting for buttons.

  **Activity first:** Driver sidebars now default to the activity view, so you see availability at a glance.

  **Smoother workflow:** Find drivers from a trip, or trips from a driver, without leaving the Dispatch Planner workflow.

  See how it works in the demo video.

  <iframe title="YouTube video" />

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)
</Update>


# October 2025 Releases
Source: https://docs.alvys.com/en/help/what-s-new/october-2025-releases

October 2025 expands Driver Events with new granular types like Sick, Hometime, and Restart so Dispatch Assist can plan more precisely around time off.

<Note>
  In October 2025 we expanded Driver Events with new, granular event types so you can plan more precisely around a driver's scheduled time off and commitments.
</Note>

## Overview

This page covers the product updates released in October 2025 (October release notes, What's New for October 2025). The release expanded the Driver Events feature with additional event types that give a more accurate way to block out a driver's calendar and feed higher-quality scheduling data into Dispatch Assist.

<Update label="October 3, 2025" description="Driver Events gains Sick or Emergency, Hometime and Restart types, and each type is now a hard or soft constraint for Dispatch Assist.">
  ## Expanded Driver Event types for more precise time-off planning

  Driver Events now includes new, granular event types so you can record a driver's scheduled time off and commitments with more accuracy than before.

  Previously the available event types were limited to Vacation, Restart, and Other, which meant relying on notes or generic categories and left gaps in the data. The expanded set lets you classify each event precisely, which improves planning around a specific driver's needs and provides higher-quality, structured data for the Dispatch Assist optimization model. Each event is classified as either a Hard Constraint (mandatory; cannot be violated) or a Soft Constraint (preference-based; can be overridden), so the optimizer avoids recommending assignments that conflict with a driver's time off.

  The full set of event options is now available when you create an event:

  * **Vacation:** scheduled paid time off.
  * **Sick or Emergency:** urgent, unplanned time off due to illness or a medical appointment.
  * **Restart:** a mandatory 34-hour hours-of-service reset period; used to confirm compliance.
  * **Hometime:** a scheduled home visit or a specific personal event, such as a graduation.
  * **Other:** a catch-all for miscellaneous, non-prohibitive events.

  Who it affects: anyone who plans around driver availability, including those who dispatch loads and those who manage drivers. A What's New page is viewable by all users.

  **Where to find it:** the updated event options are available in both the Dispatch Planners and on the Driver Profile page. When you create a new event you will see the full list of options, so you can quickly and accurately block out a driver's calendar.

  <Note>
    <img alt="Image showing Add Asset Event form on a driver profile with the new event options." />

    *Image showing **Add Asset Event** form on a driver profile with the new event options.*
  </Note>

  **Action needed:** none. The expanded options are available automatically; start selecting the most specific event type when you schedule driver time off.

  <Note>
    🎬 [Walkthrough video link of the expanded Driver Event types](https://www.loom.com/share/349c80b81fe748769ae1ea332240af8a)
  </Note>

  **Learn more:** [How to add Driver and Asset Events](/en/help/assets-fleet/how-to-add-driver-and-asset-events)
</Update>


# September 2026 Releases
Source: https://docs.alvys.com/en/help/what-s-new/september-2026-releases

September 2026 opens with clearer dispatch information: a driver's last reported position now comes from the truck they are actually assigned to, the load board shows the right trailer number as soon as you assign it, the Dispatch Planner adds four optional columns and a Docs tab, addendum supplemental invoices get their own PDF layout, and imported PrePass toll transactions carry the dates and details from the report.

<Note>
  September 2026 begins with fixes to what the dispatch screens tell you about a driver and their equipment, four new optional columns and a Docs tab in the Dispatch Planner, a clearer PDF layout for addendum supplemental invoices, and more accurate PrePass toll imports.
</Note>

## Overview

Most of this month so far is about trusting what is on the screen in front of you. If you plan from a driver's last reported position, that position now comes from the truck the driver is actually on rather than one they used to drive, and it is blank when the current truck has not reported. If you assign trailers from the loads board, the sidebar now shows the trailer the trip actually has. The Dispatch Planner picks up four more optional columns and a Docs tab for trip paperwork. On the billing side, an addendum supplemental invoice now prints its own layout, so the adjustment amount is labelled as an adjustment. And imported PrePass toll transactions are dated from the report itself instead of the moment you uploaded it. None of these changes asks anything of you: they are live for every company, with no setting to turn on.

<Update label="September 2, 2026" description="Addendum supplemental invoices get their own PDF layout, the Dispatch Planner trips table adds load planner and carrier rate columns, and PrePass toll imports date from the exit time.">
  ## Addendum supplemental invoices print a clearer layout

  An addendum supplemental invoice used to print the same layout as the original invoice, which showed the adjustment under an **Amount** heading as though it were a full invoice value. Newly generated addendum supplementals now print their own layout instead: each line shows the previous rate, units and unit of measure alongside the new ones, the adjustment is labelled as an adjustment, and the footer totals the adjustment.

  Original invoices and revision-type supplementals print exactly as they did before, and this changes the printed document only — nothing about how an invoice is built or sent has changed.

  ## Two further optional columns in the Dispatch Planner trips table

  The trips table in the Dispatch Planner adds a column for the trip's load planner and a column for the carrier rate. Like the columns added on September 1, both are hidden until you add them from the trips table's column configuration menu, and both can be sorted and filtered once added.

  The load planner column filters on who is planning the trip, including an option for trips that have no load planner assigned yet, and shows a placeholder where none is assigned. The carrier rate column is limited to accounts that are allowed to see carrier rates: where your account is not, the column does not appear in the trips table or in its column configuration menu. It shows the rate and nothing more — it does not change who may edit a rate, and it restricts nothing that was allowed before.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)

  * Imported PrePass toll transactions are now dated from the exit date and time in the Toll Details report rather than from the time you uploaded the file, entry and exit details come across with the transaction, and a truck links automatically when its transponder ID matches the report. Both the CSV and Excel versions of the report import. **Learn more:** [PrePass Toll Integration](/en/help/integrations/prepass-toll-integration)
</Update>

<Update label="September 1, 2026" description="A driver's last reported position follows the truck they are on, the loads board shows the assigned trailer straight away, and the Dispatch Planner adds two columns and a Docs tab.">
  ## A driver's last reported position now follows the truck they are on

  The last reported position shown for a driver in the Dispatch Planner now comes from the truck that driver is currently assigned to. If that truck has not reported a position, the value is blank rather than showing an older position from a different truck.

  This matters most when you plan by location. A driver who changed trucks used to be able to appear where their previous truck last reported, which put them in the wrong place on the board. A blank value now means the current truck has not reported yet, which is a different thing from being far away.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)

  ## The loads board shows the right trailer number straight away

  The **Trailer** row in the loads board side panel now shows the trailer the trip is actually assigned. It reflects the current assignment as soon as you make it, so you can confirm equipment from the board without opening the trip to check.

  **Learn more:** [Alvys Load Board](/en/help/loads-trips/alvys-load-board)

  ## Two more optional columns in the Dispatch Planner

  The drivers table in the Dispatch Planner adds a **Contractor Type** column, and the trips table adds a **Carrier Sales Agent** column. Both are hidden until you add them, so nobody's saved view changes on its own — add either one from that table's column configuration menu when you want it. Once added, both can be sorted and filtered like the rest of the table.

  **Learn more:** [Dispatch Planner](/en/help/loads-trips/dispatch-planner)

  ## Trip documents in the Dispatch Planner side panel

  The Dispatch Planner side panel adds a **Docs** tab for the trip's paperwork. From it you can upload a document, edit one already there, download a copy, and delete one — without leaving the planner to open the trip.
</Update>


# Create one-time deduction
Source: https://docs.alvys.com/en/api/reference/deductions/create-one-time-deduction

POST /api/p/v{version}/deductions/once
Create a one-time driver deduction that applies to a single upcoming settlement, specifying the driver, amount, deduction type, and effective date.

This endpoint creates a new deduction record for a driver or a truck.
Deductions are asset-specific financial adjustments and can be associated with either a driver or a truck, but not both simultaneously.
The deduction itself is always tied to a specific asset (Driver or Truck) and can optionally reference an owner operator for ownership context.

#### Key Rules:

* A deduction must include **either `DriverId` or `TruckId`** — one of them is mandatory.
* **`OwnerOperatorId`** is optional and used only to override the current owner of the asset. It is never the primary subject of the deduction.
* The deduction is always created for a specific **DriverId** or **TruckId**, not directly for an owner operator.
* If **DriverId** is provided → the deduction appears in that driver’s deductions table.
* If **TruckId** is provided → the deduction appears in that truck’s deductions table.
* If **OwnerOperatorId** is provided → it overrides the current owner of the asset to that specific owner operator (only within this deduction record). If omitted → the system automatically links the deduction to the current owner operator, if one exists.
* If the truck or driver has no owner operator → the deduction is created without one.

### Permissions Required

Only users or client credentials with **Create access** to the **Deductions** resource can perform creation.
If the API client lacks sufficient privileges, a `403 Forbidden` response will be returned.

***

### Request Body Parameters

| Parameter       | Type          | Required      | Description                                                                              |
| --------------- | ------------- | ------------- | ---------------------------------------------------------------------------------------- |
| Date            | String (Date) | Yes           | The effective date of the deduction. Time values are accepted but truncated on save.     |
| Amount          | Number        | Yes           | The deduction amount. Must be **negative** and have a value of less than  **- 1.00**.    |
| Category        | String        | Yes           | Deduction category (any string value).                                                   |
| Description     | String        | Yes           | Description or reason for the deduction.                                                 |
| DriverId        | String        | Conditionally | Required when creating a deduction for a driver. Must not be used together with TruckId. |
| TruckId         | String        | Conditionally | Required when creating a deduction for a truck. Must not be used together with DriverId. |
| OwnerOperatorId | String        | No            | Optional — used only to override the current owner of the asset (Driver or Truck).       |

### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/deductions/once' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Date": "2025-10-07",
  "Amount": -55,
  "Category": "Drug Test",
  "Description": "DOT Drug Test Fee",
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290"
}'
```

### Response Body Parameters

| Parameter       | Type               | Required      | Description                                                      |
| --------------- | ------------------ | ------------- | ---------------------------------------------------------------- |
| Id              | String             | Yes           | The unique identifier of the created deduction.                  |
| Type            | String             | Yes           | Type of record (`"Deduction"`).                                  |
| GroupId         | String             | No            | Group ID if part of a recurring rule or batch.                   |
| Description     | String             | Yes           | Description of the deduction.                                    |
| Category        | String             | Yes           | Deduction category (e.g., Fuel, Advance, Drug Test).             |
| Amount.Amount   | Number             | Yes           | Deduction amount (negative value).                               |
| Amount.Currency | Integer            | Yes           | ISO numeric currency code (e.g., 840 for USD).                   |
| DriverId        | String             | Conditionally | The Driver ID if the deduction was created for a driver.         |
| TruckId         | String             | Conditionally | The Truck ID if the deduction was created for a truck.           |
| OwnerOperatorId | String             | No            | The Owner Operator ID of the truck or driver (if applicable).    |
| Date            | String (Date)      | Yes           | The effective date of the deduction (date only, without time).   |
| IsPaid          | Boolean            | No            | Indicates whether the deduction has been paid. Default: `false`. |
| CreatedAt       | String (Date-Time) | Yes           | Timestamp when the deduction was created (UTC).                  |
| CreatedBy       | String             | No            | Client ID or User ID of the person who created the deduction.    |

***

### Example Response

```json theme={null}
{
  "Id": "22d34b6d-7403-4003-b8ea-e028cd36e7d7",
  "Type": "Deduction",
  "GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
  "Description": "DOT Drug Test Fee",
  "Category": "Drug Test",
  "Amount": {
    "Amount": -55,
    "Currency": 840
  },
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290",
  "Date": "2025-10-07",
  "IsPaid": false,
  "CreatedAt": "2025-10-09T08:30:54.873Z",
  "CreatedBy": "MhAeSgpRH6REdgfrthgfUdTdXOMgVSGyp"
}
```

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using.
Including the version number ensures that your integration remains stable as the API evolves.
For more details, refer to the [Versioning](/en/api/guides/versioning) page.

***

### Rate Limits

All endpoints are subject to standard rate limits to ensure consistent API performance.
For details, see the [Rate Limits](/en/api/guides/rate-limits) section.


# Delete deduction
Source: https://docs.alvys.com/en/api/reference/deductions/delete-deduction

DELETE /api/p/v{version}/deductions/{id}
Delete a driver deduction record by ID through the Alvys Public API, removing the deduction from payroll settlements and future driver pay statements.

This endpoint permanently deletes a deduction record by its unique identifier.
Use this method to remove a previously created deduction that was entered in error or is no longer needed.

Deletion removes only the deduction record itself — it does **not** affect any driver, or truck data. Once deleted, the deduction **cannot be recovered** through the API.

A successful deletion will immediately remove the deduction from all search and detail responses.

***

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                                              |
| --------- | ------ | -------- | -------------------------------------------------------- |
| version   | String | Yes      | The API version to use.                                  |
| id        | String | Yes      | The unique identifier (`Id`) of the deduction to delete. |

***

### Permissions Required

Only users or client credentials with **Delete access** to the **Deductions** resource can perform deletions.
If the API client lacks sufficient privileges, a `403 Forbidden` response will be returned.

***

### Example CURL Request

```bash theme={null}
curl --location --request DELETE 'https://integrations.alvys.com/api/p/v1/deductions/3243fdfd-7403-0000-b8ea-e028cd36e7d7' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

***

### Example Response (Success)

```json theme={null}
{
  "Id": "00000000-dd44-0000-0000-8a1fa91b607a",
  "Type": "Deduction",
  "GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
  "Description": "Drug Test Fee",
  "Category": "Drug Test",
  "Amount": {
    "Amount": -50,
    "Currency": 840
  },
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290",
  "Date": "2025-10-07",
  "IsPaid": false,
  "CreatedAt": "2025-10-09T08:30:54.873Z",
  "CreatedBy": "MhAeS5345435fbvccvbfUdTdXOMgVSGyp"
}
```

***

### Example Response (Error)

```json theme={null}
{
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
    "title": "Not Found",
    "status": 404,
    "traceId": "00-2ea901xgrtg4et43ab20a37057df4c54-8fe88954ae45a964-01"
}
```

***

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using.
Including the version number ensures that your integration remains stable as the API evolves.
For more details, refer to the [Versioning](/en/api/guides/versioning) page.

***

### Rate Limits

All endpoints are subject to standard rate limits to ensure consistent API performance.
For details, see the [Rate Limits](/en/api/guides/rate-limits) section.

<br />


# Get deduction
Source: https://docs.alvys.com/en/api/reference/deductions/get-deduction

GET /api/p/v{version}/deductions/{id}
Retrieve a single driver deduction record by ID, including deduction type, amount, frequency, effective dates, and the driver settlement it applies to.

This endpoint retrieves detailed information about a specific deduction record by its unique identifier.
Use this method to view all deduction details including amount, category, associated driver or truck, payment status, and creation metadata.

Deductions are asset-specific financial adjustments and can be associated with either a driver or a truck, but not both simultaneously.

***

### Request Parameters

The following parameters are required in the URL path or query:

| Parameter | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| version   | String | Yes      | The API version to use.                                    |
| id        | String | Yes      | The unique identifier (`Id`) of the deduction to retrieve. |

***

### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/deductions/00000000-dd44-0000-0000-8a1fa91b607a' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

***

### Response Body Parameters

The following parameters are included in the response body:

| Parameter       | Type               | Required      | Description                                                                                                                                              |
| --------------- | ------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id              | String             | Yes           | The unique identifier of the deduction.                                                                                                                  |
| Type            | String             | Yes           | Type of record: `"Deduction"`, or `"Credit"` for a driver credit created through [Create driver credit](/en/api/reference/credits/create-driver-credit). |
| GroupId         | String             | Yes           | Group ID if the deduction belongs to a recurring group or rule.                                                                                          |
| Description     | String             | Yes           | Description of the deduction.                                                                                                                            |
| Category        | String             | Yes           | Deduction category (e.g., Fuel, Advance, Drug Test).                                                                                                     |
| Amount.Amount   | Number             | Yes           | Deduction amount (negative for deductions).                                                                                                              |
| Amount.Currency | Integer            | Yes           | ISO numeric currency code (e.g., 840 for USD).                                                                                                           |
| DriverId        | String             | Conditionally | The Driver ID linked to the deduction.                                                                                                                   |
| TruckId         | String             | Conditionally | The Truck ID linked to the deduction.                                                                                                                    |
| OwnerOperatorId | String             | No            | The Owner Operator ID of the truck or driver.                                                                                                            |
| Date            | String (Date)      | Yes           | The effective date of the deduction (date only, without time).                                                                                           |
| IsPaid          | Boolean            | No            | Indicates whether the deduction has been paid.                                                                                                           |
| CreatedAt       | String (Date-Time) | No            | Timestamp when the deduction was created (UTC).                                                                                                          |
| CreatedBy       | String             | No            | Client ID or User ID of the person who created the deduction.                                                                                            |

***

### Example Response

```json theme={null}
{
  "Id": "00000000-dd44-0000-0000-8a1fa91b607a",
  "Type": "Deduction",
  "GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
  "Description": "Drug Test Fee",
  "Category": "Drug Test",
  "Amount": {
    "Amount": -50,
    "Currency": 840
  },
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR25165000003445290",
  "Date": "2025-10-07",
  "IsPaid": false,
  "CreatedAt": "2025-10-09T08:30:54.873Z",
  "CreatedBy": "MhAeS5345435fbvccvbfUdTdXOMgVSGyp"
}
```

***

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using.
Including the version number ensures that your integration remains stable as the API evolves.
For more details, refer to the [Versioning](/en/api/guides/versioning) page.

***

### Rate Limits

All endpoints are subject to standard rate limits to ensure consistent API performance.
For details, see the [Rate Limits](/en/api/guides/rate-limits) section.


# Search deductions
Source: https://docs.alvys.com/en/api/reference/deductions/search-deductions

POST /api/p/v{version}/deductions/search
Search driver deductions with paginated POST filters — driver, deduction type, frequency, effective date range, and active or inactive status.

This endpoint provides detailed information about each deduction that matches the specified search criteria, enabling efficient management and retrieval of deduction records.

Deductions are asset-specific financial adjustments and can be associated with either a driver or a truck, but not both simultaneously.

Only deductions are returned. Driver credits created through [Create driver credit](/en/api/reference/credits/create-driver-credit) do not appear in these results; read one by id with [Get deduction](/en/api/reference/deductions/get-deduction).

***

### Request Body Parameters

The following parameters are accepted in the request body:

| Parameter       | Type               | Required      | Description                                                                                                                                                           |
| --------------- | ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page            | Integer            | Yes           | The page number to retrieve. Default is `0`.                                                                                                                          |
| PageSize        | Integer            | Yes           | The number of items per page. Must be greater than 0.                                                                                                                 |
| DateRange       | Object             | Conditionally | The date range to filter by. This field is required if the other conditionally required fields are left empty.                                                        |
| DateRange.Start | String (Date-Time) | Yes           | Start of the date range (UTC). Required when `DateRange` is supplied.                                                                                                 |
| DateRange.End   | String (Date-Time) | No            | End of the date range (UTC).                                                                                                                                          |
| DriverId        | String             | Conditionally | Required when filtering by driver. Must not be provided together with TruckId. This field is required if the other conditionally required fields are left empty.      |
| TruckId         | String             | Conditionally | Required when filtering by truck. Must not be provided together with DriverId. This field is required if the other conditionally required fields are left empty.      |
| OwnerOperatorId | String             | Conditionally | Optional — used only to filter by the current owner of the asset (Driver or Truck). This field is required if the other conditionally required fields are left empty. |
| IncludePaid     | Boolean            | Yes           | When `true`, includes already paid deductions. Default: `false`.                                                                                                      |

<br />

### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/deductions/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "DateRange": {
    "Start": "2025-10-07T00:00:00Z",
    "End": "2025-10-09T23:59:59Z"
  },
  "DriverId": "DR2517534557938191",
  "OwnerOperatorId": "DR251652563453445290",
  "IncludePaid": true
}'
```

***

### Response Body Parameters

The following parameters are included in the response body:

| Parameter                | Type               | Required      | Description                                                     |
| ------------------------ | ------------------ | ------------- | --------------------------------------------------------------- |
| Page                     | Integer            | No            | The current page of the response.                               |
| PageSize                 | Integer            | Yes           | The number of items per page.                                   |
| Total                    | Integer            | Yes           | The total number of deduction records matching the criteria.    |
| Items\[]                 | Array              | Yes           | The list of deduction records.                                  |
| Items\[].Id              | String             | Yes           | The unique identifier of the deduction.                         |
| Items\[].Type            | String             | Yes           | Type of record (`"Deduction"`).                                 |
| Items\[].GroupId         | String             | Yes           | Group ID if the deduction belongs to a recurring group or rule. |
| Items\[].Description     | String             | Yes           | Description of the deduction.                                   |
| Items\[].Category        | String             | Yes           | Deduction category (e.g., Fuel, Advance, Drug Test).            |
| Items\[].Amount.Amount   | Number             | Yes           | Deduction amount (negative for deductions).                     |
| Items\[].Amount.Currency | Integer            | Yes           | ISO numeric currency code (e.g., 840 for USD).                  |
| Items\[].DriverId        | String             | Conditionally | The Driver ID linked to the deduction.                          |
| Items\[].TruckId         | String             | Conditionally | The Truck ID linked to the deduction.                           |
| Items\[].OwnerOperatorId | String             | No            | The Owner Operator ID of truck or driver.                       |
| Items\[].Date            | String (Date)      | Yes           | The effective date of the deduction (date only, without time).  |
| Items\[].IsPaid          | Boolean            | No            | Indicates whether the deduction has been paid.                  |
| Items\[].CreatedAt       | String (Date-Time) | No            | Timestamp when the deduction was created (UTC).                 |
| Items\[].CreatedBy       | String             | No            | Client ID or User ID of the person who created the deduction.   |

***

### Example Response

```json theme={null}
{
  "Page": 0,
  "PageSize": 100,
  "Total": 1,
  "Items": [
    {
      "Id": "00000000-dd44-0000-0000-8a1fa91b607a",
      "Type": "Deduction",
      "GroupId": "344571de-57b4-4163-a0cc-d7981fa65994",
      "Description": "Drug Test Detais",
      "Category": "Drug Test",
      "Amount": {
        "Amount": -50,
        "Currency": 840
      },
      "DriverId": "DR2517534557938191",
      "OwnerOperatorId": "DR25165000003445290",
      "Date": "2025-10-07",
      "IsPaid": false,
      "CreatedAt": "2025-10-09T08:30:54.873Z",
      "CreatedBy": "MhAeS5345435fbvccvbfUdTdXOMgVSGyp"
    }
  ]
}
```

***

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using.
Including the version number ensures that your integration remains stable as the API evolves.
For more details, refer to the [Versioning](/en/api/guides/versioning) page.

***

### Rate Limits

All endpoints are subject to standard rate limits to ensure consistent API performance.
For details, see the [Rate Limits](/en/api/guides/rate-limits) section.


# Search dispatch preferences
Source: https://docs.alvys.com/en/api/reference/dispatch-preferences/search-dispatch-preferences

POST /api/p/v{version}/dispatchpreferences/search
Search dispatch preferences with paginated POST filters, returning the routing, equipment, home-time, and lane preferences configured for drivers.

This endpoint provides detailed information about dispatch preferences that match the search criteria, enabling efficient tracking and management of dispatcher, driver, truck, and trailer assignments.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body Parameters

The following parameters are required in the request body:

| Parameter      | Type              | Required | Description                                              |
| -------------- | ----------------- | -------- | -------------------------------------------------------- |
| DispatcherIds  | Array of Strings  | No       | A list of dispatcher IDs to filter results.              |
| DriverIds      | Array of Strings  | No       | A list of driver IDs to filter results.                  |
| TruckIds       | Array of Strings  | No       | A list of truck IDs to filter results.                   |
| TrailerIds     | Array of Strings  | No       | A list of trailer IDs to filter results.                 |
| UpdatedAtStart | String (DateTime) | No       | The start date-time for filtering updated dispatch data. |
| UpdatedAtEnd   | String (DateTime) | No       | The end date-time for filtering updated dispatch data.   |

#### Example CURL request

Use the current API version number and ensure you replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/dispatchpreferences/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "DispatcherIds": ["2c551c41c840410ebcf34ba388749258"],
  "DriverIds": ["DR2517197559590084753"],
  "TruckIds": ["TR2517389363484408036"],
  "TrailerIds": ["TL2517274420190288696"],
  "UpdatedAtStart": "2025-03-01T00:00:00.000Z",
  "UpdatedAtEnd": "2025-03-03T23:59:59.999Z"
}'
```

### Response Parameters

The following table lists the parameters included in the response for dispatch preferences requests.

| Parameter    | Type              | Required | Description                                                  |
| ------------ | ----------------- | -------- | ------------------------------------------------------------ |
| UpdatedAt    | String (DateTime) | No       | The timestamp when the dispatch preference was last updated. |
| DispatcherId | String            | No       | The unique identifier of the dispatcher.                     |
| Driver1Id    | String            | No       | The unique identifier of the primary driver.                 |
| Driver2Id    | String            | No       | The unique identifier of the secondary driver.               |
| TruckId      | String            | No       | The unique identifier of the truck.                          |
| TrailerId    | String            | No       | The unique identifier of the trailer.                        |

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Example Response

```json theme={null}
[
  {
    "UpdatedAt": "2025-03-02T14:30:05+00:00",
    "DispatcherId": "2c551c41c840410ebcf34ba388749258",
    "Driver1Id": "DR2517197559590084753",
    "Driver2Id": "DR2518197559590084765",
    "TruckId": "TR2517389363484408036",
    "TrailerId": "TL2517274420190288696"
  },
  {
    "UpdatedAt": "2025-03-02T16:45:10+00:00",
    "DispatcherId": "3d671c41c840410ebcf34ba388749275",
    "Driver1Id": "DR2527197559590084754",
    "Driver2Id": "",
    "TruckId": "TR2527389363484408047",
    "TrailerId": "TL2527274420190288799"
  }
]
```

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Get driver
Source: https://docs.alvys.com/en/api/reference/drivers/get-driver

GET /api/p/v{version}/drivers/{id}
Retrieve a single driver record by ID from Alvys, including license details, contact info, pay setup, home terminal, and current employment status.

The endpoint for retrieving a driver by ID requires specifying the driver's unique ID and the API version in the URL path. This ensures that your application interacts with the correct driver's data and the appropriate version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| version   | String | Yes      | The API version to use.                    |
| id        | String | Yes      | The unique Alvys identifier of the driver. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/drivers/{id}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{id}` with the actual driver ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/drivers/DR123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJBTDM2MyIsInZlc...'
```

### Response Parameters

The following table lists the parameters included in the response for driver-related requests.

| Parameter         | Type               | Description                                                                                                 |
| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Id                | String             | The unique identifier of the driver.                                                                        |
| EmployeeId        | String             | The employee ID of the driver.                                                                              |
| PhoneNumber       | String             | The phone number of the driver.                                                                             |
| UserId            | String             | The user ID associated with the driver.                                                                     |
| Email             | String             | The email address of the driver.                                                                            |
| Name              | String             | The name of the driver.                                                                                     |
| Type              | String             | The type of driver (COMPANY, OWNER\_OPERATOR, CONTRACTOR, EXTERNAL).                                        |
| SubsidiaryId      | String             | The subsidiary ID to which the driver belongs.                                                              |
| Address           | Object             | The address details of the driver.                                                                          |
| Address.Street    | String             | The street address of the driver.                                                                           |
| Address.City      | String             | The city of the driver's address.                                                                           |
| Address.State     | String             | The state of the driver's address.                                                                          |
| Address.ZipCode   | String             | The zip code of the driver's address.                                                                       |
| Status            | String             | The current status of the driver (e.g., "SLEEPING", "DRIVING", "ON DUTY", "OFF DUTY", "ONLINE", "OFFLINE"). |
| IsActive          | Boolean            | Indicates if the driver is currently active                                                                 |
| LicenseNum        | String             | The driver's license number.                                                                                |
| LicenseState      | String             | The state that issued the driver's license.                                                                 |
| LicenseCountry    | String             | The country where the driver's license was issued (USA, Canada, Mexico).                                    |
| LicenseExpiresAt  | String (Date-Time) | The expiration date of the driver's license.                                                                |
| MedicalExpiresAt  | String (Date-Time) | The expiration date of the driver's medical certificate.                                                    |
| HiredAt           | String (Date-Time) | The date when the driver was hired.                                                                         |
| TerminatedAt      | String (Date-Time) | The date when the driver was terminated, if applicable.                                                     |
| Notes             | Array              | An optional list of notes related to the driver.                                                            |
| Notes.id          | String             | The unique identifier of the note.                                                                          |
| Notes.Description | String             | The description of the note.                                                                                |
| Notes.NoteType    | String             | The type of the note.                                                                                       |
| Notes.Time        | String (Date-Time) | The time the note was created.                                                                              |
| Notes.User        | String             | The user who created the note.                                                                              |
| Fleet             | Object             | The fleet information associated with the driver.                                                           |
| Fleet.Id          | String             | The unique identifier of the fleet.                                                                         |
| Fleet.Name        | String             | The name of the fleet.                                                                                      |
| References        | Array              | An optional list of custom references associated with the driver.                                           |
| CreatedAt         | String (Date-Time) | The date and time when the driver was created in Alvys.                                                     |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by providing the driver ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Get driver settlement statement
Source: https://docs.alvys.com/en/api/reference/drivers/get-driver-settlement-statement

GET /api/p/v{version}/driver-settlement-statements/{number}
Retrieve a finalized driver settlement statement from Alvys by statement number, including per-trip breakdown, line items, deductions, and net pay.

The Get Driver Settlement Statement endpoint returns a single finalized driver or owner-operator settlement statement by its statement number, including its full breakdown of line items and totals.

Only settled statements are returned. If the statement does not exist, or is still in-flight (being generated or reversed), the endpoint responds with `404 Not Found`. A statement whose `Status` is `Failed` is still returned.

This endpoint requires the `driver:read` scope.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |
| number    | Number | Yes      | The statement number to retrieve.       |

### Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/driver-settlement-statements/10432' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

Returns a single statement object with the same shape as each item in the Search Driver Settlement Statements response. Monetary values are objects of the form `{ "Amount": <number>, "Currency": <ISO 4217 numeric code, may be null> }`.

| Parameter      | Type             | Description                                                                                                                                     |
| -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Number         | Number           | The statement number.                                                                                                                           |
| Status         | String           | `Processed` or `Failed`.                                                                                                                        |
| StatementDate  | String           | The statement date (ISO `yyyy-MM-dd`).                                                                                                          |
| PayPeriodId    | String           | The pay period identifier.                                                                                                                      |
| PayPeriodTitle | String           | The pay period display title.                                                                                                                   |
| Driver         | Object           | Driver details: `Id`, `Name`, `Type` (`COMPANY`, `OWNER_OPERATOR`, or `CONTRACTOR`), `CompanyName`, `SubsidiaryId`, `FleetName`.                |
| Totals         | Object           | Statement totals (gross/net income, line haul, accessorials, deductions, fuel, tolls, escrow, per-diem, trip/mile counts, etc.).                |
| LineItems      | Array of Objects | The individual pay and deduction line items, each with `Category`, `Title`, `PolicyName`, `TripNumber`, `LoadNumber`, `Amount`, and `SubLines`. |

### Example Response

```json theme={null}
{
  "Number": 10432,
  "Status": "Processed",
  "StatementDate": "2026-06-20",
  "PayPeriodId": "5d2c1b7a-9f3e-4c8a-8b1d-1a2b3c4d5e6f",
  "PayPeriodTitle": "Jun 16 - Jun 30, 2026",
  "Driver": {
    "Id": "2e17c4d3-202d-4f27-b2fa-711c57435c5b",
    "Name": "John Carter",
    "Type": "OWNER_OPERATOR",
    "CompanyName": "Carter Trucking LLC",
    "SubsidiaryId": "a1b2c3d4-0000-0000-0000-000000000001",
    "FleetName": "West Fleet"
  },
  "Totals": {
    "GrossIncome": { "Amount": 4200.00, "Currency": 840 },
    "NetIncome": { "Amount": 3560.50, "Currency": 840 },
    "LineHaul": { "Amount": 4000.00, "Currency": 840 },
    "Accessorials": { "Amount": 200.00, "Currency": 840 },
    "Deductions": { "Amount": 639.50, "Currency": 840 },
    "Fuel": { "Amount": 400.00, "Currency": 840 },
    "NumberOfTrips": 2,
    "LoadedMiles": 1180.0,
    "EmptyMiles": 95.0,
    "HoursWorked": 0.0
  },
  "LineItems": [
    {
      "Category": "Per Trip",
      "Title": "Line Haul",
      "PolicyName": "OO 70% Line Haul",
      "TripNumber": "TRIP-88213",
      "LoadNumber": "L-55021",
      "Amount": { "Amount": 2800.00, "Currency": 840 },
      "SubLines": [
        { "Description": "70% of $4,000.00", "Quantity": "1", "Rate": "0.70", "Amount": { "Amount": 2800.00, "Currency": 840 } }
      ]
    }
  ]
}
```

<br />

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.


# List driver documents
Source: https://docs.alvys.com/en/api/reference/drivers/list-driver-documents

GET /api/p/v{version}/drivers/{driverId}/documents
List all documents on file for a driver by driver ID, including CDLs, medical cards, drug test results, hire packets, and other compliance uploads.

Retrieve all uploaded documents associated with a specific **Driver** by its unique `driverId`.

### Request Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| version   | String | Yes      | API version to use.              |
| driverId  | String | Yes      | Unique identifier of the driver. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/drivers/{driverId}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{driverId}` with the actual driver ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                         |
| -------------- | ------- | ------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                  |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix). |
| AttachmentType | string  | Type of document (e.g., License, Medical Card).                     |
| AttachmentSize | integer | Size of the file in bytes.                                          |
| UploadedAt     | string  | UTC timestamp when the file was uploaded .                          |
| ParentId       | string  | Identifier of the parent entity (`driverId`).                       |
| ParentType     | string  | Entity type the document is attached to (`Driver`).                 |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.       |
| DownloadUrl    | string  | Time-limited link (10 minutes) to download the document.            |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl`.                          |

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "9af00ed0-47d2-00f5-00e1-235f00cf0a55",
    "AttachmentPath": "CDL-1759237626.pdf",
    "AttachmentType": "License",
    "AttachmentSize": 50212,
    "UploadedAt": "2025-09-30T11:22:07+00:00",
    "ParentId": "DR123hf546456tg5",
    "ParentType": "Driver",
    "UploadedBy": "7000000eecc3408e90d700f4ece0e00",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/L-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T11:32:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **driverId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List drivers
Source: https://docs.alvys.com/en/api/reference/drivers/list-drivers

GET /api/p/v{version}/drivers
List drivers in your Alvys tenant with pagination, returning employment status, home terminal, license class, current truck assignment, and contact details.

The GET Drivers API endpoint allows you to retrieve a comprehensive list of drivers within the Alvys system. This endpoint provides detailed information about each driver, facilitating effective driver management and tracking. The endpoint requires specifying the API version in the URL path. This ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/drivers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/drivers' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJBTDM2MyIsInZlc...'
```

#### Response Parameters

The following table lists the parameters included in the response for each driver in the list:

| Parameter         | Type               | Description                                                                                                 |
| :---------------- | :----------------- | :---------------------------------------------------------------------------------------------------------- |
| Id                | String             | The unique identifier of the driver.                                                                        |
| EmployeeId        | String             | The employee ID of the driver.                                                                              |
| PhoneNumber       | String             | The phone number of the driver.                                                                             |
| UserId            | String             | The user ID associated with the driver.                                                                     |
| Email             | String             | The email address of the driver.                                                                            |
| Name              | String             | The name of the driver.                                                                                     |
| Type              | String             | The type of driver (COMPANY, OWNER\_OPERATOR, CONTRACTOR, EXTERNAL).                                        |
| SubsidiaryId      | String             | The subsidiary ID to which the driver belongs.                                                              |
| Address           | Object             | The address details of the driver.                                                                          |
| Address.Street    | String             | The street address of the driver.                                                                           |
| Address.City      | String             | The city of the driver's address.                                                                           |
| Address.State     | String             | The state of the driver's address.                                                                          |
| Address.ZipCode   | String             | The zip code of the driver's address.                                                                       |
| Status            | String             | The current status of the driver (e.g., "SLEEPING", "DRIVING", "ON DUTY", "OFF DUTY", "ONLINE", "OFFLINE"). |
| IsActive          | Boolean            | Indicates if the driver is currently active.                                                                |
| LicenseNum        | String             | The driver's license number.                                                                                |
| LicenseState      | String             | The state that issued the driver's license.                                                                 |
| LicenseCountry    | String             | The country where the driver's license was issued (USA, Canada, Mexico).                                    |
| LicenseExpiresAt  | String (Date-Time) | The expiration date of the driver's license.                                                                |
| MedicalExpiresAt  | String (Date-Time) | The expiration date of the driver's medical certificate.                                                    |
| HiredAt           | String (Date-Time) | The date when the driver was hired.                                                                         |
| TerminatedAt      | String (Date-Time) | The date when the driver was terminated, if applicable.                                                     |
| Notes             | Array              | An optional list of notes related to the driver.                                                            |
| Notes.id          | String             | The unique identifier of the note.                                                                          |
| Notes.Description | String             | The description of the note.                                                                                |
| Notes.NoteType    | String             | The type of the note.                                                                                       |
| Notes.Time        | String (Date-Time) | The time the note was created.                                                                              |
| Notes.User        | String             | The user who created the note.                                                                              |
| Fleet             | Object             | The fleet information associated with the driver.                                                           |
| Fleet.Id          | String             | The unique identifier of the fleet.                                                                         |
| Fleet.Name        | String             | The name of the fleet.                                                                                      |
| References        | Array              | An optional list of custom references associated with the driver.                                           |
| CreatedAt         | String (Date-Time) | The date and time when the driver was created in Alvys.                                                     |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search driver events
Source: https://docs.alvys.com/en/api/reference/drivers/search-driver-events

POST /api/p/v{version}/drivers/events/search
Search driver duty and location events with paginated POST filters — driver, event type, date range, and load or trip context for HOS and telematics data.

This endpoint provides detailed information about driver events that match the search criteria, enabling efficient tracking and management of driver-related activities.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body Parameters

The following parameters are required in the request body:

| Parameter | Type              | Required | Description                                     |
| --------- | ----------------- | -------- | ----------------------------------------------- |
| StartDate | String (DateTime) | Yes      | The start date-time for the event search range. |
| EndDate   | String (DateTime) | No       | The end date-time for the event search range.   |
| DriverIds | Array of Strings  | Yes      | The list of driver IDs to filter driver events. |

#### Example CURL request

Use the current API version number and ensure you replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/drivers/events/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "StartDate": "2025-02-06T06:50:20.471Z",
  "EndDate": "2025-02-06T06:50:20.471Z",
  "DriverIds": [
    "string"
  ]
}'
```

### Response Parameters

The following table lists the parameters included in the response for driver events requests.

| Parameter       | Type              | Required | Description                                         |
| --------------- | ----------------- | -------- | --------------------------------------------------- |
| Id              | String            | Yes      | The unique identifier of the driver event.          |
| DriverId        | String            | Yes      | The unique identifier of the driver.                |
| EventType       | String            | Yes      | The type of event (e.g., Vacation, Restart, Other). |
| Description     | String            | No       | A detailed description of the event.                |
| StartDate       | String (DateTime) | Yes      | The start date-time of the event.                   |
| EndDate         | String (DateTime) | Yes      | The end date-time of the event.                     |
| Address         | Object            | No       | The location details associated with the event.     |
| Address.Street  | String            | No       | The street address where the event occurred.        |
| Address.City    | String            | No       | The city where the event took place.                |
| Address.State   | String            | No       | The state where the event took place.               |
| Address.ZipCode | String            | No       | The ZIP code of the event location.                 |
| CreatedBy       | String            | Yes      | The user who created the event record.              |
| CreatedAt       | String (DateTime) | Yes      | The timestamp for when the event was created.       |

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Search driver settlement statements
Source: https://docs.alvys.com/en/api/reference/drivers/search-driver-settlement-statements

POST /api/p/v{version}/driver-settlement-statements/search
Search finalized driver settlement statements in Alvys with paginated POST filters by date range, driver, driver type, and statement number.

The Search Driver Settlement Statements endpoint returns a paged list of finalized driver and owner-operator settlement statements (the "Statements" tab), each with its full breakdown of line items and totals. It mirrors the in-app "Statements List and Items" report and is intended for external reporting (e.g. building your own dashboards in Power BI).

Only settled statements are returned: in-flight statements still being generated or reversed are excluded, and each returned statement carries a `Status` of `Processed` or `Failed` so you can filter downstream. Open and Draft statements are never returned.

A statement that failed a downstream step (for example, an accounting sync) is still a finalized statement on the Statements tab, so it is returned here with a `Failed` status rather than hidden. This differs from carrier settlement statements, where `Failed` and `Deleted` are lifecycle statuses and such statements are excluded.

This endpoint requires the `driver:read` scope.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

### Request Body

| Parameter                | Type               | Required | Description                                                                                                                                                                                       |
| ------------------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                     | Number             | Yes      | The page number for pagination (starts from 0).                                                                                                                                                   |
| PageSize                 | Number             | Yes      | The number of results per page. Must be greater than 0 and cannot exceed 100.                                                                                                                     |
| StatementDateRange       | Object             | Yes      | The inclusive statement-date window to filter on. Both bounds are treated as whole UTC calendar days.                                                                                             |
| StatementDateRange.Start | String (Date-Time) | Yes      | Start of the range (inclusive).                                                                                                                                                                   |
| StatementDateRange.End   | String (Date-Time) | Yes      | End of the range (inclusive). Required - an open-ended range is rejected.                                                                                                                         |
| DriverType               | String             | No       | Filter by driver type: `COMPANY`, `OWNER_OPERATOR`, or `CONTRACTOR` (case-insensitive; matches the value returned in each result's `Driver.Type` and the /drivers endpoint). Omit to include all. |
| DriverId                 | String (UUID)      | No       | Filter to a single driver.                                                                                                                                                                        |

### Example CURL Request

Use the current API version number and replace the Authorization header value with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/driver-settlement-statements/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 0,
  "PageSize": 50,
  "StatementDateRange": {
    "Start": "2026-06-01T00:00:00Z",
    "End": "2026-06-30T00:00:00Z"
  },
  "DriverType": "OWNER_OPERATOR",
  "DriverId": "2e17c4d3-202d-4f27-b2fa-711c57435c5b"
}'
```

### Response Parameters

The response is a paged envelope. Each item is a finalized statement. Monetary values are objects of the form `{ "Amount": <number>, "Currency": <ISO 4217 numeric code, may be null> }`.

| Parameter                        | Type             | Description                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                             | Number           | The current page number.                                                                                                                                                                                                                                                                                                                                    |
| PageSize                         | Number           | The number of items per page.                                                                                                                                                                                                                                                                                                                               |
| Total                            | Number           | The total number of matching statements across all pages.                                                                                                                                                                                                                                                                                                   |
| Items                            | Array of Objects | The statements on this page.                                                                                                                                                                                                                                                                                                                                |
| Items\[].Number                  | Number           | The statement number.                                                                                                                                                                                                                                                                                                                                       |
| Items\[].Status                  | String           | `Processed` or `Failed`.                                                                                                                                                                                                                                                                                                                                    |
| Items\[].StatementDate           | String           | The statement date (ISO `yyyy-MM-dd`).                                                                                                                                                                                                                                                                                                                      |
| Items\[].PayPeriodId             | String           | The pay period identifier.                                                                                                                                                                                                                                                                                                                                  |
| Items\[].PayPeriodTitle          | String           | The pay period display title.                                                                                                                                                                                                                                                                                                                               |
| Items\[].Driver                  | Object           | Driver details: `Id`, `Name`, `Type` (`COMPANY`, `OWNER_OPERATOR`, or `CONTRACTOR`), `CompanyName` (owner operators), `SubsidiaryId`, `FleetName`.                                                                                                                                                                                                          |
| Items\[].Totals                  | Object           | Statement totals - `GrossIncome`, `NetIncome`, `LineHaul`, `Accessorials`, `Echecks`, `ServiceFee`, `DriverPayment`, `Deductions`, `Reimbursements`, `Credits`, `Escrow`, `Fuel`, `Tolls`, `Bonus`, `Shortfall`, `DailyPay`, `DailyPerDiem`, `StatementPerDiem`, `TripValue` (all Money), plus `NumberOfTrips`, `LoadedMiles`, `EmptyMiles`, `HoursWorked`. |
| Items\[].LineItems               | Array of Objects | The individual pay and deduction line items.                                                                                                                                                                                                                                                                                                                |
| Items\[].LineItems\[].Category   | String           | The line-item type display name (e.g. "Per Trip", "Accessorial", "Fuel", "Deduction").                                                                                                                                                                                                                                                                      |
| Items\[].LineItems\[].Title      | String           | The line-item title.                                                                                                                                                                                                                                                                                                                                        |
| Items\[].LineItems\[].PolicyName | String           | The originating pay-policy name. Null for statement-level and deduction items.                                                                                                                                                                                                                                                                              |
| Items\[].LineItems\[].TripNumber | String           | The trip this item belongs to. Null for statement-level and deduction items.                                                                                                                                                                                                                                                                                |
| Items\[].LineItems\[].LoadNumber | String           | The load this item belongs to. Null for statement-level and deduction items.                                                                                                                                                                                                                                                                                |
| Items\[].LineItems\[].Amount     | Money            | The line-item amount.                                                                                                                                                                                                                                                                                                                                       |
| Items\[].LineItems\[].SubLines   | Array of Objects | Sub-lines: `Description`, `Quantity`, `Rate`, `Amount`.                                                                                                                                                                                                                                                                                                     |

### Example Response

```json theme={null}
{
  "Page": 0,
  "PageSize": 50,
  "Total": 1,
  "Items": [
    {
      "Number": 10432,
      "Status": "Processed",
      "StatementDate": "2026-06-20",
      "PayPeriodId": "5d2c1b7a-9f3e-4c8a-8b1d-1a2b3c4d5e6f",
      "PayPeriodTitle": "Jun 16 - Jun 30, 2026",
      "Driver": {
        "Id": "2e17c4d3-202d-4f27-b2fa-711c57435c5b",
        "Name": "John Carter",
        "Type": "OWNER_OPERATOR",
        "CompanyName": "Carter Trucking LLC",
        "SubsidiaryId": "a1b2c3d4-0000-0000-0000-000000000001",
        "FleetName": "West Fleet"
      },
      "Totals": {
        "GrossIncome": { "Amount": 4200.00, "Currency": 840 },
        "NetIncome": { "Amount": 3560.50, "Currency": 840 },
        "LineHaul": { "Amount": 4000.00, "Currency": 840 },
        "Accessorials": { "Amount": 200.00, "Currency": 840 },
        "Deductions": { "Amount": 639.50, "Currency": 840 },
        "Fuel": { "Amount": 400.00, "Currency": 840 },
        "NumberOfTrips": 2,
        "LoadedMiles": 1180.0,
        "EmptyMiles": 95.0,
        "HoursWorked": 0.0
      },
      "LineItems": [
        {
          "Category": "Per Trip",
          "Title": "Line Haul",
          "PolicyName": "OO 70% Line Haul",
          "TripNumber": "TRIP-88213",
          "LoadNumber": "L-55021",
          "Amount": { "Amount": 2800.00, "Currency": 840 },
          "SubLines": [
            { "Description": "70% of $4,000.00", "Quantity": "1", "Rate": "0.70", "Amount": { "Amount": 2800.00, "Currency": 840 } }
          ]
        },
        {
          "Category": "Deduction",
          "Title": "Fuel Advance",
          "PolicyName": null,
          "TripNumber": null,
          "LoadNumber": null,
          "Amount": { "Amount": -400.00, "Currency": 840 },
          "SubLines": []
        }
      ]
    }
  ]
}
```

<br />

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated.


# Search drivers
Source: https://docs.alvys.com/en/api/reference/drivers/search-drivers

POST /api/p/v{version}/drivers/search
Search Alvys drivers with paginated POST filters — name, status, home terminal, license class, hire date range, current truck, and pay setup.

This endpoint provides detailed information about each driver that matches the search criteria, facilitating efficient management and retrieval of driver records. The endpoint requires specifying the API version in the URL path. This ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Body Request

The following fields can be included in the request body to filter the search results:

`<Table align={["left","left","left","left"]}>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      Status
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      Conditionally
    </td>

    <td>
      A list of statuses to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      Name
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The name of the driver to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      EmployeeId
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The employee ID of the driver to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      FleetName
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The fleet name associated with the driver. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      IsActive
    </td>

    <td>
      Boolean
    </td>

    <td>
      Conditionally
    </td>

    <td>
      Whether to filter by active drivers.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/drivers/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkplA' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 50,
  "Status": [
    "OFF DUTY"
  ],
  "Name": "",
  "EmployeeId": "",
  "FleetName": "",
  "IsActive": true
}'
```

#### Response Parameters

The following table lists the parameters included in the response for driver search requests:

| Parameter         | Type               | Description                                                                                                 |
| :---------------- | :----------------- | :---------------------------------------------------------------------------------------------------------- |
| Page              | Integer            | The current page number of the results.                                                                     |
| PageSize          | Integer            | The number of results per page.                                                                             |
| Total             | Integer            | The total number of matching drivers.                                                                       |
| Id                | String             | The unique identifier of the driver.                                                                        |
| EmployeeId        | String             | The employee ID of the driver.                                                                              |
| PhoneNumber       | String             | The phone number of the driver.                                                                             |
| UserId            | String             | The user ID associated with the driver.                                                                     |
| Email             | String             | The email address of the driver.                                                                            |
| Name              | String             | The name of the driver.                                                                                     |
| Type              | String             | The type of driver (COMPANY, OWNER\_OPERATOR, CONTRACTOR, EXTERNAL).                                        |
| SubsidiaryId      | String             | The subsidiary ID to which the driver belongs.                                                              |
| Address           | Object             | The address details of the driver.                                                                          |
| Address.Street    | String             | The street address of the driver.                                                                           |
| Address.City      | String             | The city of the driver's address.                                                                           |
| Address.State     | String             | The state of the driver's address.                                                                          |
| Address.ZipCode   | String             | The zip code of the driver's address.                                                                       |
| Status            | String             | The current status of the driver (e.g., "SLEEPING", "DRIVING", "ON DUTY", "OFF DUTY", "ONLINE", "OFFLINE"). |
| IsActive          | Boolean            | Indicates if the driver is currently active.                                                                |
| LicenseNum        | String             | The driver's license number.                                                                                |
| LicenseState      | String             | The state that issued the driver's license.                                                                 |
| LicenseCountry    | String             | The country where the driver's license was issued (USA, Canada, Mexico).                                    |
| LicenseExpiresAt  | String (Date-Time) | The expiration date of the driver's license.                                                                |
| MedicalExpiresAt  | String (Date-Time) | The expiration date of the driver's medical certificate.                                                    |
| HiredAt           | String (Date-Time) | The date when the driver was hired.                                                                         |
| TerminatedAt      | String (Date-Time) | The date when the driver was terminated, if applicable.                                                     |
| Notes             | Array              | An optional list of notes related to the driver.                                                            |
| Notes.id          | String             | The unique identifier of the note.                                                                          |
| Notes.Description | String             | The description of the note.                                                                                |
| Notes.NoteType    | String             | The type of the note.                                                                                       |
| Notes.Time        | String (Date-Time) | The time the note was created.                                                                              |
| Notes.User        | String             | The user who created the note.                                                                              |
| Fleet             | Object             | The fleet information associated with the driver.                                                           |
| Fleet.Id          | String             | The unique identifier of the fleet.                                                                         |
| Fleet.Name        | String             | The name of the fleet.                                                                                      |
| References        | Array              | An optional list of custom references associated with the driver.                                           |
| CreatedAt         | String (Date-Time) | The date and time when the driver was created in Alvys.                                                     |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Upload driver document
Source: https://docs.alvys.com/en/api/reference/drivers/upload-driver-document

POST /api/p/v{version}/drivers/{driverId}/document
Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: License, Medical, Driver License, Driver Sheet, Drug Test, Operating Authority, Completed W9 Tax Form (W9 Form), Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: License, Medical, Driver License, Driver Sheet, Drug Test, Operating Authority, Completed W9 Tax Form (W9 Form), Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific driver record. Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`, `image/gif`
* **Allowed Document Types:** License, DriverLicense, DriverSheet, Drug Test, Medical *(suggested rename: Medical Card)*, Operating Authority, Completed W9 Tax Form (W9 Form), Other Documents

***

### Parameters

| Parameter  | In   | Type   | Required | Description                     |
| ---------- | ---- | ------ | -------- | ------------------------------- |
| `driverId` | path | string | Yes      | Unique identifier of the driver |
| `version`  | path | string | Yes      | API version (e.g., `1.0`)       |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG). Max size 25 MB.                         |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/drivers/{driverId}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@Driver_License.pdf" \
  -F "DocumentType=License"
```

***

### Response Body

| Name             | Type    | Description                                                                 |
| ---------------- | ------- | --------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                  |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (1757343192)           |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                   |
| `AttachmentSize` | integer | Size of the file in bytes                                                   |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded                                    |
| `ParentId`       | string  | Identifier of the parent entity (e.g., driverId, loadNumber, tripId)        |
| `ParentType`     | string  | Entity type the document is attached to (e.g., Driver, Load, Trip, Trailer) |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "4b5c38bd-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "DriverLicense-1757343192.pdf",
  "AttachmentType": "License",
  "AttachmentSize": 5245329,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "DR12345",
  "ParentType": "Driver"
}
```

<br />

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **driverId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Get fuel transaction
Source: https://docs.alvys.com/en/api/reference/fuel/get-fuel-transaction

GET /api/p/v{version}/fuel/{id}
Retrieve a single fuel transaction by ID from Alvys, including card number, driver, unit, gallons, price per gallon, location, and posted totals.

The endpoint for retrieving fuel information by ID requires specifying the fuel entry's unique ID and the API version in the URL path. This ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| version   | String | Yes      | The API version to use.                  |
| id        | String | Yes      | The unique identifier of the fuel entry. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/fuel/{id}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{id}` with the actual fuel ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/fuel/43000ba1-b001-408d-b00f-c00f8004add' \
--header 'Authorization: Bearer eLOETt0hFmWxz_1VBt_oYx9YuSVTWCbZjjNUz8DTKN_EPhH12hs3al...'
```

### Response Parameters

The following table lists the parameters included in the response for the fuel-related request:

| Parameter              | Type               | Description                                                      |
| ---------------------- | ------------------ | ---------------------------------------------------------------- |
| Id                     | String             | The unique identifier of the fuel transaction.                   |
| TransactionId          | String             | The transaction ID.                                              |
| SubsidiaryId           | String             | The subsidiary ID associated with the transaction.               |
| SubsidiaryName         | String             | The name of the subsidiary associated with the transaction.      |
| TruckId                | String             | The unique identifier of the truck.                              |
| TruckNumber            | String             | The truck number associated with the transaction.                |
| DriverId               | String             | The unique identifier of the driver.                             |
| DriverName             | String             | The name of the driver.                                          |
| OwnerOperatorId        | String             | The unique identifier of the owner-operator.                     |
| OwnerOperatorName      | String             | The name of the owner-operator.                                  |
| Source                 | String             | The name of the fuel card provider.                              |
| Type                   | String             | The raw fuel type provided by the fuel provider.                 |
| Category               | String             | The internal fuel category (e.g., Diesel, DEF, Cash Advance).    |
| Description            | String             | The fuel product description provided by the fuel card provider. |
| Location               | Object             | The location details of the transaction.                         |
| Location.Id            | String             | The unique identifier of the location.                           |
| Location.Name          | String             | The name of the location.                                        |
| Location.City          | String             | The city of the location.                                        |
| Location.State         | String             | The state of the location.                                       |
| Location.Address       | String             | The address of the location.                                     |
| Location.Country       | String             | The country of the location.                                     |
| FuelTotal              | Object             | The total fuel amount.                                           |
| FuelTotal.Amount       | Number             | The amount of fuel.                                              |
| FuelTotal.Currency     | Integer            | The currency of the fuel amount.                                 |
| Fees                   | Object             | The total fees.                                                  |
| Fees.Amount            | Number             | The amount of fees.                                              |
| Fees.Currency          | Integer            | The currency of the fees amount.                                 |
| Discounts              | Object             | The total discounts.                                             |
| Discounts.Amount       | Number             | The amount of discounts.                                         |
| Discounts.Currency     | Integer            | The currency of the discounts amount.                            |
| Advances               | Object             | The total advances.                                              |
| Advances.Amount        | Number             | The amount of advances.                                          |
| Advances.Currency      | Integer            | The currency of the advances amount.                             |
| Total                  | Object             | The total amount including fuel, fees, discounts, and advances.  |
| Total.Amount           | Number             | The total amount.                                                |
| Total.Currency         | Integer            | The currency of the total amount.                                |
| Quantity               | Object             | Details of the fuel quantity purchased.                          |
| Quantity.Value         | Number             | The numeric value of the fuel purchased.                         |
| Quantity.UnitOfMeasure | String             | The unit of measure (e.g., Gallons).                             |
| TransactionDate        | String (date-time) | The date and time of the fuel transaction.                       |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version and fuel ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search fuel transactions
Source: https://docs.alvys.com/en/api/reference/fuel/search-fuel-transactions

POST /api/p/v{version}/fuel/search
Search fuel transactions with paginated POST filters — card, driver, unit, date range, fuel type, and merchant, returning gallons, price, and totals.

The endpoint for searching fuel transactions requires specifying the API version in the URL path. This ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body

The following fields are required in the request body to filter the search results:

`<Table align={["left","left","left","left"]}>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      No
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.
      PageSize must be greater than 0 and cannot exceed 500.
    </td>
  </tr>

  <tr>
    <td>
      FuelCardNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The fuel card number used for the transactions. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TruckNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The truck number associated with the transactions.This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange
    </td>

    <td>
      Object
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The date range for the transactions.
      This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange.Start
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The start date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TransactionRange.End
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The end date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/fuel/search' \
--header 'Authorization: Bearer eP90PNFxr_y74mLOETt0hFmWxz_1VBt_oYx9YuSNUz8....' \
--header 'Content-Type: application/json' \
--data '{ 
  "Page": 0,
  "PageSize": 100,
  "FuelCardNumber": "",
  "TruckNumber": "",
  "TransactionRange": {
     "Start": "2022-07-29T15:33:17.224Z",
     "End": "2025-07-29T15:33:17.224Z"
  }
}'
```

### Response Parameters

The following table lists the parameters included in the response for fuel transaction search requests:

| Parameter                    | Type               | Description                                                      |
| ---------------------------- | ------------------ | ---------------------------------------------------------------- |
| Page                         | Integer            | The current page number of the results.                          |
| PageSize                     | Integer            | The number of results per page.                                  |
| Total                        | Integer            | The total number of matching fuel transactions.                  |
| Items                        | Array of Objects   | The list of fuel transaction records matching the criteria.      |
| Items.Id                     | String             | The unique identifier of the fuel transaction.                   |
| Items.TransactionId          | String             | The transaction ID.                                              |
| Items.SubsidiaryId           | String             | The subsidiary ID associated with the transaction.               |
| Items.SubsidiaryName         | String             | The name of the subsidiary associated with the transaction.      |
| Items.TruckId                | String             | The unique identifier of the truck.                              |
| Items.TruckNumber            | String             | The truck number associated with the transaction.                |
| Items.DriverId               | String             | The unique identifier of the driver.                             |
| Items.DriverName             | String             | The name of the driver.                                          |
| Items.OwnerOperatorId        | String             | The unique identifier of the owner-operator.                     |
| Items.OwnerOperatorName      | String             | The name of the owner-operator.                                  |
| Items.Source                 | String             | The name of the fuel card provider.                              |
| Items.Type                   | String             | The raw fuel type provided by the fuel provider.                 |
| Items.Category               | String             | The internal fuel category (e.g., Diesel, DEF, Cash Advance).    |
| Items.Description            | String             | The fuel product description provided by the fuel card provider. |
| Items.Location               | Object             | The location details of the transaction.                         |
| Items.Location.Id            | String             | The unique identifier of the location.                           |
| Items.Location.Name          | String             | The name of the location.                                        |
| Items.Location.City          | String             | The city of the location.                                        |
| Items.Location.State         | String             | The state of the location.                                       |
| Items.Location.Address       | String             | The address of the location.                                     |
| Items.Location.Country       | String             | The country of the location.                                     |
| Items.FuelTotal              | Object             | The total fuel amount.                                           |
| Items.FuelTotal.Amount       | Number             | The amount of fuel.                                              |
| Items.FuelTotal.Currency     | Integer            | The currency of the fuel amount.                                 |
| Items.Fees                   | Object             | The total fees.                                                  |
| Items.Fees.Amount            | Number             | The amount of fees.                                              |
| Items.Fees.Currency          | Integer            | The currency of the fees amount.                                 |
| Items.Discounts              | Object             | The total discounts.                                             |
| Items.Discounts.Amount       | Number             | The amount of discounts.                                         |
| Items.Discounts.Currency     | Integer            | The currency of the discounts amount.                            |
| Items.Advances               | Object             | The total advances.                                              |
| Items.Advances.Amount        | Number             | The amount of advances.                                          |
| Items.Advances.Currency      | Integer            | The currency of the advances amount.                             |
| Items.Total                  | Object             | The total amount including fuel, fees, discounts, and advances.  |
| Items.Total.Amount           | Number             | The total amount.                                                |
| Items.Total.Currency         | Integer            | The currency of the total amount.                                |
| Items.Quantity               | Object             | Details of the fuel quantity purchased.                          |
| Items.Quantity.Value         | Number             | The numeric value of the fuel purchased.                         |
| Items.Quantity.UnitOfMeasure | String             | The unit of measure (e.g., Gallons).                             |
| Items.TransactionDate        | String (date-time) | The date and time of the fuel transaction.                       |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Create carrier invoice
Source: https://docs.alvys.com/en/api/reference/invoices/create-carrier-invoice

POST /api/p/v{version}/invoices/carrier-invoice
Create a carrier invoice in Alvys for a completed load, including line items, accessorials, deductions, and the total amount owed to the carrier.

This endpoint allows factoring or payment platforms to push carrier invoices directly into Alvys and associate them with the relevant trip.

The request uses `multipart/form-data` and must contain exactly one file.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `multipart/form-data`

| Parameter            | Type   | Required | Description                                                              |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| File                 | binary | Yes      | Carrier invoice document file                                            |
| TripId               | string | Yes      | Identifier of the trip the invoice belongs to                            |
| CarrierInvoiceNumber | string | No       | Carrier-provided invoice number                                          |
| PaymentType          | string | No       | Payment type for the carrier invoice (e.g., `Standard Pay`, `Quick Pay`) |

***

### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/invoices/carrier-invoice" \
  -H "Authorization: Bearer $TOKEN" \
  -F "File=@carrier_invoice.pdf" \
  -F "TripId=trip_12345" \
  -F "CarrierInvoiceNumber=INV-93842" \
  -F "PaymentType=Standard Pay"
```

***

### Responses

#### 200 OK

Returns metadata for the uploaded carrier invoice attachment.

#### 400 Bad Request

Returned when required fields are missing or the multipart request is invalid.

#### 401 Unauthorized

Returned when authentication is missing or invalid.

#### 403 Forbidden

Returned when access to this endpoint is not allowed.

#### 404 Not Found

Returned when the specified `TripId` does not exist.

#### 413 Content Too Large

Returned when the uploaded file exceeds the allowed size limit.

#### 415 Unsupported Media Type

Returned when the uploaded file type is not supported.

### Response Body

| Field          | Type    | Description                                             |
| -------------- | ------- | ------------------------------------------------------- |
| id             | string  | Unique identifier of the uploaded document              |
| AttachmentPath | string  | File path or filename assigned during upload            |
| AttachmentType | string  | Type of the uploaded document                           |
| AttachmentSize | integer | File size in bytes                                      |
| UploadedAt     | string  | UTC timestamp when the file was uploaded                |
| ParentId       | string  | Identifier of the parent entity (TripId)                |
| ParentType     | string  | Entity type the document is attached to                 |
| UploadedBy     | string  | Identifier of the user or system that uploaded the file |
| DownloadUrl    | string  | Temporary URL to download the uploaded file             |
| ExpiresAt      | string  | Expiration timestamp for the download URL               |

***

### Example Response

```json theme={null}
{
  "id": "string",
  "AttachmentPath": "string",
  "AttachmentType": "string",
  "AttachmentSize": 0,
  "UploadedAt": "2026-03-16T13:45:12.539Z",
  "ParentId": "string",
  "ParentType": "string",
  "UploadedBy": "string",
  "DownloadUrl": "string",
  "ExpiresAt": "2026-03-16T13:45:12.539Z"
}
```

***

### Notes

* The request must include exactly **one file**.
* The uploaded document will be associated with the specified **TripId**.
* This endpoint is typically used by **factoring or payment platforms** to submit carrier invoices programmatically.
* Response schema uses the standard `AttachmentResponse` model.
* Supports `multipart/form-data` upload only.

Example integration use case:

Carriers upload invoices to a factoring/payment platform (e.g., **EPay**), which then pushes the invoice to Alvys via this endpoint so the invoice is attached to the relevant trip.

***

### Validation Notes

`PaymentType` currently accepts any string value. If the provided value does not match a configured payment type, the system defaults to **30-day payment terms**.

Recommended improvement:

The API should validate `PaymentType` against configured carrier payment terms and return **400 Bad Request** when an invalid value is provided.


# Get invoice
Source: https://docs.alvys.com/en/api/reference/invoices/get-invoice

GET /api/p/v{version}/invoices
Retrieve invoice records from Alvys by invoice number or reference, including carrier and customer invoices, line items, aging status, and payment history.

The Invoices endpoint allows you to retrieve detailed information about a specific invoice using its unique ID and version.  To ensure compatibility and stability, it is essential to include the correct version number in the URL path when making a request. For more information on versioning, refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are accepted as query parameters, except `version` which is part of the URL path:

| Parameter     | Type   | Required      | Description                                                                                                                   |
| ------------- | ------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| id            | String | Conditionally | The unique Alvys identifier of the invoice. This field is required if the other conditionally required fields are left empty. |
| invoiceNumber | String | Conditionally | The invoice number to retrieve details. This field is required if the other conditionally required fields are left empty.     |
| version       | String | Yes           | The API version to interact with.                                                                                             |

#### Example CURL request

CURL Example using Invoice ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/invoices?id={invoiceId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

CURL Example using Invoice Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/invoices?invoiceNumber={invoiceNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{invoiceNumber}` with the actual invoice number, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

Using Invoice ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/invoices?id=15fd1695595a48a48163490e3f21ddd6' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpX....'
```

Using Invoice Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/invoices?invoiceNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpX....'
```

### Response Parameters

The following table lists the parameters included in the response for invoice-related requests.

| Parameter                        | Type               | Description                                                                             |
| -------------------------------- | ------------------ | --------------------------------------------------------------------------------------- |
| Id                               | String             | The unique identifier of the invoice.                                                   |
| Number                           | String             | The invoice number.                                                                     |
| Type                             | String             | The type of the invoice (LoadInvoice, OrderInvoice, SummaryInvoice, StandaloneInvoice). |
| Status                           | String             | The current status of the invoice (Draft, AwaitingPayment, Paid).                       |
| CreatedDate                      | String (Date-Time) | The date and time when the invoice was created.                                         |
| InvoicedDate                     | String (Date-Time) | The date and time when the invoice was issued.                                          |
| DueDate                          | String (Date-Time) | The due date for the invoice payment.                                                   |
| PaidDate                         | String (Date-Time) | The date when the invoice was fully paid.                                               |
| Total                            | Object             | The total amount of the invoice.                                                        |
| Total.Amount                     | Number             | The monetary value of the total amount.                                                 |
| Total.Currency                   | Integer            | The currency in which the invoice is issued.                                            |
| AmountPaid                       | Object             | The amount that has been paid towards the invoice.                                      |
| AmountPaid.Amount                | Number             | The monetary value of the amount paid.                                                  |
| AmountPaid.Currency              | Integer            | The currency in which the payment was made.                                             |
| RemainingBalance                 | Object             | The remaining balance due on the invoice.                                               |
| RemainingBalance.Amount          | Number             | The monetary value of the remaining balance.                                            |
| RemainingBalance.Currency        | Integer            | The currency in which the balance is due.                                               |
| OverPaymentAmount                | Object             | The overpayment amount if any.                                                          |
| OverPaymentAmount.Amount         | Number             | The monetary value of the overpayment.                                                  |
| OverPaymentAmount.Currency       | Integer            | The currency in which the overpayment was made.                                         |
| IsSubmitted                      | Boolean            | Indicates if the invoice has been submitted.                                            |
| LastSendDate                     | String (Date-Time) | The last date and time when the invoice was sent.                                       |
| SupplementalInvoiceType          | String             | The type of supplemental invoice if applicable.                                         |
| Vendor                           | Object             | Vendor details associated with the invoice.                                             |
| Vendor.Id                        | String             | The unique identifier of the vendor.                                                    |
| Vendor.Name                      | String             | The name of the vendor.                                                                 |
| Vendor.RemitAddress              | Object             | The remit address of the vendor.                                                        |
| Vendor.RemitAddress.Street       | String             | The street address of the vendor.                                                       |
| Vendor.RemitAddress.City         | String             | The city of the vendor's address.                                                       |
| Vendor.RemitAddress.State        | String             | The state of the vendor's address.                                                      |
| Vendor.RemitAddress.ZipCode      | String             | The zip code of the vendor's address.                                                   |
| Vendor.RemitEmail                | String             | The email address for remittances to the vendor.                                        |
| Vendor.RemitPhone                | String             | The phone number for remittances to the vendor.                                         |
| Customer                         | Object             | Customer details associated with the invoice.                                           |
| Customer.Id                      | String             | The unique identifier of the customer.                                                  |
| Customer.Name                    | String             | The name of the customer.                                                               |
| Customer.EmailAddresses          | Array of Strings   | The list of email addresses for the customer.                                           |
| Customer.PhoneNumbers            | Array of Strings   | The list of phone numbers for the customer.                                             |
| Customer.BillingAddress          | Object             | The billing address of the customer.                                                    |
| Customer.BillingAddress.Street   | String             | The street address of the customer.                                                     |
| Customer.BillingAddress.City     | String             | The city of the customer's billing address.                                             |
| Customer.BillingAddress.State    | String             | The state of the customer's billing address.                                            |
| Customer.BillingAddress.ZipCode  | String             | The zip code of the customer's billing address.                                         |
| Customer.ShippingAddress         | Object             | The shipping address of the customer.                                                   |
| Customer.ShippingAddress.Street  | String             | The street address of the customer.                                                     |
| Customer.ShippingAddress.City    | String             | The city of the customer's shipping address.                                            |
| Customer.ShippingAddress.State   | String             | The state of the customer's shipping address.                                           |
| Customer.ShippingAddress.ZipCode | String             | The zip code of the customer's shipping address.                                        |
| LineItems                        | Array of Objects   | The line items included in the invoice.                                                 |
| LineItems.Id                     | String             | The unique identifier of the line item.                                                 |
| LineItems.Name                   | String             | The name of the line item.                                                              |
| LineItems.Amount                 | Object             | The amount associated with the line item.                                               |
| LineItems.Amount.Amount          | Number             | The monetary value of the line item.                                                    |
| LineItems.Amount.Currency        | Integer            | The currency in which the line item is priced.                                          |
| LineItems.Rate                   | Object             | The rate details for the line item.                                                     |
| LineItems.Rate.UnitOfMeasurement | String             | The unit of measurement for the rate (e.g., hours, miles).                              |
| LineItems.Rate.Units             | Number             | The number of units billed.                                                             |
| LineItems.Rate.Rate              | Number             | The rate per unit.                                                                      |
| LineItems.LoadNumber             | String             | The load number associated with the line item.                                          |
| LineItems.CustomerId             | String             | The customer ID associated with the line item.                                          |
| LineItems.Category               | String             | The category of the line item.                                                          |
| Loads                            | Array of Objects   | The loads associated with the invoice.                                                  |
| Loads.Id                         | String             | The unique identifier of the load.                                                      |
| Loads.LoadNumber                 | String             | The load number associated with the invoice.                                            |
| Loads.SubsidiaryName             | String             | The name of the subsidiary associated with the load.                                    |
| Loads.Source                     | String             | The source of the load.                                                                 |
| Loads.OrderNumber                | String             | The order number associated with the load.                                              |
| Loads.PONumber                   | String             | The purchase order number associated with the load.                                     |
| Payments                         | Array of Objects   | The payments made against the invoice.                                                  |
| Payments.Id                      | String             | The unique identifier of the payment.                                                   |
| Payments.PaymentDate             | String (Date-Time) | The date and time when the payment was made.                                            |
| Payments.Amount                  | Object             | The amount paid in the payment.                                                         |
| Payments.Amount.Amount           | Number             | The monetary value of the payment.                                                      |
| Payments.Amount.Currency         | Integer            | The currency in which the payment was made.                                             |
| Payments.CheckNumber             | String             | The check number associated with the payment.                                           |
| Payments.PaymentReference        | String             | The payment reference number.                                                           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits)  page.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Record carrier payment
Source: https://docs.alvys.com/en/api/reference/invoices/record-carrier-payment

POST /api/p/v{version}/invoices/carrier-payments
Record a carrier payment against a trip. Idempotent on `ReferenceNumber` — re-submitting the same reference returns the current state without creating a duplicate payment.

When recorded payments fully cover the carrier payable, the trip transitions to `Completed`. Partial payments leave the trip status unchanged.

This endpoint allows external systems (for example factoring or payment platforms) to record a carrier payment against a trip in Alvys.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `application/json-patch+json`

| Field           | Type               | Required | Description                                                            |
| --------------- | ------------------ | -------- | ---------------------------------------------------------------------- |
| TripId          | string             | Yes      | Identifier of the trip for which the carrier payment is being recorded |
| Amount          | object             | Yes      | Payment amount object                                                  |
| Amount.Amount   | number             | Yes      | Payment amount value                                                   |
| Amount.Currency | integer            | Yes      | Currency identifier                                                    |
| PaymentDate     | string (date-time) | Yes      | Date when the payment was made                                         |
| ReferenceNumber | string             | Yes      | External reference number for the payment                              |
| PaymentMethod   | string             | No       | Payment method used (e.g., Check, ACH, Wire)                           |
| CheckNumber     | string             | No       | Check number if payment method is check                                |
| Note            | string             | No       | Additional note related to the payment                                 |
| MarkAsPaid      | boolean            | No       | Indicates whether the trip should be marked as fully paid              |

### Example Request

```json theme={null}
{
  "TripId": "string",
  "Amount": {
    "Amount": 0,
    "Currency": 0
  },
  "PaymentDate": "2026-03-16T13:48:19.920Z",
  "ReferenceNumber": "string",
  "PaymentMethod": "string",
  "CheckNumber": "string",
  "Note": "string",
  "MarkAsPaid": true
}
```

### Response Body

| Field           | Type   | Description                                    |
| --------------- | ------ | ---------------------------------------------- |
| TripId          | string | Identifier of the trip                         |
| TripNumber      | string | Trip number associated with the payment        |
| Status          | string | Current trip status                            |
| CarrierPayments | array  | List of carrier payments recorded for the trip |

#### CarrierPayments Object

| Field           | Type    | Description                        |
| --------------- | ------- | ---------------------------------- |
| Id              | string  | Unique identifier of the payment   |
| Amount          | object  | Payment amount object              |
| Amount.Amount   | number  | Payment amount value               |
| Amount.Currency | integer | Currency identifier                |
| PaymentDate     | string  | Date when the payment was recorded |
| ReferenceNumber | string  | Payment reference number           |
| PaymentMethod   | string  | Payment method used                |
| CheckNumber     | string  | Check number if applicable         |

### Example Response

```json theme={null}
{
  "TripId": "string",
  "TripNumber": "string",
  "Status": "string",
  "CarrierPayments": [
    {
      "Id": "string",
      "Amount": {
        "Amount": 0,
        "Currency": 0
      },
      "PaymentDate": "2026-03-16T13:48:19.924Z",
      "ReferenceNumber": "string",
      "PaymentMethod": "string",
      "CheckNumber": "string"
    }
  ]
}
```


# Record customer payment
Source: https://docs.alvys.com/en/api/reference/invoices/record-customer-payment

POST /api/p/v{version}/invoices/customer-payments
Record a customer payment against one or more customer invoices in Alvys, including check or ACH reference, amount, deposit date, and payment terms.

This endpoint allows external systems to post customer payments into Alvys and apply them to the corresponding load.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `application/json-patch+json`

| Field           | Type               | Required | Description                                                    |
| --------------- | ------------------ | -------- | -------------------------------------------------------------- |
| LoadNumber      | string             | Yes      | Load number the payment should be applied to                   |
| Amount          | object             | Yes      | Payment amount object                                          |
| Amount.Amount   | number             | Yes      | Payment amount value                                           |
| Amount.Currency | integer            | Yes      | Currency identifier                                            |
| CheckNumber     | string             | No       | Check number if the payment method uses a check                |
| InvoiceNumber   | string             | No       | Invoice number associated with the payment                     |
| Note            | string             | No       | Additional note related to the payment                         |
| PaymentDate     | string (date-time) | Yes      | Date when the payment was made                                 |
| PaymentMethod   | string             | No       | Payment method used (for example Check, ACH, Wire)             |
| ReferenceNumber | string             | Yes      | External reference number for idempotency and payment tracking |

### Example Request

```json theme={null}
{
  "LoadNumber": "string",
  "Amount": {
    "Amount": 0,
    "Currency": 0
  },
  "PaymentDate": "2026-03-16T13:57:56.427Z",
  "ReferenceNumber": "string",
  "InvoiceNumber": "string",
  "PaymentMethod": "string",
  "CheckNumber": "string",
  "Note": "string"
}
```

### Response Body

| Field                  | Type    | Description                                    |
| ---------------------- | ------- | ---------------------------------------------- |
| Id                     | string  | Unique identifier of the recorded payment      |
| LoadNumber             | string  | Load number the payment was applied to         |
| Status                 | string  | Current load status after applying the payment |
| TotalPaid              | object  | Total amount paid by the customer to date      |
| TotalPaid.Amount       | number  | Monetary amount                                |
| TotalPaid.Currency     | integer | Currency identifier                            |
| TotalBillable          | object  | Total billable amount for the load             |
| TotalBillable.Amount   | number  | Monetary amount                                |
| TotalBillable.Currency | integer | Currency identifier                            |

### Notes

* This endpoint records **customer payments against loads**.
* The request body content type exposed by the API is `application/json-patch+json`.
* `ReferenceNumber` is required and is used for **idempotency**. Repeating the same `ReferenceNumber` for the same load returns the original payment instead of creating a duplicate.
* This endpoint accepts payments only when the load is in one of these statuses:

  * `Invoiced`
  * `Completed`
  * `Financed`
* Loads in non-payable statuses such as `Dispatched` are rejected with:

```text theme={null}
400 Bad Request
Load must be in one of: Invoiced, Completed, Financed.
```

* If the `LoadNumber` does not exist, the endpoint returns:

```text theme={null}
404 Not Found
```

* If `Amount.Amount` is negative or zero, the endpoint returns:

```text theme={null}
400 Bad Request
Amount must be greater than zero.
```

* If `ReferenceNumber` is empty or omitted, the endpoint returns:

```text theme={null}
400 Bad Request
The ReferenceNumber field is required.
```


# Record invoice financing
Source: https://docs.alvys.com/en/api/reference/invoices/record-invoice-financing

POST /api/p/v{version}/invoices/financing
Record a factoring or invoice financing event in Alvys for one or more carrier invoices, including funder, funded amount, reserve, and remittance details.

This endpoint records a financing transaction for a load.

Financing represents funds advanced against an invoice, typically by a factoring provider.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `application/json-patch+json`

| Field               | Type               | Required | Description                                                                     |
| ------------------- | ------------------ | -------- | ------------------------------------------------------------------------------- |
| LoadNumber          | string             | Yes      | Load number the financing should be applied to                                  |
| AmountFunded        | number             | Yes      | Amount funded for the load                                                      |
| Fee                 | number             | No       | Financing fee associated with the transaction                                   |
| DateFunded          | string (date-time) | No       | Date when the financing was issued. Defaults to the current UTC time if omitted |
| ReserveEscrowAmount | number             | No       | Amount retained in reserve or escrow                                            |
| ReferenceNumber     | string             | Yes      | External reference number used for idempotency and tracking                     |

### Example Request

```json id="gk3w1f" theme={null}
{
  "LoadNumber": "string",
  "AmountFunded": 0,
  "Fee": 0,
  "DateFunded": "2026-03-16T14:15:18.848Z",
  "ReserveEscrowAmount": 0,
  "ReferenceNumber": "string"
}
```

### Response Body

| Field       | Type   | Description                                      |
| ----------- | ------ | ------------------------------------------------ |
| LoadNumber  | string | Load number the financing was applied to         |
| Status      | string | Current load status after applying the financing |
| TotalFunded | object | Total amount funded for the load                 |
| TotalFees   | object | Total financing fees recorded for the load       |

#### Money Object

| Field    | Type    | Description         |
| -------- | ------- | ------------------- |
| Amount   | number  | Monetary amount     |
| Currency | integer | Currency identifier |

### Example Response

```json id="s4p2md" theme={null}
{
  "LoadNumber": "string",
  "Status": "string",
  "TotalFunded": {
    "Amount": 0,
    "Currency": 0
  },
  "TotalFees": {
    "Amount": 0,
    "Currency": 0
  }
}
```

### Related Load Fields Updated After Successful Financing

Successful requests may update the related load status to `Financed` and increase cumulative funded / fee totals used for load payment and factoring workflows.

### Notes

* This endpoint records **financing transactions for loads**.
* The request body content type exposed by the API is `application/json-patch+json`.
* `ReferenceNumber` is required and used for **idempotency**. Repeating the same `ReferenceNumber` for the same load returns the original financing record instead of creating a duplicate.
* Successful financing requests may update the related load to financing-related status values such as `Financed`.
* Financing can only be recorded when the load is in one of the following statuses:

  * `Invoiced`
  * `Completed`
  * `Financed`
* Loads in non-payable statuses such as `Dispatched` are rejected with:

```text id="v1s9zr" theme={null}
400 Bad Request
Load must be in one of: Invoiced, Completed, Financed.
```

* If the `LoadNumber` does not exist, the endpoint returns:

```text id="hys8u4" theme={null}
404 Not Found
```

* If `AmountFunded` is negative or zero, the endpoint returns:

```text id="fzk6t1" theme={null}
400 Bad Request
AmountFunded must be greater than zero.
```

* If `Fee` is negative, the endpoint returns:

```text id="vyu1tc" theme={null}
400 Bad Request
Fee cannot be negative.
```


# Search invoices
Source: https://docs.alvys.com/en/api/reference/invoices/search-invoices

POST /api/p/v{version}/invoices/search
Search invoices with paginated POST filters — invoice type, customer, carrier, invoice number, status, aging bucket, and issued or paid date range.

The Search Invoices endpoint allows you to search and retrieve a list of invoices based on various criteria such as invoiced date range, paid date range, status, and associated load numbers. To ensure compatibility and stability, it is essential to include the correct version number in the URL path when making a request. For more information on versioning, refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| version   | String | Yes      | The API version to interact with. |

#### Request Body

The following fields are required in the request body:

| Parameter               | Type               | Required      | Description                                                                                                                                      |
| ----------------------- | ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Page                    | Integer            | Yes           | The page number for pagination.                                                                                                                  |
| PageSize                | Integer            | Yes           | The number of records per page for pagination.                                                                                                   |
| InvoicedDateRange       | Object             | Conditionally | The range of invoiced dates to filter the results. This field is required if the other conditionally required fields are left empty.             |
| InvoicedDateRange.Start | String (Date-Time) | Conditionally | The start date for the invoiced date range. This field is required if the other conditionally required fields are left empty.                    |
| InvoicedDateRange.End   | String (Date-Time) | Conditionally | The end date for the invoiced date range. This field is required if the other conditionally required fields are left empty.                      |
| InvoiceSentRange        | Object             | Conditionally | The range of invoice sent dates to filter the results. This field is required if the other conditionally required fields are left empty.         |
| InvoiceSentRange.Start  | String (Date-Time) | Conditionally | The start date for the invoice sent date range. This field is required if the other conditionally required fields are left empty.                |
| InvoiceSentRange.End    | String (Date-Time) | Conditionally | The end date for the invoice sent date range. This field is required if the other conditionally required fields are left empty.                  |
| PaidDateRange           | Object             | Conditionally | The range of paid dates to filter the results. This field is required if the other conditionally required fields are left empty.                 |
| PaidDateRange.Start     | String (Date-Time) | Conditionally | The start date for the paid date range. This field is required if the other conditionally required fields are left empty.                        |
| PaidDateRange.End       | String (Date-Time) | Conditionally | The end date for the paid date range. This field is required if the other conditionally required fields are left empty.                          |
| Status                  | Array of Strings   | Conditionally | A list of invoice statuses to filter the results. This field is required if the other conditionally required fields are left empty.              |
| LoadNumbers             | Array of Strings   | Conditionally | A list of load numbers associated with the invoices. This field is required if the other conditionally required fields are left empty.           |
| PONumbers               | Array of Strings   | Conditionally | A list of purchase order numbers associated with the invoices. This field is required if the other conditionally required fields are left empty. |
| OrderNumbers            | Array of Strings   | Conditionally | A list of order numbers associated with the invoices. This field is required if the other conditionally required fields are left empty.          |
| CustomerId              | String             | Conditionally | The customer ID to filter the results. This field is required if the other conditionally required fields are left empty.                         |

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/invoices/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiJBT...' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "InvoicedDateRange": {
     "Start": "2023-08-02T09:53:34.251Z",
     "End": "2024-08-02T09:53:34.251Z"
  },
  "PaidDateRange": {
     "Start": "2023-08-02T09:53:34.251Z",
     "End": "2024-08-02T09:53:34.251Z"
  },
  "Status": [
     "Paid"
  ],
  "LoadNumbers": [
     "123456789"
  ],
  "CustomerId": ""
}'
```

### Response Parameters

The following table lists the parameters included in the response for invoice-related requests.

| Parameter                              | Type               | Description                                                    |
| -------------------------------------- | ------------------ | -------------------------------------------------------------- |
| Page                                   | Integer            | The current page number of the result set.                     |
| PageSize                               | Integer            | The number of records per page.                                |
| Total                                  | Integer            | The total number of records matching the search criteria.      |
| Items                                  | Array of Objects   | The list of invoices that match the search criteria.           |
| Items.Id                               | String             | The unique identifier of the invoice.                          |
| Items.Number                           | String             | The invoice number.                                            |
| Items.Type                             | String             | The type of the invoice (e.g., Standard, Credit Memo).         |
| Items.Status                           | String             | The current status of the invoice (e.g., Open, Paid, Overdue). |
| Items.CreatedDate                      | String (Date-Time) | The date and time when the invoice was created.                |
| Items.InvoicedDate                     | String (Date-Time) | The date and time when the invoice was issued.                 |
| Items.DueDate                          | String (Date-Time) | The due date for the invoice payment.                          |
| Items.PaidDate                         | String (Date-Time) | The date when the invoice was fully paid.                      |
| Items.Total                            | Object             | The total amount of the invoice.                               |
| Items.Total.Amount                     | Number             | The monetary value of the total amount.                        |
| Items.Total.Currency                   | Integer            | The currency in which the invoice is issued.                   |
| Items.AmountPaid                       | Object             | The amount that has been paid towards the invoice.             |
| Items.AmountPaid.Amount                | Number             | The monetary value of the amount paid.                         |
| Items.AmountPaid.Currency              | Integer            | The currency in which the payment was made.                    |
| Items.RemainingBalance                 | Object             | The remaining balance due on the invoice.                      |
| Items.RemainingBalance.Amount          | Number             | The monetary value of the remaining balance.                   |
| Items.RemainingBalance.Currency        | Integer            | The currency in which the balance is due.                      |
| Items.OverPaymentAmount                | Object             | The overpayment amount if any.                                 |
| Items.OverPaymentAmount.Amount         | Number             | The monetary value of the overpayment.                         |
| Items.OverPaymentAmount.Currency       | Integer            | The currency in which the overpayment was made.                |
| Items.IsSubmitted                      | Boolean            | Indicates if the invoice has been submitted.                   |
| Items.LastSendDate                     | String (Date-Time) | The last date and time when the invoice was sent.              |
| Items.SupplementalInvoiceType          | String             | The type of supplemental invoice if applicable.                |
| Items.Vendor                           | Object             | Vendor details associated with the invoice.                    |
| Items.Vendor.Id                        | String             | The unique identifier of the vendor.                           |
| Items.Vendor.Name                      | String             | The name of the vendor.                                        |
| Items.Vendor.RemitAddress              | Object             | The remit address of the vendor.                               |
| Items.Vendor.RemitAddress.Street       | String             | The street address of the vendor.                              |
| Items.Vendor.RemitAddress.City         | String             | The city of the vendor's address.                              |
| Items.Vendor.RemitAddress.State        | String             | The state of the vendor's address.                             |
| Items.Vendor.RemitAddress.ZipCode      | String             | The zip code of the vendor's address.                          |
| Items.Vendor.RemitEmail                | String             | The email address for remittances to the vendor.               |
| Items.Vendor.RemitPhone                | String             | The phone number for remittances to the vendor.                |
| Items.Customer                         | Object             | Customer details associated with the invoice.                  |
| Items.Customer.Id                      | String             | The unique identifier of the customer.                         |
| Items.Customer.Name                    | String             | The name of the customer.                                      |
| Items.Customer.EmailAddresses          | Array of Strings   | The list of email addresses for the customer.                  |
| Items.Customer.PhoneNumbers            | Array of Strings   | The list of phone numbers for the customer.                    |
| Items.Customer.BillingAddress          | Object             | The billing address of the customer.                           |
| Items.Customer.BillingAddress.Street   | String             | The street address of the customer.                            |
| Items.Customer.BillingAddress.City     | String             | The city of the customer's billing address.                    |
| Items.Customer.BillingAddress.State    | String             | The state of the customer's billing address.                   |
| Items.Customer.BillingAddress.ZipCode  | String             | The zip code of the customer's billing address.                |
| Items.Customer.ShippingAddress         | Object             | The shipping address of the customer.                          |
| Items.Customer.ShippingAddress.Street  | String             | The street address of the customer.                            |
| Items.Customer.ShippingAddress.City    | String             | The city of the customer's shipping address.                   |
| Items.Customer.ShippingAddress.State   | String             | The state of the customer's shipping address.                  |
| Items.Customer.ShippingAddress.ZipCode | String             | The zip code of the customer's shipping address.               |
| Items.LineItems                        | Array of Objects   | The line items included in the invoice.                        |
| Items.LineItems.Id                     | String             | The unique identifier of the line item.                        |
| Items.LineItems.Name                   | String             | The name of the line item.                                     |
| Items.LineItems.Amount                 | Object             | The amount associated with the line item.                      |
| Items.LineItems.Amount.Amount          | Number             | The monetary value of the line item.                           |
| Items.LineItems.Amount.Currency        | Integer            | The currency in which the line item is priced.                 |
| Items.LineItems.Rate                   | Object             | The rate details for the line item.                            |
| Items.LineItems.Rate.UnitOfMeasurement | String             | The unit of measurement for the rate (e.g., hours, miles).     |
| Items.LineItems.Rate.Units             | Number             | The number of units billed.                                    |
| Items.LineItems.Rate.Rate              | Number             | The rate per unit.                                             |
| Items.LineItems.LoadNumber             | String             | The load number associated with the line item.                 |
| Items.LineItems.CustomerId             | String             | The customer ID associated with the line item.                 |
| Items.LineItems.Category               | String             | The category of the line item.                                 |
| Items.Loads                            | Array of Objects   | The loads associated with the invoice.                         |
| Items.Loads.Id                         | String             | The unique identifier of the load.                             |
| Items.Loads.LoadNumber                 | String             | The load number associated with the invoice.                   |
| Items.Loads.SubsidiaryName             | String             | The name of the subsidiary associated with the load.           |
| Items.Loads.Source                     | String             | The source of the load.                                        |
| Items.Loads.OrderNumber                | String             | The order number associated with the load.                     |
| Items.Loads.PONumber                   | String             | The purchase order number associated with the load.            |
| Items.Payments                         | Array of Objects   | The payments made against the invoice.                         |
| Items.Payments.Id                      | String             | The unique identifier of the payment.                          |
| Items.Payments.PaymentDate             | String (Date-Time) | The date and time when the payment was made.                   |
| Items.Payments.Amount                  | Object             | The amount paid in the payment.                                |
| Items.Payments.Amount.Amount           | Number             | The monetary value of the payment.                             |
| Items.Payments.Amount.Currency         | Integer            | The currency in which the payment was made.                    |
| Items.Payments.CheckNumber             | String             | The check number associated with the payment.                  |
| Items.Payments.PaymentReference        | String             | The payment reference number.                                  |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

This endpoint is subject to standard rate limiting. The default rate limit is 10 requests per minute. For more information, refer to the [Rate Limits](/en/api/guides/rate-limits) page.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Create load note
Source: https://docs.alvys.com/en/api/reference/loads/create-load-note

POST /api/p/v{version}/loads/{loadNumber}/notes
Add an internal note or comment to a load by load number, with note type and body, so dispatch and operations can log context on the load timeline.

Create a new note associated with a specific load.

Notes can be used to store operational comments, updates, or other annotations related to the load.

### Path Parameters

| Name       | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| loadNumber | string | Yes      | The unique number identifying the load.          |
| version    | string | Yes      | API version (e.g., `1.0`). Default value: `1.0`. |

### Request Body

```json theme={null}
{
  "Id": "string",
  "Description": "string",
  "NoteType": "string"
}
```

### Request Body Parameters

| Name        | Type   | Required | Description                                                                                                           |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| Id          | string | Yes      | Unique identifier of the note.                                                                                        |
| Description | string | Yes      | The text content of the note. Maximum 4000 characters.                                                                |
| NoteType    | string | Yes      | The category or type of the note. Maximum 50 characters. Must be one of: `System`, `General`, `Assignment`, `Safety`. |

### Responses

#### 201 Created

Returned when a new note is successfully created.

```json theme={null}
{
  "CreatedAt": "2026-03-16T12:54:26.203Z",
  "CreatedBy": "string",
  "CreatedById": "string",
  "Description": "string",
  "Id": "string",
  "NoteType": "string"
}
```


# Delete load note
Source: https://docs.alvys.com/en/api/reference/loads/delete-load-note

DELETE /api/p/v{version}/loads/{loadNumber}/notes/{noteId}
Delete a specific note attached to a load by note ID and load number, permanently removing the comment from the load timeline and operational history.

Delete a specific note associated with a load.

### Path Parameters

| Name       | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| loadNumber | string | Yes      | The unique number identifying the load.          |
| noteId     | string | Yes      | The unique identifier of the note to delete.     |
| version    | string | Yes      | API version (e.g., `1.0`). Default value: `1.0`. |

### Responses

#### 204 No Content

Returned when the note is successfully deleted. The response body is empty.

#### 404 Not Found

Returned when the specified `loadNumber` or `noteId` does not exist. The response body is empty.


# Get equipment types
Source: https://docs.alvys.com/en/api/reference/loads/get-equipment-types

GET /api/p/v{version}/loads/equipment-types
Returns every equipment type accepted by the Equipment Type field on load create, as an alphabetically ordered array of strings.

The endpoint for retrieving equipment types requires specifying the API version in the URL path. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

Returns every equipment type accepted by the Equipment Type field on load create, as an alphabetically ordered array of strings. This is the same closed set the create endpoint validates against, so a client should source its picker here rather than hardcoding a copy that can drift.

### Request Parameters

The version is **required** in the PATH parameters:

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| version   | String | Yes      | The API version to interact with. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads/equipment-types' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v2.0/loads/equipment-types' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

Returns a `200 OK` response with an alphabetically ordered JSON array of strings. Each value is an equipment type accepted by the Equipment Type field on load create.

#### Example Response

```json theme={null}
[
  "Auto Carrier",
  "Belt",
  "Belt Trailer",
  "Booster",
  "B-Trains",
  "Cargo Van",
  "Conestoga",
  "Container",
  "Flatbed",
  "Reefer",
  "Van"
]
```

<Note>
  The response is the full closed set (dozens of values), sorted alphabetically. The sample above is abbreviated for readability.
</Note>

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Get load
Source: https://docs.alvys.com/en/api/reference/loads/get-load

GET /api/p/v{version}/loads
Retrieve load records from Alvys by load number, including customer, rate, stops, assigned driver and truck, current status, and reference numbers.

The endpoint for retrieving loads requires specifying the API version in the URL path. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The version is **required** in the PATH parameters. The following parameters can be added as QUERY parameters to filter the results:

| Parameter   | Type   | Required      | Description                                                                                                                |
| ----------- | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| version     | String | String        | The API version to interact with.                                                                                          |
| id          | String | Conditionally | The unique Alvys identifier of the load. This field is required if the other conditionally required fields are left empty. |
| loadNumber  | String | Conditionally | Human-readable load number. This field is required if the other conditionally required fields are left empty.              |
| orderNumber | String | Conditionally | An optional external order number. This field is required if the other conditionally required fields are left empty.       |

#### Example CURL request

Example using Load ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?id={loadId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Example using Load Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?loadNumber={loadNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Example using Order Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads?orderNumber={orderNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{loadId}`, `{loadNumber}`, and `{orderNumber}` with the actual values, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

Using Load ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/loads?id=12345678964a744d5bd543647e6106f52' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

Using Load Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/loads?loadNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

Using Order Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/loads?orderNumber=GENEIC123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

The following table lists the parameters included in the response for load-related requests.

| Parameter                                     | Type              | Required | Description                                                                                                                                                                  |
| :-------------------------------------------- | :---------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                                            | String            | Yes      | The unique identifier of the load.                                                                                                                                           |
| LoadNumber                                    | String            | Yes      | Human-readable load number, unique by subsidiary.                                                                                                                            |
| OrderNumber                                   | String            | No       | An optional external order number.                                                                                                                                           |
| PONumber                                      | String            | No       | An optional external Purchase Order number.                                                                                                                                  |
| CustomerId                                    | String            | Yes      | The internal Customer ID for the load.                                                                                                                                       |
| CustomerName                                  | String            | No       | Normalized customer name for reporting purposes; can be null for some historical data.                                                                                       |
| CustomerNumber                                | String            | No       | The customer number associated with the load.                                                                                                                                |
| Status                                        | String            | Yes      | One of the following: In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, TONU, Released, Queued, Invoiced, Financed, Completed, Paid, Cancelled. |
| TenderId                                      | String            | No       | The identifier of the inbound EDI tender that created this load. `null` if the load was created manually or through a non-tender channel.                                    |
| ContractId                                    | String            | No       | Optional Customer Contract ID.                                                                                                                                               |
| CustomerType                                  | List `<String>`   | Yes      | The type of customer this load is associated with.                                                                                                                           |
| Stops                                         | Array of Objects  | Yes      | List of stops associated with the load.                                                                                                                                      |
| Fleet                                         | Object            | No       | Information about the fleet associated with the load.                                                                                                                        |
| Fleet.Id                                      | String            | No       | The unique identifier of the fleet.                                                                                                                                          |
| Fleet.Name                                    | String            | No       | The name of the fleet.                                                                                                                                                       |
| Fleet.InvoiceNumberPrefix                     | String            | No       | The invoice number prefix used by the fleet.                                                                                                                                 |
| InvoiceAs                                     | String            | Yes      | The subsidiary or company information used when invoicing this load.                                                                                                         |
| OfficeId                                      | String            | No       | This value corresponds to the internal Office ID associated with the load.                                                                                                   |
| Linehaul                                      | Object            | No       | The cost of transporting the load, excluding additional fees such as fuel surcharges or accessorials.                                                                        |
| Linehaul.Amount                               | Number            | No       | The numeric value of the linehaul charge.                                                                                                                                    |
| Linehaul.Currency                             | String            | No       | The currency of the linehaul charge.                                                                                                                                         |
| FuelSurcharge                                 | Object            | No       | The additional charge applied to cover fluctuating fuel costs.                                                                                                               |
| FuelSurcharge.Amount                          | Number            | No       | The numeric value of the fuel surcharge.                                                                                                                                     |
| FuelSurcharge.Currency                        | String            | No       | The currency of the fuel surcharge.                                                                                                                                          |
| CustomerAccessorials                          | Object            | No       | Additional charges beyond the base rate and fuel surcharge, such as detention or lumper fees.                                                                                |
| CustomerAccessorials.Amount                   | Number            | No       | The numeric value of the accessorial charges.                                                                                                                                |
| CustomerAccessorials.Currency                 | String            | No       | The currency of the accessorial charges.                                                                                                                                     |
| CustomerRate                                  | Object            | No       | Information about the rate charged to the customer for the load.                                                                                                             |
| CustomerRate.Amount                           | Number            | No       | The numeric amount of the customer rate, which includes all applicable customer accessorials like Linehaul (LH) + Fuel Surcharge (FSC) + Accessorials (ACC).                 |
| CustomerRate.Currency                         | String            | No       | The currency of the customer rate.                                                                                                                                           |
| CustomerMileage                               | Object            | No       | Information about the mileage associated with the load.                                                                                                                      |
| CustomerMileage.Distance                      | Object            | No       | Information about the distance details.                                                                                                                                      |
| CustomerMileage.Distance.Value                | Number            | No       | The numeric value of the distance.                                                                                                                                           |
| CustomerMileage.Distance.UnitOfMeasure        | String            | No       | The unit of measure for the distance, e.g., Miles.                                                                                                                           |
| CustomerMileage.Source                        | String            | No       | The source of the mileage data.                                                                                                                                              |
| CustomerMileage.ProfileId                     | String            | No       | The profile ID used for the mileage data.                                                                                                                                    |
| CustomerMileage.ProfileName                   | String            | No       | The profile name used for the mileage data.                                                                                                                                  |
| InvoicedAmount                                | Object            | No       | Information about the total amount invoiced for the load.                                                                                                                    |
| InvoicedAmount.Amount                         | Number            | No       | The numeric amount invoiced.                                                                                                                                                 |
| InvoicedAmount.Currency                       | String            | No       | The currency of the invoiced amount.                                                                                                                                         |
| Weight                                        | Object            | No       | Information about the weight of the load.                                                                                                                                    |
| Weight.Value                                  | Number            | No       | The numeric value of the weight.                                                                                                                                             |
| Weight.UnitOfMeasure                          | String            | No       | The unit of measure for the weight, e.g., Kilograms.                                                                                                                         |
| Volume                                        | Object            | No       | Information about the volume of the load.                                                                                                                                    |
| Volume.Value                                  | Number            | No       | The numeric value of the volume.                                                                                                                                             |
| Volume.UnitOfMeasure                          | String            | No       | The unit of measure for the volume, e.g., Gallons.                                                                                                                           |
| ScheduledPickupAt                             | String            | No       | Scheduled pick-up date and time.                                                                                                                                             |
| ScheduledDeliveryAt                           | String            | No       | Scheduled delivery date and time.                                                                                                                                            |
| PickedUpAt                                    | String            | No       | Actual pick-up time, always in UTC.                                                                                                                                          |
| DeliveredAt                                   | String            | No       | Actual delivery time, always in UTC.                                                                                                                                         |
| InvoicedAt                                    | String            | No       | Date and time when the first invoice was generated.                                                                                                                          |
| LastInvoiceSentAt                             | String (DateTime) | No       | The timestamp of the most recent successful submission of an invoice from the Load Details page.                                                                             |
| Notes                                         | Array of Objects  | Yes      | List of notes associated with the load.                                                                                                                                      |
| CreatedAt                                     | String (DateTime) | Yes      | The date and time when the load was created.                                                                                                                                 |
| CreatedBy                                     | String            | Yes      | The user who created the load.                                                                                                                                               |
| CancelledAt                                   | String (DateTime) | No       | The date and time when the load was cancelled.                                                                                                                               |
| CancelledBy                                   | String            | No       | The user who cancelled the load.                                                                                                                                             |
| References                                    | Object            | No       | Information about references associated with the load.                                                                                                                       |
| References.Id                                 | String            | No       | The unique identifier of the reference.                                                                                                                                      |
| References.Name                               | String            | No       | The name of the reference.                                                                                                                                                   |
| References.Value                              | String            | No       | The value of the reference.                                                                                                                                                  |
| References.Type                               | String            | No       | The data type of the reference, e.g., Text, Date, Bool, or List.                                                                                                             |
| References.Access                             | String            | No       | The access level of the reference, e.g., Internal or Public.                                                                                                                 |
| CustomerServiceRepId                          | String            | No       | The unique identifier of the Customer Service Representative assigned to the load.                                                                                           |
| CustomerSalesAgentId                          | String            | No       | The unique identifier of the Customer Sales Agent assigned to the load.                                                                                                      |
| CustomerSalesManagerId                        | String            | No       | The unique identifier of the Customer Sales Manager assigned to the load.                                                                                                    |
| CustomerLoadPlannerId                         | String            | No       | The unique identifier of the Customer Load Planner assigned to the load.                                                                                                     |
| CustomerAccountManagerId                      | String            | No       | The unique identifier of the Customer Account Manager assigned to the load.                                                                                                  |
| UpdatedAt                                     | String            | No       | The date and time when the load was last updated.                                                                                                                            |
| UpdatedBy                                     | String            | No       | The user who last updated the load.                                                                                                                                          |
| PaidAt                                        | String (DateTime) | No       | Timestamp when a customer payment was recorded against this load.                                                                                                            |
| TotalPaid                                     | Object            | No       | Total amount paid by the customer to date.                                                                                                                                   |
| TotalPaid.Amount                              | Number            | No       | The numeric total amount paid by the customer to date.                                                                                                                       |
| TotalPaid.Currency                            | String            | No       | The currency of the total paid amount.                                                                                                                                       |
| Payments                                      | Array of Objects  | No       | Array of individual customer payment records.                                                                                                                                |
| Payments\[].Id                                | String            | No       | The unique identifier of the payment record.                                                                                                                                 |
| Payments\[].Amount.Amount                     | Number            | No       | The numeric amount of the payment.                                                                                                                                           |
| Payments\[].Amount.Currency                   | String            | No       | The currency of the payment amount.                                                                                                                                          |
| Payments\[].PaidAt                            | String (DateTime) | No       | The date and time when the payment was recorded.                                                                                                                             |
| TenderId                                      | String            | No       | The identifier of the inbound EDI tender that created this load. `null` if the load was created manually or through a non-tender channel.                                    |
| IsDeleted                                     | Boolean           | No       | Indicates whether the load is deleted.                                                                                                                                       |
| RequiredEquipment                             | List `<String>`   | No       | The required equipment for this load.                                                                                                                                        |
| LoadType                                      | String            | No       | The `LoadType` field indicates whether a load is `"Revenue"` or `"Non-Revenue"`.                                                                                             |
| CustomerAccessorialsDetails                   | Array of Objects  | No       | List of accessorial charges for the customer on the load.                                                                                                                    |
| CustomerAccessorialsDetails\[].Id             | String            | No       | Unique ID of the accessorial.                                                                                                                                                |
| CustomerAccessorialsDetails\[].Type           | String            | No       | Type of accessorial (e.g., Detention, Layover, Fuel Surcharge).                                                                                                              |
| CustomerAccessorialsDetails\[].Total.Amount   | Number            | No       | Total charge amount of the accessorial.                                                                                                                                      |
| CustomerAccessorialsDetails\[].Total.Currency | String            | No       | Currency of the total amount (e.g., USD).                                                                                                                                    |
| CustomerAccessorialsDetails\[].Rate.Amount    | Number            | No       | Unit rate applied to the accessorial.                                                                                                                                        |
| CustomerAccessorialsDetails\[].Rate.Currency  | String            | No       | Currency of the unit rate.                                                                                                                                                   |
| CustomerAccessorialsDetails\[].RateType       | String            | No       | How the rate is calculated (e.g., Flat, PerHour, PerMile).                                                                                                                   |
| CustomerAccessorialsDetails\[].Uom            | String            | No       | Unit of measure (e.g., Hour, Mile, Stop).                                                                                                                                    |
| CustomerAccessorialsDetails\[].Quantity       | Number            | No       | Quantity multiplied by the rate to compute the total.                                                                                                                        |
| CustomerAccessorialsDetails\[].IsPaid         | Boolean           | No       | If present, indicates whether the accessorial has been paid.                                                                                                                 |
| CustomerAccessorialsDetails\[].StopId         | String            | No       | ID of the related stop, if the accessorial is stop-specific (e.g., Detention).                                                                                               |
| CustomerAccessorialsDetails\[].CreatedAt      | String (DateTime) | No       | Timestamp when the accessorial was created (UTC).                                                                                                                            |
| CustomerAccessorialsDetails\[].UpdatedAt      | String (DateTime) | No       | Timestamp when the accessorial was last updated (UTC).                                                                                                                       |

#### 404 Not Found

**404 Not Found** is returned in two cases:

1. No load with the given ID exists for your tenant.
2. A load record exists but has no associated trips (abandoned creation). These loads are treated as non-existent by the API.

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# List load documents
Source: https://docs.alvys.com/en/api/reference/loads/list-load-documents

GET /api/p/v{version}/loads/{loadNumber}/documents
List all documents attached to a load by load number, including rate confirmations, BOLs, PODs, lumper receipts, and any customer-required paperwork.

Documents associated with a specific **Load** by its `loadNumber`.

### Request Parameters

| Parameter  | Type   | Required | Description         |
| ---------- | ------ | -------- | ------------------- |
| version    | String | Yes      | API version to use. |
| loadNumber | String | Yes      | Unique load number. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{loadNumber}` with the actual load number, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                                            |
| -------------- | ------- | -------------------------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                                     |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix).                    |
| AttachmentType | string  | Type of document (e.g., Customer Rate Confirmation).                                   |
| AttachmentSize | integer | Size of the file in bytes.                                                             |
| UploadedAt     | string  | UTC timestamp when the file was uploaded (ISO 8601).                                   |
| ParentId       | string  | Identifier of the parent entity (`loadNumber`= 10302010).                              |
| ParentType     | string  | Entity type the document is attached to (Carrier, Driver, Load, Trip, Truck, Trailer). |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.                          |
| DownloadUrl    | string  | Time-limited link (10 minutes) to download the document.                               |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl`.                                             |

***

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "c2e418d5-3125-4b14-b6b0-dcf77b0c2a93",
    "AttachmentPath": "POD-1759237626.pdf",
    "AttachmentType": "Customer Rate Confirmation",
    "AttachmentSize": 342115,
    "UploadedAt": "2025-09-30T14:02:07+00:00",
    "ParentId": "3022258",
    "ParentType": "Load",
    "UploadedBy": "7190175eecc1101e11d1111f1e1e0e11",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/CRC-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T14:12:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **loadNumber** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List load notes
Source: https://docs.alvys.com/en/api/reference/loads/list-load-notes

GET /api/p/v{version}/loads/{loadNumber}/notes
List all internal notes and comments attached to a load by load number, ordered by timestamp with the author and note type for each entry.

Retrieve all notes associated with a specific load.

Notes may include operational comments, internal updates, or other annotations added during the lifecycle of the load.

### Path Parameters

| Name       | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| loadNumber | string | Yes      | The unique number identifying the load.          |
| version    | string | Yes      | API version (e.g., `1.0`). Default value: `1.0`. |

### Response

#### 200 OK

Returns the list of notes associated with the specified load.

```json theme={null}
[
  {
    "CreatedAt": "2026-03-16T12:51:57.916Z",
    "CreatedBy": "string",
    "CreatedById": "string",
    "Description": "string",
    "Id": "string",
    "NoteType": "string"
  }
]
```

### Response Body Parameters

| Name        | Type     | Description                                                        |
| ----------- | -------- | ------------------------------------------------------------------ |
| CreatedAt   | datetime | The timestamp when the note was created.                           |
| CreatedBy   | string   | The user or system that created the note.                          |
| CreatedById | string   | The unique identifier of the user or system that created the note. |
| Description | string   | The text content of the note.                                      |
| Id          | string   | Unique identifier of the note.                                     |
| NoteType    | string   | The category or type of the note.                                  |

<br />


# Search loads
Source: https://docs.alvys.com/en/api/reference/loads/search-loads

POST /api/p/v{version}/loads/search
Search loads with paginated POST filters — customer, status, pickup and delivery date ranges, origin and destination, equipment, and reference numbers.

The endpoint for searching loads requires specifying the API version in the URL path. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](#versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body Parameters

The version is **required** in the **path** parameters. The **request body** parameters for this endpoint are listed below.

| Parameter            | Type    | Required      | Description                                                                                                                                                                                                                                                                                                                                                   |
| -------------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                 | Number  | Yes           | The page number for pagination.                                                                                                                                                                                                                                                                                                                               |
| PageSize             | Number  | Yes           | The number of items per page for pagination. PageSize must be greater than 0.                                                                                                                                                                                                                                                                                 |
| DateRange            | Object  | No            | The date range to filter the loads.                                                                                                                                                                                                                                                                                                                           |
| DateRange.Start      | String  | Yes           | The start date of the range to filter the `createdAt` loads.                                                                                                                                                                                                                                                                                                  |
| DateRange.End        | String  | No            | The end date of the range to filter the `createdAt` loads.                                                                                                                                                                                                                                                                                                    |
| Status               | Array   | Conditionally | The status of the loads to filter. This field is required if the other conditionally required fields are left empty. Statuses: \[Admin, In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, TONU, Released, Released-Carrier Paid, Carrier Paid, Trip Completed, Queued, Invoiced, Financed, Completed, Paid, Cancelled, En-Route] |
| OrderNumbers         | Array   | Conditionally | The order numbers to filter the loads. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                                                                      |
| LoadNumbers          | Array   | Conditionally | The load numbers to filter the loads. This field is required if the other conditionally required fields are left empty. The maximum number of load numbers allowed in the search body is 150.                                                                                                                                                                 |
| PONumbers            | Array   | Conditionally | The purchase order numbers to filter the loads. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                                                             |
| CustomerId           | String  | Conditionally | The customer ID to filter the loads. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                                                                        |
| UpdatedAtRange       | Object  | No            | The date range to filter loads based on their last update.                                                                                                                                                                                                                                                                                                    |
| UpdatedAtRange.Start | String  | Yes           | The start date of the range to filter the `updatedAt` loads.                                                                                                                                                                                                                                                                                                  |
| UpdatedAtRange.End   | String  | No            | The end date of the range to filter the `updatedAt` loads.                                                                                                                                                                                                                                                                                                    |
| UpdatedBy            | String  | Conditionally | The user ID of the person who last updated the loads. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                                                       |
| IncludeDeleted       | Boolean | No            | Optional flag. When set to true, the response will include both active and deleted loads (with `IsDeleted: true` for deleted items). If omitted or set to false, only active records are returned and no `IsDeleted` flags are included.                                                                                                                      |

<br />

#### Example CURL request

Use the current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/loads/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 200,
  "DateRange": {
    "Start": "2023-09-09T13:09:30.788Z",
    "End": "2024-09-09T13:09:30.788Z"
  },
  "Status": ["In Transit"],
  "UpdatedBy": "0d00f000-1b85-4ed8-000-6a000d1111db",
  "UpdatedAtRange": {
    "Start": "2024-09-09T13:09:30.788Z",
    "End": "2024-10-19T13:09:30.788Z"
  },
  "OrderNumbers": [
    "123456789"
  ],
  "LoadNumbers": [
    "123456789"
  ],
  "PONumbers": [
    "123456789"
  ],
  "CustomerId": "0e2bb9d5eae342c9bb89f7ac24f01a84"
}'
```

### Response Parameters

The following table lists the parameters included in the response for load-related requests.

| Parameter                                     | Type              | Required | Description                                                                                                                                                                  |
| :-------------------------------------------- | :---------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                                            | String            | Yes      | The unique identifier of the load.                                                                                                                                           |
| LoadNumber                                    | String            | Yes      | Human-readable load number, unique by subsidiary.                                                                                                                            |
| OrderNumber                                   | String            | No       | An optional external order number.                                                                                                                                           |
| PONumber                                      | String            | No       | An optional external Purchase Order number.                                                                                                                                  |
| CustomerId                                    | String            | Yes      | The internal Customer ID for the load.                                                                                                                                       |
| CustomerName                                  | String            | No       | Normalized customer name for reporting purposes; can be null for some historical data.                                                                                       |
| CustomerNumber                                | String            | No       | The customer number associated with the load.                                                                                                                                |
| Status                                        | String            | Yes      | One of the following: In Review, Open, Quoted, Reserved, Covered, Dispatched, In Transit, Delivered, TONU, Released, Queued, Invoiced, Financed, Completed, Paid, Cancelled. |
| TenderId                                      | String            | No       | The identifier of the inbound EDI tender that created this load. `null` if the load was created manually or through a non-tender channel.                                    |
| ContractId                                    | String            | No       | Optional Customer Contract ID.                                                                                                                                               |
| CustomerType                                  | List `<String>`   | Yes      | The type of customer this load is associated with.                                                                                                                           |
| Stops                                         | Array of Objects  | Yes      | List of stops associated with the load.                                                                                                                                      |
| Fleet                                         | Object            | No       | Information about the fleet associated with the load.                                                                                                                        |
| Fleet.Id                                      | String            | No       | The unique identifier of the fleet.                                                                                                                                          |
| Fleet.Name                                    | String            | No       | The name of the fleet.                                                                                                                                                       |
| Fleet.InvoiceNumberPrefix                     | String            | No       | The invoice number prefix used by the fleet.                                                                                                                                 |
| InvoiceAs                                     | String            | Yes      | The subsidiary or company information used when invoicing this load.                                                                                                         |
| OfficeId                                      | String            | No       | This value corresponds to the internal Office ID associated with the load.                                                                                                   |
| Linehaul                                      | Object            | No       | The cost of transporting the load, excluding additional fees such as fuel surcharges or accessorials.                                                                        |
| Linehaul.Amount                               | Number            | No       | The numeric value of the linehaul charge.                                                                                                                                    |
| Linehaul.Currency                             | String            | No       | The currency of the linehaul charge.                                                                                                                                         |
| FuelSurcharge                                 | Object            | No       | The additional charge applied to cover fluctuating fuel costs.                                                                                                               |
| FuelSurcharge.Amount                          | Number            | No       | The numeric value of the fuel surcharge.                                                                                                                                     |
| FuelSurcharge.Currency                        | String            | No       | The currency of the fuel surcharge.                                                                                                                                          |
| CustomerAccessorials                          | Object            | No       | Additional charges beyond the base rate and fuel surcharge, such as detention or lumper fees.                                                                                |
| CustomerAccessorials.Amount                   | Number            | No       | The numeric value of the accessorial charges.                                                                                                                                |
| CustomerAccessorials.Currency                 | String            | No       | The currency of the accessorial charges.                                                                                                                                     |
| CustomerRate                                  | Object            | No       | Information about the rate charged to the customer for the load.                                                                                                             |
| CustomerRate.Amount                           | Number            | No       | The numeric amount of the customer rate, which includes all applicable customer accessorials like Linehaul (LH) + Fuel Surcharge (FSC) + Accessorials (ACC).                 |
| CustomerRate.Currency                         | String            | No       | The currency of the customer rate.                                                                                                                                           |
| CustomerMileage                               | Object            | No       | Information about the mileage associated with the load.                                                                                                                      |
| CustomerMileage.Distance                      | Object            | No       | Information about the distance details.                                                                                                                                      |
| CustomerMileage.Distance.Value                | Number            | No       | The numeric value of the distance.                                                                                                                                           |
| CustomerMileage.Distance.UnitOfMeasure        | String            | No       | The unit of measure for the distance, e.g., Miles.                                                                                                                           |
| CustomerMileage.Source                        | String            | No       | The source of the mileage data.                                                                                                                                              |
| CustomerMileage.ProfileId                     | String            | No       | The profile ID used for the mileage data.                                                                                                                                    |
| CustomerMileage.ProfileName                   | String            | No       | The profile name used for the mileage data.                                                                                                                                  |
| InvoicedAmount                                | Object            | No       | Information about the total amount invoiced for the load.                                                                                                                    |
| InvoicedAmount.Amount                         | Number            | No       | The numeric amount invoiced.                                                                                                                                                 |
| InvoicedAmount.Currency                       | String            | No       | The currency of the invoiced amount.                                                                                                                                         |
| Weight                                        | Object            | No       | Information about the weight of the load.                                                                                                                                    |
| Weight.Value                                  | Number            | No       | The numeric value of the weight.                                                                                                                                             |
| Weight.UnitOfMeasure                          | String            | No       | The unit of measure for the weight, e.g., Kilograms.                                                                                                                         |
| Volume                                        | Object            | No       | Information about the volume of the load.                                                                                                                                    |
| Volume.Value                                  | Number            | No       | The numeric value of the volume.                                                                                                                                             |
| Volume.UnitOfMeasure                          | String            | No       | The unit of measure for the volume, e.g., Gallons.                                                                                                                           |
| ScheduledPickupAt                             | String            | No       | Scheduled pick-up date and time.                                                                                                                                             |
| ScheduledDeliveryAt                           | String            | No       | Scheduled delivery date and time.                                                                                                                                            |
| PickedUpAt                                    | String            | No       | Actual pick-up time, always in UTC.                                                                                                                                          |
| DeliveredAt                                   | String            | No       | Actual delivery time, always in UTC.                                                                                                                                         |
| InvoicedAt                                    | String            | No       | Date and time when the first invoice was generated.                                                                                                                          |
| LastInvoiceSentAt                             | String (DateTime) | No       | The timestamp of the most recent successful submission of an invoice from the Load Details page.                                                                             |
| Notes                                         | Array of Objects  | Yes      | List of notes associated with the load.                                                                                                                                      |
| CreatedAt                                     | String (DateTime) | Yes      | The date and time when the load was created.                                                                                                                                 |
| CreatedBy                                     | String            | Yes      | The user who created the load.                                                                                                                                               |
| CancelledAt                                   | String (DateTime) | No       | The date and time when the load was cancelled.                                                                                                                               |
| CancelledBy                                   | String            | No       | The user who cancelled the load.                                                                                                                                             |
| References                                    | Object            | No       | Information about references associated with the load.                                                                                                                       |
| References.Id                                 | String            | No       | The unique identifier of the reference.                                                                                                                                      |
| References.Name                               | String            | No       | The name of the reference.                                                                                                                                                   |
| References.Value                              | String            | No       | The value of the reference.                                                                                                                                                  |
| References.Type                               | String            | No       | The data type of the reference, e.g., Text, Date, Bool, or List.                                                                                                             |
| References.Access                             | String            | No       | The access level of the reference, e.g., Internal or Public.                                                                                                                 |
| CustomerServiceRepId                          | String            | No       | The unique identifier of the Customer Service Representative assigned to the load.                                                                                           |
| CustomerSalesAgentId                          | String            | No       | The unique identifier of the Customer Sales Agent assigned to the load.                                                                                                      |
| CustomerSalesManagerId                        | String            | No       | The unique identifier of the Customer Sales Manager assigned to the load.                                                                                                    |
| CustomerLoadPlannerId                         | String            | No       | The unique identifier of the Customer Load Planner assigned to the load.                                                                                                     |
| CustomerAccountManagerId                      | String            | No       | The unique identifier of the Customer Account Manager assigned to the load.                                                                                                  |
| UpdatedAt                                     | String            | No       | The date and time when the load was last updated.                                                                                                                            |
| UpdatedBy                                     | String            | No       | The user who last updated the load.                                                                                                                                          |
| PaidAt                                        | String (DateTime) | No       | Timestamp when a customer payment was recorded against this load.                                                                                                            |
| TotalPaid                                     | Object            | No       | Total customer payment amount recorded to date.                                                                                                                              |
| TotalPaid.Amount                              | Number            | No       | The numeric value of the total customer payment amount recorded to date.                                                                                                     |
| TotalPaid.Currency                            | String            | No       | The currency of the total customer payment amount.                                                                                                                           |
| Payments                                      | Array of Objects  | No       | Array of individual customer payment records associated with this load.                                                                                                      |
| Payments\[].Id                                | String            | Yes      | The unique identifier of the payment record.                                                                                                                                 |
| Payments\[].Amount                            | Object            | Yes      | Information about the payment amount recorded for this payment entry.                                                                                                        |
| Payments\[].Amount.Amount                     | Number            | Yes      | The numeric value of the payment amount.                                                                                                                                     |
| Payments\[].Amount.Currency                   | String            | No       | The currency of the payment amount.                                                                                                                                          |
| Payments\[].PaidAt                            | String (DateTime) | No       | Timestamp when this payment record was marked as paid.                                                                                                                       |
| IsDeleted                                     | Boolean           | No       | Indicates deletion status of the item: `true` for deleted records, `false` for active records. Only present when `includeDeleted: true`.                                     |
| RequiredEquipment                             | Array             | No       | List of equipment types required for this load, e.g., `["Dry Van"]` or `["Reefer", "Liftgate"]`.                                                                             |
| LoadType                                      | String            | No       | The `LoadType` field indicates whether a load is `"Revenue"` or `"Non-Revenue"`.                                                                                             |
| CustomerAccessorialsDetails                   | Array of Objects  | No       | List of accessorial charges for the customer on the load.                                                                                                                    |
| CustomerAccessorialsDetails\[].Id             | String            | No       | Unique ID of the accessorial.                                                                                                                                                |
| CustomerAccessorialsDetails\[].Type           | String            | No       | Type of accessorial (e.g., Detention, Layover, Fuel Surcharge).                                                                                                              |
| CustomerAccessorialsDetails\[].Total.Amount   | Number            | No       | Total charge amount of the accessorial.                                                                                                                                      |
| CustomerAccessorialsDetails\[].Total.Currency | String            | No       | Currency of the total amount (e.g., USD).                                                                                                                                    |
| CustomerAccessorialsDetails\[].Rate.Amount    | Number            | No       | Unit rate applied to the accessorial.                                                                                                                                        |
| CustomerAccessorialsDetails\[].Rate.Currency  | String            | No       | Currency of the unit rate.                                                                                                                                                   |
| CustomerAccessorialsDetails\[].RateType       | String            | No       | How the rate is calculated (e.g., Flat, PerHour, PerMile).                                                                                                                   |
| CustomerAccessorialsDetails\[].Uom            | String            | No       | Unit of measure (e.g., Hour, Mile, Stop).                                                                                                                                    |
| CustomerAccessorialsDetails\[].Quantity       | Number            | No       | Quantity multiplied by the rate to compute the total.                                                                                                                        |
| CustomerAccessorialsDetails\[].IsPaid         | Boolean           | No       | If present, indicates whether the accessorial has been paid.                                                                                                                 |
| CustomerAccessorialsDetails\[].StopId         | String            | No       | ID of the related stop, if the accessorial is stop-specific (e.g., Detention).                                                                                               |
| CustomerAccessorialsDetails\[].CreatedAt      | String (DateTime) | No       | Timestamp when the accessorial was created (UTC).                                                                                                                            |
| CustomerAccessorialsDetails\[].UpdatedAt      | String (DateTime) | No       | Timestamp when the accessorial was last updated (UTC).                                                                                                                       |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

<br />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

<br />


# Update load
Source: https://docs.alvys.com/en/api/reference/loads/update-load

PATCH /api/p/v{version}/loads/{loadNumber}
Partially update a load by load number in Alvys, changing only the supplied fields such as rate, references, equipment, assigned driver, or stop details.

The Update Load endpoint applies a partial (PATCH) update to an existing load. Today the only writable field is the **Order Number** (the partner-facing "Shipment Id"); the payload shape allows future writable fields to be added without a breaking change. Fields that are omitted from the body are left unchanged.

Updates use optimistic concurrency: you must send the load's current `ETag` in an `If-Match` header. The current `ETag` is returned on the `ETag` response header of this endpoint and of the load read endpoints. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

***

### Request Parameters

The following parameters are available in the URL path:

| Parameter  | Type   | Required | Description                            |
| ---------- | ------ | -------- | -------------------------------------- |
| version    | String | Yes      | The version of the API.                |
| loadNumber | String | Yes      | The load number of the load to update. |

The following header is required:

| Header   | Type   | Required | Description                                                                                            |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| If-Match | String | Yes      | The load's current `ETag`, for optimistic concurrency. If omitted, the request is rejected with `428`. |

***

### Request Body

| Field       | Type   | Required | Description                                                                                                                             |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| OrderNumber | String | No       | The partner-facing Order Number ("Shipment Id"). Must be 30 characters or fewer. Omit to leave it unchanged; a blank value is rejected. |

***

### Example CURL Request

```bash theme={null}
curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1/loads/{loadNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "00000000-0000-0000-0000-000000000001"' \
--data-raw '{
  "OrderNumber": "SHIP-100245"
}'
```

Replace `{loadNumber}` with the actual load number, the `If-Match` value with the load's current `ETag`, and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

***

### Response

On success the endpoint returns the updated load (the same object shape as [Get Loads](/en/api/reference/loads/get-load)), and the new optimistic-concurrency token on the `ETag` response header.

***

### Status Codes

| Code | Description                                                                                  |
| ---- | -------------------------------------------------------------------------------------------- |
| 200  | The load was updated; the response body contains the updated load.                           |
| 400  | The request body failed validation (e.g., Order Number longer than 30 characters or blank).  |
| 401  | Authentication failed or the token is missing.                                               |
| 403  | The token is not authorized to update loads.                                                 |
| 404  | No load was found for the given load number.                                                 |
| 409  | The update conflicts with the current state of the load.                                     |
| 412  | The `If-Match` ETag did not match the load's current version (it changed since you read it). |
| 428  | The `If-Match` header was not provided.                                                      |


# Upload load document
Source: https://docs.alvys.com/en/api/reference/loads/upload-load-document

POST /api/p/v{version}/loads/{loadNumber}/document
Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific **load**. Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`, `image/gif`
* **Allowed Document Types:** Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels

***

### Parameters

| Parameter    | In   | Type   | Required | Description               |
| ------------ | ---- | ------ | -------- | ------------------------- |
| `loadNumber` | path | string | Yes      | Public load number        |
| `version`    | path | string | Yes      | API version (e.g., `1.0`) |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG, GIF). Max size 25 MB.                    |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/loads/{loadNumber}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -F "File=@POD.pdf" \
  -F "DocumentType=Proof of Delivery"
```

***

### Response Body

| Name             | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (e.g., `1757343192`) |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                 |
| `AttachmentSize` | integer | Size of the file in bytes                                                 |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded (ISO 8601)                       |
| `ParentId`       | string  | Identifier of the parent entity (the `{loadNumber}`)                      |
| `ParentType`     | string  | Entity type the document is attached to (`Load`)                          |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "a1b2c3d4-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "ProofOfDelivery-1757343192.pdf",
  "AttachmentType": "Proof of Delivery",
  "AttachmentSize": 5245329,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "1006321",
  "ParentType": "Load"
}
```

#### 404 Not Found

404 Not Found is returned in two cases:

1. No load with the given ID exists for your tenant.
2. A load record exists but has no associated trips (abandoned creation). These loads are treated as non-existent by the API.

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the Rate Limits section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **loadNumber** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

Don’t forget to authorize yourself before trying a request.


# Get location
Source: https://docs.alvys.com/en/api/reference/locations/get-location

GET /api/p/v{version}/locations
Retrieve saved location records from Alvys, including shipper and consignee addresses, contact details, receiving hours, and geocoded coordinates.

The endpoint for retrieving **a single location** requires specifying the API **version** in the path and **one** identifier in the query: either `id` **or** `companyNumber`. For details on how versioning works, see the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

**Path parameters**

| Parameter     | Type   | Required               | Description                                                          |
| ------------- | ------ | ---------------------- | -------------------------------------------------------------------- |
| version       | String | Yes                    | The API version to use.                                              |
| id            | String | Conditionally required | The unique Location ID. Required if `companyNumber` is not provided. |
| companyNumber | String | Conditionally required | The company number. Required if `id` is not provided.                |

> Exactly **one** of `id` or `companyNumber` must be provided.

#### Example cURL requests

Lookup by **id**:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/locations?id=120f97b9-1aa2-4201-b1aa-24...' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Lookup by **companyNumber**:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/locations?companyNumber=MGD0012312345' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response Parameters

| Parameter               | Type              | Description                                                                                                                                              |
| ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                      | String            | Unique location identifier.                                                                                                                              |
| Name                    | String            | Location name.                                                                                                                                           |
| CompanyNumber           | String            | Company number for this location. This is provided when uploading files for that company.                                                                |
| Type                    | String            | Location type (e.g., Terminal, Shipper/Consignee, Cold Warehouse, Dry Warehouse).                                                                        |
| Status                  | String            | Location status (e.g., Active, Disabled, Inactive).                                                                                                      |
| PhysicalAddress         | Object            | Address block.                                                                                                                                           |
| PhysicalAddress.Street  | String            | Street line.                                                                                                                                             |
| PhysicalAddress.City    | String            | City.                                                                                                                                                    |
| PhysicalAddress.State   | String            | State/Province.                                                                                                                                          |
| PhysicalAddress.ZipCode | String            | ZIP/Postal code.                                                                                                                                         |
| Email                   | Array of String   | Email addresses.                                                                                                                                         |
| Phone                   | Array of String   | Phone numbers.                                                                                                                                           |
| Fax                     | String            | Fax number.                                                                                                                                              |
| DateCreated             | String (DateTime) | Creation timestamp (UTC).                                                                                                                                |
| ExternalId              | String            | External reference ID (if any).                                                                                                                          |
| Notes                   | Array of Object   | Notes attached to the location.                                                                                                                          |
| Notes\[].id             | String            | Note identifier.                                                                                                                                         |
| Notes\[].Description    | String            | Note text.                                                                                                                                               |
| Notes\[].NoteType       | String            | Type/category of the note.                                                                                                                               |
| Notes\[].Time           | String (DateTime) | Timestamp of the note (UTC).                                                                                                                             |
| Notes\[].User           | String            | Author/user who added the note.                                                                                                                          |
| References              | Array of Objects  | An optional list of custom references associated with the location. Only values whose reference definition includes the Public API surface are returned. |

#### Example Response

```json theme={null}
{
  "Id": "loc-45678",
  "Name": "Alvys Teminal Group LLC",
  "CompanyNumber": "LP-12345",
  "Type": "Terminal",
  "Status": "Active",
  "PhysicalAddress": {
    "Street": "001 Main St",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "70000"
  },
  "Email": ["terminal@acme.example"],
  "Phone": ["+1-214-555-0100"],
  "Fax": null,
  "DateCreated": "2025-09-08T16:01:26.908Z",
  "ExternalId": "EXT-001",
  "Notes": [
    {
      "id": "n-001",
      "Description": "24/7 gate access",
      "NoteType": "General",
      "Time": "2025-09-08T18:10:00Z",
      "User": "dispatch@acme.example"
    }
  ]
}
```

#### Rate Limits

All endpoints are subject to platform rate limits. See [Rate Limits](/en/api/guides/rate-limits).


# Search locations
Source: https://docs.alvys.com/en/api/reference/locations/search-locations

POST /api/p/v{version}/locations/search
Search saved shipper and consignee locations with paginated POST filters — name, city, state, zip, hours of operation, and appointment requirements.

The Locations endpoint provides detailed information about company-related sites such as Terminals, Shippers/Consignees, Cold Warehouses, and Dry Warehouses. The endpoint for **searching locations** requires specifying the API **version** in the path and providing filters in the request body. For details on API versioning, see [Versioning](/en/api/guides/versioning).

***

### Request Parameters

**Path parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

**Request body (filters + paging)**

| Parameter              | Type              | Required | Description                                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                   | Integer           | No       | Page index.                                                                                                                                                                                                                                                                                                                                         |
| PageSize               | Integer           | Yes      | Page size (must be > 0).                                                                                                                                                                                                                                                                                                                            |
| Status                 | Array of String   | No       | Filter by one or more location statuses. Allowed values (case-sensitive): `"Active"`, `"Inactive"`, `"Disabled"`, `"On Hold"`, `"Do Not Use"`. Filtering by `"Inactive"` also returns locations whose stored status is `"On Hold"` or `"Do Not Use"`. Rows filtered by `"On Hold"` or `"Do Not Use"` still return `"Inactive"` in `Items[].Status`. |
| LocationIds            | Array of String   | No       | Filter by a set of Location IDs.                                                                                                                                                                                                                                                                                                                    |
| CreatedDateRange       | Object            | No       | Filter by creation timestamp range (UTC).                                                                                                                                                                                                                                                                                                           |
| CreatedDateRange.Start | String (DateTime) | No       | Start of the date range.                                                                                                                                                                                                                                                                                                                            |
| CreatedDateRange.End   | String (DateTime) | No       | End of the date range.                                                                                                                                                                                                                                                                                                                              |

### Example cURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/locations/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "Status": ["Active", "Disabled", "Inactive", "On Hold", "Do Not Use"],
  "LocationIds": [],
  "CreatedDateRange": {
    "Start": "2025-01-01T00:00:00Z",
    "End": "2025-09-08T23:59:59Z"
  }
}'
```

***

### Response Parameters

| **Parameter**                    | **Type**          | **Description**                                                                                                                                          |
| -------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                             | integer           | The current page number.                                                                                                                                 |
| Total                            | integer           | The total number of items matching the criteria.                                                                                                         |
| PageSize                         | integer           | The number of items per page.                                                                                                                            |
| Items\[].Id                      | string            | Unique identifier of the location.                                                                                                                       |
| Items\[].Name                    | string            | Location (company site) name.                                                                                                                            |
| Items\[].CompanyNumber           | string            | Company number for this location. This is also provided when uploading files for that company.                                                           |
| Items\[].Type                    | string            | Location type (e.g., Terminal, Shipper/Consignee, Cold Warehouse, Dry Warehouse).                                                                        |
| Items\[].Status                  | string            | Location status. Supported values: `"Active"`, `"Disabled"`, `"Inactive"`.                                                                               |
| Items\[].PhysicalAddress.Street  | string            | The street line of the location’s physical address.                                                                                                      |
| Items\[].PhysicalAddress.City    | string            | The city of the location.                                                                                                                                |
| Items\[].PhysicalAddress.State   | string            | The state or province of the location.                                                                                                                   |
| Items\[].PhysicalAddress.ZipCode | string            | The postal/ZIP code of the location.                                                                                                                     |
| Items\[].Email\[]                | array of string   | A list of email addresses for the location.                                                                                                              |
| Items\[].Phone\[]                | array of string   | A list of phone numbers for the location.                                                                                                                |
| Items\[].Fax                     | string            | The fax number for the location.                                                                                                                         |
| Items\[].DateCreated             | string (datetime) | Timestamp when the location was created (UTC).                                                                                                           |
| Items\[].ExternalId              | string            | An external reference identifier, if applicable.                                                                                                         |
| Items\[].Notes\[]                | array of objects  | A list of notes attached to the location.                                                                                                                |
| Items\[].Notes\[].id             | string            | Unique identifier of the note.                                                                                                                           |
| Items\[].Notes\[].Description    | string            | The text of the note.                                                                                                                                    |
| Items\[].Notes\[].NoteType       | string            | The type/category of the note.                                                                                                                           |
| Items\[].Notes\[].Time           | string (datetime) | The timestamp when the note was created (UTC).                                                                                                           |
| Items\[].Notes\[].User           | string            | The user who created the note.                                                                                                                           |
| Items\[].References\[]           | array of objects  | An optional list of custom references associated with the location. Only values whose reference definition includes the Public API surface are returned. |

### Rate Limit

All endpoints are subject to platform rate limits. See [Rate Limits](/en/api/guides/rate-limits).


# Get maintenance record
Source: https://docs.alvys.com/en/api/reference/maintenance/get-maintenance-record

GET /api/p/v{version}/maintenance/{id}
Retrieve a single maintenance record by ID, including the truck or trailer, work order details, vendor, parts, labor cost, and completion date.

The GET Maintenance by ID API endpoint allows you to retrieve detailed information about a specific maintenance record using its unique ID. This endpoint provides comprehensive data about the maintenance record, facilitating effective asset management and tracking within the Alvys system.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| version   | String | Yes      | The API version to use.                          |
| id        | String | Yes      | The unique identifier of the maintenance record. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/maintenance/{id}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{id}` with the actual maintenance ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/maintenance/123456789a-00b0-00ae-0000-0e01234567e6f' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
```

### Response Parameters

The following table lists the parameters included in the response for maintenance-related requests:

| Parameter                | Type               | Required | Description                                                      |
| ------------------------ | ------------------ | -------- | ---------------------------------------------------------------- |
| Id                       | String             | Yes      | The unique identifier of the maintenance record.                 |
| PO                       | String             | No       | The purchase order number associated with the maintenance.       |
| Reference                | String             | No       | A reference string for the maintenance record.                   |
| RelatedAsset             | Object             | No       | Details about the related asset for the maintenance.             |
| RelatedAsset.AssetId     | String             | No       | The unique identifier of the asset.                              |
| RelatedAsset.AssetNumber | String             | No       | The asset number.                                                |
| RelatedAsset.AssetType   | String             | No       | The type of asset (e.g., Truck, Trailer).                        |
| Category                 | Object             | No       | The category of the maintenance work.                            |
| Category.Id              | String             | No       | The unique identifier of the category.                           |
| Category.Name            | String             | No       | The name of the category.                                        |
| Description              | String             | No       | A description of the maintenance work.                           |
| Comments                 | String             | No       | Additional comments or notes about the maintenance.              |
| Amount                   | Object             | No       | The total amount for the maintenance work.                       |
| Amount.Amount            | Number             | No       | The amount value.                                                |
| Amount.Currency          | Integer            | No       | The currency identifier of the amount (Money = ).                |
| RepairShop               | Object             | No       | Information about the repair shop.                               |
| RepairShop.Id            | String             | No       | The unique identifier of the repair shop.                        |
| RepairShop.Name          | String             | No       | The name of the repair shop.                                     |
| Reminders                | Array              | No       | A list of reminders associated with the maintenance.             |
| Reminders.id             | String             | No       | The unique identifier of the reminder.                           |
| Reminders.DueDate        | String (Date-Time) | No       | The due date for the reminder.                                   |
| CreatedAt                | String (Date-Time) | Yes      | The date and time when the maintenance record was created.       |
| CreatedBy                | String             | No       | The user who created the maintenance record.                     |
| ModifiedAt               | String (Date-Time) | No       | The date and time when the maintenance record was last modified. |
| ModifiedBy               | String             | No       | The user who last modified the maintenance record.               |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

<br />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by providing the driver ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search maintenance records
Source: https://docs.alvys.com/en/api/reference/maintenance/search-maintenance-records

POST /api/p/v{version}/maintenance/search
Search maintenance records with paginated POST filters — truck or trailer, work order type, vendor, service date range, and completion status.

The Search Maintenance API endpoint allows you to search for maintenance records within the Alvys system based on various criteria such as asset type, category, status, and date range. This endpoint provides detailed information about each maintenance record that matches the search criteria, facilitating efficient management and retrieval of maintenance records.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body

The following fields are required in the request body to filter the search results:

`<Table>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.\
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      TruckIds
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      Conditionally
    </td>

    <td>
      A list of truck IDs to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      TrailerIds
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      Conditionally
    </td>

    <td>
      A list of trailer IDs to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      Categories
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      Conditionally
    </td>

    <td>
      A list of categories to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      Status
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The status of the maintenance record. One of the following: `Urgent`, `Open`, `Closed`. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange
    </td>

    <td>
      Object
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The date range for the maintenance records. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange.Start
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The start date of the maintenance records range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange.End
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The end date of the maintenance records range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/maintenance/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "TruckIds": [
      "TR123456789"
  ],
  "TrailerIds": [
      ""
  ],
  "Categories": [
      "Tires"
  ],
  "Status": "Open",
  "DateRange": {
      "Start": "2021-01-23T13:36:42.021Z",
      "End": "2024-08-23T13:36:42.021Z"
  }
}'
```

### Response Parameters

The following table lists the parameters included in the response for maintenance search requests:

| Parameter                      | Type               | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                           | Integer            | Yes      | The current page number of the results.                                                                                                                                                                                                                                                                                                                                                                               |
| PageSize                       | Integer            | Yes      | The number of results per page.                                                                                                                                                                                                                                                                                                                                                                                       |
| Total                          | Integer            | Yes      | The total number of matching maintenance records.                                                                                                                                                                                                                                                                                                                                                                     |
| Items                          | Array of Objects   | Yes      | The list of maintenance records matching the criteria.                                                                                                                                                                                                                                                                                                                                                                |
| Items.Id                       | String             | Yes      | The unique identifier of the maintenance record.                                                                                                                                                                                                                                                                                                                                                                      |
| Items.PO                       | String             | No       | The purchase order number associated with the maintenance.                                                                                                                                                                                                                                                                                                                                                            |
| Items.Reference                | String             | No       | A reference string for the maintenance record.                                                                                                                                                                                                                                                                                                                                                                        |
| Items.RelatedAsset             | Object             | No       | Details about the related asset for the maintenance.                                                                                                                                                                                                                                                                                                                                                                  |
| Items.RelatedAsset.AssetId     | String             | No       | The unique identifier of the asset.                                                                                                                                                                                                                                                                                                                                                                                   |
| Items.RelatedAsset.AssetNumber | String             | No       | The asset number.                                                                                                                                                                                                                                                                                                                                                                                                     |
| Items.RelatedAsset.AssetType   | String             | No       | The type of asset (e.g., Truck, Trailer).                                                                                                                                                                                                                                                                                                                                                                             |
| Items.Category                 | Object             | No       | The category of the maintenance work.                                                                                                                                                                                                                                                                                                                                                                                 |
| Items.Category.Id              | String             | No       | The unique identifier of the category.                                                                                                                                                                                                                                                                                                                                                                                |
| Items.Category.Name            | String             | No       | The name of the category.                                                                                                                                                                                                                                                                                                                                                                                             |
| Items.Description              | String             | No       | A description of the maintenance work.                                                                                                                                                                                                                                                                                                                                                                                |
| Items.Comments                 | String             | No       | Additional comments or notes about the maintenance.                                                                                                                                                                                                                                                                                                                                                                   |
| Items.Amount                   | Object             | No       | The total amount for the maintenance work.                                                                                                                                                                                                                                                                                                                                                                            |
| Items.Amount.Amount            | Number             | No       | The amount value.                                                                                                                                                                                                                                                                                                                                                                                                     |
| Items.Amount.Currency          | Integer            | No       | The currency of the amount.                                                                                                                                                                                                                                                                                                                                                                                           |
| Items.RepairShop               | Object             | No       | Information about the repair shop.                                                                                                                                                                                                                                                                                                                                                                                    |
| Items.RepairShop.Id            | String             | No       | The unique identifier of the repair shop.                                                                                                                                                                                                                                                                                                                                                                             |
| Items.RepairShop.Name          | String             | No       | The name of the repair shop.                                                                                                                                                                                                                                                                                                                                                                                          |
| Items.Reminders                | Array              | No       | A list of reminders associated with the maintenance.                                                                                                                                                                                                                                                                                                                                                                  |
| Items.Reminders.id             | String             | No       | The unique identifier of the reminder.                                                                                                                                                                                                                                                                                                                                                                                |
| Items.Reminders.DueDate        | String (Date-Time) | No       | The due date for the reminder.                                                                                                                                                                                                                                                                                                                                                                                        |
| Items.CreatedAt                | String (Date-Time) | Yes      | The date and time when the maintenance record was created. For some maintenance records, the `CreatedAt` field may display `1970-01-01T00:00:00+00:00`. This placeholder represents the Unix Epoch and indicates that the original creation timestamp is unavailable. Users should interpret this as an unknown creation date, specific only to the `CreatedAt` field and not reflective of other timestamps or data. |
| Items.CreatedBy                | String             | No       | The user who created the maintenance record.                                                                                                                                                                                                                                                                                                                                                                          |
| Items.ModifiedAt               | String (Date-Time) | No       | The date and time when the maintenance record was last modified.                                                                                                                                                                                                                                                                                                                                                      |
| Items.ModifiedBy               | String             | No       | The user who last modified the maintenance record.                                                                                                                                                                                                                                                                                                                                                                    |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](#rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Get subsidiary
Source: https://docs.alvys.com/en/api/reference/subsidiaries/get-subsidiary

GET /api/p/v{version}/subsidiaries/{id}
Retrieve a single subsidiary of your own company by id, returning its name, type, MC and DOT numbers, default equipment type, and remit address.

Returns a single subsidiary of your own company by id. Use [List subsidiaries](/en/api/reference/subsidiaries/list-subsidiaries) when you do not already have the id.

<Note>
  This endpoint requires the `subsidiary:read` scope. It is not part of any other scope, and credentials issued before it existed do not carry it — grant it to the client before your first call. See [Authentication](/en/api/guides/authentication-1).
</Note>

A subsidiary outside your credential's subsidiary scope answers `404`, identically to one that does not exist. This is deliberate: a scoped credential cannot use this endpoint to discover which subsidiaries exist that it may not read.

### Endpoint

```
GET /api/p/v{version}/subsidiaries/{id}
```

### Request Parameters

| Parameter      | Type    | Required | Description                                                      |
| -------------- | ------- | -------- | ---------------------------------------------------------------- |
| version        | string  | Yes      | API version to use (`1.0`).                                      |
| id             | string  | Yes      | Unique identifier of the subsidiary.                             |
| includeDeleted | boolean | No       | Return the subsidiary even if soft-deleted. Defaults to `false`. |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/subsidiaries/9d4b1327-2774-d32c-fb33-87a288c2722c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response Fields

| Field                | Type   | Description                                                                                                                                                                                                                        |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                   | string | Unique identifier of the subsidiary.                                                                                                                                                                                               |
| Name                 | string | Name of the subsidiary.                                                                                                                                                                                                            |
| Type                 | string | Either `Carrier` or `Brokerage`.                                                                                                                                                                                                   |
| McNumber             | string | MC number of the subsidiary. Omitted when none is recorded.                                                                                                                                                                        |
| DotNumber            | string | DOT number of the subsidiary. Omitted when none is recorded.                                                                                                                                                                       |
| DefaultEquipmentType | string | Default equipment type for the subsidiary.                                                                                                                                                                                         |
| RemitAddress         | Object | Postal remit-to address. Postal fields only — no contact details.                                                                                                                                                                  |
| RemitAddress.Street  | string | Street line of the remit address.                                                                                                                                                                                                  |
| RemitAddress.City    | string | City of the remit address.                                                                                                                                                                                                         |
| RemitAddress.State   | string | State or province of the remit address.                                                                                                                                                                                            |
| RemitAddress.ZipCode | string | Postal code of the remit address.                                                                                                                                                                                                  |
| RemitAddress.Country | string | Country of the remit address. Publishes `US`, `CA` or `MX` for recognized spellings of those countries, otherwise the value exactly as recorded. Omitted when no country is recorded, which must not be read as the United States. |

### Example Response

**200 OK**

```json theme={null}
{
  "Id": "9d4b1327-2774-d32c-fb33-87a288c2722c",
  "Name": "Alvy's Motor",
  "Type": "Carrier",
  "McNumber": "1234567",
  "DotNumber": "2515539",
  "DefaultEquipmentType": "Van",
  "RemitAddress": {
    "Street": "201 Lomas Santa Fe Dr",
    "City": "Solana Beach",
    "State": "CA",
    "ZipCode": "92075",
    "Country": "US"
  }
}
```

### Status Codes

| Status | Description                                                          |
| ------ | -------------------------------------------------------------------- |
| 200    | Subsidiary returned.                                                 |
| 401    | Missing or invalid access token.                                     |
| 403    | Token lacks the `subsidiary:read` scope.                             |
| 404    | Subsidiary not found, or outside your credential's subsidiary scope. |
| 429    | Rate limit exceeded.                                                 |

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. See [Rate Limits](/en/api/guides/rate-limits).


# List subsidiaries
Source: https://docs.alvys.com/en/api/reference/subsidiaries/list-subsidiaries

GET /api/p/v{version}/subsidiaries
List the subsidiaries of your own company so an integration can resolve a subsidiary id to a recognizable name, MC or DOT number, and remit address.

Returns the subsidiaries of your own company. Nothing in the Alvys interface shows a subsidiary id, so this is how an integration resolves one — for example the `SubsidiaryId` a webhook subscription is scoped to, or the subsidiary a trip was tendered as.

Deleted subsidiaries are omitted unless you pass `includeDeleted=true`. A credential scoped to specific subsidiaries only ever receives those, and `includeDeleted` cannot widen that scope.

A company with no subsidiaries returns `200` and an empty array, not `404`. The list addresses no single resource, so there is nothing to be missing.

<Note>
  This endpoint requires the `subsidiary:read` scope. It is not part of any other scope, and credentials issued before it existed do not carry it — grant it to the client before your first call. See [Authentication](/en/api/guides/authentication-1).
</Note>

### Endpoint

```
GET /api/p/v{version}/subsidiaries
```

### Request Parameters

| Parameter      | Type    | Required | Description                                             |
| -------------- | ------- | -------- | ------------------------------------------------------- |
| version        | string  | Yes      | API version to use (`1.0`).                             |
| includeDeleted | boolean | No       | Include soft-deleted subsidiaries. Defaults to `false`. |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/subsidiaries' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response Fields

The response is an array of subsidiary objects.

| Field                | Type   | Description                                                                                       |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------- |
| Id                   | string | Unique identifier of the subsidiary. This is the value other endpoints expect as a subsidiary id. |
| Name                 | string | Name of the subsidiary.                                                                           |
| Type                 | string | Either `Carrier` or `Brokerage`.                                                                  |
| McNumber             | string | MC number of the subsidiary. Omitted when none is recorded.                                       |
| DotNumber            | string | DOT number of the subsidiary. Omitted when none is recorded.                                      |
| DefaultEquipmentType | string | Default equipment type for the subsidiary.                                                        |
| RemitAddress         | Object | Postal remit-to address. Postal fields only — no contact details.                                 |
| RemitAddress.Street  | string | Street line of the remit address.                                                                 |
| RemitAddress.City    | string | City of the remit address.                                                                        |
| RemitAddress.State   | string | State or province of the remit address.                                                           |
| RemitAddress.ZipCode | string | Postal code of the remit address.                                                                 |
| RemitAddress.Country | string | Country of the remit address. See [Country values](#country-values).                              |

### Example Response

**200 OK**

```json theme={null}
[
  {
    "Id": "9d4b1327-2774-d32c-fb33-87a288c2722c",
    "Name": "Alvy's Motor",
    "Type": "Carrier",
    "McNumber": "1234567",
    "DotNumber": "2515539",
    "DefaultEquipmentType": "Van",
    "RemitAddress": {
      "Street": "201 Lomas Santa Fe Dr",
      "City": "Solana Beach",
      "State": "CA",
      "ZipCode": "92075",
      "Country": "US"
    }
  }
]
```

### Country values

`Country` publishes the ISO 3166-1 alpha-2 code when the recorded value is a recognized spelling of the United States, Canada or Mexico. Any other recorded value publishes exactly as stored, which for addresses created before the field existed may be any string.

<Warning>
  `Country` is omitted when no country is recorded. An absent `Country` must **not** be read as the United States.
</Warning>

### Status Codes

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| 200    | Subsidiaries returned. An empty array is a valid result. |
| 401    | Missing or invalid access token.                         |
| 403    | Token lacks the `subsidiary:read` scope.                 |
| 429    | Rate limit exceeded.                                     |

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. See [Rate Limits](/en/api/guides/rate-limits).


# Accept tender
Source: https://docs.alvys.com/en/api/reference/tenders/accept-tender

POST /api/p/v{version}/tenders/{tenderId}/accept
Accept an inbound tender by tender ID, converting it into a booked load in Alvys with the customer, rate, stops, and equipment from the offer.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/{tenderId}/accept": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "tenderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptTenderRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptTenderRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptTenderRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptTenderRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Accept tender",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.AcceptTenderRequest": {
        "required": [
          "StopCompanyLinks"
        ],
        "type": "object",
        "properties": {
          "StopCompanyLinks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.StopCompanyLink"
            }
          },
          "FleetId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.StopCompanyLink": {
        "required": [
          "CompanyId",
          "StopId"
        ],
        "type": "object",
        "properties": {
          "StopId": {
            "type": "string"
          },
          "CompanyId": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderDateTimeResponse": {
        "required": [
          "DateTime"
        ],
        "type": "object",
        "properties": {
          "DateTime": {
            "type": "string",
            "format": "date-time"
          },
          "TimeZoneCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEntityResponse": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "CompanyName": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEquipmentResponse": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderOrderDetailResponse": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId2": {
            "type": "string",
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderReferenceResponse": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderResponse": {
        "required": [
          "CompanyCode",
          "Id",
          "Status"
        ],
        "type": "object",
        "properties": {
          "Id": {
            "type": "string"
          },
          "CompanyCode": {
            "type": "string"
          },
          "Status": {
            "type": "string"
          },
          "DateImported": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ShipmentId": {
            "type": "string",
            "nullable": true
          },
          "LoadNumber": {
            "type": "string",
            "nullable": true
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEquipmentResponse"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "SCAC": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "string",
            "nullable": true
          },
          "ExpirationDate": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderStopResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          },
          "Etag": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderStopResponse": {
        "required": [
          "StopId",
          "Type"
        ],
        "type": "object",
        "properties": {
          "StopId": {
            "type": "string"
          },
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderOrderDetailResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ArrivedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "DepartedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Accept tender cancellation
Source: https://docs.alvys.com/en/api/reference/tenders/accept-tender-cancellation

POST /api/p/v{version}/tenders/{tenderId}/accept-cancel
Acknowledge and accept a customer-initiated tender cancellation by tender ID, confirming the shipment will be released and no longer executed.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/{tenderId}/accept-cancel": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "tenderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Accept tender cancellation",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Accept tender updates
Source: https://docs.alvys.com/en/api/reference/tenders/accept-tender-updates

POST /api/p/v{version}/tenders/{tenderId}/accept-updates
Accept customer-initiated updates to an existing tender by tender ID, confirming revised stops, timing, rate, or references against the current tender.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/{tenderId}/accept-updates": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "tenderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptUpdatesRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptUpdatesRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptUpdatesRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.AcceptUpdatesRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Accept tender updates",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.AcceptUpdatesRequest": {
        "required": [
          "ApplyAllChangesToLoad"
        ],
        "type": "object",
        "properties": {
          "ApplyAllChangesToLoad": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Cancel tenders
Source: https://docs.alvys.com/en/api/reference/tenders/cancel-tenders

POST /api/p/v{version}/tenders/cancel
Cancel one or more tenders in bulk by tender ID, sending an EDI 990-style cancellation to the customer for shipments that will not be picked up.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/cancel": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Cancel tenders",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.CreateTenderEntityRequest": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderReferenceRequest": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderStopRequest": {
        "required": [
          "Type"
        ],
        "type": "object",
        "properties": {
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledAppointment": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.InboundTenderRequest": {
        "required": [
          "ReceiverGsId",
          "ReceiverIsaId",
          "ReceiverIsaIdQualifier",
          "SCAC",
          "SenderGsId",
          "SenderIsaId",
          "SenderIsaIdQualifier",
          "ShipmentId",
          "Stops"
        ],
        "type": "object",
        "properties": {
          "SenderIsaId": {
            "type": "string"
          },
          "SenderIsaIdQualifier": {
            "type": "string"
          },
          "SenderGsId": {
            "type": "string"
          },
          "ReceiverIsaId": {
            "type": "string"
          },
          "ReceiverIsaIdQualifier": {
            "type": "string"
          },
          "ReceiverGsId": {
            "type": "string"
          },
          "SCAC": {
            "type": "string"
          },
          "ShipmentId": {
            "type": "string"
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderStopRequest"
            }
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "VolumeQualifier": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "ExpirationDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Create tender
Source: https://docs.alvys.com/en/api/reference/tenders/create-tender

POST /api/p/v{version}/tenders
Create a new inbound tender in Alvys from an EDI 204 or manual offer, including customer, stops, offered rate, equipment, and reference numbers.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Create tender",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.CreateTenderEntityRequest": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderReferenceRequest": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderStopRequest": {
        "required": [
          "Type"
        ],
        "type": "object",
        "properties": {
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledAppointment": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.InboundTenderRequest": {
        "required": [
          "ReceiverGsId",
          "ReceiverIsaId",
          "ReceiverIsaIdQualifier",
          "SCAC",
          "SenderGsId",
          "SenderIsaId",
          "SenderIsaIdQualifier",
          "ShipmentId",
          "Stops"
        ],
        "type": "object",
        "properties": {
          "SenderIsaId": {
            "type": "string"
          },
          "SenderIsaIdQualifier": {
            "type": "string"
          },
          "SenderGsId": {
            "type": "string"
          },
          "ReceiverIsaId": {
            "type": "string"
          },
          "ReceiverIsaIdQualifier": {
            "type": "string"
          },
          "ReceiverGsId": {
            "type": "string"
          },
          "SCAC": {
            "type": "string"
          },
          "ShipmentId": {
            "type": "string"
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderStopRequest"
            }
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "VolumeQualifier": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "ExpirationDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Get tender
Source: https://docs.alvys.com/en/api/reference/tenders/get-tender

GET /api/p/v{version}/tenders/{tenderId}
Retrieve a single tender by tender ID from Alvys, including customer, offered rate, stops, equipment requirements, and current acceptance status.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/{tenderId}": {
      "get": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "tenderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Get tender",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Response.TenderDateTimeResponse": {
        "required": [
          "DateTime"
        ],
        "type": "object",
        "properties": {
          "DateTime": {
            "type": "string",
            "format": "date-time"
          },
          "TimeZoneCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEntityResponse": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "CompanyName": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEquipmentResponse": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderOrderDetailResponse": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId2": {
            "type": "string",
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderReferenceResponse": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderResponse": {
        "required": [
          "CompanyCode",
          "Id",
          "Status"
        ],
        "type": "object",
        "properties": {
          "Id": {
            "type": "string"
          },
          "CompanyCode": {
            "type": "string"
          },
          "Status": {
            "type": "string"
          },
          "DateImported": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ShipmentId": {
            "type": "string",
            "nullable": true
          },
          "LoadNumber": {
            "type": "string",
            "nullable": true
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEquipmentResponse"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "SCAC": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "string",
            "nullable": true
          },
          "ExpirationDate": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderStopResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          },
          "Etag": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderStopResponse": {
        "required": [
          "StopId",
          "Type"
        ],
        "type": "object",
        "properties": {
          "StopId": {
            "type": "string"
          },
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderOrderDetailResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ArrivedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "DepartedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Reject tender
Source: https://docs.alvys.com/en/api/reference/tenders/reject-tender

POST /api/p/v{version}/tenders/{tenderId}/reject
Reject an inbound tender by tender ID with a reason code, sending an EDI 990-style decline back to the customer so they can retender the shipment.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/{tenderId}/reject": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "tenderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.RejectTenderRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.RejectTenderRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.RejectTenderRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.RejectTenderRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Reject tender",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.RejectTenderRequest": {
        "required": [
          "CancelLinkedLoad",
          "ReasonCode",
          "ReasonDescription"
        ],
        "type": "object",
        "properties": {
          "ReasonCode": {
            "type": "string"
          },
          "ReasonDescription": {
            "type": "string"
          },
          "CancelLinkedLoad": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Search tenders
Source: https://docs.alvys.com/en/api/reference/tenders/search-tenders

POST /api/p/v{version}/tenders/search
Search tenders with paginated POST filters — customer, status, offered rate range, pickup and delivery windows, origin and destination, and equipment type.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/search": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.SearchTendersRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.SearchTendersRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.SearchTendersRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.SearchTendersRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alvys.Helpers.PagedResponse1Alvys.Models.Tenders.Response.TenderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Search tenders",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Helpers.PagedResponse1Alvys.Models.Tenders.Response.TenderResponse": {
        "required": [
          "Items",
          "Page",
          "PageSize",
          "Total"
        ],
        "type": "object",
        "properties": {
          "Page": {
            "type": "integer",
            "format": "int32"
          },
          "PageSize": {
            "type": "integer",
            "format": "int32"
          },
          "Facets": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Alvys.Helpers.ResultSetFacetItem"
              }
            },
            "nullable": true
          },
          "Aggregations": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Alvys.Helpers.Storage.SearchAggregationResult"
            },
            "nullable": true
          },
          "Total": {
            "type": "integer",
            "format": "int64"
          },
          "Items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderResponse"
            }
          }
        },
        "additionalProperties": false
      },
      "Alvys.Helpers.ResultSetFacetItem": {
        "required": [
          "Count",
          "Value"
        ],
        "type": "object",
        "properties": {
          "Value": {
            "type": "string"
          },
          "Count": {
            "type": "integer",
            "format": "int64"
          }
        },
        "additionalProperties": false
      },
      "Alvys.Helpers.Storage.SearchAggregationResult": {
        "type": "object",
        "properties": {
          "Value": {
            "type": "number",
            "format": "double",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Period": {
        "required": [
          "Start"
        ],
        "type": "object",
        "properties": {
          "Start": {
            "type": "string",
            "format": "date-time"
          },
          "End": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.SearchTendersRequest": {
        "required": [
          "Page",
          "PageSize"
        ],
        "type": "object",
        "properties": {
          "Page": {
            "type": "integer",
            "format": "int32"
          },
          "PageSize": {
            "type": "integer",
            "format": "int32"
          },
          "Sort": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.TenderSortRequest"
              }
            ],
            "nullable": true
          },
          "Filter": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.TenderFilterRequest"
              }
            ],
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.TenderFilterRequest": {
        "type": "object",
        "properties": {
          "Status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "CreatedAtRange": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Period"
              }
            ],
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Source": {
            "type": "string",
            "nullable": true
          },
          "SourceCustomer": {
            "type": "string",
            "nullable": true
          },
          "ShipmentId": {
            "type": "string",
            "nullable": true
          },
          "LoadNumber": {
            "type": "string",
            "nullable": true
          },
          "ExternalTenderId": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.TenderSortRequest": {
        "required": [
          "Direction",
          "Field"
        ],
        "type": "object",
        "properties": {
          "Field": {
            "type": "string"
          },
          "Direction": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderDateTimeResponse": {
        "required": [
          "DateTime"
        ],
        "type": "object",
        "properties": {
          "DateTime": {
            "type": "string",
            "format": "date-time"
          },
          "TimeZoneCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEntityResponse": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "CompanyName": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderEquipmentResponse": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderOrderDetailResponse": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId2": {
            "type": "string",
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderReferenceResponse": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderResponse": {
        "required": [
          "CompanyCode",
          "Id",
          "Status"
        ],
        "type": "object",
        "properties": {
          "Id": {
            "type": "string"
          },
          "CompanyCode": {
            "type": "string"
          },
          "Status": {
            "type": "string"
          },
          "DateImported": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ShipmentId": {
            "type": "string",
            "nullable": true
          },
          "LoadNumber": {
            "type": "string",
            "nullable": true
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEquipmentResponse"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "SCAC": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "string",
            "nullable": true
          },
          "ExpirationDate": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderStopResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          },
          "Etag": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Response.TenderStopResponse": {
        "required": [
          "StopId",
          "Type"
        ],
        "type": "object",
        "properties": {
          "StopId": {
            "type": "string"
          },
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderEntityResponse"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderOrderDetailResponse"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderReferenceResponse"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ArrivedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "DepartedAt": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Response.TenderDateTimeResponse"
              }
            ],
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Update tender
Source: https://docs.alvys.com/en/api/reference/tenders/update-tender

POST /api/p/v{version}/tenders/update
Update one or more open tenders with revised stops, appointment windows, rate, or reference numbers, keeping Alvys in sync with EDI 204 updates.

# OpenAPI definition

```json theme={null}
{
  "openapi": "3.0.1",
  "info": {
    "title": "Alvys",
    "description": "Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests.",
    "contact": {
      "name": "Alvys Support",
      "url": "https://www.alvys.com/resources/contact/"
    },
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://integrations.alvys.com",
      "description": "Public API Server"
    },
    {
      "url": "https://api.alvys.com/",
      "description": "Public API Server"
    }
  ],
  "paths": {
    "/api/p/v{version}/tenders/update": {
      "post": {
        "tags": [
          "Tenders"
        ],
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "API version (e.g., 1.0)",
            "required": true,
            "schema": {
              "type": "string",
              "default": "1.0",
              "example": "1.0"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json-patch+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "text/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            },
            "application/*+json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.InboundTenderRequest"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails"
                }
              }
            }
          }
        },
        "summary": "Update tender",
        "security": [
          {
            "Public": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Alvys.Models.Tenders.Request.CreateTenderEntityRequest": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Name": {
            "type": "string",
            "nullable": true
          },
          "IdCodeQualifier": {
            "type": "string",
            "nullable": true
          },
          "IdCode": {
            "type": "string",
            "nullable": true
          },
          "N1Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Street": {
            "type": "string",
            "nullable": true
          },
          "City": {
            "type": "string",
            "nullable": true
          },
          "PostalCode": {
            "type": "string",
            "nullable": true
          },
          "CountryCode": {
            "type": "string",
            "nullable": true
          },
          "Phone": {
            "type": "string",
            "nullable": true
          },
          "Email": {
            "type": "string",
            "nullable": true
          },
          "State": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest": {
        "type": "object",
        "properties": {
          "Number": {
            "type": "string",
            "nullable": true
          },
          "Length": {
            "type": "string",
            "nullable": true
          },
          "Type": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest": {
        "type": "object",
        "properties": {
          "Quantity": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "ReferenceId": {
            "type": "string",
            "nullable": true
          },
          "PoNumber": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "UnitBasisForMeasurement": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderReferenceRequest": {
        "type": "object",
        "properties": {
          "Id": {
            "type": "string",
            "nullable": true
          },
          "Qualifier": {
            "type": "string",
            "nullable": true
          },
          "Description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.CreateTenderStopRequest": {
        "required": [
          "Type"
        ],
        "type": "object",
        "properties": {
          "Type": {
            "type": "string"
          },
          "Entity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
              }
            ],
            "nullable": true
          },
          "SequenceNumber": {
            "type": "string",
            "nullable": true
          },
          "Orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderOrderDetailRequest"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "ScheduledArrivalStart": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledArrivalEnd": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ScheduledAppointment": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "StopReasonCode": {
            "type": "string",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Alvys.Models.Tenders.Request.InboundTenderRequest": {
        "required": [
          "ReceiverGsId",
          "ReceiverIsaId",
          "ReceiverIsaIdQualifier",
          "SCAC",
          "SenderGsId",
          "SenderIsaId",
          "SenderIsaIdQualifier",
          "ShipmentId",
          "Stops"
        ],
        "type": "object",
        "properties": {
          "SenderIsaId": {
            "type": "string"
          },
          "SenderIsaIdQualifier": {
            "type": "string"
          },
          "SenderGsId": {
            "type": "string"
          },
          "ReceiverIsaId": {
            "type": "string"
          },
          "ReceiverIsaIdQualifier": {
            "type": "string"
          },
          "ReceiverGsId": {
            "type": "string"
          },
          "SCAC": {
            "type": "string"
          },
          "ShipmentId": {
            "type": "string"
          },
          "Stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderStopRequest"
            }
          },
          "Equipment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEquipmentRequest"
              }
            ],
            "nullable": true
          },
          "Entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderEntityRequest"
            },
            "nullable": true
          },
          "PaymentMethod": {
            "type": "string",
            "nullable": true
          },
          "QtyPallets": {
            "type": "string",
            "nullable": true
          },
          "Weight": {
            "type": "string",
            "nullable": true
          },
          "WeightUnitCode": {
            "type": "string",
            "nullable": true
          },
          "WeightQualifier": {
            "type": "string",
            "nullable": true
          },
          "Volume": {
            "type": "string",
            "nullable": true
          },
          "VolumeUnitCode": {
            "type": "string",
            "nullable": true
          },
          "VolumeQualifier": {
            "type": "string",
            "nullable": true
          },
          "Rate": {
            "type": "number",
            "format": "double",
            "nullable": true
          },
          "ExpirationDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "Notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "References": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Alvys.Models.Tenders.Request.CreateTenderReferenceRequest"
            },
            "nullable": true
          },
          "RoutingSequenceCode": {
            "type": "string",
            "nullable": true
          },
          "TransportationMethodTypeCode": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "Microsoft.AspNetCore.Mvc.ProblemDetails": {
        "type": "object",
        "properties": {
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "Microsoft.AspNetCore.Mvc.ValidationProblemDetails": {
        "required": [
          "Errors"
        ],
        "type": "object",
        "properties": {
          "Errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "Type": {
            "type": "string",
            "nullable": true
          },
          "Title": {
            "type": "string",
            "nullable": true
          },
          "Status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "Detail": {
            "type": "string",
            "nullable": true
          },
          "Instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      }
    },
    "securitySchemes": {
      "Public": {
        "type": "apiKey",
        "description": "JWT token needed to access the endpoints. (eg.) Bearer: <token>",
        "name": "Authorization",
        "in": "header"
      }
    }
  }
}
```


# Get toll transaction
Source: https://docs.alvys.com/en/api/reference/tolls/get-toll-transaction

GET /api/p/v{version}/tolls/{id}
Retrieve a single toll transaction by ID, including transponder, driver, unit, plaza, timestamp, amount, and the trip or load the toll is tied to.

The Retrieve Toll Transaction by ID API endpoint allows you to retrieve detailed information about a specific toll transaction using its unique ID. This endpoint provides comprehensive data about the toll transaction, facilitating effective tracking and management within the Alvys system.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                                    |
| --------- | ------ | -------- | ---------------------------------------------- |
| version   | String | Yes      | The API version to use.                        |
| id        | String | Yes      | The unique identifier of the toll transaction. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/tolls/{id}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{id}` with the actual toll ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/tolls/00c8d000-00c0-0000-ba60-000e0f0e0ae0' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

The following table lists the parameters included in the response for toll transaction-related requests:

| Parameter               | Type               | Required | Description                                                     |
| ----------------------- | ------------------ | -------- | --------------------------------------------------------------- |
| Id                      | String             | Yes      | The unique identifier of the toll transaction.                  |
| SubsidiaryId            | String             | No       | The subsidiary ID associated with the transaction.              |
| TransactionId           | String             | No       | The external transaction ID from the toll provider.             |
| TransponderId           | String             | No       | The transponder ID associated with the transaction.             |
| Source                  | String             | Yes      | The toll provider (e.g., PrePass, BestPass, IPass).             |
| Agency                  | String             | Yes      | The tolling agency that issued the transaction.                 |
| UnitId                  | String             | No       | The Alvys unit ID associated with the transaction.              |
| UnitNumber              | String             | No       | The unit number associated with the transaction.                |
| LicenseState            | String             | No       | The state where the vehicle is licensed.                        |
| LicensePlate            | String             | No       | The license plate of the vehicle.                               |
| PrePaid                 | Boolean            | Yes      | Indicates whether the toll was prepaid.                         |
| Service                 | String             | No       | The toll road or service (e.g., Texas Toll Roads, PA Turnpike). |
| CostCenter              | String             | No       | The cost center associated with the transaction.                |
| EntryLane               | String             | No       | The lane used at entry.                                         |
| EntryPlazaId            | String             | No       | The identifier of the entry plaza.                              |
| EntryPlazaName          | String             | No       | The name of the entry plaza.                                    |
| EntryTime               | String (Date-Time) | No       | The date and time of entry.                                     |
| ExitLane                | String             | No       | The lane used at exit.                                          |
| ExitPlazaId             | String             | No       | The identifier of the exit plaza.                               |
| ExitPlazaName           | String             | No       | The name of the exit plaza.                                     |
| ExitTime                | String (Date-Time) | No       | The date and time of exit.                                      |
| FormattedLocation       | String             | No       | The formatted location of the toll transaction.                 |
| Amount                  | Object             | Yes      | The toll amount.                                                |
| Amount.Amount           | Number             | Yes      | The monetary value of the toll.                                 |
| Amount.Currency         | Integer            | Yes      | The currency identifier of the toll amount.                     |
| RunningBalance          | Object             | No       | The running account balance after the transaction.              |
| RunningBalance.Amount   | Number             | No       | The monetary value of the running balance.                      |
| RunningBalance.Currency | Integer            | No       | The currency identifier of the running balance.                 |
| Fee                     | Object             | No       | The fee charged for the transaction.                            |
| Fee.Amount              | Number             | No       | The monetary value of the fee.                                  |
| Fee.Currency            | Integer            | No       | The currency identifier of the fee.                             |
| PostedAt                | String (Date-Time) | No       | The date and time when the transaction was posted.              |
| TransactionDate         | String (Date-Time) | Yes      | The date and time when the toll transaction occurred.           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

<br />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by providing the toll transaction ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search toll transactions
Source: https://docs.alvys.com/en/api/reference/tolls/search-toll-transactions

POST /api/p/v{version}/tolls/search
Search toll transactions with paginated POST filters — transponder, driver, unit, plaza, date range, and amount, returning per-transaction detail.

This endpoint provides detailed information about each toll transaction that matches the search criteria, facilitating efficient management and retrieval of toll transaction records.

The Search Toll Transactions API endpoint allows you to search for toll transactions within the Alvys system based on various criteria such as transponder ID, unit IDs, and date range. This endpoint provides detailed information about each toll transaction that matches the search criteria, facilitating efficient management and retrieval of toll transaction records.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body

The following fields are required in the request body to filter the search results:

`<Table>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.\
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      TransponderId
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The transponder ID used for the toll transactions. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      UnitIds
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      Conditionally
    </td>

    <td>
      A list of unit IDs to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange
    </td>

    <td>
      Object
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The date range for the toll transactions. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange.Start
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The start date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      DateRange.End
    </td>

    <td>
      String (Date-Time)
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The end date of the transaction range. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/tolls/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "TransponderId": "",
  "UnitIds": [
      "TR25123456789"
  ],
  "DateRange": {
      "Start": "2021-07-23T14:48:05.234Z",
      "End": "2024-07-23T14:48:05.234Z"
  }
}'
```

### Response Parameters

The following table lists the parameters included in the response for toll transaction search requests:

| Parameter                     | Type               | Required | Description                                                     |
| ----------------------------- | ------------------ | -------- | --------------------------------------------------------------- |
| Page                          | Integer            | Yes      | The current page number of the results.                         |
| PageSize                      | Integer            | Yes      | The number of results per page.                                 |
| Total                         | Integer            | Yes      | The total number of matching toll transactions.                 |
| Items                         | Array of Objects   | Yes      | The list of toll transaction records matching the criteria.     |
| Items.Id                      | String             | Yes      | The unique identifier of the toll transaction.                  |
| Items.SubsidiaryId            | String             | No       | The subsidiary ID associated with the transaction.              |
| Items.TransactionId           | String             | No       | The external transaction ID from the toll provider.             |
| Items.TransponderId           | String             | No       | The transponder ID associated with the transaction.             |
| Items.Source                  | String             | Yes      | The toll provider (e.g., PrePass, BestPass, IPass).             |
| Items.Agency                  | String             | Yes      | The tolling agency that issued the transaction.                 |
| Items.UnitId                  | String             | No       | The Alvys unit ID associated with the transaction.              |
| Items.UnitNumber              | String             | No       | The unit number associated with the transaction.                |
| Items.LicenseState            | String             | No       | The state where the vehicle is licensed.                        |
| Items.LicensePlate            | String             | No       | The license plate of the vehicle.                               |
| Items.PrePaid                 | Boolean            | Yes      | Indicates whether the toll was prepaid.                         |
| Items.Service                 | String             | No       | The toll road or service (e.g., Texas Toll Roads, PA Turnpike). |
| Items.CostCenter              | String             | No       | The cost center associated with the transaction.                |
| Items.EntryLane               | String             | No       | The lane used at entry.                                         |
| Items.EntryPlazaId            | String             | No       | The identifier of the entry plaza.                              |
| Items.EntryPlazaName          | String             | No       | The name of the entry plaza.                                    |
| Items.EntryTime               | String (Date-Time) | No       | The date and time of entry.                                     |
| Items.ExitLane                | String             | No       | The lane used at exit.                                          |
| Items.ExitPlazaId             | String             | No       | The identifier of the exit plaza.                               |
| Items.ExitPlazaName           | String             | No       | The name of the exit plaza.                                     |
| Items.ExitTime                | String (Date-Time) | No       | The date and time of exit.                                      |
| Items.FormattedLocation       | String             | No       | The formatted location of the toll transaction.                 |
| Items.Amount                  | Object             | Yes      | The toll amount.                                                |
| Items.Amount.Amount           | Number             | Yes      | The monetary value of the toll.                                 |
| Items.Amount.Currency         | Integer            | Yes      | The currency identifier of the toll amount.                     |
| Items.RunningBalance          | Object             | No       | The running account balance after the transaction.              |
| Items.RunningBalance.Amount   | Number             | No       | The monetary value of the running balance.                      |
| Items.RunningBalance.Currency | Integer            | No       | The currency identifier of the running balance.                 |
| Items.Fee                     | Object             | No       | The fee charged for the transaction.                            |
| Items.Fee.Amount              | Number             | No       | The monetary value of the fee.                                  |
| Items.Fee.Currency            | Integer            | No       | The currency identifier of the fee.                             |
| Items.PostedAt                | String (Date-Time) | No       | The date and time when the transaction was posted.              |
| Items.TransactionDate         | String (Date-Time) | Yes      | The date and time when the toll transaction occurred.           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

<br />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Get trailer
Source: https://docs.alvys.com/en/api/reference/trailers/get-trailer

GET /api/p/v{version}/trailers/{id}
Retrieve a single trailer record by ID, including trailer number, type, ownership, license plate, current location, and current load or trip assignment.

This endpoint allows you to search for trailers within the Alvys system based on various criteria such as status, trailer number, fleet name, and VIN number. The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| version   | String | Yes      | The API version to use.               |
| id        | String | Yes      | The unique identifier of the trailer. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trailers/{trailerId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{trailerId}` with the actual trailer ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trailers/TL2512345678951234569' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

The following table lists the parameters included in the response for trailer-related requests:

| Parameter                 | Type               | Required | Description                                                        |
| ------------------------- | ------------------ | -------- | ------------------------------------------------------------------ |
| Id                        | String             | Yes      | The unique identifier of the trailer.                              |
| TrailerNum                | String             | No       | The trailer number associated with the trailer.                    |
| Fleet                     | Object             | No       | The fleet information associated with the trailer.                 |
| Fleet.Id                  | String             | No       | The unique identifier of the fleet.                                |
| Fleet.Name                | String             | No       | The name of the fleet.                                             |
| Fleet.InvoiceNumberPrefix | String             | No       | The invoice number prefix for the fleet.                           |
| Year                      | Integer            | No       | The manufacturing year of the trailer.                             |
| Make                      | String             | No       | The make of the trailer.                                           |
| LicenseNum                | String             | No       | The license number of the trailer.                                 |
| LicenseState              | String             | No       | The state where the trailer is licensed.                           |
| LicenseCountry            | String             | No       | The country where the trailer is licensed (USA, Canada, Mexico).   |
| PlateExpiresAt            | String (Date)      | No       | The expiration date of the trailer's plate.                        |
| LicenseExpiresAt          | String (Date)      | No       | The expiration date of the trailer's license (registration).       |
| VinNum                    | String             | No       | The Vehicle Identification Number (VIN) of the trailer.            |
| Status                    | String             | No       | The current status of the trailer.                                 |
| SubsidiaryId              | String             | No       | The subsidiary ID associated with the trailer.                     |
| EquipmentType             | String             | No       | The type of equipment of the trailer.                              |
| EquipmentSize             | String             | No       | The size of the equipment.                                         |
| Capacity                  | Object             | No       | The capacity information of the trailer.                           |
| Capacity.Pallets          | Integer            | No       | The number of pallets the trailer can carry.                       |
| Capacity.Weight           | Integer            | No       | The weight capacity of the trailer.                                |
| InsuranceCompany          | String             | No       | The name of the insurance company.                                 |
| InsurancePolicyNumber     | String             | No       | The insurance policy number.                                       |
| InsuranceExpiresAt        | String (Date)      | No       | The expiration date of the insurance policy.                       |
| InspectionExpiresAt       | String (Date)      | No       | The expiration date of the trailer's inspection.                   |
| Notes                     | Array              | No       | An optional list of notes related to the trailer.                  |
| References                | Array              | No       | An optional list of custom references associated with the trailer. |
| CreatedAt                 | String (Date-Time) | Yes      | The date and time when the trailer was created in Alvys.           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by providing the trailer ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# List trailer documents
Source: https://docs.alvys.com/en/api/reference/trailers/list-trailer-documents

GET /api/p/v{version}/trailers/{trailerId}/documents
List all documents attached to a trailer by trailer ID, including registration, inspection reports, lease agreements, and maintenance certifications.

Retrieve all uploaded documents associated with a specific **Trailer** by its unique `trailerId`.

### Request Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| version   | String | Yes      | API version to use.               |
| trailerId | String | Yes      | Unique identifier of the trailer. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trailers/{trailerId}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{trailerId}` with the actual trailer ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                         |
| -------------- | ------- | ------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                  |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix). |
| AttachmentType | string  | Type of document (e.g., Insurance Certificate, Vehicle Image).      |
| AttachmentSize | integer | Size of the file in bytes.                                          |
| UploadedAt     | string  | UTC timestamp when the file was uploaded.                           |
| ParentId       | string  | Identifier of the parent entity (`trailerId`).                      |
| ParentType     | string  | Entity type the document is attached to (`Trailer`).                |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.       |
| DownloadUrl    | string  | Time-limited link (10 minutes) to download the document.            |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl`.                          |

***

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "ec0a0ef0-000c-0000-9f00-5d0f00c4cf00",
    "AttachmentPath": "TrailerIns-1759237626.pdf",
    "AttachmentType": "Insurance Certificate",
    "AttachmentSize": 95421,
    "UploadedAt": "2025-09-30T17:07:07+00:00",
    "ParentId": "TRL002",
    "ParentType": "Trailer",
    "UploadedBy": "1110002eecc3408e90d3322f4ece0e11",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/TrailerIns-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T17:17:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **trailerId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List trailers
Source: https://docs.alvys.com/en/api/reference/trailers/list-trailers

GET /api/p/v{version}/trailers
List trailers in your Alvys fleet with pagination, returning trailer number, type, ownership, license, current status, and last known location.

The Retrieve All Trailers API endpoint allows you to retrieve a list of all trailers in the Alvys system. This endpoint provides comprehensive data about each trailer, facilitating effective asset management and tracking within the system.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trailers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trailers' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

The following table lists the parameters included in the response for trailer-related requests:

| Parameter                 | Type               | Required | Description                                                        |
| ------------------------- | ------------------ | -------- | ------------------------------------------------------------------ |
| Id                        | String             | Yes      | The unique identifier of the trailer.                              |
| TrailerNum                | String             | No       | The trailer number associated with the trailer.                    |
| Fleet                     | Object             | No       | The fleet information associated with the trailer.                 |
| Fleet.Id                  | String             | No       | The unique identifier of the fleet.                                |
| Fleet.Name                | String             | No       | The name of the fleet.                                             |
| Fleet.InvoiceNumberPrefix | String             | No       | The invoice number prefix for the fleet.                           |
| Year                      | Integer            | No       | The manufacturing year of the trailer.                             |
| Make                      | String             | No       | The make of the trailer.                                           |
| LicenseNum                | String             | No       | The license number of the trailer.                                 |
| LicenseState              | String             | No       | The state where the trailer is licensed.                           |
| LicenseCountry            | String             | No       | The country where the trailer is licensed (USA, Canada, Mexico).   |
| PlateExpiresAt            | String (Date)      | No       | The expiration date of the trailer's plate.                        |
| LicenseExpiresAt          | String (Date)      | No       | The expiration date of the trailer's license (registration).       |
| VinNum                    | String             | No       | The Vehicle Identification Number (VIN) of the trailer.            |
| Status                    | String             | No       | The current status of the trailer.                                 |
| SubsidiaryId              | String             | No       | The subsidiary ID associated with the trailer.                     |
| EquipmentType             | String             | No       | The type of equipment of the trailer.                              |
| EquipmentSize             | String             | No       | The size of the equipment.                                         |
| Capacity                  | Object             | No       | The capacity information of the trailer.                           |
| Capacity.Pallets          | Integer            | No       | The number of pallets the trailer can carry.                       |
| Capacity.Weight           | Integer            | No       | The weight capacity of the trailer.                                |
| InsuranceCompany          | String             | No       | The name of the insurance company.                                 |
| InsurancePolicyNumber     | String             | No       | The insurance policy number.                                       |
| InsuranceExpiresAt        | String (Date)      | No       | The expiration date of the insurance policy.                       |
| InspectionExpiresAt       | String (Date)      | No       | The expiration date of the trailer's inspection.                   |
| Notes                     | Array              | No       | An optional list of notes related to the trailer.                  |
| References                | Array              | No       | An optional list of custom references associated with the trailer. |
| CreatedAt                 | String (Date-Time) | Yes      | The date and time when the trailer was created in Alvys.           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search trailer events
Source: https://docs.alvys.com/en/api/reference/trailers/search-trailer-events

POST /api/p/v{version}/trailers/events/search
Search trailer telematics events with paginated POST filters — trailer, event type, date range, and load or trip context for location and status pings.

This endpoint provides detailed information about trailer events that match the search criteria, enabling efficient tracking and management of trailer-related activities.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body Parameters

The following parameters are required in the request body:

| Parameter  | Type              | Required | Description                                       |
| ---------- | ----------------- | -------- | ------------------------------------------------- |
| StartDate  | String (DateTime) | Yes      | The start date-time for the event search range.   |
| EndDate    | String (DateTime) | No       | The end date-time for the event search range.     |
| TrailerIds | Array of Strings  | Yes      | The list of trailer IDs to filter trailer events. |

#### Example CURL request

Use the current API version number and ensure you replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trailers/events/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "StartDate": "2025-02-06T06:50:20.471Z",
  "EndDate": "2025-02-06T06:50:20.471Z",
  "TrailerIds": [
    "string"
  ]
}'
```

### Response Parameters

The following table lists the parameters included in the response for trailer events requests.

| Parameter       | Type              | Required | Description                                     |
| --------------- | ----------------- | -------- | ----------------------------------------------- |
| Id              | String            | Yes      | The unique identifier of the trailer event.     |
| TrailerId       | String            | Yes      | The unique identifier of the trailer.           |
| Title           | String            | Yes      | The title or reference code of the event.       |
| EventType       | String            | Yes      | The type of event (e.g., Repair, Other).        |
| Description     | String            | Yes      | A detailed description of the event.            |
| StartDate       | String (DateTime) | Yes      | The start date-time of the event.               |
| EndDate         | String (DateTime) | Yes      | The end date-time of the event.                 |
| Address         | Object            | No       | The location details associated with the event. |
| Address.Street  | String            | No       | The street address where the event occurred.    |
| Address.City    | String            | No       | The city where the event took place.            |
| Address.State   | String            | No       | The state where the event took place.           |
| Address.ZipCode | String            | No       | The ZIP code of the event location.             |
| CreatedBy       | String            | Yes      | The user who created the event record.          |
| CreatedAt       | String (DateTime) | Yes      | The timestamp for when the event was created.   |

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Search trailers
Source: https://docs.alvys.com/en/api/reference/trailers/search-trailers

POST /api/p/v{version}/trailers/search
Search trailers with paginated POST filters — trailer number, type, ownership, current status, license, home terminal, and current load or trip.

The Search Trailers API endpoint allows you to search for trailers within the Alvys system based on various criteria such as status, trailer number, fleet name, and VIN number. This endpoint provides detailed information about each trailer that matches the search criteria, facilitating efficient management and retrieval of trailer records.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body

The following fields are required in the request body to filter the search results:

`<Table>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.\
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      Status
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      No
    </td>

    <td>
      A list of status values to filter by.
    </td>
  </tr>

  <tr>
    <td>
      TrailerNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The trailer number to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      FleetName
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The name of the fleet to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      VinNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The VIN number of the trailer. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trailers/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{ 
   "Page": 0,
   "PageSize": 50,
   "Status": [
       "Active"
   ],
   "TrailerNumber": "",
   "FleetName": "",
   "VinNumber": ""
}'
```

### Response Parameters

The following table lists the parameters included in the response for trailer search requests:

| Parameter                       | Type               | Required | Description                                                        |
| ------------------------------- | ------------------ | -------- | ------------------------------------------------------------------ |
| Page                            | Integer            | Yes      | The current page number of the results.                            |
| PageSize                        | Integer            | Yes      | The number of results per page.                                    |
| Total                           | Integer            | Yes      | The total number of matching trailers.                             |
| Items                           | Array of Objects   | Yes      | The list of trailer records matching the criteria.                 |
| Items.Id                        | String             | Yes      | The unique identifier of the trailer.                              |
| Items.TrailerNum                | String             | No       | The trailer number associated with the trailer.                    |
| Items.Fleet                     | Object             | No       | The fleet information associated with the trailer.                 |
| Items.Fleet.Id                  | String             | No       | The unique identifier of the fleet.                                |
| Items.Fleet.Name                | String             | No       | The name of the fleet.                                             |
| Items.Fleet.InvoiceNumberPrefix | String             | No       | The invoice number prefix for the fleet.                           |
| Items.Year                      | Integer            | No       | The manufacturing year of the trailer.                             |
| Items.Make                      | String             | No       | The make of the trailer.                                           |
| Items.LicenseNum                | String             | No       | The license number of the trailer.                                 |
| Items.LicenseState              | String             | No       | The state where the trailer is licensed.                           |
| Items.LicenseCountry            | String             | No       | The country where the trailer is licensed (USA, Canada, Mexico).   |
| Items.PlateExpiresAt            | String (Date)      | No       | The expiration date of the trailer's plate.                        |
| Items.LicenseExpiresAt          | String (Date)      | No       | The expiration date of the trailer's license (registration).       |
| Items.VinNum                    | String             | No       | The Vehicle Identification Number (VIN) of the trailer.            |
| Items.Status                    | String             | No       | The current status of the trailer.                                 |
| Items.SubsidiaryId              | String             | No       | The subsidiary ID associated with the trailer.                     |
| Items.EquipmentType             | String             | No       | The type of equipment of the trailer.                              |
| Items.EquipmentSize             | String             | No       | The size of the equipment.                                         |
| Items.Capacity                  | Object             | No       | The capacity information of the trailer.                           |
| Items.Capacity.Pallets          | Integer            | No       | The number of pallets the trailer can carry.                       |
| Items.Capacity.Weight           | Integer            | No       | The weight capacity of the trailer.                                |
| Items.InsuranceCompany          | String             | No       | The name of the insurance company.                                 |
| Items.InsurancePolicyNumber     | String             | No       | The insurance policy number.                                       |
| Items.InsuranceExpiresAt        | String (Date)      | No       | The expiration date of the insurance policy.                       |
| Items.InspectionExpiresAt       | String (Date)      | No       | The expiration date of the trailer's inspection.                   |
| Items.Notes                     | Array              | No       | An optional list of notes related to the trailer.                  |
| Items.References                | Array              | No       | An optional list of custom references associated with the trailer. |
| Items.CreatedAt                 | String (Date-Time) | Yes      | The date and time when the trailer was created in Alvys.           |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Upload trailer document
Source: https://docs.alvys.com/en/api/reference/trailers/upload-trailer-document

POST /api/p/v{version}/trailers/{trailerId}/document
Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific **trailer**. Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`
* **Allowed Document Types:** Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents

***

### Parameters

| Parameter   | In   | Type   | Required | Description                  |
| ----------- | ---- | ------ | -------- | ---------------------------- |
| `trailerId` | path | string | Yes      | Unique identifier of trailer |
| `version`   | path | string | Yes      | API version (e.g., `1.0`)    |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG). Max size 25 MB.                         |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/trailers/{trailerId}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@COI.pdf" \
  -F "DocumentType=Certificate of Insurance (COI)"
```

***

### Response Body

| Name             | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (e.g., `1757343192`) |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                 |
| `AttachmentSize` | integer | Size of the file in bytes                                                 |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded (ISO 8601)                       |
| `ParentId`       | string  | Identifier of the parent entity (the `{trailerId}`)                       |
| `ParentType`     | string  | Entity type the document is attached to (`Trailer`)                       |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "c3f0a7d2-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "COI-1757343192.pdf",
  "AttachmentType": "Certificate of Insurance (COI)",
  "AttachmentSize": 1048576,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "trl-12345",
  "ParentType": "Trailer"
}
```

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **trailerId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Assign trip
Source: https://docs.alvys.com/en/api/reference/trips/assign-trip

POST /api/p/v{version}/trips/{tripId}/assign
Assign a driver, truck, and trailer to a trip in Alvys by trip ID, setting the resources that will move the load through pickup and delivery stops.



# Clear stop arrival
Source: https://docs.alvys.com/en/api/reference/trips/clear-stop-arrival

DELETE /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
Clear a recorded arrival timestamp on a trip stop by trip and stop ID, resetting the arrival event so drivers or dispatchers can log the correct time.

## Clear Stop Arrival

Clears the recorded arrival time for a specific stop within a trip.

This endpoint removes the `ArrivedAt` timestamp from the stop, effectively marking the stop as **not yet arrived**.

The response returns the **updated stop object** after the arrival timestamp has been cleared.

***

### Endpoint

```
DELETE /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
```

***

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | string | Yes      | API version (e.g. `1.0`).      |
| tripId    | string | Yes      | Unique identifier of the trip. |
| stopId    | string | Yes      | Unique identifier of the stop. |

***

### Example CURL request

```bash theme={null}
curl --location --request DELETE 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/arrival' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace:

* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `{stopId}` with the stop ID
* `YOUR_ACCESS_TOKEN` with your Bearer token

***

### Response Parameters

| Parameter                 | Type              | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.Street            | string            | Street address of the stop location.                                                                                                                                                                                                        |
| Address.City              | string            | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | State of the stop location.                                                                                                                                                                                                                 |
| Address.ZipCode           | string            | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | Appointment date and time for the stop.                                                                                                                                                                                                     |
| AppointmentRequested      | boolean           | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | Timestamp when the stop was marked as arrived (UTC). This value will be **null after clearing arrival**.                                                                                                                                    |
| DepartedAt                | string (datetime) | Timestamp when the stop was departed (UTC).                                                                                                                                                                                                 |
| Eta                       | object            | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| ScheduleType              | string            | Schedule type (`APPT` or `FCFS`).                                                                                                                                                                                                           |
| LoadingType               | string            | Loading type (`Live`, `Drop`, `Hook`, etc.).                                                                                                                                                                                                |
| StopType                  | string            | Type of stop (`Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                            |
| Status                    | string            | Operational status of the stop.                                                                                                                                                                                                             |
| Coordinates.Latitude      | string            | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | Longitude of the stop location.                                                                                                                                                                                                             |
| References\[]             | array             | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Id          | string            | Reference identifier.                                                                                                                                                                                                                       |
| References\[].ReferenceId | string            | External reference identifier.                                                                                                                                                                                                              |
| References\[].Name        | string            | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Value       | string            | Value of the reference.                                                                                                                                                                                                                     |
| References\[].Type        | string            | Type of reference.                                                                                                                                                                                                                          |
| References\[].Access      | string            | Access level (`Public`, `Internal`).                                                                                                                                                                                                        |
| References\[].Origin      | string            | Origin of the reference.                                                                                                                                                                                                                    |
| CompanyId                 | string            | Identifier of the company associated with the stop.                                                                                                                                                                                         |
| CompanyNumber             | string            | Company registration or identification number.                                                                                                                                                                                              |
| CompanyName               | string            | Company name associated with the stop.                                                                                                                                                                                                      |

***

### Example Response

```json theme={null}
{
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "AppointmentDate": "2026-03-16T12:35:48.148Z",
  "ScheduleType": "string",
  "LoadingType": "string",
  "Id": "string",
  "Address": {
    "Street": "string",
    "City": "string",
    "State": "string",
    "ZipCode": "string"
  },
  "Coordinates": {
    "Latitude": "string",
    "Longitude": "string"
  },
  "Status": "string",
  "StopType": "string",
  "ArrivedAt": null,
  "DepartedAt": "2026-03-16T12:35:48.148Z",
  "References": [
    {
      "Id": "string",
      "ReferenceId": "string",
      "Name": "string",
      "Value": "string",
      "Type": "string",
      "Access": "string",
      "Origin": "string"
    }
  ],
  "CompanyId": "string",
  "CompanyNumber": "string",
  "CompanyName": "string",
  "Eta": {
    "Planned": "2026-03-16T10:40:00.000Z",
    "Live": "2026-03-16T10:52:00.000Z",
    "Manual": null
  }
}
```

***

### Status Codes

| Status Code   | Description                                  |
| ------------- | -------------------------------------------- |
| 200 OK        | Stop arrival timestamp successfully cleared. |
| 404 Not Found | Trip or stop could not be found.             |

***

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.

Refer to the **Rate Limits** documentation for more information.


# Dispatch trip
Source: https://docs.alvys.com/en/api/reference/trips/dispatch-trip

POST /api/p/v{version}/trips/{tripId}/dispatch
Dispatch an assigned trip in Alvys by trip ID, transitioning the trip from Assigned to Dispatched and notifying the driver on the mobile companion app.



# Get trip
Source: https://docs.alvys.com/en/api/reference/trips/get-trip

GET /api/p/v{version}/trips
Retrieve trip records from Alvys by trip ID, including the assigned driver and truck, sequenced stops, current status, and associated load numbers.

### Request Parameters

The following parameters are available in the URL path and query string:

| Parameter      | Type    | Required      | Description                                                                                                                                    |
| -------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| version        | String  | Yes           | The API version to use.                                                                                                                        |
| tripNumber     | String  | Conditionally | The trip number to filter results. This field is required if the other conditionally required fields are left empty.                           |
| id             | String  | Conditionally | The trip id to filter results. This field is required if the other conditionally required fields are left empty.                               |
| includeDeleted | Boolean | No            | When `true`, also returns trips that are deleted or invisible (for example, an original trip superseded by a load split). Defaults to `false`. |

#### Example CURL request

Example using Trip ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trips?id={tripId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Example using Trip Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trips?tripNumber={tripNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{tripId}` with the actual trip ID, `{tripNumber}` with the actual trip number, and `YOUR_ACCESS_TOKEN` with your actual Bearer token:

Using Trip ID:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips?id=000c3a9bf0000000bf000d000e000a0b' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

Using Trip Number:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips?tripNumber=123456789' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....'
```

### Response Parameters

The following table lists the parameters included in the response for a single trip request:

| Parameter                                               | Type              | Required | Description                                                                                                                                                                                                                                                         |
| :------------------------------------------------------ | :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Id                                                      | string            | Yes      | Unique identifier of the trip.                                                                                                                                                                                                                                      |
| TripNumber                                              | string            | Yes      | Number associated with the trip.                                                                                                                                                                                                                                    |
| Status                                                  | string            | No       | Current status of the trip.                                                                                                                                                                                                                                         |
| LoadNumber                                              | string            | No       | Load number associated with the trip.                                                                                                                                                                                                                               |
| TenderAs                                                | string            | No       | Role under which the trip was tendered.                                                                                                                                                                                                                             |
| TenderAsSubsidiaryType                                  | string            | No       | Subsidiary type under which the trip was tendered (e.g., `"Carrier"`).                                                                                                                                                                                              |
| Stops\[]                                                | array             | No       | List of stops for the trip.                                                                                                                                                                                                                                         |
| Stops\[].Id                                             | string            | No       | Unique identifier of the stop.                                                                                                                                                                                                                                      |
| Stops\[].Address.Street                                 | string            | No       | Street address of the stop.                                                                                                                                                                                                                                         |
| Stops\[].Address.City                                   | string            | No       | City of the stop.                                                                                                                                                                                                                                                   |
| Stops\[].Address.State                                  | string            | No       | State of the stop.                                                                                                                                                                                                                                                  |
| Stops\[].Address.ZipCode                                | string            | No       | ZIP code of the stop.                                                                                                                                                                                                                                               |
| Stops\[].Coordinates.Latitude                           | string            | No       | Latitude of the stop.                                                                                                                                                                                                                                               |
| Stops\[].Coordinates.Longitude                          | string            | No       | Longitude of the stop.                                                                                                                                                                                                                                              |
| Stops\[].Status                                         | string            | No       | Status of the stop.                                                                                                                                                                                                                                                 |
| Stops\[].StopType                                       | string            | No       | Type of stop (e.g., Pickup, Delivery).                                                                                                                                                                                                                              |
| Stops\[].AppointmentDate                                | string (datetime) | No       | Appointment date/time for the stop.                                                                                                                                                                                                                                 |
| Stops\[].Eta                                            | object            | No       | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan.                         |
| Stops\[].Eta.Planned                                    | string (datetime) | No       | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                                                |
| Stops\[].Eta.Live                                       | string (datetime) | No       | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                                                     |
| Stops\[].Eta.Manual                                     | string (datetime) | No       | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                                               |
| TotalMileage.Distance.Value                             | number            | No       | Total mileage value.                                                                                                                                                                                                                                                |
| TotalMileage.Distance.UnitOfMeasure                     | string            | No       | Unit of measure for total mileage.                                                                                                                                                                                                                                  |
| TotalMileage.Source                                     | string            | No       | Source of mileage data.                                                                                                                                                                                                                                             |
| TotalMileage.ProfileName                                | string            | No       | Name of the mileage profile used.                                                                                                                                                                                                                                   |
| EmptyMileage.Distance.Value                             | number            | No       | Empty mileage value.                                                                                                                                                                                                                                                |
| LoadedMileage.Distance.Value                            | number            | No       | Loaded mileage value.                                                                                                                                                                                                                                               |
| PickupDate                                              | string (datetime) | No       | Scheduled pickup date.                                                                                                                                                                                                                                              |
| DeliveryDate                                            | string (datetime) | No       | Scheduled delivery date.                                                                                                                                                                                                                                            |
| PickedUpAt                                              | string (datetime) | No       | Actual pickup timestamp.                                                                                                                                                                                                                                            |
| DeliveredAt                                             | string (datetime) | No       | Actual delivery timestamp.                                                                                                                                                                                                                                          |
| CarrierAssignedAt                                       | string (datetime) | No       | Carrier assignment timestamp.                                                                                                                                                                                                                                       |
| TripValue.Amount                                        | number            | No       | Total trip value.                                                                                                                                                                                                                                                   |
| TripValue.Currency                                      | string            | No       | Currency for trip value.                                                                                                                                                                                                                                            |
| Truck.Id                                                | string            | No       | Truck ID.                                                                                                                                                                                                                                                           |
| Truck.Fleet.Id                                          | string            | No       | Fleet ID of the truck.                                                                                                                                                                                                                                              |
| Truck.Fleet.Name                                        | string            | No       | Fleet name of the truck.                                                                                                                                                                                                                                            |
| Trailer.Id                                              | string            | No       | Trailer ID.                                                                                                                                                                                                                                                         |
| Trailer.EquipmentType                                   | string            | No       | Equipment type of trailer.                                                                                                                                                                                                                                          |
| Temperature                                             | object            | No       | Temperature requirements for temperature-controlled trips. Returned only when configured; otherwise omitted from the response.                                                                                                                                      |
| Temperature.SetpointTemperature                         | number            | No       | Required target temperature.                                                                                                                                                                                                                                        |
| Temperature.SetpointTemperatureMax                      | number            | No       | Optional maximum temperature when a temperature range is defined.                                                                                                                                                                                                   |
| Temperature.ControlMode                                 | string            | No       | Operational mode of the trailer (`Continuous`, `Start/Stop`).                                                                                                                                                                                                       |
| RequiredEquipment\[]                                    | array of strings  | No       | List of equipment types required for the trip (e.g., `Reefer`, `Van`, `Flatbed`). Returned only when configured; omitted when no requirement exists.                                                                                                                |
| Eta                                                     | object            | No       | Estimated time of arrival at the trip's final stop. `null` when the trip has no stops or the final stop has no estimate. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned                                             | string (datetime) | No       | ETA from route planning for the final stop.                                                                                                                                                                                                                         |
| Eta.Live                                                | string (datetime) | No       | ETA for the final stop, recalculated from the latest vehicle location.                                                                                                                                                                                              |
| Eta.Manual                                              | string (datetime) | No       | ETA for the final stop entered by a user or integration.                                                                                                                                                                                                            |
| Driver1.Id                                              | string            | No       | Unique ID of Driver 1.                                                                                                                                                                                                                                              |
| Driver1.ContractorType                                  | string            | No       | Contractor type of Driver 1.                                                                                                                                                                                                                                        |
| Driver1.Rates\[]                                        | array             | No       | **Legacy field.** Old driver rate objects. Returned for backward compatibility and may be empty or outdated.                                                                                                                                                        |
| Driver1.RatesV2\[]                                      | array             | No       | New structured rate objects for Driver 1 showing applied pay rules and calculated line items.                                                                                                                                                                       |
| Driver1.RatesV2\[].PolicyId                             | string            | No       | Unique identifier of the applied rate policy.                                                                                                                                                                                                                       |
| Driver1.RatesV2\[].PolicyName                           | string            | No       | Display name of the rate policy.                                                                                                                                                                                                                                    |
| Driver1.RatesV2\[].PerTripRate.Rate                     | number            | No       | Flat per-trip pay rate applied to the trip.                                                                                                                                                                                                                         |
| Driver1.RatesV2\[].PerTripRate.RateId                   | string            | No       | Identifier of the per-trip rate type.                                                                                                                                                                                                                               |
| Driver1.RatesV2\[].PerTripRate.RateName                 | string            | No       | Name of the per-trip rate type.                                                                                                                                                                                                                                     |
| Driver1.RatesV2\[].PerTripRate.LineItems\[]             | array             | No       | Detailed line-item breakdown for per-trip rate.                                                                                                                                                                                                                     |
| Driver1.RatesV2\[].TripValuePercentageRate.Percentage   | number            | No       | Percentage of trip value used to calculate pay.                                                                                                                                                                                                                     |
| Driver1.RatesV2\[].TripValuePercentageRate.RateId       | string            | No       | Identifier of the percentage-based rate type.                                                                                                                                                                                                                       |
| Driver1.RatesV2\[].TripValuePercentageRate.RateName     | string            | No       | Name of the percentage-based rate.                                                                                                                                                                                                                                  |
| Driver1.RatesV2\[].TripValuePercentageRate.LineItems\[] | array             | No       | Line-item breakdown for percentage-based rate (description, amount, currency).                                                                                                                                                                                      |
| Driver2.Id                                              | string            | No       | Unique ID of Driver 2.                                                                                                                                                                                                                                              |
| Driver2.ContractorType                                  | string            | No       | Contractor type of Driver 2.                                                                                                                                                                                                                                        |
| Driver2.Rates\[]                                        | array             | No       | Legacy rate list for Driver 2 — may be empty or outdated.                                                                                                                                                                                                           |
| Driver2.RatesV2\[]                                      | array             | No       | Structured rate objects for Driver 2.                                                                                                                                                                                                                               |
| OwnerOperator.Id                                        | string            | No       | Unique ID of the owner-operator.                                                                                                                                                                                                                                    |
| OwnerOperator.Rates\[]                                  | array             | No       | Legacy rate list for Owner Operator — may be empty or outdated.                                                                                                                                                                                                     |
| OwnerOperator.RatesV2\[]                                | array             | No       | Structured rate objects for Owner Operator.                                                                                                                                                                                                                         |
| Carrier.Id                                              | string            | No       | Carrier ID.                                                                                                                                                                                                                                                         |
| Carrier.Rate.Amount                                     | number            | No       | Carrier rate amount.                                                                                                                                                                                                                                                |
| Carrier.Rate.Currency                                   | string            | No       | Carrier rate currency.                                                                                                                                                                                                                                              |
| Carrier.Linehaul.Amount                                 | number            | No       | Carrier linehaul amount.                                                                                                                                                                                                                                            |
| Carrier.Linehaul.Currency                               | string            | No       | Currency of linehaul.                                                                                                                                                                                                                                               |
| Carrier.TotalPayable.Amount                             | number            | No       | Total payable amount to the carrier.                                                                                                                                                                                                                                |
| Carrier.TotalPayable.Currency                           | string            | No       | Currency for total payable amount.                                                                                                                                                                                                                                  |
| DispatchedBy                                            | string            | No       | User who dispatched the trip.                                                                                                                                                                                                                                       |
| DispatcherId                                            | string            | No       | ID of the dispatcher.                                                                                                                                                                                                                                               |
| UpdatedAt                                               | string (datetime) | No       | Timestamp when the trip was last updated.                                                                                                                                                                                                                           |
| UpdatedBy                                               | string            | No       | User who last updated the trip.                                                                                                                                                                                                                                     |

#### ⚠️ Important Note on `Rates` and `RatesV2` Fields

Both the legacy `Rates[]` and the new `RatesV2[]` fields are currently returned in the Trips API response under `driver1`, `driver2`, and `ownerOperator`.

* The legacy **`Rates[]`** field remains available for backward compatibility but is no longer populated for new trips created after migration to Driver Settlement.
* For trips that existed prior to migration, `Rates[]` may still contain historical data; however, it can be out of sync with `RatesV2[]` if additional rate changes were made after migration.
* Integrations that continue to read data from `Rates[]` may receive empty or outdated arrays.
* To ensure accurate and complete pay information, integrations should rely on **`RatesV2[]`** going forward.

Each rate type (e.g., `tripValuePercentageRate`, `perTripRate`, `minimumPayRate`) within `RatesV2[]` is returned as a structured object with optional `lineItems[]` breakdowns.

### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the Versioning page.

### Example Response

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated.


# Get trip stop
Source: https://docs.alvys.com/en/api/reference/trips/get-trip-stop

GET /api/p/v{version}/trips/{tripId}/stops/{stopId}
Retrieve a single trip stop by trip and stop ID, including the location, appointment window, arrival and departure timestamps, and stop-level notes.

This endpoint retrieves a single stop record associated with a given trip, including scheduling information, arrival/departure timestamps, location details, and references.

### Endpoint

```
GET /api/p/v{version}/trips/{tripId}/stops/{stopId}
```

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                                    |
| --------- | ------ | -------- | ---------------------------------------------- |
| version   | String | Yes      | The API version to use.                        |
| tripId    | String | Yes      | Unique identifier of the trip.                 |
| stopId    | String | Yes      | Unique identifier of the stop within the trip. |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace:

* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `{stopId}` with the stop ID
* `YOUR_ACCESS_TOKEN` with your Bearer token

Example:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips/000c3a9bf0000000bf000d000e000a0b/stops/000a3b9bf0000000bf000d000e000a0c' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

| Parameter                 | Type              | Required | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Yes      | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.City              | string            | No       | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | No       | State of the stop location.                                                                                                                                                                                                                 |
| Address.Street            | string            | No       | Street address of the stop location.                                                                                                                                                                                                        |
| Address.ZipCode           | string            | No       | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | No       | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | No       | Appointment date/time for the stop. Populated when `scheduleType = APPT`.                                                                                                                                                                   |
| AppointmentRequested      | boolean           | No       | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | No       | Timestamp when the stop was arrived at (UTC).                                                                                                                                                                                               |
| CompanyId                 | string            | No       | Unique identifier of the company associated with the stop.                                                                                                                                                                                  |
| CompanyName               | string            | No       | Name of the company associated with the stop.                                                                                                                                                                                               |
| CompanyNumber             | string            | No       | Registration or identification number of the company.                                                                                                                                                                                       |
| Coordinates.Latitude      | string            | No       | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | No       | Longitude of the stop location.                                                                                                                                                                                                             |
| DepartedAt                | string (datetime) | No       | Timestamp when the stop was departed from (UTC).                                                                                                                                                                                            |
| Eta                       | object            | No       | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | No       | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | No       | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | No       | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| LoadingType               | string            | No       | Loading type at the stop (for example `Live`, `Drop`, `Hook`, `Drop&Hook`).                                                                                                                                                                 |
| References\[]             | array             | No       | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Access      | string            | No       | Access level of the reference (`Internal`, `Public`).                                                                                                                                                                                       |
| References\[].Id          | string            | No       | Unique identifier of the reference.                                                                                                                                                                                                         |
| References\[].Name        | string            | No       | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Origin      | string            | No       | Origin of the reference (for example `Manual`, `Integration`).                                                                                                                                                                              |
| References\[].ReferenceId | string            | No       | External reference identifier.                                                                                                                                                                                                              |
| References\[].Type        | string            | No       | Reference type (for example `Text`, `Date`).                                                                                                                                                                                                |
| References\[].Value       | string            | No       | Value of the reference.                                                                                                                                                                                                                     |
| ScheduleType              | string            | No       | Schedule type of the stop (`APPT` or `FCFS`).                                                                                                                                                                                               |
| Status                    | string            | No       | Current operational status of the stop.                                                                                                                                                                                                     |
| StopType                  | string            | No       | Type of stop (for example `Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                |
| StopWindow\.Begin         | string (datetime) | No       | Start of the delivery window when `scheduleType = FCFS`.                                                                                                                                                                                    |
| StopWindow\.End           | string (datetime) | No       | End of the delivery window when `scheduleType = FCFS`.                                                                                                                                                                                      |
| \$type                    | string            | No       | Polymorphic type discriminator for the stop representation (`appointment`, `delivery_window`, `waypoint`).                                                                                                                                  |

### Example Response

```json theme={null}
{
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "AppointmentDate": "2026-03-16T11:05:40.106Z",
  "ScheduleType": "APPT",
  "LoadingType": "Live",
  "Id": "string",
  "Address": {
    "Street": "123 Industrial Rd",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "75201"
  },
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "Status": "Open",
  "StopType": "Pickup",
  "ArrivedAt": "2026-03-16T11:05:40.106Z",
  "DepartedAt": "2026-03-16T11:45:40.106Z",
  "References": [
    {
      "Id": "string",
      "ReferenceId": "PO123456",
      "Name": "PO Number",
      "Value": "PO123456",
      "Type": "Text",
      "Access": "Public",
      "Origin": "Manual"
    }
  ],
  "CompanyId": "string",
  "CompanyNumber": "GT530",
  "CompanyName": "Alvys Distribution",
  "Eta": {
    "Planned": "2026-03-16T10:40:00.000Z",
    "Live": "2026-03-16T10:52:00.000Z",
    "Manual": null
  },
  "$type": "appointment"
}
```

### Status Codes

| Status Code   | Description                                    |
| ------------- | ---------------------------------------------- |
| 200 OK        | Stop successfully retrieved.                   |
| 404 Not Found | Trip or stop does not exist or is not visible. |

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using. Including the version ensures that your integration interacts with the correct API contract and remains compatible as the API evolves.

For more details, see the **Versioning** documentation.

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.\
Refer to the **Rate Limits** documentation for more information.

<br />


# List trip check calls
Source: https://docs.alvys.com/en/api/reference/trips/list-trip-check-calls

GET /api/p/v{version}/trips/{tripId}/check-calls
Returns the check calls (driver status updates) logged on a trip, most recent first.

Retrieve the check calls (driver status updates) logged on a specific trip by its unique `tripId`, most recent first. Check calls are trip-level: a driver is assigned per trip, and each trip carries its own latest check call.

### Endpoint

```
GET /api/p/v{version}/trips/{tripId}/check-calls
```

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | String | Yes      | API version to use (`1.0`).    |
| tripId    | String | Yes      | Unique identifier of the trip. |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/check-calls' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with `1.0`, `{tripId}` with the actual trip ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of check-call objects:

| Name                | Type         | Description                                                                       |
| ------------------- | ------------ | --------------------------------------------------------------------------------- |
| Id                  | string       | Unique identifier of the check call.                                              |
| LoadNumber          | string       | Load number the check call belongs to.                                            |
| Description         | string       | Free-text note captured with the check call (e.g. the driver's reply).            |
| Location            | object, null | Structured location (`Street`, `City`, `State`, `Zip`, `Country`, `Coordinates`). |
| CreatedAt           | string, null | UTC timestamp when the check call was recorded.                                   |
| Activity            | string, null | The activity reported (e.g. `Driving`, `At Pickup`).                              |
| ResponseType        | string, null | Categorization of the response (e.g. arrival, departure).                         |
| CreatedBy           | string, null | Name of the user or integration that logged the check call.                       |
| DriverName          | string, null | Assigned driver's name, if known.                                                 |
| TripId              | string       | Id of the trip the check call belongs to.                                         |
| TripNumber          | string, null | Related trip number, if known.                                                    |
| SetpointTemperature | object, null | Reefer set-point temperature (`Value`, `Unit`).                                   |
| ReturnTemperature   | object, null | Reefer return temperature (`Value`, `Unit`).                                      |

### Example Response (200 OK)

```json theme={null}
[
  {
    "Id": "9f1c2a7b3e4d4f8a9b0c1d2e3f4a5b6c",
    "LoadNumber": "L100245",
    "Description": "Driver reports on schedule",
    "Location": {
      "Street": "123 Main St",
      "City": "Dallas",
      "State": "TX",
      "Zip": "75001",
      "Country": "US",
      "Coordinates": { "Latitude": "32.7767", "Longitude": "-96.7970" }
    },
    "CreatedAt": "2026-07-08T15:04:07+00:00",
    "Activity": "Driving",
    "ResponseType": null,
    "CreatedBy": "public-api-tl743-integration",
    "DriverName": "Jordan Rivera",
    "TripId": "b93e5cf1b6134f5e9a78b07af2870d9b",
    "TripNumber": "T100245-1",
    "SetpointTemperature": { "Value": 34, "Unit": "Fahrenheit" },
    "ReturnTemperature": null
  }
]
```

### Status Codes

| Code | Meaning                                            |
| ---- | -------------------------------------------------- |
| 200  | Check calls returned (most recent first).          |
| 401  | Missing or invalid access token.                   |
| 403  | Token lacks the required scope.                    |
| 404  | Trip not found (or not accessible to your tenant). |
| 429  | Rate limit exceeded.                               |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **tripId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List trip documents
Source: https://docs.alvys.com/en/api/reference/trips/list-trip-documents

GET /api/p/v{version}/trips/{tripId}/documents
List all documents attached to a trip by trip ID, including driver-submitted PODs, scale tickets, fuel receipts, and other on-the-road paperwork.

Retrieve all uploaded documents associated with a specific **Trip** by its unique `tripId`.

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | String | Yes      | API version to use.            |
| tripId    | String | Yes      | Unique identifier of the trip. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{tripId}` with the actual trip ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                         |
| -------------- | ------- | ------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                  |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix). |
| AttachmentType | string  | Type of document (e.g., Trip Manifes, Proof of Delivery).           |
| AttachmentSize | integer | Size of the file in bytes.                                          |
| UploadedAt     | string  | UTC timestamp when the file was uploaded.                           |
| ParentId       | string  | Identifier of the parent entity (`tripId`).                         |
| ParentType     | string  | Entity type the document is attached to (`Trip`).                   |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.       |
| DownloadUrl    | string  | Time-limited link (10 minutes) to download the document.            |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl`.                          |

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "fe8b7d62-bc61-421e-b8b2-208bc9f7a34c",
    "AttachmentPath": "TripManifes-1759237626.pdf",
    "AttachmentType": "Trip Manifes",
    "AttachmentSize": 83200,
    "UploadedAt": "2025-09-30T15:07:07+00:00",
    "ParentId": "T98765",
    "ParentType": "Trip",
    "UploadedBy": "7190175eecc3408e90d7173f4ece0e59",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/Manifes-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T15:18:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **tripId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List trip stops
Source: https://docs.alvys.com/en/api/reference/trips/list-trip-stops

GET /api/p/v{version}/trips/{tripId}/stops
List all stops on a trip by trip ID in sequence order, returning location, appointment window, arrival and departure timestamps, and stop status for each.

Each stop contains scheduling information, location details, operational timestamps (arrival and departure), and optional references such as PO numbers or other identifiers.

### Endpoint

```
GET /api/p/v{version}/trips/{tripId}/stops
```

### Request Parameters

The following parameters are required in the URL path:

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | String | Yes      | The API version to use.        |
| tripId    | String | Yes      | Unique identifier of the trip. |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace:

* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `YOUR_ACCESS_TOKEN` with your Bearer token

Example:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips/000c3a9bf0000000bf000d000e000a0b/stops' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

***

### Response Parameters

| Parameter                 | Type              | Required | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Yes      | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.Street            | string            | No       | Street address of the stop location.                                                                                                                                                                                                        |
| Address.City              | string            | No       | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | No       | State of the stop location.                                                                                                                                                                                                                 |
| Address.ZipCode           | string            | No       | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | No       | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | No       | Appointment date/time when `scheduleType = APPT`.                                                                                                                                                                                           |
| AppointmentRequested      | boolean           | No       | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | No       | Timestamp when the stop was arrived at (UTC).                                                                                                                                                                                               |
| CompanyId                 | string            | No       | Unique identifier of the company associated with the stop.                                                                                                                                                                                  |
| CompanyName               | string            | No       | Name of the company associated with the stop.                                                                                                                                                                                               |
| CompanyNumber             | string            | No       | Company registration or identification number.                                                                                                                                                                                              |
| Coordinates.Latitude      | string            | No       | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | No       | Longitude of the stop location.                                                                                                                                                                                                             |
| DepartedAt                | string (datetime) | No       | Timestamp when the stop was departed from (UTC).                                                                                                                                                                                            |
| Eta                       | object            | No       | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | No       | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | No       | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | No       | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| LoadingType               | string            | No       | Loading type at the stop (for example `Live`, `Drop`, `Hook`, `Drop&Hook`).                                                                                                                                                                 |
| References\[]             | array             | No       | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Access      | string            | No       | Access level of the reference (`Internal`, `Public`).                                                                                                                                                                                       |
| References\[].Id          | string            | No       | Unique identifier of the reference.                                                                                                                                                                                                         |
| References\[].Name        | string            | No       | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Origin      | string            | No       | Origin of the reference (for example `Manual`, `Integration`).                                                                                                                                                                              |
| References\[].ReferenceId | string            | No       | External reference identifier.                                                                                                                                                                                                              |
| References\[].Type        | string            | No       | Reference type (for example `Text`, `Date`).                                                                                                                                                                                                |
| References\[].Value       | string            | No       | Value of the reference.                                                                                                                                                                                                                     |
| ScheduleType              | string            | No       | Schedule type of the stop (`APPT` or `FCFS`).                                                                                                                                                                                               |
| Status                    | string            | No       | Current operational status of the stop.                                                                                                                                                                                                     |
| StopType                  | string            | No       | Type of stop (for example `Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                |
| StopWindow\.Begin         | string (datetime) | No       | Start of the delivery window when `scheduleType = FCFS`.                                                                                                                                                                                    |
| StopWindow\.End           | string (datetime) | No       | End of the delivery window when `scheduleType = FCFS`.                                                                                                                                                                                      |
| \$type                    | string            | No       | Polymorphic type discriminator for the stop representation (`appointment`, `delivery_window`, `waypoint`).                                                                                                                                  |

### Example Response

```json theme={null}
[
  {
    "AppointmentRequested": true,
    "AppointmentConfirmed": true,
    "AppointmentDate": "2026-03-16T11:05:40.106Z",
    "ScheduleType": "APPT",
    "LoadingType": "Live",
    "Id": "string",
    "Address": {
      "Street": "123 Industrial Rd",
      "City": "Dallas",
      "State": "TX",
      "ZipCode": "75201"
    },
    "Coordinates": {
      "Latitude": "32.7767",
      "Longitude": "-96.7970"
    },
    "Status": "Open",
    "StopType": "Pickup",
    "ArrivedAt": "2026-03-16T11:05:40.106Z",
    "DepartedAt": "2026-03-16T11:45:40.106Z",
    "References": [
      {
        "Id": "string",
        "ReferenceId": "PO123456",
        "Name": "PO Number",
        "Value": "PO123456",
        "Type": "Text",
        "Access": "Public",
        "Origin": "Manual"
      }
    ],
    "CompanyId": "string",
    "CompanyNumber": "GT530",
    "CompanyName": "Alvys Distribution",
    "Eta": {
      "Planned": "2026-03-16T10:40:00.000Z",
      "Live": "2026-03-16T10:52:00.000Z",
      "Manual": null
    },
    "$type": "appointment"
  }
]
```

### Status Codes

| Status Code   | Description                            |
| ------------- | -------------------------------------- |
| 200 OK        | Trip stops successfully retrieved.     |
| 404 Not Found | Trip does not exist or is not visible. |

### Versioning

The `version` parameter in the URL path specifies which version of the API you are using. Including the version ensures that your integration interacts with the correct API contract and remains compatible as the API evolves.

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.\
Refer to the **Rate Limits** documentation for more information.

<br />


# Log a trip check call
Source: https://docs.alvys.com/en/api/reference/trips/log-a-trip-check-call

POST /api/p/v{version}/trips/{tripId}/check-calls
Logs a check call (driver status update) on an in-progress trip. Only accepted while the trip is Covered, Dispatched, or In Transit.

Log a check call (driver status update) on a trip. Check calls are trip-level, so the load number, trip number, identity, and timestamp are resolved server-side from the trip in the URL path.

The trip must be in progress (`Covered`, `Dispatched`, or `In Transit`); a check call on a terminal, pre-dispatch, or post-delivery-billing trip is rejected with `422`.

### Endpoint

```
POST /api/p/v{version}/trips/{tripId}/check-calls
```

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | String | Yes      | API version to use (`1.0`).    |
| tripId    | String | Yes      | Unique identifier of the trip. |

### Request Body

| Field               | Type   | Required | Description                                                                                                                                          |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Description         | string | Yes      | Free-text note for the check call (e.g. the driver's reply). Max 4000 characters.                                                                    |
| Activity            | string | No       | The activity reported (e.g. `Driving`, `At Pickup`). Max 100 characters.                                                                             |
| DriverId            | string | No       | Id of the driver to attribute the check call to. Must be one of the trip's assigned drivers (a team trip has two). Omit to record at the trip level. |
| Location            | object | No       | Structured location: `Street`, `City`, `State`, `Zip`, `Country`, `Coordinates` (). All fields optional.                                             |
| SetpointTemperature | object | No       | Reefer set-point temperature: `Value` (number) + `Unit` (`Fahrenheit` / `Celsius` / `Kelvin`).                                                       |
| ReturnTemperature   | object | No       | Reefer return temperature: `Value` + `Unit`.                                                                                                         |

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trips/{tripId}/check-calls' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Description": "Driver reports on schedule",
  "Activity": "Driving",
  "DriverId": "DR2517179655771527026",
  "Location": {
    "City": "Dallas",
    "State": "TX",
    "Coordinates": { "Latitude": "32.7767", "Longitude": "-96.7970" }
  },
  "SetpointTemperature": { "Value": 34, "Unit": "Fahrenheit" }
}'
```

Replace `{version}` with `1.0`, `{tripId}` with the actual trip ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

The created check-call object:

| Name                | Type         | Description                                                                       |
| ------------------- | ------------ | --------------------------------------------------------------------------------- |
| Id                  | string       | Unique identifier of the check call.                                              |
| LoadNumber          | string       | Load number the check call belongs to.                                            |
| Description         | string       | Free-text note captured with the check call.                                      |
| Location            | object, null | Structured location (`Street`, `City`, `State`, `Zip`, `Country`, `Coordinates`). |
| CreatedAt           | string, null | UTC timestamp when the check call was recorded.                                   |
| Activity            | string, null | The activity reported (e.g. `Driving`, `At Pickup`).                              |
| ResponseType        | string, null | Categorization of the response (e.g. arrival, departure).                         |
| CreatedBy           | string, null | Name of the user or integration that logged the check call.                       |
| DriverName          | string, null | Assigned driver's name, if known.                                                 |
| TripId              | string       | Id of the trip the check call belongs to.                                         |
| TripNumber          | string, null | Related trip number, if known.                                                    |
| SetpointTemperature | object, null | Reefer set-point temperature (`Value`, `Unit`).                                   |
| ReturnTemperature   | object, null | Reefer return temperature (`Value`, `Unit`).                                      |

### Example Response (201 Created)

```json theme={null}
{
  "Id": "9f1c2a7b3e4d4f8a9b0c1d2e3f4a5b6c",
  "LoadNumber": "L100245",
  "Description": "Driver reports on schedule",
  "Location": {
    "Street": "",
    "City": "Dallas",
    "State": "TX",
    "Zip": "",
    "Country": "",
    "Coordinates": { "Latitude": "32.7767", "Longitude": "-96.7970" }
  },
  "CreatedAt": "2026-07-08T15:04:07+00:00",
  "Activity": "Driving",
  "ResponseType": null,
  "CreatedBy": "public-api-tl743-integration",
  "DriverName": "Jordan Rivera",
  "TripId": "b93e5cf1b6134f5e9a78b07af2870d9b",
  "TripNumber": "T100245-1",
  "SetpointTemperature": { "Value": 34, "Unit": "Fahrenheit" },
  "ReturnTemperature": null
}
```

### Status Codes

| Code | Meaning                                                             |
| ---- | ------------------------------------------------------------------- |
| 201  | Check call logged.                                                  |
| 400  | Validation error (e.g. empty `Description`).                        |
| 401  | Missing or invalid access token.                                    |
| 403  | Token lacks the required scope.                                     |
| 404  | Trip not found (or not accessible to your tenant).                  |
| 422  | Trip is not in progress, or `DriverId` is not assigned to the trip. |
| 429  | Rate limit exceeded.                                                |

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **tripId** in the URL path and editing the request body.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Record stop arrival
Source: https://docs.alvys.com/en/api/reference/trips/record-stop-arrival

PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
Record the arrival timestamp on a trip stop by trip and stop ID, marking when the driver checked in at the shipper or consignee location.

This endpoint marks the stop as **arrived** and updates the stop’s `ArrivedAt` timestamp.\
The `ArrivedAt` field is required and must be an ISO 8601 date/time. A value sent without a UTC offset is read as the stop's local time.

<Note>
  **Accepted formats.** `yyyy-MM-dd`, optionally followed by `THH:mm`, `THH:mm:ss`, or fractional seconds, and optionally a `Z` or `±hh:mm` offset. A value in any other format — including `MM/dd/yyyy` — is rejected with `400` and the offending field named.
</Note>

The response returns the **updated stop object**.

***

### Endpoint

```
PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
```

***

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | string | Yes      | API version (e.g. `1.0`).      |
| tripId    | string | Yes      | Unique identifier of the trip. |
| stopId    | string | Yes      | Unique identifier of the stop. |

***

### Request Body

| Field     | Type              | Required | Description                                                                            |
| --------- | ----------------- | -------- | -------------------------------------------------------------------------------------- |
| ArrivedAt | string (datetime) | Yes      | Arrival timestamp, ISO 8601. Without a UTC offset it is read as the stop's local time. |

***

### Example Request Body

```json theme={null}
{
  "ArrivedAt": "2026-03-16T12:34:30.277Z"
}
```

***

### Example CURL request

```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/arrival' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ArrivedAt": "2026-03-16T12:34:30.277Z"
}'
```

***

### Response Parameters

| Parameter                 | Type              | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.Street            | string            | Street address of the stop location.                                                                                                                                                                                                        |
| Address.City              | string            | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | State of the stop location.                                                                                                                                                                                                                 |
| Address.ZipCode           | string            | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | Appointment date and time for the stop.                                                                                                                                                                                                     |
| AppointmentRequested      | boolean           | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | Timestamp when the stop was marked as arrived (UTC).                                                                                                                                                                                        |
| DepartedAt                | string (datetime) | Timestamp when the stop was departed (UTC).                                                                                                                                                                                                 |
| Eta                       | object            | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| ScheduleType              | string            | Schedule type (`APPT` or `FCFS`).                                                                                                                                                                                                           |
| LoadingType               | string            | Loading type (`Live`, `Drop`, `Hook`, etc.).                                                                                                                                                                                                |
| StopType                  | string            | Type of stop (`Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                            |
| Status                    | string            | Operational status of the stop.                                                                                                                                                                                                             |
| Coordinates.Latitude      | string            | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | Longitude of the stop location.                                                                                                                                                                                                             |
| References\[]             | array             | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Id          | string            | Reference identifier.                                                                                                                                                                                                                       |
| References\[].ReferenceId | string            | External reference identifier.                                                                                                                                                                                                              |
| References\[].Name        | string            | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Value       | string            | Value of the reference.                                                                                                                                                                                                                     |
| References\[].Type        | string            | Type of reference.                                                                                                                                                                                                                          |
| References\[].Access      | string            | Access level.                                                                                                                                                                                                                               |
| References\[].Origin      | string            | Origin of the reference.                                                                                                                                                                                                                    |
| CompanyId                 | string            | Identifier of the company associated with the stop.                                                                                                                                                                                         |
| CompanyNumber             | string            | Company registration or identification number.                                                                                                                                                                                              |
| CompanyName               | string            | Company name associated with the stop.                                                                                                                                                                                                      |

***

### Example Response

```json theme={null}
{
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "AppointmentDate": "2026-03-16T12:34:30.277Z",
  "ScheduleType": "string",
  "LoadingType": "string",
  "Id": "string",
  "Address": {
    "Street": "string",
    "City": "string",
    "State": "string",
    "ZipCode": "string"
  },
  "Coordinates": {
    "Latitude": "string",
    "Longitude": "string"
  },
  "Status": "string",
  "StopType": "string",
  "ArrivedAt": "2026-03-16T12:34:30.277Z",
  "DepartedAt": "2026-03-16T12:34:30.277Z",
  "References": [
    {
      "Id": "string",
      "ReferenceId": "string",
      "Name": "string",
      "Value": "string",
      "Type": "string",
      "Access": "string",
      "Origin": "string"
    }
  ],
  "CompanyId": "string",
  "CompanyNumber": "string",
  "CompanyName": "string",
  "Eta": {
    "Planned": "2026-03-16T10:40:00.000Z",
    "Live": "2026-03-16T10:52:00.000Z",
    "Manual": null
  }
}
```

***

### Status Codes

| Status Code     | Description                               |
| --------------- | ----------------------------------------- |
| 200 OK          | Stop arrival successfully recorded.       |
| 400 Bad Request | Invalid request body or timestamp format. |
| 404 Not Found   | Trip or stop could not be found.          |

***

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.

Refer to the **Rate Limits** documentation for more information.


# Record stop departure
Source: https://docs.alvys.com/en/api/reference/trips/record-stop-departure

PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/departure
Record the departure timestamp on a trip stop by trip and stop ID, marking when the driver left the shipper or consignee location for the next stop.

## Record Stop Departure

Records the departure time for a specific stop within a trip.

This endpoint marks the stop as **departed** and updates the stop's `DepartedAt` timestamp.\
The `DepartedAt` field is required and must be an ISO 8601 date/time. A value sent without a UTC offset is read as the stop's local time.

<Note>
  **Accepted formats.** `yyyy-MM-dd`, optionally followed by `THH:mm`, `THH:mm:ss`, or fractional seconds, and optionally a `Z` or `±hh:mm` offset. A value in any other format — including `MM/dd/yyyy` — is rejected with `400` and the offending field named.
</Note>

The response returns the **updated stop object**.

***

### Endpoint

```
PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/departure
```

***

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | string | Yes      | API version (e.g. `1.0`).      |
| tripId    | string | Yes      | Unique identifier of the trip. |
| stopId    | string | Yes      | Unique identifier of the stop. |

***

### Request Body

| Field      | Type              | Required | Description                                                                                                                |
| ---------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| DepartedAt | string (datetime) | Yes      | Departure timestamp, ISO 8601 (e.g. `2026-03-16T12:44:51.437Z`). Without a UTC offset it is read as the stop's local time. |

***

### Example Request Body

```json theme={null}
{
  "DepartedAt": "2026-03-16T12:44:51.437Z"
}
```

***

### Example CURL request

```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/departure' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "DepartedAt": "2026-03-16T12:44:51.437Z"
}'
```

Replace:

* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `{stopId}` with the stop ID
* `YOUR_ACCESS_TOKEN` with your Bearer token

***

### Response Parameters

| Parameter                 | Type              | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.Street            | string            | Street address of the stop location.                                                                                                                                                                                                        |
| Address.City              | string            | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | State of the stop location.                                                                                                                                                                                                                 |
| Address.ZipCode           | string            | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | Appointment date and time for the stop.                                                                                                                                                                                                     |
| AppointmentRequested      | boolean           | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | Timestamp when the stop was marked as arrived (UTC).                                                                                                                                                                                        |
| DepartedAt                | string (datetime) | Timestamp when the stop was marked as departed (UTC).                                                                                                                                                                                       |
| Eta                       | object            | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| ScheduleType              | string            | Schedule type (`APPT` or `FCFS`).                                                                                                                                                                                                           |
| LoadingType               | string            | Loading type (`Live`, `Drop`, `Hook`, etc.).                                                                                                                                                                                                |
| StopType                  | string            | Type of stop (`Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                            |
| Status                    | string            | Operational status of the stop.                                                                                                                                                                                                             |
| Coordinates.Latitude      | string            | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | Longitude of the stop location.                                                                                                                                                                                                             |
| References\[]             | array             | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Id          | string            | Reference identifier.                                                                                                                                                                                                                       |
| References\[].ReferenceId | string            | External reference identifier.                                                                                                                                                                                                              |
| References\[].Name        | string            | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Value       | string            | Value of the reference.                                                                                                                                                                                                                     |
| References\[].Type        | string            | Type of reference.                                                                                                                                                                                                                          |
| References\[].Access      | string            | Access level (`Public`, `Internal`).                                                                                                                                                                                                        |
| References\[].Origin      | string            | Origin of the reference.                                                                                                                                                                                                                    |
| CompanyId                 | string            | Identifier of the company associated with the stop.                                                                                                                                                                                         |
| CompanyNumber             | string            | Company registration or identification number.                                                                                                                                                                                              |
| CompanyName               | string            | Company name associated with the stop.                                                                                                                                                                                                      |

***

### Example Response

```json theme={null}
{
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "AppointmentDate": "2026-03-16T12:44:51.437Z",
  "ScheduleType": "string",
  "LoadingType": "string",
  "Id": "string",
  "Address": {
    "Street": "string",
    "City": "string",
    "State": "string",
    "ZipCode": "string"
  },
  "Coordinates": {
    "Latitude": "string",
    "Longitude": "string"
  },
  "Status": "string",
  "StopType": "string",
  "ArrivedAt": "2026-03-16T12:44:51.437Z",
  "DepartedAt": "2026-03-16T12:44:51.437Z",
  "References": [
    {
      "Id": "string",
      "ReferenceId": "string",
      "Name": "string",
      "Value": "string",
      "Type": "string",
      "Access": "string",
      "Origin": "string"
    }
  ],
  "CompanyId": "string",
  "CompanyNumber": "string",
  "CompanyName": "string",
  "Eta": {
    "Planned": "2026-03-16T10:40:00.000Z",
    "Live": "2026-03-16T10:52:00.000Z",
    "Manual": null
  }
}
```

***

### Status Codes

| Status Code              | Description                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------ |
| 200 OK                   | Stop departure successfully recorded.                                                |
| 400 Bad Request          | Invalid request body or timestamp format.                                            |
| 404 Not Found            | Trip or stop could not be found.                                                     |
| 422 Unprocessable Entity | No prior arrival has been recorded for the stop. Departure requires a prior arrival. |

***

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.

Refer to the **Rate Limits** documentation for more information.


# Search trips
Source: https://docs.alvys.com/en/api/reference/trips/search-trips

POST /api/p/v{version}/trips/search
Search trips with paginated POST filters — driver, truck, status, load number, planned pickup and delivery windows, origin, and destination.

This endpoint provides detailed information about each trip that matches the search criteria, enabling efficient management and retrieval of trip records.

#### Request Body Parameters

The following parameters are required in the request body:

| Parameter               | Type               | Required      | Description                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                    | Integer            | Yes           | The page number to retrieve.                                                                                                                                                                                                                                                                                     |
| PageSize                | Integer            | Yes           | The number of items per page. Must be greater than 0.                                                                                                                                                                                                                                                            |
| Status                  | Array of Strings   | Conditionally | The status of the trip. Must be one or more of the allowed values: "Open", "Reserved", "Covered", "Dispatched", "In Transit", "Delivered", "Invoiced", "Completed", "Quoted", "Released", "TONU", "Cancelled", "Queued", "Financed", "Paid", "In Review". Required if no other conditional filters are provided. |
| LoadNumbers             | Array of Strings   | Conditionally | The load number(s) associated with the trips. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                  |
| TripNumbers             | Array of Strings   | Conditionally | The trip number(s) to search for. This field is required if items matching the other conditionally required fields are left empty.                                                                                                                                                                               |
| PickupDateRange         | Object             | No            | The range of pickup dates to filter by.                                                                                                                                                                                                                                                                          |
| PickupDateRange.Start   | String (Date-Time) | No            | The start date of the pickup range.                                                                                                                                                                                                                                                                              |
| PickupDateRange.End     | String (Date-Time) | No            | The end date of the pickup range.                                                                                                                                                                                                                                                                                |
| DeliveryDateRange       | Object             | No            | The range of delivery dates to filter by.                                                                                                                                                                                                                                                                        |
| DeliveryDateRange.Start | String (Date-Time) | No            | The start date of the delivery range.                                                                                                                                                                                                                                                                            |
| DeliveryDateRange.End   | String (Date-Time) | No            | The end date of the delivery range.                                                                                                                                                                                                                                                                              |
| UpdatedAtRange          | Object             | No            | The range of update timestamps to filter by.                                                                                                                                                                                                                                                                     |
| UpdatedAtRange.Start    | String (Date-Time) | No            | The start date of the updatedAt range.                                                                                                                                                                                                                                                                           |
| UpdatedAtRange.End      | String (Date-Time) | No            | The end date of the updatedAt range.                                                                                                                                                                                                                                                                             |
| UpdatedBy               | String             | Conditionally | The user who last updated the trips. This field is required if the other conditionally required fields are left empty.                                                                                                                                                                                           |
| IncludeDeleted          | Boolean            | No            | When set to `true`, the response will include both active and deleted trips (with `"IsDeleted": true` for deleted items). If `false` or omitted, only active records are returned and no `IsDeleted` flags are included.                                                                                         |

<br />

#### Example CURL request

Use the Current API version The load number and make sure to replace the Authorization header value associated with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trips/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
"Page": 0,
"PageSize": 100,
"Status": [
"Covered"
],
"UpdatedBy" : "0d00f000-1b85-4ed8-000-6a000d1111db",
"UpdatedAtRange": {
"Start": "2024-09-09T13:09:30.788Z",
"End": "2024-10-19T13:09:30.788Z"
},
"LoadNumbers": [
"123456789"
],
"TripNumbers": [
"123456789"
],
"PickupDateRange": {
"Start": "2025-07-23T10:45:56.477Z",
"End": "2025-07-23T10:45:56.477Z"
},
"DeliveryDateRange": {
"Start": "2025-07-23T10:45:56.477Z",
"End": "2025-07-23T10:45:56.477Z"
}
}'
```

#### Response Body Parameters

The following parameters are required in the request body:

| Parameter                                                   | Type              | Required | Description                                                                                                                                                                                                                                                         |
| :---------------------------------------------------------- | :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Page                                                        | integer           | No       | The current page of the response.                                                                                                                                                                                                                                   |
| PageSize                                                    | integer           | Yes      | The number of items per page.                                                                                                                                                                                                                                       |
| Total                                                       | integer           | Yes      | The total number of items matching the criteria.                                                                                                                                                                                                                    |
| Items\[].Id                                                 | string            | Yes      | The unique identifier of the trip.                                                                                                                                                                                                                                  |
| Items\[].TripNumber                                         | string            | Yes      | The number associated with the trip.                                                                                                                                                                                                                                |
| Items\[].Status                                             | string            | No       | The current status of the trip. Will always be one of the allowed values: "Open", "Reserved", "Covered", "Dispatched", "In Transit", "Delivered", "Invoiced", "Completed", "Quoted", "Released", "TONU", "Cancelled", "Queued", "Financed", "Paid", "In Review".    |
| Items\[].LoadNumber                                         | string            | No       | The load number associated with the trip.                                                                                                                                                                                                                           |
| Items\[].TenderAs                                           | string            | No       | Role under which the trip was tendered.                                                                                                                                                                                                                             |
| Items\[].Stops\[]                                           | array of objects  | No       | The list of stops associated with the trip.                                                                                                                                                                                                                         |
| Items\[].Stops\[].Id                                        | string            | No       | The unique identifier of the stop.                                                                                                                                                                                                                                  |
| Items\[].Stops\[].Address.Street                            | string            | No       | The street address of the stop.                                                                                                                                                                                                                                     |
| Items\[].Stops\[].Address.City                              | string            | No       | The city of the stop.                                                                                                                                                                                                                                               |
| Items\[].Stops\[].Address.State                             | string            | No       | The state of the stop.                                                                                                                                                                                                                                              |
| Items\[].Stops\[].Address.ZipCode                           | string            | No       | The ZIP code of the stop.                                                                                                                                                                                                                                           |
| Items\[].Stops\[].Coordinates.Latitude                      | string            | No       | The latitude of the stop location.                                                                                                                                                                                                                                  |
| Items\[].Stops\[].Coordinates.Longitude                     | string            | No       | The longitude of the stop location.                                                                                                                                                                                                                                 |
| Items\[].Stops\[].Status                                    | string            | No       | The current status of the stop.                                                                                                                                                                                                                                     |
| Items\[].Stops\[].StopType                                  | string            | No       | The type of stop (e.g., Pickup, Delivery).                                                                                                                                                                                                                          |
| Items\[].Stops\[].ScheduleType                              | string            | No       | The schedule type of the stop. If `APPT`, see `appointmentDate`; if `FCFS`, see `stopWindow.*`.                                                                                                                                                                     |
| Items\[].Stops\[].AppointmentDate                           | string (datetime) | No       | Appointment date/time for the stop. **Only populated when `scheduleType = APPT`.**                                                                                                                                                                                  |
| Items\[].Stops\[].StopWindow\.Begin                         | string (datetime) | No       | Window begin time for the stop. **Only populated when `scheduleType = FCFS`.**                                                                                                                                                                                      |
| Items\[].Stops\[].StopWindow\.End                           | string (datetime) | No       | Window end time for the stop. **Only populated when `scheduleType = FCFS`.**                                                                                                                                                                                        |
| Items\[].Stops\[].LoadingType                               | string            | No       | The loading type at the stop.                                                                                                                                                                                                                                       |
| Items\[].Stops\[].ArrivedAt                                 | string (datetime) | No       | When the stop was arrived at (UTC).                                                                                                                                                                                                                                 |
| Items\[].Stops\[].DepartedAt                                | string (datetime) | No       | When the stop was departed from (UTC).                                                                                                                                                                                                                              |
| Items\[].Stops\[].References\[]                             | array of objects  | No       | A list of references associated with the stop.                                                                                                                                                                                                                      |
| Items\[].Stops\[].References\[].Id                          | string            | No       | The unique identifier of the reference.                                                                                                                                                                                                                             |
| Items\[].Stops\[].References\[].ReferenceId                 | string            | No       | The external reference ID.                                                                                                                                                                                                                                          |
| Items\[].Stops\[].References\[].Name                        | string            | No       | The name of the reference.                                                                                                                                                                                                                                          |
| Items\[].Stops\[].References\[].Value                       | string            | No       | The value of the reference.                                                                                                                                                                                                                                         |
| Items\[].Stops\[].References\[].Type                        | string            | No       | The type of reference (e.g., Text, Date).                                                                                                                                                                                                                           |
| Items\[].Stops\[].References\[].Access                      | string            | No       | The access level (e.g., Internal, Public).                                                                                                                                                                                                                          |
| Items\[].Stops\[].References\[].Origin                      | string            | No       | Origin of the reference field (e.g., Manual, Integration).                                                                                                                                                                                                          |
| Items\[].Stops\[].CompanyId                                 | string            | No       | The unique identifier of the company associated with the stop.                                                                                                                                                                                                      |
| Items\[].Stops\[].CompanyNumber                             | string            | No       | The number of registration or identification number of the company linked to the stop.                                                                                                                                                                              |
| Items\[].Stops\[].CompanyName                               | string            | No       | Name of the company linked to this stop.                                                                                                                                                                                                                            |
| Items\[].Stops\[].Eta                                       | object            | No       | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan.                         |
| Items\[].Stops\[].Eta.Planned                               | string (datetime) | No       | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                                                |
| Items\[].Stops\[].Eta.Live                                  | string (datetime) | No       | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                                                     |
| Items\[].Stops\[].Eta.Manual                                | string (datetime) | No       | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                                               |
| Items\[].TotalMileage.Distance.Value                        | number            | No       | Total mileage value.                                                                                                                                                                                                                                                |
| Items\[].TotalMileage.Distance.UnitOfMeasure                | string            | No       | Unit of measure for total mileage (e.g., Miles).                                                                                                                                                                                                                    |
| Items\[].TotalMileage.Source                                | string            | No       | Source of total mileage.                                                                                                                                                                                                                                            |
| Items\[].TotalMileage.ProfileId                             | string            | No       | ID of mileage profile used.                                                                                                                                                                                                                                         |
| Items\[].TotalMileage.ProfileName                           | string            | No       | Name of mileage profile used.                                                                                                                                                                                                                                       |
| Items\[].EmptyMileage.Distance.Value                        | number            | No       | Empty mileage value.                                                                                                                                                                                                                                                |
| Items\[].LoadedMileage.Distance.Value                       | number            | No       | Loaded mileage value.                                                                                                                                                                                                                                               |
| Items\[].PickupDate                                         | string (datetime) | No       | Scheduled pickup date.                                                                                                                                                                                                                                              |
| Items\[].DeliveryDate                                       | string (datetime) | No       | Scheduled delivery date.                                                                                                                                                                                                                                            |
| Items\[].PickedUpAt                                         | string (datetime) | No       | Actual pickup timestamp.                                                                                                                                                                                                                                            |
| Items\[].DeliveredAt                                        | string (datetime) | No       | Actual delivery timestamp.                                                                                                                                                                                                                                          |
| Items\[].CarrierAssignedAt                                  | string (datetime) | No       | Carrier assignment timestamp.                                                                                                                                                                                                                                       |
| Items\[].ReleasedAt                                         | string (datetime) | No       | Timestamp when the trip was marked as released.                                                                                                                                                                                                                     |
| Items\[].TripValue.Amount                                   | number            | No       | Total trip value.                                                                                                                                                                                                                                                   |
| Items\[].TripValue.Currency                                 | string            | No       | Currency for trip value.                                                                                                                                                                                                                                            |
| Items\[].Truck.Id                                           | string            | No       | ID of the truck.                                                                                                                                                                                                                                                    |
| Items\[].Trailer.Id                                         | string            | No       | ID of the trailer.                                                                                                                                                                                                                                                  |
| Items\[].Trailer.EquipmentType                              | string            | No       | Equipment type of trailer.                                                                                                                                                                                                                                          |
| Items\[].Trailer.EquipmentLength.Value                      | number            | No       | Trailer length.                                                                                                                                                                                                                                                     |
| Items\[].Trailer.EquipmentLength.Unit                       | string            | No       | Unit for trailer length (e.g., Feet).                                                                                                                                                                                                                               |
| Items\[].Driver1.AccessorialsDetails\[]                     | array of objects  | No       | List of driver1 accessorials.                                                                                                                                                                                                                                       |
| Items\[].Driver2.AccessorialsDetails\[]                     | array of objects  | No       | List of driver2 accessorials.                                                                                                                                                                                                                                       |
| Items\[].OwnerOperator.AccessorialsDetails\[]               | array of objects  | No       | List of owner-operator accessorials.                                                                                                                                                                                                                                |
| Items\[].Carrier.AccessorialsDetails\[]                     | array of objects  | No       | List of carrier accessorials.                                                                                                                                                                                                                                       |
| Items\[].\*.AccessorialsDetails\[].Id                       | string            | No       | Unique ID of the accessorial.                                                                                                                                                                                                                                       |
| Items\[].\*.AccessorialsDetails\[].Type                     | string            | No       | Type of accessorial (e.g., Detention).                                                                                                                                                                                                                              |
| Items\[].\*.AccessorialsDetails\[].Total.Amount             | number            | No       | Total charge amount.                                                                                                                                                                                                                                                |
| Items\[].\*.AccessorialsDetails\[].Total.Currency           | string            | No       | Currency of the total.                                                                                                                                                                                                                                              |
| Items\[].\*.AccessorialsDetails\[].Rate.Amount              | number            | No       | Rate per unit.                                                                                                                                                                                                                                                      |
| Items\[].\*.AccessorialsDetails\[].Rate.Currency            | string            | No       | Currency of the rate.                                                                                                                                                                                                                                               |
| Items\[].\*.AccessorialsDetails\[].RateType                 | string            | No       | Rate type (Flat, PerHour, etc).                                                                                                                                                                                                                                     |
| Items\[].\*.AccessorialsDetails\[].Uom                      | string            | No       | Unit of measure (e.g., Hours, Miles).                                                                                                                                                                                                                               |
| Items\[].\*.AccessorialsDetails\[].Quantity                 | number            | No       | Quantity of units billed.                                                                                                                                                                                                                                           |
| Items\[].\*.AccessorialsDetails\[].IsPaid                   | boolean           | No       | If present, indicates whether accessorial has been paid.                                                                                                                                                                                                            |
| Items\[].\*.AccessorialsDetails\[].StopId                   | string            | No       | ID of the stop this accessorial is linked to (if applicable).                                                                                                                                                                                                       |
| Items\[].\*.AccessorialsDetails\[].ECheckNumber             | string            | No       | Associated ECheck number if applicable.                                                                                                                                                                                                                             |
| Items\[].\*.AccessorialsDetails\[].CreatedAt                | string (datetime) | No       | When the accessorial was created (UTC).                                                                                                                                                                                                                             |
| Items\[].\*.AccessorialsDetails\[].CreatedBy                | string            | No       | User who created the accessorial.                                                                                                                                                                                                                                   |
| Items\[].\*.AccessorialsDetails\[].UpdatedAt                | string (datetime) | No       | When the accessorial was last updated (UTC).                                                                                                                                                                                                                        |
| Items\[].\*.AccessorialsDetails\[].UpdatedBy                | string            | No       | User who last updated the accessorial.                                                                                                                                                                                                                              |
| Items\[].\*.EChecks\[]                                      | array of objects  | No       | List of EChecks issued to driver1, driver2, or ownerOperator.                                                                                                                                                                                                       |
| Items\[].\*.EChecks\[].Id                                   | string            | No       | Unique ID of the ECheck.                                                                                                                                                                                                                                            |
| Items\[].\*.EChecks\[].CheckNumber                          | string            | No       | ECheck number.                                                                                                                                                                                                                                                      |
| Items\[].\*.EChecks\[].Amount.Amount                        | number            | No       | Amount value of the ECheck.                                                                                                                                                                                                                                         |
| Items\[].\*.EChecks\[].Amount.Currency                      | string            | No       | Currency of the ECheck amount.                                                                                                                                                                                                                                      |
| Items\[].\*.EChecks\[].Fee.Amount                           | number            | No       | Fee value of the ECheck.                                                                                                                                                                                                                                            |
| Items\[].\*.EChecks\[].Fee.Currency                         | string            | No       | Currency of the fee.                                                                                                                                                                                                                                                |
| Items\[].\*.EChecks\[].Type                                 | string            | No       | Type of ECheck.                                                                                                                                                                                                                                                     |
| Items\[].\*.EChecks\[].IsPaid                               | boolean           | No       | Indicates whether the ECheck is paid.                                                                                                                                                                                                                               |
| Items\[].\*.EChecks\[].CreatedAt                            | string (datetime) | No       | When the ECheck was created (UTC).                                                                                                                                                                                                                                  |
| Items\[].Carrier.Linehaul.Amount                            | number            | No       | Carrier linehaul amount.                                                                                                                                                                                                                                            |
| Items\[].Carrier.Linehaul.Currency                          | string            | No       | Currency of linehaul.                                                                                                                                                                                                                                               |
| Items\[].Carrier.Accessorials.Amount                        | number            | No       | Total accessorials amount for carrier.                                                                                                                                                                                                                              |
| Items\[].Carrier.Accessorials.Currency                      | string            | No       | Currency for carrier accessorials.                                                                                                                                                                                                                                  |
| Items\[].Carrier.TotalPayable.Amount                        | number            | No       | Total amount payable to carrier.                                                                                                                                                                                                                                    |
| Items\[].Carrier.TotalPayable.Currency                      | string            | No       | Currency for total payable amount.                                                                                                                                                                                                                                  |
| Items\[].Carrier.CarrierInvoiceNumber                       | string            | No       | Invoice number from the carrier.                                                                                                                                                                                                                                    |
| Items\[].Carrier.Id                                         | string            | No       | Unique ID of the carrier.                                                                                                                                                                                                                                           |
| Items\[].ReleasedBy                                         | string            | No       | User who released the trip.                                                                                                                                                                                                                                         |
| Items\[].DispatchedBy                                       | string            | No       | User who dispatched the trip.                                                                                                                                                                                                                                       |
| Items\[].DispatcherId                                       | string            | No       | ID of the dispatcher.                                                                                                                                                                                                                                               |
| Items\[].CarrierSalesAgentId                                | string            | No       | ID of the carrier sales agent.                                                                                                                                                                                                                                      |
| Items\[].CarrierPayOnHold                                   | boolean           | No       | Indicates if carrier payment is on hold.                                                                                                                                                                                                                            |
| Items\[].UpdatedAt                                          | string (datetime) | No       | Timestamp when the trip was last updated.                                                                                                                                                                                                                           |
| Items\[].UpdatedBy                                          | string            | No       | User who last updated the trip.                                                                                                                                                                                                                                     |
| Items\[].IsDeleted                                          | boolean           | No       | Indicates if trip is deleted (true) or active (false). Only shown when IncludeDeleted: true.                                                                                                                                                                        |
| Items\[].Driver1.Rates\[]                                   | array             | No       | Legacy rate objects for **Driver 1** — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be **deprecated**.                                                       |
| Items\[].Driver2.Rates\[]                                   | array             | No       | Legacy rate objects for **Driver 2** — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be **deprecated**.                                                       |
| Items\[].OwnerOperator.Rates\[]                             | array             | No       | Legacy rate objects for **Owner Operator** — used before the new driver rate-policy logic was introduced. This field remains for backward compatibility but is currently returned empty and will be **deprecated**.                                                 |
| Items\[].Driver1.RatesV2\[]                                 | array             | No       | List of structured rate objects for **Driver 1** showing applied pay rules and calculated line items.                                                                                                                                                               |
| Items\[].Driver2.RatesV2\[]                                 | array             | No       | List of structured rate objects for **Driver 2** showing applied pay rules and calculated line items.                                                                                                                                                               |
| Items\[].OwnerOperator.RatesV2\[]                           | array             | No       | List of structured rate objects for **Owner Operator** showing applied pay rules and calculated line items.                                                                                                                                                         |
| Items\[].\*.RatesV2\[].PolicyId                             | string            | No       | Unique identifier of the specific pay policy instance applied to this driver for this trip.                                                                                                                                                                         |
| Items\[].\*.RatesV2\[].PolicyName                           | string            | No       | Display name of the rate policy as shown in the UI.                                                                                                                                                                                                                 |
| Items\[].\*.RatesV2\[].PerTripRate.Rate                     | number            | No       | Flat per-trip pay rate applied to the trip.                                                                                                                                                                                                                         |
| Items\[].\*.RatesV2\[].PerTripRate.RateId                   | string            | No       | Identifies the rate type defined within that policy.                                                                                                                                                                                                                |
| Items\[].\*.RatesV2\[].PerTripRate.RateName                 | string            | No       | Name of the per-trip rate type.                                                                                                                                                                                                                                     |
| Items\[].\*.RatesV2\[].PerTripRate.LineItems\[]             | array             | No       | Detailed line-item breakdown for the per-trip rate (description and amount).                                                                                                                                                                                        |
| Items\[].\*.RatesV2\[].TripValuePercentageRate.Percentage   | number            | No       | Percentage of trip value used to calculate pay.                                                                                                                                                                                                                     |
| Items\[].\*.RatesV2\[].TripValuePercentageRate.RateId       | string            | No       | Identifier of the percentage-based rate type.                                                                                                                                                                                                                       |
| Items\[].\*.RatesV2\[].TripValuePercentageRate.RateName     | string            | No       | Name of the percentage-based rate.                                                                                                                                                                                                                                  |
| Items\[].\*.RatesV2\[].TripValuePercentageRate.LineItems\[] | array             | No       | Line-item breakdown for the percentage-based rate (description, amount, currency).                                                                                                                                                                                  |
| Items\[].RequiredEquipment\[]                               | array of strings  | No       | List of equipment types required for the trip (e.g., "Reefer", "Van", "Flatbed"). Returned only when configured; otherwise omitted.                                                                                                                                 |
| Items\[].Temperature                                        | object            | No       | Temperature requirements for temperature-controlled trips. Returned only when configured; otherwise omitted.                                                                                                                                                        |
| Items\[].Temperature.SetpointTemperature                    | number            | No       | Required target temperature.                                                                                                                                                                                                                                        |
| Items\[].Temperature.SetpointTemperatureMax                 | number            | No       | Optional maximum temperature when a range is defined.                                                                                                                                                                                                               |
| Items\[].Temperature.ControlMode                            | string            | No       | Operational mode ("Continuous", "Start/Stop").                                                                                                                                                                                                                      |
| Items\[].Eta                                                | object            | No       | Estimated time of arrival at the trip's final stop. `null` when the trip has no stops or the final stop has no estimate. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Items\[].Eta.Planned                                        | string (datetime) | No       | ETA from route planning for the final stop.                                                                                                                                                                                                                         |
| Items\[].Eta.Live                                           | string (datetime) | No       | ETA for the final stop, recalculated from the latest vehicle location.                                                                                                                                                                                              |
| Items\[].Eta.Manual                                         | string (datetime) | No       | ETA for the final stop entered by a user or integration.                                                                                                                                                                                                            |

#### ⚠️ Important Note on `Rates` and `RatesV2` Fields

Both the legacy `Rates[]` and the new `RatesV2[]` fields are currently returned in the Trips API response under `Driver1`, `Driver2`, and `OwnerOperator`.

* The legacy **`Rates[]`** field remains available for backward compatibility but is no longer populated for **new trips created after migration** to Driver Settlement.
* For **trips that existed prior to migration**, `Rates[]` may still contain historical data; however, it can be **out of sync** with `RatesV2[]` if additional rate changes were made after migration.
* Integrations that continue to read data from `Rates[]` will receive **empty or outdated arrays**.
* To ensure accurate and complete pay information, integrations should rely solely on **`RatesV2[]`** going forward.

Each rate type (e.g., `TripValuePercentageRate`, `PerTripRate`, `MinimumPayRate`, etc.) within `RatesV2[]` is provided as a **structured object** with detailed breakdowns via optional `LineItems[]`.

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

<br />


# Set stop appointment
Source: https://docs.alvys.com/en/api/reference/trips/set-stop-appointment

PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment
Set or update the appointment window on a trip stop by trip and stop ID, including scheduled date, start and end time, and appointment type.

Updates the scheduling information for a specific stop within a trip.

This endpoint allows updating the stop appointment details including:

* schedule type
* loading type
* appointment date
* appointment request / confirmation flags
* delivery window (for FCFS stops)

The response returns the **updated stop object**.

***

### Endpoint

```
PUT /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment
```

***

### Request Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| version   | string | Yes      | API version (e.g. `1.0`).      |
| tripId    | string | Yes      | Unique identifier of the trip. |
| stopId    | string | Yes      | Unique identifier of the stop. |

***

### Request Body

| Field                | Type              | Required    | Description                                                                                                                                   |
| -------------------- | ----------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| ScheduleType         | string            | Yes         | Schedule type of the stop (`APPT` or `FCFS`).                                                                                                 |
| LoadingType          | string            | Yes         | Loading type (`Live`, `Drop`, `Hook`, `Drop&Hook`).                                                                                           |
| AppointmentDate      | string (datetime) | Conditional | Appointment date and time, ISO 8601. Required when `ScheduleType = APPT`.                                                                     |
| AppointmentRequested | boolean           | Yes         | Indicates whether an appointment has been requested.                                                                                          |
| AppointmentConfirmed | boolean           | Yes         | Indicates whether the appointment has been confirmed.                                                                                         |
| WindowBegin          | string (datetime) | Conditional | Start of the delivery window, ISO 8601. Required when `ScheduleType = FCFS`.                                                                  |
| WindowEnd            | string (datetime) | No          | End of the delivery window, ISO 8601. Used when `ScheduleType = FCFS`. If provided alongside `WindowBegin`, must be later than `WindowBegin`. |

<Note>
  **Accepted date/time formats.** `yyyy-MM-dd`, optionally followed by `THH:mm`, `THH:mm:ss`, or fractional seconds, and optionally a `Z` or `±hh:mm` offset. A value in any other format — including `MM/dd/yyyy` — is rejected with `400` and the offending field named. A value sent without a UTC offset is read as the stop's local time.

  `WindowBegin` and `WindowEnd` are compared as points in time, not as digits, so a pair sent with different offsets is accepted when it is correctly ordered.
</Note>

<Warning>
  **Conditional validation rules:**

  * If `ScheduleType = APPT`, you must provide `AppointmentDate`.
  * If `ScheduleType = FCFS`, you must provide `WindowBegin`.
  * If both `WindowBegin` and `WindowEnd` are provided, `WindowBegin` must be earlier than `WindowEnd`.
</Warning>

***

### Example Request Body

```json theme={null}
{
  "ScheduleType": "string",
  "LoadingType": "string",
  "AppointmentDate": "string",
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "WindowBegin": "string",
  "WindowEnd": "string"
}
```

***

### Example CURL request

```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v1/trips/{tripId}/stops/{stopId}/appointment' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ScheduleType": "APPT",
  "LoadingType": "Live",
  "AppointmentDate": "2026-03-16T12:45:43.262Z",
  "AppointmentRequested": true,
  "AppointmentConfirmed": true
}'
```

Replace:

* `{version}` with the API version (for example `1`)
* `{tripId}` with the actual trip ID
* `{stopId}` with the stop ID
* `YOUR_ACCESS_TOKEN` with your Bearer token

***

### Response Parameters

| Parameter                 | Type              | Description                                                                                                                                                                                                                                 |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Id                        | string            | Unique identifier of the stop.                                                                                                                                                                                                              |
| Address.Street            | string            | Street address of the stop location.                                                                                                                                                                                                        |
| Address.City              | string            | City of the stop location.                                                                                                                                                                                                                  |
| Address.State             | string            | State of the stop location.                                                                                                                                                                                                                 |
| Address.ZipCode           | string            | ZIP code of the stop location.                                                                                                                                                                                                              |
| AppointmentConfirmed      | boolean           | Indicates whether the appointment has been confirmed.                                                                                                                                                                                       |
| AppointmentDate           | string (datetime) | Appointment date and time for the stop.                                                                                                                                                                                                     |
| AppointmentRequested      | boolean           | Indicates whether an appointment has been requested.                                                                                                                                                                                        |
| ArrivedAt                 | string (datetime) | Timestamp when the stop was marked as arrived (UTC).                                                                                                                                                                                        |
| DepartedAt                | string (datetime) | Timestamp when the stop was marked as departed (UTC).                                                                                                                                                                                       |
| Eta                       | object            | Estimated time of arrival at this stop. `null` when no planned, live, or manual estimate exists. `Planned` and `Live` require HOS-aware ETAs (Growth or Scale package, or the Samsara Premium add-on); `Manual` is available on every plan. |
| Eta.Planned               | string (datetime) | ETA from route planning, set when the trip is planned or re-planned.                                                                                                                                                                        |
| Eta.Live                  | string (datetime) | ETA recalculated from the latest vehicle location while the trip is in transit.                                                                                                                                                             |
| Eta.Manual                | string (datetime) | ETA entered by a user or integration, or defaulted from the stop date or appointment.                                                                                                                                                       |
| ScheduleType              | string            | Schedule type (`APPT` or `FCFS`).                                                                                                                                                                                                           |
| LoadingType               | string            | Loading type (`Live`, `Drop`, `Hook`, etc.).                                                                                                                                                                                                |
| StopType                  | string            | Type of stop (`Pickup`, `Delivery`, `Waypoint`).                                                                                                                                                                                            |
| Status                    | string            | Operational status of the stop.                                                                                                                                                                                                             |
| Coordinates.Latitude      | string            | Latitude of the stop location.                                                                                                                                                                                                              |
| Coordinates.Longitude     | string            | Longitude of the stop location.                                                                                                                                                                                                             |
| References\[]             | array             | List of references associated with the stop.                                                                                                                                                                                                |
| References\[].Id          | string            | Reference identifier.                                                                                                                                                                                                                       |
| References\[].ReferenceId | string            | External reference identifier.                                                                                                                                                                                                              |
| References\[].Name        | string            | Name of the reference field.                                                                                                                                                                                                                |
| References\[].Value       | string            | Value of the reference.                                                                                                                                                                                                                     |
| References\[].Type        | string            | Type of reference.                                                                                                                                                                                                                          |
| References\[].Access      | string            | Access level (`Public`, `Internal`).                                                                                                                                                                                                        |
| References\[].Origin      | string            | Origin of the reference.                                                                                                                                                                                                                    |
| CompanyId                 | string            | Identifier of the company associated with the stop.                                                                                                                                                                                         |
| CompanyNumber             | string            | Company registration or identification number.                                                                                                                                                                                              |
| CompanyName               | string            | Company name associated with the stop.                                                                                                                                                                                                      |

***

### Example Response

```json theme={null}
{
  "AppointmentRequested": true,
  "AppointmentConfirmed": true,
  "AppointmentDate": "2026-03-16T12:45:43.262Z",
  "ScheduleType": "string",
  "LoadingType": "string",
  "Id": "string",
  "Address": {
    "Street": "string",
    "City": "string",
    "State": "string",
    "ZipCode": "string"
  },
  "Coordinates": {
    "Latitude": "string",
    "Longitude": "string"
  },
  "Status": "string",
  "StopType": "string",
  "ArrivedAt": "2026-03-16T12:45:43.262Z",
  "DepartedAt": "2026-03-16T12:45:43.262Z",
  "References": [
    {
      "Id": "string",
      "ReferenceId": "string",
      "Name": "string",
      "Value": "string",
      "Type": "string",
      "Access": "string",
      "Origin": "string"
    }
  ],
  "CompanyId": "string",
  "CompanyNumber": "string",
  "CompanyName": "string",
  "Eta": {
    "Planned": "2026-03-16T10:40:00.000Z",
    "Live": "2026-03-16T10:52:00.000Z",
    "Manual": null
  }
}
```

***

### Status Codes

| Status Code     | Description                            |
| --------------- | -------------------------------------- |
| 200 OK          | Stop appointment successfully updated. |
| 400 Bad Request | Invalid request body.                  |
| 404 Not Found   | Trip or stop could not be found.       |

***

### Rate Limits

All endpoints are subject to API rate limits to ensure service stability and protect against traffic spikes.

Refer to the **Rate Limits** documentation for more information.


# Upload trip document
Source: https://docs.alvys.com/en/api/reference/trips/upload-trip-document

POST /api/p/v{version}/trips/{tripId}/document
Upload multipart/form-data. One file per request. Max file size 25 MB.
Allowed document types: Proof of Delivery, Bill of Lading, Carrier Rate Confirmation, Load Manifest, Trip Report, Temp. Log, Proof of Pickup, Scale Ticket, Notice of Assignment, NOA, Shipping Labels.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 25 MB.
Allowed document types: Proof of Delivery, Bill of Lading, Carrier Rate Confirmation, Load Manifest, Trip Report, Temp. Log, Proof of Pickup, Scale Ticket, Notice of Assignment, NOA, Shipping Labels.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific **trip** (or split trip). Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`, `image/gif`
* **Allowed Document Types:** Proof of Delivery (POD), Bill of Lading (BOL), Carrier Rate Confirmation, Load Manifest, Trip Report, Temp. Log, Proof of Pickup, Scale Ticket, Notice of Assignment (NOA), Shipping Labels

  * *Not allowed:* Carrier Invoice, Trip Manifest

***

### Parameters

| Parameter | In   | Type   | Required | Description                   |
| --------- | ---- | ------ | -------- | ----------------------------- |
| `tripId`  | path | string | Yes      | Unique identifier of the trip |
| `version` | path | string | Yes      | API version (e.g., `1.0`)     |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG). Max size 25 MB.                         |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/trips/{tripId}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@BOL.jpg" \
  -F "DocumentType=Bill of Lading"
```

***

### Response Body

| Parameter        | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (e.g., `1757343192`) |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                 |
| `AttachmentSize` | integer | Size of the file in bytes                                                 |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded (ISO 8601)                       |
| `ParentId`       | string  | Identifier of the parent entity (the `{tripId}`)                          |
| `ParentType`     | string  | Entity type the document is attached to (`Trip`)                          |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "e7c9f1a2-005e-0000-a4ee-45ca5e8600a",
  "AttachmentPath": "BillOfLading-1757343192.jpg",
  "AttachmentType": "Bill of Lading",
  "AttachmentSize": 2097152,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "trp-12345",
  "ParentType": "Trip"
}
```

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **tripId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# Get truck
Source: https://docs.alvys.com/en/api/reference/trucks/get-truck

GET /api/p/v{version}/trucks/{id}
Retrieve a single truck record by ID, including truck number, make and model, VIN, license plate, current driver, and last reported GPS position.

The endpoint for retrieving trucks by ID requires specifying the API version in the URL path. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |
| id        | String | Yes      | The unique identifier of the truck.     |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trucks/{truckId}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number, `{truckId}` with the actual truck ID, and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trucks/TL123456789123400402' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

The following table lists the parameters included in the response for truck-related requests.

| Parameter                          | Type               | Description                                                      |
| ---------------------------------- | ------------------ | ---------------------------------------------------------------- |
| Id                                 | String             | The unique identifier of the truck.                              |
| TruckNum                           | String             | The truck number.                                                |
| VinNumber                          | String             | The Vehicle Identification Number (VIN) of the truck.            |
| Year                               | Integer            | The manufacturing year of the truck.                             |
| Make                               | String             | The manufacturer of the truck.                                   |
| Model                              | String             | The model of the truck.                                          |
| LicenseNum                         | String             | The license plate number of the truck.                           |
| LicenseState                       | String             | The state that issued the truck's license plate.                 |
| LicenseCountry                     | String             | The country where the truck is licensed (USA, Canada, Mexico).   |
| PlateExpirationDate                | String (Date-Time) | The expiration date of the truck's license plate.                |
| LicenseExpirationDate              | String (Date-Time) | The expiration date of the truck's license.                      |
| Status                             | String             | The current status of the truck (e.g., Active).                  |
| SubsidiaryId                       | String             | The subsidiary ID associated with the truck.                     |
| NumberOfAxles                      | Integer            | The number of axles on the truck.                                |
| Fleet                              | Object             | The fleet details associated with the truck.                     |
| Fleet.Id                           | String             | The unique identifier of the fleet.                              |
| Fleet.Name                         | String             | The name of the fleet.                                           |
| Fleet.InvoiceNumberPrefix          | String             | The invoice number prefix for the fleet.                         |
| GrossWeight                        | Object             | The gross weight details of the truck.                           |
| GrossWeight.Value                  | Integer            | The value of the gross weight.                                   |
| GrossWeight.UnitOfMeasure          | String             | The unit of measure for the gross weight (e.g., Kilograms).      |
| EmptyWeight                        | Object             | The empty weight details of the truck.                           |
| EmptyWeight.Value                  | Integer            | The value of the empty weight.                                   |
| EmptyWeight.UnitOfMeasure          | String             | The unit of measure for the empty weight (e.g., Kilograms).      |
| Color                              | String             | The color of the truck.                                          |
| FuelType                           | String             | The type of fuel used by the truck.                              |
| FuelCards                          | Array of Objects   | The list of fuel cards associated with the truck.                |
| FuelCards.id                       | String             | The unique identifier of the fuel card.                          |
| FuelCards.CardNumber               | String             | The card number of the fuel card.                                |
| FuelCards.Provider                 | String             | The provider of the fuel card.                                   |
| FuelCards.DeductFuel               | Boolean            | Indicates if fuel costs are deducted.                            |
| FuelCards.ApplyFuelDiscount        | Boolean            | Indicates if a fuel discount is applied.                         |
| FuelCards.DeductFromId             | String             | The ID from which fuel costs are deducted.                       |
| FuelCards.DeductFromName           | String             | The name from which fuel costs are deducted.                     |
| FuelCards.DeductFromSubsidiary     | String             | The subsidiary from which fuel costs are deducted.               |
| FuelCards.DeductFromContractorType | String             | The contractor type from which fuel costs are deducted.          |
| InsuranceCompany                   | String             | The insurance company of the truck.                              |
| InsurancePolicyNumber              | String             | The insurance policy number.                                     |
| InsuranceExpirationDate            | String (Date-Time) | The expiration date of the insurance policy.                     |
| InspectionExpirationDate           | String (Date-Time) | The expiration date of the truck's inspection.                   |
| Notes                              | Array of Objects   | An optional list of notes related to the truck.                  |
| Notes.id                           | String             | The unique identifier of the note.                               |
| Notes.Description                  | String             | The description of the note.                                     |
| Notes.NoteType                     | String             | The type of note.                                                |
| Notes.Time                         | String (Date-Time) | The time the note was created.                                   |
| Notes.User                         | String             | The user who created the note.                                   |
| References                         | Array of Objects   | An optional list of custom references associated with the truck. |
| CreatedAt                          | String (Date-Time) | The date and time when the truck record was created.             |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](#rate-limits) section.

This page is interactive, allowing you to try a request by providing the truck ID in the URL path. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# List truck documents
Source: https://docs.alvys.com/en/api/reference/trucks/list-truck-documents

GET /api/p/v{version}/trucks/{truckId}/documents
List all documents attached to a truck by truck ID, including registration, IFTA credentials, inspection reports, and lease or title paperwork.

Retrieve all uploaded documents associated with a specific **Truck** by its unique `truckId`.

### Request Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| version   | String | Yes      | API version to use.             |
| truckId   | String | Yes      | Unique identifier of the truck. |

### Example cURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trucks/{truckId}/documents' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version, `{truckId}` with the actual truck ID, and `YOUR_ACCESS_TOKEN` with a valid token.

### Response Body

Array of document objects:

| Name           | Type    | Description                                                         |
| -------------- | ------- | ------------------------------------------------------------------- |
| id             | string  | Unique identifier of the document.                                  |
| AttachmentPath | string  | File name and extension assigned on upload (with timestamp suffix). |
| AttachmentType | string  | Type of document (e.g., Registration, Insurance).                   |
| AttachmentSize | integer | Size of the file in bytes.                                          |
| UploadedAt     | string  | UTC timestamp when the file was uploaded (ISO 8601).                |
| ParentId       | string  | Identifier of the parent entity (`truckId`).                        |
| ParentType     | string  | Entity type the document is attached to (`Truck`).                  |
| UploadedBy     | string  | User ID if uploaded via UI, or Client ID if uploaded via API.       |
| DownloadUrl    | string  | **Time-limited link (10 minutes) to download the document.**        |
| ExpiresAt      | string  | Expiration timestamp of the `DownloadUrl` (ISO 8601).               |

***

### Example Response (200 OK)

```json theme={null}
[
  {
    "id": "7b000001-c2f1-4a6a-92cf-24e6e00d00cd",
    "AttachmentPath": "Inspection-1759237626.pdf",
    "AttachmentType": "Inspection Certificate",
    "AttachmentSize": 128000,
    "UploadedAt": "2025-09-30T16:07:07+00:00",
    "ParentId": "TR0008002833900000000",
    "ParentType": "Truck",
    "UploadedBy": "7190000eecc3408e90d7000f4ece0e00",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/InspectionCertificate-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T16:19:15.9506343+00:00"
  }
]
```

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **truckId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List trucks
Source: https://docs.alvys.com/en/api/reference/trucks/list-trucks

GET /api/p/v{version}/trucks
List trucks in your Alvys fleet with pagination, returning truck number, make and model, VIN, ownership, current driver, and last reported location.

The endpoint for list all trucks requires specifying the API version in the URL path. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/trucks' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trucks' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

The following table lists the parameters included in the response for truck-related requests.

| Parameter                          | Type               | Description                                                      |
| ---------------------------------- | ------------------ | ---------------------------------------------------------------- |
| Id                                 | String             | The unique identifier of the truck.                              |
| TruckNum                           | String             | The truck number.                                                |
| VinNumber                          | String             | The Vehicle Identification Number (VIN) of the truck.            |
| Year                               | Integer            | The manufacturing year of the truck.                             |
| Make                               | String             | The manufacturer of the truck.                                   |
| Model                              | String             | The model of the truck.                                          |
| LicenseNum                         | String             | The license plate number of the truck.                           |
| LicenseState                       | String             | The state that issued the truck's license plate.                 |
| LicenseCountry                     | String             | The country where the truck is licensed (USA, Canada, Mexico).   |
| PlateExpirationDate                | String (Date-Time) | The expiration date of the truck's license plate.                |
| LicenseExpirationDate              | String (Date-Time) | The expiration date of the truck's license.                      |
| Status                             | String             | The current status of the truck (e.g., Active).                  |
| SubsidiaryId                       | String             | The subsidiary ID associated with the truck.                     |
| NumberOfAxles                      | Integer            | The number of axles on the truck.                                |
| Fleet                              | Object             | The fleet details associated with the truck.                     |
| Fleet.Id                           | String             | The unique identifier of the fleet.                              |
| Fleet.Name                         | String             | The name of the fleet.                                           |
| Fleet.InvoiceNumberPrefix          | String             | The invoice number prefix for the fleet.                         |
| GrossWeight                        | Object             | The gross weight details of the truck.                           |
| GrossWeight.Value                  | Integer            | The value of the gross weight.                                   |
| GrossWeight.UnitOfMeasure          | String             | The unit of measure for the gross weight (e.g., Kilograms).      |
| EmptyWeight                        | Object             | The empty weight details of the truck.                           |
| EmptyWeight.Value                  | Integer            | The value of the empty weight.                                   |
| EmptyWeight.UnitOfMeasure          | String             | The unit of measure for the empty weight (e.g., Kilograms).      |
| Color                              | String             | The color of the truck.                                          |
| FuelType                           | String             | The type of fuel used by the truck.                              |
| FuelCards                          | Array of Objects   | The list of fuel cards associated with the truck.                |
| FuelCards.id                       | String             | The unique identifier of the fuel card.                          |
| FuelCards.CardNumber               | String             | The card number of the fuel card.                                |
| FuelCards.Provider                 | String             | The provider of the fuel card.                                   |
| FuelCards.DeductFuel               | Boolean            | Indicates if fuel costs are deducted.                            |
| FuelCards.ApplyFuelDiscount        | Boolean            | Indicates if a fuel discount is applied.                         |
| FuelCards.DeductFromId             | String             | The ID from which fuel costs are deducted.                       |
| FuelCards.DeductFromName           | String             | The name from which fuel costs are deducted.                     |
| FuelCards.DeductFromSubsidiary     | String             | The subsidiary from which fuel costs are deducted.               |
| FuelCards.DeductFromContractorType | String             | The contractor type from which fuel costs are deducted.          |
| InsuranceCompany                   | String             | The insurance company of the truck.                              |
| InsurancePolicyNumber              | String             | The insurance policy number.                                     |
| InsuranceExpirationDate            | String (Date-Time) | The expiration date of the insurance policy.                     |
| InspectionExpirationDate           | String (Date-Time) | The expiration date of the truck's inspection.                   |
| Notes                              | Array of Objects   | An optional list of notes related to the truck.                  |
| Notes.id                           | String             | The unique identifier of the note.                               |
| Notes.Description                  | String             | The description of the note.                                     |
| Notes.NoteType                     | String             | The type of note.                                                |
| Notes.Time                         | String (Date-Time) | The time the note was created.                                   |
| Notes.User                         | String             | The user who created the note.                                   |
| References                         | Array of Objects   | An optional list of custom references associated with the truck. |
| CreatedAt                          | String (Date-Time) | The date and time when the truck record was created.             |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](#rate-limits) section.

This page is interactive, allowing you to try a request without any parameters. The Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search truck events
Source: https://docs.alvys.com/en/api/reference/trucks/search-truck-events

POST /api/p/v{version}/trucks/events/search
Search truck telematics events with paginated POST filters — truck, event type, date range, and load or trip context for location, HOS, and status pings.

This endpoint provides detailed information about truck events that match the search criteria, enabling efficient tracking and management of truck-related activities.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| version   | String | Yes      | The API version to use. |

#### Request Body Parameters

The following parameters are required in the request body:

| Parameter | Type              | Required | Description                                     |
| --------- | ----------------- | -------- | ----------------------------------------------- |
| StartDate | String (DateTime) | Yes      | The start date-time for the event search range. |
| EndDate   | String (DateTime) | No       | The end date-time for the event search range.   |
| TruckIds  | Array of Strings  | Yes      | The list of truck IDs to filter truck events.   |

#### Example CURL request

Use the current API version number and ensure you replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trucks/events/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
--header 'Content-Type: application/json' \
--data '{
  "StartDate": "2025-02-06T06:50:20.471Z",
  "EndDate": "2025-02-06T06:50:20.471Z",
  "TruckIds": [
    "string"
  ]
}'
```

### Response Parameters

The following table lists the parameters included in the response for truck events requests.

| Parameter       | Type              | Required | Description                                     |
| --------------- | ----------------- | -------- | ----------------------------------------------- |
| Id              | String            | Yes      | The unique identifier of the truck event.       |
| TruckId         | String            | Yes      | The unique identifier of the truck.             |
| Title           | String            | Yes      | The title or reference code of the event.       |
| EventType       | String            | Yes      | The type of event (e.g., Repair, Other).        |
| Description     | String            | No       | A detailed description of the event.            |
| StartDate       | String (DateTime) | Yes      | The start date-time of the event.               |
| EndDate         | String (DateTime) | Yes      | The end date-time of the event.                 |
| Address         | Object            | No       | The location details associated with the event. |
| Address.Street  | String            | No       | The street address where the event occurred.    |
| Address.City    | String            | No       | The city where the event took place.            |
| Address.State   | String            | No       | The state where the event took place.           |
| Address.ZipCode | String            | No       | The ZIP code of the event location.             |
| CreatedBy       | String            | Yes      | The user who created the event record.          |
| CreatedAt       | String (DateTime) | Yes      | The timestamp for when the event was created.   |

#### Versioning

The version parameter in the URL path specifies which version of the API you are using. Including the version number ensures that your application interacts with the correct version of the API, providing stability and compatibility as the API evolves. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by specifying the API version in the URL path and providing the necessary request body. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Search trucks
Source: https://docs.alvys.com/en/api/reference/trucks/search-trucks

POST /api/p/v{version}/trucks/search
Search trucks with paginated POST filters — truck number, make and model, ownership, home terminal, current driver, and active or inactive status.

This endpoint provides detailed information about each truck that matches the search criteria, facilitating efficient management and retrieval of truck records.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

#### Request Body

The request body must include the following parameters to filter the search results.

`<Table>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number of the results to retrieve.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Integer
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.\
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      Status
    </td>

    <td>
      Array of Strings
    </td>

    <td>
      No
    </td>

    <td>
      A list of truck statuses to filter by.
    </td>
  </tr>

  <tr>
    <td>
      TruckNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The truck number to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      FleetName
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The fleet name to filter by. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      VinNumber
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The Vehicle Identification Number (VIN) to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      IsActive
    </td>

    <td>
      Boolean
    </td>

    <td>
      Conditionally
    </td>

    <td>
      Filter by active status (true for active, false for inactive). This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>

  <tr>
    <td>
      RegisteredName
    </td>

    <td>
      String
    </td>

    <td>
      Conditionally
    </td>

    <td>
      The registered name of the truck to search for. This field is required if the other conditionally required fields are left empty.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/trucks/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "Status": [
      "Active"
  ],
  "TruckNumber": "",
  "FleetName": "",
  "VinNumber": "",
  "IsActive": true,
  "RegisteredName": ""
}'
```

### Response Parameters

The following table lists the parameters included in the response for truck-related requests.

| Parameter                                | Type               | Description                                                      |
| ---------------------------------------- | ------------------ | ---------------------------------------------------------------- |
| Page                                     | Integer            | The current page number of the results.                          |
| PageSize                                 | Integer            | The number of results per page.                                  |
| Total                                    | Integer            | The total number of results available.                           |
| Items                                    | Array of Objects   | The list of truck objects matching the search criteria.          |
| Items.Id                                 | String             | The unique identifier of the truck.                              |
| Items.TruckNum                           | String             | The truck number.                                                |
| Items.VinNumber                          | String             | The Vehicle Identification Number (VIN) of the truck.            |
| Items.Year                               | Integer            | The manufacturing year of the truck.                             |
| Items.Make                               | String             | The manufacturer of the truck.                                   |
| Items.Model                              | String             | The model of the truck.                                          |
| Items.LicenseNum                         | String             | The license plate number of the truck.                           |
| Items.LicenseState                       | String             | The state that issued the truck's license plate.                 |
| Items.LicenseCountry                     | String             | The country where the truck is licensed (USA, Canada, Mexico).   |
| Items.PlateExpirationDate                | String (Date-Time) | The expiration date of the truck's license plate.                |
| Items.LicenseExpirationDate              | String (Date-Time) | The expiration date of the truck's license.                      |
| Items.Status                             | String             | The current status of the truck (e.g., Active).                  |
| Items.SubsidiaryId                       | String             | The subsidiary ID associated with the truck.                     |
| Items.NumberOfAxles                      | Integer            | The number of axles on the truck.                                |
| Items.Fleet                              | Object             | The fleet details associated with the truck.                     |
| Items.Fleet.Id                           | String             | The unique identifier of the fleet.                              |
| Items.Fleet.Name                         | String             | The name of the fleet.                                           |
| Items.Fleet.InvoiceNumberPrefix          | String             | The invoice number prefix for the fleet.                         |
| Items.GrossWeight                        | Object             | The gross weight details of the truck.                           |
| Items.GrossWeight.Value                  | Integer            | The value of the gross weight.                                   |
| Items.GrossWeight.UnitOfMeasure          | String             | The unit of measure for the gross weight (e.g., Kilograms).      |
| Items.EmptyWeight                        | Object             | The empty weight details of the truck.                           |
| Items.EmptyWeight.Value                  | Integer            | The value of the empty weight.                                   |
| Items.EmptyWeight.UnitOfMeasure          | String             | The unit of measure for the empty weight (e.g., Kilograms).      |
| Items.Color                              | String             | The color of the truck.                                          |
| Items.FuelType                           | String             | The type of fuel used by the truck.                              |
| Items.FuelCards                          | Array of Objects   | The list of fuel cards associated with the truck.                |
| Items.FuelCards.id                       | String             | The unique identifier of the fuel card.                          |
| Items.FuelCards.CardNumber               | String             | The card number of the fuel card.                                |
| Items.FuelCards.Provider                 | String             | The provider of the fuel card.                                   |
| Items.FuelCards.DeductFuel               | Boolean            | Indicates if fuel costs are deducted.                            |
| Items.FuelCards.ApplyFuelDiscount        | Boolean            | Indicates if a fuel discount is applied.                         |
| Items.FuelCards.DeductFromId             | String             | The ID from which fuel costs are deducted.                       |
| Items.FuelCards.DeductFromName           | String             | The name from which fuel costs are deducted.                     |
| Items.FuelCards.DeductFromSubsidiary     | String             | The subsidiary from which fuel costs are deducted.               |
| Items.FuelCards.DeductFromContractorType | String             | The contractor type from which fuel costs are deducted.          |
| Items.InsuranceCompany                   | String             | The insurance company of the truck.                              |
| Items.InsurancePolicyNumber              | String             | The insurance policy number.                                     |
| Items.InsuranceExpirationDate            | String (Date-Time) | The expiration date of the insurance policy.                     |
| Items.InspectionExpirationDate           | String (Date-Time) | The expiration date of the truck's inspection.                   |
| Items.Notes                              | Array of Objects   | An optional list of notes related to the truck.                  |
| Items.Notes.id                           | String             | The unique identifier of the note.                               |
| Items.Notes.Description                  | String             | The description of the note.                                     |
| Items.Notes.NoteType                     | String             | The type of note.                                                |
| Items.Notes.Time                         | String (Date-Time) | The time the note was created.                                   |
| Items.Notes.User                         | String             | The user who created the note.                                   |
| Items.References                         | Array of Objects   | An optional list of custom references associated with the truck. |
| Items.CreatedAt                          | String (Date-Time) | The date and time when the truck record was created.             |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request without any parameters. The Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Upload truck document
Source: https://docs.alvys.com/en/api/reference/trucks/upload-truck-document

POST /api/p/v{version}/trucks/{truckId}/document
Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload multipart/form-data. One file per request. Max file size 10 MB.
Allowed document types: Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents.
Allowed MIME types: application/pdf, image/jpeg, image/png.

Upload a document to a specific **truck**. Supports `multipart/form-data`. Each request must contain exactly one file.

* **Max file size:** 25 MB
* **Allowed MIME types:** `application/pdf`, `image/jpeg`, `image/png`
* **Allowed Document Types:** Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents

***

### Parameters

| Parameter | In   | Type   | Required | Description                |
| --------- | ---- | ------ | -------- | -------------------------- |
| `truckId` | path | string | Yes      | Unique identifier of truck |
| `version` | path | string | Yes      | API version (e.g., `1.0`)  |

***

### Request Body

`multipart/form-data`

| Parameter      | Type   | Required | Description                                                                  |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `File`         | binary | Yes      | The file to upload (PDF, JPEG, PNG). Max size 25 MB.                         |
| `FileName`     | string | No       | Optional custom filename (if omitted, filename is taken from multipart part) |
| `DocumentType` | string | Yes      | The type of document. Must match one of the allowed document types.          |

***

#### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/trucks/{truckId}/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@MVR.pdf" \
  -F "DocumentType=Motor Vehicle Record"
```

***

### Response Body

| Name             | Type    | Description                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------- |
| `id`             | string  | Unique identifier of the uploaded document                                |
| `AttachmentPath` | string  | File name/path assigned on upload + timestamp suffix (e.g., `1757343192`) |
| `AttachmentType` | string  | Type of document (matches `DocumentType`)                                 |
| `AttachmentSize` | integer | Size of the file in bytes                                                 |
| `UploadedAt`     | string  | UTC timestamp when the file was uploaded (ISO 8601)                       |
| `ParentId`       | string  | Identifier of the parent entity (the `{truckId}`)                         |
| `ParentType`     | string  | Entity type the document is attached to (`Truck`)                         |

#### Example Response

**200 OK**

```json theme={null}
{
  "id": "f91c0b66-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "MVR-1757343192.pdf",
  "AttachmentType": "Motor Vehicle Record",
  "AttachmentSize": 1048576,
  "UploadedAt": "2025-09-09T08:26:03.194Z",
  "ParentId": "TR12345",
  "ParentType": "Trucks"
}
```

On the right side, you can see examples of different error codes by clicking **Example** and selecting the response code.

***

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes.
For detailed information, see the [Rate Limits](/en/api/guides/rate-limits) section.

***

### Try It Out

This page is interactive, allowing you to try a request by specifying the **API version** and **truckId** in the URL path.

As you fill out the parameters, the cURL command on the right side of the page will be automatically updated. Alternatively, you can directly edit the cURL command.

⚠️ Don’t forget: make sure to **authorize yourself** before trying a request.


# List users
Source: https://docs.alvys.com/en/api/reference/users/list-users

GET /api/p/v{version}/users/list
List user accounts in your Alvys tenant, including full name, email, role assignments, subsidiary access, and enabled or disabled account status.

The List Users API endpoint is used for fetching comprehensive details of all users, helping administrators and managers keep track of user accounts and their associated roles and permissions within the Alvys system. The inclusion of versioning in the URL path ensures compatibility with different API versions as the platform evolves. For more information on versioning, refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

#### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v{version}/users/list' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `{version}` with the API version number and `YOUR_ACCESS_TOKEN` with your actual Bearer token.

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/users/list' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...'
```

### Response Parameters

The response contains a list of users, each represented by the following parameters:

| Parameter   | Type               | Description                                                                                                               |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Id          | String             | The unique identifier of the user.                                                                                        |
| UserName    | String             | The username of the user.                                                                                                 |
| Name        | String             | The full name of the user.                                                                                                |
| Email       | String             | The email address of the user.                                                                                            |
| UserType    | String             | The type of user (e.g., Internal, External).                                                                              |
| Role        | String             | The role assigned to the user (e.g., Admin, Dispatcher, Driver, Biller, SalesAgent, DataEntry, Safety, OperationManager). |
| Phone       | String             | The phone number of the user.                                                                                             |
| CompanyCode | String             | The code of the company the user is associated with.                                                                      |
| Status      | String             | The current status of the user (e.g., Active, Disabled, Deleted).                                                         |
| Permissions | Array of Strings   | A list of permissions assigned to the user.                                                                               |
| CreatedAt   | String (Date-Time) | The date and time when the user was created.                                                                              |
| ModifiedAt  | String (Date-Time) | The date and time when the user's details were last modified.                                                             |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](#rate-limits) section.

This page is interactive, allowing you to try a request without any parameters. The Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Search users
Source: https://docs.alvys.com/en/api/reference/users/search-users

POST /api/p/v{version}/users/search
Search Alvys user accounts with paginated POST filters — name, email, role, subsidiary access, and enabled or disabled account status.

The Search Users API endpoint allows users to search for specific user accounts within the Alvys system based on a keyword. This endpoint helps administrators efficiently find and manage user data by providing detailed information about users matching the search criteria.

### Request Parameters

The following parameter is required in the URL path:

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| version   | String | Yes      | The version of the API being requested. |

#### Request Body

The request body must include the following parameters:

`<Table>`

<thead>
  <tr>
    <th>
      Parameter
    </th>

    <th>
      Type
    </th>

    <th>
      Required
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Page
    </td>

    <td>
      Number
    </td>

    <td>
      Yes
    </td>

    <td>
      The page number for pagination.
    </td>
  </tr>

  <tr>
    <td>
      PageSize
    </td>

    <td>
      Number
    </td>

    <td>
      Yes
    </td>

    <td>
      The number of results per page.\
      PageSize must be greater than 0.
    </td>
  </tr>

  <tr>
    <td>
      Keyword
    </td>

    <td>
      String
    </td>

    <td>
      No
    </td>

    <td>
      The keyword to search for in user data.
    </td>
  </tr>
</tbody>

`</Table>`

#### Example CURL request

Use the Current API version number and make sure to replace the Authorization header value with your actual Bearer token for the request:

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/users/search' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 0,
  "PageSize": 100,
  "Keyword": ""
}'
```

### Response Parameters

The response contains a list of users matching the search criteria, each represented by the following parameters:

| Parameter         | Type               | Description                                                                                                               |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Page              | Number             | The current page number.                                                                                                  |
| PageSize          | Number             | The number of items per page.                                                                                             |
| Total             | Number             | The total number of matching items.                                                                                       |
| Items             | Array              | The list of users matching the search criteria.                                                                           |
| Items.Id          | String             | The unique identifier of the user.                                                                                        |
| Items.UserName    | String             | The username of the user.                                                                                                 |
| Items.Name        | String             | The full name of the user.                                                                                                |
| Items.Email       | String             | The email address of the user.                                                                                            |
| Items.UserType    | String             | The type of user (e.g., Internal, External).                                                                              |
| Items.Role        | String             | The role assigned to the user (e.g., Admin, Dispatcher, Driver, Biller, SalesAgent, DataEntry, Safety, OperationManager). |
| Items.Phone       | String             | The phone number of the user.                                                                                             |
| Items.CompanyCode | String             | The code of the company the user is associated with.                                                                      |
| Items.Status      | String             | The current status of the user (e.g., Active, Disabled, Deleted).                                                         |
| Items.Permissions | Array of Strings   | A list of permissions assigned to the user.                                                                               |
| Items.CreatedAt   | String (Date-Time) | The date and time when the user was created.                                                                              |
| Items.ModifiedAt  | String (Date-Time) | The date and time when the user's details were last modified.                                                             |

#### Example Response

On the right side, you can see examples of different error codes by clicking "Example" and selecting the response code.

<img alt="" />

#### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the Curl command on the right side of the page will be automatically updated. Alternatively, you can directly edit the Curl command. Make sure to authorize yourself before trying a request.


# Get inbound visibility history
Source: https://docs.alvys.com/en/api/reference/visibility/get-inbound-visibility-history

GET /api/p/v{version}/visibility/inbound/{loadNumber}/history
Retrieve the inbound visibility update history for a load by load number, listing every position ping, ETA, and status event received from carriers.

The location history endpoint provides access to inbound updates for a specific load by using the loadNumber and version in your request. The history includes location updates from various sources, such as ELD integrations (if enabled for assets), manual Checkcalls, EDI & Visibility integrations, or updates from the driver app. These updates help track the load's location, detailing event types, timestamps, and asset information. For guidance on versioning and how to include it in your requests, visit the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL:

| Parameter  | Type   | Required | Description                                                   |
| ---------- | ------ | -------- | ------------------------------------------------------------- |
| version    | String | Yes      | The API version you are using (e.g., "v1").                   |
| loadNumber | String | Yes      | The unique number assigned to the load for tracking purposes. |

***

#### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/visibility/inbound/12345/history' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token and `12345` with the load number you wish to track.

### Response Fields

The following fields are included in the response:

| Field                 | Type               | Description                                                                                                                        |
| --------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Id                    | String             | The unique identifier of the location update.                                                                                      |
| ExternalId            | String             | The external ID related to the update.                                                                                             |
| TripNumber            | String             | The trip number linked to the load.                                                                                                |
| LoadNumber            | String             | The load number for which the update is recorded.                                                                                  |
| EventType             | String             | The type of event, typically "Location".                                                                                           |
| SharedAt              | String (Date-Time) | The date and time when the update was shared.                                                                                      |
| Destination           | String             | The destination of the load.                                                                                                       |
| TruckNumber           | String             | The number of the truck transporting the load.                                                                                     |
| DriverName            | String             | The name of the driver.                                                                                                            |
| TrailerNumber         | String             | The number of the trailer being used.                                                                                              |
| StopId                | String             | The ID of the stop associated with the location update.                                                                            |
| LocationId            | String             | The ID of the location where the update occurred.                                                                                  |
| SharedBy              | String             | The entity (user or system) that shared the update.                                                                                |
| Reason                | String             | The reason for the update, if provided. There is defined list on system, depending on integration. E.g.: "NA"- Normal Appointment. |
| Address               | Object             | The address details of the location update.                                                                                        |
| Address.Street        | String             | The street of the location.                                                                                                        |
| Address.City          | String             | The city of the location.                                                                                                          |
| Address.State         | String             | The state of the location.                                                                                                         |
| Address.ZipCode       | String             | The postal code of the location.                                                                                                   |
| Coordinates           | Object             | The geographic coordinates of the location.                                                                                        |
| Coordinates.Latitude  | String             | The latitude of the location.                                                                                                      |
| Coordinates.Longitude | String             | The longitude of the location.                                                                                                     |
| Status                | String             | The status of the update (e.g., "Completed", "Failed").                                                                            |
| Error                 | String             | Any error message, if the update could not be processed.                                                                           |

#### Example Response

```json theme={null}
[
  {
    "Id": "9b834b4c77124b8f8f0d97b56b7dabc4",
    "ExternalId": "EXT-001",
    "TripNumber": "TRIP12345",
    "LoadNumber": "LOAD12345",
    "EventType": "Location",
    "SharedAt": "2024-11-11T15:02:49.233Z",
    "Destination": "Los Angeles, CA",
    "TruckNumber": "TRK98765",
    "DriverName": "John Doe",
    "TrailerNumber": "TRL12345",
    "StopId": "STOP001",
    "LocationId": "LOC001",
    "SharedBy": "TMS System",
    "Reason": "NA",//Normal Appointment
    "Address": {
      "Street": "123 Main St",
      "City": "Los Angeles",
      "State": "CA",
      "ZipCode": "90001"
    },
    "Coordinates": {
      "Latitude": "34.052235",
      "Longitude": "-118.243683"
    },
    "Status": "Completed",
    "Error": ""
  }
]
```

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Get outbound visibility history
Source: https://docs.alvys.com/en/api/reference/visibility/get-outbound-visibility-history

GET /api/p/v{version}/visibility/outbound/{loadNumber}/history
Retrieve the outbound visibility update history for a load by load number, listing every position ping and status event Alvys pushed to customer platforms.

This endpoint provides access to outbound updates for a specific load by using the `loadNumber` and `version` in your request. To use outbound visibility, customers must first set up an EDI integration in EDI Tenders. Auto-updates can be configured either in EDI Tenders or on the Company Details page within Alvys platform. Based on the configured auto-updates settings, the updates are shared automatically, including event type details, location, date shared, and the error details if any issues encountered. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/en/api/guides/versioning) page.

### Request Parameters

The following parameters are required in the URL:

| Parameter  | Type   | Required | Description                                          |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| version    | String | Yes      | The API version you are using (e.g., "v1").          |
| loadNumber | String | Yes      | The unique number assigned to the load for tracking. |

#### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/visibility/outbound/12345/history' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token and `12345` with the load number you wish to track.

### Response Fields

The following fields are included in the response:

| Field                 | Type               | Description                                                                                                                    |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Id                    | String             | The unique identifier of the outbound update.                                                                                  |
| ExternalId            | String             | The external ID related to the update.                                                                                         |
| TripNumber            | String             | The trip number linked to the load.                                                                                            |
| LoadNumber            | String             | The load number for which the update is recorded.                                                                              |
| EventType             | String             | The type of event, typically "Location".                                                                                       |
| SharedAt              | String (Date-Time) | The date and time when the update was shared.                                                                                  |
| Destination           | String             | The destination of the load.                                                                                                   |
| TruckNumber           | String             | The number of the truck transporting the load.                                                                                 |
| DriverName            | String             | The name of the driver.                                                                                                        |
| TrailerNumber         | String             | The number of the trailer being used.                                                                                          |
| StopId                | String             | The ID of the stop associated with the update.                                                                                 |
| LocationId            | String             | The ID of the location related to the update.                                                                                  |
| SharedBy              | String             | The entity (user or system) that shared the update.                                                                            |
| Reason                | String             | The reason for the update, if provided.  There is defined list on system, depending on integration. E.g.: "AY" - Missed Pickup |
| Address               | Object             | The address details of the location update.                                                                                    |
| Address.Street        | String             | The street of the location.                                                                                                    |
| Address.City          | String             | The city of the location.                                                                                                      |
| Address.State         | String             | The state of the location.                                                                                                     |
| Address.ZipCode       | String             | The postal code of the location.                                                                                               |
| Coordinates           | Object             | The geographic coordinates of the location.                                                                                    |
| Coordinates.Latitude  | String             | The latitude of the location.                                                                                                  |
| Coordinates.Longitude | String             | The longitude of the location.                                                                                                 |
| Status                | String             | The status of the update (e.g., "Completed", "Failed").                                                                        |
| Error                 | String             | Any error message, if the update could not be processed.                                                                       |

#### Example Response

```json theme={null}
[
  {
    "Id": "9b834b4c77124b8f8f0d97b56b7dabc4",
    "ExternalId": "EXT-002",
    "TripNumber": "TRIP54321",
    "LoadNumber": "LOAD54321",
    "EventType": "Location",
    "SharedAt": "2024-11-11T15:06:23.767Z",
    "Destination": "New York, NY",
    "TruckNumber": "TRK12345",
    "DriverName": "Jane Doe",
    "TrailerNumber": "TRL54321",
    "StopId": "STOP002",
    "LocationId": "LOC002",
    "SharedBy": "EDI System",
    "Reason": "AY", //MP - Missed Pickup
    "Address": {
      "Street": "456 Elm St",
      "City": "New York",
      "State": "NY",
      "ZipCode": "10001"
    },
    "Coordinates": {
      "Latitude": "40.712776",
      "Longitude": "-74.005974"
    },
    "Status": "Completed",
    "Error": ""
  }
]
```

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. Alternatively, you can fork our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c) directly. Make sure to authorize yourself before trying a request.


# Record asset location
Source: https://docs.alvys.com/en/api/reference/visibility/record-asset-location

POST /api/p/v{version}/assets/{assetId}/locations
Record where a driver, truck, or trailer is from a third-party source, so partner telematics data drives Alvys load and asset tracking alongside first-party ELD feeds.

Records where an asset is — position, and optionally the odometer. Use this when an external system knows an asset's location: a third-party ELD, or a vehicle reporting its own position.

To send speed, fuel, or temperature readings taken at the same moment, use [Record asset telemetry](/en/api/reference/visibility/record-asset-telemetry) instead. This endpoint is position-only by design.

<Note>
  This endpoint requires the `visibility:create` scope. See [Authentication](/en/api/guides/authentication-1).
</Note>

`assetId` is the Alvys id of a driver, truck, or trailer — the `Id` returned by the [drivers](/en/api/reference/drivers/list-drivers), [trucks](/en/api/reference/trucks/list-trucks), and [trailers](/en/api/reference/trailers/list-trailers) endpoints. It is **not** a unit number.

### Ordering and duplicate readings

Positions are ordered per asset by `RecordedAt`. A reading older than, or equal to, the one already held for this source is discarded and answered `409 Conflict`.

<Warning>
  A `409` is a normal out-of-order outcome, not a failure. **Do not retry it** — resending the same reading will keep answering `409`. Send the next reading instead.
</Warning>

This also makes retries safe: resending a reading you already delivered does not move the asset or fire a duplicate tracking update.

### Endpoint

```
POST /api/p/v{version}/assets/{assetId}/locations
```

### Request Parameters

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| version   | string | Yes      | API version to use (`1.0`).                                   |
| assetId   | string | Yes      | Alvys id of the driver, truck, or trailer. Not a unit number. |

### Request Body

| Field                 | Type              | Required | Description                                                                                                           |
| --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| Coordinates           | Object            | Yes      | Where the asset is. A missing, out-of-range, or `(0, 0)` value is rejected with `400`.                                |
| Coordinates.Latitude  | string            | Yes      | Latitude, as a string.                                                                                                |
| Coordinates.Longitude | string            | Yes      | Longitude, as a string.                                                                                               |
| RecordedAt            | string (datetime) | No       | When the reading was taken, ISO-8601. Defaults to the time Alvys receives it. Positions are ordered by this field.    |
| Address               | Object            | No       | `Street`, `City`, `State`, `ZipCode`, `Country`. Omit it and Alvys resolves an address from the coordinates.          |
| TripId                | string            | No       | The trip to attribute the reading to. Omit it and Alvys selects the asset's active trip with the nearest stop.        |
| Odometer              | number            | No       | Odometer reading in miles. A value of `0` is treated as no reading and discarded rather than stored.                  |
| OdometerReadingAt     | string (datetime) | No       | When the odometer was read, ISO-8601. Stored only alongside a surviving `Odometer` reading; on its own it is ignored. |

<Tip>
  Pass `TripId` when you know it. On an asset running more than one active trip — a team, drop-and-hook, or multi-stop asset — Alvys otherwise picks the trip with the nearest stop, and the tracking update, ETA, and customer tracking page follow that choice.
</Tip>

The request body is limited to 8 KB. Send one reading per request.

### Example Request Body

```json theme={null}
{
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "RecordedAt": "2026-08-21T14:32:00Z",
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z"
}
```

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/assets/{assetId}/locations' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "RecordedAt": "2026-08-21T14:32:00Z",
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z"
}'
```

### Response Fields

| Field                 | Type              | Description                                                                        |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| AssetId               | string            | Alvys id of the asset.                                                             |
| AssetType             | string            | `Driver`, `Truck`, or `Trailer`.                                                   |
| Source                | string            | Tracking source. Always `PublicApi` for positions submitted through this endpoint. |
| Coordinates.Latitude  | string            | Latitude of the recorded position.                                                 |
| Coordinates.Longitude | string            | Longitude of the recorded position.                                                |
| Address               | Object            | The address you supplied, or the one resolved from the coordinates.                |
| FormattedAddress      | string            | That address as a single display string.                                           |
| RecordedAt            | string (datetime) | Observation time the position is ordered by.                                       |
| ReceivedAt            | string (datetime) | When Alvys accepted the position.                                                  |
| TripId                | string            | The asset's trip at the time of the reading, if any.                               |
| TripNumber            | string            | Number of that trip, if any.                                                       |
| Odometer              | number            | Odometer reading in miles, as reported.                                            |
| OdometerReadingAt     | string (datetime) | When the odometer was read, as reported.                                           |

### Example Response

**201 Created**

```json theme={null}
{
  "AssetId": "TR2517179655771527026",
  "AssetType": "Truck",
  "Source": "PublicApi",
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "Address": {
    "Street": "201 Main St",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "75201",
    "Country": "US"
  },
  "FormattedAddress": "201 Main St, Dallas, TX 75201",
  "RecordedAt": "2026-08-21T14:32:00Z",
  "ReceivedAt": "2026-08-21T14:32:04Z",
  "TripId": "9d4b1327-2774-d32c-fb33-87a288c2722c",
  "TripNumber": "T-100234",
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z"
}
```

### Status Codes

| Status | Description                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 201    | Position recorded.                                                                                                                                                  |
| 400    | Invalid body — missing, out-of-range, or `(0, 0)` coordinates, or a malformed field.                                                                                |
| 401    | Missing or invalid access token.                                                                                                                                    |
| 403    | Token lacks the `visibility:create` scope.                                                                                                                          |
| 404    | Asset not found, or outside your credential's subsidiary scope.                                                                                                     |
| 409    | A newer position is already recorded for this asset from this source. The reading was discarded. Do not retry.                                                      |
| 422    | `RecordedAt` is more than 5 minutes ahead of the server clock. A future-dated reading would suppress every later position for this asset until real time caught up. |
| 429    | Rate limit exceeded.                                                                                                                                                |

A `409` carries the error type `https://api.alvys.com/errors/Conflict/StaleLocation` and reports the `RecordedAt` of the position currently held, so you can tell how far behind your feed is.

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. See [Rate Limits](/en/api/guides/rate-limits).


# Record asset telemetry
Source: https://docs.alvys.com/en/api/reference/visibility/record-asset-telemetry

POST /api/p/v{version}/assets/{assetId}/telemetry
Record a driver, truck, or trailer position together with the speed, heading, odometer, fuel level, and ambient temperature read at the same moment.

Records an asset's position together with the readings taken at the same moment — speed, heading, odometer, fuel level, and ambient temperature.

If you only have a position and an odometer, use [Record asset location](/en/api/reference/visibility/record-asset-location) instead. Everything else on this page behaves identically to that endpoint.

<Note>
  This endpoint requires the `visibility:create` scope. See [Authentication](/en/api/guides/authentication-1).
</Note>

`assetId` is the Alvys id of a driver, truck, or trailer — the `Id` returned by the [drivers](/en/api/reference/drivers/list-drivers), [trucks](/en/api/reference/trucks/list-trucks), and [trailers](/en/api/reference/trailers/list-trailers) endpoints. It is **not** a unit number.

### Ordering and duplicate readings

Positions are ordered per asset by `RecordedAt`. A reading older than, or equal to, the one already held for this source is discarded and answered `409 Conflict`.

<Warning>
  A `409` is a normal out-of-order outcome, not a failure. **Do not retry it** — resending the same reading will keep answering `409`. Send the next reading instead.
</Warning>

### Endpoint

```
POST /api/p/v{version}/assets/{assetId}/telemetry
```

### Request Parameters

| Parameter | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| version   | string | Yes      | API version to use (`1.0`).                                   |
| assetId   | string | Yes      | Alvys id of the driver, truck, or trailer. Not a unit number. |

### Request Body

| Field                    | Type              | Required | Description                                                                                                            |
| ------------------------ | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| Coordinates              | Object            | Yes      | Where the asset is. A missing, out-of-range, or `(0, 0)` value is rejected with `400`.                                 |
| Coordinates.Latitude     | string            | Yes      | Latitude, as a string.                                                                                                 |
| Coordinates.Longitude    | string            | Yes      | Longitude, as a string.                                                                                                |
| RecordedAt               | string (datetime) | No       | When the readings were taken, ISO-8601. Defaults to the time Alvys receives them. Positions are ordered by this field. |
| Address                  | Object            | No       | `Street`, `City`, `State`, `ZipCode`, `Country`. Omit it and Alvys resolves an address from the coordinates.           |
| TripId                   | string            | No       | The trip to attribute the reading to. Omit it and Alvys selects the asset's active trip with the nearest stop.         |
| Speed                    | number            | No       | Speed at the moment of the reading.                                                                                    |
| Heading                  | number            | No       | Heading in degrees at the moment of the reading.                                                                       |
| Odometer                 | number            | No       | Odometer reading in miles. A value of `0` is treated as no reading and discarded rather than stored.                   |
| OdometerReadingAt        | string (datetime) | No       | When the odometer was read, ISO-8601. Stored only alongside a surviving `Odometer` reading; on its own it is ignored.  |
| FuelPercent              | number            | No       | Fuel level as a percentage.                                                                                            |
| AmbientTemperature       | Object            | No       | Ambient temperature at the asset.                                                                                      |
| AmbientTemperature.Value | number            | Yes      | Temperature reading. Required when `AmbientTemperature` is present.                                                    |
| AmbientTemperature.Unit  | string            | Yes      | `Fahrenheit`, `Celsius`, or `Kelvin`. Required when `AmbientTemperature` is present.                                   |

<Tip>
  Pass `TripId` when you know it. On an asset running more than one active trip — a team, drop-and-hook, or multi-stop asset — Alvys otherwise picks the trip with the nearest stop, and the tracking update, ETA, and customer tracking page follow that choice.
</Tip>

The request body is limited to 8 KB. Send one reading per request.

### Example Request Body

```json theme={null}
{
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "RecordedAt": "2026-08-21T14:32:00Z",
  "Speed": 62.4,
  "Heading": 271.0,
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z",
  "FuelPercent": 48.5,
  "AmbientTemperature": {
    "Value": 34.0,
    "Unit": "Fahrenheit"
  }
}
```

### Example CURL request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/assets/{assetId}/telemetry' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "RecordedAt": "2026-08-21T14:32:00Z",
  "Speed": 62.4,
  "Heading": 271.0,
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z",
  "FuelPercent": 48.5,
  "AmbientTemperature": {
    "Value": 34.0,
    "Unit": "Fahrenheit"
  }
}'
```

### Response Fields

| Field                    | Type              | Description                                                                       |
| ------------------------ | ----------------- | --------------------------------------------------------------------------------- |
| AssetId                  | string            | Alvys id of the asset.                                                            |
| AssetType                | string            | `Driver`, `Truck`, or `Trailer`.                                                  |
| Source                   | string            | Tracking source. Always `PublicApi` for readings submitted through this endpoint. |
| Coordinates.Latitude     | string            | Latitude of the recorded position.                                                |
| Coordinates.Longitude    | string            | Longitude of the recorded position.                                               |
| Address                  | Object            | The address you supplied, or the one resolved from the coordinates.               |
| FormattedAddress         | string            | That address as a single display string.                                          |
| RecordedAt               | string (datetime) | Observation time the position is ordered by.                                      |
| ReceivedAt               | string (datetime) | When Alvys accepted the reading.                                                  |
| TripId                   | string            | The asset's trip at the time of the reading, if any.                              |
| TripNumber               | string            | Number of that trip, if any.                                                      |
| Speed                    | number            | Speed, as reported.                                                               |
| Heading                  | number            | Heading in degrees, as reported.                                                  |
| Odometer                 | number            | Odometer reading in miles, as reported.                                           |
| OdometerReadingAt        | string (datetime) | When the odometer was read, as reported.                                          |
| FuelPercent              | number            | Fuel level percentage, as reported.                                               |
| AmbientTemperature.Value | number            | Ambient temperature reading, as reported.                                         |
| AmbientTemperature.Unit  | string            | Unit of that reading — `Fahrenheit`, `Celsius`, or `Kelvin`.                      |

### Example Response

**201 Created**

```json theme={null}
{
  "AssetId": "TR2517179655771527026",
  "AssetType": "Truck",
  "Source": "PublicApi",
  "Coordinates": {
    "Latitude": "32.7767",
    "Longitude": "-96.7970"
  },
  "Address": {
    "Street": "201 Main St",
    "City": "Dallas",
    "State": "TX",
    "ZipCode": "75201",
    "Country": "US"
  },
  "FormattedAddress": "201 Main St, Dallas, TX 75201",
  "RecordedAt": "2026-08-21T14:32:00Z",
  "ReceivedAt": "2026-08-21T14:32:04Z",
  "TripId": "9d4b1327-2774-d32c-fb33-87a288c2722c",
  "TripNumber": "T-100234",
  "Speed": 62.4,
  "Heading": 271.0,
  "Odometer": 154302.5,
  "OdometerReadingAt": "2026-08-21T14:32:00Z",
  "FuelPercent": 48.5,
  "AmbientTemperature": {
    "Value": 34.0,
    "Unit": "Fahrenheit"
  }
}
```

### Status Codes

| Status | Description                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 201    | Reading recorded.                                                                                                                                                   |
| 400    | Invalid body — missing, out-of-range, or `(0, 0)` coordinates, or a malformed field.                                                                                |
| 401    | Missing or invalid access token.                                                                                                                                    |
| 403    | Token lacks the `visibility:create` scope.                                                                                                                          |
| 404    | Asset not found, or outside your credential's subsidiary scope.                                                                                                     |
| 409    | A newer position is already recorded for this asset from this source. The reading was discarded. Do not retry.                                                      |
| 422    | `RecordedAt` is more than 5 minutes ahead of the server clock. A future-dated reading would suppress every later position for this asset until real time caught up. |
| 429    | Rate limit exceeded.                                                                                                                                                |

A `409` carries the error type `https://api.alvys.com/errors/Conflict/StaleLocation` and reports the `RecordedAt` of the position currently held, so you can tell how far behind your feed is.

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. See [Rate Limits](/en/api/guides/rate-limits).


# Search outbound visibility errors
Source: https://docs.alvys.com/en/api/reference/visibility/search-outbound-visibility-errors

POST /api/p/v{version}/visibility/outbound/errors
Search outbound visibility delivery errors with paginated POST filters — customer platform, load number, error type, and failure date range for troubleshooting.

This endpoint allows you to retrieve a paginated list of outbound errors for a specified time range. The request includes parameters for pagination and a time range filter. Note that the time range must be 7 days or less. This feature helps users identify and manage any errors that occurred while sharing updates with external systems.

### Request Body Parameters

All the following parameters are required in the request body:

| Parameter       | Type               | Required | Description                                                          |
| --------------- | ------------------ | -------- | -------------------------------------------------------------------- |
| Page            | Number             | Yes      | The page number to retrieve.                                         |
| PageSize        | Number             | Yes      | The number of items to retrieve per page.                            |
| TimeRange       | Object             | Yes      | The time range filter for retrieving errors. Must be 7 days or less. |
| TimeRange.Start | String (Date-Time) | Yes      | The start date and time for the time range.                          |
| TimeRange.End   | String (Date-Time) | Yes      | The end date and time for the time range.                            |

#### Example CURL Request

```bash theme={null}
curl --location 'https://integrations.alvys.com/api/p/v1/visibility/outbound/errors' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Page": 0,
    "PageSize": 10,
    "TimeRange": {
        "Start": "2024-11-11T15:15:13.876Z",
        "End": "2024-11-18T15:15:13.876Z"
    }
}'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token. Ensure that the `start` and `end` dates are within a 7-day range.

#### Validation errors

`TimeRange` is required. If the request body omits it, the endpoint returns `400 Bad Request` and names the missing field in the validation message: `TimeRange is required`.

If `TimeRange` spans more than 7 days, the endpoint returns `400 Bad Request` with the validation message `Time range must be less than 7 days`.

### Response Fields

The response is a paginated list of error items, including details about each error:

| Field                       | Type               | Description                                                                                                                 |
| --------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Page                        | Number             | The current page number.                                                                                                    |
| PageSize                    | Number             | The number of items per page.                                                                                               |
| Total                       | Number             | The total number of error items.                                                                                            |
| Items                       | Array              | A list of error items.                                                                                                      |
| Items.Id                    | String             | The unique identifier of the error.                                                                                         |
| Items.ExternalId            | String             | The external ID related to the error.                                                                                       |
| Items.TripNumber            | String             | The trip number linked to the load.                                                                                         |
| Items.LoadNumber            | String             | The load number for which the error occurred.                                                                               |
| Items.EventType             | String             | The type of event, typically "Location".                                                                                    |
| Items.SharedAt              | String (Date-Time) | The date and time when the update was shared.                                                                               |
| Items.Destination           | String             | The destination of the load.                                                                                                |
| Items.TruckNumber           | String             | The number of the truck transporting the load.                                                                              |
| Items.DriverName            | String             | The name of the driver.                                                                                                     |
| Items.TrailerNumber         | String             | The number of the trailer being used.                                                                                       |
| Items.StopId                | String             | The ID of the stop related to the error.                                                                                    |
| Items.LocationId            | String             | The ID of the location associated with the error.                                                                           |
| Items.SharedBy              | String             | The entity (user or system) that shared the update.                                                                         |
| Items.Reason                | String             | The reason for the error, if provided. There is defined list on system, depending on integration. E.g.: NS - Normal Status. |
| Items.Address               | Object             | The address details of the location update.                                                                                 |
| Items.Address.Street        | String             | The street of the location.                                                                                                 |
| Items.Address.City          | String             | The city of the location.                                                                                                   |
| Items.Address.State         | String             | The state of the location.                                                                                                  |
| Items.Address.ZipCode       | String             | The postal code of the location.                                                                                            |
| Items.Coordinates           | Object             | The geographic coordinates of the location.                                                                                 |
| Items.Coordinates.Latitude  | String             | The latitude of the location.                                                                                               |
| Items.Coordinates.Longitude | String             | The longitude of the location.                                                                                              |
| Items.Status                | String             | The status of the update (e.g., "Completed", "Failed").                                                                     |
| Items.Error                 | String             | The error message related to the update.                                                                                    |

#### Example Response

```json theme={null}
{
  "Page": 0,
  "PageSize": 10,
  "Total": 1,
  "Items": [
    {
      "Id": "9b834b4c77124b8f8f0d97b56b7dabc4",
      "ExternalId": "EXT-003",
      "TripNumber": "TRIP67890",
      "LoadNumber": "LOAD67890",
      "EventType": "Location",
      "SharedAt": "2024-11-11T15:15:13.896Z",
      "Destination": "Chicago, IL",
      "TruckNumber": "TRK67890",
      "DriverName": "Alex Johnson",
      "TrailerNumber": "TRL67890",
      "StopId": "STOP003",
      "LocationId": "LOC003",
      "SharedBy": null,
      "Reason": "NS", //normal status
      "Address": {
        "Street": "789 Oak St",
        "City": "Chicago",
        "State": "IL",
        "ZipCode": "60601"
      },
      "Coordinates": {
        "Latitude": "41.878113",
        "Longitude": "-87.629799"
      },
      "Status": "Failed",
      "Error": "EDI|Failed to send message to General Mills via EDI. Please try again or reach out to support if the problem persist."
    }
  ]
}
```

### Rate Limits

All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/en/api/guides/rate-limits) section.

This page is interactive, allowing you to test the endpoint by providing the required request body. The CURL command will update automatically based on your inputs. You can also try this request by forking our [Public API Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c). Remember to authorize yourself before trying a request.


# Change Diffs (data.diff)
Source: https://docs.alvys.com/en/api/reference/webhooks/change-diffs

How load.changed and trip.changed webhook events expose changed fields via data.diff, including the optional previousAttributes payload for delta processing.

`load.changed` and `trip.changed` events carry the **full current snapshot** of the load or trip in `data`. In addition, they can include an optional `data.diff` node that tells you **what changed** — and, if you opt in, **what the value was before**.

This lets a consumer decide whether a change is relevant and apply just the delta, instead of re-importing the whole record on every event.

<Info>
  `data.diff` is only present on `load.changed` and `trip.changed`. It is **never** included on `*.status.changed` events, and it is **omitted on the first event for a record** (create), where there is no prior state to compare against.
</Info>

## Shape

```json theme={null}
{
  "type": "load.changed",
  "data": {
    "load": { "...": "full current snapshot" },
    "diff": {
      "changes": [ { "kind": "…", "target": { "type": "…", "id": "…" } } ],
      "previousAttributes": { "…": "previous values (opt-in)" }
    }
  }
}
```

`data.diff` has two independent parts:

| Node                 | Answers                      | Availability                                                                        |
| -------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `changes`            | *Which* things changed?      | Always present on `load.changed` / `trip.changed` when something meaningful changed |
| `previousAttributes` | What was the value *before*? | Opt-in per subscription (see [Enabling previous values](#enabling-previous-values)) |

***

## `data.diff.changes`

`changes` is an array of objects, each `{ kind, target? }`:

* **`kind`** — a domain-named change type from a fixed vocabulary (for example `StatusChanged`, `RateChanged`, `StopReordered`). Kind names describe business concepts — they never expose internal field names or JSON paths.
* **`target`** — present **only** when the change is scoped to an identified sub-entity. It is `{ type, id }`:
  * `type` — a closed set: `Stop` or `Field`.
  * `id` — the **stable** identity of that sub-entity as it appears in the snapshot (for a stop, its `StopId` — never a positional array index).

Entity-level changes omit `target`; sub-entity changes carry it.

```json theme={null}
"changes": [
  { "kind": "StatusChanged" },
  { "kind": "CarrierRateChanged" },
  { "kind": "StopAddressChanged",  "target": { "type": "Stop",  "id": "abc123" } },
  { "kind": "AppointmentChanged",  "target": { "type": "Stop",  "id": "abc123" } },
  { "kind": "FieldChanged",        "target": { "type": "Field", "id": "PONumber" } }
]
```

The vocabulary is **closed per entity** — only the kinds below are emitted today. Loads and trips have separate lists; a kind that exists on one entity is not necessarily valid on the other (for example `CarrierRateChanged` is trip-only).

**`load.changed`:** `StatusChanged`, `RateChanged`, `FuelSurchargeChanged`, `AccessorialsChanged`, `MileageChanged`, `InvoicedChanged`, `PaymentRecorded`, `InvoicingChanged`, `CustomerChanged`, `ContractChanged`, `ScheduleChanged`, `DueDateChanged`, `Delivered`, `DimensionsChanged`, `CommodityChanged`, `NotesChanged`, `ReferencesChanged`, `FieldChanged`.

**`trip.changed`:** `StatusChanged`, `ReleasedChanged`, `DispatchChanged`, `CarrierChanged`, `CarrierPayOnHoldChanged`, `DriverChanged`, `TruckChanged`, `TrailerChanged`, `TemperatureChanged`, `CarrierRateChanged`, `TripValueChanged`, `FuelSurchargeChanged`, `DriverRatesChanged`, `CarrierPaymentRecorded`, `DueDateChanged`, `StopAdded`, `StopRemoved`, `StopReordered`, `StopAddressChanged`, `StopTypeChanged`, `StopCommodityChanged`, `StopNotesChanged`, `StopReferencesChanged`, `StopInstructionsChanged`, `AppointmentChanged`, `ScheduleChanged`, `ArrivalRecorded`, `DepartureRecorded`, `StopStatusChanged`, `PickedUp`, `Delivered`, `MileageChanged`, `TenderChanged`, `ReferencesChanged`, `FieldChanged`.

Stop-scoped kinds (`StopAddressChanged`, `AppointmentChanged`, …) carry `target: { type: "Stop", id: "<StopId>" }`.

<Warning>
  The change-kind vocabulary is curated and may grow over time. Treat `changes` as a **filtering hint only** — it is never authoritative and never suppresses an event. Always tolerate change kinds you don't recognize (ignore them), and never assume the snapshot didn't change just because a kind is missing.
</Warning>

### `FieldChanged` and the allow-list

Some business values change without a dedicated semantic kind. These surface through a single `FieldChanged` kind whose `target` is `{ "type": "Field", "id": "<ResponsePropertyName>" }`.

`FieldChanged` fires only for an explicit allow-list of fields. In v1:

| Entity | `target.id` in `changes`  | JSON key in snapshot / `previousAttributes` |
| ------ | ------------------------- | ------------------------------------------- |
| Load   | `OrderNumber`, `PONumber` | `orderNumber`, `poNumber`                   |
| Trip   | *(none in v1)*            | —                                           |

<Info>
  `FieldChanged` `target.id` uses the **API model property name** (PascalCase, e.g. `PONumber`). The snapshot and `previousAttributes` serialize the same fields in **JSON camelCase** (e.g. `poNumber`). Do not use `target.id` as a direct key into the payload — correlate by field identity (or normalize casing in your client).
</Info>

### When `changes` is present

* An **empty or absent** `changes` array means nothing meaningful changed. Bookkeeping/noise fields (for example `updatedAt`, `version`, ETag, internal sync hashes) never produce a `changes` entry.
* `changes` is omitted on create.

***

## `data.diff.previousAttributes`

`previousAttributes` carries the **previous value of every changed field that is visible on the public response**, keyed by response field name — so keys line up 1:1 with the snapshot in the same payload. This lets a state-mirroring consumer apply deltas without a full reconcile.

It is **opt-in** per subscription — see [Enabling previous values](#enabling-previous-values).

### Rules

* **Keyed collections** (any array of `id`-bearing elements — stops, references, charge lines, …) are diffed by stable `id`, recursively:
  * `removed` — the full previous element (no longer in the snapshot).
  * `changed` — a sparse `{ id, ...previous values }` (recurses into the element's own keyed sub-collections).
  * `added` — `{ id }` only. The new values are already in the snapshot; the `id` lets you locate and insert it.
* Every other changed field carries its whole previous value. Arrays of scalars / id-less objects are treated as opaque (the whole previous array is returned).
* **Audit fields are included.** Unlike `changes`, `previousAttributes` does include fields such as `updatedAt`, so the channel always confirms a real write happened.
* `previousAttributes` is emitted **whenever the current and previous responses differ**, independently of `changes`. A response-only delta can therefore produce `"changes": []` alongside a populated `previousAttributes`.
* It is **omitted** on create and when the two images are identical.
* A field appears here only if it is part of the public response. A change detected on a field that is not exposed on the response still signals via `changes` but carries no value in `previousAttributes`.

***

## Enabling previous values

`data.diff.changes` is delivered to every subscriber on `load.changed` and `trip.changed` events. `data.diff.previousAttributes` is **opt-in** and delivered only to subscriptions that request it.

* **Dashboard:** enable **Include previous values** on the webhook (see [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration)).
* **API:** set `IncludePreviousAttributes` to `true` when creating or updating the subscription (see [Create webhook](/en/api/reference/webhooks/create-webhook-subscription)). Defaults to `false`.

***

## Delivery model — one action can produce several events

Alvys sends **one webhook per underlying write** — deliveries are never merged or de-duplicated. As a result, a single user action can produce more than one event:

* **Parent cascades.** Editing a value on a trip re-saves its parent load (and some load edits re-save related records). For example, changing Paid Loaded Miles on a trip produces a `trip.changed` carrying `MileageChanged` **and** a companion `load.changed` whose `changes` is `[]` (only `updatedAt` differs) — the load's public content genuinely didn't change.
* **Batched, concurrent writes.** Events are delivered as the store commits them, in batches. A single burst can contain writes for **different records, and from different users**, that happened at the same time — they are not necessarily related to one another.

<Warning>
  Always key off `data` (the entity and its `id`) and `changes` — **never assume every delivery in a time window belongs to the same action**. A reliable filter: ignore any delivery where `changes` is empty (and, if you opted into previous values, where `previousAttributes` contains only `updatedAt`).
</Warning>

***

## Worked examples

### A field change on a load (`FieldChanged`)

Setting the PO number on a load from the dashboard. `PONumber` is on the Load allow-list, so it surfaces as `FieldChanged`; the previous value was empty (`null`). This is a single `load.changed` — editing a load field re-saves only the load:

```json theme={null}
{
  "type": "load.changed",
  "data": {
    "load": {
      "loadNumber": "1008222",
      "orderNumber": "783068797",
      "poNumber": "666783068797",
      "...": "full current snapshot"
    },
    "diff": {
      "changes": [
        { "kind": "FieldChanged", "target": { "type": "Field", "id": "PONumber" } }
      ],
      "previousAttributes": {
        "poNumber": null,
        "updatedAt": "2026-07-03T14:26:11Z"
      }
    }
  }
}
```

One glance tells the consumer the PO number changed and was previously unset (`null`) — no snapshot cache, no full re-sync.

### A trip field edit and its parent cascade

Changing Paid Loaded Miles from 500 to 400 on a trip delivers **two** events — the meaningful `trip.changed` plus a content-free `load.changed` cascade. (`MileageChanged` covers trip mileage fields including paid/loaded miles.)

```json theme={null}
// trip.changed — the meaningful one
"diff": {
  "changes": [ { "kind": "MileageChanged" } ],
  "previousAttributes": {
    "loadedMileage": { "distance": { "value": 500 }, "source": "Manual" },
    "updatedAt": "2026-07-03T13:55:16Z"
  }
}

// load.changed — parent cascade, safely ignorable
"diff": { "changes": [], "previousAttributes": { "updatedAt": "2026-07-03T13:55:16Z" } }
```

`previousAttributes` lists every response field that changed. This edit updates `loadedMileage`; `totalMileage` may also appear when the platform recalculates it from the same action.

The `trip.changed` carries the real change; the `load.changed` has empty `changes` because the load's public content didn't change — filter it out.

### Keyed collections in `previousAttributes`

When stops or their references change, `previousAttributes` diffs the collection by stable `id` — `removed` / `changed` / `added`:

```json theme={null}
"diff": {
  "changes": [ { "kind": "StopReferencesChanged", "target": { "type": "Stop", "id": "6fe6…" } } ],
  "previousAttributes": {
    "stops": { "changed": [ { "id": "6fe6…", "references": { "removed": [ { "id": "r9", "name": "KK", "value": "2175048" } ] } } ] },
    "updatedAt": "2026-06-26T12:10:16Z"
  }
}
```

The consumer learns exactly which stop's references changed and what was removed — without re-importing the load.


# Create webhook subscription
Source: https://docs.alvys.com/en/api/reference/webhooks/create-webhook-subscription

POST /api/p/v{version}/webhooks
Creates a new webhook subscription. **Note:** You must verify the HMAC-SHA256 signature using the raw request body.

Creates a new webhook subscription. **Note:** You must verify the HMAC-SHA256 signature using the raw request body.


# Delete webhook
Source: https://docs.alvys.com/en/api/reference/webhooks/delete-webhook

DELETE /api/p/v{version}/webhooks/{id}
Soft-deletes a webhook subscription.Supports RFC 7232 optimistic concurrency via `If-Match`.

Soft-deletes a webhook subscription.Supports RFC 7232 optimistic concurrency via `If-Match`.


# Disable webhook
Source: https://docs.alvys.com/en/api/reference/webhooks/disable-webhook

POST /api/p/v{version}/webhooks/{id}/disable
Disables a webhook subscription

Disables a webhook subscription


# Enable webhook
Source: https://docs.alvys.com/en/api/reference/webhooks/enable-webhook

POST /api/p/v{version}/webhooks/{id}/enable
Enables a disabled webhook subscription

Enables a disabled webhook subscription


# Event Delivery & Reliability
Source: https://docs.alvys.com/en/api/reference/webhooks/event-delivery-reliability

How Alvys delivers webhook events with at-least-once semantics, unique event IDs, automatic retries on transient failures, and handling of duplicate deliveries.

This page explains how webhook events are delivered, retried, and handled when failures occur.

### Delivery Model

Alvys uses an **at-least-once** delivery model.

This means:

* An event may be delivered more than once.
* Duplicate deliveries are possible.
* Exactly-once delivery is not guaranteed.

Each event includes a unique identifier in the header:

```
X-Alvys-Event-Id
```

Your system must use this value to detect and safely ignore duplicate deliveries.

#### Delivery Success Criteria

An event is considered successfully delivered when the endpoint returns:

```
HTTP 200–299
```

Any other response may trigger retry behavior.

| Category         | Behavior                                                                           |
| ---------------- | ---------------------------------------------------------------------------------- |
| Delivery Model   | At-least-once                                                                      |
| Max Attempts     | 4                                                                                  |
| Timeout          | 30 seconds                                                                         |
| Duplicate Events | Possible                                                                           |
| Global Ordering  | Not guaranteed                                                                     |
| Auto-Disable     | After 10 consecutive failed deliveries across distinct events (not retry attempts) |
| Idempotency      | Required                                                                           |

### Event Request Format

When a subscribed event occurs, Alvys sends an HTTPS POST request to your configured endpoint.

Example request:

```
POST https://your-endpoint.com/webhook
Content-Type: application/json
```

Headers:

```
X-Alvys-Event: tender.accepted
X-Alvys-Event-Id: evt-123456
X-Alvys-Timestamp: 1699200000
X-Alvys-Signature: t=1699200000,v1=abcdef...
X-Alvys-Attempt: 1
```

Header descriptions:

* `X-Alvys-Event` — The event type.
* `X-Alvys-Event-Id` — Unique identifier for the event. This value remains the same across retry attempts.
* `X-Alvys-Timestamp` — Unix timestamp (seconds) used for signature generation.
* `X-Alvys-Signature` — HMAC-SHA256 signature (see Security & Signature Verification).
* `X-Alvys-Attempt` — The delivery attempt number (starts at 1 and increments on each retry).

Example payload:

```json theme={null}
{
  "id": "3cd9960e-ef75-446c-92e4-e9815f6e4024-2",
  "type": "tender.accepted",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "data": {
    "tenderId": "3cd0060e-ef75-000c-92e4-e9815f6e0000",
    "loadId": "3cd0060e-ef75-446c-00e4-e9815f6e0000",
    "loadNumber": "1000580"
  }
}
```

The `data` object contains event-specific fields.

### Delivery Attempts

Each event may be delivered up to four times:

1. Initial delivery
2. Retry after approximately 10 seconds
3. Retry after approximately 30 seconds
4. Final retry after approximately 60 seconds

Retries use the same:

* Endpoint URL
* HTTP method
* Request body
* `X-Alvys-Event-Id`

There is no separate retry endpoint. The delivery attempt number is exposed on every delivery via the `X-Alvys-Attempt` header, which increments on each retry.

From the consumer’s perspective, a retry is simply another delivery of the same event.

### Retry Conditions

Retries occur when:

* The endpoint returns HTTP 500–599
* The endpoint returns HTTP 408 or 429
* A network failure occurs
* No response is received within 30 seconds

Retries do not occur for other 4xx responses.

### Timeout

Each delivery attempt allows up to 30 seconds for your endpoint to respond.

If no response is received within this window, the attempt is considered failed and may trigger a retry.

To avoid unnecessary retries, endpoints should acknowledge the event promptly after validation and persist processing asynchronously.

### HTTP Response Handling

Response code behavior:

* `200–299` — Delivery acknowledged.
* `400–499` (except 408/429) — Permanent failure, no retry.
* `408` or `429` — Retry.
* `500–599` — Retry.
* No response within 30 seconds — Retry.

### Auto-Disable Policy

A webhook is automatically disabled after:

```
10 consecutive failed events
```

A failed event means:

* A single event (identified by X-Alvys-Event-Id)
* That was attempted up to four times
* And ultimately did not receive a successful 200–299 response

Important:

* Failures are counted per event, not per retry attempt.
* Multiple retry attempts for the same event count as one failed event.
* The counter increments only after all retry attempts for an event are exhausted.
* A successful event delivery resets the consecutive failure counter to zero.

When 10 distinct events fail consecutively, the webhook is automatically disabled and must be manually re-enabled.

### Ordering

Global ordering across different tenders is not guaranteed.

Events related to the same tender are dispatched sequentially. However, integrations must tolerate:

* Retries
* Duplicate deliveries
* Timing variations

Do not rely on strict ordering guarantees.


# Get event types
Source: https://docs.alvys.com/en/api/reference/webhooks/get-event-types

GET /api/p/v{version}/webhooks/event-types
Returns all available webhook event types

Returns all available webhook event types


# Get webhook
Source: https://docs.alvys.com/en/api/reference/webhooks/get-webhook

GET /api/p/v{version}/webhooks/{id}
Returns a specific webhook by ID

Returns a specific webhook by ID


# List webhooks
Source: https://docs.alvys.com/en/api/reference/webhooks/list-webhooks

GET /api/p/v{version}/webhooks
Returns paginated webhook subscriptions. Default size: 50. Ordered by creation date (newest first).

Returns paginated webhook subscriptions. Default size: 50. Ordered by creation date (newest first).


# Load Events
Source: https://docs.alvys.com/en/api/reference/webhooks/load-events

Reference for Alvys load webhook events, including load.status.changed and load.changed, event payloads, and optional data.diff field-level changes.

Alvys emits webhook events for the load lifecycle, so external systems stay in sync in real time instead of polling the Loads API.

| Event                 | Fires when                                                                    | Carries `data.diff` |
| --------------------- | ----------------------------------------------------------------------------- | ------------------- |
| `load.status.changed` | A load's status transitions (e.g. `Covered` → `Dispatched`)                   | No                  |
| `load.changed`        | Any meaningful load write (rate, appointments, stops, carrier, references, …) | Yes (optional)      |

Subscribe to either or both when creating or updating a webhook (see [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration)). The full list of valid event-type strings is returned by `GET /api/p/v1/webhooks/event-types`.

## Status vs. changed

`load.status.changed` fires **only** on a status transition and never includes a `data.diff`.

`load.changed` fires on **every** meaningful write — including status changes — and can include an optional `data.diff` describing what changed. See [Change Diffs (data.diff)](/en/api/reference/webhooks/change-diffs).

<Info>
  A single underlying write can emit **both** events — one `load.status.changed` and one `load.changed`. They are distinguished by the suffix on the event `id`: `-1` for the status event and `-0` for the changed event. Use `X-Alvys-Event-Id` for idempotency so the two are processed independently and duplicates are ignored.
</Info>

## Payload

Load events use the standard Alvys webhook [envelope](/en/api/reference/webhooks/event-delivery-reliability#event-request-format). The `data.load` object carries the **full current snapshot** of the load — the same shape the Loads API returns from its `GET` endpoint.

### `load.status.changed`

```json theme={null}
{
  "id": "3cd9960e-ef75-446c-92e4-e9815f6e4024-1",
  "type": "load.status.changed",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "data": {
    "load": { "...": "full current Load snapshot (matches GET /api/p/v1/loads)" }
  }
}
```

### `load.changed`

```json theme={null}
{
  "id": "3cd9960e-ef75-446c-92e4-e9815f6e4024-0",
  "type": "load.changed",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "data": {
    "load": { "...": "full current Load snapshot" },
    "diff": {
      "changes": [
        { "kind": "StatusChanged" },
        { "kind": "RateChanged" },
        { "kind": "FieldChanged", "target": { "type": "Field", "id": "PONumber" } }
      ],
      "previousAttributes": { "...": "previous values (opt-in)" }
    }
  }
}
```

## Notes

* Because `data.load` always carries the full snapshot, you can apply the current state directly without a follow-up `GET`. To react to only what changed, use [`data.diff`](/en/api/reference/webhooks/change-diffs).
* Delivery is **at-least-once** — deduplicate on `X-Alvys-Event-Id`. See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability).
* `data.diff` is omitted on the first event for a load (create) and is never present on `load.status.changed`.


# Webhooks overview
Source: https://docs.alvys.com/en/api/reference/webhooks/overview

Complete guide to Alvys webhooks — signed HTTPS event delivery, endpoint verification, signature validation, retries, event types, and the full webhook management API.

Webhooks let your system receive real-time updates from Alvys when business events occur. Instead of polling the API, Alvys sends an HTTPS POST request to your configured endpoint whenever a subscribed event is triggered.

Webhooks are configured per Subsidiary. Each Subsidiary maintains its own set of webhook subscriptions, and events are delivered only within that Subsidiary's context.

<Warning>
  Webhooks are currently available by request. To enable this functionality for your account, contact your Customer Success Manager or Implementation Manager.
</Warning>

## How it works

1. **Subscribe** — create a webhook with an HTTPS endpoint URL and at least one subscribed event, either in the dashboard (**Settings → Connections → Webhooks**) or via the [Create webhook](/en/api/reference/webhooks/create-webhook-subscription) endpoint.
2. **Verify ownership** — when the webhook is enabled, Alvys sends a `webhook.verification` challenge to your endpoint. Your endpoint echoes the challenge back to prove ownership. See [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration).
3. **Receive events** — Alvys delivers each subscribed event as a signed HTTPS POST request to your endpoint.
4. **Validate and acknowledge** — your endpoint verifies the HMAC-SHA256 signature, deduplicates on the event ID, and returns a `2xx` response promptly.
5. **Retries** — failed deliveries are retried automatically. After 10 consecutive failed events, the webhook is disabled automatically.

All deliveries:

* Use HTTPS (TLS 1.2+)
* Are signed using HMAC-SHA256
* Follow an at-least-once delivery model
* Are retried automatically on transient failure
* Are disabled automatically after repeated delivery failures

To integrate successfully, your endpoint must verify signatures, handle retries safely, and implement idempotency.

## Which events reach your subscription

A subscription belongs to one Subsidiary, and it receives an event only when the record the event is about belongs to that same Subsidiary.

| Event group                                                   | The Subsidiary the event is matched on                                        |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `load.*`                                                      | The load's invoicing Subsidiary                                               |
| `trip.*`                                                      | The trip's tendering Subsidiary                                               |
| `load.document.*`, `trip.document.*`                          | The Subsidiary of the load or trip the document is filed against              |
| `driver.document.*`, `truck.document.*`, `trailer.document.*` | The Subsidiary of the driver, truck, or trailer the document is filed against |
| `tender.*`                                                    | The tender's Subsidiary                                                       |

Carrier documents are the one exception: a carrier carries no Subsidiary on the broker side, so `carrier.document.*` events are delivered to every subscription in the tenant.

<Note>
  Document and tender events were previously delivered to every subscription in the tenant regardless of Subsidiary. They now follow the table above. If your integration filtered these events by Subsidiary itself, that filtering is now redundant but harmless; no action is required. If it relied on receiving another Subsidiary's document or tender events, it will stop receiving them.
</Note>

Where the Subsidiary of a record cannot be determined, the event is delivered to every subscription in the tenant rather than withheld.

## Event types

| Event                                                                                                                                                                                                   | Fires when                                                                 | Details                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `load.status.changed`                                                                                                                                                                                   | A load's status transitions (e.g. `Covered` → `Dispatched`)                | [Load Events](/en/api/reference/webhooks/load-events)                                           |
| `load.changed`                                                                                                                                                                                          | Any meaningful load write — rate, appointments, stops, references, …       | [Load Events](/en/api/reference/webhooks/load-events)                                           |
| `trip.status.changed`                                                                                                                                                                                   | A trip's status transitions                                                | [Trip Events](/en/api/reference/webhooks/trip-events)                                           |
| `trip.changed`                                                                                                                                                                                          | Any meaningful trip write — carrier, driver, stops, appointments, rates, … | [Trip Events](/en/api/reference/webhooks/trip-events)                                           |
| `tender.created`                                                                                                                                                                                        | An inbound tender arrives, before anyone reviews it                        | [Tender Events](/en/api/reference/webhooks/tender-events)                                       |
| `tender.change.created`                                                                                                                                                                                 | A change tender is received for an existing tender                         | [Tender Events](/en/api/reference/webhooks/tender-events)                                       |
| `tender.accepted`, `tender.rejected`, `tender.cancelled`, `tender.change.accepted`, `tender.bid.submitted`, `tender.invoiced`, `tender.stop.arrived`, `tender.stop.departed`, `tender.stop.eta_updated` | A tender moves through its lifecycle                                       | [Tender Events](/en/api/reference/webhooks/tender-events)                                       |
| `webhook.verification`                                                                                                                                                                                  | Alvys verifies ownership of your endpoint (system event, not signed)       | [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration) |

The authoritative list of valid event-type strings for your account is returned by [Get event types](/en/api/reference/webhooks/get-event-types) (`GET /api/p/v1/webhooks/event-types`).

`load.changed` and `trip.changed` events carry the full current snapshot of the record plus an optional `data.diff` node describing what changed — and, if you opt in, what the values were before. See [Change Diffs (data.diff)](/en/api/reference/webhooks/change-diffs).

## Anatomy of a delivery

When a subscribed event occurs, Alvys sends an HTTPS POST request to your configured endpoint.

Headers:

```
X-Alvys-Event: load.status.changed
X-Alvys-Event-Id: evt-123456
X-Alvys-Timestamp: 1699200000
X-Alvys-Signature: t=1699200000,v1=abcdef...
X-Alvys-Attempt: 1
```

* `X-Alvys-Event` — the event type.
* `X-Alvys-Event-Id` — unique identifier for the event. Remains the same across retry attempts; use it for idempotency.
* `X-Alvys-Timestamp` — Unix timestamp (seconds) used for signature generation.
* `X-Alvys-Signature` — HMAC-SHA256 signature (see [Verifying signatures](#verifying-signatures)).
* `X-Alvys-Attempt` — the delivery attempt number (starts at 1, increments on each retry).

Every event body uses the same envelope:

```json theme={null}
{
  "id": "3cd9960e-ef75-446c-92e4-e9815f6e4024-1",
  "type": "load.status.changed",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "etag": "99005ab4-0000-0300-0000-699c72880000",
  "data": {
    "load": { "...": "full current Load snapshot (matches GET /api/p/v1/loads)" }
  }
}
```

Every envelope carries `etag`, identifying the version of the record the payload was built from. Tender events use `version: "v2"`; all other events use `"v1"`.

The `data` object contains event-specific fields. For load and trip events it carries the full current snapshot of the record — the same shape the corresponding `GET` endpoint returns — so you can apply the current state directly without a follow-up request. See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability#event-request-format) for the full request format.

## Verifying signatures

Every event delivery is signed so you can confirm it came from Alvys and was not tampered with. Verification requests (`webhook.verification`) are not signed.

The `X-Alvys-Signature` header has the format `t={timestamp},v1={signature}`, where the signature is an HMAC-SHA256 hash of:

```
{timestamp}.{eventId}.{raw_request_body}
```

To validate a delivery:

1. Extract the timestamp and signature value(s) from the `X-Alvys-Signature` header.
2. Construct the signed payload from the timestamp, event ID, and the exact raw request body — do not reformat or reserialize the JSON.
3. Compute an HMAC-SHA256 hash using your webhook's signing secret.
4. Compare against the provided signature(s) using constant-time comparison.
5. Return `401 Unauthorized` and do not process the event if no match is found.

During secret rotation the header carries two signatures (`v1` for the new secret, `v0` for the previous one) — accept either during the transition window. Rejecting requests whose timestamp is more than 5 minutes old reduces replay risk.

Full details, including transport requirements and secret management: [Security & Signature Verification](/en/api/reference/webhooks/security-signature-verification).

## Delivery guarantees

| Category         | Behavior                                                                      |
| ---------------- | ----------------------------------------------------------------------------- |
| Delivery model   | At-least-once                                                                 |
| Max attempts     | 4 (initial + retries after \~10s, \~30s, \~60s)                               |
| Timeout          | 30 seconds per attempt                                                        |
| Retry triggers   | HTTP 500–599, 408, 429, network failure, or timeout                           |
| Duplicate events | Possible — deduplicate on `X-Alvys-Event-Id`                                  |
| Global ordering  | Not guaranteed                                                                |
| Auto-disable     | After 10 consecutive failed events (counted per event, not per retry attempt) |
| Idempotency      | Required                                                                      |

A delivery succeeds when your endpoint returns HTTP `200–299`. Other 4xx responses (except 408 and 429) are permanent failures and are not retried. A successful delivery resets the consecutive-failure counter; once 10 distinct events fail consecutively, the webhook is disabled and must be manually re-enabled.

<Tip>
  Acknowledge the event promptly after validation and persist processing asynchronously. This avoids timeouts, unnecessary retries, and accidental auto-disable.
</Tip>

See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability) for the complete retry, timeout, and ordering semantics.

## Managing webhooks

Webhooks can be managed from the dashboard (**Settings → Connections → Webhooks**) or entirely via the API:

| Action                | Endpoint                                           | Reference                                                                                                   |
| --------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Create a webhook      | `POST /api/p/v1/webhooks`                          | [Create webhook subscription](/en/api/reference/webhooks/create-webhook-subscription)                       |
| List webhooks         | `GET /api/p/v1/webhooks`                           | [List webhooks](/en/api/reference/webhooks/list-webhooks)                                                   |
| Get a webhook         | `GET /api/p/v1/webhooks/{id}`                      | [Get webhook](/en/api/reference/webhooks/get-webhook)                                                       |
| Update a webhook      | `PUT /api/p/v1/webhooks/{id}`                      | [Update webhook](/en/api/reference/webhooks/update-webhook)                                                 |
| Delete a webhook      | `DELETE /api/p/v1/webhooks/{id}`                   | [Delete webhook](/en/api/reference/webhooks/delete-webhook)                                                 |
| Enable / disable      | `POST /api/p/v1/webhooks/{id}/enable` · `/disable` | [Enable](/en/api/reference/webhooks/enable-webhook) · [Disable](/en/api/reference/webhooks/disable-webhook) |
| Verify ownership      | `POST /api/p/v1/webhooks/{id}/verify`              | [Verify webhook ownership](/en/api/reference/webhooks/verify-webhook-ownership)                             |
| Send a test event     | `POST /api/p/v1/webhooks/{id}/test`                | [Test webhook delivery](/en/api/reference/webhooks/test-webhook-delivery)                                   |
| List event types      | `GET /api/p/v1/webhooks/event-types`               | [Get event types](/en/api/reference/webhooks/get-event-types)                                               |
| Reveal signing secret | `POST /api/p/v1/webhooks/{id}/reveal-secret`       | [Reveal webhook secret](/en/api/reference/webhooks/reveal-webhook-secret)                                   |
| Rotate signing secret | `POST /api/p/v1/webhooks/{id}/rotate-secret`       | [Rotate secret](/en/api/reference/webhooks/rotate-secret)                                                   |

Configuration details — states, endpoint verification, updating subscriptions, and the **Include previous values** option — are covered in [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration).

## Monitoring and troubleshooting

Every delivery attempt is logged and queryable:

| Action                       | Endpoint                                                   | Reference                                                                           |
| ---------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| List delivery logs           | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs`         | [List delivery logs](/en/api/reference/webhooks/list-delivery-logs)                 |
| Get delivery detail          | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs/{logId}` | [Get delivery log detail](/en/api/reference/webhooks/get-delivery-log-detail)       |
| Export logs (CSV/JSON)       | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs/export`  | [Export delivery logs](/en/api/reference/webhooks/export-delivery-logs)             |
| Health metrics (1/7/30 days) | `GET /api/p/v1/webhooks/{webhookId}/health`                | [Get webhook health metrics](/en/api/reference/webhooks/get-webhook-health-metrics) |

Use [Test webhook delivery](/en/api/reference/webhooks/test-webhook-delivery) to send a signed test payload to your endpoint and verify your signature logic end to end.

## Best practices

* **Verify every signature** before executing any business logic; return `401` on failure.
* **Deduplicate on `X-Alvys-Event-Id`** — delivery is at-least-once, so duplicates are expected.
* **Acknowledge fast** — return `2xx` after validation and process asynchronously to stay inside the 30-second window.
* **Don't rely on ordering** — tolerate retries, duplicates, and timing variations.
* **Use `data.diff` to filter noise** — ignore deliveries where `changes` is empty (parent cascades), and tolerate change kinds you don't recognize.
* **Support dual signatures** (`v1` and `v0`) so secret rotation never interrupts your integration.
* **Watch health metrics and delivery logs** so you catch failures before the auto-disable threshold.

## Next steps

<CardGroup>
  <Card title="Webhook Lifecycle & Configuration" href="/en/api/reference/webhooks/webhook-lifecycle-configuration" icon="gear">
    Create, verify, update, and manage webhook subscriptions per Subsidiary.
  </Card>

  <Card title="Security & Signature Verification" href="/en/api/reference/webhooks/security-signature-verification" icon="shield-halved">
    Validate HMAC-SHA256 signatures and handle secret rotation.
  </Card>

  <Card title="Event Delivery & Reliability" href="/en/api/reference/webhooks/event-delivery-reliability" icon="rotate">
    At-least-once delivery, retries, timeouts, and auto-disable semantics.
  </Card>

  <Card title="Change Diffs (data.diff)" href="/en/api/reference/webhooks/change-diffs" icon="code-compare">
    React to exactly what changed with `changes` and `previousAttributes`.
  </Card>
</CardGroup>


# Reveal webhook secret
Source: https://docs.alvys.com/en/api/reference/webhooks/reveal-webhook-secret

POST /api/p/v{version}/webhooks/{id}/reveal-secret
Decrypts and returns the webhook secret in plaintext

Decrypts and returns the webhook secret in plaintext


# Rotate secret
Source: https://docs.alvys.com/en/api/reference/webhooks/rotate-secret

POST /api/p/v{version}/webhooks/{id}/rotate-secret
Generates a new webhook secret while maintaining backward compatibility

Generates a new webhook secret while maintaining backward compatibility


# Security & Signature Verification
Source: https://docs.alvys.com/en/api/reference/webhooks/security-signature-verification

Validate incoming Alvys webhook deliveries by verifying HMAC-SHA256 signatures over the raw request body, plus HTTPS and TLS transport requirements.

All webhook event deliveries are signed to ensure authenticity and integrity.

Your endpoint must validate the signature before processing any event.

Verification requests (`webhook.verification`) are **not signed**.

### Transport Requirements

Webhook endpoints must:

* Use HTTPS
* Support TLS 1.2 or higher
* Present a valid certificate

Requests are delivered only over secure connections.

### Signature Header

Each event delivery includes the header:

```
X-Alvys-Signature
```

Format:

```
t={timestamp},v1={signature}
```

During secret regeneration, the header may include two signatures:

```
t={timestamp},v1={new_signature},v0={previous_signature}
```

Where:

* `t` is the Unix timestamp (seconds)
* `v1` is generated using the current secret
* `v0` is generated using the previous secret during the transition window

### Signed Payload Format

The signature is generated from:

```
{timestamp}.{eventId}.{raw_request_body}
```

Important:

* Use the exact raw request body.
* Do not reformat or reserialize JSON before verification.
* Any change to whitespace or formatting will invalidate the signature.

### Verification Process

To validate a delivery:

1. Extract the timestamp from the `X-Alvys-Signature` header.
2. Extract the signature value.
3. Read the raw request body exactly as received.
4. Construct the signed payload string.
5. Compute an HMAC-SHA256 hash using your webhook secret.
6. Compare the computed value to the signature(s) provided.
7. Process the event only if a match is found.

Signature comparison should use constant-time comparison to prevent timing attacks.

### Replay Protection

It is recommended to reject requests where:

```
|current_time - timestamp| > 5 minutes
```

This helps reduce replay risk.

### Secret Management

Each webhook has a unique signing secret.

The secret:

* Is generated when the webhook is created.
* Can be regenerated using the **Regenerate Secret Key** option in the UI.
* Should be stored securely.
* Must never be exposed in client-side code or logs.

### If Signature Validation Fails

If the signature cannot be verified:

* Return HTTP `401 Unauthorized`.
* Do not process the event.

Signature validation must occur before executing any business logic.


# Tender Events
Source: https://docs.alvys.com/en/api/reference/webhooks/tender-events

Reference for Alvys tender webhook events, including tender.created and tender.change.created, event payloads, the published change-type vocabulary, and subscription behavior.

Alvys emits webhook events across the inbound tender lifecycle, so external systems can react to tenders as they arrive and change instead of polling the Tenders API.

| Event                     | Fires when                                                            | `data` fields beyond `tenderId`                           |
| ------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| `tender.created`          | A new inbound tender is received, before anyone reviews or accepts it | `tender`                                                  |
| `tender.change.created`   | A change tender is received for an existing tender                    | `queuedForReview`, `changeCount`, `changeTypes`, `tender` |
| `tender.accepted`         | A tender is accepted                                                  | `loadId`, `loadNumber`, `tender`                          |
| `tender.rejected`         | A tender is rejected                                                  | `tender`                                                  |
| `tender.cancelled`        | A tender is cancelled                                                 | `tender`                                                  |
| `tender.change.accepted`  | Queued tender changes are applied                                     | `tender`                                                  |
| `tender.bid.submitted`    | A bid is submitted for a tender                                       | `bidAmount`, `tender`                                     |
| `tender.stop.arrived`     | A stop arrival is recorded                                            | `stopId`, `arrivedAt`, `reason`, `tender`                 |
| `tender.stop.departed`    | A stop departure is recorded                                          | `stopId`, `departedAt`, `reason`, `tender`                |
| `tender.stop.eta_updated` | A stop's estimated time of arrival is updated                         | `stopId`, `estimatedAt`, `reason`, `tender`               |
| `tender.invoiced`         | A tender is invoiced                                                  | `invoiceId`, `tender`                                     |

The authoritative list of valid event-type strings for your account is returned by [Get event types](/en/api/reference/webhooks/get-event-types) (`GET /api/p/v1/webhooks/event-types`).

<Warning>
  There is no wildcard subscription. Each event you want must be listed explicitly on the subscription, so an existing webhook does **not** start receiving `tender.created` or `tender.change.created` until you add them — see [Update webhook](/en/api/reference/webhooks/update-webhook).
</Warning>

## Payload

Tender events use the standard Alvys webhook [envelope](/en/api/reference/webhooks/event-delivery-reliability#event-request-format), with one difference from load and trip events: the envelope `version` is `v2` rather than `v1`. As on every event, `etag` identifies the version of the tender the payload was built from.

Every tender payload carries `data.tenderId` and a `data.tender` object holding a full tender snapshot — the same shape [Get tender](/en/api/reference/tenders/get-tender) returns. Event-specific fields sit alongside it.

```json theme={null}
{
  "id": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c-2",
  "type": "tender.accepted",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v2",
  "etag": "99005ab4-0000-0300-0000-699c72880000",
  "data": {
    "tenderId": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c",
    "loadId": "3cd0060e-ef75-446c-00e4-e9815f6e0000",
    "loadNumber": "1000580",
    "tender": { "...": "full current Tender snapshot" }
  }
}
```

<Warning>
  If Alvys cannot build the snapshot for a delivery, `data.tender` is **omitted from the payload entirely** rather than sent as `null`, and the rest of the envelope is unaffected. Treat a missing `data.tender` as "snapshot unavailable on this delivery", not as an empty tender, and read the tender with [Get tender](/en/api/reference/tenders/get-tender) when you need it.
</Warning>

A tender whose distance was recorded in a unit other than miles or kilometers — meters or feet, for example — is converted to miles for reporting purposes. Those tenders carry `data.tender` on every event, and [Get tender](/en/api/reference/tenders/get-tender) and [Search tenders](/en/api/reference/tenders/search-tenders) return them normally. `TenderResponse` does not expose a distance field, so the recorded unit is not visible on the tender itself.

The envelope `timestamp` is the moment the underlying business event occurred. For the three stop events it is when Alvys **recorded** the update, which can be later than the arrival, departure, or ETA the payload itself reports — use `data.arrivedAt`, `data.departedAt`, or `data.estimatedAt` when you need the operational time.

## `tender.created`

Fires when a new inbound tender is received, before any review or acceptance. `data` carries `tenderId` and the tender snapshot.

```json theme={null}
{
  "id": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c-0",
  "type": "tender.created",
  "timestamp": "2026-02-23T15:30:07.4523837+00:00",
  "version": "v2",
  "etag": "99005ab4-0000-0300-0000-699c72880000",
  "data": {
    "tenderId": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c",
    "tender": { "...": "full current Tender snapshot" }
  }
}
```

<Info>
  This event also fires when a change tender cannot be matched to an existing shipment and Alvys creates a new tender for it. A `data.tender.shipmentId` you have already seen can therefore arrive a second time under a different `tenderId` — key your own records on `tenderId`, not on the shipment identifier.
</Info>

Because `tender.created` fires on every inbound tender rather than only on tenders someone has acted on, it delivers at a substantially higher rate than the other tender events. Size your endpoint accordingly.

## `tender.change.created`

Fires when a change tender is received, whether or not the tender has a linked load. `data.queuedForReview` tells the two cases apart, and it decides how to read the rest of the payload.

| `queuedForReview` | What happened                                                                | `data.tender` holds                        | `changeCount` / `changeTypes` |
| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------- |
| `true`            | The tender has a linked load, so the changes are queued and await acceptance | The tender **before** the proposed changes | Present                       |
| `false`           | The tender has no linked load, so its fields were replaced outright          | The tender **after** the change            | Omitted                       |

```json theme={null}
{
  "id": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c-2",
  "type": "tender.change.created",
  "timestamp": "2026-02-23T15:30:07.4523837+00:00",
  "version": "v2",
  "etag": "99005ab4-0000-0300-0000-699c72880000",
  "data": {
    "tenderId": "d9a958b3-77cb-43fb-bdc7-ec7e027e689c",
    "queuedForReview": true,
    "changeCount": 3,
    "changeTypes": ["LoadRate", "StopSchedule"],
    "tender": { "...": "full Tender snapshot, before the proposed changes" }
  }
}
```

<Warning>
  When `queuedForReview` is `true`, `data.tender` is the tender as it stands **now**, not as it would stand after the changes. Reading `data.tender.rate` on a queued `LoadRate` change gives you the current rate, not the proposed one. Accept the changes with [Accept tender updates](/en/api/reference/tenders/accept-tender-updates) (`POST /api/p/v1/tenders/{tenderId}/accept-updates`) and read the tender again to see the applied values.
</Warning>

A change tender that restates what Alvys already has is still delivered, with `changeCount: 0` and `changeTypes: []`. Use the zero count to skip it.

### `changeTypes`

`changeTypes` lists the **distinct** categories of change proposed, in the order they appear on the tender. `changeCount` counts every queued update, so the two can disagree — a change tender can carry several updates of one category, and a category Alvys does not publish is counted without being named. Do not treat `changeTypes.length` as an upper bound on `changeCount`.

The published vocabulary is:

<CodeGroup>
  ```text Tender-level theme={null}
  LoadRate
  TotalWeight
  Trailer
  PaymentMethod
  PalletQuantity
  Distance
  TenderNotes
  TenderCharges
  AccessorialsUpdate
  PurchaseOrderNumber
  TenderReferenceAdded
  TenderReferenceRemoved
  ```

  ```text Stop-level theme={null}
  StopSchedule
  StopAddress
  StopAdded
  StopRemoved
  StopNotes
  StopPositionChanged
  StopOrderDetailsChanged
  StopPoNumberChanged
  StopInfoChanged
  StopReferenceAdded
  StopReferenceRemoved
  ```
</CodeGroup>

These values are a stable contract. Treat any value outside this list as unrecognized rather than failing on it — the list can gain entries without notice, and unpublished categories are never named.

## Notes

* Delivery is **at-least-once** — deduplicate on `X-Alvys-Event-Id`. See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability).
* Tender events are matched to a subscription by the tender's Subsidiary — the same subsidiary scoping that applies to load and trip events. See [Which events reach your subscription](/en/api/reference/webhooks/overview#which-events-reach-your-subscription).
* Tender events do not carry a `data.diff` node. The only action available on a queued change is to accept it in full, so `changeTypes` is the granularity you can act on.
* Events for the same tender are dispatched in order; ordering across different tenders is not guaranteed.


# Test webhook delivery
Source: https://docs.alvys.com/en/api/reference/webhooks/test-webhook-delivery

POST /api/p/v{version}/webhooks/{id}/test
Sends a signed test payload to the configured URL to verify signature logic.

Sends a signed test payload to the configured URL to verify signature logic.


# Trip Events
Source: https://docs.alvys.com/en/api/reference/webhooks/trip-events

Reference for Alvys trip webhook events, including trip.status.changed and trip.changed, event payloads, and optional data.diff field-level changes.

Alvys emits webhook events for the trip lifecycle, so external systems stay in sync in real time instead of polling the Trips API.

| Event                 | Fires when                                                                 | Carries `data.diff` |
| --------------------- | -------------------------------------------------------------------------- | ------------------- |
| `trip.status.changed` | A trip's status transitions                                                | No                  |
| `trip.changed`        | Any meaningful trip write (carrier, driver, stops, appointments, rates, …) | Yes (optional)      |

Subscribe to either or both when creating or updating a webhook (see [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration)). The full list of valid event-type strings is returned by `GET /api/p/v1/webhooks/event-types`.

## Status vs. changed

`trip.status.changed` fires **only** on a status transition and never includes a `data.diff`.

`trip.changed` fires on **every** meaningful write — including status changes — and can include an optional `data.diff` describing what changed. See [Change Diffs (data.diff)](/en/api/reference/webhooks/change-diffs).

<Info>
  A single underlying write can emit **both** events — one `trip.status.changed` and one `trip.changed`. They are distinguished by the suffix on the event `id`: `-1` for the status event and `-0` for the changed event. Use `X-Alvys-Event-Id` for idempotency so the two are processed independently and duplicates are ignored.
</Info>

## Payload

Trip events use the standard Alvys webhook [envelope](/en/api/reference/webhooks/event-delivery-reliability#event-request-format). The `data.trip` object carries the **full current snapshot** of the trip — the same shape the Trips API returns from its `GET` endpoint.

### `trip.status.changed`

```json theme={null}
{
  "id": "7be1220a-1c22-4f10-b8a1-2d3e4f5a6b7c-1",
  "type": "trip.status.changed",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "data": {
    "trip": { "...": "full current Trip snapshot (matches GET /api/p/v1/trips)" }
  }
}
```

### `trip.changed`

```json theme={null}
{
  "id": "7be1220a-1c22-4f10-b8a1-2d3e4f5a6b7c-0",
  "type": "trip.changed",
  "timestamp": "2026-02-23T15:19:35.8794642+00:00",
  "version": "v1",
  "data": {
    "trip": { "...": "full current Trip snapshot" },
    "diff": {
      "changes": [
        { "kind": "CarrierChanged" },
        { "kind": "AppointmentChanged", "target": { "type": "Stop", "id": "abc123" } },
        { "kind": "StopReordered" }
      ],
      "previousAttributes": { "...": "previous values (opt-in)" }
    }
  }
}
```

<Info>
  Trip stop-scoped changes (`StopAddressChanged`, `AppointmentChanged`, `StopReordered`, …) carry a `target` of `{ "type": "Stop", "id": "<StopId>" }`, where `id` is the stable stop identity from the snapshot — never a positional index.
</Info>

## Notes

* Because `data.trip` always carries the full snapshot, you can apply the current state directly without a follow-up `GET`. To react to only what changed, use [`data.diff`](/en/api/reference/webhooks/change-diffs).
* Delivery is **at-least-once** — deduplicate on `X-Alvys-Event-Id`. See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability).
* `data.diff` is omitted on the first event for a trip (create) and is never present on `trip.status.changed`.


# Update webhook
Source: https://docs.alvys.com/en/api/reference/webhooks/update-webhook

PUT /api/p/v{version}/webhooks/{id}
Updates a webhook subscription. Supports RFC 7232 optimistic concurrency via `If-Match`.

Updates a webhook subscription. Supports RFC 7232 optimistic concurrency via `If-Match`.


# Verify webhook ownership
Source: https://docs.alvys.com/en/api/reference/webhooks/verify-webhook-ownership

POST /api/p/v{version}/webhooks/{id}/verify
Verifies webhook endpoint ownership using challenge-response mechanism

Verifies webhook endpoint ownership using challenge-response mechanism


# Webhook Lifecycle & Configuration
Source: https://docs.alvys.com/en/api/reference/webhooks/webhook-lifecycle-configuration

Create, configure, and manage Alvys webhook subscriptions per Subsidiary, including event selection, Include Previous Values, and lifecycle states.

Webhooks are configured from **Settings → Connections → Webhooks**.

Each webhook belongs to a specific Subsidiary. When you switch subsidiaries in the UI, you are viewing and managing webhooks for that Subsidiary only. Events are delivered only within that Subsidiary’s context: a load event reaches a subscription when the load is invoiced as that Subsidiary, and a trip event when the trip is tendered as it.

<Note>
  Two cases deliver across every subscription in the tenant rather than to one Subsidiary:

  * An event whose Subsidiary cannot be determined (fail-open), including `carrier.document.*` — a carrier carries no broker-side Subsidiary.
  * A subscription created before a Subsidiary was required, which therefore has none recorded.

  Document and tender events are Subsidiary-matched like load and trip events. See [Which events reach your subscription](/en/api/reference/webhooks/overview#which-events-reach-your-subscription). If you receive an event you did not expect on a Subsidiary-scoped subscription, check which of the cases above applies before treating it as a routing fault.
</Note>

<Warning>
  **Webhook Availability Notice**

  Webhooks are currently available by request.
  To enable this functionality for your account, please contact your Customer Success Manager or Implementation Manager.
</Warning>

## Creating a Webhook

1. Navigate to **Settings → Webhooks**
2. Select a **Subsidiary**
3. Click **Create Webhook**
4. Provide:

   * **Name**
   * **Endpoint URL** (HTTPS required)
   * **At least one subscribed event**

The endpoint must be publicly accessible over HTTPS and support TLS 1.2 or higher.

<img alt="" />

After saving:

* A signing secret is generated.
* The webhook is created in a **Pending** state.
* No events are delivered until the webhook is enabled and verified.

<img alt="" />

## Enabling a Webhook

Webhooks are activated using the **Send Events** toggle.

When enabled, Alvys verifies ownership of your endpoint before delivering business events.

### Endpoint Verification

When activation is triggered, Alvys sends an HTTPS POST request to your configured endpoint.

#### Request

```
POST https://your-endpoint.com/webhook
```

Headers:

```
Content-Type: application/json; charset=utf-8
User-Agent: Alvys-Webhook/1.0
X-Alvys-Event: webhook.verification
X-Alvys-Challenge: {random_token}
traceparent: {w3c-trace-id}
```

Body:

```json theme={null}
{
  "type": "webhook.verification",
  "challenge": "{random_token}"
}
```

Verification requests are **not signed**.

### Required Response

Your endpoint must respond within **30 seconds**:

Status:

```
200 OK
```

Body:

```json theme={null}
{
  "challenge": "{the_same_random_token}"
}
```

Requirements:

* The response must be valid JSON.
* The property name must be exactly `challenge`.
* The value must match exactly (case-sensitive).
* Do not wrap the response.
* Do not return plain text.

If verification succeeds:

* The webhook status changes to Active
* The UI status indicator turns green and displays Connected
* Business events begin to be delivered to the endpoint

If verification fails:

* The webhook remains Disabled
* The UI displays a failed verification state
* No events are delivered

## Webhook States

A webhook may be in one of the following states:

* **Disabled** — Not delivering events
* **Pending** — Pending Verification in progress
* **Connected** — Verified and delivering events
* **Failed to verify** — Verification attempt failed

<br />

## Updating a Webhook

### Changing the Endpoint URL

If the endpoint URL is updated:

* The webhook is automatically set to **Pending**
* Verification is required again
* No events are delivered until verification succeeds

### Updating Subscribed Events

Changes to event selection:

* Take effect immediately

* Do not require verification

## Include Previous Values

On `load.changed` and `trip.changed` events, Alvys can include the previous value of every changed field via `data.diff.previousAttributes`, so your integration can apply just the delta instead of re-syncing the whole record.

This is **opt-in per webhook**:

* Enable the **Include previous values** option on the webhook (or set `IncludePreviousAttributes` to `true` via the API — see [Create webhook](/en/api/reference/webhooks/create-webhook-subscription)).
* Defaults to **off**. When off, `load.changed` / `trip.changed` events still include `data.diff.changes` (what changed) but not the previous values.
* Changes take effect immediately and do not require re-verification.

See [Change Diffs (data.diff)](/en/api/reference/webhooks/change-diffs) for the full payload shape.

### Rotating the Signing Secret

You can regenerate a webhook’s signing secret from the Webhook details page using the **Regenerate Secret Key** option.

When the secret is regenerated:

* A new signing secret is created.
* The webhook remains **Active**.
* Event delivery continues without interruption.
* Endpoint re-verification is not required.

During the rotation window, each delivery includes two signatures:

```
X-Alvys-Signature: t={timestamp},v1={new_signature},v0={previous_signature}
```

Where:

* `v1` is generated using the new secret.
* `v0` is generated using the previous secret.
* Your endpoint should accept either signature during this transition period.

After the rotation window ends, only the `v1` signature is included in deliveries.

If your integration validates webhook signatures, ensure it supports dual-signature verification during secret rotation.

## Manual Disable

Disabling a webhook:

* Immediately stops event delivery
* Preserves configuration
* Allows re-enablement at any time


# Changelog
Source: https://docs.alvys.com/en/api/changelog

Release notes and updates for the Alvys Public API, webhooks, MCP server, and integrations, with new entries added when surfaces change.

<Update label="September 6, 2026" description="Trip and stop ETAs on the Public API">
  Trips and stops now report their estimated time of arrival. Every stop returned by the Trips and Loads endpoints carries an `Eta` object, and each trip carries the ETA of its final stop, so you can surface arrival estimates without polling a tracking provider or computing them yourself.

  ### What's New

  * **`Eta` on every stop** — `GET /api/p/v{version}/trips`, `POST /trips/search`, `GET /trips/{tripId}/stops`, `GET /trips/{tripId}/stops/{stopId}`, the stop write endpoints (arrival, departure, clear arrival, set appointment), and the load endpoints (`GET /loads`, `POST /loads/search`) return an `Eta` object on each stop: `{ "Planned", "Live", "Manual" }`, each an ISO 8601 date-time or `null`.
  * **`Eta` on every trip** — `GET /trips`, `POST /trips/search`, `POST /trips/{tripId}/assign`, and `POST /trips/{tripId}/dispatch` return the same object at the trip level, carrying the ETA of the trip's final stop.
  * **`Planned`** is the ETA from route planning, set when the trip is planned or re-planned. **`Live`** is the live ETA, recalculated from the latest vehicle location while the trip is in transit. **`Manual`** is the ETA a user or integration entered on the stop, or the default taken from the stop date or appointment.

  ### What Changes

  * This release is additive and backward compatible. Existing consumers see one new nullable field on each stop and each trip.
  * **HOS-aware ETAs are a plan feature.** `Planned` and `Live` are populated only for tenants whose plan includes HOS-aware ETAs — live estimates that account for the driver's remaining hours of service and required rest breaks. That is the **Growth** and **Scale** packages, or any plan with the **Samsara Premium** add-on. On other plans both values are `null`. `Manual` is available on every plan.
  * **`Eta` is `null` when nothing is known.** The whole object is omitted as `null` when a stop has no planned, live, or manual estimate; a trip's `Eta` is `null` when it has no stops or its final stop has no estimate.
  * **Webhooks carry the field too.** `trip.changed` and `trip.status.changed` embed the full trip snapshot, so the payload now includes `Eta` on the trip and on each stop. Change detection is unchanged: an ETA update on its own does not fire a `trip.changed` event or appear in `data.diff.changes`.
  * There is no MCP tool change. The `trips_get_by_id` and `trips_search` tools return the updated response shape automatically.
</Update>

<Update label="September 4, 2026" description="Driver credits on the Public API">
  You can now credit a driver through the Public API. `POST /api/p/v{version}/credits/driver` posts a one-time credit to the driver's next settlement statement, completing the credits surface alongside the customer and carrier credits.

  ### What's New

  * **Create driver credit** — `POST /api/p/v{version}/credits/driver` (new). Takes a `Date`, a positive `Amount`, a settlement `Category`, a `Description`, the `DriverId`, and an optional `OwnerOperatorId`. Returns `201 Created` with the same body shape as `GET /api/p/v{version}/deductions/{id}`, with `Type` set to `Credit`.

  ### What Changes

  * This release is additive and backward compatible.
  * **A driver credit is not an accessorial.** It is the same record the driver profile page creates when a deduction is added with payment type Credit, so it takes an amount and a category rather than an accessorial type, rate, and quantity. Use `POST /accessorials/driver` to pay a driver more for a specific trip, and `POST /deductions/once` to take money from a driver.
  * **Scope.** The endpoint requires `deduction:create`, not `accessorial:create`. A token scoped only for accessorials receives `403`.
  * **`Amount` is the magnitude.** Zero or positive; values between 0 and 1 are rejected with `400`. This mirrors `POST /deductions/once`, which requires a negative amount.
  * **`Date` is normalised to its UTC calendar date.** A time and offset are accepted, and an offset that crosses midnight in UTC lands the credit on the following day's statement.
  * **Not idempotent.** There is no `ExternalId` on this route, so retrying a successful request creates a second credit. Confirm a timed-out request before resending it.
  * **`404` for an unknown or out-of-scope driver.** The response is identical whether the `DriverId` (or `OwnerOperatorId`) does not exist or belongs to a subsidiary your credentials cannot see.
  * **Reading credits back.** `POST /deductions/search` returns deductions only, so credits do not appear in its results. Read one by id with `GET /deductions/{id}`, or see it as a line item on the driver's finalized settlement statement. `Type` on the deduction response can now be `Credit` as well as `Deduction`.
  * There is no MCP tool for driver credits yet. The MCP catalog and the driver accessorial reference now point to this endpoint instead of describing a driver credit as unavailable.
</Update>

<Update label="September 2, 2026" description="Driver, customer, and carrier accessorials, plus customer and carrier credits, are now part of the published Public API, with matching MCP tools">
  The accessorial and credit endpoints are now part of the published Public API reference and the OpenAPI document, and the same operations are available as MCP tools. The endpoints themselves were already live; this release publishes them so integrators and agents can build against a documented contract.

  ### What's New

  * **List accessorial types** — `GET /api/p/v{version}/accessorials/accessorial-types`. The reference data every accessorial create needs: each type's id, name, whether it requires a stop, and the rate types and units of measure it allows. Pass `includeDeleted=true` to also return soft-deleted types.
  * **Create a driver accessorial** — `POST /api/p/v{version}/accessorials/driver`. Pays a driver an extra amount on a trip — detention, layover, an extra stop. `Rate` must be greater than zero.
  * **Create a customer accessorial** — `POST /api/p/v{version}/accessorials/customer`. Bills the customer an extra amount on a load. `Rate` must be greater than zero.
  * **Create a carrier accessorial** — `POST /api/p/v{version}/accessorials/carrier`. Pays a carrier an extra amount on a brokerage trip. `Rate` must be greater than zero.
  * **Post a credit** — `POST /api/p/v{version}/credits/customer` and `/credits/carrier`. `Rate` must be less than zero; send the signed negative amount.
  * **MCP tools** — `accessorials_list_types` (Read · `accessorial:read`), `accessorials_create_driver`, `accessorials_create_customer`, `accessorials_create_carrier`, `credits_create_customer`, and `credits_create_carrier` (Write · `accessorial:create`). Write tools follow the same visibility rules as the other write tools in the catalog.

  ### What Changes

  * All changes are additive and backward compatible. The paths are the ones production already served, so existing callers need no migration.
  * **New scopes** `accessorial:read` and `accessorial:create`, listed in the Authentication guide.
  * **`ExternalId` is an optional idempotency key** on every create. Retrying with the same key returns the original record; reusing a key against different money or a different trip, load, stop, driver, or type is refused with `409 Conflict`. A `503` means the write could not be confirmed and may already exist — retry the identical request when you supplied a key.
</Update>

<Update label="September 1, 2026" description="Odometer readings of zero are discarded on asset location and telemetry writes">
  ### What Changed?

  On `POST /api/p/v{version}/visibility/assets/{assetType}/{assetId}/locations` and `.../telemetry`, an `Odometer` of `0` is now treated as no reading and is discarded rather than stored. `OdometerReadingAt` is stored only alongside a surviving `Odometer` value; sent on its own, it is ignored.

  ### Why?

  A stored zero looked like a real reading and, in any calculation that takes the difference between two odometer values, inflated the result by the truck's entire lifetime mileage. Omitting the field, or sending `null`, already meant no reading; `0` now means the same thing.

  ### Who is affected?

  Only integrations that send `0` as a placeholder when they have no odometer. Those positions are still recorded; only the odometer value is dropped. Real readings are unaffected. `Odometer` remains in miles.
</Update>

<Update label="August 31, 2026" description="Document and tender webhook events are routed by Subsidiary">
  ### What Changed?

  A webhook subscription belongs to one Subsidiary, and it now receives an event only when the record the event is about belongs to that same Subsidiary. This already applied to `load.*` and `trip.*` events; it now applies to document and tender events too.

  | Event group                                                   | The Subsidiary the event is matched on                                        |
  | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
  | `load.*`                                                      | The load's invoicing Subsidiary                                               |
  | `trip.*`                                                      | The trip's tendering Subsidiary                                               |
  | `load.document.*`, `trip.document.*`                          | The Subsidiary of the load or trip the document is filed against              |
  | `driver.document.*`, `truck.document.*`, `trailer.document.*` | The Subsidiary of the driver, truck, or trailer the document is filed against |
  | `tender.*`                                                    | The tender's Subsidiary                                                       |

  `carrier.document.*` events are the one exception: a carrier carries no Subsidiary on the broker side, so they are delivered to every subscription in the tenant. Where a record's Subsidiary cannot be determined, the event is delivered to every subscription rather than withheld.

  ### Who is affected?

  * If your integration filtered document or tender events by Subsidiary itself, that filtering is now redundant but harmless. No action is required.
  * If it relied on receiving another Subsidiary's document or tender events on a Subsidiary-scoped subscription, it will stop receiving them. Subscribe from that Subsidiary instead.

  See [Which events reach your subscription](/en/api/reference/webhooks/overview#which-events-reach-your-subscription).
</Update>

<Update label="August 3, 2026" description="MCP server now speaks protocol revision 2026-07-28, with tool safety hints and clearer argument errors. Existing clients keep working.">
  The Alvys MCP server now implements MCP protocol revision **2026-07-28** — the largest revision of the protocol since it launched. Older revisions are still accepted, so **no action is required for existing clients**.

  <Note>
    **Nothing to configure.** MCP clients and servers negotiate the protocol revision automatically on connect. The server URL, the tool catalog, and the scopes are identical across revisions — the negotiated revision changes protocol mechanics, not what your agent can do.
  </Note>

  ## Protocol revision support

  | MCP revision | Supported | Notes                                                                              |
  | ------------ | --------- | ---------------------------------------------------------------------------------- |
  | `2026-07-28` | Yes       | Current. Sessionless — the revision travels on each request.                       |
  | `2025-11-25` | Yes       | Negotiated via the `initialize` handshake.                                         |
  | `2025-06-18` | Yes       | Negotiated via the `initialize` handshake.                                         |
  | `2025-03-26` | Yes       | Negotiated via the `initialize` handshake.                                         |
  | `2024-11-05` | Yes       | Negotiated via the `initialize` handshake. Deprecated by MCP, still accepted here. |

  If a client fails to connect, the protocol revision is very unlikely to be the cause — check authentication and organization selection first.

  ## Added

  * **Tool safety hints.** Every tool now advertises MCP `annotations` — `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` — derived from the same Read/Write/Destructive classification the server enforces, so the advertised hint always matches the enforced policy. Clients use these to decide when to ask a human before running a tool. The beta surface is read-only, so every currently visible tool is marked `readOnlyHint: true` and `destructiveHint: false`; the hints matter once write tools are enabled, and are in place ahead of that.
  * **Server usage guidance.** The server publishes natural-language `instructions` describing how to use the surface — that tool visibility is fixed per deployment, that unknown parameters are rejected rather than ignored, and that searches are 0-based and paginated. Clients that surface server instructions will pass this to the model automatically.

  ## Changed

  * **Stable tool ordering.** `tools/list` and `prompts/list` return entries sorted by name, so the catalog no longer varies between requests. This makes client-side caching reliable and improves prompt-cache hit rates when the tool list is included in model context.
  * **`GET` and `DELETE` on `/mcp` return `405 Method Not Allowed`.** These were the legacy session verbs — `GET` opened a server-to-client stream and `DELETE` ended a session. Revision `2026-07-28` is sessionless, so neither is offered. They now answer `405` (a capability signal) rather than `400` or `401`, so a client probing for session support gets an unambiguous answer without a token.
  * **`offline_access` is no longer advertised in `scopes_supported`.** A refresh token is not a requirement of this resource, so the protected-resource metadata no longer lists it. Clients that want a refresh token still request it from the authorization server as before. This shortens the consent screen.

  ## Fixed

  * **Argument errors are actionable instead of generic.** A missing required argument, or one of the wrong type (for example `page: "not-an-int"`), previously returned `An error occurred.` — indistinguishable from a server fault. These now return a structured `[invalid_params]` error naming the parameter, so an agent can correct the call and retry. This covers both tools and prompts.
  * **Prompt argument errors.** `prompts/get` with a missing required argument returned the same generic error. It now returns `invalid_params` naming the argument.
  * **Malformed requests return a proper error body.** A malformed JSON-RPC request now returns `400` with a JSON-RPC error rather than an empty `500`.

  <Tip>
    Using an official MCP client (Claude.ai, Claude Desktop, Cursor, `mcp-remote`)? You do not need to do anything — revision negotiation and the new request headers are handled for you. Only hand-rolled HTTP clients that pin a protocol revision need to be aware of the table above.
  </Tip>
</Update>

<Update label="July 28, 2026" description="Unknown Public API paths return 404, not 401">
  ### What Changed?

  Requests to a Public API path that does not exist — for example a typo'd controller name or a retired endpoint — return **404 Not Found**. They do **not** return **401 Unauthorized**.

  **401 Unauthorized** continues to mean the access token is missing or invalid. See [Response Codes](/en/api/guides/response-codes).

  ### What Should I Do?

  No client changes are required if you already treat unknown paths as 404. If you recently treated unexpected 401s on bad URLs as credential failures, verify the request path against the [API reference](/en/api/reference/authentication) first.
</Update>

<Update label="July 24, 2026" description="MCP tool catalog: stop-status write split into three tools, new trucks_events_search, discovery and authorization fixes">
  ## MCP tools

  * **Added** `trips_record_arrival` (Write · `stop:update`) — record an arrival event on a trip stop. Wraps `PUT /api/p/v1/trips/{tripId}/stops/{stopId}/arrival`.
  * **Added** `trips_record_departure` (Write · `stop:update`) — record a departure event on a trip stop. The server enforces that an arrival must exist first. Wraps `PUT /api/p/v1/trips/{tripId}/stops/{stopId}/departure`.
  * **Added** `trips_update_stop_appointment` (Write · `stop:update`) — update the appointment (or FCFS window) on a trip stop. `scheduleType` must be `APPT` or `FCFS`; `appointmentDate` is required when `scheduleType=APPT`, and `windowBegin` is required when `scheduleType=FCFS`. Wraps `PUT /api/p/v1/trips/{tripId}/stops/{stopId}/appointment`.
  * **Removed** `trips_update_stop_status` — the single combined tool is replaced by the three purpose-built tools above. Callers should migrate to the specific tool for the action they want to take.
  * **Added** `trucks_events_search` (Read · `truck:read`) — fetch truck events (maintenance, schedule, availability) for one or more trucks over a date range, mirroring `drivers_events_search`. Pass `truckIds` (Alvys truck ids, not unit numbers) and a `startDate`; `endDate` is optional. Returns a flat event list, not paged — an empty list means no events in the range.

  ## Fixed

  * **Browser-based MCP clients can complete discovery.** The protected-resource metadata endpoints and `/mcp` now answer cross-origin requests and OPTIONS preflights, so a client that runs guided OAuth in a browser (for example MCP Inspector) can finish the handshake instead of failing on preflight.
  * **Consistent authorization for settlement-statement-only tokens.** A user token carrying only settlement-statement permissions no longer passes the `carriers_*` and `drivers_*` read tools at the MCP edge only to be rejected by the Public API downstream. Those tools now require the same carrier and driver read permissions their underlying endpoints enforce, so both sides agree on the outcome.

  <Note>
    The underlying Public API endpoints are unchanged — what moved is the MCP tool catalog and the MCP server's own authorization and discovery behavior.
  </Note>
</Update>

<Update label="July 23, 2026" description="MCP: strict arguments, 0-based paging, Public-API-aligned argument shapes">
  The Alvys MCP server is now stricter about tool arguments and aligns paging and filter shapes with the Public API, so calls port 1:1 between the two. Two of these are **breaking** for anyone who scripted against the previous MCP facade.

  <Warning>
    **Breaking — paging is now 0-based.** Every search tool's `page` parameter defaults to `0` and is passed through to the Public API unchanged. If your agent or script currently sends `page=1` to fetch the first page, it now fetches the **second** page. Update callers to start at `page=0`. `page=-1` (or any negative value) is rejected with `[invalid_params]`.
  </Warning>

  <Warning>
    **Breaking — unknown parameters are rejected.** The MCP SDK previously bound arguments by name and silently discarded unknown keys, so a misspelled or unsupported filter (e.g. `customers_search name="Colortech"`) returned confident, wrong results — the full unfiltered list — instead of an error. Every tool now validates argument keys against its advertised input schema before running, including nested keys inside date ranges and array elements, and returns a structured `[invalid_params]` error that names the rejected keys and the valid parameter list. Migrate callers that relied on unknown keys being silently ignored; the error message tells you exactly which keys to drop or rename.
  </Warning>

  ## What changed

  * **0-based paging on every search tool.** `page` defaults to `0` and responses echo the request `page` back so agents can drive their own pager. `pageSize` still defaults to `25` (max `100`).
  * **Strict argument validation.** Unknown keys — at the top level or nested inside a date-range object or array element — return `[invalid_params]` naming the offending keys and the tool's full valid-parameter list.
  * **Array filters, matching the Public API.** Filters that map to `/search` array fields are now declared as arrays on the tool so you can pass one or many values in a single call.
  * **Structured date-range objects.** Date-range filters are now single `{ start, end }` objects using the same parameter names the Public API uses. An `end` without a `start` is rejected up front. `invoices_search` still requires at least one non-date filter alongside a range (matching the Public API); `trips_search` accepts a range as its only filter.

  ## Tools affected

  | Tool                       | Parameters changed                                                                                                                                                                                                                                                                               |
  | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `customers_search`         | `status` (string) → `statuses` (array); `createdFrom` / `createdTo` → `createdDateRange` `{ start, end }`; `page` default `1` → `0`                                                                                                                                                              |
  | `carriers_search`          | `status` (string) → `status` (array); `mcNumber` → `mcNumbers` (array); `dotNumber` → `dotNumbers` (array); `page` default `1` → `0`                                                                                                                                                             |
  | `loads_search`             | `status` (string) → `status` (array); `loadNumber` → `loadNumbers` (array, max 50); `orderNumber` → `orderNumbers` (array, max 50); `page` default `1` → `0`                                                                                                                                     |
  | `trips_search`             | `status` (string) → `status` (array); `loadNumber` → `loadNumbers` (array, max 50); `tripNumber` → `tripNumbers` (array, max 50); `pickupFrom` / `pickupTo` → `pickupDateRange` `{ start, end }`; `deliveryFrom` / `deliveryTo` → `deliveryDateRange` `{ start, end }`; `page` default `1` → `0` |
  | `drivers_search`           | `status` (string) → `status` (array); `page` default `1` → `0`                                                                                                                                                                                                                                   |
  | `drivers_events_search`    | `driverId` (single) → `driverIds` (array; pass several for a fleet-wide query)                                                                                                                                                                                                                   |
  | `trucks_search`            | `unitNumber` → `truckNumber`; `status` (string) → `status` (array); `page` default `1` → `0`                                                                                                                                                                                                     |
  | `trailers_search`          | `unitNumber` → `trailerNumber`; `status` (string) → `status` (array); `page` default `1` → `0`                                                                                                                                                                                                   |
  | `invoices_search`          | `status` (string) → `status` (array); `loadNumber` → `loadNumbers` (array, max 50); `orderNumber` → `orderNumbers` (array, max 50); `invoicedFrom` / `invoicedTo` → `invoicedDateRange` `{ start, end }`; `paidFrom` / `paidTo` → `paidDateRange` `{ start, end }`; `page` default `1` → `0`     |
  | `fuel_transactions_search` | `truckId` → `truckNumber`; `from` / `to` → `transactionRange` `{ start, end }`; `page` default `1` → `0`                                                                                                                                                                                         |
  | `tenders_search`           | `status` (string) → `status` (array); `page` default `1` → `0`                                                                                                                                                                                                                                   |
  | `deductions_search`        | `page` default `1` → `0`                                                                                                                                                                                                                                                                         |

  ## Migration

  1. **Rename any renamed parameters.** In particular: `unitNumber` → `truckNumber` / `trailerNumber` (on `trucks_search` / `trailers_search`), `truckId` → `truckNumber` (on `fuel_transactions_search`), and singular `mcNumber` / `dotNumber` / `loadNumber` / `orderNumber` / `tripNumber` / `driverId` → their plural array forms on the search tools listed above.
  2. **Wrap single-value filters in an array.** `status: "Active"` → `status: ["Active"]`, `mcNumber: "12345"` → `mcNumbers: ["12345"]`, and so on.
  3. **Collapse date pairs into `{ start, end }` objects** using the new parameter names (`createdDateRange`, `pickupDateRange`, `deliveryDateRange`, `invoicedDateRange`, `paidDateRange`, `transactionRange`).
  4. **Shift `page` down by one.** `page=1` (old first page) → `page=0`. If your code computes `page` from a UI index, subtract `1` at the call site.
  5. **Drop any unrecognized keys.** If a call now returns `[invalid_params]`, the error message lists both the rejected keys and the valid parameter set — align on that list.

  Guided prompts (`carrier_onboarding_v1`, `settlement_reconciliation_v1`) have been updated to reference the new parameter names. Read tool coverage, permissions, and endpoints are otherwise unchanged.

  See [Available MCP Tools](/en/api/guides/available-mcp-tools#conventions) for the full conventions and an example `[invalid_params]` payload.
</Update>

<Update label="July 23, 2026" description="Subsidiary-scoped API credentials">
  API credentials can now be **scoped to specific subsidiaries**. A scoped credential's access token is limited to the data of the subsidiaries it was issued for — across every read *and* write endpoint of the Public API, including webhooks.

  ### What changed

  Previously, every API credential had tenant-wide access: any token could read and modify data belonging to any subsidiary in your company. Subsidiary selections made during credential creation were stored but not enforced.

  Now, when a credential is created with one or more subsidiaries selected, that scope is embedded in the access token and enforced on every request.

  ### How token scope works

  When you request an access token, Alvys adds a new claim to the token:

  ```text theme={null}
  https://alvys.com/claims/app/subsidiaries
  ```

  The claim is added automatically when the token is issued and restricts the credential's access to only the subsidiaries it has been granted. It is evaluated on every API request, with no additional configuration required.

  **Scope rules:**

  | Your credential setup                     | Claim in the token    | What the token can do                      |
  | ----------------------------------------- | --------------------- | ------------------------------------------ |
  | Scoped to specific subsidiaries (up to 3) | The subsidiaries' IDs | Only see and edit those subsidiaries' data |
  | **All subsidiaries** selected             | `*`                   | Access every subsidiary in your company    |
  | No subsidiaries selected                  | `*`                   | Access every subsidiary in your company    |
  | Credentials created before this release   | `*`                   | No change — same access as before          |

  ### What a scoped token can see and do

  **Reads** — search and list endpoints return only records belonging to the credential's subsidiaries, plus records that have no subsidiary assignment (tenant-level data). Get-by-ID requests for a record outside the scope return `404 Not Found`, exactly as if the record did not exist.

  **Writes** — a scoped token cannot create, update, or delete records outside its subsidiaries. Out-of-scope writes return `404 Not Found` — the same response as a nonexistent record, so a scoped credential cannot probe for the existence of another subsidiary's data. This covers load updates, notes and documents, trip assignment/dispatch, stop arrivals/departures/appointments, check calls, customer updates and deletes, deductions, invoice payments and financing, and asset document uploads.

  **Webhooks** — webhook subscriptions are subsidiary-bound. A scoped credential can only create, list, manage, and read delivery logs for webhooks belonging to its own subsidiaries, and can only subscribe to events of those subsidiaries.

  ### Scoped entities

  Subsidiary scope applies to: Loads, Trips (including stops and check calls), Invoices, Customers, Deductions, Fuel transactions, Tolls, Drivers, Trucks, Trailers, Driver Settlement Statements, Carrier Settlement Statements, and Webhooks. Carriers and Tenders are not subsidiary-scoped.

  ### Response code changes

  One response code changed as part of this work: `POST /api/p/v{version}/trips/{tripId}/assign` with an **unknown trip ID** now returns `404 Not Found` (previously `400 Bad Request`). This aligns assign with the other trip endpoints and is required for the no-existence-leak guarantee above. No other status codes changed.

  ### Backward compatibility

  Existing credentials and integrations are unaffected. Tokens issued from credentials without a subsidiary selection — including all credentials created before this release — remain tenant-wide. Scoping only applies when you explicitly select subsidiaries on a credential.

  ### Creating a scoped credential

  1. Navigate to **Settings → API Keys**
  2. Click **New credential**
  3. Select **permissions** and choose the **subsidiaries** the credential may access — up to 3 specific subsidiaries, or **All subsidiaries** for tenant-wide access
  4. Click **Generate** and store the Client ID and Secret securely

  Tokens requested with these credentials via the standard OAuth 2.0 Client Credentials flow will carry the subsidiary scope automatically.
</Update>

<Update label="July 22, 2026" description="Escrow transaction type on driver settlement statements, user-token read access">
  ## Public API + MCP: user-token access to read endpoints

  * **Fixed** interactive (user-PKCE) tokens failing `load:read`, `stop:read`, `trip:read`, `visibility:read`, and `carrier:read` on the Public API and MCP for otherwise-privileged users. These endpoints were checking for internal permissions (`ViewLoads`, base `Carrier`) that no real user record carries. Any authenticated tenant user now passes the user-token half of those read checks, matching the in-app role gating. Machine-to-machine tokens are unchanged — they still require the corresponding OAuth scope. Every write endpoint keeps its real permission check.

  ## `POST /api/p/v{version}/driver-settlement-statements/search` and `GET /api/p/v{version}/driver-settlement-statements/{number}`

  * **Added** `TransactionType` on the response `LineItems[]`. Populated only when `Category` is `Escrow`; `null` for every other line item.
    * `"Deposit"` — money moved **into** the driver's escrow account. Appears as a negative `Amount`.
    * `"Withdrawal"` — money moved **out** of the escrow account. Appears as a positive `Amount`.
  * Additive and non-breaking. Existing consumers see one new nullable field. Totals and every other field are unchanged. This is the only Public API surface that returns escrow line items today; `POST /api/p/v{version}/deductions/search` does not.
</Update>

<Update label="July 13, 2026" description="Carrier payment trip status fix">
  ## `POST /api/p/v{version}/invoices/carrier-payments`

  * **Removed** `MarkAsPaid` from the request body. The field only existed to force a `Paid` trip status, which Alvys does not use. Existing callers that still send `markAsPaid` are unaffected — the field is ignored.
  * **Fixed** trip status in the response: when recorded payments fully cover the carrier payable, the trip now transitions to **`Completed`** instead of **`Paid`**. Partial payments leave the trip status unchanged.
  * The response `Status` field reflects the trip's current status after the payment is applied.

  ## MCP: `invoices_record_carrier_payment`

  * **Removed** the `markAsPaid` parameter (same behavior as the Public API change above).

  <Note>
    Historical trips may still carry a `Paid` status from before this fix. A one-time data backfill is planned separately.
  </Note>
</Update>

<Update label="July 13, 2026" description="Webhook Change Diffs: See Exactly What Changed on Load & Trip Events">
  Load & trip webhooks can now tell you exactly what changed. `load.changed` and `trip.changed` events carry an optional `data.diff` — a list of domain-named change kinds (e.g. `StatusChanged`, `RateChanged`, `AppointmentChanged`) and, opt-in, the previous values of every changed field. React to the exact change that matters and apply just the delta, instead of diffing full snapshots yourself.

  **What's New?**

  `load.changed` and `trip.changed` webhooks now carry an optional `data.diff` node that tells you **what changed** on the record — and, if you opt in, **what the value was before**. You no longer have to diff successive snapshots yourself to react to a change.

  **What Changed?**

  Previously, `load.changed` and `trip.changed` delivered only the full current snapshot in `data`. Consumers had to cache the prior payload and compute their own delta to know whether a change was relevant. Each event can now include `data.diff` with two independent parts:

  * `data.diff.changes` — an array of domain-named change kinds (e.g. `StatusChanged`, `RateChanged`, `StopReordered`, `AppointmentChanged`). Delivered to every subscriber whenever something meaningful changed. Sub-entity changes carry a `target` — `{ "type": "Stop" | "Field", "id": "<stableId>" }`.
  * `data.diff.previousAttributes` — the previous value of every changed field visible on the public response, keyed 1:1 with the snapshot. Keyed collections (stops, references, charge lines) diff by stable `id`. **Opt-in per subscription.**

  **Event Envelope**

  ```json theme={null}
  {
    "type": "load.changed",
    "data": {
      "load": { "...": "full current snapshot" },
      "diff": {
        "changes": [
          { "kind": "StatusChanged" },
          { "kind": "AppointmentChanged", "target": { "type": "Stop", "id": "abc123" } }
        ],
        "previousAttributes": { "...": "previous values (opt-in)" }
      }
    }
  }
  ```

  `data.diff` is present only on `load.changed` / `trip.changed` — **never** on `*.status.changed`, and it is **omitted on the first (create) event** where there is no prior state.

  <Warning>
    **Treat `changes` as a filtering hint only.** The vocabulary is curated and may grow — always ignore change kinds you don't recognize, and never assume the snapshot is unchanged just because a kind is missing.
  </Warning>

  **How to Enable Previous Values**

  `data.diff.changes` is delivered automatically. `data.diff.previousAttributes` is opt-in:

  * **Dashboard:** turn on **Include previous values** on the webhook.
    <img alt="" />
  * **API:** set `IncludePreviousAttributes: true` when creating or updating the subscription (defaults to `false`).

  **Endpoints Affected**

  `POST /p/v1.0/webhooks` and `PUT /p/v1.0/webhooks/{id}` accept the new `IncludePreviousAttributes` flag. Event delivery on existing `load.changed` / `trip.changed` subscriptions is backward compatible — `data.diff` is additive.

  **Why?**

  State-mirroring integrators can now apply just the delta instead of re-importing the whole record on every event — lower processing cost, cleaner audit trails, and the ability to filter on the exact business change that matters.
</Update>

<Update label="July 10, 2026" description="Check Calls Now Available in the Public API">
  ### What's New?

  Check calls — driver status updates recorded against a trip — can now be read and logged through the Public API. Tracking platforms and visibility providers can push location updates into Alvys and read back the full check-call history without manual entry.

  ### What Changed?

  Previously, check calls were only visible and editable inside the Alvys platform.

  Now, the Public API includes two new endpoints:

  ```http theme={null}
  GET  /api/p/v{version}/trips/{tripId}/check-calls
  POST /api/p/v{version}/trips/{tripId}/check-calls
  ```

  * **List trip check calls** — returns every check call recorded on the trip.
  * **Log a trip check call** — records a new check call with a required `description` plus optional `activity`, `driverId`, structured `location` (coordinates included), and reefer `setpointTemperature` / `returnTemperature`.

  ### Response Body Includes

  * Core: `Id`, `LoadNumber`, `TripId`, `TripNumber`, `Description`
  * Status: `Activity`, `ResponseType`, `DriverName`
  * Location: structured address with coordinates
  * Reefer: `SetpointTemperature`, `ReturnTemperature`
  * Audit: `CreatedAt`, `CreatedBy`

  Unset optional fields are returned as `null` (not empty strings), so consumers can distinguish "not provided" from "explicitly empty".

  ### Why?

  Check calls are the heartbeat of in-transit visibility. Exposing them via the Public API lets tracking integrations write status updates directly to the trip and lets downstream systems consume a single, consistent history.
</Update>

<Update label="July 6, 2026" description="New Public API Settlement Statement Endpoints">
  We've added Public API support for finalized driver, owner-operator, and carrier settlement statements. Partners can now pull statement headers, totals, and full line-item detail programmatically — making it easier to build custom reporting and reconciliation workflows without manually exporting the "Statements List and Items" report.

  ### What's New

  * Search finalized driver and owner-operator settlement statements with paging, line items, and totals.
  * Search finalized carrier settlement statements with paging, per-trip breakdowns, line items, payments, and totals.
  * Fetch a single driver, owner-operator, or carrier settlement statement by statement number.
  * Filter statement searches by statement-date range, driver type, carrier, and subsidiary.

  ### What Changes

  * This release is additive and backward compatible.
  * Only finalized statements from the **Statements** tab are returned. Open and Draft statements are excluded.
  * Driver settlement statements may include `Failed` statements; these are identified through the `Status` field.
  * Carrier settlement statements exclude `Failed` and `Deleted` statements.
  * `StatementDateRange` is required for search requests. Both `Start` and `End` must be provided and are interpreted as inclusive UTC calendar days.
  * The driver `DriverType` filter accepts `COMPANY`, `OWNER_OPERATOR`, or `CONTRACTOR`, case-insensitive, matching the `/drivers` endpoint.
  * Monetary values are returned as `{ Amount, Currency }` objects.
  * Access uses existing scopes:
    * `driver:read` for driver settlement statements
    * `carrier:read` for carrier settlement statements

  ### Endpoints Affected

  * `POST /p/v1.0/driver-settlement-statements/search` (new) — search finalized driver and owner-operator settlement statements.
  * `GET /p/v1.0/driver-settlement-statements/{number}` (new) — fetch a single driver or owner-operator settlement statement by statement number.
  * `POST /p/v1.0/carrier-settlement-statements/search` (new) — search finalized carrier settlement statements.
  * `GET /p/v1.0/carrier-settlement-statements/{number}` (new) — fetch a single carrier settlement statement by statement number.
</Update>

<Update label="June 19, 2026" description="New Public API Endpoints for Trips and Carriers">
  We've added Public API support for assigning carriers to trips, dispatching trips, searching trips by assigned equipment, updating carrier status, and reading carrier contacts — so partners can run more of the dispatch and carrier workflow programmatically.

  ## What's New

  * **Assign a carrier to a trip** — assign a carrier, and optionally a driver, truck, and trailer, to a trip.
  * **Dispatch a trip** — dispatch a covered trip so dispatch can be triggered from your own workflow.
  * **Filter trips by driver, truck, or trailer** — narrow trip search to a specific driver or piece of equipment.
  * **Update a carrier's status** — set a carrier's status (e.g. Active, Do Not Load) to keep records in sync with your compliance and vetting systems.
  * **Carrier contacts in the carrier response** — read carrier contact details without extra calls.

  ## What Changes

  * All changes are additive and backward compatible.
  * The new trip filters (`driverId`, `truckId`, `trailerId`) are optional. Each is valid on its own or alongside existing search parameters; `driverId` matches primary, secondary, and owner-operator assignments.
  * Carrier responses now include a `Contacts` collection (name, email, phone, mobile, title, and a primary-contact flag) on both the get-by-id and search responses.
  * Assigning a carrier requires `carrierId` and `dispatcherId`; `driver2Id` cannot be sent without `driver1Id`. Assets are referenced by id — resolve them via their search endpoints first.
  * Dispatch requires the trip to be **Covered** (carrier and assets assigned); otherwise the request is rejected.
  * Updating carrier status supports optimistic concurrency via the `If-Match` header and returns a fresh `ETag` for the next update.

  ## Endpoints Affected

  * `POST /p/v1.0/trips/{tripId}/assign` *(new)* — assign a carrier and optional assets; returns the updated trip.
  * `POST /p/v1.0/trips/{tripId}/dispatch` *(new)* — dispatch a covered trip; returns the updated trip.
  * `POST /p/v1.0/trips/search` *(updated)* — now accepts `driverId`, `truckId`, and `trailerId` filters.
  * `PATCH /p/v1.0/carriers/{carrierId}/status` *(new)* — update a carrier's status; returns `204 No Content` with a fresh `ETag`.
  * `GET /p/v1.0/carriers/{id}` and `POST /p/v1.0/carriers/search` *(updated)* — responses now include `Contacts`.

  <br />
</Update>

<Update label="June 19, 2026" description="Tender Endpoints Now Available in the Public API">
  **Release Date:** November 2025 (tender ingest), June 19, 2026 (public availability)

  ### What's New?

  The Public API now includes a full set of **Tender** endpoints, covering the complete tender lifecycle — create, update, cancel, search, and respond (accept / reject). Originally introduced as an EDI-focused add-on, the Tenders API is now part of the standard public Swagger group and available to all Public API consumers.

  ### What Changed?

  Previously, tender operations were only available through EDI integrations or as a restricted add-on.

  Now, the Public API includes:

  ```http theme={null}
  POST /api/p/v{version}/tenders/search
  GET  /api/p/v{version}/tenders/{tenderId}
  POST /api/p/v{version}/tenders
  POST /api/p/v{version}/tenders/update
  POST /api/p/v{version}/tenders/cancel
  POST /api/p/v{version}/tenders/{tenderId}/accept
  POST /api/p/v{version}/tenders/{tenderId}/accept-updates
  POST /api/p/v{version}/tenders/{tenderId}/accept-cancel
  POST /api/p/v{version}/tenders/{tenderId}/reject
  ```

  * **Search & get** — query tenders and retrieve full tender detail.
  * **Create / update / cancel** — ingest load tenders (including EDI 204-originated tenders) programmatically.
  * **Accept / reject** — respond to a tender; accepting creates the corresponding load in Alvys.
  * **Accept updates / accept cancellation** — apply an inbound tender update or cancellation to the linked load.

  Pairs with the tender lifecycle **webhook events** (`tender.created`, `tender.change.created`, `tender.cancelled`, and related events) — subscribe to webhooks for real-time notification, then act on the tender via these endpoints.

  ### Why?

  Tendering is the front door of the load lifecycle. Exposing it in the Public API lets brokers, shippers, and integration platforms route freight into Alvys — and respond to it — without requiring a traditional EDI pipeline.
</Update>

<Update label="June 3, 2026" description="Update a Load's Order Number via the Public API">
  ## What's New?

  We've added a `PATCH /p/v1.0/loads/{loadNumber}` endpoint to the Public API. Partners running an external system of record (e.g. AS400) can now write their generated identifier back onto an Alvys load as the **Order Number (Shipment ID)** — programmatically, with no human in the loop.

  The endpoint is a **partial update**: only the fields you send are modified, leaving everything else untouched. It's shaped so additional writable load fields can be added later without breaking the contract. In this first iteration, `orderNumber` is the only writable field.

  ## What Changed?

  Previously, a load's Order Number could only be set in the UI — there was no public write path. Now you can update it directly:

  ```bash theme={null}
  curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1.0/loads/3039979' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: "8DBAC1F2E3..."' \
  --data-raw '{
    "orderNumber": "2026-00471"
  }'
  ```

  A successful call returns `200 OK` with the updated load representation and a fresh `ETag`.

  ## Preventing Accidental Overwrites

  To help prevent one update from accidentally overwriting another, this endpoint requires the latest record version when making changes.

  When you retrieve or update a record, the response includes an `ETag`. Send that value in the `If-Match` request header when making your next update.

  | Scenario                                   | Response                    |
  | ------------------------------------------ | --------------------------- |
  | Missing `If-Match` header                  | `428 Precondition Required` |
  | Record changed since you last retrieved it | `412 Precondition Failed`   |
  | Update succeeds                            | `200 OK`                    |

  If you receive `412 Precondition Failed`, retrieve the record again to get the latest `ETag`, then retry the update.

  After a successful update, the new `ETag` is returned in both the response body and the `ETag` response header, so you can use it for the next update without making another `GET` request.

  ## Validation & History

  * A blank or empty Order Number is rejected with `400 Bad Request` — the same rule as the internal Order Number update.
  * Every change is written to the load's history (the same audit trail as the UI path).
  * EDI-originated loads are rejected. The Order Number on an EDI load is locked to the value received on the inbound tender and cannot be changed through this endpoint.

  ## Endpoints Affected

  `PATCH /p/v1.0/loads/{loadNumber}` is new and updates a load's Order Number.

  No request or response shapes were changed for existing endpoints. This update is fully backward compatible.

  ## Response Codes

  | Code                        | Meaning                                                        |
  | --------------------------- | -------------------------------------------------------------- |
  | `200 OK`                    | Order Number updated; updated load returned with a fresh ETag. |
  | `400 Bad Request`           | Invalid request (e.g. blank Order Number).                     |
  | `401 / 403`                 | Authentication or permission failure.                          |
  | `404 Not Found`             | Load not found within the caller's company.                    |
  | `409 Conflict`              | Conflicting state.                                             |
  | `412 Precondition Failed`   | Stale ETag.                                                    |
  | `428 Precondition Required` | `If-Match` header missing.                                     |

  <br />
</Update>

<Update label="June 3, 2026" description="Remote MCP Server for the Alvys Public API">
  **Release Date:** June 3, 2026 (server), June 18, 2026 (prompts & write tools), July 3, 2026 (user sign-in)

  ### What's New?

  Alvys now ships a remote **Model Context Protocol (MCP) server** that exposes the Public API to AI agents — Claude, Cursor, and your own custom agents. Instead of hand-wiring HTTP calls, an agent connects to one governed endpoint and discovers Alvys tools automatically.

  ### What Changed?

  Previously, integrating an AI agent with Alvys meant holding a raw Public API token and calling REST endpoints directly.

  Now, agents connect to the Alvys MCP server and get:

  * **Read tools** across core entities — loads, trips, carriers, customers, drivers, trucks, trailers, invoices, deductions, fuel transactions, tenders, visibility history, and documents.
  * **Write tools** (opt-in) — create/accept/reject tenders, record carrier and customer payments, record financing, assign and dispatch trips, update carrier status, upload documents, record stop arrivals/departures, and update stop appointments.
  * **Curated prompts (v1)** — guided multi-step workflows such as `find_and_cover_load`, `dispatch_driver`, `carrier_onboarding`, `settlement_reconciliation`, and `track_shipment`.

  ### Authentication

  Two ways to connect:

  * **Machine-to-machine** — Auth0 client-credentials tokens, same as the Public API.
  * **User sign-in** — OAuth 2.1 with PKCE per the MCP specification, including protected-resource discovery (RFC 9728) and resource indicators (RFC 8707), so interactive clients like Claude can sign in as a user.

  ### Governance & Safety

  * Tenant isolation is enforced from the token — never from the request body.
  * Every tool is classified **Read / Write / Destructive** with runtime gates; write tools are disabled unless explicitly enabled.
  * Each tool requires a matching granular API permission (e.g. `tender:read`, `invoice:update`).
  * All calls are rate-limited, size-capped, and audit-logged.

  ### Why?

  AI agents are becoming a first-class way to operate a TMS. The MCP server gives them a discoverable, audited, tenant-isolated surface — one choke point with tool-level authorization instead of raw API tokens spread across agents.
</Update>

<Update label="May 29, 2026" description="Public API: Customer write endpoints (create, update, delete)">
  The Public API now supports **writes** on the `Customer` resource. Partners can create new customers, update existing ones, and soft-delete them directly through the API — no more read-only ceiling.

  This release is **purely additive**. The existing `GET` reads and `POST /api/p/v1.0/customers/search` are unchanged.

  ## What's new

  | Endpoint                            | Action                           | Returns                         | Permission        |
  | ----------------------------------- | -------------------------------- | ------------------------------- | ----------------- |
  | `POST /api/p/v1.0/customers`        | Create                           | `201` + `CustomerWriteResponse` | `customer:create` |
  | `PATCH /api/p/v1.0/customers/{id}`  | Update (partial, RFC 7396 merge) | `200` + `CustomerWriteResponse` | `customer:update` |
  | `DELETE /api/p/v1.0/customers/{id}` | Soft-delete                      | `204`                           | `customer:delete` |

  Applies to both business-company types: `Customer` and `Broker/3PL`.

  ## Why it matters

  * **Real-time CRM sync** — push customer records straight into Alvys from your TMS, ERP, or CRM instead of entering them by hand.
  * **Conflict-safe edits** — `ETag` / `If-Match` optimistic concurrency means two concurrent edits never silently overwrite each other.

  ## Create

  ```http theme={null}
  POST /api/p/v1.0/customers
  Authorization: Bearer <token with customer:create>
  Content-Type: application/json

  {
    "Name": "Acme Logistics",
    "Type": "Customer",
    "CompanyNumber": "ACME-1",
    "Status": "Active",
    "BillingAddress": { "Street": "1 Main", "City": "City", "State": "NY", "Zip": "10001" },
    "Email": ["billing@acme.example"],
    "Phone": ["555-1234"]
  }
  ```

  Returns `201 Created` with a `Response` body. The `ETag` is returned both in the body and on the response header. `Name` and `Type` are required on create; `Type` must be `Customer` or `Broker/3PL`.

  ## Update (partial)

  ```http theme={null}
  PATCH /api/p/v1.0/customers/{id}
  Authorization: Bearer <token with customer:update>
  If-Match: "etag-from-prior-read"

  { "Status": "Inactive" }
  ```

  Returns `200 OK`. `PATCH` is a true partial update (RFC 7396 JSON Merge Patch) — omit any field to leave it unchanged.

  ## Delete

  ```http theme={null}
  DELETE /api/p/v1.0/customers/{id}
  Authorization: Bearer <token with customer:delete>
  If-Match: "etag-from-prior-read"
  ```

  Returns `204 No Content`. The record moves to `Status: Inactive` (soft-delete) and its `CompanyNumber` stays reserved to prevent reuse.

  ## Supported writable fields

  The following fields can be created or updated through the Customer write endpoints:

  `Name`, `Type`, `CompanyNumber`, `Status`, `BillingAddress`, `Email`, `Phone`, `Fax`, `ExternalId`.

  All other fields are read-only or managed by Alvys, including `SalesAgentId`, `Contacts`, `Notes`, `InvoicingInformation`, `Id`, `DateCreated`, and `DateModified`.

  Unsupported or read-only fields included in the request body are ignored.

  ## Field validation

  | Field           | Validation                                                  |
  | --------------- | ----------------------------------------------------------- |
  | `Name`          | Required. Must not be blank. Maximum 200 characters.        |
  | `CompanyNumber` | Maximum 32 characters. Placeholder values are not accepted. |
  | `ExternalId`    | Maximum 100 characters.                                     |
  | `Status`        | Must be `Active` or `Inactive`.                             |

  ## Request behavior

  `PATCH` and `DELETE` require the `If-Match` header.

  If `If-Match` is missing, the API returns `428 Precondition Required`. If the `ETag` is outdated, the API returns `412 Precondition Failed`. Retrieve the customer again to get the latest `ETag`, then retry.

  Duplicate `CompanyNumber`, `ExternalId`, or `Name` + billing ZIP code returns `409 Conflict`. The response identifies the conflicting field and existing `customerId`.

  If customer writes are temporarily unavailable, the API returns `503 Service Unavailable` with `Retry-After: 3600` and the `EndpointDisabled` problem type. Customer read endpoints remain available.

  ## Write and read responses

  Successful `POST` and `PATCH` requests return `CustomerWriteResponse`.

  The write response includes:

  `Id`, `ETag`, `Name`, `CompanyNumber`, `Type`, `Status`, `BillingAddress`, `Email`, `Phone`, `Fax`, `DateCreated`, `DateModified`, `InvoicingInformation`, `ExternalId`.

  For write responses, `ETag` is returned in both the response body and response header.

  Existing `GET` and search endpoints are unchanged. They continue to return `CustomerResponse`, with `Status` as `Active` or `Inactive` and `ETag` in the response header only.

  ## Access

  Use your existing Client Credentials and add the scopes you need:

  * `customer:read` — `GET` / `search`
  * `customer:create` — `POST`
  * `customer:update` — `PATCH`
  * `customer:delete` — `DELETE`

  No new credential or OAuth client is required. Scopes are granted per Client Credentials in [API management](https://app.alvys.com/#/manage/public-api).

  ## FAQ

  **Do I need a new credential or OAuth client?**<br />No. Your existing Client Credentials works — just add the `customer:create` / `customer:update` / `customer:delete` scopes you need. `customer:read` is unchanged.

  **How do I get the** `ETag `**for an update or delete?** It's returned on the response header of any `GET`, `POST`, or `PATCH`, and additionally in the body of `POST` / `PATCH`. Use it as `If-Match` on your next mutation. On a `412`, re-`GET` for the fresh value.

  **What happens if two callers update the same customer at once?** The first `PATCH` wins (`200`); the second sees a stale `If-Match` and gets `412`. Re-`GET`, reapply, retry. No silent overwrite.

  **Does** `DELETE `**actually remove the record?** No — it's a soft-delete. `Status` goes to `Inactive` and the `CompanyNumber` stays reserved (a duplicate `POST` with that number returns `409`). To restore, `PATCH` with `{ "Status": "Active" }`.

  **What happens if I send an unsupported field like** `Notes `**in the body?** It's silently ignored. Only the writable fields listed above are applied.

  **Does this change the existing** `GET `**or search response shape?** No. The read surface is unchanged; this release is purely additive.

  **When do I see** `404 `**vs** `412`**?** `404` = the id does not exist in your tenant (ids in another tenant also return `404`). `412` = the id exists in your tenant but your `If-Match` is stale — re-`GET` for the current `ETag`.
</Update>

<Update label="May 22, 2026" description="Webhook Events for General Load & Trip Updates">
  ## What's New?

  We've added two new webhook event types to the Public API: `load.changed` and `trip.changed`. Whenever an operational field (such as rates, appointments, stops, or carrier assignments) is updated on a load or trip, Alvys now pushes a real-time webhook to every active subscription that selected those events.

  ## What Changed?

  Previously, detecting load- and trip-level updates required polling `GET /loads` and `GET /trips` on a schedule. Now, the following event types are available alongside the existing events and can be selected when creating or editing a webhook subscription:

  * `load.changed`
  * `trip.changed`

  The full list is also returned by: `GET /p/v1.0/webhooks/event-types`

  ## Event Envelope

  All webhook deliveries share the standard Alvys envelope. The new event types reuse it with a specific ID suffix for idempotency:

  ```jsonc theme={null}
  {
    "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97-d900dc51-...-0",
    "type": "load.changed",
    "timestamp": "2026-05-22T09:19:52.652Z",
    "version": "v1",
    "data": { /* event-specific payload - see below */ }
    // Other envelope fields are omitted from this example for brevity.
  }

  ```

  The envelope `id` is unique per event and should be used as the idempotency key on the consumer side. *Note: General changes end in a* `-0 `*suffix, while status changes end in* `-1`*.*

  ## load.changed

  Triggered when a load document is created or updated. The payload carries a full Public-API load snapshot - the same shape returned by `GET /p/v1.0/loads/{loadNumber}`.

  ```jsonc theme={null}
  {
    "load": {
      "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97",
      "loadNumber": "3039979",
      "orderNumber": "ABC-12-007",
      "status": "Open",
      "loadType": "Revenue",
      "customerRate": {
        "amount": 1749.06,
        "currency": 840
      }
      // Full Public-API load object - same fields as GET /p/v1.0/loads/{loadNumber}.
      // Other fields (stops, charges, references, etc.) omitted here for brevity.
    }
  }

  ```

  ## trip.changed

  Triggered when a trip document is created or updated. The payload carries a full Public-API trip snapshot - the same shape returned by `GET /p/v1.0/trips/{tripId}`.

  ```jsonc theme={null}
  {
    "trip": {
      "id": "dd5ba174abe845568f5e5c2a850db8ca",
      "tripNumber": "3039979",
      "status": "Open",
      "loadNumber": "3039979",
      "orderNumber": "ABC-12-007",
      "tripValue": {
        "amount": 1599.06,
        "currency": 840
      }
      // Full Public-API trip object - same fields as GET /p/v1.0/trips/{tripId}.
      // Other fields (driver, truck, stops, accessorials, etc.) omitted here for brevity.
    }
  }

  ```

  ## Endpoints Affected

  * `GET /p/v1.0/webhooks/event-types` now returns `load.changed` and `trip.changed`.
  * `POST /p/v1.0/webhooks` / `PUT /p/v1.0/webhooks/{id}` accept the new event type values in the `eventTypes` array.

  No request/response shapes were changed for existing endpoints. This update is fully backward compatible.

  ## Why?

  These events let API partners and integrations:

  * React to load and trip operational changes in real time, without polling.
  * Reduce overall API call volume on `/loads` and `/trips`.
  * Drive downstream automations (factoring, tracking, billing) the moment an operational state changes.
  * Keep audit trails consistent through the existing webhook Delivery Logs UI.

  <br />
</Update>

<Update label="May 13, 2026" description="Per-Entity Document Webhooks for Loads, Trips, Drivers, Carriers, Trucks & Trailers">
  ## What's New?

  Twelve new webhook event types are now available on the Public API — two for each parent entity that exposes documents through the API. Whenever a document is uploaded or removed in Alvys, the platform emits a webhook to every active subscription that selected the corresponding event.

  | Event                       | Fires when                              |
  | --------------------------- | --------------------------------------- |
  | `load.document.uploaded`    | A new document is attached to a load    |
  | `load.document.deleted`     | A load document is soft-deleted         |
  | `trip.document.uploaded`    | A new document is attached to a trip    |
  | `trip.document.deleted`     | A trip document is soft-deleted         |
  | `driver.document.uploaded`  | A new document is attached to a driver  |
  | `driver.document.deleted`   | A driver document is soft-deleted       |
  | `carrier.document.uploaded` | A new document is attached to a carrier |
  | `carrier.document.deleted`  | A carrier document is soft-deleted      |
  | `truck.document.uploaded`   | A new document is attached to a truck   |
  | `truck.document.deleted`    | A truck document is soft-deleted        |
  | `trailer.document.uploaded` | A new document is attached to a trailer |
  | `trailer.document.deleted`  | A trailer document is soft-deleted      |

  Events fire regardless of write source — UI uploads, Public API uploads, mobile-app uploads, EDI document ingestion, or third-party integrations all produce the same deliveries.

  Every `*.document.uploaded` event ships with a short-lived pre-signed download URL (≤ 15-minute TTL) so partners can pull the file directly without an additional API call.

  ## What Changed?

  ### Subscribing

  In **Settings → API → Webhooks → Create / Edit subscription**, select any combination of the new event types. The full list is also returned by `GET /p/v1.0/webhooks/event-types` for programmatic configuration.

  ### Envelope (general structure)

  All document webhook deliveries share the standard envelope used by `tender.*`, `load.status.changed`, and `trip.status.changed`. `id` is the deterministic idempotency key (`{documentId}-{etag}`); `etag` is also exposed as its own top-level envelope field so consumers can detect out-of-order replays for the same `documentId`.

  ### `*.document.uploaded` payload (general structure)

  Real production sample (`trip.document.uploaded`):

  ```json theme={null}
  {
    "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
    "type": "trip.document.uploaded",
    "timestamp": "2026-05-13T09:16:30.9797738+00:00",
    "version": "v1",
    "etag": "00000000-0000-0000-0000-000000000000",
    "data": {
      "tripId": "00000000000000000000000000000000",
      "document": {
        "id": "00000000-0000-0000-0000-000000000000",
        "attachmentPath": "bol.pdf",
        "attachmentType": "Bill of Lading",
        "attachmentSize": 10000,
        "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
        "parentId": "1000000",
        "parentType": "Trip",
        "uploadedBy": "00000000000000000000000000000000",
        "downloadUrl": "{url}",
        "expiresAt": "2026-05-13T09:26:35.3227049+00:00"
      }
    }
  }
  ```

  * `data.tripId` is the **trip GUID** (the natural public identifier returned by `GET /p/v1.0/trips/{tripId}`).
  * `data.document.parentId` on a trip document is the **load number** (`"1000000"`) — matching how trip documents are stored internally and returned by `GET /loads/{loadNumber}/documents`.
  * `attachmentType` is a **human-readable** Alvys document type (e.g. `"Bill of Lading"`, `"Proof of Delivery"`, `"Rate Confirmation"`) — same value returned by the document Public API endpoints.
  * `uploadedBy` is the **user id** (GUID) of the uploader.

  The same shape applies to the other five parent types — `data` always contains the parent's natural public identifier (`loadNumber`, `tripId`, `driverId`, `carrierId`, `truckId`, or `trailerId`) plus a `document` block. For example, `driver.document.uploaded` swaps `tripId` for `driverId`; the `document` block is identical.

  ### `*.document.deleted` payload (general structure)

  ```json theme={null}
  // load.document.deleted
  {
    "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
    "type": "load.document.deleted",
    "timestamp": "2026-05-13T16:05:22.118+00:00",
    "version": "v1",
    "etag": "00000000-0000-0000-0000-000000000000",
    "data": {
      "loadNumber": "1000000",
      "document": {
        "id": "00000000-0000-0000-0000-000000000000",
        "attachmentPath": "bol.pdf",
        "attachmentType": "Bill of Lading",
        "attachmentSize": 10000,
        "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
        "uploadedBy": "00000000000000000000000000000000",
        "parentId": "1000000",
        "parentType": "Load"
      }
    }
  }
  ```

  `downloadUrl` and `expiresAt` are omitted on delete events — the document is logically gone, so consumers should not pull bytes.

  ### Behavior notes

  * An event fires **only when a document is created or soft-deleted** — rename, retype, and other metadata-only edits do not generate deliveries.
  * Pre-signed `downloadUrl` is short-lived (≤ 15 minutes). Pull the file promptly, or fall back to `GET /p/v1.0/{parent}/{parentId}/documents/{documentId}` if it expires.

  ## Endpoints Affected

  ### Webhook subscription management

  These existing endpoints now accept the twelve new event types in their `eventTypes` array:

  * `GET /p/v1.0/webhooks/event-types` — returns the full catalog including the new document event types.
  * `POST /p/v1.0/webhooks` — create a subscription that selects any combination of the new events.
  * `PUT /p/v1.0/webhooks/{id}` — update an existing subscription to add or remove document events.
  * `GET /p/v1.0/webhooks/{id}` — inspect which events a subscription is selecting.
  * `GET /p/v1.0/webhooks/{id}/deliveries` — delivery history for the new events flows through the same logs surface as `tender.*` and `*.status.changed`.

  ### Document endpoints driving the events

  Any write to the following document sub-resources will fire the corresponding webhook for active subscribers. **No request or response shape has changed on these endpoints** — they are listed here so you can correlate which API actions produce which events.

  | Endpoint                                                     | Fires                       |
  | ------------------------------------------------------------ | --------------------------- |
  | `POST /p/v1.0/loads/{loadNumber}/documents`                  | `load.document.uploaded`    |
  | `DELETE /p/v1.0/loads/{loadNumber}/documents/{documentId}`   | `load.document.deleted`     |
  | `POST /p/v1.0/trips/{tripId}/documents`                      | `trip.document.uploaded`    |
  | `DELETE /p/v1.0/trips/{tripId}/documents/{documentId}`       | `trip.document.deleted`     |
  | `POST /p/v1.0/drivers/{driverId}/documents`                  | `driver.document.uploaded`  |
  | `DELETE /p/v1.0/drivers/{driverId}/documents/{documentId}`   | `driver.document.deleted`   |
  | `POST /p/v1.0/carriers/{carrierId}/documents`                | `carrier.document.uploaded` |
  | `DELETE /p/v1.0/carriers/{carrierId}/documents/{documentId}` | `carrier.document.deleted`  |
  | `POST /p/v1.0/trucks/{truckId}/documents`                    | `truck.document.uploaded`   |
  | `DELETE /p/v1.0/trucks/{truckId}/documents/{documentId}`     | `truck.document.deleted`    |
  | `POST /p/v1.0/trailers/{trailerId}/documents`                | `trailer.document.uploaded` |
  | `DELETE /p/v1.0/trailers/{trailerId}/documents/{documentId}` | `trailer.document.deleted`  |

  UI uploads, mobile-app uploads, EDI ingestion, and third-party integrations also produce the same events even though they don't go through the Public API endpoints above.

  ### Fallback retrieval (if a `downloadUrl` expires)

  If the 15-minute pre-signed `downloadUrl` expires before you fetch the file, retrieve the document through the standard authenticated endpoint:

  ```text theme={null}
  GET /p/v1.0/{parent}/{parentId}/documents/{documentId}
  ```

  ## Why?

  Until now, retrieving newly uploaded documents required polling the document sub-resource on each parent — `/loads/{loadNumber}/documents`, `/drivers/{driverId}/documents`, and four more. With these events in place:

  * ⚡ **Real-time document automation** — POD-driven invoice automation, factoring, document management, and EDI 210 invoice validation no longer wait on a poll loop.
  * 🔁 **Lower API load** — eliminates polling traffic against six different parent endpoints.
  * 🎯 **Subscribe narrowly** — events are scoped per entity (`load.*` vs `driver.*` vs `carrier.*` …). A factoring integration that only cares about load-side documents won't receive driver med-card updates.
  * 🧾 **Built-in audit trail** — every delivery attempt is recorded and visible in the Webhook details page.
  * 🔗 **Direct download** — every `*.uploaded` event carries a pre-signed download URL.

  ## Who has access?

  All Public API consumers with an active webhook subscription that selects any of the new event types. Subscription management requires Partner Admin / Admin / Support role under **Settings → API → Webhooks**.

  ## Frequently Asked Questions (FAQ)

  **Q: Do I need a new credential or scope to receive these events?** A: No. Existing webhook subscriptions can opt in by selecting the new event types.

  **Q: Is the `downloadUrl` reusable?** A: It's a single short-lived pre-signed Azure Blob SAS — valid for up to 15 minutes from emission. If it expires, retrieve the document through the standard Public API endpoint instead.

  **Q: Are events ordered?** A: Deliveries are best-effort ordered per document. Consumers should be **idempotent** and use the envelope `id` (`{documentId}-{_etag}`) as the idempotency key.

  **Q: Can I see delivery history for these events?** A: Yes — the existing **Logs** sidebar on the webhook detail page shows every delivery attempt for these event types, with the same filtering, pagination, and CSV/JSON export as `tender.*` and status-change events.

  **Q: Are document update / rename events available?** A: Not in this release. Today we emit on upload and soft-delete only. Update events may be added later as `*.document.updated` if there's customer demand.
</Update>

<Update label="May 4, 2026" description="Webhook Events for Load & Trip Status Updates">
  ### What's New?

  We've added two new webhook event types to the Public API: **`load.status.changed`** and **`trip.status.changed`**. Whenever a load or trip transitions from one status to another (for example, `Covered → Dispatched` or `Dispatched → InTransit`), Alvys now pushes a real-time webhook to every active subscription that selected those events.

  ### What Changed?

  Previously, the Public API exposed webhooks only for tender lifecycle events. Detecting load- and trip-level status transitions required polling `GET /loads` and `GET /trips` on a schedule.

  Now, the following event types are available alongside the existing `tender.*` events and can be selected when creating or editing a webhook subscription:

  ```text theme={null}
  load.status.changed
  trip.status.changed
  ```

  The full list is also returned by:

  ```text theme={null}
  GET /p/v1.0/webhooks/event-types
  ```

  ### Event Envelope

  All webhook deliveries share the standard Alvys envelope. The new event types reuse it without changes:

  ```jsonc theme={null}
  {
    "id": "…",
    "type": "load.status.changed",
    "timestamp": "2026-05-04T14:32:11.482Z",
    "version": "1",
    "data": { /* event-specific payload — see below */ }
    // Other envelope fields are omitted from this example for brevity.
  }
  ```

  The envelope `id` is unique per event and should be used as the **idempotency key** on the consumer side.

  ### `load.status.changed`

  Triggered when a load transitions from one status to another. The payload carries the prior + current status delta and a full Public-API load snapshot — the same shape returned by `GET /p/v1.0/loads/{loadNumber}`.

  ```jsonc theme={null}
  {
    "previousStatus": "Covered",
    "status": "Dispatched",
    "load": {
      "id": "…",
      "loadNumber": "1006321",
      "status": "Dispatched"
      // Full Public-API load object — same fields as GET /p/v1.0/loads/{loadNumber}.
      // Other fields (customer, stops, charges, references, etc.) omitted here for brevity.
    }
  }
  ```

  ### `trip.status.changed`

  Triggered when a trip transitions from one status to another. The payload carries the prior + current status delta and a full Public-API trip snapshot — the same shape returned by `GET /p/v1.0/trips/{tripId}`.

  ```jsonc theme={null}
  {
    "previousStatus": "Dispatched",
    "status": "InTransit",
    "trip": {
      "id": "…",
      "tripNumber": "T-1006321-1",
      "status": "InTransit"
      // Full Public-API trip object — same fields as GET /p/v1.0/trips/{tripId}.
      // Other fields (driver, truck, stops, accessorials, etc.) omitted here for brevity.
    }
  }
  ```

  ### Behavior

  * Events are emitted **only on actual transitions** — when `status` differs from `previousStatus`. No-op writes do not generate deliveries.
  * `load` / `trip` may be `null` if the snapshot read fails or if the payload exceeded the size limit and was stripped. The `previousStatus` and `status` fields are always present so consumers can still react to the transition and refetch via `GET /loads/{id}` or `GET /trips/{id}` if needed.
  * Deliveries are signed (`X-Alvys-Signature`), retried with exponential backoff, and auto-disable subscriptions after sustained failures — identical to existing `tender.*` events.

  ### Endpoints Affected

  * `GET /p/v1.0/webhooks/event-types` — now returns `load.status.changed` and `trip.status.changed`
  * `POST /p/v1.0/webhooks` / `PUT /p/v1.0/webhooks/{id}` — accept the new event type values in the `eventTypes` array

  No request/response shapes were changed for existing endpoints. This update is fully backward compatible.

  ### Why?

  These events let API partners and integrations:

  * React to load and trip status changes in real time, without polling
  * Reduce overall API call volume on `/loads` and `/trips`
  * Drive downstream automations (factoring, tracking, billing) the moment an operational state changes
  * Keep audit trails consistent through the existing webhook Delivery Logs UI

  This update extends the Public API's webhook surface with operational lifecycle coverage while preserving the existing event envelope contract.
</Update>

<Update label="April 22, 2026" description="Public API Carrier & Customer Payments Enhancements">
  ### What’s New?

  We’ve introduced new Public API capabilities for **carrier payments**, **customer payments**, and **financing transactions**. These additions make it easier for external payment platforms, factoring providers, and finance systems to sync financial activity directly with Alvys.

  ### What Changed?

  Previously, the Public API did not provide dedicated endpoints for recording these financial transactions.

  Now, the API includes the following new endpoints:

  ```http theme={null}
  POST /p/v1.0/invoices/carrier-payments
  POST /p/v1.0/invoices/customer-payments
  POST /p/v1.0/invoices/financing
  ```

  ### Carrier Payments

  Records a payment made to a carrier for a trip.

  Example:

  ```json theme={null}
  {
    "tripId": "string",
    "amount": {
      "value": 1000.00,
      "currency": "USD"
    }
  }
  ```

  Updates trip payment fields such as `carrierPaidAt`.

  ### Customer Payments

  Records a payment received from a customer for a load.

  Example:

  ```json theme={null}
  {
    "loadId": "string",
    "amount": {
      "value": 2500.00,
      "currency": "USD"
    }
  }
  ```

  Updates load payment details such as:

  * `paidAt`
  * `totalPaid`
  * `payments[]`

  ### Financing

  Records financing activity such as reserve or escrow amounts for a load.

  Example:

  ```json theme={null}
  {
    "loadId": "string",
    "reserveAmount": {
      "value": 500.00,
      "currency": "USD"
    },
    "escrowAmount": {
      "value": 200.00,
      "currency": "USD"
    }
  }
  ```

  ### Endpoints Affected:

  * `POST /p/v1.0/invoices/carrier-payments`
  * `POST /p/v1.0/invoices/customer-payments`
  * `POST /p/v1.0/invoices/financing`

  ### Why?

  These enhancements provide:

  * Faster integration with payment and finance platforms
  * Better automation for receivables and payables
  * Support for factoring and escrow workflows
  * Reduced manual entry of financial transactions
  * Improved accounting visibility across loads and trips

  This update expands the Public API’s financial integration capabilities while maintaining backward compatibility.
</Update>

<Update label="April 17, 2026" description="Trip Search Returns Tombstones for Deleted Trips">
  ### What’s New?

  We’ve updated **Trip Search** behavior for **invisible trips created by split, re-split, and unsplit flows** when `includeDeleted: true` is used. This improves sync reliability for integrations that poll trips using `updatedSince` or `updatedAtRange`.

  ### What Changed?

  The default behavior is unchanged:

  * when `includeDeleted` is omitted, Trip Search returns only visible, non-deleted trips
  * when `includeDeleted=false`, Trip Search also returns only visible, non-deleted trips

  The changed behavior applies only when `includeDeleted=true`.

  Previously, when a load was split, superseded or hidden trips could silently disappear from API results, even when `includeDeleted=true`. This made it difficult for integrations to detect lifecycle transitions and could leave stale records in downstream systems.

  Now, when `includeDeleted=true`, Trip Search returns invisible trip records as tombstones by surfacing them with `isDeleted: true`. This includes:

  * superseded base trips
  * hidden child legs from chained splits
  * hidden child legs from split-cancel / unsplit / restore scenarios

  In addition, `updatedAt` is updated when trip visibility changes, so polling by `updatedSince` or `updatedAtRange` can reliably capture these events.

  ### What `isDeleted` Means

  When `includeDeleted=true`:

  * `isDeleted=true` means the trip is deleted or no longer visible and should be treated as inactive for sync
  * `isDeleted=false` means the trip is a current visible leg

  ### Common Scenarios

  | Scenario                                         | Before                                 | After (with `includeDeleted: true`)                                                                    |
  | ------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
  | Trip `555` split into `555-1`, `555-2`           | `555` silently disappeared             | `555` is returned with `isDeleted: true`                                                               |
  | Trip `555-2` further split into `555-3`, `555-4` | `555-2` silently disappeared           | `555-2` is returned with `isDeleted: true`                                                             |
  | Split cancelled / unsplit / restored             | hidden split legs silently disappeared | hidden split legs are returned with `isDeleted: true`, restored active trip remains `isDeleted: false` |

  ### Example

  For a load with chained split behavior such as `1110758`:

  | Trip        | isDeleted | Meaning                               |
  | ----------- | --------: | ------------------------------------- |
  | `1110758`   |    `true` | Superseded base trip                  |
  | `1110758-1` |   `false` | Active leg                            |
  | `1110758-2` |    `true` | Child leg superseded by a later split |
  | `1110758-3` |   `false` | Active leg                            |
  | `1110758-4` |   `false` | Active leg                            |

  ### Endpoint Affected

  ```http theme={null}
  POST /p/v1.0/trips/search
  ```

  ### Why?

  This enhancement provides:

  * reliable tombstone detection for invisible and superseded trips
  * better support for `updatedSince` and `updatedAtRange` polling
  * more consistent synchronization for split, re-split, cancel-split, and restore scenarios

  <br />
</Update>

<Update label="April 15, 2026" description="Public API Webhook Enhancements: Delivery Attempts, Status Reason, and Delivery Log Export">
  ### What’s New?

  We’ve expanded the Public API webhook capabilities with new delivery metadata, richer event payloads, and export support for webhook delivery logs. These updates make webhook integrations easier to monitor, debug, and process safely.

  ### What Changed?

  Previously, webhook consumers did not receive a delivery-attempt header, visibility/status webhook payloads did not include a human-readable status reason, and there was no dedicated delivery-log export endpoint in the published schema. In addition, delivery log filters previously accepted single string values.

  Now, the Public API includes the following webhook changes:

  ```http theme={null}
  GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export
  ```

  ### Delivery Attempt Header

  Alvys now includes an `X-Alvys-Attempt` header on every outbound webhook delivery request. The value represents the delivery attempt number as an integer string.

  | Header            | Type           | Description                                               |
  | ----------------- | -------------- | --------------------------------------------------------- |
  | `X-Alvys-Attempt` | integer string | Delivery attempt number for the outbound webhook request. |

  | Value | Meaning                                       |
  | ----- | --------------------------------------------- |
  | `1`   | First delivery attempt                        |
  | `2`   | First retry after 10-second backoff           |
  | `3`   | Second retry after 30-second backoff          |
  | `4`   | Third and final retry after 60-second backoff |

  This can be used to support idempotent processing, suppress duplicate warnings, and track retry behavior.

  ### `statusReason` Added to Webhook Payloads

  Outbound webhook payloads for visibility and status events now include a `statusReason` field. This field provides the human-readable reason description, distinct from the reason code.

  Example:

  ```json theme={null}
  {
    "statusReason": "Normal Status"
  }
  ```

  ### Delivery Logs Export

  A new webhook delivery log export endpoint is now available in the new schema: `GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export`. It supports CSV and JSON export and uses the same filters as the delivery logs list endpoint. The schema description also confirms the export supports up to 25,000 rows total.

  #### Query Parameters

  | Parameter   | Type               | Description                                               |
  | ----------- | ------------------ | --------------------------------------------------------- |
  | `webhookId` | string             | Webhook identifier to export logs for.                    |
  | `Format`    | string             | Export format. Supported values include `csv` and `json`. |
  | `Page`      | integer            | 0-based last page index to include in the export.         |
  | `PageSize`  | integer            | Number of rows per page. Max 100, default 50.             |
  | `Status`    | array of strings   | Filter by one or more delivery statuses.                  |
  | `EventType` | array of strings   | Filter by one or more webhook event types.                |
  | `StartDate` | string (date-time) | Start of the date range.                                  |
  | `EndDate`   | string (date-time) | End of the date range.                                    |

  #### Export Behavior

  The new schema documents the following format resolution behavior for the export endpoint:

  1. `Format=csv` or `Format=json` in the query string takes precedence when provided.
  2. Otherwise, the `Accept` header is used.
  3. Otherwise, the response defaults to JSON.

  ### Breaking Change: Delivery Log Filters Now Accept Arrays

  The delivery logs list endpoint changed its filter shape between the old and new schema. Previously, both `Status` and `EventType` were single strings. In the new schema, both are arrays of strings.

  #### Before

  ```json theme={null}
  {
    "status": "failed",
    "eventType": "load.updated"
  }
  ```

  #### After

  ```json theme={null}
  {
    "status": ["failed"],
    "eventType": ["load.updated"]
  }
  ```

  This change also applies to the export endpoint, where `Status` and `EventType` are defined as arrays.

  ### Endpoints Affected

  * `GET /p/v{version}/webhooks/{webhookId}/delivery-logs`
  * `GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export`

  ### Why?

  These enhancements provide:

  * better retry visibility for webhook consumers
  * clearer status context in outbound payloads
  * easier export and audit of webhook delivery history
  * more flexible filtering for delivery log queries and exports

  <br />
</Update>

<Update label="April 13, 2026" description="Public API Enhancements for Loads, Trips, Carriers, Tenders, and Core Response Schemas">
  ### What’s New?

  We’ve delivered additional Public API improvements across **loads**, **trips**, **carriers**, **tenders**, and several existing response schemas. These changes improve sync reliability, expose more operational data, and make related endpoints more consistent.

  ### What Changed?

  Previously, several important fields and behaviors were either missing from the published schema, inconsistent between related endpoints, or not fully exposed to integrations.

  Now, the Public API includes the following confirmed changes:

  #### Loads

  Load responses now include:

  ```json theme={null}
  {
    "tenderId": "string | null",
    "requiredEquipment": [
      "Reefer"
    ]
  }
  ```

  In addition:

  * orphaned loads are now treated as non-existent
  * load search totals exclude abandoned loads with no trips
  * load document and note operations now return `404` for orphaned loads

  #### Trips

  Trip responses now include:

  ```json theme={null}
  {
    "orderNumber": "string | null"
  }
  ```

  Trip sync behavior was also improved:

  * split or invisible trips can now be returned as `isDeleted: true` when `includeDeleted=true`
  * `GET /p/v{version}/trips` now supports `includeDeleted`
  * `POST /p/v{version}/trips/search` now allows `updatedAtRange` as the only filter
  * load references of type `service_exception` are now exposed
  * carrier payloads are aligned between single-trip retrieval and trip search

  #### Carriers

  Carrier search results now include carriers in `DoNotLoad` status, which were previously omitted even when they were referenced by trips.

  #### Tenders

  Tender request `references[]` objects now support a `type` field, enabling typed reference routing.

  #### Additional response schema updates

  The new schema also confirms additional response-model changes outside the payment-posting flows:

  * `CarrierResponse` now includes:
    * `PaymentMethod`
    * `ExternalIds`
    * `FactoringCompany`
  * `DriverResponse`, `TruckResponse`, and `TrailerResponse` now include:
    * `LicenseCountry`
  * `FuelResponse` now includes:
    * `Description`
  * `FuelResponsePumpLocation` now includes:
    * `State`

  #### Trip rate schema updates

  The trip rate-related schemas were expanded with additional structures and fields:

  * `DriverRatePolicyResponse` now includes:
    * `CustomerLineHaulDeductionRate`
    * `PerMileRate`
    * `PerMileDeductionRate`
  * `PerLoadRate` now uses a dedicated `PerLoadRateDto`
  * `MileageRateDto` now includes:
    * `UseHighestTier`
  * `PerTripRateDto` now includes:
    * `Tiers`
    * `MileageType`
  * `PerTripRateDto.Rate` is now marked as deprecated in the schema

  #### Error-response documentation updates

  The new schema also adds broader error-response documentation across many existing non-webhook endpoints:

  * `401 Unauthorized`
  * `403 Forbidden`
  * `429 Too Many Requests`

  ### Why?

  These enhancements provide:

  * better load and trip sync reliability for polling integrations
  * clearer identification of tender-originated loads
  * better visibility into order linkage at the trip level
  * more complete carrier search results
  * stronger consistency between related trip endpoints
  * richer master-data payloads for carriers, drivers, trucks, trailers, and fuel records
  * more expressive trip rate schemas

  <br />

  <br />
</Update>

<Update label="March 13, 2026" description="Manage Stop Arrivals, Departures & Appointments via the Public API">
  ### What’s New?

  The Public API now supports full stop-level trip execution: read a trip’s stops, record (or clear) arrivals, record departures, and manage stop appointments — so dispatch events can flow into Alvys from your own systems in real time.

  ### What Changed?

  Previously, stop arrivals, departures, and appointment changes could only be recorded inside the Alvys platform.

  Now, the Public API includes the following endpoints:

  ```http theme={null}
  GET    /api/p/v{version}/trips/{tripId}/stops
  GET    /api/p/v{version}/trips/{tripId}/stops/{stopId}
  PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
  DELETE /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
  PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/departure
  PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment
  ```

  * [**Record stop arrival**](/en/api/reference/trips/record-stop-arrival) — body takes a required `arrivedAt` timestamp; returns the updated stop.
  * [**Clear stop arrival**](/en/api/reference/trips/clear-stop-arrival) — removes a previously recorded arrival.
  * [**Record stop departure**](/en/api/reference/trips/record-stop-departure) — body takes a required `departedAt` timestamp; returns `422` if the stop is not in a state that can be departed.
  * [**Set stop appointment**](/en/api/reference/trips/set-stop-appointment) — update the stop’s `scheduleType`, `loadingType`, and appointment window.

  All mutation endpoints return the updated `StopResponse`, so callers get fresh state without a follow-up read.

  ### Why?

  EDI providers, driver apps, and dispatch systems generate arrival/departure events outside Alvys. These endpoints let those events land directly on the trip’s stops, keeping statuses, timestamps, and downstream billing (e.g. detention) accurate.

  <br />
</Update>

<Update label="March 2, 2026" description="Load Notes Endpoints Added to the Public API">
  **Release Date:** March 2, 2026 (endpoints), April 30, 2026 (`CreatedById`)

  ### What's New?

  You can now list, create, and delete load notes through the Public API — keeping operational commentary in sync between Alvys and your external systems.

  ### What Changed?

  Previously, load notes were only accessible inside the Alvys platform.

  Now, the Public API includes:

  ```http theme={null}
  GET    /api/p/v1/loads/{loadNumber}/notes
  POST   /api/p/v1/loads/{loadNumber}/notes
  DELETE /api/p/v1/loads/{loadNumber}/notes/{noteId}
  ```

  * **List load notes** — returns all notes on the load.
  * **Create load note** — body takes `description`, `noteType`, and an optional client-supplied `id`; returns `201` with the created note.
  * **Delete load note** — returns `204` on success.

  ### Response Body Includes

  * `Id`, `Description`, `NoteType`
  * `CreatedAt`, `CreatedBy`
  * `CreatedById` — the unique identifier of the user who created the note *(added April 2026)*, so integrations can attribute notes to a user by id instead of parsing display names.

  Notes on orphaned or inaccessible loads return `404`.

  ### Why?

  Notes carry dispatch context — special instructions, exception history, customer commitments. Exposing them via the API lets integrations read that context and write their own, without double entry in two systems.
</Update>

<Update label="February 23, 2026" description="Alvys Webhooks Now Available for Tender Lifecycle Events">
  ## What’s New?

  Alvys now supports **Webhooks** — a secure way to receive real-time event notifications directly from Alvys to your system.

  Instead of polling the API for updates, your system can now subscribe to events and receive them automatically via secure HTTPS calls.

  **In this initial release, Webhooks support tender-related events only.** Additional event domains (such as loads or trips) will be introduced in future releases.

  This version establishes the foundation layer for real-time event distribution in Alvys.

  ## What You Can Do

  With Webhooks, you can:

  * Receive real-time **tender lifecycle events**
  * Automatically trigger workflows in your system
  * Improve integration speed and responsiveness

  ## Included in This Release

  ### Event Delivery

  Alvys sends HTTPS `POST` requests to your configured endpoint whenever a subscribed **tender event** occurs.

  Each delivery includes:

  * Event type
  * Unique event ID
  * Timestamp
  * Secure HMAC signature

  Webhooks use an **at-least-once delivery model** with automatic retries to ensure reliability.

  ### Automatic Retries

  If your endpoint is temporarily unavailable, Alvys will retry delivery automatically.

  Each event can be attempted up to four times.

  Retries occur when:

  * Your endpoint returns a server error (5xx)
  * A timeout occurs
  * A temporary network failure happens

  Retries do not occur for permanent client errors (most 4xx responses).

  ### Security & Verification

  Webhooks include:

  * HMAC-SHA256 signature verification
  * Replay protection using timestamps
  * HTTPS-only delivery
  * Endpoint ownership verification during setup

  This ensures events are authentic and securely transmitted.

  ## Why This Matters

  Webhooks enable real-time, event-driven integrations between Alvys and your systems.

  This release lays the foundation for:

  * EDI over API integrations
  * Automated tender workflows
  * Faster operational response
  * Secure third-party integrations

  Future releases will expand webhook support to additional business domains.

  ## Documentation

  For full implementation details, please refer to:

  * [**Webhook Lifecycle & Configuration**](/en/api/reference/webhooks/webhook-lifecycle-configuration)
  * [**Event Delivery & Reliability**](/en/api/reference/webhooks/event-delivery-reliability)
  * [**Security & Signature Verification**](/en/api/reference/webhooks/security-signature-verification)

  These guides cover subscription setup, retry behavior, auto-disable rules, signature validation, and best practices for building robust integrations.

  <br />

  <Warning>
    **Webhook Availability Notice**

    Webhooks are currently available by request. To enable this functionality for your account, please contact your Customer Success Manager or Implementation Manager.
  </Warning>
</Update>

<Update label="February 13, 2026" description="Trip Temperature & Required Equipment Fields Added to Trip Response Body">
  ### What’s New?

  We’ve added two new fields to the **Trips** endpoints in the Public API: **Temperature** and **RequiredEquipment**. These fields provide visibility into temperature requirements and equipment specifications for each trip.

  ### What Changed?

  Previously, temperature requirements and normalized equipment requirements were not exposed in the Public API.

  Now, the response includes the following new properties:

  ```json theme={null}
  "Temperature": {
    "SetpointTemperature": 70.0,
    "SetpointTemperatureMax": 75.0,
    "ControlMode": "Start/Stop"
  },

  "RequiredEquipment": [
    "Reefer"
  ]
  ```

  #### Temperature

  The `Temperature` object represents the required temperature settings for temperature-controlled trips.

  * **SetpointTemperature** – The required target temperature.
  * **SetpointTemperatureMax** – Optional maximum temperature when a range is defined.
  * **ControlMode** – Expected operational mode (`Continuous` or `Start/Stop`).

  If no temperature requirement exists for the trip, this field will return `null`.

  #### RequiredEquipment

  The `RequiredEquipment` field is now returned as an array of equipment types required for the trip.

  Examples:

  ```json theme={null}
  "RequiredEquipment": ["Reefer", "Van"]
  "RequiredEquipment": ["Van"]
  "RequiredEquipment": ["Flatbed", "StepDeck"]
  ```

  If no equipment requirement is defined, this field will return `null`.

  ### Endpoints Affected:

  * `POST /api/p/{version}/trips/search`
  * `GET /api/p/{version}/trips/{id}`

  ### Why?

  These additions provide:

  * Improved visibility into temperature-controlled trip requirements
  * Structured equipment data for easier validation and integration
  * Better support for compliance workflows and custom tracking applications

  This update enhances clarity and integration capabilities while maintaining backward compatibility.
</Update>

<Update label="January 26, 2026" description="Custom References for Trips, Drivers, Trucks & Trailers">
  ### What's New?

  Custom references — tenant-defined key/value identifiers configured in your Alvys company profile — are now exposed in the Public API on **trips**, **drivers**, **trucks**, and **trailers**.

  ### What Changed?

  Previously, custom references were only visible inside the Alvys platform.

  Now, the corresponding get-by-id and search responses include a `references` collection:

  ```json theme={null}
  "references": [
    {
      "id": "string",
      "referenceId": "string",
      "name": "string",
      "value": "string",
      "type": "Text",
      "access": "Public",
      "origin": "string"
    }
  ]
  ```

  ### Endpoints Affected

  * `GET /api/p/v{version}/trips/{id}` and `POST /api/p/v{version}/trips/search`
  * `GET /api/p/v{version}/drivers/{id}` and `POST /api/p/v{version}/drivers/search`
  * `GET /api/p/v{version}/trucks/{id}` and `POST /api/p/v{version}/trucks/search`
  * `GET /api/p/v{version}/trailers/{id}` and `POST /api/p/v{version}/trailers/search`

  Only references configured as visible to the Public API are returned — reference visibility is controlled per reference type in your company profile.

  ### Why?

  Most fleets track external identifiers that don't fit standard fields — payroll ids, ELD ids, insurance policy numbers, legacy system keys. Custom references let you model those in Alvys, and this change makes them available to every integration that needs to join Alvys records to outside systems.
</Update>

<Update label="October 24, 2025" description="Enhanced Driver Rates Visibility in Trips Endpoint">
  ### What’s New?

  We’ve introduced the new **RatesV2** structure for drivers and owner-operators in the Trips Public API. This structure provides a detailed breakdown of how each driver’s pay was calculated based on applied rate rules and policies.

  ### What Changed?

  Previously, driver payment data under `Driver1`, `Driver2`, and `OwnerOperator` included only simple `Rates[]` arrays with limited fields (e.g., `rate`, `rateType`, `source`).

  Now, the response includes a **`RatesV2`** array, containing all applied rules, their types, amounts, and computed line items.

  Each `RatesV2[]` entry contains a unique `PolicyId`, `PolicyName`, and one or more detailed rate components such as:

  ```json theme={null}
   "RatesV2": [
                      {
                          "PolicyId": "c00fda1001ec4a11100affdb0234de00",
                          "PolicyName": "Custom Rate",
                          "PerTripRate": {
                              "Rate": 250.0,
                              "RateId": "1",
                              "RateName": "Per Trip",
                              "LineItems": [
                                  {
                                      "Description": "1 trip @ $250",
                                      "Amount": {
                                          "Amount": 250.0,
                                          "Currency": 840
                                      }
                                  }
                              ]
                          }
                      },
                      {
                          "PolicyId": "a00fba1001ec4a11100aaddff0234de00",
                          "PolicyName": "Public API",
                          "TripValuePercentageRate": {
                              "Percentage": 25.0,
                              "RateId": "2",
                              "RateName": "% of Trip Value",
                              "LineItems": [
                                  {
                                      "Description": "25% of $3,800",
                                      "Amount": {
                                          "Amount": 950.0,
                                          "Currency": 840
                                      }
                                  }
                              ]
                          }
                      }
                  ]
  ```

  ### Endpoints Affected

  * `GET /api/p/{version}/trips`
  * `POST /api/p/{version}/trips/search`

  ### Why?

  This change exposes **driver rate calculation logic** used in the Alvys UI, allowing integrators to:

  * Understand which rules and policies were applied to determine each payout.
  * Align backend integrations with the new internal pay policy engine for consistent reporting and reconciliation.

  <br />

  <Warning>
    Important Note

    This update is **partially backward compatible**:

    * The legacy `Rates[]` field still exists and is returned in API responses.
    * For **new trips created after migration** to Driver Settlement (DS), the `Rates[]` array will **always be empty**.
    * For **trips created before migration**, `Rates[]` may still contain historical data, but it can be **out of sync** with `RatesV2[]` if new rates were added after migration.
    * All current and future rate data is now provided exclusively in the **`RatesV2[]`** array.
    * Integrations should **update their logic** to use `RatesV2[]` as the source of truth for driver and owner-operator pay details.
    * The legacy `Rates[]` field will remain available temporarily for backward compatibility but will be **fully deprecated later**.

    Each rate type (e.g., `TripValuePercentageRate`, `PerTripRate`, `MinimumPayRate`, etc.) is now provided as a structured object with additional `LineItems[]` for detailed breakdowns.
  </Warning>

  <br />
</Update>

<Update label="October 9, 2025" description="New Endpoints for Managing Deductions">
  ### What’s New?

  A new **Deductions** module has been added to the Alvys Public API. These endpoints allow integrations to create, search, retrieve, and delete deduction records associated with drivers or trucks. A deduction represents an **asset-specific financial adjustment** (e.g., drug test fees, fuel advances, or reimbursements) and is always linked to a specific **DriverId** or **TruckId**, but never both.

  At this stage, only **one-time (Once)** deductions are supported.

  ***

  ### What Changed?

  **New endpoints:**

  | Method   | Endpoint                              | Description                                                    |
  | -------- | ------------------------------------- | -------------------------------------------------------------- |
  | `GET`    | `/api/p/v{version}/deductions/{id}`   | Retrieves a deduction by its unique ID.                        |
  | `POST`   | `/api/p/v{version}/deductions/search` | Searches deductions by date, driver, truck, or owner operator. |
  | `POST`   | `/api/p/v{version}/deductions/once`   | Creates a one-time deduction for a driver or a truck.          |
  | `DELETE` | `/api/p/v{version}/deductions/{id}`   | Deletes a specific deduction by its unique ID.                 |

  **Validation rules:**

  * A deduction must include **either `DriverId` or `TruckId`** — one of them is required.
  * **`OwnerOperatorId`** is optional and may be used only to override the current owner of the asset. It is never the primary deduction subject.
  * If `DriverId` is provided → the deduction appears in that driver’s deduction list.
  * If `TruckId` is provided → the deduction appears in that truck’s deduction list.
  * For creating a deduction, the amount must be **negative** and less than **- 1.00**.
  * Only `"Once"` frequency is supported.
  * Requires a valid Bearer token with the appropriate scope (`deduction:read`, `deduction:create`, or `deduction:delete`).

  ***

  ### Why?

  This release introduces a consistent and secure way to manage **one-time deductions** through the Public API. It enables automated synchronization of deduction data across financial and payroll systems while maintaining full ownership and asset context within Alvys.
</Update>

<Update label="September 30, 2025" description="Public API Now Supports Document Fetching Across Core Entities">
  We’ve added new **Documents retrieval endpoints** to the Public API. These endpoints allow you to retrieve uploaded documents for carriers, drivers, loads, trips, trucks, and trailers.

  ***

  ### What Changed?

  Previously, documents were only available through internal UI and were not exposed in the Public API.

  Now, the following new endpoints are available for retrieving documents associated with each entity type:

  **Endpoints Added:**

  `GET /api/p/{version}/carriers/{carrierId}/documents`

  `GET /api/p/{version}/drivers/{driverId}/documents`

  `GET /api/p/{version}/loads/{loadNumber}/documents`

  `GET /api/p/{version}/trips/{tripId}/documents`

  `GET /api/p/{version}/trucks/{truckId}/documents`

  `GET /api/p/{version}/trailers/{trailerId}/documents`

  ***

  ### Response Example

  Each endpoint returns an array of document objects, providing all documents linked to the specified entity. Each document includes details such as type, size, uploader, and upload time, along with a secure download link. The `DownloadUrl` is valid for 10 minutes and includes an `ExpiresAt` timestamp.

  ```json theme={null}
  [
    {
      "id": "a314c7cd-783a-4807-8771-06406a9e490a",
      "AttachmentPath": "Loads-1759237626.pdf",
      "AttachmentType": "Customer Rate Confirmation",
      "AttachmentSize": 170225,
      "UploadedAt": "2025-09-30T13:07:07+00:00",
      "ParentId": "3022259",
      "ParentType": "Load",
      "UploadedBy": "7190175eecc3408e90d7173f4ece0e59",
      "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/Loads-1759237626.pdf?...",
      "ExpiresAt": "2025-09-30T15:12:15.9506343+00:00"
    }
  ]
  ```

  ***

  ### Why?

  This enhancement improves transparency and flexibility by making documents accessible through the Public API. It supports broader use cases, enabling external systems to integrate seamlessly with Alvys data and workflows.

  <br />
</Update>

<Update label="September 24, 2025" description="Introduced Load Office to Public API">
  ### What’s New?

  We’ve added the **Load Office** field to the Public API. This field is now returned under the **Loads** endpoint, giving you visibility into which office a load belongs to.

  ### What Changed?

  Previously, the Load’s office information was not exposed in the Public API.

  Now, the response includes the following new property:

  ```json theme={null}
  "OfficeId": "string",
  ```

  This value corresponds to the internal Office ID associated with the load.

  ### Endpoints Affected:

  * `POST /api/p/{version}/loads/search`
  * `GET /api/p/{version}/loads/{id}`

  ### Why?

  This change provides transparency into load ownership by office, supporting office-level reporting and integrations that require filtering or grouping loads by their assigned office.

  <br />

  <br />
</Update>

<Update label="September 8, 2025 · 4:28 PM" description="Document Upload Endpoints Now Available in Public API">
  ### What’s New?

  We added a new set of document upload endpoints that allow attaching files directly to Carriers, Drivers, Loads, Trailers, Trips, and Trucks. Each endpoint supports `multipart/form-data` uploads with validation on file size and document type.

  📂**File uploads up to 25 MB** (PDF, JPEG, PNG)

  🧾 **Entity-specific validation** → Each entity supports only its own `DocumentType` list (e.g., `Carrier Agreement`, `Driver License`, `Proof of Deliver`)

  🗂️ **Standardized metadata** → Every upload returns `AttachmentPath`, `AttachmentType`, `AttachmentSize`, `UploadedAt`, and parent entity reference

  🔑 **Authentication & scopes** → Requires valid Bearer token with read/update scope for the target entity

  ***

  ### What Changed?

  * **New endpoints**:
    * `POST /api/p/v{version}/carriers/{carrierId}/document`
    * `POST /api/p/v{version}/drivers/{driverId}/document`
    * `POST /api/p/v{version}/loads/{loadNumber}/document`
    * `POST /api/p/v{version}/trailers/{trailerId}/document`
    * `POST /api/p/v{version}/trips/{tripId}/document`
    * `POST /api/p/v{version}/trucks/{truckId}/document`
  * **Validation by entity**:
    * **Carrier**→ Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents
    * **Driver**→ License, Drug Test, Medical (suggested rename: Medical Card), W9 Form, Operating Authority, Other Documents
    * **Truck/Trailer** → Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents
    * **Loads**→ Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels
    * **Trips** → Proof of Delivery (POD), Bill of Lading (BOL), Carrier Rate Confirmation, Load Manifest, Trip Report, Temperature Log, Proof of Pickup, Scale Ticket, Notice of Assignment (NOA), Shipping Labels
  * **Error handling standardized**:
    `400` invalid `DocumentType` or file too large
    `401` invalid/expired token
    `403` missing scopes
    `404` parent not found/deleted
    `415` unsupported content type
    `429` rate limit exceeded

  ***

  ### Example — Upload Document to Load

  ```bash theme={null}
  curl -X POST "{{host}}/api/p/v1/loads/1006321/document" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: multipart/form-data" \
    -F "File=@Test_File.pdf" \
    -F "DocumentType=Bill of Lading"
  ```

  **Response:**

  ```json theme={null}
  {
    "id": "4b5c38bd-005e-4903-a4ee-45ca5e86411a",
    "AttachmentPath": "DOC-1757343192.jpeg",
    "AttachmentType": "Bill of Lading",
    "AttachmentSize": 5245329,
    "UploadedAt": "2025-09-08T14:53:12Z",
    "ParentId": "1006321",
    "ParentType": "Load"
  }
  ```

  ***

  ### Why?

  This enhancement provides a **standardized and secure way** to upload and manage documents across all core entities. By enforcing file size and type validation, plus entity-specific `DocumentType` rules, we improve **compliance and data integrity**. These endpoints also unlock automation use cases, such as auto-attaching Proof of Delivery, Insurance Certificates, or Rate Confirmations during operational workflows.

  <br />
</Update>

<Update label="September 8, 2025 · 4:18 PM" description="New Endpoints for Company Location Details">
  ### What’s New?

  We added a new **Locations Controller** to the Public API. This lets you fetch and search company location details (e.g., Terminals, Shippers/Consignees, Cold Warehouses, Dry Warehouses).

  * **Lookup by ID or Company Number**: Retrieve a single location by unique `id` or `companyNumber`.
  * **Flexible search**: Filter by `Statuses`, `LocationIds`, or `CreatedDateRange`.
  * **Richer details**: Get company name, type, address, contacts, and notes directly in the response.

  ***

  ### What Changed?

  * **New endpoints**:
    * `GET /api/p/v{version}/locations` → Single location lookup by `id` or `companyNumber`.
    * `POST /api/p/v{version}/locations/search` → Search and paginate results.
  * **Response body includes**:
    * Core: `Id`, `Name`, `CompanyNumber`, `Type`, `Status`
    * Address: `PhysicalAddress { Street, City, State, ZipCode }`
    * Contacts: `Email[]`, `Phone[]`, `Fax`
    * Metadata: `DateCreated`, `ExternalId`
    * Notes: `[ { Id, Description, NoteType, Time, User } ]`
  * **Backward compatibility**: No changes to existing load/trip stop payloads. Stops continue to expose `companyId`, but now customers can resolve those IDs via the Locations Controller for more context.

  ***

  ### New Endpoints

  * `GET /api/p/v{version}/locations`
  * `POST /api/p/v{version}/locations/search`

  ***

  ### Why?

  Stops in loads and trips previously only included a **companyId**, making it difficult to identify the company behind each stop. With this release, customers can resolve those IDs into **names, addresses, and full details**. This improves reporting precision, operational visibility, and overall usability — without breaking existing integrations.

  <br />
</Update>

<Update label="September 4, 2025" description="Enhanced Fuel Endpoints with Transaction Date and Quantity Details">
  ### What’s New?

  We enhanced the **Fuel API endpoints** with additional fields to provide more complete transaction details:

  * **TransactionDate** → Now included in all fuel transactions.
  * **Quantity** → Each transaction includes the purchased quantity with value and unit of measure:

  ```json theme={null}
  "Quantity": {
    "Value": 7.799,
    "UnitOfMeasure": "Gallons"
  }
  ```

  This makes it possible to accurately calculate the total fuel purchased and improve report metrics.

  <br />
</Update>

<Update label="August 21, 2025" description="Granular Accessorials Breakdown: Customers, Carriers & Drivers">
  **Release Date:** August 21, 2025

  ## What’s New?

  We added **detailed accessorial breakdowns** to the `/loads` and `/trips` endpoints. Instead of only totals, each accessorial is now returned as its own record, giving you full visibility into charges.

  * **Multi-entity support**: Accessorials are now tracked for **Customers, Carriers, Drivers, and OwnerOperators**.
  * **EChecks integration**: Driver and OwnerOperator accessorials can include linked eCheck numbers and amounts.
  * **Updated settlement logic**: `TotalPayable` now calculates as `Linehaul + Accessorials – EChecks`.

  ## What Changed?

  * **`/loads`** → `CustomerAccessorialsDetails[]` added.
  * **`/trips`** → New detail arrays for:
    * `Carrier.AccessorialsDetails[]`
    * `Driver1.AccessorialsDetails[]` for Driver and OwnerOperator.
  * **Each accessorial includes**:
    * Default: `Id`, `Type`, `Total { Amount, Currency }`, `Rate { Amount, Currency }`, `RateType`, `Uom`, `Quantity`
    * Optional: `IsPaid`, `ECheckNumber`, `StopId`
    * Audit: `CreatedAt`, `UpdatedAt`, `CreatedBy`, `UpdatedBy`
  * **EChecks** are now returned as part of trip data when relevant.
  * **Cancelled loads/trips** → No accessorial details returned.
  * **Backward compatibility** → Legacy totals remain available (`CustomerAccessorials`, `Carrier.Accessorials`, `Linehaul`, etc.), so this is a non-breaking change.

  ### Example — Accessorials

  ```json theme={null}
  {
    "Id": "acc-78901",
    "Type": "Layover Pay",
    "Total": { "Amount": 150.0, "Currency": 840 },
    "Rate": { "Amount": 75.0, "Currency": 840 },
    "RateType": "Time",
    "Uom": "Hour",
    "Quantity": 2.0,
    "ECheckNumber": "12345",
    "CreatedAt": "2024-07-11T14:30:00Z"
  }
  ```

  ## Endpoints Affected

  * `GET /api/p/v{version}/loads`
  * `POST /api/p/v{version}/loads/search`
  * `GET /api/p/v{version}/trips`
  * `POST /api/p/v{version}/trips/search`

  ## Why?

  This enhancement provides **granular billing data** for all parties involved in a load or trip, including customer charges, carrier costs, driver pay, and owner-operator expenses. With eCheck tracking and updated `TotalPayable` logic, you can reconcile payments more accurately while maintaining **full backward compatibility** for existing integrations.
</Update>

<Update label="August 8, 2025" description="Introducing new response field, LoadType, to distinguish between revenue- and non-revenue loads">
  **Release Date:** August 7, 2025

  **What’s New?**

  We’ve added a new response field, **`LoadType`**, to distinguish between revenue- and non-revenue loads.

  **What Changed?**

  * **`LoadType`** now appears on load objects.
  * Returned values: `"Revenue"` or `"Non-Revenue"`

  **Endpoints Affected:**

  * `GET  /api/p/{version}/loads`
  * `POST /api/p/{version}/loads/search`

  **Why?**

  This field makes it easier to filter and report on revenue-generating versus non-revenue loads directly in your API integrations.
</Update>

<Update label="August 7, 2025" description="Exposing Deleted Loads and Trips in the Public API When `IncludeDeleted` Is True">
  Release Date: August 7, 2025

  **What’s New?**

  We’ve added an optional request parameter, **`IncludeDeleted`**, so you can control whether deleted loads and trips appear in API responses.

  **What Changed?**

  * Previously, deleted loads and trips were never returned.
  * You can now include **`IncludeDeleted`** (boolean, optional) in your request body:
    * `true` → returns both active and deleted records.
    * omitted or `false` → returns only active records.
  * When `IncludeDeleted: true`, every returned record includes an **`IsDeleted`** flag:
    * `"IsDeleted": true` for deleted items
    * `"IsDeleted": false` for active items
  * When `IncludeDeleted` is omitted or `false`, **no** `IsDeleted` flags appear (all records are active by definition).

  **Endpoints Affected:**

  * `POST /api/p/{version}/loads/search`
  * `POST /api/p/{version}/trips/search`

  **Why?**

  This enhancement gives you direct control over including or excluding deleted records at the API level—surfacing deleted data only when needed.
</Update>

<Update label="June 24, 2025" description="📝 Power BI: New Auth, Auto-Paging, and More Improvements">
  **Release date: June 2025**

  ***

  ### 🔐 **New Authentication**

  * Now get access token via `auth.alvys.com/oauth/token` for improved security and compliance.
  * **Old authentication method will soon be disabled**—update your credentials using the new setup instructions.

  ***

  ### 🔄 **Automated Pagination**

  * All queries now handle **paging automatically**.
  * Large datasets load completely, with no missing records or manual adjustments.
  * A built-in delay mechanism helps prevent hitting API rate limits during refreshes, improving reliability for large data pulls.

  ***

  ### ↔️ **Nested Data Expansion**

  * Data queries now **automatically expand up to 3 levels** of nested fields.
  * All relevant API data is accessible without extra manual steps.

  ***

  ### 🗓️ **Automatic Field Type Conversion**

  * Key fields such as dates and numbers are now automatically converted to the correct data types during import (e.g., date columns to datetime, amounts to numbers).
  * Ensures correct filtering, calculations, and visualization in your reports without manual adjustments.

  ***

  ### 📦 **Loads Data Improvements**

  * Loads are imported through two queries:
    * **Full Import**
    * **Incremental Updates**
  * **Automatic deduplication** ensures only the most recent update for each load is kept.

  ***

  ### 🧰 **Consistent Query Structure**

  * All endpoints (Loads, Trips, Users, etc.) now use a **unified paging and expansion pattern**.
  * Makes the model easier to understand, troubleshoot, and extend.

  ***

  ### 📊 **New DAX & Reporting Features**

  * Added several basic DAX formulas (e.g., simple sums, counts, or averages) to help users quickly analyze and familiarize themselves with their data.
  * Created a sample weekly summary report table—aggregates core metrics by week, making it easy to spot trends over time.
  * These examples are intended as a starting point for your own analysis—feel free to adjust or build on them as needed.

  ***

  ### 📘 **Improved Onboarding**

  * **Step-by-step setup instructions** are included to guide you through credential updates and data loading. You can find the link to the latest file and a quick onboarding [guide here](/en/api/guides/power-bi-template-file-fast-setup-guide).

  ***

  *If you have questions or need help migrating, see the included instructions or contact your support team.*
</Update>

<Update label="June 17, 2025" description="Improved Trips Accuracy for Split Loads">
  Release Date: June 17, 2025

  **What’s New?**

  To improve clarity and eliminate confusion in trip reporting, we’ve updated the behavior of the Trips endpoints when handling split loads.

  **What Changed?**

  When a load is split into sub-trips, the original (parent) trip is no longer returned via the API. Only the active sub-trips are included in the response.

  If a load has not been split, the original trip is returned as usual.

  **Endpoints Affected:**

  `GET /api/p/version/trips`

  `POST /api/p/version/trips/search`

  **Why?**

  Previously, both the original (parent) trip and its sub-trips were returned via the API. This could lead to duplicated mileage, carrier amounts, and other values in reports unless the parent trip was manually excluded.<br />With this update, only sub-trips are returned when a load is split — allowing customers to calculate totals (like mileage or carrier amounts) by simply summing all trips returned. This change improves accuracy in any report that relies on trip-level data.

  <br />

  > ❗️ Important Note
  >
  > **This change may impact metrics in your current reports** — such as total trips, total mileage, total carrier rate, and others — **starting today.**
  >
  > If your reporting logic includes custom filters or scripts to automatically exclude the original *(dispatched)* trip when a load is split, those filters may now be obsolete. Since the original trip is no longer returned, continuing to exclude it may result in underreporting.
  >
  > Please review and update any custom reporting logic accordingly to ensure accurate totals going forward.
</Update>

<Update label="June 13, 2025" description="🔐 New Token Endpoint with Granular API Access">
  **Release Date:** June 13, 2025

  ### **What’s New?**

  We’ve introduced improvements to how API access is authorized to enhance security and give customers more precise control over what data and actions their integrations can access.

  ### **What Changed?**

  * A new token endpoint must now be used to generate access tokens:<br />`POST https://auth.alvys.com/oauth/token`
  * Tokens now include permission scopes (e.g.` load:read, trip:create`) that define which resources and actions the client is allowed to access
  * Scope-based access enforcement is enabled for tokens generated via the new endpoint — requests without the proper scope will return 403 Forbidden
  * The legacy `{tenant_id}` token endpoint is deprecated and will be shut down on July 31, 2025<br />(tokens from this endpoint do not include scopes and are treated as read-only for now)

  ### **How to Request a Token**

  To request a token, send a `POST` request to the new endpoint with this JSON body:

  ```json theme={null}
  {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.alvys.com/public/",
    "grant_type": "client_credentials"
  }
  ```

  <Tip>
    When including a "scope" field in the token request body, please note:

    * The returned token will **always include all scopes** that have been granted to your client application, regardless of what you specify in the scope field.
    * Therefore, including a `scope `field in the request **does not override or limit the access** defined by your assigned permissions in the issued token.
    * The only functional effect of providing a `scope` field is that the token request will fail (unauthorized) if you include any scope that has not been granted to your client.
    * If the `scope `field is omitted, the token will still include **all scopes** granted to your application.
  </Tip>

  ### **Endpoints Affected:**

  * ✅ **New (required):** `POST https://auth.alvys.com/oauth/token`
  * 🛑 **Later Deprecated:** `POST /authentication/{tenant_id}/token` (to be removed on **July 31, 2025**)

  <br />

  > ❗️ **Important:**
  >
  > The legacy `POST /authentication/{tenant_id}/token` token endpoint will be **permanently shut down on July 31, 2025**. **All integrations using this authentication flow must be updated to use the new token endpoint before this date to avoid disruption.**
</Update>

<Update label="May 30, 2025 · 6:41 PM" description="Enhanced Carrier Rate Details in Trips Endpoints">
  **Release Date**: June 3, 2025

  **What’s New?**

  The Carrier object in the Trips endpoints now includes additional payment breakdown fields:

  * `Linehaul` — Base transportation cost.
  * `Accessorials` — Additional charges (e.g., fuel surcharges, detention).
  * `TotalPayable` — Full amount payable to the carrier.

  Endpoints Updated:

  `GET /api/p/v1/trips`

  `POST /api/p/v1/trips/search`

  **Why?**<br />These additional fields provide a more detailed view of carrier payments, helping customers with more accurate reconciliation and reporting. It ensures consistency with the financial data seen in the Alvys UI and improves financial transparency in reporting.

  > ❗️ **Important:**  The Rate field in the Carrier object will be deprecated in a future release.
  >
  > **We recommend updating reports and integrations to use the new`Linehaul`, `Accessorials`, and `TotalPayable `fields.**
  >
  > **This change will not happen immediately — there will be a transition period, and we will provide advance notice before the field is removed.**
  >
  > Please review your current usage and plan updates accordingly to ensure a smooth transition.
</Update>

<Update label="May 30, 2025 · 6:36 PM" description="Carrier Endpoints Added to Public API">
  **Release Date**: June 3, 2025

  **What’s New?**

  Two new endpoints have been added to the Public API for Carriers and Subsidiaries:

  `GET /api/p/v1/carriers/'{id}'` — Retrieve detailed carrier or subsidiary information by ID.

  `POST /api/p/v1/carriers/search` — Search carriers or subsidiaries using filters such as Status, MC numbers, DOT numbers, or specific IDs.

  **Why?**<br />These new endpoints improve data accessibility and precision, allowing customers to retrieve only the carrier data they need. This enhancement supports better performance, eliminates unnecessary large data pulls, and aligns the Public API with customer operational needs.
</Update>

<Update label="May 22, 2025" description="Driver Status Visibility Enhancement">
  **Release Date:** May 22, 2025

  **What’s Improved?**

  We’ve updated the Driver endpoints in the Public API to include an `isActive` field, helping external systems easily determine whether a driver is currently active based on their operational status.

  **Added Field:**

  `isActive` – Indicates whether the driver is currently active.

  The value of `isActive` is:

  * ✅ `true` for active
  * ❌ `false` for inactive.

  **Why?**

  Previously, API consumers had to interpret raw status strings to determine activity. Now, the system does that work internally and returns a clear, easy-to-use value - reducing complexity and helping teams filter or display driver activity more reliably.
</Update>

<Update label="May 14, 2025" description="Public API Update – Accurate Pickup & Delivery Timestamps">
  **Release Date:** May 14, 2025

  We’ve fixed an issue where actual pickup and delivery timestamps were incorrectly showing the values in the Public API.

  ✅ What’s Fixed

  `ScheduledPickupAt` and `ScheduledDeliveryAt` reflect the planned schedule

  `PickupDate` and `DeliveryDate` displays actual pickup and delivery timestamp

  Affected Endpoints

  GET /api/p/`v{version}`/loads

  POST /api/p/`v{version}`/loads/search

  Note: No action is required, your integrations will now return the correct values automatically.
</Update>

<Update label="April 18, 2025" description="Maintenance Record Endpoints in the Public API">
  ### What's New?

  Asset maintenance records are now readable through the Public API, enabling fleet maintenance platforms (e.g. FleetRock) and reporting tools to sync maintenance history for trucks and trailers.

  ### What Changed?

  Previously, maintenance records were only visible inside the Alvys platform.

  Now, the Public API includes:

  ```http theme={null}
  GET  /api/p/v{version}/maintenance/{id}
  POST /api/p/v{version}/maintenance/search
  ```

  * **Get maintenance record** — retrieve a single record by id.
  * **Search maintenance records** — search and paginate records.

  ### Response Body Includes

  * Core: `Id`, `PO`, `Reference`, `Description`, `Comments`
  * Classification: `Category`
  * Asset: `RelatedAsset` (the truck or trailer the record belongs to)
  * Financial: `Amount` (value + currency)
  * Shop: `RepairShop` details
  * Scheduling: `Reminders`
  * Audit: `CreatedAt`, `CreatedBy`, `ModifiedAt`, `ModifiedBy`

  ### Why?

  Maintenance spend and history live at the intersection of operations and accounting. Exposing these records lets maintenance vendors and analytics tools stay in sync with Alvys without manual exports.
</Update>

<Update label="April 16, 2025" description="🔐 Token Endpoint Enhancement – JSON Support Added & Stricter Validation Enforced">
  **Release Date:** April 16, 2025

  **What’s New?**<br />The `/token` authentication endpoint now supports requests with Content-Type: `application/json`, in addition to the existing `application/x-www-form-urlencoded` support.

  This change applies to:

  POST /api/authentication/`{tenant_id}`/token

  **Why?**<br />Supporting JSON-formatted requests improves developer experience by aligning with modern integration standards. It allows clients to choose the format that best fits their architecture and ensures consistency across API calls.

  <Warning>
    **Important:** The `/api/authentication/{tenant_id}/token` endpoint now enforces **stricter content-type validation**.<br />Only `application/json` and `application/x-www-form-urlencoded` are supported. Requests using other formats will return a **415 Unsupported Media Type** error.
  </Warning>
</Update>

<Update label="March 26, 2025" description="Trips Endpoint Update: `ReleasedAt` Field Added">
  **Release Date:** March 27, 2025

  What’s New?<br />Added the `ReleasedAt` field to the following Public API Trips endpoints:

  `GET /api/p/v{version}/trips`<br />`POST /api/p/v{version}/trips/search`

  This field indicates the timestamp when the load was marked as "Released".

  Why?<br />Exposing the `ReleasedAt` field allows customers to build more customizable and accurate reports. It ensures consistency with internal data and provides better visibility into load release timelines.
</Update>

<Update label="March 25, 2025" description="Expose CarrierPaymentOnHold Field in Trips Endpoints">
  **Release Date:** March 25, 2025

  What’s New?

  Exposed the `CarrierPaymentOnHold` field in the following Public API Trips endpoints:

  `GET   /api/p/v1/trips`

  `POST   /api/p/v1/trips/search`

  This field indicates whether a carrier’s payment is currently on hold.

  **Why?**

  Previously, API users couldn't determine if a carrier's payment was on hold when retrieving trip data, which created a gap in visibility. By exposing the `CarrierPaymentOnHold` field in the Trips endpoints, users can now programmatically access this critical status to support automation, financial workflows, and operational decisions.
</Update>

<Update label="March 3, 2025" description="New Dispatch Preferences Endpoint">
  **Release Date:** February 28, 2025

  **What’s New?**

  Added a new endpoint `/api/p/v{version}/dispatchpreferences/search` to retrieve dispatch preferences based on filters such as dispatcher, driver, truck, and trailer or dates range.

  **Why?**

  This endpoint was introduced to improve tracking and management of dispatch preferences, enabling more efficient operations.
</Update>

<Update label="February 6, 2025 · 8:55 AM" description="Load Rates Enhancements">
  **Release Date:** February 01, 2025

  **What’s Improved?**

  We’ve updated the Load endpoint to include additional financial breakdowns, making rate calculations more transparent and detailed.

  **Added Fields:**

  * `linehaul `– Base transportation cost.
  * `fuelSurcharge `– Fuel cost adjustments.
  * `customerAccessorials` – Extra charges like detention or lumper fees.

  Why?

  Previously, cost details lacked granularity, making it harder to track financial components. These updates provide clearer visibility into load pricing, helping businesses optimize their cost management.
</Update>

<Update label="February 6, 2025 · 8:48 AM" description="Exposing Asset Events Endpoints">
  **Release Date:** February 01, 2025

  **What’s New?**

  We’ve added three new endpoints to the Public API to provide events updates on truck, driver, and trailer, improving tracking and operational visibility.

  POST /api/p/v\{version}/drivers/events/search – Retrieve driver-related event history.

  POST /api/p/v\{version}/trailers/events/search – Fetch events related to trailers.

  POST /api/p/v\{version}/trucks/events/search – Access historical events for trucks.

  **Why?**

  These changes enhance the API's ability to automate asset event tracking, improve data accuracy, and streamline workflows for better resource management.
</Update>

<Update label="December 13, 2024 · 6:50 PM" description="Updated LoadNumber Search Limit">
  **Release Date**: December 16, 2024

  **What's New?**:

  * **Increased Limit**: The maximum number of loads allowed in the search request body has been increased from **50** to **150**.
    * **Impact**: Users can now include more load IDs in a single search request operation.
    * **Error Handling**: Requests exceeding 150 load IDs will return an error message.
</Update>

<Update label="December 13, 2024 · 6:46 PM" description="Trips Endpoint Enhancement: DispatcherId Added">
  **Release Date**: December 13, 2024

  **What's New?**:

  * **DispatcherId Field**: The `DispatcherId` field is now included in the response body for all trips endpoints.
    * **Purpose**: Provides the unique identifier of the dispatcher assigned to the trip for improved data tracking and integration.
    * **Benefits**: Enhances trip management and reporting by making dispatcher data more accessible through the API.
</Update>

<Update label="November 11, 2024" description="New Endpoints for Visibility Public API">
  #### **Release Date**: November 11, 2024

  ***

  ### **What’s New?**

  1. **Visibility Public API Endpoints**:
     * Introduces endpoints for tracking asset locations and receiving real-time event updates.
  2. **Endpoints Overview**:
     * **Inbound Visibility**:
       * **GET** `/api/p/v{version}/visibility/inbound/{loadNumber}/history`: Retrieve location update history for a specific load number.
     * **Outbound Visibility**:
       * **GET** `/api/p/v{version}/visibility/outbound/{loadNumber}/history`: Retrieve event update history sent for a specific load number.
       * **POST** `/api/p/v{version}/visibility/outbound/errors`: Search for and manually resend failed updates using a time range filter.

  ***

  ### **Usage**

  #### **Inbound Visibility Example**

  ```json theme={null}
  GET /api/p/v{version}/visibility/inbound/{{loadNumber}}/history
  ```

  #### **Outbound Visibility Examples**

  ```json theme={null}
  GET /api/p/v{version}/visibility/outbound/{{loadNumber}}/history
  ```

  #### **Search Failed Updates**:

  ```json theme={null}
  POST /api/p/v{version}/visibility/outbound/errors
  {
    "page": 0,
    "pageSize": 10,
    "timeRange": {
      "start": "2024-11-05T16:58:54.450Z",
      "end": "2024-11-11T16:58:54.450Z"
    }
  }
  ```

  ### **Additional Resources**

  * [API Documentation](/en/api/reference/visibility/get-inbound-visibility-history)
  * [Postman Collection](https://www.postman.com/alvys-public-api-team/alvys-public-api/collection/2p0o9wj/alvys-public-api-collection)

  ***

  ### **Important Notes**

  ⚠️ **Settings for EDI Integration**:

  * All EDI-related configurations must be done within the platform. Contact the support team if assistance is required.

  ***
</Update>

<Update label="November 8, 2024 · 1:11 PM" description="Update for Customer Rate Details field">
  #### **Release Date**: November 08, 2024

  ***

  ### **What’s New?**

  1. **Update to`customerRate.amount` Field**:
     * **Change**: The `customerRate.amount` field now includes the following:
       * `CustomerLineHaul`
       * `FuelSurcharge`
       * `CustomerAccessorials`
     * **Impact**: This ensures alignment with the total customer billable displayed in the UI, improving accuracy for billing and revenue reporting.
  2. **Purpose**:
     * Enhances the clarity and precision of customer rate charges.

  ***

  ### **Usage**

  * The `customerRate.amount` field now reflects the total customer rate, incorporating: Linehaul, Fuel Surcharge, Accessorials).

  **Example Calculation**:

  ```json theme={null}
  "CustomerRate": {
                  "Amount": 5168.0,
                  "Currency": 840
              },
  ```

  ***

  ### **Endpoints Impacted**

  * **GET** `/api/p/v{version}/loads`: [View Documentation](/en/api/reference/loads/get-load)
  * **POST** `/api/p/v{version}/loads/search`: [View Documentation](/en/api/reference/loads/search-loads)

  ***

  ### **Important Note**

  ⚠️ **If you relied on the previous`customerRate.amount` value for revenue reporting, please review your integration. This change corrects the calculation to include Customer Accessorials, which were previously excluded.**

  ***
</Update>

<Update label="November 8, 2024 · 1:07 PM" description="New Endpoints for Customer Data Management">
  #### **Release Date**: November 11, 2024

  ***

  ### **What’s New?**

  1. **New GET and POST Endpoints Introduced**:
     * **GET Endpoint**:
       * **`/api/p/v{version}/customers`**: Retrieves detailed customer profiles, including contact information and associated data, by `id` or `companyNumber`.
         **Example Request**:
       ```json theme={null}
       GET /api/p/v{version}/customers?id=12345
       //or
       //GET /api/p/v{version}/customers?companyNumber=12345
       ```
     * **POST Endpoint**:
       * **`/api/p/v{version}/customers/search`**: Supports advanced filtered searches for customer records by status, or date range. Includes pagination for optimized data access.
         **Example Request**:
       ```json theme={null}
       POST /api/p/v{version}/customers/search
       {
         "page": 0,
         "pageSize": 100,
         "statuses": [
           "Active"
         ],
         "createdDateRange": {
       //     "start": "2024-11-08T19:38:34.529Z",
       //     "end": "2024-11-08T19:38:34.529Z"
         }
       }
       ```

  ***

  ### **Purpose**

  * Provides flexibility for retrieving and searching customer data.
  * Enables streamlined workflows for integration, automation, and reporting.

  ***

  ### **Additional Resources:**

  * [API Documentation](/en/api/reference/customers/list-customers)
  * [Postman Collection](https://app.getpostman.com/run-collection/39138316-54c493c3-15e5-4fd7-a651-6e45b308548f?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D39138316-54c493c3-15e5-4fd7-a651-6e45b308548f%26entityType%3Dcollection%26workspaceId%3Dc0255544-5964-4c52-9d24-05b30a9b021c)

  ***
</Update>

<Update label="October 18, 2024 · 11:49 AM" description="Enhancements to Load Management with New Assignment Fields">
  ### **What’s New?**

  1. **New Fields Added to Load Endpoints response body**:
     * **`customerServiceRepId`**: Customer Service Representative assigned to the load.
     * **`customerSalesAgentId`**: Customer Sales Agent responsible for the load.
     * **`customerSalesManagerId`**: Customer Sales Manager assigned to the load.
     * **`customerLoadPlannerId`**: Customer Sales Manager assigned to the load.
     * **`carrierSalesAgentId`**: Carrier Sales Agent assigned to the load, enabling customers to attribute credit and calculate commissions for securing the carrier.
  2. **Purpose**:
     * Enhances transparency in load assignments.
     * Streamlines tender management and load tracking processes.

  ***
</Update>

<Update label="October 18, 2024 · 5:43 AM" description="Including `UpdatedAt` and `UpdatedBy` to Load and Trip Endpoints">
  #### **Release Date**: October 18, 2024

  ***

  ### **What’s New?**

  1. **New Fields Added to Load and Trip Endpoints**:
     * **`UpdatedAt`**: Timestamp of the last modification.
     * **`UpdatedBy`**: User ID responsible for the last update.
  2. **New Parameters Added to Load and Trip Search body**:
     * `UpdatedAtRange`: Search by update timestamps using `start` or `end` date.
     * `UpdatedBy`: Search by the user who made updates.

  ```json theme={null}
  {
      "updatedAtRange": {
          "start": "2024-10-18T04:38:53.470Z",
          "end": "2024-10-19T04:38:53.470Z"
      },
      "updatedBy": "user123"
  }
  ```

  3. **Conditionally Mandatory Parameters**<br />At least **one search parameter** from the list of conditionally mandatory parameters must be provided. If no parameter is included, the following error message will be returned:

  ```json theme={null}
  {
      "Status": [
          "At least one search parameter must be provided"
      ],
      "PONumbers": [
          "At least one search parameter must be provided"
      ],
      "UpdatedBy": [
          "At least one search parameter must be provided"
      ],
      "CustomerId": [
          "At least one search parameter must be provided"
      ],
      "LoadNumbers": [
          "At least one search parameter must be provided"
      ],
      "OrderNumbers": [
          "At least one search parameter must be provided"
      ]
  }
  ```
</Update>

<Update label="July 5, 2024" description="Public API Initial Offering">
  We're excited to announce the initial offering of the Alvys Public API! This release marks a new era of integration and customization for our platform.

  Highlights:

  * **Public API Launch**: Our Public API is now available, providing developers with secure and flexible access to Alvys' core functionalities.
  * **Comprehensive Documentation**: Extensive guides and resources are available to facilitate smooth integration and implementation.
  * **Key Features**: The API includes endpoints for users, trucks, trailers, drivers, loads and trips, and more, designed to allow for easy extraction of data from Alvys.

  *Note: This is the initial release of our Public API, and we are committed to continuously expanding and improving its capabilities. Feedback and suggestions are welcome as we refine and grow our offerings.*

  Stay tuned for more updates and features! 🚀
</Update>


# Export delivery logs
Source: https://docs.alvys.com/en/api/reference/webhooks/export-delivery-logs

GET /api/p/v{version}/webhooks/{webhookId}/delivery-logs/export
Downloads delivery logs as CSV or JSON using the same filters as the list endpoint. Format resolution: (1) optional query parameter <c>Format=csv</c> or <c>Format=json</c> overrides everything when present; (2) otherwise the <c>Accept</c> header is used (<c>text/csv</c>, <c>application/csv</c>, <c>application/json</c>, or <c>*+json</c>); (3) otherwise the response defaults to JSON. Page (0-based) is the last list page index to include: pages 0 through Page are read, each with PageSize items (max 100, default 50), up to 25,000 rows total. This matches the delivery-log UI, which sends the highest page the user has loaded. Page=0 exports only the first page.

Downloads delivery logs as CSV or JSON using the same filters as the list endpoint. Format resolution: (1) optional query parameter `<c>`Format=csv`</c>` or `<c>`Format=json`</c>` overrides everything when present; (2) otherwise the `<c>`Accept`</c>` header is used (`<c>`text/csv`</c>`, `<c>`application/csv`</c>`, `<c>`application/json`</c>`, or `<c>`\*+json`</c>`); (3) otherwise the response defaults to JSON. Page (0-based) is the last list page index to include: pages 0 through Page are read, each with PageSize items (max 100, default 50), up to 25,000 rows total. This matches the delivery-log UI, which sends the highest page the user has loaded. Page=0 exports only the first page.


# Get delivery log detail
Source: https://docs.alvys.com/en/api/reference/webhooks/get-delivery-log-detail

GET /api/p/v{version}/webhooks/{webhookId}/delivery-logs/{logId}
Returns full detail of a single delivery attempt including response body and entity metadata.

Returns full detail of a single delivery attempt including response body and entity metadata.


# Get webhook health metrics
Source: https://docs.alvys.com/en/api/reference/webhooks/get-webhook-health-metrics

GET /api/p/v{version}/webhooks/{webhookId}/health
Returns aggregated delivery health metrics for a webhook over 1, 7, or 30 days.

Returns aggregated delivery health metrics for a webhook over 1, 7, or 30 days.


# List delivery logs
Source: https://docs.alvys.com/en/api/reference/webhooks/list-delivery-logs

GET /api/p/v{version}/webhooks/{webhookId}/delivery-logs
Returns paginated delivery logs for a webhook with optional status, event type, and date range filters.

Returns paginated delivery logs for a webhook with optional status, event type, and date range filters.