> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stage.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get tracking events
> Receive status events on the delivery status of an order — a list of Global-e order IDs and/or tracking numbers (all the same direction), returning their tracking events.
The Get Tracking Events API lets you receive status events on the delivery status of an order — a list of either forward shipments after checkout completion (`outbound`) or returns (`inbound`), up to 100 per call — and returns their status. Having tracking events for return shipments also lets refunds be triggered automatically upon confirmation of returned-item receipt (or any other tracking event).
**Prerequisite — one direction per request.** A request may include a list of Global-e order IDs, a list of tracking numbers, or both — but all the same type: `inbound` or `outbound`. Inbound and outbound cannot be mixed; to request both, issue two separate requests.
The full list of tracking events reported by Global-e (`GlobaleEventCode` → `GlobaleEventDescription`), returned in the `TrackingEvents` array of each successful result:
| Code | Description |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | The parcel has been created but is waiting to be manifested (i.e. despatched) |
| 2 | The parcel has been manifested (i.e. despatched) |
| 3 | The carrier has yet to receive the parcel into their network |
| 4 | The carrier has acknowledged receipt of the parcel into their network |
| 5 | The carrier has acknowledged receipt of the parcel into their network but did not receive the required electronic manifest (pre advice file) |
| 6 | A collection request has been acknowledged by the carrier |
| 7 | The carrier has successfully collected a parcel from a customer |
| 8 | The carrier has failed to collect a parcel from a customer |
| 9 | The parcel has been misrouted by the carrier due to incorrect routing on the label |
| 10 | The parcel has been misrouted by the carrier due to incorrect routing on the label |
| 11 | The parcel has been advised as lost within the carriers network |
| 12 | The parcel has been delayed due to factors beyond the carriers control (i.e. inclement weather) |
| 13 | The parcel is with Customs (NR: This does not necessarily mean that the parcel has been refused entry into the destination country) |
| 14 | The parcel has been damaged |
| 15 | The parcel is in transit (NB: This could either be en route to a country hubs delivery depot) |
| 16 | The parcel has been Left at the local post office for collection |
| 17 | The parcel is with a 3rd party sub-contractor and a tracking event has occurred (refer to "Confirmation' field for further information if provided |
| 18 | The parcel has left the delivery depot for the recipients address |
| 19 | The parcel has been received by a sub-contractor 3rd party |
| 20 | The carrier has a query concerning the recipients address (i.e. Unable to locate,. incorrect post code etc.) |
| 21 | The carrier has left a calling card for the customer as they were unable to deliver the parcel |
| 22 | The carrier has delivered part of the consignment advised (e.g. Parcel 1 parcel of a 2 parcel consignment has been delivered) |
| 23 | The parcel is available to collect from the carriers premises |
| 24 | The parcel is being held at the delivery depot |
| 25 | The recipient no longer resides at the delivery address |
| 26 | The recipient refused to take delivery of the parcel |
| 27 | The parcel is to be returned to the sender |
| 28 | The carrier was unable to deliver the parcel (No reason specified) |
| 29 | The parcel has been successfully delivered |
| 30 | The carrier has provided some information concerning the parcel |
| 31 | An event has occurred after the parcel has been delivered / lost or RTS (i.e. acknowledgement of a claim) |
| 32 | Special delivery instructions to app.? |
| 33 | The delivery / collection has requested to be cancelled |
| 34 | The carrier has received an electronic pre advice (manifest) for this parcel |
| 35 | The parcel has been at a status that does not set an actual or default end date and as such has been 'closed" after a certain period of time dependent on the environment it belongs to |
| 36 | The parcel was miss sorted by the carrier and sent to the incorrect -deliver? dept. |
| 37 | The recipient has arranged a delivery with the carrier |
| 38 | The carrier attempted to deliver the parcel but was unable to access the recipients address to deliver or leave a calling card (i.e. Closed office building, gated development etc) |
| 39 | The payment for cash on delivery could not be collected |
| 40 | The recipient's identification failed |
| 41 | The payment could not be processed due to an invalid method of payment by recipient. |
| 42 | The payment for cash on delivery of parcel has been collected by the carrier |
| 43 | The parcel has been cleared for delivery |
| 44 | The parcel has been re boxed / re packed |
| 45 | The parcel has been requested to be disposed |
| 46 | The declared weight of the parcel does not match the actual weight of the parcel. |
| 47 | The parcel has been held by destination Customs |
| 48 | The parcel has been held by origin Customs |
| 49 | The parcel has been delivered to a neighbour's address |
| 50 | The parcel has been delivered to a safe place suggested by the recipient |
| 51 | The customer has collected the parcel from the store |
| 52 | The parcel is received at store and is ready for collection by recipient |
| 53 | The parcel is ready for collection at the store and it has not been collected after a period of time |
| 54 | The parcel has been delivered to a locker or collection point and is ready to be collected by the recipient. |
| 55 | The parcel has been delivered to the recipient's preferred point instead of collecting from depot or re-delivery or return |
| 56 | The package has been held by the carrier whilst collecting recipient details for clearance |
| 57 | The parcel has been re-labelled |
| 58 | The parcel attributes lie outside of service capability, i.e. weight/size/remote area issues |
| 59 | An SMS has been transmitted to the recipient to inform that the parcel is out for delivery today |
| 60 | An email has been transmitted to the recipient to inform that the parcel is out for delivery today |
| 61 | The carrier attempted delivering the parcel but could not deliver |
| 62 | The package/s arrived to the destination country |
| 63 | A choice that the customer has made for delivery to a safe place (the delivery not happened yet) |
Returned per item in the `FailedTrackingNumbers` list. `{0}` is replaced with the relevant value (order ID, tracking number, or limit).
| Code | Message |
| ---- | ------------------------------------------------------------------------------------- |
| E01 | The shipment (`{0}`) is not trackable with this shipper |
| E02 | The order (`{0}`) is not trackable with this shipper |
| E03 | The provided tracking number (`{0}`) was not found |
| E04 | The provided order ID (`{0}`) was not found |
| E05 | The order (`{0}`) is not associated to the merchant |
| E06 | The tracking number (`{0}`) is not associated to the merchant |
| E07 | The order (`{0}`) doesn't have a tracking number |
| E08 | The tracking event type parameter is invalid |
| E10 | The number of input values (Tracking Number and Order IDs) exceeded the (`{0}`) limit |
| E11 | At least one Order ID or Tracking Number should be specified |
## OpenAPI
````yaml api-reference/specs/gettrackingevents.yaml POST /Shipment/GetTrackingEvents
openapi: 3.0.3
info:
title: GetTrackingEvents
version: 1.0.0
description: >-
The Get Tracking Events API lets you receive status events on the delivery
status of an order. Reporting of tracking events allows both Global-e's
customers and 3rd parties to stay informed about the exact location and
status of returned items throughout the entire external return journey.
Having tracking events for return shipments also allows refunds to be
triggered automatically upon confirmation of returned item receipt (or any
other tracking event). The API accepts one or more order ID numbers, up to
100, on a single call — a list of either orders moved to forward shipments
after checkout completion (outbound) or returns (inbound) — and returns
their status.
servers:
- url: https://{globale_api_domain}
variables:
globale_api_domain:
default: globale_api_domain
description: Global-e API host, supplied to the merchant by Global-e.
security: []
tags:
- name: GetTrackingEvents
x-page-title: GetTrackingEvents
- name: 'Direction: Merchant → Global-e'
- name: 'Domain: Shipping'
paths:
/Shipment/GetTrackingEvents:
post:
tags:
- GetTrackingEvents
summary: Get tracking events
description: >-
Receive status events on the delivery status of an order. Accepts a list
of Global-e order IDs, a list of Global-e tracking numbers, or both —
but all the same type (inbound or outbound) — and returns their tracking
events.
operationId: getTrackingEvents
parameters:
- name: MerchantGUID
in: header
required: true
schema:
type: string
description: Merchant's unique identifier (present in the documented example).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetTrackingEventsRequest'
example:
EventSinceInUTC: '2025-04-01T20:08:05Z'
Type: outbound
OrderIds:
- GE381652418TS
TrackingNumbers: []
responses:
'200':
description: >-
Tracking events for the requested orders/tracking numbers. Each
successful entry is returned in SuccessfulTrackingNumbers; per-item
failures are returned in FailedTrackingNumbers (each carrying an
ErrorInfo).
content:
application/json:
schema:
$ref: '#/components/schemas/GetTrackingEventsResponse'
example:
Data:
SuccessfulTrackingNumbers:
- GlobaleOrderID: GE381652418US
MerchantOrderID: '#22165241'
GlobaleParcelCode: 'null'
GlobaleRMANumber: '2832849023948'
MerchantRMANumber: '832849932893'
IsTrackingNumberActive: true
TrackingNumber: GE381652418TS2864637A0
Type: outbound
TrackingUrl: >-
https://mailingtechnology.com/tracking/?tn=GE381652418TS2864637A0
ShipperName: Spring XBS Packet Registered-GlobalE
TrackingEvents:
- ShipperEventDescription: >-
The parcel has been created but is waiting to be
manifested (i.e. despatched)
TrackingEventDateTimeInUTC: '2024-03-24T09:19:08'
GlobaleEventCode: '1'
GlobaleEventDescription: >-
The parcel has been created but is waiting to be
manifested (i.e. despatched)
ShipperEventCode: '0'
TrackingEventStatus: []
Location:
FullAddress: BALTIMORE AIRPORT,MD-USA
- GlobaleOrderID: GE8770052418US
MerchantOrderID: '#23816524'
GlobaleParcelCode: 'null'
GlobaleRMANumber: '0239283284948'
MerchantRMANumber: '8884994993293'
IsTrackingNumberActive: true
TrackingNumber: GE381652418TS2864637A0
Type: outbound
TrackingUrl: >-
https://mailingtechnology.com/tracking/?tn=GE381652418TS2864637A0
ShipperName: Spring XBS Packet Registered-GlobalE
TrackingEvents:
- ShipperEventDescription: >-
The parcel has been created but is waiting to be
manifested (i.e. despatched)
TrackingEventDateTimeInUTC: '2024-03-24T09:19:16'
GlobaleEventCode: '1'
GlobaleEventDescription: >-
The parcel has been created but is waiting to be
manifested (i.e. despatched)
ShipperEventCode: '0'
TrackingEventStatus: []
Location:
FullAddress: BALTIMORE AIRPORT,MD-USA
FailedTrackingNumbers:
- OrderId: ABC123
TrackingNumber: '123'
ErrorInfo:
Code: E06
Error: >-
The tracking number (123) is not associated with the
merchant
Description: null
Success: false
Errors: null
components:
schemas:
GetTrackingEventsRequest:
type: object
title: GetTrackingEventsRequest
required:
- Type
properties:
EventSinceInUTC:
type: string
description: >-
Date and time for the earliest time of the order shipment status,
UTC, in RFC 2822 format (for example, Fri, 8 Aug 2014 17:13:07
+0000).
OrderIds:
type: array
items:
type: string
description: >-
List of Global‑e Order IDs. Up to 100 in each request. Note: each
OrderId, string, has prefix GE followed by numbers, in the format
GE1234. Max length: 100 chars. One of either OrderIds or
TrackingNumbers are mandatory.
TrackingNumbers:
type: array
items:
type: string
description: >-
List of Global‑e tracking numbers. Up to 100 in each request, with
prefix GE followed by numbers in the format GE1234. Conditional —
one of either OrderIds or TrackingNumbers are mandatory.
Type:
type: string
enum:
- inbound
- outbound
description: The shipment direction. One of the following - inbound, outbound.
GetTrackingEventsResponse:
type: object
title: GetTrackingEventsResponse
properties:
Data:
type: object
properties:
SuccessfulTrackingNumbers:
type: array
items:
$ref: '#/components/schemas/SuccessfulTrackingNumbers'
FailedTrackingNumbers:
type: array
items:
$ref: '#/components/schemas/FailedTrackingNumbers'
Errors:
nullable: true
description: >-
Present in the documented example (null on success). Shape
undocumented.
SuccessfulTrackingNumbers:
type: object
title: SuccessfulTrackingNumbers
properties:
GlobaleOrderID:
type: string
description: The Global-e order ID for the parcel.
GlobaleParcelCode:
type: string
description: The parcel code used by Global-e.
GlobaleRMANumber:
type: string
description: The Global‑e RMA number.
IsTrackingNumberActive:
type: boolean
description: Identifies if the tracking number is in use.
MerchantOrderID:
type: string
description: The order ID used by the merchant for the order.
MerchantRMANumber:
type: string
description: >-
The return merchandise authorization number used by the merchant for
the parcel.
ShipperName:
type: string
description: The shipping method name.
TrackingEvents:
type: array
items:
$ref: '#/components/schemas/TrackingEvent'
description: >-
Tracking details for each Global-e order ID in the request, in
ascending tracking event time.
TrackingNumber:
type: string
description: >-
Global‑e tracking number, with prefix GE followed by numbers in the
format GE1234.
TrackingURL:
type: string
description: Full tracking URL used for this parcel.
Type:
type: string
enum:
- inbound
- outbound
description: Type of shipment. One of the following values - inbound or outbound.
FailedTrackingNumbers:
type: object
title: FailedTrackingNumbers
properties:
ErrorInfo:
allOf:
- $ref: '#/components/schemas/ErrorInfo'
description: ErrorInfo object with the error code and error details.
OrderID:
type: string
description: Unique order identifier.
Success:
type: boolean
description: >-
Indicates success or failure. True - If the API call is successful.
False - If the API call failed.
TrackingNumber:
type: string
description: The Global-e tracking number.
TrackingEvent:
type: object
title: TrackingEvent
properties:
GlobaleEventCode:
type: string
description: >-
The Global-e tracking event code. See the "Global-e Tracking Events"
table on the reference page for the full list (codes 1–63).
GlobaleEventDescription:
type: string
description: The description of the Global-e tracking event.
Location:
$ref: '#/components/schemas/Location'
ShipperEventCode:
type: string
description: The shipper's tracking event code.
ShipperEventDescription:
type: string
description: The shipper's tracking event description.
TrackingEventDateTimeInUTC:
type: string
description: The date and time of the tracking event, UTC.
TrackingEventStatus:
type: array
items:
type: string
enum:
- DispatchedToCustomer
- DeliveryAttempt
- Delivered
- ReturnedByShipper
description: >-
The tracking event status. One of the following values -
DispatchedToCustomer, DeliveryAttempt, Delivered, ReturnedByShipper.
Empty when the event carries no such status (e.g. a newly created
parcel).
TrackingNumber:
type: string
description: The tracking number as the shipper has specified.
TrackingURL:
type: string
description: Full tracking URL used for this parcel.
ErrorInfo:
type: object
title: ErrorInfo
description: ErrorInfo object with the error code and error details.
properties:
Code:
type: string
description: The error code.
Error:
type: string
description: The error message.
Description:
type: string
description: The error description.
Location:
type: object
title: Location
description: The location associated with the tracking event.
properties:
FullAddress:
type: string
description: The full address of the tracking event location.
````