> ## 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. # Rate Card Management > Rate Card Management lists your carrier rate cards with version, validity and status, and lets you upload and activate new versions in the portal. **Available to all Logistics customers.** Rate Card Overview must be enabled for your organization, and at least one carrier rate card must already be set up by Perform.AI. Users with the Administrator role can view the rate cards linked to a carrier in carrier settings. ## Summary Rate Card Management shows every carrier rate card your organization has on file, which version is live, how each card is set up and which carrier reference it applies to. When a carrier sends updated rates, you upload the new version yourself, it is validated against the existing card, and it starts calculating shipping costs only once you activate it. ## Who it’s for Logistics operations managers who maintain carrier rate cards through annual or contractual rate changes, and finance and procurement teams who need to see which rates applied to a shipment on a given date. It removes the support ticket for routine rate updates while keeping a new file from affecting live cost calculation until it has been checked. ## Key benefits * **Routine rate updates without a ticket.** A newer version of a rate card Perform.AI has already integrated is uploaded directly in the portal. * **Clear version history.** Every card carries a version, a validity period and a status, so it is obvious which card is live, which is scheduled and which is historical. * **Safe by default.** Each upload is validated in two steps, and a new version only affects cost calculation after you activate it. * **Auditable.** The read-only details show the carrier, shipping service, currency, weight configuration, fuel surcharges and source files behind each card, with the original files available for download. * **Rates resolve per carrier reference.** Each carrier reference is linked to the rate card for its shipping service, and the card used for a shipment is shown in its Shipping Cost section. ## How it works ### What you can upload yourself Self-service upload covers a newer version of a rate card that is already set up: same carrier, same file format and structure, same calculation logic, no new surcharge types, only the rate values differ. A new carrier, a new file format, a new charge type, a new destination or anything needing new calculation logic is set up by Perform.AI; use **Contact support** in the upload dialog to request it. Rate cards are processed from Excel (XLSX) files. Each carrier’s rate card structure is unique, so every new rate card is reviewed by Perform.AI before it is integrated. ### Rate Card Overview table Go to **Shipping Cost Audit** > **Rate Card Overview**. The header shows the total count, for example **All Rate Cards (15 rate cards)**, and an **Upload Rate Card** button. The table lists one row per carrier and shipping service. A rate card that covers several shipping services appears as several rows, because each service has its own calculation set-up. | Column | Content | | - | - | | Carrier | Carrier name | | Shipping Service | The service the card prices; `-` when the carrier has none | | Status | Draft, Processing, Active, Scheduled, Failed or Expired | | Version | Shown for Scheduled, Active and Expired cards only | | Rate Card ID | Readable identifier, unique in your organization | | Validity Period | Start and end date, or no end date | | Carrier Reference | The carrier reference the card is linked to | | Last Updated, Date Added | Timestamps | Default sort is Last Updated descending; all columns are sortable and resizable. Page size can be 10, 20 or 50 rows. Missing values show `-`. **Rate Card ID** is `{carrierID}_{shipping-service-slug}_{version}`, for example `UPS_international-express_V1`, or `{carrierID}_{version}` for a card without a shipping service. Each card also has an immutable Rate Card UUID. Versions you upload increment the major version (1.0, 2.0, 3.0); minor versions (1.1, 1.2) are reserved for changes made by Perform.AI. ### Search and filters Search matches Rate Card ID and Rate Card UUID, partial and case-insensitive. Filters are Date Added, Carrier, Status, Shipping Service, Validity Period and Carrier Reference, all multi-select; search and filters combine with AND, and **Clear all** resets them. The Validity Period filter matches any card whose validity range overlaps the selected range, inclusive of the boundary days. A card with no end date matches whenever its start date is on or before the end of the selected range. The filter ignores status, so Scheduled and Expired cards appear if their dates fall in the window. ### Uploading a new version **Upload Rate Card** opens a dialog for a new version of a rate card already set up for your carrier. | Field | Rule | | - | - | | Carrier | Required. Only carriers you already have rate cards for, with their accepted file types. | | Shipping Service | Multi-select, shown when the card has services; displays the linked carrier reference. `-` for cards without a service. | | Rate Card Name | Required. Free text. | | Version | Generated by the system, read-only. | | Validity Start, Validity End | Required. End date offers **No end date** for open-ended cards and cannot be earlier than the start. | | Timezone | Required, in Region/Country format. | | Upload File | Required. Click or drag and drop. Up to 5 files of 50 MB each; formats restricted per carrier. A tooltip lists the previously uploaded file names. | The Upload button stays disabled until the required fields are filled. If a card for the same carrier and shipping service is still Processing, the upload is blocked with an error. Selecting two shipping services creates two rate card records; updating only one of them creates a new version for that service only. ### Validation On submit the card enters Processing and runs two checks in order: 1. **Structure.** The file is compared with the layout saved for that carrier and shipping service at first set-up: number and type of files, number of sheets, column labels and order, and overall layout. Any structural change fails the upload. Keep the same sheets as the previous version, including a fuel surcharge sheet, even if the surcharge is sourced from the carrier’s website. 2. **Calculation match.** Runs only if the structure passes. The new file is used to recalculate a set of sample shipments created for the rate card at set-up, and the result is compared with the current version: the same cost components must be present with the same names, and the total cost must stay within a tolerance. Any sample shipment that fails, fails the upload. If both pass, the card moves to **Draft**. If either fails, the card moves to **Failed** with an **Upload error details** banner listing the issues, in these standard messages: * The number of files or the file type wasn’t what we expected for this carrier. * This file doesn’t have the expected number of sheets for this carrier’s rate card. * Some columns are missing, in a different order, or labelled differently from the expected template. * The overall layout of this rate card doesn’t match the expected template for this carrier. A failure also notifies the Perform.AI team with the detected differences. You receive an email on both outcomes, with a link that opens the card’s details. The live rate card is untouched by a failed upload. ### Status lifecycle | Transition | Trigger | | - | - | | Processing to Draft | Upload passes both checks | | Processing to Failed | Upload fails a check | | Draft to Active | You activate the card while the current date is inside its validity period | | Draft to Scheduled | You activate the card while its validity start is in the future | | Scheduled to Active | Automatic, on the validity start date | | Active to Expired | Automatic, when the validity end date passes | ### Activating a Draft card A Draft card is visible and auditable but not used for cost calculation. **Activate** appears in the footer of the details panel for Draft cards only. A confirmation explains that the card will be used to calculate shipping costs for all future shipments matching its carrier reference and validity period, that existing shipments keep their current values, and that the card cannot return to Draft. On confirmation the card becomes Active or Scheduled and a banner confirms it. ### Which card applies to a shipment Overlapping validity periods are allowed. When more than one card could apply, the card with the latest effective start date and version at the shipment’s event time is used. An Expired card is still used for shipments whose event time falls inside its historical validity window, including late-arriving events, so past shipments keep the rate that applied to them. Rate cards and fuel surcharges store date, time and timezone. When a shipment event occurs, the event time, the card’s validity and the surcharge periods are all converted to UTC before comparison. ### Rate card details Click a row to open the read-only details panel. It shows the carrier, Rate Card Name, Rate Card ID, Rate Card UUID, Version, Currency, Validity Period and Shipping Service (UUID, version, currency and ID are hidden for Processing and Failed cards), an error banner for Failed cards and an information banner for Expired cards, then: * **Linked Carrier References.** The carrier reference the card resolves for, linking to the carrier’s settings. Draft cards state that references are linked automatically or set up after activation; Processing and Failed cards show no references. * **Weight Configuration.** Weight Type (Shipment Weight, Volumetric Weight, or Higher of Shipment or Volumetric) and the volumetric divisor used to convert dimensions into volumetric weight where the carrier bills by volume. * **Calculation Settings.** The cost calculation trigger, which is First Shipping Milestone. * **Fuel Surcharges.** Per shipping service: the Fuel Surcharge Discount percentage, the source (the carrier’s published page, linked, or Manual Input) and a table of Period, Carrier Rate, Applied Rate (the carrier rate after your discount) and Last Updated. Rows are ordered by period, the current period is highlighted, and periods with no published rate yet are shown empty rather than omitted. Twelve periods of history are kept, six per page. * **Documents.** The source files, each downloadable. ### Linking rate cards to carrier references Each carrier reference maps to exactly one shipping service; a brand that needs several shipping services for one carrier maintains several carrier references. The **Linked Rate Card** section under **Settings** > **Carriers** > carrier reference > **Carrier Details** shows which card resolves for that reference, and warns when no Active card exists or only an Expired one. Linking is automatic when the carrier has no shipping service, or exactly one; when a card covers several shipping services you select the service on the carrier reference. Only cards that have been or will be live can be linked: Active, Scheduled and Expired. Draft, Processing and Failed cards cannot. The shipping service comes from the carrier reference, not from the shipment, so shipments do not need to carry a shipping service for cost calculation. A mapping from your own service codes (for example `P1`) to the carrier’s service names is set up during onboarding. ### Where rate-card rates appear The card used for a shipment is shown in the Shipping Cost section of Shipment and Booking Details, with the Rate-Card Rate column. A shipment needs a weight or dimensions for a rate to be calculated; with both, the higher of the shipment weight and the volumetric weight is used, as set in the card’s Weight Configuration. When calculation is skipped, an issue icon next to Rate-Card Rate gives the reason: missing weight and dimensions, no rate card for the carrier, destination not covered, or service not covered. Rate card and invoice must be in the same currency; domestic shipments are not processed. ### Languages The interface and tooltips are available in German, Spanish and French, set under **My Profile** > **Portal language**, with English as the fallback. ## Set up in the portal 1. Go to **Shipping Cost Audit** > **Rate Card Overview** and select **Upload Rate Card**. 2. Choose the carrier and, if offered, the shipping services the new version covers. 3. Enter a rate card name, the validity start and end dates (or **No end date**) and the timezone. 4. Add the file or files from the carrier and select **Upload**. The card shows as Processing. 5. When the email arrives, open the card. A Draft card has passed validation: review its details and select **Activate**. A Failed card shows the error banner; correct the file structure or contact support if the carrier changed its format. 6. Under **Settings** > **Carriers**, open the carrier reference and check **Linked Rate Card**. If the card covers several shipping services, select the service for that reference. > [!TIP] > > Activate renewed cards before their validity start date. The card sits in Scheduled and goes live on the start date without further action. ## FAQ ### I uploaded a new rate card and my shipping costs did not change. Why? A card that passes validation lands in Draft, not Active. Open its details and select **Activate**. It becomes Active immediately, or Scheduled if its validity start is in the future. Existing shipments keep their already-calculated values either way. ### My carrier sent a new format with a new surcharge. Can I upload it? No. Self-service upload only handles a newer version of a card that is already set up, with the same format and structure. Use **Contact support** in the upload dialog; Perform.AI integrates the new format. ### Why do two cards have overlapping validity periods? Overlaps are allowed. When more than one card could apply, the card with the latest effective start date and version at the shipment’s event time is used. ### Why does my card show no version number? Versions are assigned once a card has reached Scheduled, Active or Expired. Processing, Draft and Failed cards have none. ### Why is a fuel surcharge row empty for the current month? The carrier has not published a rate for that period yet. The row is shown so the gap is visible, and it fills once the rate is available. ### I selected two shipping services in one upload. Why are there two rows? The overview lists one row per carrier and shipping service, because each service has its own calculation set-up. One upload covering two services creates two records, each with its own version. ## Troubleshooting | Symptom | Cause | Fix | | - | - | - | | **Rate Card Overview** is missing from the navigation | The page is not enabled for your organization | Ask your account team to enable it. | | Upload fails with a sheets or columns message | The carrier changed the file structure, or a sheet was removed | Restore the previous structure (including unused sheets) and upload again; if the carrier genuinely changed the format, contact support. | | Upload is blocked with an error toast | A card for the same carrier and shipping service is still Processing | Wait for that upload to finish, then retry. | | Rate-Card Rate shows `-` on shipments for a carrier with an Active card | The carrier reference has no linked card, no shipping service selected, or the shipment lacks weight and dimensions | Check **Linked Rate Card** on the carrier reference and the shipment’s weight or dimensions. | | The Linked Rate Card section shows a red warning | Only an Expired card is linked to the carrier reference | Upload and activate a new version. | ## Related * [Shipping Cost Audit](https://developers.perform.ai/products/logistics/shipping-cost-audit.md) * [Carrier Invoice Processing](https://developers.perform.ai/products/logistics/carrier-invoice-processing.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.