> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Shipping Documents API
> Global-e's Shipping API provides merchants with fully integrated shipping capabilities to get the relevant shipping labels and documentation to ship straight from their warehouses or through a 3PL.
## Introduction
Global-e's Shipping API provides merchants with fully integrated shipping capabilities to get the relevant shipping labels and documentation to ship straight from their warehouses or through a 3PL. For this purpose, the integration is based on implementing the Global-e shipping solution akin to a simplified carrier integration.
This API works seamlessly across Global-e direct integrations and Managed Markets merchants.
This document describes the implementation of the API calls required to perform the necessary shipping activities.
## Shipping Model Scenarios
To fulfil a cross-border order, use the Global-e APIs to generate shipping documents, including labels and commercial invoices. This ensures accurate and compliant documentation for the shipment, enabling a duty guarantee.
Global-e supports the following document and document formats:
* Shipping labels in 6x4 format, available in PDF/ZPL/EPL for specific UK carriers.
* Commercial Invoices in 8.5x11 inch letter size or A4 format, provided only when a carrier and country do not support Paperless Trading (PLT).
Global-e offers various shipping models to leverage our extended carrier network with specialised services through the Global-e facility.
| Scenario | Documents Returned by the API |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Direct dispatch from the warehouse with final mile carrier | Carrier label; PDF invoice(s); Additional documents (e.g. Dangerous Goods Note) |
| Shipping via the Global-e Hub | 6x4 ZPL/PDF cross-docking label for the Global-e hub |
## Integration Overview
Ensuring an accurate description of the shipment contents on both the label and Commercial Invoice (CI) is crucial to avoid potential overcharges for duties and taxes. The information declared in the API must align with the actual contents of the parcels being shipped.
The shipping process and its integration are built based on the following logic:
1. Receive and identify Global-e operated orders.
2. Declare orders fulfilled and ready for dispatch in API call #1.
3. Retrieve shipping documents as a response to API call #1:
* The carrier label
* The commercial invoice (for non-paperless countries)
* Other documents, such as the Dangerous Goods note
4. Declare effective dispatch of orders in API call #2.
5. Retrieve the carrier manifest for carrier sign-off as a response to API call #2.
6. Declare the fulfilment back to the eCommerce platform.
The following diagrams illustrate the standard fulfilment and dispatch flow through the end-to-end API process.
### Declare Order Fulfilment and Retrieve Shipping Documents
### Orders Dispatch Notification
## Prerequisites
The Merchant Order Management System (OMS) or Warehouse Management System (WMS) should be familiar with and support the following features, either directly or through an escalation process:
* Display the complete list of items in the order
* Enable the selection of items for dispatch
After completing the pick & pack and necessary actions in the OMS/WMS, follow the integration steps outlined in this document to process orders for dispatch.
## Integration Steps
### Identify Orders Processed via the Global-e API
You can receive orders directly on your eCommerce platform or via 3rd party integrations. Accordingly, the following scenarios should be supported to associate orders with the Global-e integration to generate shipping documentation:
Shipping/Carrier code as provided in the order payload received:
* In Shopify's context, such indication is available via the order `shipping_lines` code or title field. Mapping of values presented in these fields should allow mapping orders to the Global-e integration.
* Outside Shopify, standard carrier mapping as currently performed should be used.
Additionally when using a direct integration with Shopify to retrieve orders, for example, Managed Markets, the `merchant_of_record_app_id` field will be provided. When Global-e is responsible for an order, this value will be set to `2745565185`. However, if you are an independent merchant doing this integration, you may choose either of the methods above per your integration.
The `merchant_of_record_app_id` field is available on Shopify webhooks, RESTful GET Orders calls or GraphQL queries. Version 2022-10 or later of the Shopify API is required for this field to be present.
Both methods should be implemented to comply with different merchant setups in pushing orders to the WMS/3PL.
Orders will arrive via the same channel as all other orders for a merchant. It's important to map such orders and prevent them from being shipped via means other than Global-e.
### Declare Order Fulfilment and Get Documents
From the orders indicated as fulfilled with possible exceptions, the GetShippingDocuments API (`POST /Order/GetShippingDocuments`) will return the required shipping documentation as a base64 encoded byte array and URL for printing.
Parameters, schema, examples, and the interactive playground for `POST /Order/GetShippingDocuments`.
The response of the Get Shipping Documents API call (GSD) will include the tracking information of the shipment(s). Tracking information includes:
* Shipper Name (order level)
* Tracking Number (for each parcel and order level)
* Tracking URL (for each parcel and order level)
Tracking should always be stored from the `ParcelsTracking` array by matching the relevant parcel code tracking. If the tracking is done on the order level, the tracking information of the order (Tracking Number and URL) will be populated on the parcel level as well (with the same values).
### OrderDocument DocumentTypeCode list
Use `DocumentTypeCode` to identify the type of document returned by the API and how to print it.
**Labels for Zebra/Thermal Printer**
| DocumentTypeCode | Description | Paper format | Notes |
| ---------------- | ------------- | ------------ | -------------------------------------------------------------- |
| 4 | Carrier Label | 6x4 | For direct dispatch. Default configuration |
| 7 | GELabel | 6x4 | Configurable. Use for solution-specific scenarios upon request |
| 9 | ArchiveLabel | 6x4 | Only for specific |
**A4 / Letter Size for Laser printer**
| DocumentTypeCode | Description | Paper format | Notes |
| ---------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------- |
| 1 | CommercialInvoice | A4 / Letter Size | Provided only for destinations not supporting electronic customs declarations |
| 5 | VATInvoice | A4 / Letter Size | legacy |
| 6 | DangerousGoods | A4 / Letter Size | Only for merchants shipping Dangerous Goods |
| 10 | Delivery Advice | A4 / Letter Size | For specific UAE Free Trade Zones requirements |
### Notify Order Dispatch and Retrieve Carrier Manifest
The DispatchOrders API (`POST /Order/DispatchOrders`) provides the necessary carrier manifest, encoded as a base64 byte array, and a printing URL for all orders with printed labels since the last DispatchOrders call. Non-Shopify orders are tagged as Dispatched to Customer and set up to send tracking notification emails.
Parameters, schema, examples, and the interactive playground for `POST /Order/DispatchOrders`.
### Mark the Order Fulfilled
Once a label has been used to ship a set of goods, update the fulfilment state back to the merchant platform to complete the workflow.
* **Status:** Success
* **Tracking Company:** Use the `ShipperName` returned by the GetShippingDocuments call
* **Tracking Number:** Use the `ParcelTrackingNumber` returned by the GetShippingDocuments call
* **Items:** Only those items that have shipped with this label should be identified
## Use Cases
Examples of request body as `UpdateOrderDispatchRequest`. Order description for this section: product-A in quantity 1, product-B in quantity 2.
### Single Parcel Shipping
Single call:
```json theme={null}
{
"OrderId": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-1",
"Products": [
{ "ProductCode": "product-A", "DeliveryQuantity": 1 },
{ "ProductCode": "product-B", "DeliveryQuantity": 2 }
]
}
]
}
```
### Multi Parcel
Single call:
```json theme={null}
{
"OrderId": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-1",
"Products": [
{ "ProductCode": "product-A", "DeliveryQuantity": 1 }
]
},
{
"ParcelCode": "100018322-2",
"Products": [
{ "ProductCode": "product-B", "DeliveryQuantity": 2 }
]
}
]
}
```
### Split Parcels
First call ("day 1"):
```json theme={null}
{
"OrderId": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-1",
"Products": [
{ "ProductCode": "product-A", "DeliveryQuantity": 1 },
{ "ProductCode": "product-B", "DeliveryQuantity": 1 }
]
}
]
}
```
Subsequent call ("day 2"):
```json theme={null}
{
"OrderId": "100018322",
"Parcels": [
{
"ParcelCode": "100018322-2",
"Products": [
{ "ProductCode": "product-B", "DeliveryQuantity": 1 }
]
}
]
}
```
## Country Of Origin, Parcel Weight & Dimensions
When using Global-e Enterprise services for shipping, consult with your account manager about the availability of this feature.
You can send the product's country of origin, parcel weight, and parcel dimensions to DHL and Aramex via the ship request, according to the data you provided via GetShippingDocuments. If any of the following attributes are not specified, this information is taken from the default value provided in the product catalogue, as part of the ecommerce integration:
* **Product Country of Origin**
* **Parcel Weight:** For Global-e Enterprise, the weight of the products within the parcel is calculated according to the parcel weight with the simple average method. Example: for a parcel weighing 1000 Grams with two items, each item will weigh 500 Grams. The weight is always in Grams in GetShippingDocuments.
* **Parcel Dimensions:** For Aramex, Global-e provides the parcel dimensions according to the first parcel even for consolidated shipment (in the current implementation, the dimensions exist at the shipment level and not per parcel). The dimensions are always in Centimetres in GetShippingDocuments.
```json theme={null}
{
"OrderId": "{Order_id}",
"Parcels": [{
"ParcelCode": "123454321",
"Length": 37.5,
"Width": 24,
"Height": 13,
"Weight": 1300,
"Products": [
{ "DeliveryQuantity": 1, "ProductCode": "sku121212", "OriginCountryCode": "IL" },
{ "DeliveryQuantity": 2, "ProductCode": "sku131313", "OriginCountryCode": "US" }
]
}]
}
```
## Error Handling
### Processing Exception Scenarios
The following diagrams illustrate the processing-exception scenarios.
### Normal Operation – No issues
### With Error Handling
### Scenario: Order to be Cancelled after a Failed API request
### Scenario: End-of-day Manifesting
### Scenario: End-of-day Manifesting with Possible Errors
### Scenario: End-of-day Manifesting with Possible Errors and Error Handling
### GetShippingDocuments Error Codes
| Error Code | Error Text in response | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A100 | Invalid information schema. | Relevant for technical errors. For example, wrong JSON object structure |
| A200 | Could not retrieve documents and/or process orders. Either the order has the wrong status or partial information is provided. | Relevant for logical errors. For example, the order has the wrong status |
| A300 | There is at least one SKU that was not part of the original order. Please use only SKUs which were originally ordered. | Relevant for cases in which the fulfilled SKUs contain an SKU not originally ordered (and SKU validation is turned on) |
| A400 | Either there are no valid SKUs to place in parcels or parcels could not be created. | Relevant for cases in which ALL fulfilled SKUs were not originally ordered and if we were to amend there will be no item to put in parcels (and SKU validation is turned off) |
| A500 | SMB API returns an error | There was an error generating a label via the Global-e SMB Bridge |
| A018 | Failed to generate an AWB with `{shipper name}` | When a ship request fails |
| A019 | The order was cancelled and cannot be shipped | When the order is in 'Cancelled' status |
### DispatchOrders Error Codes
| Error Code | Error Text in response | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| B100 | There are no orders valid for dispatch. | Relevant for dispatch requests that do not contain any valid order for dispatch |
| B200 | Could not determine the destination hub. Either none or more than one hub was found. | Relevant for consolidated shipment dispatch requests that contain orders associated with more than one hub |
| B300 | The number of outer boxes cannot be greater than the number of parcels. The total number of parcels is %Number of Parcels% and the number of outer boxes is %Number of outer boxes%. | |
| B400 | Could not create the manifest | Relevant when the hub manifest cannot be created |
| B500 | Could not create AWB | Relevant when the consolidated AWB cannot be created |
| B600 | Configuration error. Cannot determine source hub. Please contact Global-e TechSupport | There is a configuration error on the Global-e side, more than one merchant hub is configured |
| B700 | Unknown failure | Relevant for general errors and unhandled exceptions |
| B800 | Hub Code is required | Merchant is configured to use multiple hubs per order but did not send hub code |
| B001 | Order ID not found | Refers to Order ID provided by the merchants but it does not exist |
| B002 | Order cannot be dispatched. Order and/or parcels have the wrong status. | Possible reasons: Order AWB generation has failed; Order yet to be processed with GetShippingDocuments; Order already dispatched |
| B003 | Order must be dispatched as part of a consolidated shipment | For consolidated post orders |
| B004 | Order must NOT be dispatched as part of a consolidated shipment | For NON-consolidated post orders |
## Void Parcel
The Void Parcel API lets you take out a declared parcel if you do not intend to send it or if it needs to be updated due to changed shipment requirements.
At least one order ID should be provided in the request — the Global-e `OrderId` or the merchant's `MerchantOrderId`.
The endpoint is `POST /Parcel/VoidParcel`. Parameters: `OrderId` (mandatory) — order unique identifier; `ParcelCode` (mandatory) — code used to identify the ParcelCode to void; `MerchantOrderId` — the merchant's order unique identifier.
Parameters, schema, examples, and the interactive playground for `POST /Parcel/VoidParcel`.
### Void Parcel Error Handling
| Error Code | Error Text | Additional Information |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| C100 | The parcel cannot be voided due to the status of the parcel. For a Global-e operated hub, only the following statuses can be voided: Failed Transfer To Shipping; Shipped By Merchant | This is the error in case the hub is operated by Global-e and the parcel has the wrong status. |
| C101 | The parcel cannot be voided due to the status of the parcel. For merchant-operated hubs, only the following statuses can be voided: Failed Transfer To Shipping; Shipped By Merchant; Received In Hub | This is the error in case the hub is operated by the Merchant and the parcel has the wrong status. |
| C102 (Log) | The parcel was voided, but the shipper's API to cancel the shipment failed. The following information is available from the shipper. Error code: ``; Error text: `` | The API succeeds (IsSuccess=True). Add it to the log and to the relevant field in the response |
| C103 | Internal unknown failure | - |
| C104 | The parcel code was not found, or the parcel was already voided | - |
## Appendix – Shopify Managed Markets
### Testing Shopify Managed Markets Integration
To do an end-to-end test for Managed Markets orders, you need to use a Shopify Shop that has Managed Markets enabled. We recommend you use a separate test shop. You can also reuse an existing test shop by simply enabling Managed Markets.
#### Build a New Shopify Shop
* A new developer shop should be created and connected to your software or warehouse management system.
* This shop should have at least one physical product in its catalogue.
* Set up the location of a USA-based warehouse and allocate products to it so that orders can be placed.
* Enable Shopify Payments.
* Be aware that sandbox shops cannot be promoted to production shops.
#### Enable Managed Markets
Contact Shopify support. Let them know you are testing an SMP shipping integration, what your shop's myshopify.com domain is, and some of your existing Shopify merchants. Make it clear you would like to make a sandbox integration — this will allow you to test using test credit cards and test carrier accounts.
You should be given access to create an application for Managed Markets. Fill this out to the best of your ability. As this is a sandbox shop, accurate data is not required to be accepted.
After creating an application, you will soon get an email indicating that your application has been accepted. Click the link in this email and you will be walked through the process of enabling Managed Markets.
You will also receive a `merchantGUID` from Shopify.
Adding a country picker to your shop template can help streamline the testing of international orders, but is not required.
#### Testing Managed Markets
* You must place an order via standard checkout and not a draft order, created through Shopify Admin.
* Create a new Incognito window every time you submit a test order to avoid previous addresses being reused in the checkout.
* If you added a country picker, you can select the country you want to test.
* Any physical product may be purchased.
* Provide an accurate country, city, state, and postal code at checkout; name and address can be anything.
* Use the following test credit card data: Card Number `4111 1111 1111 1111`, Name: Any Name, Expiration `03/2030`, CVC `737`.
You should see the order in Shopify Admin immediately. The order should also appear in your Warehouse Management system, correctly flagged as either a Managed Markets order (if it's an international order) or as a standard order (if it's domestic).
#### Example Test Orders
* **Destination France (75001, Paris):** This should be a Managed Markets order. Ensure that the label is correct and that a Commercial Invoice (CI) was recorded. The label should print at 4"x6". France allows Paperless Trading (PLT) and the CI need not be printed.
* **Destination Brazil (Rio de Janeiro):** This should be a Managed Markets order. Ensure that the label is correct and that a Commercial Invoice (CI) was recorded. The label should print at 4"x6". Brazil is not a PLT country — the CI should be printed at 8.5"x11".
* **Destination USA (Domestic):** This is not a Managed Markets order. Ensure that your standard operations for assigning carriers and printing labels still apply to this order.