openapi: 3.0.0 info: title: Metapack Tracking API version: 1.0.12 description: |- The Tracking API lets you easily integrate delivery tracking data with your apps and services. You can track delivery events from more than 300 carriers through a single API. It also enables you to publish pre-ship and returns events for complete end-to-end order tracking. For more information about the API, go to [https://dev.metapack.com/](https://dev.metapack.com/). contact: name: Metapack url: https://www.metapack.com/ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - description: Sandbox url: https://api.sbx.metapack.com/tracking/v1 - description: Production url: https://api.metapack.com/tracking/v1 paths: /parcel-journeys: get: operationId: getParcelJourneys summary: Retrieve the parcel journeys for an order or a parcel tags: - Tracking description: |- A parcel journey contains the full tracking history related to the delivery of a parcel. It unifies in a normalised format all of the events that have been published for the parcel, both pre-allocation and post-allocation. These events include deliveries, delivery legs, and carrier tracking events. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' - name: Accept-Encoding description: |- Enables the compression of the content returned in the response. Supported content encodings are `gzip` and `deflate`. in: header schema: type: string example: gzip, deflate - name: Accept-Language description: |- Use this header to retrieve parcel journeys with information localised in the requested language. The default format used is an [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) language code in lowercase hyphenated with a country code in [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#search/code/) format in UPPERCASE. For example, `en-GB` will return information localised in UK English whereas `en-US` will return information localised in US English. If this header is omitted, the parcel journeys will be returned with information localised in English. **Note:** Localised information will be returned only when requesting a supported language. in: header schema: type: string enum: - bg-BG - cs-CZ - da-DK - de-DE - en-GB - en-US - es-ES - fi-FI - fr-FR - hr-HR - hu-HU - it-IT - ja-JP - ko-KR - nb-NO - nl-NL - pl-PL - pt-PT - ro-RO - sv-SE - tr-TR - zh-CN example: en-GB - name: orderRef description: |- Use the order reference to retrieve all parcel journeys for the order. **Note:** This parameter is case sensitive. in: query schema: type: string example: REPLACE-WITH-YOUR-ORDER-REF - name: trackingIdentifier description: |- Use the tracking identifier to retrieve the parcel journey for a specific parcel. Use this parameter in combination with order reference to ensure that any parcel journeys returned for an order contain at least one delivery leg that matches the specified tracking identifier. **Note:** This parameter is case sensitive. in: query schema: type: string example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER - name: customerRef description: |- Unique reference of the customer. Use this optional parameter to filter parcel journeys for a specific customer when a multi-brand seller can use the same order reference across its brands. To use this filter, the customer reference must be provided in the delivery and delivery legs for the corresponding order and parcels (`order.customer.customerRef`). **Note:** This parameter is case sensitive. in: query schema: type: string example: REPLACE-WITH-YOUR-CUSTOMER-REF - name: postcode description: |- The postcode of the parcel recipient. Use this optional parameter in combination with order reference or tracking identifier to ensure that any parcel journeys returned for an order contain at least one parcel journey that matches the specified parcel recipient postcode (`recipient.postCode`). **Note:** This parameter is case sensitive. in: query schema: type: string example: WC1X 8XZ responses: '200': description: Parcel Journeys have been returned successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/ParcelJourney' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '500': $ref: '#/components/responses/internalError' /delivery-legs: post: operationId: postDeliveryLeg summary: Create or update a delivery leg for a trackable item tags: - Post-allocation description: |- A delivery leg is a stage of the parcel journey defined by a single tracking identifier. It contains the necessary information for the delivery of a parcel and the information about the carrier delivering the parcel. A delivery leg can be used to support a tracking experience after the trackable item has been allocated a tracking identifier. A delivery leg can be linked to a delivery if they share the same delivery reference. Multiple delivery legs can be linked to one another if they share the same parcel reference. A delivery leg is identified by its tracking identifier only or its tracking identifier in combination with its parcel reference when both are provided. **Note:** Each time you update a delivery leg, you must resubmit the mandatory information of the delivery leg in addition to any other data that you have added or modified. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' - $ref: '#/components/parameters/ShipperIdHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/DeliveryLeg' responses: '204': description: The delivery leg information has been processed successfully '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '415': $ref: '#/components/responses/unsupportedMedia' '500': $ref: '#/components/responses/internalError' delete: operationId: deleteDeliveryLegs summary: Delete delivery legs for a given tracking identifier tags: - Post-allocation description: |- Delete the delivery legs that have been created with the given tracking identifier. This method is used to remove delivery legs no longer needed in a parcel journey. This happens when the tracking identifier in the delivery leg will never be used for tracking a parcel, which means that no tracking events will ever be received for the given tracking identifier. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' - name: trackingIdentifier description: |- Use the tracking identifier of the delivery legs that need to be deleted. **Note:** This parameter is case sensitive. in: query required: true schema: type: string example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER responses: '200': description: All delivery legs for the specified tracking identifier have been deleted content: application/json: schema: $ref: '#/components/schemas/Message' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '500': $ref: '#/components/responses/internalError' /delivery-legs/events: post: operationId: postDeliveryLegEvent summary: Add tracking events for a delivery leg tags: - Post-allocation description: |- A delivery leg event for a trackable item that relates to the status of a parcel post-allocation. Delivery leg events can be used to update the status of a parcel when ready for collection in a store or at a pickup point. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/DeliveryLegEvent' responses: '204': description: Tracking event has been published successfully '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '415': $ref: '#/components/responses/unsupportedMedia' '500': $ref: '#/components/responses/internalError' /deliveries: post: operationId: postDelivery summary: Create or update a delivery tags: - Pre-allocation description: |- A delivery is a placeholder entity created by a seller before the order is allocated to a carrier. A delivery is identified by its unique delivery reference or the combination of its delivery reference and order reference when both are provided. Before a trackable item exists, a delivery resource can provide a tracking experience. **Note:** Each time you update a delivery, you must resubmit the mandatory information of the delivery in addition to any other data that you have added or modified. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' - $ref: '#/components/parameters/ShipperIdHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/Delivery' responses: '204': description: Delivery information for the order has been processed successfully '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '415': $ref: '#/components/responses/unsupportedMedia' '500': $ref: '#/components/responses/internalError' /deliveries/events: post: operationId: postDeliveryEvent summary: Add events for a delivery tags: - Pre-allocation description: |- A delivery event is an event published by a seller that relates to the status of a delivery pre-allocation, such as an order being processed or awaiting payment. Delivery events can be defined before a trackable item exists. security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/DeliveryEvent' responses: '204': description: Delivery event has been published successfully '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '415': $ref: '#/components/responses/unsupportedMedia' '500': $ref: '#/components/responses/internalError' /parcel-journeys/search: post: summary: Search for parcel journeys using sensitive data security: - BasicAuth: [] parameters: - $ref: '#/components/parameters/UserAgentHeader' tags: - Customer Support operationId: post-parceljourneys-search responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/ParcelJourney' '400': $ref: '#/components/responses/badRequest' '401': $ref: '#/components/responses/unauthorized' '403': $ref: '#/components/responses/forbidden' '500': $ref: '#/components/responses/internalError' requestBody: content: application/json: schema: anyOf: - properties: email: type: string description: The email address of the customer for which the parcel journeys are being requested. example: john.doe@example.com - properties: customerRef: type: string description: The unique reference of the customer for which the parcel journeys are being requested. example: REPLACE-WITH-YOUR-CUSTOMER-REF type: object description: |- Search for parcel journeys using sensitive data, such as a customers email address or customer reference. The email address or the customer reference can be used to search for parcel journeys over a period of 90 days. A parcel journey contains the full tracking history related to the delivery of a parcel. It unifies in a normalised format all of the events that have been published for the parcel, both pre-allocation and post-allocation. These events include deliveries, delivery legs, and carrier tracking events. components: securitySchemes: BasicAuth: type: http scheme: basic description: |- To authenticate yourself to the Tracking API, you need to include an `Authorization` header in each API request. The `Authorization` header comprises the prefix `Basic` followed by a Base64-encoded `:` string. If you don't include the header when making an API request, the API will return a `401` (Unauthorized) error. **Note:** The Tracking API uses HTTPS to provide secure connections. Therefore, you must use HTTPS for all direct communication between your systems or apps and the API. parameters: UserAgentHeader: name: User-Agent description: The name of the client that interacts with the API. in: header required: false schema: type: string example: REPLACE-WITH-YOUR-USER-AGENT ShipperIdHeader: name: Shipper-Id description: |- The unique identifier of a shipper within Metapack shipping platform. **Note:** Reserved for Metapack use only. in: header required: false schema: type: string responses: badRequest: description: |- Bad request. The request failed validation due to missing required information in the parameters or the body of the request. Error code: PS-0400. content: application/json: schema: $ref: '#/components/schemas/Error' forbidden: description: |- Forbidden. The API user is not authorized to proceed with the processing of the request. Error code: PS-0403. content: application/json: schema: $ref: '#/components/schemas/Error' unauthorized: description: |- Unauthorized. The request did not provide the credentials required to authorize access to the API. Error code: PS-0401. content: application/json: schema: $ref: '#/components/schemas/Error' unsupportedMedia: description: |- Unsupported media format. The request failed due to an unsupported media type in the request. Error code: PS-0415. content: application/json: schema: $ref: '#/components/schemas/Error' internalError: description: |- Internal Server Error. The processing of the request failed due to an internal problem. The request needs to be retried. Error code: PS-0500. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Address: description: Address information. properties: addressLine1: type: string description: The first line of an unstructured address. example: 200 Grays Inn Road addressLine2: type: string description: The second line of an unstructured address. postCode: type: string description: The postal code of an address (if supported). example: WC1X 8XZ countryCode: type: string description: The country code of an address in [ISO 3166-1 alpha-3](https://www.iso.org/obp/ui/#search/code/) format in UPPERCASE. example: GBR companyName: type: string description: The name of the company. example: Metapack city: type: string description: The city (or town) of an address. example: London stateProvince: type: string description: The region or provence of an address. example: London timeZone: type: string description: The time zone of an address. example: Europe/London Collection: type: object description: Collection information for pickup point or store collection delivery. properties: accessibility: type: boolean description: Information provided to show if collection location is accessible for disabled recipients, such as "Wheelchair accessible". example: true daysHeld: type: number description: Number of lapsed working days a parcel will be held at a collection location before it is returned back to the shipper. Used to prompt collection notifications and in-app prompts. example: 7 information: type: string description: Any information a carrier or click-and-collect provider wants to provide to increase the likelihood of successful delivery. example: Collection counter on 2nd floor next to womenswear locationId: type: string description: Location identifier used to retrieve collection information. May not be unique across carriers or even within a carrier. example: EASYCOLLECT-1234 openingHours: type: array description: Opening hours for a collection location. The format supported by Metapack products is [Key:opening_hours](https://wiki.openstreetmap.org/wiki/Key:opening_hours). Each day has a separate string entry, with a time range (24hr). Closed is not supported. Public Holidays are not supported. example: - Mo 08:00-12:00,14:00-17:00 - Tu 09:00-20:00 - We 09:00-20:00 - Th 09:00-20:00 - Fr 09:00-20:00 - Sa 09:00-17:00 - Su 09:00-17:00 items: type: string parkingAvailability: type: boolean description: Indicates that parking is available. example: true storeDetailsURL: type: string format: uri pattern: ^https:// description: URL to specific page displaying store details. This can also be used for stores that can't or won't provide store details, such as opening hours, in API responses. Equally, if a store's standard opening hours change for public holidays, providing this URL avoids the need to overwrite its standard `openingHours` data in API responses. example: https://easycollect.com/shops/info address: allOf: - $ref: '#/components/schemas/Address' - properties: contact: type: object description: Contact information for collection properties: email: type: string description: The email address of the collection location, which can be used by the recipient to locate the collection point. example: somebody@example.com phone: type: string description: The phone number of the collection location, which can be used by the recipient to locate the collection point. example: '0800155781' location: $ref: '#/components/schemas/Location' Customer: type: object properties: customerRef: type: string description: Seller reference to identify a specific shopper within its organisation. example: REPLACE-WITH-YOUR-CUSTOMER-REF customerSegment: type: string description: Seller grouping of customers based on categories such as value. Can be used to identify groups that should have a specific experience based on their segment. Can lead to different notification bundles, features, returns options, and so on. example: VIP email: type: string description: The email address of the contact. Can be passed to and used by the logistics service provider for the purposes of contact regarding the delivery. example: john.doe@example.com name: type: string description: The name of the contact. example: John Doe phone: type: string description: The phone number of the contact. Can be passed to and used by the logistics service provider for the purposes of contact regarding the delivery. example: '07814354765' Delivery: title: Delivery type: object description: A delivery is a placeholder entity created by a seller before the order is allocated to a carrier. Requires a delivery reference (`deliveryRef`), which is unique to the seller and can be associated with an order using (`order.orderRef`). required: - deliveryRef properties: deliveryRef: type: string description: The unique delivery reference. This reference is used to link a delivery for an order with the delivery legs for the parcels within this delivery that are part of the order. example: REPLACE-WITH-YOUR-DELIVERY-REF order: $ref: '#/components/schemas/Order' collection: $ref: '#/components/schemas/Collection' delivery: $ref: '#/components/schemas/DeliveryInformation' recipient: $ref: '#/components/schemas/Recipient' sender: $ref: '#/components/schemas/Sender' DeliveryEvent: title: DeliveryEvent type: object description: A delivery event. Supports pre-allocation. required: - eventDate - eventTimeZone - deliveryRef - eventCode allOf: - properties: deliveryRef: type: string description: The unique delivery reference. This reference is used to link a delivery for an order with the delivery legs for the parcels within this delivery that are part of the order. example: REPLACE-WITH-YOUR-DELIVERY-REF eventCode: type: string description: Metapack event code. enum: - ORDER_ACCEPTED - PAYMENT_SUCCESSFUL - PAYMENT_DECLINED - CANCELLED_BEFORE_DESPATCH - ORDER_DECLINED - PERSONALISATION_STARTED - PERSONALISATION_ISSUE - AWAITING_FULFILMENT - PERSONALISATION_COMPLETED - READY_FOR_PACKING - DESPATCH_DELAYED - DESPATCH_DELAYED_IN_PART - RETURN_CREATED - RETURN_NEEDS_APPROVAL - RETURN_APPROVED - RETURN_CANCELLED - RETURN_REJECTED - RETURN_WINDOW_EXPIRED - RETURN_NOT_COMPLETED - RETURN_COMPLETED - RETURN_COMPLETED_IN_PART example: ORDER_ACCEPTED - $ref: '#/components/schemas/LogisticsEvent' DeliveryInformation: title: DeliveryInformation type: object description: Information about the type of delivery. properties: carrierPINCode: type: string description: Secure PIN code provided by the carrier that must be entered by the recipient to receive a parcel. example: '2351' carrierServiceType: type: string description: Specifies whether a parcel is tracked or untracked. enum: - TRACKED - UNTRACKED example: TRACKED direction: type: string description: The direction of the delivery. Defaults to `OUTBOUND`. enum: - OUTBOUND - RETURN example: OUTBOUND instructions: type: string description: Instructions for the delivery. example: Please collect your parcel from the pick up location returnType: type: string description: Describes type of returns label to help inform an application and notifications behaviour. Will have limited values for either returns on demand or pre-printed labels in a box. Defaults to `ON_DEMAND` in the parcel journey when the direction is `RETURN`. enum: - ON_DEMAND - PRE_PRINTED shippedDateTime: type: string format: date-time description: Date and time provided by the seller when a parcel was shipped or collected from the shipping address. type: type: string description: The delivery channel, which supports home delivery, pickup point, and collection in store. Defaults to `HOME`. enum: - HOME - PUDO - STORE example: PUDO deliveryWindow: $ref: '#/components/schemas/DeliveryWindow' selectedTimeSlot: $ref: '#/components/schemas/DeliveryTimeSlot' DeliveryLeg: title: DeliveryLeg type: object description: A delivery leg is a stage of the parcel journey defined by a single tracking identifier. It can be a full end-to-end parcel journey if the delivery scenario is for a single parcel, a single carrier, or a single leg. Alternatively, it can represent one leg of many for things, such as over-labelling or parent-child consolidation. required: - trackingIdentifier properties: trackingIdentifier: type: string description: The external identifier used to track the parcel. This can be the tracking identifier used by carriers or any barcode that identifies the parcel. example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER carrierCode: type: string description: The carrier code (Metapack code). example: DPD_UK carrierDisplayName: type: string description: The name of the carrier. example: DPD UK carrierServiceCode: type: string description: The service code (Metapack code). example: DPD_UK_CLASSIC carrierTrackingURL: type: string description: The link to the carrier website for tracking the parcel. format: uri pattern: ^https:// example: https://track.dpd.co.uk/parcels/REPLACE-WITH-YOUR-TRACKING-IDENTIFIER deliveryRef: type: string description: The unique delivery reference. example: REPLACE-WITH-YOUR-DELIVERY-REF finalDeliveryLeg: type: boolean description: Indicates that the parcel delivery leg is the final stage in the delivery journey. Default to `true`. example: true collection: $ref: '#/components/schemas/Collection' delivery: $ref: '#/components/schemas/DeliveryInformation' order: $ref: '#/components/schemas/Order' parcel: $ref: '#/components/schemas/DeliveryLegParcel' recipient: $ref: '#/components/schemas/Recipient' sender: $ref: '#/components/schemas/Sender' DeliveryLegEvent: title: DeliveryLegEvent description: A delivery leg event for a trackable item, such as a parcel. Supports post-allocation. type: object required: - eventDate - eventTimeZone - trackingIdentifier - eventCode allOf: - properties: trackingIdentifier: type: string description: The external identifier used to track the parcel. This can be the tracking identifier used by carriers or any barcode that identifies the parcel. example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER eventCode: type: string description: Metapack event code. enum: - AWAITING_DESPATCH - DESPATCHED - NOT_YET_RECEIVED_BY_CARRIER - RECEIVED_BY_CARRIER - RECD_BY_CARRIER_NO_ELEC_ADVICE - COLLECTION_REQUESTED - COLLECTION_MADE - COLLECTION_FAILED - ROUTING_ERROR - CARRIER_DELAYS - PARCEL_LOST - DELAYED_NOT_CARRIER - HELD_BY_CUSTOMS - PARCEL_DAMAGED - IN_TRANSIT - RECEIVED_LOCAL_DELIVERY_DEPOT - HUB_SCAN_OUT - CUSTOMS_PROCESSING - COLLECT_AT_LOCAL_PO - SUB_CONTRACTOR_EVENT - OUT_FOR_DELIVERY - SUB_CONTRACTOR_RECEIVED - ADDRESS_QUERY - CUSTOMER_CARDED - DELIVERED_IN_PART - CUSTOMER_TO_COLLECT_FROM_CARRIER - HELD_BY_CARRIER - CUSTOMER_MOVED - REFUSED_BY_CUSTOMER - RETURN_TO_SENDER - NOT_DELIVERED - NOT_DELIVERED_ADDRESSEE_DECEASED - DELIVERED - DELIVERED_TO_PO_BOX - DELIVERED_DAMAGED - INFORMATION - POST_TRANSIT_STATUS - PROOF_OF_DELIVERY - HAZARDOUS_PROHIBITED - CANCELLED - ELEC_ADVICE_RECD_BY_CARRIER - CLOSED_BY_SYSTEM - MISSORTED - DELIVERY_ARRANGED_WITH_RECIPIENT - NO_ACCESS_TO_RECIPIENTS_ADDRESS - COD_AMOUNT_NOT_PAID - CUSTOMER_IDENTIFICATION_FAILED - INVALID_METHOD_OF_PAYMENT - COD_AMOUNT_PAID - CUSTOMS_CLEARED - PARCEL_REPACKED - PARCEL_DISPOSED - INCORRECT_DECLARATION - HELD_BY_IMPORT_CUSTOMS - HELD_BY_EXPORT_CUSTOMS - DELIVERED_TO_NEIGHBOUR - DELIVERED_SPECIFIED_SAFE_PLACE - PARCEL_COLLECTED_FROM_PICKUP_POINT - AWAITING_COLLECTION_FROM_PICKUP_POINT - NOT_COLLECTED_FROM_PICKUP_POINT - DELIVERED_TO_LOCKER_COLLECTION_POINT - DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION - HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING - PARCEL_OVER_LABELLED - PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY - PARCEL_UPDATE_NOTIFICATION_VIA_SMS - PARCEL_UPDATE_NOTIFICATION_VIA_EMAIL - ATTEMPTED_DELIVERY - ATTEMPTED_DELIVERY_2ND - ATTEMPTED_DELIVERY_3RD - READY_FOR_PACKING - CANCELLED_BEFORE_DESPATCH - RETURN_CREATED - RETURN_NEEDS_APPROVAL - RETURN_APPROVED - RETURN_LABEL_CREATED - RETURN_CANCELLED - RETURN_REJECTED - RETURN_WINDOW_EXPIRED - RETURN_RECEIVED - RETURN_COMPLETED - RETURN_COMPLETED_IN_PART - RETURN_NOT_COMPLETED example: AWAITING_COLLECTION_FROM_PICKUP_POINT - $ref: '#/components/schemas/LogisticsEvent' DeliveryLegParcel: type: object properties: parcelRef: type: string description: The external reference used to identify the parcel for this delivery leg. It can be used to group delivery legs for a parcel journey. example: REPLACE-WITH-YOUR-PARCEL-REF items: type: array items: $ref: '#/components/schemas/Item' DeliveryTimeSlot: title: DeliveryTimeSlot description: The time window in which to expect the delivery of the parcel. type: object properties: from: type: string description: Beginning of the time slot for which the delivery has been requested. example: '11:00:00' to: type: string description: End of the time slot for which the delivery has been requested. example: '12:00:00' DeliveryWindow: title: DeliveryWindow type: object description: The window in which to expect the delivery of the parcel. properties: from: type: string description: The earliest date when the parcel is expected to be delivered. format: date-time to: type: string description: The latest date when the parcel is expected to be delivered. format: date-time Error: type: object properties: message: type: string description: Error message. example: This is an error message errorCode: type: string description: Error code. example: PS-XXXX systemMessage: type: string description: System message informing about the error. example: This is a system message related to the error traceId: type: string description: The request identifier from the original request if provided. example: 4d1544c7-1977-4c03-82fa-ecacd1837532 timestamp: type: string description: Timestamp when the error occured. format: date-time EventLocation: type: object description: Location information where the event occured. properties: location: $ref: '#/components/schemas/Location' address: $ref: '#/components/schemas/Address' Images: type: object description: Information about the product images. properties: desktop: type: string format: uri pattern: ^https:// description: The desktop product thumbnail URL to be rendered in the products where utilised. [Metapack Delivery Tracker](https://help.metapack.com/hc/en-gb/articles/360018632258-Delivery-Tracker) requires two image sizes to ensure that image quality is in line with seller's standards. example: https://some.cdn.com/products/images/desktop/PRD-12345.png mobile: type: string format: uri pattern: ^https:// description: The mobile product thumbnail URL to be rendered in the products where utilised. [Metapack Delivery Tracker](https://help.metapack.com/hc/en-gb/articles/360018632258-Delivery-Tracker) requires two image sizes to ensure that image quality is in line with seller's standards. example: https://some.cdn.com/products/images/mobile/PRD-12345.png altTag: type: string description: The alt tag for the product image to support accessibility and enable search engines to read and to describe the product. Use a single tag for both images (desktop and mobile). example: Picture of trainers Item: type: object properties: itemRef: type: string description: The internal identifier used by the shipping location for the trade item, such as the stock-keeping unit (SKU). A unique code that helps a shipper to identify the exact product. It will relate to the product name, but it will probably not be recognised by shoppers. example: PRD-12345-BL-06 Location: type: object description: Information of a location so that it can be displayed on a map. properties: latitude: type: number description: The distance of a place north or south of the equator, measured in degrees. example: 51.52325226913702 longitude: type: number description: The distance of a place east or west of the Greenwich meridian, measured in degrees. example: -0.1146692876584629 what3words: type: string description: What3Words code used to display a location on a map. example: lowest.homes.calm LogisticsEvent: type: object properties: eventDate: type: string description: Date and time when the event occured. format: date-time eventSource: type: string description: Source of the event, such as `CARRIER` or `STORE`. example: STORE eventTimeZone: type: string description: Time zone at the location of the event. example: Europe/London eventLocation: $ref: '#/components/schemas/EventLocation' Message: type: object properties: message: type: string description: Information message. example: Deleted 2 delivery legs Order: type: object description: An order contains information about the seller and the customer. It is used to provide the full overview of the deliveries for all the parcels within this order by using the order reference (`orderRef`). properties: orderRef: type: string description: The reference of the order. example: REPLACE-WITH-YOUR-ORDER-REF orderDate: type: string description: Date and time the order was accepted. format: date-time marketplace: type: string description: Ecommerce website where product or service information is provided by multiple third parties. example: Acme billingAddress: $ref: '#/components/schemas/Address' customer: $ref: '#/components/schemas/Customer' products: type: array items: $ref: '#/components/schemas/Product' seller: $ref: '#/components/schemas/Seller' Parcel: type: object description: Information about the parcel. properties: deliveryRef: type: string description: The unique delivery reference. It is used to link a delivery for an order with the delivery legs for the parcels in the delivery. example: REPLACE-WITH-YOUR-DELIVERY-REF parcelRef: type: string description: The external reference used to identify the parcel and its delivery legs. It is used to link delivery legs in a single parcel journey. example: REPLACE-WITH-YOUR-PARCEL-REF deliveryLegs: type: array items: $ref: '#/components/schemas/ParcelDeliveryLeg' items: type: array items: $ref: '#/components/schemas/Item' ParcelDeliveryLeg: type: object properties: carrierCode: type: string description: The carrier code (Metapack code). example: DPD_UK carrierDisplayName: type: string description: The carrier name displayed to a shopper. By default, it is based on the value of the `carrierCode` parameter. However, a seller can overwrite the calculated value of this parameter. The purpose of this parameter is to facilitate regionalisation or personalisation of carrier names to suit seller preferences and to reduce jargon in notifications sent to shoppers. example: DPD UK carrierServiceCode: type: string description: Carrier service used for this particular parcel delivery leg. example: DPD_UK_CLASSIC carrierTrackingURL: type: string description: The link to the carrier website for tracking the parcel. format: uri example: https://track.dpd.co.uk/parcels/REPLACE-WITH-YOUR-TRACKING-IDENTIFIER finalDeliveryLeg: type: boolean description: Indicates that the parcel delivery leg is the final stage in the delivery journey. example: true trackingIdentifier: type: string description: The external identifier used to track the parcel. This can be the tracking identifier used by carriers or any barcode that identifies the parcel. example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER ParcelJourney: title: ParcelJourney description: A parcel journey covers all tracking events (including one or more delivery legs) for either outbound deliveries (including "return to sender" for failed deliveries) or returns. A seller will request parcel journey(s) for an order, so a parcel journey should include all tracking events for all legs for a single parcel. type: object properties: order: $ref: '#/components/schemas/Order' recipient: $ref: '#/components/schemas/Recipient' delivery: $ref: '#/components/schemas/DeliveryInformation' collection: $ref: '#/components/schemas/Collection' parcel: $ref: '#/components/schemas/Parcel' latestTrackingStatus: $ref: '#/components/schemas/TrackingEvent' sender: $ref: '#/components/schemas/Sender' trackingEvents: type: array items: $ref: '#/components/schemas/TrackingEvent' Price: type: object properties: amount: type: number description: The price paid for a product at the checkout. example: 60.99 currencyCode: type: string description: The [three-letter ISO currency code](https://www.iban.com/currency-codes) of the currency used by a shopper to pay for the products in an order. example: GBP Product: type: object properties: productRef: type: string description: The external reference used to identify the product. example: PRD-12345 name: type: string description: The shopper facing name of the product that matches the name of the items purchased at check out. Should match shopping cart name to enable recipient to clearly recognise their products. example: Trainers description: type: string description: A short description of a product that matches the description of the items purchased at checkout. Should match shopping cart information to enable recipients to recognise the products that they purchased. longDescription: type: string description: A longer description of a product that matches the description of the items purchased at checkout. Should match shopping cart information to enable recipients to recognise the products that they purchased. quantity: type: number description: The number of products bought that matches the count purchased at checkout. Should match shopping cart information to enable recipients to recognise the products that they purchased. example: 1 size: type: string description: Where applicable, the size of the product bought that matches the products purchased at checkout. Should match shopping cart information to enable recipients to recognise the products that they purchased. example: 39 / 6 colour: type: string description: Where applicable, the colour of the product bought that matches the products purchased at checkout. Should match shopping cart information to enable recipients to recognise the products that they purchased. example: Blue pageURL: type: string format: uri pattern: ^https:// description: External URL of the relevant product page in the seller's website. example: https://some.cdn.com/products/PRD-12345.html images: $ref: '#/components/schemas/Images' salePrice: $ref: '#/components/schemas/Price' items: type: array items: $ref: '#/components/schemas/Item' Recipient: type: object description: The person receiving the parcel(s) in an order. The recipient is used to provide the destination time zone (`Recipient.timeZone`), which is used to process tracking events received from carriers when they do not provide time zone information with their events. allOf: - $ref: '#/components/schemas/Address' - properties: contact: type: object properties: name: type: string description: The name of the contact. example: John Doe email: type: string description: The email address of the contact. Can be passed to and used by the logistics service provider for the purposes of contact regarding the delivery. example: johndoe@email.com phone: type: string description: The phone number of the contact. Can be passed to and used by the logistics service provider for the purposes of contact regarding the delivery. example: '07814354765' identity: type: object properties: birthDate: type: string description: The date of birth of the person who receives the product(s) in the form of deliveries. Could be used to age check delivery of certain products (for example, alcohol). example: 13/05/1978 Seller: type: object properties: brand: type: string description: The shopper-facing brand name that a shopper expects to see in in-app and other notifications. The brand from which a shopper has purchased products. example: Phasion for Men brandRef: type: string description: A code or reference number that a seller might use in its internal systems to link an order (or parcel) to a specific brand. Could be used instead of the `brand` parameter to map data within seller systems, such as customer service tools or an ecommerce platform. example: PH20MEN companyName: type: string description: The organisation from which a shopper purchases products (orders). It is also the organisation with which a shopper has a contract through a purchase and which the shopper will hold accountable for issues with delivery. This organisation might own its own shipping solutions, including shipping platform, carrier contracts and so on, or it might outsource these to third-party specialists. example: Phasion id: type: string description: Metapack unique reference number that identifies an account within Metapack applications and that can be used to support authentication, users, invoicing, and so on. example: 6a624ffb-1032-4941-ba4b-c23834bfc876 parentOrg: type: string description: Top level of hierarchy if seller has complex structure. The parent organisation sits over various sellers or brands and can be used to group seller accounts for invoicing and related purposes. example: Metapack Sender: title: Sender type: object description: Sender contains the information about the location from where the parcels for a delivery will ship. It contains the source time zone (`Sender.timeZone`), which is used to process tracking events received from carriers when they do not provide time zone information with their events. allOf: - $ref: '#/components/schemas/Address' TrackingEvent: title: TrackingEvent type: object description: Tracking Event allOf: - properties: trackingIdentifier: type: string description: The external identifier used to track a parcel. example: REPLACE-WITH-YOUR-TRACKING-IDENTIFIER deliveryRef: type: string description: The unique delivery reference. example: REPLACE-WITH-YOUR-DELIVERY-REF eventCode: description: Metapack event code. type: string example: AWAITING_COLLECTION_FROM_PICKUP_POINT - $ref: '#/components/schemas/LogisticsEvent' - properties: eventDescription: type: string description: Description of the event according to the event code. Description can vary to provide more user-friendly terminology or if natural language changes over time. Description can vary because it could be requested in different languages for inclusion in an application or in a notification. example: Ready to collect eventCategory: type: string description: Grouping of different events that have the same behaviour or will in future drive the same treatment in products. Grouped together to enable functionality to be coded at the group level for efficiency. enum: - EXCEPTION_ACTION - EXCEPTION_INFO - EXCEPTION_FATAL - HAPPY - SYSTEM example: HAPPY exceptionMessage: type: string description: |- The shopper-facing headline and body text that positions the nature of the exception, states the impact of the exception, and provides a "call to action" for the shopper (if applicable). Some exception messages contain the token {brandName}. This token serves as a placeholder and will be replaced with the brand located at `order.seller.brand` in the parcel journey. If the brand has not been supplied and is therefore unavailable the token will be returned and will need to be replaced by the application. example: The delivery company will provide instructions about where to collect your order. statusCode: type: string description: This is used to define the stage of a parcel journey when an event occurred. enum: - CANCELLED_BEFORE_DESPATCH - DELIVERED - IN_TRANSIT - NOT_COLLECTED - NOT_DELIVERED - ORDER_PROCESSING - OUT_FOR_DELIVERY - PERSONALISATION_IN_PROGRESS - PREPARING_FOR_DESPATCH - PROCESSING - READY_TO_COLLECT - RETURN_CANCELLED - RETURN_COMPLETED - RETURN_CREATED - RETURN_DECLINED - RETURN_RECEIVED - RETURN_REQUEST_IN_PROGRESS - RETURN_TO_SENDER example: READY_TO_COLLECT statusDescription: type: string description: Description can vary to provide more user-friendly terminology or if natural language changes over time. Description can vary because it could be requested in different languages for inclusion in an application or a notification. example: Ready to collect