Dispatch Notifications via API
This section describes the manifest shipping requirements sent by Merchants to Global-e via API.
The Manifest allows the timely and correct processing of parcels in the Global‑e hub or in the Merchant’s warehouse.
This procedure is required for:
Merchants sending multi-parcel orders.
Merchants wishing to fulfill backordered items.
The manifest includes information about items and parcels that you ship on a given day and allows Global‑e to:
Create relevant Airway bills (AWB) and export documentation for all parcels when the parcels are processed at the Global-e hub.
Amend out-of-stock items automatically:
The customer is notified in advance that some of the items are out of stock.
The customer is refunded or authorization amounts are amended.
The export paperwork is updated to reflect the correct items and quantities for duties and taxes calculations, ensuring timely release from customs in the destination country.
Shipping via the Global‑e hub: Know in advance how many parcels are on the way and their unique identifier codes so that these can be scanned and processed on arrival.
Note
The manifest is recommended but not required when:
Shipping a single parcel order and you do not require backorder (pre-order) items support. When implementing the manifest, the order is automatically amended for out-of-stock items.
Shipping multi-parcel orders from your warehouse and all parcels are shipped the same day (order fulfilment is not split over a period of few days). When implementing the manifest, the order is automatically amended for out-of-stock items and the airway bills (AWB) and export paperwork are automatically generated.
As part of its cross-border enablement, Global‑e provides the following shipping-related features:
Duties & Taxes calculation
Commercial Invoice generation (or paperless trading when relevant)
Carrier label
Automated international refunds
Order split shipment
Customer dispatch notification and tracking information
As part of the order fulfilment process, the following should be covered to guarantee that the shipping documentation matches the order dispatch:
Multiple parcels order declaration
Order items line cancellation (for example, Out of stock)
Partial delayed shipments (for example, restocking items)
Types of shipping exceptions
ExceptionType | Name | Description |
|---|---|---|
1 | Out-of-Stock | Out of stock, will not be fulfilled. |
2 | Backorder Pre-order Customized Item | Backorder/preorder/customized item/to be restocked will be fulfilled. |
3 | Cancelled by request | The customer requested to remove this product. Will not be fulfilled |
Used in the following cases
(1) Shipping from the Global‑e hub and the merchant notifies about the parcel shipped from the merchant hub to the Global‑e hub,
(2) Out of Stock Notification
(3) WYOL: In this case, no documents are needed.
Note
The manifest process (and related API) is designed to support notifications of parcel preparation/dispatch. Calls should always be made upon dispatching a product and never be used to notify only exceptions.
The only edge case with using only an exception in a call is to notify no further expected items will be dispatched thus requiring to close the order with “Out of stock” and “order complete” where all remaining items would be refunded.
Prerequisites
The Merchant OMS or WhMS should have knowledge of the following information and allow, either directly or through an escalation process, to:
Have the full list of items in the order
Enable selection of items to be dispatched
if applicable, enable the cancellation of line items
if applicable, enable the declaration of items as back-ordered
After performing the effective pick&pack and required actions in the OMS/WhMS, the following integration can be used to process the orders prior to dispatch.
Schedule
The report should be sent once the pick and pack in the Merchant warehouse has been completed for the day and before the orders arrive at the Global-e hub or before the orders are prepared for international shipping by merchants fulfilling from their own warehouse.
Integration General Specification
The following samples are descriptive of typical use cases. For the full extent of the respective call specifications mentioned below, and optional attributes visibility, see the Global‑e API document.
API Call
API call (POST request) - Endpoint: UpdateOrderDispatchV2
https://connect.bglobale.com/Order/UpdateOrderDispatchV2?merchantGUID=abcdabcd-abcd-abcd- abcd-abcdabcdabcd
{
"OrderId": "GE123874638GB",
"MerchantOrderID": "100018322",
"DeliveryReferenceNumber": "123756483",
"IsCompleted": false,
"Parcels": [
{
"ParcelCode": "123454321",
"Products": [
{
"DeliveryQuantity": 1,
"CartItemId": "12365",
"ProductCode": "121212"
},
{
"DeliveryQuantity": 2,
"CartItemId": "12376",
"ProductCode": "131313"
}
]
}
],
"Exceptions": [
{
"CartItemId": "12366",
"ProductCode": "121213",
"ExceptionType": 1
"Quantity": 1
},
{
"CartItemId": "12367",
"ProductCode": "121214",
"ExceptionType": 2,
"ExpectedFulfilmentDate": "2018-01-18"
}
]
}Main Attributes Description
Attribures | Descritption |
|---|---|
OrderId OR (only 1 required) MerchantOrderId | Global‑e Order ID (starting with “GE”) OR Merchant order Id as recorded in own ecommerce platform |
DeliveryReferenceNumber | (optional) Additional informative dispatch reference |
IsCompleted (can be optional) | Once True, all items not already declared as part of a parcel will be cancelled and refunded Until True consolidation of parcels is expected if no backorders If orders have backorders exception specified: not required to allow for dispatch of existing parcels without delay |
ParcelCode (MAX 20 characters) | Merchant unique identifier for each parcel(/box) to be shipped Can be freely generated in any range as long as unique |
ProductCode OR (only 1 required) CartItemId | Product Code/SKU OR Cart Item/Line Identifier (should match cart information fields exchanged at checkout time) |
ExceptionType (With optional quantity) | 1 for explicit item line cancellation (implicit if IsCompleted to “true” and some items were not assigned to a parcel 2 for backordering (differed shipping) |
ExpectedFulfilmentDate (Optional) | (Optional) Tentative target for fulfilment of backordered items (in YYYY-MM-DD format) |
TrackingDetails (see WYOL use case ) | In case the AWB has been generated through other means (WYOL), tracking information can be pushed here |
API Response
Note
The API triggers an asynchronous process, only the first-level JSON body structure will be checked upon receiving a call to trigger a success or failure response. Hence expected results must not be presumed on Success response depending on body sub-attributes processed asynchronously.
Success Response
ResponseInfo : (Reason is optional)
{
"Success": true,
"Reason": "Operation description"
}Failure Response
General API error as ErrorInfo :
{
"Code": "error code",
"Error": "error message",
"Description": "error description"
}Object processing error as ResponseInfo: (Reason is optional)
{
"Success": false,
"Reason": "Processing error detail"
}Use Cases
Examples of request body as UpdateOrderDispatchRequest
Considerations regarding examples for simplicity:
Using
MerchantOrderIDrather than GE OrderIdUsing
ProductCoderather thanCartItemId
Single Parcel Shipping
Order description for this section :
Product-A in quantity 1
Product-B in quantity 2
No Exceptions
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}, {
"ProductCode": "product-B",
"DeliveryQuantity": 2
}
]
}
],
"Exceptions": []
}Explicit Partial Cancellation
Cancellation of 1 product-B
Single Call
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}, {
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
],
"Exceptions": [{
"ProductCode": "product-B",
"ExceptionType": 1
}
]
}Implicit Partial Cancellation
Cancellation of 1 product-B
Single call
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}, {
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
]
}Multi Parcel (No Splitting / Partial Shipping)
Order description for this section :
product-A in quantity 1
product-B in quantity 2
No Exceptions
Single call
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}, {
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 2
}
]
}
]
}Partial Dispatches and Calls with Consolidation Request
Dispatch of 1 product-B at a later date but to be consolidated with other parcels before shipping any.
Note
The 1st call flags the order as incomplete but no “backorder” is specified.
First call (“day 1”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}, {
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
]
}Subsequent call (“day 2”)
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-3",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
]
}Split parcel supporting pre-orders and backorders
Order description for this section :
product-A in quantity 1
product-B in quantity 2
product-C in quantity 1
Explicit Backordering and Explicit Cancellation
Cancellation of 1 product-C
Backordering of 1 product-A
First call (“day 1”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 2
},
]
}
],
"Exceptions": [{
"ProductCode": "product-C",
"ExceptionType": 1
}, {
"ProductCode": "product-A",
"ExceptionType": 2
}
]
}
Subsequent call (“day 2”)
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}
]
}Implicit Partial Cancellation (split)
Cancellation of 1 product-C
Backordering of 1 product-A
First call (“day 1”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 2
}
]
}
],
"Exceptions": [{
"ProductCode": "product-A",
"ExceptionType": 2
}
]
}Subsequent call (“day 2”)
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}
]
}Multiple Partial Dispatches with Explicit Cancellation (Consolidated)
Cancellation of 1 product-B
Backordering of 1 product-A
Backordering of 1 product-C
First call (“day 1”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
],
"Exceptions": [{
"ProductCode": "product-B",
"ExceptionType": 1
}
]
}Subsequent call (“day 2”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}
]
}Subsequent call (“day 3”)
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "100018322-3",
"Products": [{
"ProductCode": "product-C",
"DeliveryQuantity": 1
}
]
}
]
}Partial Dispatch Followed by the Cancellation of Missing Item(s)
First call (“day 1”)
{
"MerchantOrderID": "100018322",
"IsCompleted": false,
"Parcels": [{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}, {
"ProductCode": "product-B",
"DeliveryQuantity": 2
}
]
}
]
}Subsequent call (“day 2”)
Cancellation of product-C as non-available in the end, “close order” call
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [],
"Exceptions": [{
"ProductCode": "product-C",
"ExceptionType": 1
}
]
}« Auto complete » with Split
First Dispatch
1 product-B dispatch 1 product-A backorder 1 product-B backorder 1 product-C backorder | {
"MerchantOrderID": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-1",
"Products": [{
"ProductCode": "product-B",
"DeliveryQuantity": 1
}
]
}
],
"Exceptions": [
{
"ProductCode": "product-A",
"ExceptionType": 2
},
{
"ProductCode": "product-B",
"ExceptionType": 2
},
{
"ProductCode": "product-C",
"ExceptionType": 2
}
]
} |
Intermediate Cancel
1 product-B cancel | {
"MerchantOrderID": "100018322",
"Parcels": [],
"Exceptions": [
{
"ProductCode": "product-B",
"ExceptionType": 1
}
]
} |
Second Dispatch
1 product-A dispatch | {
"MerchantOrderID": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-2",
"Products": [{
"ProductCode": "product-A",
"DeliveryQuantity": 1
}
]
}
]
} |
Closing Cancel (last cannot be dispatched)
1 product-C cancel | {
"MerchantOrderID": "100018322",
"Parcels": [],
"Exceptions": [
{
"ProductCode": "product-C",
"ExceptionType": 1
}
]
} |
WYOL – Recording Parcel Tracking
{
"MerchantOrderID": "100018322",
"IsCompleted": true,
"Parcels": [{
"ParcelCode": "123454321",
"Products": [{
"DeliveryQuantity": 1,
"ProductCode": "121212"
}
],
"TrackingDetails": {
"TrackingNumber": "1111111166",
"TrackingURL": "http://trackingurlofshipper.com",
"ShipperName": "MyCarrier"
}
}
],
"Exceptions": null