# Perform.AI

- [Perform.AI Developer Portal](https://developers.perform.ai/introduction.md): Build on Perform.AI — REST APIs for shipment tracking, booking, and returns, webhooks for real-time updates, and an MCP server for AI assistants.
- [Quickstart](https://developers.perform.ai/quickstart.md): Make your first Perform.AI API calls: generate a token, create a shipment, and retrieve its details.
- [Authentication](https://developers.perform.ai/authentication.md): Generate a Bearer access token with your Client ID and Client Secret, and use it to call the Perform.AI Public API.
- [Shipments](https://developers.perform.ai/concepts/shipments.md): The Shipment is Perform.AI's core object — what it contains, how it's identified, and how it comes to life.
- [Statuses and phases](https://developers.perform.ai/concepts/statuses-and-phases.md): The two dimensions of a Shipment's lifecycle — record status and delivery phase — and how to use each.
- [Orders: Group and Track Shipments in Perform.AI](https://developers.perform.ai/concepts/orders.md): An order groups multiple shipments and returns under one identifier in Perform.AI, giving you unified end-to-end visibility across your fulfilment.
- [Returns Experience: Manage Consumer Returns via API](https://developers.perform.ai/concepts/returns.md): Perform.AI Returns Experience lets you manage consumer return requests and return shipments via API, with full visibility in the Perform.AI portal.
- [Events](https://developers.perform.ai/concepts/events.md): How tracking events work in Perform.AI — carrier events, manual events, and the standard event model.
- [Carriers](https://developers.perform.ai/concepts/carriers.md): How carriers work in Perform.AI — the master catalogue, your configurations, and the two identifiers you must not confuse.
- [Responses and errors](https://developers.perform.ai/essentials/responses-and-errors.md): The response envelope, warning model, and error codes shared by every Perform.AI Public API endpoint.
- [Rate limits](https://developers.perform.ai/essentials/rate-limits.md): Request limits for the Perform.AI Public API and how to handle throttling.
- [Timestamps and timezones](https://developers.perform.ai/essentials/timestamps.md): How Perform.AI formats dates, times, and timezone information in API responses.
- [Field reference](https://developers.perform.ai/essentials/field-reference.md): Every shared field used across the Perform.AI Public API — types, character limits, and formats.
- [Create a Shipment](https://developers.perform.ai/guides/create-shipment.md): Register a Shipment in Perform.AI — from a minimal Open Shipment to a fully tracked, enriched record.
- [Update a Shipment](https://developers.perform.ai/guides/update-shipment.md): Change an existing Shipment — and understand which fields replace, which append, and which can never change.
- [List and search Shipments](https://developers.perform.ai/guides/list-shipments.md): Search your Shipments with filters, AND/OR conditions, and cursor pagination.
- [Retrieve Shipment details](https://developers.perform.ai/guides/retrieve-shipment.md): Fetch the full record of one Shipment — including its complete event history — in v5.0 or the extended v5.2 shape.
- [Retrieve Shipment documents](https://developers.perform.ai/guides/shipment-documents.md): Download documents attached to Shipments — one by UUID, or across up to ten Shipments at once.
- [Create a Booking](https://developers.perform.ai/guides/create-booking.md): Book an Open Shipment with a carrier and provision its shipping labels.
- [Retrieve shipping labels](https://developers.perform.ai/guides/retrieve-labels.md): Fetch the shipping labels of up to ten Shipments in one call.
- [Retrieve PUDO locations](https://developers.perform.ai/guides/pudo-locations.md): Search pick-up/drop-off points across your carriers and feed them into checkout and booking.
- [Retrieve carrier configurations](https://developers.perform.ai/guides/carrier-configurations.md): Discover the carriers configured in your account — and the reference values every other endpoint expects.
- [Create a Return](https://developers.perform.ai/guides/create-return.md): Create a Return Ticket and its Return Shipment via the API.
- [Create a Return with a preprinted label](https://developers.perform.ai/guides/create-return-preprinted-label.md): Register a return whose label already shipped inside the outbound box.
- [Update a Return](https://developers.perform.ai/guides/update-return.md): Approve, reject, or amend a Return and its Return Shipment.
- [Update a Return with a preprinted label](https://developers.perform.ai/guides/update-return-preprinted-label.md): Amend a Return Shipment registered through the preprinted-label flow.
- [Create events](https://developers.perform.ai/guides/create-events.md): Add manual tracking events to a Shipment — for warehouse milestones, quality checks, refunds, and anything carriers don't report.
- [Receive webhooks](https://developers.perform.ai/guides/webhooks.md): Get Shipment updates pushed to your endpoint — setup, triggers, verification, payload formats, and field behaviors.
- [Predict checkout delivery dates](https://developers.perform.ai/guides/predict-checkout-edd.md): Show accurate delivery estimates at checkout, and link each prediction to the shipment it becomes.
- [Set Up Branded Shipment Tracking Pages in Perform.AI](https://developers.perform.ai/guides/tracking-page.md): Link shipments to a branded tracking experience in Perform.AI so customers see your logo, colors, and real-time updates in one place.
- [Configure Shipment Notifications via Perform.AI](https://developers.perform.ai/guides/notifications.md): Set up automated email and SMS shipment update notifications in Perform.AI using the notification_email and notification_phone fields.
- [Shopify integration setup](https://developers.perform.ai/integrations/shopify.md): Connect your Shopify store to Perform.AI — shipments import automatically, tracked end to end.
- [Changelog](https://developers.perform.ai/changelog.md): What changed on the Perform.AI developer platform and this portal.
- [API Reference overview](https://developers.perform.ai/api-reference/overview.md): Base URL, authentication, the response envelope, and how the reference pages work.
- [Generate Bearer access token](https://developers.perform.ai/api-reference/v5/authentication/generate-bearer-access-token.md): Generates a Bearer access token using the OAuth 2.0 client credentials flow. Send your Client ID and Client Secret as HTTP Basic authentication and `grant_type=client_credentials` as a form-encoded body.
- [Create Shipment](https://developers.perform.ai/api-reference/v5/shipments/create-shipment.md): Creates a Shipment in your account. Only `shipment_id` is required; a Shipment created without a `tracking_number` and carrier is an **Open Shipment** — a standalone record you can complete later, or hand to the Booking API to book with a carrier.
- [Update Shipment](https://developers.perform.ai/api-reference/v5/shipments/update-shipment.md): Updates an existing Shipment, identified by the `shipment_uuid` **or** `shipment_id` query parameter.
- [Update Shipment (v5.2)](https://developers.perform.ai/api-reference/v5/shipments/update-shipment-v52.md): Same as [Update Shipment](#tag/Shipments) v5.0, plus the **`tags_action`** field controlling how the `tags` array is applied:
- [List Shipments](https://developers.perform.ai/api-reference/v5/shipments/list-shipments.md): Searches your Shipments and returns key information for each match, including its latest event. Use [Retrieve Shipment Details](#tag/Shipments) for the full record of a single Shipment.
- [Retrieve Shipment Details](https://developers.perform.ai/api-reference/v5/shipments/retrieve-shipment-details.md): Returns the full record of one Shipment — identifiers, carrier, status and phase, all address objects, costs, dimensions, linked Shipments, documents, and the complete event history in `all_events`.
- [Retrieve Shipment Details (v5.2)](https://developers.perform.ai/api-reference/v5/shipments/retrieve-shipment-details-v52.md): Returns everything [Retrieve Shipment Details](#tag/Shipments) v5.0 returns, **plus**: `shipment_type` (`"return"` or `null`), a `returns` object for Return Shipments, `line_items`, `collection_point`, `rating`, `parcel_recipient_information`, and `pod_url` (carrier proof of delivery; the URL expire…
- [Create Booking](https://developers.perform.ai/api-reference/v5/booking/create-booking.md): Books an existing **Open Shipment** with a carrier and provisions the shipping label(s). On success you receive the carrier-generated tracking number, the booking status, the label document(s), and — for PUDO bookings — the confirmed location details.
- [List Documents](https://developers.perform.ai/api-reference/v5/documents/list-documents.md): Retrieves the documents of one or more Shipments. Identify the Shipments with **either** `shipment_uuids` **or** `shipment_ids` — never both — as a comma-joined list (no spaces) of up to **10** values.
- [Retrieve a Document](https://developers.perform.ai/api-reference/v5/documents/retrieve-a-document.md): Retrieves one document by its `document_uuid`. The response provides the document both as a `download_url` (valid for **1 hour**, regenerated on every call) and as a Base64-encoded string.
- [List Labels](https://developers.perform.ai/api-reference/v5/documents/list-labels.md): Retrieves the **shipping labels** of one or more Shipments — the documents listing pre-filtered to `type` `shipping_label` (pdf/zpl/png) and `shipping_label_qr` (png/jpg/pdf). Labels are generated by the Create Booking endpoint.
- [Retrieve PUDO Locations](https://developers.perform.ai/api-reference/v5/pudo-locations/retrieve-pudo-locations.md): Searches the pick-up/drop-off locations (parcel lockers, service points, post offices, parcel shops) of your configured carriers, with standardized addresses, location types, and operating hours. Feed a selected location's `pudo_location_uuid` into Create Booking to route the label there.
- [Retrieve Carrier Configurations](https://developers.perform.ai/api-reference/v5/carrier-configurations/retrieve-carrier-configurations.md): Lists the carriers configured in your account (**Settings > Carriers**). Use it to discover the `carrier_reference` values accepted by Create Shipment and Create Booking, and the `carrier_id` values used as filters in List Shipments and PUDO locations.
- [Create Events](https://developers.perform.ai/api-reference/v5/events/create-events.md): Adds manual tracking events to an existing Shipment — outbound or return. Identify the Shipment with `shipment_uuid` **or** `shipment_id` in the body; the `events` array is required.
- [Create Return](https://developers.perform.ai/api-reference/v5/returns/create-return.md): Creates a Return — a Return Ticket plus its Return Shipment. Available to accounts using the Returns Experience (contact your account team to enable it).
- [Update Return](https://developers.perform.ai/api-reference/v5/returns/update-return.md): Updates an existing Return's ticket and/or its Return Shipment. Both body objects are optional — send what changes.
- [Shipment update (format 5.0)](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-0.md): Sent to your configured endpoint whenever a Shipment has new events. One webhook per update cycle, even when several triggers fire — the `trigger` array lists every trigger the cycle satisfied.
- [Shipment update (format 5.2)](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md): Everything in format 5.0, plus: `shipment_type`, a `returns` object for Return Shipments, `line_items`, `collection_point`, `rating`, `tracking_page_url`, `pod_url`, `parcel_recipient_information`, and the enriched `event.location` (full address, coordinates, timezone) on every event object. The emi…
- [Shipment update (format 5.3)](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md): Everything in format 5.2, with two changes:
- [Predict Checkout EDD](https://developers.perform.ai/api-reference/checkout/predict-checkout-edd.md): Creates a **checkout event** — a virtual representation of a potential order — and returns its Estimated Delivery Date. One checkout event corresponds to at most one resulting Shipment; checkout events are not visible in the Portal.
- [Perform.AI MCP server](https://developers.perform.ai/mcp/overview.md): Connect AI assistants like Claude and ChatGPT to your Perform.AI account data through the Model Context Protocol.
- [Install the Perform.AI MCP server](https://developers.perform.ai/mcp/installation.md): Connect the Perform.AI MCP server to Claude, ChatGPT, Microsoft Copilot, or your own MCP client.
- [MCP tools](https://developers.perform.ai/mcp/tools.md): Every tool the Perform.AI MCP server exposes — session, Shipment search and details, and carrier data — plus filter semantics and reference resources.

## OpenAPI Specs

- [checkout-v1](/specs/checkout-v1.yaml)
- [public-api-v5](/specs/public-api-v5.yaml)