> ## 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.

# Data Integration

> How shipment and order data enters Perform.AI through the API, file upload, SFTP, webhooks and store integrations, and how it comes back out.

**Available to all Platform customers.** Users with the Administrator or Parcel Creation role can create and edit shipments in the portal. API credentials are issued per account.

## Summary

Data Integration is the set of ways your shipment and order data reaches Perform.AI and the set of ways it comes back to your own systems. You choose the method that fits your technical setup, from a CSV file dropped into the portal to a Public API call from your order management system, and Perform.AI returns the tracked, standardised shipment through webhooks, the API, portal exports and the MCP server.

## Who it’s for

Operations, IT and integration teams who need every shipment in Perform.AI without building a bespoke pipeline, and who need the tracked result back in the warehouse system, the helpdesk or the order system where their colleagues already work. The question it answers is “how do we get our data in, and how do we get it out again”.

## Key benefits

* **More than one way in.** Create shipments by hand in the portal, upload a CSV, drop files on SFTP, call the Public API, receive incoming webhooks, or connect a Shopify store. The method is chosen per account, so a carrier that will not issue credentials or a system that cannot call an API is still covered.
* **One record comes back out.** Whatever the input method, Perform.AI returns the same shipment record with its standardised event history, through webhooks, the API, the portal and the MCP server.
* **Push, not poll.** Outgoing webhooks deliver a Shipment update the moment Perform.AI processes new events, one message per update cycle, so your systems do not spend the rate budget asking.
* **Mistakes are reported, not silently dropped.** Every CSV upload produces a processed file report that says, row by row, whether the shipment was accepted, rejected or accepted with warnings, and why.
* **Only one field is required to start.** A shipment created through the API needs only a `shipment_id`. Without a tracking number and carrier it is an Open Shipment, completed later or handed to Booking.

## How it works

### Ways to send data in

| Method | What it does | How to start |
| - | - | - |
| Portal, single or multiple parcels | Create one parcel from a tracking number and carrier, with optional order ID, name and email, or paste or scan many tracking numbers at once. | **Shipment Overview** > **Add Parcels**. |
| Portal, file upload | Create shipments in bulk from a CSV file that follows the Create Shipment template. | **Shipment Overview** > **Add Parcels** > **File Upload**. |
| SFTP or FTP | You drop files into a folder Perform.AI provides; the files are pulled and processed on a schedule. Your own file format can be parsed and mapped to the standard schema. | Contact your account team to set up the folder and the parser. |
| Public API | Your systems create and update shipments and add events over HTTPS with OAuth 2.0 Bearer authentication. | Request credentials under **Integrations** > **API**, then follow the [Developers guides](https://developers.perform.ai/guides/create-shipment.md). |
| Incoming webhooks | Systems that can push data send each shipment to a dedicated Perform.AI endpoint. Calls are authenticated per message and create or update the shipment as they arrive. | Contact your account team for the endpoint and authentication. |
| Private API (your own or your carrier’s) | Perform.AI connects to an API you already expose, on a schedule that fits that API’s limits, to retrieve shipment data and create shipments. | Share the API documentation with your account team. |
| Shopify | Orders and fulfilments flow from one or more Shopify stores into one Perform.AI organization without any code. Imported shipments can carry a store tag and be linked to a Tracking Page. | **Integrations** > **Add Store**. See [Shopify](https://developers.perform.ai/products/integrations/shopify.md). |
| Kafka | Shipment creation and updates over a Kafka stream. | Available on request through your account team. |

Whichever method you use, Perform.AI identifies the carrier from the `carrier_reference` you send and starts retrieving tracking events. Configure your carriers under **Settings** > **Carriers** before you upload, and include the reference on every shipment: shipments without one take longer to assign to a carrier and can end up on the wrong one. See [Carrier Integration](https://developers.perform.ai/products/platform/carrier-integration.md).

### What a shipment needs

| Input method | Required | Notes |
| - | - | - |
| Public API, Create Shipment | `shipment_id` | Without `tracking_number` and a carrier the shipment is an Open Shipment: complete it later with Update Shipment, or book it with a carrier through Create Booking. |
| File upload | `shipment[shipment_id]` and `shipment[tracking_number]` | The CSV must follow the Create Shipment template and its validation rules. |
| Portal, single parcel | Tracking number and carrier | Order ID, name and email are optional. |

Every `shipment_id` must be unique in your account. Some fields travel in pairs: an `order[order_reference]` needs an `order[order_id]`, and an event with a time and a location also needs an event description or event key. Dates and times must follow the format in the template guide, and fields with a character limit are rejected when they exceed it.

### File upload status report

Every CSV you upload, through the portal or an SFTP folder, produces a processed file report in the `processed_file_report/` folder of your SFTP space. The report mirrors your upload with two added columns.

| Processed status | Meaning |
| - | - |
| Accepted | The row was processed with no errors or warnings. |
| Rejected | The row has at least one validation error and was not processed. |
| Warning | The row was processed but at least one validation warning was recorded. |

The **Errors/Warnings** column names the problem for each row, such as a missing field or a wrong format, so you can correct the affected rows and upload them again.

### Updating shipments

Update Shipment changes an existing shipment identified by `shipment_uuid` or `shipment_id`. The guide sets out which fields are replaced, which are appended and which can never change; the v5.2 variant adds `tags_action`, which controls how the `tags` array is applied. In the portal, addresses, order information, custom data, tags, notifications and notes can be edited from Parcel Details; line items, documents and events are updated through the API. A Return Shipment can no longer be updated once it has been booked with a carrier through Booking.

### Your own events

Create Events adds milestones that carriers never report, such as packed, quality-checked or refunded, to an outbound or Return Shipment. The events appear in the shipment’s history, on the Tracking Page and in webhooks, because every call is an update cycle.

### What comes back

| Channel | What you get |
| - | - |
| Outgoing webhooks | A Shipment update pushed to your HTTPS endpoint whenever Perform.AI processes new events: the full shipment plus `latest_event`, `new_events` for this cycle and `all_events`. One webhook per update cycle, with a `trigger` array listing every activated trigger the cycle satisfied. Signed with HMAC-SHA256. |
| Public API | List Shipments searches with filters and returns key fields and the latest event; Retrieve Shipment Details returns one shipment with its complete history. Document download links are valid for one hour and regenerated on every call. |
| Portal | Export from Shipment Overview as a CSV sent to your email, chart and report exports from Reports & Analysis, and custom reports delivered to email or an SFTP folder. |
| MCP | Your own AI assistant reads shipments, bookings, invoices and configuration through the Perform.AI MCP server, scoped to your organization and your portal permissions. Read-only. See [MCP overview](https://developers.perform.ai/mcp/overview.md). |

Webhook triggers are `all_events` or specific milestones: picked up, out for delivery, delivered, failed delivery attempt, customs, delay and exception. Accounts using Returns also have return-lifecycle triggers; custom triggers are set up with your account team.

| Webhook format | Adds | How it is enabled |
| - | - | - |
| 5.0 | The baseline Shipment payload. | Default. |
| 5.2 | `shipment_type`, `returns`, `line_items`, `collection_point`, `rating`, `tracking_page_url`, `pod_url`, `parcel_recipient_information` and enriched event locations. | Automatic with Returns; otherwise through your account team. |
| 5.3 | `expected_delivery` split by source and `pa_results` (Performance Aspiration evaluations). | Through your account team. |

The format is set per account, not per endpoint. Your endpoint must answer HTTP 200. Anything else, including a timeout, is retried three times, five minutes apart, then dropped. Missed webhooks are not replayed; reconcile gaps with List Shipments filtered by `updated_date`.

### Rate limits

The Public API allows 40 requests per second per account, shared across every endpoint and every system using the same credentials. Exceeding it returns HTTP 429, which is safe to retry with exponential backoff. Accounts also carry an overall request quota; exhausting it returns HTTP 403 with `Quota exceeded`. Run bulk jobs at a steady pace below the limit and use webhooks instead of polling wherever you can.

## Set up in the portal

### Upload a CSV file

1. Go to **Shipment Overview** and select **Add Parcels**, then **File Upload**.
2. Select **Create Shipment Template** to download the CSV template, or build your own file with the fields from the template field guide. Include at least `shipment[shipment_id]` and `shipment[tracking_number]`, and the `carrier_reference` of a configured carrier.
3. Enter one shipment per row and save the file as CSV.
4. Drop the file into the upload box and select **Confirm**.
5. Check the processed file report for rejected rows, correct them and upload again.

> [!TIP]
>
> Always include the carrier reference. It assigns the carrier at once and starts tracking immediately, instead of leaving the shipment to be identified later.

### Request API credentials

1. Go to **Integrations** > **API** and select **Request Credentials**. Your Client ID and Client Secret are shown.
2. Generate a Bearer token with `POST /auth/oauth/token/`. Tokens last one hour; request a new one before it expires.
3. Call `GET /v5/carrier-configs/` to find your `carrier_reference` values, then create your first shipment. See the [Quickstart](https://developers.perform.ai/quickstart.md).

### Register a webhook endpoint

1. Go to **Integrations** > **Webhooks** and register your HTTPS endpoint with a name and URL.
2. Copy the Authentication Key. It is the key for the HMAC-SHA256 signature on every webhook.
3. Save, then activate the endpoint and the triggers you want. Perform.AI sends a sample payload to validate the endpoint before the setup is final.
4. Confirm the payload format version for your account with your account team.

### Connect a Shopify store

Go to **Integrations** and select **Add Store** in the Shopify tile. The steps are on the [Shopify](https://developers.perform.ai/products/integrations/shopify.md) page.

## Use via API and MCP

* Guides: [Create Shipment](https://developers.perform.ai/guides/create-shipment.md), [Update Shipment](https://developers.perform.ai/guides/update-shipment.md), [List Shipments](https://developers.perform.ai/guides/list-shipments.md), [Retrieve Shipment](https://developers.perform.ai/guides/retrieve-shipment.md), [Create Events](https://developers.perform.ai/guides/create-events.md), [Webhooks](https://developers.perform.ai/guides/webhooks.md), [Shopify integration](https://developers.perform.ai/integrations/shopify.md).
* API reference: [Create Shipment](https://developers.perform.ai/api-reference/v5/shipments/create-shipment.md), [Update Shipment](https://developers.perform.ai/api-reference/v5/shipments/update-shipment.md) and [v5.2](https://developers.perform.ai/api-reference/v5/shipments/update-shipment-v52.md), [List Shipments](https://developers.perform.ai/api-reference/v5/shipments/list-shipments.md), [Retrieve Shipment Details](https://developers.perform.ai/api-reference/v5/shipments/retrieve-shipment-details.md) and [v5.2](https://developers.perform.ai/api-reference/v5/shipments/retrieve-shipment-details-v52.md), [Create Events](https://developers.perform.ai/api-reference/v5/events/create-events.md).
* Webhook payloads: [format 5.0](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-0.md), [format 5.2](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md), [format 5.3](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md).
* MCP tools: list\_integration\_types and list\_integration\_connections show the store connections your organization has set up, the integration each runs on, its status and how far each sync reaches. The shipment tools read what your integrations created. Documented on the [MCP tools](https://developers.perform.ai/mcp/tools.md) page.

## FAQ

### Do I need a tracking number to create a shipment?

Not through the API. Only `shipment_id` is required; a shipment without a tracking number and carrier is an Open Shipment that you complete later or book through Booking. A CSV upload needs both `shipment[shipment_id]` and `shipment[tracking_number]`.

### Why was my uploaded file rejected?

The most common causes are a missing `shipment_id` or `tracking_number`, a `carrier_reference` that is not configured in your account, a reused `shipment_id` or `document_id`, an `order_reference` without an `order_id`, an event with a time but no description or key, a wrong date format or a field over its character limit. The processed file report names the problem per row.

### Which webhook format will I receive?

The format set on your account: 5.0 by default, 5.2 automatically if you use Returns, 5.3 on request. Confirm it with your account team before you build the parser, and build it to ignore unknown fields.

### What happens if my endpoint is down when a webhook fires?

Perform.AI retries three times, five minutes apart, then stops. Missed webhooks are not replayed. Reconcile with List Shipments filtered by `updated_date`.

### Why do the events in Perform.AI differ from the carrier’s tracking site?

The number of events, timestamps and descriptions depend on what the carrier shares through the integration in place. Private integrations (API, webhook or SFTP) often provide more detail than the carrier’s public tracking page. See [Carrier Integration](https://developers.perform.ai/products/platform/carrier-integration.md).

### Can I test webhooks without a carrier?

Yes. Create a test shipment with a tracking number and carrier, then push events with Create Events. Each call delivers a webhook.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Rows in the processed file report are Rejected | A required field is missing, a unique field is reused, or a value fails validation | Read the **Errors/Warnings** column for the row, correct the file and upload the affected rows again. |
| Shipment is created but never receives tracking events | The `carrier_reference` was missing or is not configured in your account | Add the carrier under **Settings** > **Carriers** and reassign the shipment from Parcel Details while it is Pending or Expired. |
| API call returns HTTP 403 `Key not authorized` | The Client Secret is wrong or the token has expired | Check the credentials and generate a new token; tokens last one hour. |
| API call returns HTTP 429 `Throttled` | More than 40 requests per second from all systems using the same credentials | Retry with exponential backoff and jitter, and pace bulk jobs below the limit. |
| Webhooks stop arriving | The endpoint did not answer HTTP 200 within the retry window | Fix the endpoint, then reconcile the gap with List Shipments filtered by `updated_date`. |

## Related

* [Carrier Integration](https://developers.perform.ai/products/platform/carrier-integration.md)
* [Security & Compliance](https://developers.perform.ai/products/platform/security-and-compliance.md)
* [Shopify](https://developers.perform.ai/products/integrations/shopify.md), [File upload](https://developers.perform.ai/products/integrations/file-upload.md), [Webhooks](https://developers.perform.ai/products/integrations/webhooks.md), [Kafka](https://developers.perform.ai/products/integrations/kafka.md)
* [Shipment Overview](https://developers.perform.ai/products/post-purchase/shipment-overview.md)
* [Platform overview](https://developers.perform.ai/products/platform/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.