> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # Carrier Invoice Processing > Carrier Invoice Processing uploads freight, duty and tax, and surcharge invoices, extracts their charges and matches them to your shipments. **Available to all Logistics customers.** Invoice upload must be enabled for your organization. Users with the Administrator role or a finance role can upload, delete and export invoices; other users see shipment-level costs when the Shipping Cost section is enabled. ## Summary Carrier Invoice Processing lets you upload the invoice files your carriers send, extracts the charges from them and matches each billed shipment to the shipment in your portal by tracking number. Freight, duty and tax, and surcharge invoices are supported, so a shipment’s total cost covers everything the carrier billed for it. ## Who it’s for Logistics operations managers who receive invoice files on the carrier’s billing cycle, and finance teams who need every charge attached to the shipment it belongs to before month-end close. It replaces manual re-keying of invoice lines into spreadsheets. ## Key benefits * **One upload flow for every invoice type.** Freight, Duty & Tax and Other Charges invoices are uploaded in the same place with the same steps. * **Charges land on the shipment.** Costs are allocated to shipments by tracking number, and one shipment can carry several invoices while one invoice covers many shipments. * **Surcharge type is detected for you.** For Other Charges invoices you do not pick the surcharge type; it is identified from the file and shown as its own line item. * **Status and notifications.** Each invoice moves from Processing to OK or Failed, and you receive an email when processing finishes. * **Invoice history stays in the portal.** The invoice table keeps every upload with its status, uploader and original file for download. ## How it works ### Invoice types | Invoice type | What it contains | File format | Notes | | - | - | - | - | | Freight | Shipping cost line items | PDF or CSV, depending on the carrier | Existing invoices without a type are treated as Freight. | | Duty & Tax | Customs duty and tax line items | ZIP containing exactly one PDF (invoice summary) and one Excel file (per-shipment breakdown), both carrying the same invoice number | Currently supported for Aramex. | | Other Charges | Surcharge invoices, for example remote area surcharge, airport handling fee, address correction charge, return charge or import processing charge | PDF for a single-shipment invoice, or ZIP (PDF summary plus Excel per-shipment breakdown) for a multi-shipment invoice | One file per upload. Enabled per carrier and per surcharge type. | An invoice is identified by its Invoice Type plus Invoice No., so the same invoice number can exist as a Freight and as a Duty & Tax invoice without conflict. Each carrier’s invoice format is integrated for your organization before you can upload it. During onboarding you provide sample invoices (and rate cards, duty tables and contracts where relevant) for each carrier you want processed. For a carrier that is not yet integrated, contact your account team. ### Upload rules * Up to 5 files per upload, 50 MB in total. For Other Charges, one file per upload. * In the upload dialog you choose the carrier and the invoice type. Only carriers configured in your organization are offered, and only the invoice types supported for the selected carrier. The upload area is enabled once both are set. * A ZIP for Duty & Tax must contain exactly one PDF and one Excel file; any other count is rejected with the message “ZIP file must contain exactly 2 files (1 PDF and 1 CSV)”. * When you select Other Charges, a helper line confirms that the surcharge type is detected automatically from the file. ### Processing statuses | Status | Meaning | What you get | | - | - | - | | Processing | The file was received and is being extracted. | Nothing to do yet. Keep the page open until the status shows. | | OK | Extracted and matched. Shipment-level costs appear in the Shipping Cost section wherever a tracking number matched. | Success email. | | Failed | The file could not be processed, for example a corrupted file, incomplete data or an unsupported layout. | Failure email with guidance to re-upload a corrected file. | The invoice details header is green for OK, yellow for Processing and red for Failed. A failed Other Charges invoice shows one of two messages: a general processing error, meaning the Perform.AI team has been notified, or “Unsupported Invoice Type”, meaning that surcharge type is not yet enabled for your carrier and needs to be enabled before you re-upload. ### Matching to shipments Invoiced shipments are matched to portal shipments by tracking number or shipment reference, regardless of shipment status. A shipment can be linked to several invoices (for example one Freight and one Duty & Tax) and one invoice can cover many shipments. The shipment’s total cost is the sum of all its linked, successfully processed invoices; uploading a surcharge invoice adds to the freight cost rather than replacing it. Shipments that appear on an invoice but not in the portal are counted as Shipments Not in Portal on the Invoice Overview dashboard. ### Surcharge invoices For Other Charges invoices the specific surcharge type is identified from the file content. Each surcharge becomes its own line item in the shipment’s Cost Breakdown (for example “Remote Area Surcharge”), and the Invoices table on the shipment lists the invoice under that specific type with a tooltip naming the charges it covers. For some surcharge types the rate-card rate can only be determined after the invoice is processed; for those, a rate-card recalculation runs automatically once processing finishes so the comparison is ready without a manual step. Previously processed invoices are not remapped when a new surcharge type is enabled. ### Duplicates and deletion * **Duplicate upload.** If you upload an invoice with the same Invoice Type and Invoice No. as an existing one, the new file is processed and you receive an email asking you to delete the old one. Both stay in Invoice Overview until you delete the old one. For Other Charges invoices, duplicate detection is not available. * **Same type, different number.** The invoice is processed and the shipment costs update with the latest data. * **Deletion.** Invoices of any status can be deleted, individually from the invoice details header or in bulk from Invoice Overview. Deleting removes the linked shipment-level costs and recalculates the dashboard, the invoice table and the shipment costs. The confirmation reads “Deletion in progress. This may take some time.” ### Invoice Overview table | Column | Content | | - | - | | Status | OK, Processing or Failed | | Carrier | Carrier name | | Invoice ID | System-generated identifier, searchable in Shipment Overview | | Invoice No. | The carrier’s invoice number | | Invoice Type | Freight, Duty & Tax or the detected surcharge type | | Invoice Date | Date on the carrier invoice | | Shipments | Number of shipments on the invoice | | Total Cost, Avg Cost | In your display currency, with a conversion icon when converted | | Uploaded By | Email of the user who uploaded it | | Last Updated, Date Added | Upload time or last status change | | Download | The original invoice file | All columns except Download are sortable; the default sort is Last Updated descending. Filters for Status, Carrier, Invoice Type, Invoice Date, Invoice No. and Date Added (default: the past year) combine with AND. ### Languages Line item names and the “Charges covered” tooltip are available in German, Spanish and French, falling back to English where no translation exists. Invoice type names in the table and its filter stay in English. ## Set up in the portal 1. Go to **Cost Audit** > **Invoice Overview** and select **Upload Invoice**. 2. Choose the carrier and the invoice type (Freight, Duty & Tax or Other Charges). 3. Add the file or files and submit. Keep the page open until the invoice shows Processing. 4. Wait for the email. When the status is OK, open the invoice row to check the Service Overview and Cost Breakdown, or select **View Invoiced Shipments** to see the matched shipments. 5. If the status is Failed, read the error on the invoice, correct the file and upload again. > [!TIP] > > Upload invoices on the carrier’s billing cadence, weekly or monthly, so the Invoice Coverage Summary for each month is complete. ## Use via API and MCP Invoice upload is portal-only; there is no REST endpoint. From an AI assistant connected through the [Perform.AI MCP](https://developers.perform.ai/mcp/overview.md), `list_invoices`, `get_invoice_detail` and `get_invoice_stats` list your invoices, open one with its cost breakdown and return invoice statistics. See [Installation](https://developers.perform.ai/mcp/installation.md) and [Tools](https://developers.perform.ai/mcp/tools.md). ## FAQ ### Which file formats can I upload? Freight invoices in PDF or CSV, depending on the carrier. Duty and tax invoices as a ZIP with exactly one PDF and one Excel file. Surcharge (Other Charges) invoices as a PDF, or a ZIP with a PDF summary and an Excel breakdown for multi-shipment invoices. ### Does a surcharge invoice overwrite the freight cost? No. Costs are additive. The shipment total is the sum of all linked invoice types; the freight cost stays as it was and the surcharge is added on top. ### Why don’t I see any carriers after choosing Duty & Tax? The carrier list only shows carriers configured for your organization that support that invoice type. Duty and tax processing is currently supported for Aramex; check **Settings** > **Carriers** to confirm the carrier is configured. ### What happens if my carrier sends a surcharge type you have not seen before? The upload fails with “Unsupported Invoice Type”. Ask your account team to enable the surcharge type for that carrier, then upload the invoice again. ### Can I upload several surcharge files at once? Not for Other Charges; each upload takes one file. Freight uploads accept up to 5 files and 50 MB in total. ### I uploaded the same invoice twice. What now? The newer one is processed and you receive an email asking you to delete the older one. Delete it from Invoice Overview; the costs are recalculated. ## Troubleshooting | Symptom | Cause | Fix | | - | - | - | | **Upload Invoice** is not visible | Invoice upload is not enabled for your organization | Ask your account team to enable it. | | ZIP upload is rejected | The ZIP does not contain exactly one PDF and one Excel file | Repackage the ZIP with the two files, both carrying the same invoice number. | | Invoice fails with “Unsupported Invoice Type” | The surcharge type is not enabled for this carrier | Ask your account team to enable it, then re-upload. | | Invoice is OK but shipments show no Invoice Cost | Tracking numbers on the invoice do not match shipments in the portal | Check the Shipments Not in Portal count on the dashboard and the tracking numbers sent with your shipments. | | Processing never finishes | The file is corrupted or incomplete | Check the failure email, correct the file and upload again. If no email arrives, contact your account team. | ## Related * [Shipping Cost Audit](https://developers.perform.ai/products/logistics/shipping-cost-audit.md) * [Rate Card Management](https://developers.perform.ai/products/logistics/rate-card-management.md) * [Cost Disputes Management](https://developers.perform.ai/products/logistics/cost-disputes-management.md) * [Logistics overview](https://developers.perform.ai/products/logistics/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.