Shipping Documents API

​

Introduction

​

Shipping Model Scenarios

• 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).

​

Integration Overview

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.

​

Declare Order Fulfilment and Retrieve Shipping Documents

​

Orders Dispatch Notification

​

Prerequisites

• Display the complete list of items in the order
• Enable the selection of items for dispatch

​

Integration Steps

​

Identify Orders Processed via the Global-e API

• 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.

​

Declare Order Fulfilment and Get Documents

• Shipper Name (order level)
• Tracking Number (for each parcel and order level)
• Tracking URL (for each parcel and order level)

​

OrderDocument DocumentTypeCode list

​

Notify Order Dispatch and Retrieve Carrier Manifest

​

Mark the Order Fulfilled

• 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

​

Single Parcel Shipping

{
    "OrderId": "100018322",
    "Parcels": [
        {
            "ParcelCode": "100018322-1",
            "Products": [
                { "ProductCode": "product-A", "DeliveryQuantity": 1 },
                { "ProductCode": "product-B", "DeliveryQuantity": 2 }
            ]
        }
    ]
}

​

Multi Parcel

{
    "OrderId": "100018322",
    "Parcels": [
        {
            "ParcelCode": "100018322-1",
            "Products": [
                { "ProductCode": "product-A", "DeliveryQuantity": 1 }
            ]
        },
        {
            "ParcelCode": "100018322-2",
            "Products": [
                { "ProductCode": "product-B", "DeliveryQuantity": 2 }
            ]
        }
    ]
}

​

Split Parcels

{
    "OrderId": "100018322",
    "Parcels": [
        {
            "ParcelCode": "100018322-1",
            "Products": [
                { "ProductCode": "product-A", "DeliveryQuantity": 1 },
                { "ProductCode": "product-B", "DeliveryQuantity": 1 }
            ]
        }
    ]
}

{
    "OrderId": "100018322",
    "Parcels": [
        {
            "ParcelCode": "100018322-2",
            "Products": [
                { "ProductCode": "product-B", "DeliveryQuantity": 1 }
            ]
        }
    ]
}

​

Country Of Origin, Parcel Weight & Dimensions

• 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.

{
    "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

​

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

​

DispatchOrders Error Codes

​

Void Parcel

​

Void Parcel Error Handling

​

Appendix – Shopify Managed Markets

​

Testing Shopify Managed Markets Integration

​

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

​

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.

​

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.