Skip to main content

Documentation Portal

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 fulfillment 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 canceled 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 fulfillment 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 MerchantOrderID rather than GE OrderId

  • Using ProductCode rather than CartItemId

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