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
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.
What a shipment needs
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 theprocessed_file_report/ folder of your SFTP space. The report mirrors your upload with two added columns.
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 byshipment_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
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.
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 withQuota 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
- Go to Shipment Overview and select Add Parcels, then File Upload.
- 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]andshipment[tracking_number], and thecarrier_referenceof a configured carrier. - Enter one shipment per row and save the file as CSV.
- Drop the file into the upload box and select Confirm.
- Check the processed file report for rejected rows, correct them and upload again.
Request API credentials
- Go to Integrations > API and select Request Credentials. Your Client ID and Client Secret are shown.
- Generate a Bearer token with
POST /auth/oauth/token/. Tokens last one hour; request a new one before it expires. - Call
GET /v5/carrier-configs/to find yourcarrier_referencevalues, then create your first shipment. See the Quickstart.
Register a webhook endpoint
- Go to Integrations > Webhooks and register your HTTPS endpoint with a name and URL.
- Copy the Authentication Key. It is the key for the HMAC-SHA256 signature on every webhook.
- 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.
- 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 page.Use via API and MCP
- Guides: Create Shipment, Update Shipment, List Shipments, Retrieve Shipment, Create Events, Webhooks, Shopify integration.
- API reference: Create Shipment, Update Shipment and v5.2, List Shipments, Retrieve Shipment Details and v5.2, Create Events.
- Webhook payloads: format 5.0, format 5.2, format 5.3.
- 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 page.
FAQ
Do I need a tracking number to create a shipment?
Not through the API. Onlyshipment_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 missingshipment_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 byupdated_date.