> ## 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. # Performance Aspirations > Define the transit time you expect from each carrier, warehouse or leg of the journey; every shipment is marked compliant or breached on your calendar. **Available to all AI Decision Intelligence customers.** Performance Aspirations is switched on per account. If it does not appear in your menu, contact your account team. ## Summary Performance Aspirations lets you define the transit time you expect from each service provider, such as carriers, warehouses and distribution centres, or from any leg of the shipment journey, and measures every matching shipment against it automatically. Each shipment is marked compliant or breached on your own terms: your working days, cut-off times, public holidays and timezone. ## Who it’s for Logistics teams whose SLA report is rebuilt by hand every month, or whose transit time numbers never match what was agreed with the carrier because they count calendar days. Data and IT teams use the results through the API and webhook to feed their own scorecards. ## Key benefits * **Compliance becomes a result, not a project.** Every shipment is evaluated the moment it reaches the end milestone of its category, with no manual tracking. * **Measured on your calendar, not the carrier’s.** Each rule carries its own working days, per-day cut-off times, public holidays by origin or destination country, and timezone. * **Each provider is measured on its own leg.** Categories are built from a start and an end milestone, so a warehouse, a carrier, customs or the last mile can each carry its own standard. * **Rules go live in minutes.** Create rules one at a time in the portal or hundreds at once by CSV, and change them yourself when a carrier changes its commitments. * **One standard, carried through.** The same rules power compliance charts in Business Intelligence, a transit time metric in AI Performance Alerts and the SLA breach rate in AI Recommendations. ## How it works Performance Aspirations is configuration before it is output: a category, a rule, a calendar. The first time it is switched on, a sample **Warehouse** category with draft rules is created so you have something to start from. ### Categories A category is any leg of the journey you want to measure. You name it and pick its start and end milestone, and that pair is what starts and stops the clock. A category can represent a type of service provider or a stretch of the journey: | Example category | Start milestone | End milestone | | - | - | - | | Warehouse | Order placed | Pickup | | Reseller or drop-shipper | Order placed | First shipping event | | Carrier | First shipping event | First delivery attempt | | Customs | Pre-alert with carrier | Customs completed | | Line haul | First shipping event | First out for delivery | | Last mile | First out for delivery | First delivery attempt | | Returns | Any start milestone | Return to sender | | Rule | Limit | | - | - | | Categories per organisation | Up to 20 | | Category name | Unique within your organisation | | Milestones | Start and end must differ, and the end milestone must follow the start milestone in the standard sequence (custom milestones are exempt) | You can edit a category’s name or milestones at any time; updates apply only to shipments not yet evaluated. A category can be deleted only while all its rules are in Draft status, and deleting it removes those draft rules. ### Milestones Categories are built from 13 standard milestones: 9 that fire in sequence from order placed through to final delivery, and 4 that fire independently. | Sequential milestones | Independent milestones | | - | - | | Order placed | Drop-off at collection point | | Fulfillment started | First issue exception event | | Pre-alert with carrier | Return to sender | | Pickup | Last event | | First shipping event | | | Customs completed | | | First out for delivery | | | First delivery attempt | | | Final delivery / collected at collection point | | The sequential chain is kept in chronological order, so inaccurate carrier data cannot produce a negative transit time. Where your own start or end event maps to none of the standard milestones, up to 5 custom milestones per organisation can be built by Perform.AI and then selected like any other. ### Rules A rule is the expected transit time for a specific slice of shipments within a category. You name each rule, so the list reads like your own network: USPS US Domestic, DHL China to North America, FedEx International. | Field | Rule | | - | - | | Rule name | Required. | | Filters | Optional. Carrier, linked shipment carrier, destination country, origin country, tag, origin postcode, destination postcode, sender address, shipping service, origin state, destination state. One value per filter field. A rule with no filters catches every shipment that reaches the end milestone. | | Working days | Required. Which days count. Default Monday to Friday. | | Cut-off time | Optional. A per-day cut-off; it can differ by day, for instance 18:00 on weekdays and 12:00 on Saturdays. | | Timezone | Required. IANA identifier such as `Europe/Berlin` or `Asia/Singapore`. Default `Europe/Berlin`. | | Public holiday | Required. Apply holidays from the origin country, the destination country or both. Default both. | | Expected transit time | Required. An integer, in days or hours. | | Priority | Optional, 1 to 100. Controls which rule applies when several match the same shipment; a lower number is evaluated first. | | Limit | Value | | - | - | | Rules per organisation | Up to 1,000 | | CSV upload | Up to 3 MB per file | **Rule matching.** A shipment must match all of a rule’s filters. When several rules match, the most specific rule applies first; equally specific rules are ordered by priority, and if no priority is set the earliest-created rule wins. Rules are normally written to be mutually exclusive, so priority is an edge case rather than part of the standard setup. **Rule status.** A rule is either **Draft** (not evaluating) or **Active** (evaluating matching shipments). Activating starts calculation for shipments that reach the end milestone from then on; deactivating returns the rule to Draft and stops it for future shipments. Only Draft rules can be deleted, so an Active rule has to be deactivated first. Editing a rule never recalculates shipments already evaluated. ### The business calendar Measured transit time is counted in working days only, using the rule’s calendar: * Non-working days are not counted. * When the start milestone falls after the day’s cut-off time, the count begins on the next working day. * Public holidays in the origin country, the destination country or both are excluded, depending on the rule. * All milestone timestamps are converted to the rule’s timezone before the calculation, so cut-offs and day boundaries reflect where the operation runs. The measured time is compared with the expected transit time. Within it, the shipment is **Compliant**; over it, **Breached**. ### Bulk management by CSV Within a category, **Upload File** opens a dialog with a downloadable CSV template and a setup guide covering the concepts, worked examples and what each field does. The file is validated on upload for format and size. On success you choose **Close** (new rules created as Draft) or **Activate** (new rules created and set Active). On failure you download an error report, the original data with an error column, fix it and re-upload. A row with a rule ID updates that rule; a row without one creates a new rule. To update a carrier’s commitments after a network change, export the category’s rules, edit the values and re-upload. Selecting rules in the list enables bulk **Export**, **Activate**, **Deactivate** and **Delete**. Delete skips any Active rules in the selection. When every rule is selected, you choose whether the action applies to the current page or to all rules in the category. ### Results A shipment is evaluated when it reaches the end milestone of a matching category. Shipments still in transit have no result yet. * **Shipment Details.** A **Performance Aspirations** section lists, per evaluation, the category, the rule that matched, the start and end milestone, the expected result, the measured result and the outcome. Hover the expected and measured results to see the transit time values. * **Tags.** Each evaluated shipment carries a compliant or breached tag named after its category. Use it in shipment filters, chart filters and alert filters. * **Business Intelligence.** The **Transit Time (Performance Aspirations)** and **On-time rate (Performance Aspirations)** report templates and every chart prefixed **(Performance Aspirations)** run on the measured transit time. Apply the Performance Aspirations category filter to read one category at a time. Charts include compliance scorecards, a compliance rate map by country and a performance-by-market table. * **AI Performance Alerts.** The **Transit Time (Performance Aspirations)** metric, as an average, median, P90 or P95, filtered to one category. * **AI Recommendations.** The SLA breach rate metric is calculated from your rules. * **API and webhook.** From API and webhook version 5.3.0, the shipment payload carries one object per evaluation with the category name, rule name, outcome, expected and measured transit time with its unit, the start and end milestone types and timestamps, and the evaluation date. A shipment with no evaluations, or still in transit, returns an empty array. ## Set up in the portal Go to **AI Decision Intelligence** > **Performance Aspirations**. 1. Select **Create**, enter a category name and choose the **Start Milestone** and **End Milestone**, then **Save**. 2. Within the category, select **Create Rule**. Name the rule, add the filters that identify the shipments it covers, set the working days, cut-off time, timezone and public holiday setting, and enter the expected transit time. 3. **Save** to keep the rule as a draft, or **Activate** to start evaluating shipments immediately. 4. To load many rules at once, select **Upload File**, download the CSV template, fill it in and upload it. Choose **Activate** to set the new rules live. 5. Open a delivered shipment in **Shipment Overview** and check the **Performance Aspirations** section in its details. 6. In **Business Intelligence**, create a report from the **Transit Time (Performance Aspirations)** or **On-time rate (Performance Aspirations)** template, and in **AI Performance Alerts** add an alert on the **Transit Time (Performance Aspirations)** metric for the categories you want watched. > [!TIP] > > Start from your carrier agreements: enter the transit time you agreed per carrier, service and country as one rule each. ## Use via API and MCP Performance Aspirations results travel with the shipment: * [Retrieve a shipment](https://developers.perform.ai/guides/retrieve-shipment.md) and the [shipment update webhook](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md) return the evaluations for a shipment from version 5.3.0. * Through [MCP](https://developers.perform.ai/mcp/overview.md), the tools `list_performance_categories`, `list_performance_rules`, `get_performance_rule` and `list_comply_milestones` read your categories, rules and the milestones available to build them, and `get_shipment_details` returns a shipment’s results. See [MCP tools](https://developers.perform.ai/mcp/tools.md). ## FAQ ### How quickly is a shipment evaluated after I activate a rule? As soon as a matching shipment reaches the category’s end milestone. There is no delay, and no result exists for shipments still in transit. ### What happens to shipments already evaluated when I change a rule? Nothing. Rule updates apply only to shipments not yet evaluated; past results are not recalculated. ### Can I delete an Active rule? No. Deactivate it first, which moves it to Draft, then delete it. ### Our carriers already report their SLA performance. Why measure it here? A carrier reports against its own definition. Performance Aspirations measures against yours: your working days, your cut-offs, your holidays, and the same standard then drives your reports, alerts and daily insight. ### Can I measure end to end with one rule? One rule measures one leg. Build end-to-end compliance from several categories, for instance a warehouse category and a carrier category, each measured on its own. ### Can I get the results into my own systems? Yes. From API and webhook version 5.3.0, the shipment payload carries the evaluations, so you can feed your own BI tool, data warehouse or carrier scorecards. ## Troubleshooting | Symptom | Cause | Fix | | - | - | - | | A rule produces no results | Filters too narrow for your shipments, the rule is still in Draft, or no matching shipment has reached the end milestone yet | Check the filter values against real shipments, activate the rule and wait for shipments to reach the end milestone. | | The delete action is unavailable on a rule | The rule is Active | Deactivate it, then delete. | | A category cannot be deleted | It still holds Active rules | Deactivate every rule in the category first. | | Results did not change after I edited a rule | Edits apply only to shipments evaluated from then on | Nothing to fix; new shipments use the updated rule. | | The CSV upload fails | Format or size error (files over 3 MB are rejected) | Download the error report, correct the rows flagged in the error column and re-upload. | ## Related * [AI Performance Alerts](https://developers.perform.ai/products/ai-decision-intelligence/ai-performance-alerts.md) * [Business Intelligence](https://developers.perform.ai/products/ai-decision-intelligence/business-intelligence.md) * [AI Recommendations](https://developers.perform.ai/products/ai-decision-intelligence/ai-recommendations.md) * [AI Decision Intelligence overview](https://developers.perform.ai/products/ai-decision-intelligence/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.