Create a return, or create a return together with its associated return shipment, in a Parcel Perform account (one return per request). Return shipments flow through the same shipment and tracking-event model as outbound parcels, giving merchants a single system for forward and reverse logistics visibility.
openapi: 3.0.3
info:
title: Parcel Perform API
description: >-
Parcel Perform aggregates real-time tracking data across hundreds of
carriers into one standardized event model, then layers shipment
management, returns, outgoing webhooks, and delivery-experience analytics
on top. All requests are authenticated with an OAuth2 client-credentials
Bearer access token obtained from the auth endpoint below.
Endpoint groups marked CONFIRMED were verified against Parcel Perform's
public developer portal (developer.parcelperform.com, hosted on Stoplight
at developers.parcelperform.com) via documentation page titles and
indexed search snippets - the base domain `api.parcelperform.com`, the
literal auth path `/auth/oauth/token/`, and the literal shipment-details
path fragment `/v5/shipment/details/` were confirmed verbatim. The
Stoplight portal renders its reference pages client-side, which blocked
programmatic extraction of the remaining literal path strings and full
request/response schemas, so most operation paths and all schemas below
are MODELED - built from the confirmed operation names/versions
(Create/Retrieve/List/Update Shipment, Create Events, Create Return,
Outgoing Webhooks v5.0.0/v5.2.0, Response Structure & Errors) and standard
Parcel Perform v5 REST conventions. The Couriers and Analytics groups are
entirely modeled - Parcel Perform's public API reference does not document
a standalone endpoint set for either, so those paths are illustrative
based on the company's marketing/product pages.
version: '5.2.0'
contact:
name: Parcel Perform
url: https://www.parcelperform.com
termsOfService: https://www.parcelperform.com/terms-of-service
servers:
- url: https://api.parcelperform.com/v5
description: Parcel Perform production API (v5)
security:
- bearerAuth: []
tags:
- name: Authentication
description: OAuth2 client-credentials token issuance. CONFIRMED path.
- name: Shipments
description: Create, retrieve, list, and update shipments. CONFIRMED operations; MODELED paths/schemas.
- name: Tracking Events
description: Normalized carrier tracking event timeline. CONFIRMED operations; MODELED paths/schemas.
- name: Returns
description: Create returns and return shipments. CONFIRMED operations; MODELED paths/schemas.
- name: Webhooks
description: Outgoing webhook subscriptions for tracking updates. CONFIRMED operations; MODELED paths/schemas.
- name: Couriers
description: Carrier/courier reference data. Entirely MODELED - no public reference page found.
- name: Analytics
description: Delivery-experience performance metrics behind the Analyze product. Entirely MODELED - no public reference page found.
paths:
/auth/oauth/token/:
post:
operationId: createAccessToken
tags:
- Authentication
summary: Generate a Bearer access token (CONFIRMED path)
description: >-
Exchanges API credentials for a short-lived OAuth2 Bearer access
token using the client-credentials grant. Send `Authorization: Basic
base64(client_id:client_secret)` and `grant_type=client_credentials`
in a form-encoded body. Confirmed via Parcel Perform's public
"Generate Bearer Access Token" documentation page and indexed
third-party integration guides; the returned token is reported valid
for 3600 seconds (60 minutes).
security: []
parameters:
- name: Authorization
in: header
required: true
description: 'Basic base64(client_id:client_secret).'
schema:
type: string
example: Basic base64Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
properties:
grant_type:
type: string
enum: [client_credentials]
responses:
'200':
description: Bearer token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/shipment:
post:
operationId: createShipment
tags:
- Shipments
summary: Create a shipment (MODELED path; operation name CONFIRMED)
description: >-
Creates a shipment in the Parcel Perform account so it can be
tracked across the carrier network. Confirmed via the "Create a
Shipment" documentation page title; exact path and payload fields are
modeled on Parcel Perform's documented v5 shipment object.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentInput'
responses:
'201':
description: The created shipment.
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/shipment/list:
get:
operationId: listShipments
tags:
- Shipments
summary: List shipments (MODELED path; operation name CONFIRMED)
description: >-
Retrieves a list of shipments and their key details using search
criteria such as tracking number, courier code, or creation date
range. Confirmed via the "List Shipments (v5.0)" documentation page
title; exact path, query parameters, and pagination are modeled.
parameters:
- name: tracking_number
in: query
schema:
type: string
- name: courier
in: query
description: Carrier/courier code.
schema:
type: string
- name: created_from
in: query
schema:
type: string
format: date-time
- name: created_to
in: query
schema:
type: string
format: date-time
- name: page
in: query
schema:
type: integer
default: 1
- name: page_size
in: query
schema:
type: integer
default: 50
responses:
'200':
description: A page of shipments.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Shipment'
meta:
$ref: '#/components/schemas/PageMeta'
'401':
$ref: '#/components/responses/Unauthorized'
/shipment/details/{tracking_id}:
parameters:
- name: tracking_id
in: path
required: true
description: Parcel Perform tracking ID or tracking number for the shipment.
schema:
type: string
get:
operationId: getShipmentDetails
tags:
- Shipments
summary: Retrieve shipment details (CONFIRMED path fragment)
description: >-
Retrieves the user-input details plus the normalized tracking events
for a single shipment. The `/v5/shipment/details/` path fragment is
confirmed verbatim from indexed documentation; the trailing path
parameter name is modeled. The v5.2.0 response additionally includes
`returns`, `rating`, `line_items`, `collection_point`, and
`event.location` objects versus v5.0.0, per the documented version
diff.
responses:
'200':
description: The requested shipment, including its tracking events.
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentDetails'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateShipment
tags:
- Shipments
summary: Update shipment (MODELED path; operation name CONFIRMED)
description: >-
Updates certain fields, or adds additional elements, for an existing
outbound or return shipment. Confirmed via the "Update Shipment
(v5.0)" and "Update Details for an Existing Shipment" documentation
page titles; exact path/verb and payload are modeled (Parcel
Perform's docs list both PUT and POST variants by title, so PUT is
used here as the primary verb).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentUpdateInput'
responses:
'200':
description: The updated shipment.
content:
application/json:
schema:
$ref: '#/components/schemas/Shipment'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
/shipment/{tracking_id}/event:
parameters:
- name: tracking_id
in: path
required: true
schema:
type: string
post:
operationId: createShipmentEvents
tags:
- Tracking Events
summary: Create events for an existing shipment (MODELED path; operation name CONFIRMED)
description: >-
Manually creates one or more tracking events on an existing outbound
or return shipment, for cases such as in-house last-mile legs not
covered by a carrier feed. Confirmed via the "Create Events for an
Existing Shipment" and "Create Events (v5.0)" documentation page
titles; exact path and payload are modeled on the documented event
object (status, location, timestamp).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/EventInput'
responses:
'201':
description: The created events.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Event'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
/return:
post:
operationId: createReturn
tags:
- Returns
summary: Create a return (MODELED path; operation name CONFIRMED)
description: >-
Creates a return in the Parcel Perform account against an existing
outbound shipment. Only one return may be created per request.
Confirmed via the "Create a Return" / "Create Return" documentation
page titles; exact path and payload are modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnInput'
responses:
'201':
description: The created return.
content:
application/json:
schema:
$ref: '#/components/schemas/Return'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/return/shipment:
post:
operationId: createReturnWithShipment
tags:
- Returns
summary: Create a return with its return shipment (MODELED path; operation name CONFIRMED)
description: >-
Creates a Return and its associated Return Shipment together in a
single request. Confirmed via the "Create a Return" documentation
page title (which pairs Create Return with Create Shipment); exact
path and payload are modeled.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ReturnInput'
- type: object
properties:
shipment:
$ref: '#/components/schemas/ShipmentInput'
responses:
'201':
description: The created return and return shipment.
content:
application/json:
schema:
type: object
properties:
return:
$ref: '#/components/schemas/Return'
shipment:
$ref: '#/components/schemas/Shipment'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/webhook:
get:
operationId: listWebhookSubscriptions
tags:
- Webhooks
summary: List outgoing webhook subscriptions (MODELED)
description: >-
Lists the callback URLs registered to receive outgoing Shipment
Tracking Update webhooks. The existence of outgoing webhooks in
v5.0.0 and v5.2.0 payload formats is confirmed via documentation page
titles; a management endpoint for subscriptions is modeled, since
webhook target URLs are commonly configured in the Parcel Perform
console rather than (or in addition to) via API.
responses:
'200':
description: Registered webhook subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createWebhookSubscription
tags:
- Webhooks
summary: Create an outgoing webhook subscription (MODELED)
description: >-
Registers a callback URL and payload format version
(`5.0.0` or `5.2.0`) to receive outgoing Shipment Tracking Update
events. Modeled endpoint - see summary on the GET operation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionInput'
responses:
'201':
description: The created webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/courier:
get:
operationId: listCouriers
tags:
- Couriers
summary: List supported couriers/carriers (MODELED - not found in public reference)
description: >-
Illustrative list of the courier/carrier network Parcel Perform
tracks against (reported between roughly 900 and 1,000+ carriers
worldwide per Parcel Perform's marketing pages). No standalone
`/courier` endpoint is documented in the public API Guides &
Reference as of this review; carrier codes otherwise only appear as
a field on Shipment resources. Entirely modeled.
responses:
'200':
description: Supported couriers.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Courier'
'401':
$ref: '#/components/responses/Unauthorized'
/courier/{courier_code}:
parameters:
- name: courier_code
in: path
required: true
schema:
type: string
get:
operationId: getCourier
tags:
- Couriers
summary: Retrieve a courier/carrier (MODELED - not found in public reference)
description: Entirely modeled - see summary on the list operation.
responses:
'200':
description: The requested courier.
content:
application/json:
schema:
$ref: '#/components/schemas/Courier'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/analytics/performance:
get:
operationId: getPerformanceAnalytics
tags:
- Analytics
summary: Retrieve delivery-experience performance metrics (MODELED - not found in public reference)
description: >-
Illustrative reporting endpoint modeled on the metrics described for
Parcel Perform's "Analyze" product - carrier on-time/SLA performance,
exception rates, and estimated-delivery-date accuracy aggregated over
a date range. No standalone analytics endpoint is documented in the
public API Guides & Reference as of this review; Analyze is presented
as an in-app dashboard/AI-insights product. Entirely modeled.
parameters:
- name: date_from
in: query
required: true
schema:
type: string
format: date
- name: date_to
in: query
required: true
schema:
type: string
format: date
- name: courier
in: query
schema:
type: string
- name: group_by
in: query
schema:
type: string
enum: [courier, country, service_level]
responses:
'200':
description: Aggregated performance metrics.
content:
application/json:
schema:
$ref: '#/components/schemas/PerformanceReport'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer access token obtained from POST /auth/oauth/token/, valid for
3600 seconds (60 minutes) per indexed integration guides. Passed as
`Authorization: Bearer YOUR_ACCESS_TOKEN`.
responses:
Unauthorized:
description: Missing, invalid, or expired Bearer token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: The request payload failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
status:
type: string
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
field:
type: string
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
enum: [Bearer]
expires_in:
type: integer
description: Token lifetime in seconds. Reported as 3600 (60 minutes).
example: 3600
PageMeta:
type: object
properties:
page:
type: integer
page_size:
type: integer
total:
type: integer
ShipmentInput:
type: object
required:
- tracking_number
- courier
properties:
tracking_number:
type: string
courier:
type: string
description: Carrier/courier code (e.g. dhl, ups, fedex, ninjavan).
reference_number:
type: string
description: Merchant order/reference number.
sender:
$ref: '#/components/schemas/Party'
recipient:
$ref: '#/components/schemas/Party'
line_items:
type: array
items:
$ref: '#/components/schemas/LineItem'
collection_point:
$ref: '#/components/schemas/CollectionPoint'
metadata:
type: object
additionalProperties: true
ShipmentUpdateInput:
type: object
properties:
reference_number:
type: string
recipient:
$ref: '#/components/schemas/Party'
metadata:
type: object
additionalProperties: true
Shipment:
allOf:
- $ref: '#/components/schemas/ShipmentInput'
- type: object
properties:
id:
type: string
status:
type: string
description: Normalized shipment status/milestone.
enum:
- info_received
- in_transit
- out_for_delivery
- delivered
- exception
- returned
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ShipmentDetails:
allOf:
- $ref: '#/components/schemas/Shipment'
- type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/Event'
returns:
type: array
description: Present in v5.2.0 responses.
items:
$ref: '#/components/schemas/Return'
rating:
type: object
description: Present in v5.2.0 responses.
additionalProperties: true
Party:
type: object
properties:
name:
type: string
email:
type: string
phone:
type: string
address:
type: string
city:
type: string
state:
type: string
postal_code:
type: string
country:
type: string
LineItem:
type: object
properties:
sku:
type: string
name:
type: string
quantity:
type: integer
weight:
type: number
CollectionPoint:
type: object
properties:
id:
type: string
name:
type: string
address:
type: string
EventInput:
type: object
required:
- status
- occurred_at
properties:
status:
type: string
description:
type: string
occurred_at:
type: string
format: date-time
location:
type: object
properties:
city:
type: string
state:
type: string
country:
type: string
Event:
allOf:
- $ref: '#/components/schemas/EventInput'
- type: object
properties:
id:
type: string
courier_raw_status:
type: string
description: The original, non-normalized status text reported by the carrier.
ReturnInput:
type: object
required:
- shipment_tracking_number
properties:
shipment_tracking_number:
type: string
description: Tracking number of the outbound shipment being returned.
reason:
type: string
line_items:
type: array
items:
$ref: '#/components/schemas/LineItem'
Return:
allOf:
- $ref: '#/components/schemas/ReturnInput'
- type: object
properties:
id:
type: string
status:
type: string
enum:
- requested
- approved
- in_transit
- received
- refunded
- rejected
created_at:
type: string
format: date-time
WebhookSubscriptionInput:
type: object
required:
- target_url
- format_version
properties:
target_url:
type: string
format: uri
format_version:
type: string
enum: ['5.0.0', '5.2.0']
secret:
type: string
description: Shared secret used to sign the webhook payload.
WebhookSubscription:
allOf:
- $ref: '#/components/schemas/WebhookSubscriptionInput'
- type: object
properties:
id:
type: string
created_at:
type: string
format: date-time
Courier:
type: object
properties:
code:
type: string
name:
type: string
country:
type: string
service_types:
type: array
items:
type: string
PerformanceReport:
type: object
properties:
date_from:
type: string
format: date
date_to:
type: string
format: date
groups:
type: array
items:
type: object
properties:
key:
type: string
shipment_count:
type: integer
on_time_rate:
type: number
exception_rate:
type: number
average_transit_days:
type: number