Order Methods
CreateOrderPlatform
This API starts the process of creating an order in the Global-e system. OrderCreationSource
is an important attribute in the Class SendFinalCartData
and the value of OrderCreationSource
can be called in different ways in the order creation process.
URL
https://{server_name}/Checkout/CreateOrderPlatform
Parameters
Request
Provides full CheckoutCartInfo details.
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Full cart data for the order creation process. |
Return
Name | Type | Description |
---|---|---|
| Object | Indicates if the API call was successful. |
Examples
Request
{ "ShippingDetails": { "UserId": "5920775766266", "UserIdNumber": null, "UserIdNumberType": null, "FirstName": "Tema", "LastName": "Test", "FirstNameInLocalCulture": null, "LastNameInLocalCulture": null, "MiddleName": null, "Salutation": null, "Phone1": "3000000001", "Phone2": null, "Fax": null, "Email": "[email protected]", "Address1": "ORREGO LUCO 54", "Address2": "", "City": "PROVIDENCIA", "CityRegion": null, "StateOrProvince": "Maule", "Zip": "7510115", "CountryCode": "CL", "StateCode": "ML", "Company": null }, "BillingDetails": { "UserId": "5920775766266", "UserIdNumber": null, "UserIdNumberType": null, "FirstName": "Tema", "LastName": "Test", "FirstNameInLocalCulture": null, "LastNameInLocalCulture": null, "MiddleName": null, "Salutation": null, "Phone1": "3000000000", "Phone2": null, "Fax": null, "Email": "[email protected]", "Address1": "ORREGO LUCO 54", "Address2": "", "City": "PROVIDENCIA", "CityRegion": null, "StateOrProvince": "Maule", "Zip": "7510115", "CountryCode": "CL", "StateCode": "ML", "Company": null }, "ShippingMethodId": "40032680", "IsTaxPrePaid": true, "IsSameDayDispatchSelected": false, "GiftCards": null, "CustomerPayments": { "Duties": 5807.0, "Taxes": 19491.0, "CustomClearanceFee": 0.0, "ShippingPrice": 11377.0, "Total": 122075.0 }, "CheckoutUrl": "https://globale-dev.myshopify.com/56721965226/checkouts/ 372520cb016c0fdb8459367755b69113?key=667dc86bdac6597af3ad9b2229c8397f", "MarketplaceData": null, "OrderReplacementData": null, "OrderData": null, "IsMarketplaceOrder": false, "IsReplacementOrder": false, "IsOOS": true, "IsSyncOrder": false, "CountryCode": "CL", "ClientIP": null, "Currency": { "OriginalCurrencyCode": "GBP", "CurrencyCode": "CLP" }, "PriceModification": null, "Culture": { "PreferedCultureCode": null, "InputDataCultureCode": "en", "CultureCode": null }, "LocalShippingOptions": [{ "Carrier": "globaleintegration_standard", "CarrierTitle": "globaleintegration_standard", "CarrierName": "globaleintegration_standard", "Code": "globaleintegration_standard", "Method": "globaleintegration_standard", "MethodTitle": "globaleintegration_standard", "MethodDescription": "globaleintegration_standard", "Price": 0.0, "IsPreferred": true } ], "Products": [{ "ProductCode": "40166999589034", "ProductGroupCode": "6707847102634", "Name": "ADIDAS | CLASSIC BACKPACK BBBB", "NameEnglish": null, "Keywords": null, "URL": null, "Description": null, "DescriptionEnglish": null, "GenericHSCode": null, "Weight": "0", "Height": null, "Length": null, "Width": null, "Volume": null, "ImageURL": "https://cdn.shopify.com/s/files/1/0567/2196/5226/products/ 85cc58608bf138a50036bcfe86a3a362.jpg?v=1620302515", "ImageWidth": null, "ImageHeight": null, "OriginCountryCode": null, "ListPrice": "115000.0", "OriginalListPrice": null, "SalePrice": "85400.0", "OriginalSalePrice": null, "UnitSalePriceForDuties": null, "SalePriceBeforeRounding": null, "OriginalSalePriceAfterGlobalEDiscount": null, "OriginalSalePriceAfterRounding": null, "VATRateType": { "VATRateTypeCode": "vatRateType_GB_20", "Name": "vatRateType_GB_20", "Rate": 20.0, "InternalVATRateTypeId": 0 }, "LocalVATRateType": { "VATRateTypeCode": "vatRateType_GB_20", "Name": "vatRateType_GB_20", "Rate": 20.0, "InternalVATRateTypeId": 0 }, "Brand": { "BrandCode": "ADIDAS", "Name": "ADIDAS" }, "Categories": [{ "CategoryCode": "2222", "Name": "2222" }, { "CategoryCode": "adidas", "Name": "adidas" }, { "CategoryCode": "backpack", "Name": "backpack" }, { "CategoryCode": "egnition-sample-data", "Name": "egnition-sample-data" }, { "CategoryCode": "getest", "Name": "getest" }, { "CategoryCode": "globaleteg", "Name": "globaleteg" }, { "CategoryCode": "men", "Name": "men" }, { "CategoryCode": "pc - test2", "Name": "pc - test2" } ], "OrderedQuantity": 1, "DeliveryQuantity": -1, "CartItemId": "40166999589034-0", "ParentCartItemId": null, "CartItemOptionId": null, "IsBlockedForGlobalE": false, "IsBundle": null, "Attributes": null, "AttributesEnglish": null, "MetaData": { "Attributes": [{ "AttributeKey": "backpack", "AttributeValue": "backpack" } ] }, "IsFixedPrice": true, "HandlingCode": null, "NetWeight": null, "NetVolume": null, "IsVirtual": false, "ProductGroupCodeSecondary": null, "ProductCodeSecondary": "123456", "GiftMessage": null, "OriginalMerchantUnitSalePrice": null, "VATCategory": null, "IsBackOrdered": false, "BackOrderDate": null, "ProductClassCode": null, "PriceCoefficientRate": null, "IsGiftCard": false, "GiftCardId": null, "PlatformIsActive": null, "MerchantPriceForDuties": null, "HubCode": null, "OriginalSalePriceAfterDiscounts": null, "EstimatedDeliveryDate": null, "AvailableQuantity": null } ], "CartToken": null, "MerchantCartToken": "372520cb016c0fdb8459367755b69113", "MerchantCartHash": "nf2JfTVEveA+Sn53c7Fo0w==", "HubId": null, "PaymentInstallments": null, "UserDetails": { "UserId": "5920775766266", "IsB2B": false, "AddressDetails": [{ "FirstName": "Test", "LastName": "Test", "Email": "[email protected]", "Phone1": "3000000000", "Address1": "ORREGO LUCO 54", "City": "Colorado", "Zip": "7510114", "CountryCode": "CL" } ] }, "UrlParameters": null, "Discounts": [], "Benefits": null, "VATRegistration": null, "FreeShipping": null, "VoucherData": null, "LoyaltyData": null, "SessionId": null, "AuthToken": null, "UseIpv6": false, "rateData": null, "WebStoreCode": "globale-dev.myshopify.com", "WebStoreInstanceCode": null, "LoyaltyPoints": null, "AllowMailsFromMerchant": false, "AllowDirectCommunicationFromMerchant": false, "CartId": null, "MerchantOrderId": "TestMerchantOrderId", "MerchantInternalOrderId": "TestMerchantInternalOrderId", "BillingCustomFields": null, "ShippingCustomFields": null, "ShippingMethodCode": null, "ShippingServiceCode": "DHL", "OrderCreationSource": "ShopifyAPI" }
CreateOrderRefund (Merchant to Global-e)
The CreateOrderRefund API Issues a refund for the order specified in the orderRefund
argument. Optionally, this method may include the list of RefundProducts
to refund. If orderRefund.TotalRefundAmount
is not specified, it is converted to the end customer’s currency based on the RefundAmount
or OriginalRefundAmount
values for the RefundProduct
s in the refundProductsList
and their respective Product VAT rates.
If orderRefund.FullRefund
is specified as true:
A full refund is created.
refundProductsList
should not be provided, otherwise, the call fails with an error "Full refund requested but list of RefundProduct is not empty."The
orderRefund.TotalRefundAmount
andorderRefund.OriginalTotalRefundAmount
values which are provided in the call are ignored and recalculated based on the order details.
ELSE
If product.RefundAmount
AND product.OriginalRefundAmount
are not specified then:
product.RefundAmount
ANDproduct.OriginalRefundAmount
are calculated based on the order product price.orderRefund.TotalRefundAmount
is recalculated based on the products refund amount plus the sum of all non-product related refund components(
orderRefund.ServiceGestureAmount
+orderRefund.DutiesAmount
+orderRefund.ShippingAmount
)
In case a full refund is not performed or the refund request/refund item quantity is not valid, a JSON response is returned in accordance to the Merchant Account Settings ReturnResponseOfErrorInfoStruct
value.
If this Merchant Account Settings is true, the JSON response is in the
ErrorCode
struct.Otherwise, the response is in the
ResponseInfo
struct.
The Merchant Account Settings ‘SetAllPrepaidReturnsWithRefund
’ supports all prepaid returns includes free by Admin and free by Merchant that the return IDcwill be sent to NotifyOrderRefund
and wiil link the OrderRefund
with the return.
Method/URL
POST https://{globale_api_domain}/Order/CreateOrderRefund
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Order refund details for the specified order | Yes |
| List of | List of | Note that this products list is mandatory if the refund is issued for Products. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Response information for the API call. | No |
Errors
Error Codes
The ErrorInfo
includes a field code containing a numeric value.
Code | Description |
---|---|
1001 | Order already fully refunded or cancelled |
1002 | Requested refund amount is greater than the remaining amount available for a refund for this order |
1003 | Invalid quantity |
1004 | Refund request must contain at least one refund component |
1005 | Cartitemid {currentRefundProduct.CartItemId} doesn’t exists for order {orderRefundObj.OrderId |
1006 | CartItemId {currOrderProduct.CartItemId} exceeded the quantity of the available products to refund |
Examples
Request
[ { "CartItemId": "134643", "RefundQuantity": "1", "RefundAmount": "42", "RefundReason": { "OrderRefundReasonCode": "RETURN", "Name": "RETURN" }, "RefundComments": "" }, { "CartItemId": "134644", "RefundQuantity": "1", "RefundAmount": "58", "RefundReason": { "OrderRefundReasonCode": "RETURN", "Name": "RETURN" }, "RefundComments": "" } ]
Response Error
{ "Code": "1006", "Error": "Cartitemid 1 exceeded the available products quantity to refund", "Description": "After Method ValidateProducts. refund amount: 67.8700 , available loyalty points: 0.0000" }
CreateOrderRefund API - Out of Stock
The Out of Stock (OOS) feature allows merchants to indicate products as out-of-stock through the CreateOrderRefund
API without specifying the refund amount.
This feature enabled the following actions:
Modification of the product quantity.
Recalculation of duties and taxes.
Adjustment of shipping costs (if there are no flat rates).
The update of associated documents.
The Issuing of a product refund.
If all the products within an order are indicated as out of stock, the order status is changed to 'Cancelled by Merchant'.
Refunds
The out-of-stock quantities are indicated by using the product quantity field.
Any provided amount associated with a product with an out-of-stock refund reason is ignored.
If out-of-stock is provided for a product that a product appeasement is made for, only the remaining amounts are refunded.
Mapping
Out-of-stock products must be assigned a pre-mapped refund reason in order to be recognized by the system.
Mapping is established between the merchant's refund reasons and Global-e's internal reasons, as specified in the MapMerchantOrderRefundReasons
table,
Examples of codes in the MapMerchantOrderRefundReasons
table
Code | Refund Reason |
---|---|
5 | Out of Stock |
14 | Out-of-Stock Item |
23 | Product out of stock |
Errors
Validation Errors
The following situations cause the amend and refund operation to fail and return an error in the CreateOrderRefund
response.
Situation | Error Message |
---|---|
Combining various refund reasons, including out-of-stock and non-out-of-stock reasons, within a single | "Issuing a refund for out-of-stock products alongside other refund reasons is not permitted. Please include any out-of-stock products in a separate call without other refund reasons." |
If the quantity of out-of-stock products exceeds the quantity of remaining products. | "The number of out-of-stock products exceeds the number of remaining products." |
If the quantity of out-of-stock products is zero or not provided. | "Out-of-stock quantity missing or zero. Please provide a valid quantity." |
If a product is declared as out-of-stock for an order in a not allowed status. Note: Out-of-stock products can only be declared for pre-shipped products. | “The current order status %Order status name% does not permit the declaration of out-of-stock products”. |
Example
[ { "CartItemId":"39493377065032-0", "RefundQuantity":1, "RefundAmount":79.00, "RefundReason":{ "OrderRefundReasonCode":"Out of stock", "Name":"Out of stock" } }, { "CartItemId":"39638402039880-1", "RefundQuantity":1, "RefundAmount":0.00, "RefundReason":{ "OrderRefundReasonCode":"Out of stock", "Name":"Out of stock" } } ]
DispatchConsolidatedShipment
Returns a list of details for the orders. Can consume a list of Global‑e order IDs.
Method/URL
https://{server_name}/Order/DispatchConsolidatedShipment
Parameters
Request
Include post data list for order IDs and outer boxes amount.
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Includes order manifest data for the order shipment process. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Provides order documents for the order shipment process. |
Examples
Request
{ "OrderIds":[ "GE2794623GB", "GE2794622GB", "GE2794621GB" ], “OuterBoxesAmount”: 1 }
DispatchOrders
Returns manifest documents. Can consume either a list of Global-e order IDs or a list of merchant order IDs. If the optional hubCode
parameter is specified, then only the parcels or orders that were sent from the specified hub will be dispatched.
Method/URL
https://{server_name}/Order/DispatchOrders
Parameters
Request
Provide post data list of order IDs.
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Provides order manifest data for the order shipment process. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Provides order documents for the order shipment process. |
Examples
Request
Request 1
{ "HubCode": "Store", "OrderIds": ["GE2794623GB", " GE2794622GB", " GE2794621GB"] }
Request 2
{ "OrderIds": ["2794623", " 2794622", " 2794621"] }
Edit Order
Important
This API does not apply to Shopify.
The Edit Order API lets you change an order. The API has two separate URLs with identical structure. The quote URL will return the updated order content and prices without changing the order. To apply the changes, call the editing URL with the same request.
Please note: the edit is not obligated to be identical to the quote total price. It is advised to immediately call the edit request following an approval of a quote.
Assumptions
The following assumptions apply:
Orders can be edited only when are with “Received by Global-e” status.
Editing an order to a lower value will be possible if the payment has not been captured yet.
Editing an order to a higher value will be allowed only if the merchant is willing to subsidize the difference between the original and the adjusted order value. The end customer will not be charged for any additional cost.
The edit request must contain new items- new additional products or exchanging current ones. The API cannot be used to only remove items from an order.
EditOrder API
Method/URL
Quote Endpoint
POST https://{server_name}/api/orders/changes/quote
Editing Endpoint
POST https://{server_name}/api/orders/changes
Parameters
Request
Parameter | Type | Description | Mandatory |
---|---|---|---|
| Object | Details of changes to order, including of products to add to or remove from the order. | Yes |
Response
Parameter | Type | Description | Mandatory |
---|---|---|---|
| Object | Object with merchant order information. | Yes |
Errors
Error Codes
Code | Description |
---|---|
| Success |
| Bad Request.
|
| Forbidden.
Message: “ |
Examples
Request
{ "OrderId": "GE379858112TS", "RemovedProducts": [ { "cartItemId": "1", "quantity": 1 } ], "NewProducts": [ { "ProductCode": "750518703039M", "CartItemId": "2", "OrderedQuantity": 1, "OriginalSalePrice": 125.12, "ReplacementOfCartItemId": "1" } ], "subsidizeHigherValue": 0 // enum No = 0, Yes = 1 }
Response
The response payload is a Merchant.Order object.
{ "OrderId": "GE379858112TS", "CurrencyCode": "GBP", "Products": [ { "Sku": "750518703039M", "CartItemId": "2", "ParentCartItemId": null, "Quantity": 1, "Price": 125.12, "InternationalPrice": 160, "DiscountedPrice": 125.12, "InternationalDiscountedPrice": 160, } ], "Discounts": [ { "Name": "Hidden DDP", "Description": "Discount generated to discount the DDP", "Price": 8, "InternationalPrice": 10.00, "ProductCartItemId": null, } ], "TotalDutiesAndTaxesPrice": 79.83, "USSalesTax": 0.00, "CCFPrice": 12.40, "TotalDutiesPaidByCustomerPrice": 0.00, "InternationalDetails": { "CurrencyCode": "EUR", "TotalPrice": 160.00, "TransactionCurrencyCode": "EUR", "TransactionTotalPrice": 160.00, "TotalShippingPrice": 0.00, "TotalCCFPrice": 14.79, "TotalDutiesPrice": 0.00, "USSalesTax": 0.00, "DutiesGuaranteed": true, "ConsignmentFee": 0.0000, "DiscountedShippingPrice": 0.00 } }
Success Response
OK (200)
Error Response
{ "Errors": [ { "Code": "B100", "Message": "<Validation error>", "Description": "<error id>" } ] }
GetOrdersDetails
Returns a list of orders and their details. Can function with a list of Global‑e order IDs.
URL
https://{server_name}/Order/GetOrdersDetails
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| Object OrdersDetailsFilter | Full post data list of order IDs. |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object Merchant.Order | Provides merchant order details for the order process. |
Examples
Request
{ "OrderIds": ["GE2794623GB", "GE2794622GB", "GE2794621GB"] }
GetShippingDocuments
Returns the existing shipping documents for the requested order, and also shipping documents and parcels for the orders specified in the request.
Usage
There are two usages:
The request is issued with an empty list of parcels, and/or exceptions (no
hubCode
is provided). Here all the existing shipping documents for the requested order are returned.The request includes a list of parcels for the
OrderId
/MerchantOrderId
, and/or the list of exceptions. It returns:- Updates to order status and Delivery Quantities for the products and Merchant’s internal Delivery Reference Number if applicable. Optionally, it can include Exceptions to report on out-of-stock items and items that will be shipped later on. In addition, there is an option to add tracking information on each parcel or for the entire order.
- Update the status of orders and parcels received in the Hub. If the optional
hubCode
is provided, assign the specified parcels for the specified hub. The feature is used when an order includes parcels to be sent from different hubs.Optional: You can add information to be used later when the shipping request is placed to FedEx. This is implemented by adding the
ShippingAdditionalInformation
property in the order level or the parcel level (not both).When the shipping is handled by 3PL, depending on the merchant configuration, the
GELabel
may be set to 4, to print a Global-e label at the hub.
URL
https://{server_name}/Order/GetShippingDocuments
Parameters
Request
Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| Object UpdateOrderDispatchRequest | Full post data including Note: | Y |
Response
Name | Type | Description |
---|---|---|
| Object OrderDocumentsResponse | Receive object OrderDocumentsResponse. |
Examples
Request
Sample request for the first usage with an empty list of parcels and empty list of exceptions, returning all the existing shipping documents for the requested order
{ "OrderId": "GE123874638GB", "MerchantOrderID": "100018322", "DeliveryReferenceNumber": "123756483", "IsCompleted": true, "Parcels": [], "Exceptions": [] }
Sample request for the second usage with a list of parcels and exceptions, which updates the order status
{ "HubCode": "Store", "OrderId": "GE123874638GB", "MerchantOrderID": "100018322", "DeliveryReferenceNumber": "123756483", "IsCompleted": true, "Parcels": [{ "ParcelCode": "123454321", "Products": [{ "DeliveryQuantity": 1, "CartItemId": "12365", "ProductCode": "121212" }, { "DeliveryQuantity": 2, "CartItemId": "12376", "ProductCode": "131313" } ], "TrackingDetails": { "TrackingNumber": "111111122666" }, /*Add ShippingAdditionalInformation at the order level or at the package level, not both.*/ "ShippingAdditionalInformation": [{ "name": "ITNNumber", "value": "12345" } ] } ], "Exceptions": [{ "CartItemId": "12366", "ProductCode": "121213", "ExceptionType": 1 }, { "CartItemId": "12367", "SKU": "SKU121214", "ExceptionType": 2, "ExpectedFulfilmentDate": "2018-01-18" } ], "TrackingDetails": { "TrackingNumber": "111111122666" }, /*Add ShippingAdditionalInformation at the order level or at the package level, not both.*/ "ShippingAdditionalInformation": [{ "name": "ITNNumber", "value": "12345" } ] }
SendOrder (Automation - Internal)
sendOrder (stringcartToken
, UserDetailsshippingDetails
, UserDetailsbillingDetails
, stringshippingMethodId
, boolisTaxPrePaid, stringpaymentMethodId
, CheckoutCartDetailscardDetails
)
Sends information collected from the end customer in the checkout form, to Global‑e, and creates a pending payment order in the Global‑e system.
For non-PCI compliant merchants, if a “card” payment method is selected, the end customer must be presented with a standard card form to be submitted to Global‑e secured environment, to complete the purchase. For PCI-compliant merchants, card details may be specified in the cardDetails
argument.
If an alternative payment method is selected, the end customer must be redirected to the URL specified in the PaymentActionURL
property for this order’s SendOrderResponseInfo
. After the payment is taken, the user will be redirected to the URL on the merchant’s site that will include HMAC hash which can be used to validate the payment authorization URL parameters.
The returned Order property for this order’s SendOrderResponseInfo
will contain the order in the Global-e system. This Order includes all the details, including the end customer pricing that can be used on the merchant’s side for My Account and other customer-facing purposes.
This method is entitled to the Merchants who implement API checkout, instead of using the checkout widget. All these methods assume that a new SendCart
call will be required if the shipping country is changed.
SAMPLE
URL:
https://{server_name}/Order/SendOrder?cartToken=707ce8e4-bae7-4138-bfbd-000a480f54b0&shippingDetails={"FirstName":"John","LastName":"Smith","Phone1":"1234567890","Email":"[email protected]","Address1":"5 Broadway St.","City":"New York","StateOrProvice":"New York","StateCode":"NY","Zip":"123456"}&billingDetails={"FirstName":"John","LastName":"Smith","Phone1":"1234567890","Email":"[email protected]","Address1":"5 Broadway St.","City":"New York","StateOrProvice":"New York","StateCode":"NY","Zip":"123456"}&isTaxPrePaid=true&paymentMethodId=2
ACCEPTS
string
cartToken
Cart token returned by the
SendCart
method preceding the current method call.UserDetails
shippingDetails
Shipping details entered by the end customer in the checkout form. If the
CountryCode
is included, it is ignored (as stated above, a new SendCart call is required if the shipping country is changed).UserDetails
billingDetails
The billing details entered by the end customer in the checkout form.
bool
isTaxPrePaid
Indicates if the end customer has selected or has been forced to prepay duties & taxes.
string
paymentMethodId
(optional)Global‑e identifier of the payment method that was selected in the merchant’s checkout. This is mandatory for alternative payment methods. If not specified, a “card” payment method will be assumed and the card brand will be determined on the Global‑e side by the card number.
CheckoutCardDetails
cardDetails
(optional)The payment card details specified in the merchant’s checkout (for PCI-compliant merchants).
RETURNS
SendOrderResponseInfo
class
SendOrderToMerchant (Global-e to Merchant)
Note
This API is part of Global-e's extensions and plug-ins. Merchants do not need to implement this API unless a custom integration is required.
This API posts the new order or updates the existing order on the merchant’s site.
When implementing a Global-e extension or plug-in, this method is required to create the customer order in the merchant’s system, clear the user’s basket, and optionally, reserve the inventory.
If
order.PaymentDetails
are provided, this method also performs the payment and returns the currency and amount actually charged in theMerchant.ResponseInfo
.If additional shipping documents are required for merchants that are shipping the order themselves, then it is indicated in
AdditionalRequiredDocuments
. In that case, the merchant should delay the fulfillment until the documents are ready and provided to the merchant in theSendAdditionalRequiredDocumentsToMerchant
webhook.
Method/URL
POST https://www.merchant-site-domain.com/order-update-create-url
Parameters
Request
Requests can contain more parameters than listed.
Name | Type | Description | Mandatory |
---|---|---|---|
order | Object | Information about the order. |
Response
Note
Some values are encoded and require the merchant to decode them, for example URLs, addresses, emails, and phone numbers.
Name | Type | Description | Mandatory |
---|---|---|---|
ResponseInfo | Object | Indicates if an API call was successful or not and why. |
Examples
Request
Request Sample 1
{ "ClearCart": true, "UserId": null, "CurrencyCode": "ILS", "Products": [{ "Attributes": [{ "AttributeKey": "color", "AttributeValue": "GREY" } ], "ProductName":"Ribbed Modal Tank Flare Pants Set", "Sku": "7290012491726", "Price": 21.55, "Quantity": 8, "VATRate": 18, "InternationalPrice": 4.84, "CartItemId": "11007", "Brand": null, "Categories": [] } ], "Customer": { "EmailAddress": "[email protected]", "IsEndCustomerPrimary": false, "SendConfirmation": false }, "PrimaryShipping": { "FirstName": "GlobalE", "LastName": "GlobalE", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "21/D, Yegi'a Kapayim st. Yellow building - Floor 1", "Address2": "Test Address2", "City": "Petach Tikva", "StateCode": "NN", "StateOrProvince": null, "Zip": "4913020", "Email": "[email protected]", "Phone1": " 972 73 204 1384", "Phone2": "Test Phone2", "Fax": "Test Fax", "CountryCode": "IL", "CountryName": "Israel", "CollectionPointId": "030749" }, "SecondaryShipping": { "FirstName": "John", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "Amishav%2024", "Address2": null, "City": "Paris", "StateCode": null, "StateOrProvince": null, "Zip": "66666", "Email": "John.Smith%40global-e.com", "Phone1": "98756344782", "Phone2": null, "Fax": null, "CountryCode": "FR", "CountryName": "France", "CollectionPointId": null }, "ShippingMethodCode": "globaleintegration_standard", "Discounts": [{ "Name": "Shipping discount provided by globale", "Description": "Auto calculated according to products", "Price": 35.31, "DiscountType": 2, "VATRate": 18, "CouponCode": null, "InternationalPrice": 6.58 "MetaData":"" } ], "InternationalDetails": { "CurrencyCode": "EUR", "TotalPrice": 64.88, "TransactionCurrencyCode": "EUR", "TransactionTotalPrice": 64.88, "TotalShippingPrice": 32.74, "TotalDutiesPrice": 0, "ShippingMethodCode": "2", "ShippingMethodName": "EMS", "PaymentMethodCode": "1", "PaymentMethodName": "Visa", "DutiesGuaranteed": false, "OrderTrackingNumber": null, "OrderTrackingUrl": "http://www.israelpost.co.il/itemtrace.nsf/mainsearch?openform", "OrderWaybillNumber": null, "OrderWaybillUrl": null, "ShippingMethodStatusCode": "0", "ShippingMethodStatusName": "undefined", "CardNumberLastFourDigits": "7854", "ExpirationDate": "2023-06-30", "TotalVATAmount": 11.14 }, "PaymentDetails": null, "PrimaryBilling": { "FirstName": "GlobalE", "LastName": "GlobalE", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "21/D, Yegi'a Kapayim st. Yellow building - Floor 1", "Address2": null, "City": "Petach Tikva", "StateCode": null, "StateOrProvince": null, "Zip": "4913020", "Email": "[email protected]", "Phone1": " 972 73 204 1384", "Phone2": null, "Fax": " 972 73 204 1386", "CountryCode": "IL", "CountryName": "Israel", "CollectionPointId": null }, "SecondaryBilling": { "FirstName": "John", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "Amishav%2024", "Address2": null, "City": "Paris", "StateCode": null, "StateOrProvince": null, "Zip": "66666", "Email": "John.Smith%40global-e.com", "Phone1": "972500000", "Phone2": null, "Fax": null, "CountryCode": "FR", "CountryName": "France", "CollectionPointId": null }, "OrderId": "GE927127", "StatusCode": "N/A", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "CartId": "9936", "MerchantOrderId": null, "PriceCoefficientRate": 1, "OrderCreationSource": 0, "IsMoto": true, "ModifiedProduct": "G007163737" "AdditionalRequiredDocuments": [ { "DocumentTypeCode": "11 (value from enum)", "DocumentTypeName": "EAD", }, ] }
Request Sample 2
{ "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd", "OrderId": "GE12345678GB", "CartId": "56004460", "UserId": "cecofzj348wdhbr98UbNNDa", "CurrencyCode": "GBP", "PriceCoefficientRate": 1.340000, "RoundingRate": 0.8774285714285714285714285714, "UrlParameters":"[{\"Key\":\"associateOrder\",\"Value\":\"false\"}}], "OrderCreationDate":"2024-05-29T12:33:08.443", "EffectiveFXRate":0.944130024000, "WebStoreInstanceCode": "GlobalEDefaultStoreInstance", "DiscountedShippingPrice": 8.77, "DoNotChargeVAT": false, "AllowMailsFromMerchant": true, "CustomerComments": null, "IsFreeShipping": false, "FreeShippingCouponCode": null, "ShipToStoreCode": null, "InternationalDetails": { "CurrencyCode": "USD", "TotalPrice": 38.00, "TransactionCurrencyCode": "USD", "TransactionTotalPrice": 38.0000, "TotalShippingPrice": 15.3600, "DiscountedShippingPrice": 10.0000, "DutiesGuaranteed": false, "TotalDutiesPrice": 0.0000, "PaymentMethodCode": "1", "PaymentMethodName": "Visa", "ShippingMethodCode": "608", "ShippingMethodName": "DHL Express Worldwide", "ShippingMethodTypeCode": "Express", "ShippingMethodTypeName": "Express Courier (Air)", "PaymentTransactionReference":"89288", "DeliveryDaysFrom": 3, "DeliveryDaysTo": 4, "OrderTrackingNumber": null, "OrderTrackingUrl": "https%3a%2f%2fwww2.bglobale.com%2fOrder%2fTrack%2fmZyd%3fOrderId%3dGE4874348GB%26ShippingEmail%3djsmith%40merchant.com", "CardNumberLastFourDigits": "7854", "ExpirationDate": "2023-06-18" }, "Products": [{ "CartItemId": "10367295488044", "Sku": "2410016114", "Price": 30.7100, "Quantity": 1, "VATRate": 20.000000, "InternationalPrice": 35.0000, "RoundingRate": 0.8774285714285714285714285714, "IsBackOrdered": false, "BackOrderDate": null, "DiscountedPrice": 24.57, "InternationalDiscountedPrice": 28.0000, "GenericHSCode":"392800", "GiftMessage": null, "MetaData": { "Attributes": [{ "AttributeKey": "giftnotemessage", "AttributeValue": "Hello, world" }, { "AttributeKey": "giftnotefont", "AttributeValue": "FONTTYPE1" }, { "AttributeKey": "WRTY", "AttributeValue": "Warranty card" } ] } } ], "Discounts": [{ "DiscountType": 1, "Name": "20% off", "Description": "20% off all non-sale items.", "Price": 6.1400, "VATRate": 20.000000, "InternationalPrice": 7.0000, "CouponCode": "GO20", "DiscountCode": "Email_Sign_up-20%_off", "ProductCartItemId": "10367295488044", "LoyaltyVoucherCode": null }, { "DiscountType": 2, "Name": "Shipping discount for fixed price", "Description": "Shipping discount provided from fixed price range 24663", "Price": 4.7000, "VATRate": 20.000000, "InternationalPrice": 5.3600, "CouponCode": null, "DiscountCode": null, "ProductCartItemId": null, "LoyaltyVoucherCode": null } ], "PrimaryShipping": { "FirstName": "Jenny", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "12+E+11th+St", "Address2": null, "City": "New+York", "StateCode": "NY", "StateOrProvince": "New York", "Zip": "10003", "Email": "jsmith%40merchant.com", "Phone1": "0123456789", "Fax": null, "CountryCode": "US", "CountryCode3": "USA", "CountryName": "United States" }, "SecondaryShipping": { "FirstName": "GlobalE", "LastName": "East Midlands Airport", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "96a, Beverley Road", "Address2": "East Midlands Airport\r\nGE12345678GB", "City": "Derby", "StateCode": "NN", "StateOrProvince": null, "Zip": "DE74 2SA", "Email": "[email protected]", "Phone1": "01332 818723", "Fax": null, "CountryCode": "GB", "CountryCode3": "GBR", "CountryName": "United Kingdom" }, "PrimaryBilling": { "FirstName": "Jenny", "LastName": "Smith", "MiddleName": null, "Salutation": null, "Company": null, "Address1": "12+E+11th+St", "Address2": null, "City": "New+York", "StateCode": "NY", "StateOrProvince": "New York", "Zip": "10003", "Email": "jsmith%40merchant.com", "Phone1": "0123456789", "Fax": null, "CountryCode": "US", "CountryCode3": "USA", "CountryName": "United+States" }, "SecondaryBilling": { "FirstName": "GlobalE", "LastName": "UK Limited", "MiddleName": null, "Salutation": null, "Company": "GlobalE", "Address1": "45 Leather Lane", "Address2": null, "City": "London", "StateCode": null, "StateOrProvince": null, "Zip": "EC1N 7TJ", "Email": "[email protected]", "Phone1": "+ 44 (0)808 258 0300", "Fax": "+ 44 (0)203 514 7171", "CountryCode": "GB", "CountryCode3": "GBR", "CountryName": "United Kingdom" }, "OrderPaymentMethods":[ { "PaymentMethodGuid":"23ATEM329IF9493", "IsGiftCard":false, "GiftCardFields":null, }], "AdditionalRequiredDocuments": [ { "DocumentTypeCode": "11", "DocumentTypeName": "EAD", } ] }
UpdateOrder (Not implemented, Internal)
UpdateOrder
(string orderId
, string merchantOrderId
, List<OrderProduct> products, List<OrderDiscount> discounts, string stateCode
, decimal shippingPrice
)
The UpdateOrder
method receives the Global-e or the Merchant OrderId and returns taxes and duties international prices for the specified stateCode
(in countries where the state impacts taxes and duties calculation) and the shipping price.
Call this method to recalculate taxes and duties when products are removed from the order after placement (because they are out-of-stock).
This method is for Merchants who implement the non-MOR checkout (when Global-e is not the Merchant On Record).
SAMPLE
Body:
{ "orderId": "GE123456GB", "stateCode": "", "shippingPrice": 10, "products": [{ "productCode": "SKU1", "cartItemId": "1", "deliveredQuantity": 1 } ], "discounts": [{ "discountCode": "10Percent", "discountValue": 30 } ] }
URL:
https://{server_name}/Order/UpdateOrder
ACCEPTS
string
orderId
(optional)Global‑e order id of the updated order. Either
orderId
ormerchantOrderId
should be specified.string
merchantOrderId
(optional)Merchant order id of the updated order. Either
orderId
ormerchantOrderId
should be specified.List<
OrderProduct
> productsThe updated list of products (i.e. after out-of-stock items have been removed).
List<
OrderDiscount
> discountsThe updated list of discounts (i.e. after all irrelevant discounts have been removed, such as discounts related to products that will not be shipped, or order level discounts that are no longer applicable due to the lower order value, after some products have been removed).
string
stateCode
(optional)State or province ISO code such as AZ for Arizona (if applicable), to use in taxes and duties calculation for this cart. This parameter is mandatory for countries that have states.
decimal
shippingPrice
International shipping price in the end customer’s currency, according to the shipping option selected by the customer.
RETURNS
UpdateOrderResponse
class
UpdateOrderProducts
The UpdateOrderProducts
API lets you update the order product's metadata and country of origin after the order has been created.
Method/URL
POST https://{server_name}/Order/UpdateOrderProducts
Parameter
Request
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Object | The order information and list of products that require updating |
Response
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Indicates the results of the API call. |
Error Codes
When providing an invalid or non-existent value, the Global-e returns an “ErrorInfo” with an appropriate error message.
Code | Error Message | Description |
---|---|---|
D001 |
| The provided order ID does not exist |
D002 |
| The provided cart item ID does not exist in this order |
D003 |
| The provided product code does not exist in this order |
D004 |
| The provided origin country code does not exist in the system |
D005 |
| The provided value for product meta-data is empty or null |
UpdateOrderStatus (Global-e to Merchant)
The method sends order status updates from the Global-e to the merchant’s site whenever a status is changed (for example, when the order fulfillment or shipping notifications are triggered).
Method/URL
POST https://www.merchant-site-domain.com/order-status-update-only-url
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
orderStatus | Object | Object OrderStatusDetails contains information about the status of the order on the merchant's site. | Yes |
Response
Name | Type | Description |
---|---|---|
ResponseInfo | Object Merchant.ResponInfo | Response details regarding API call. |
Examples
Request
{ "OrderId": "00010000100000000020", "StatusCode": "canceled", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd" }
UpdateOrderStatus (Merchant to Global-e)
The method sends order status updates from the merchant’s site to Global-e whenever a status is changed (for example, when the order fulfillment or shipping notifications are triggered).
Important
When the request is made by the merchant to cancel the order, the merchant must make sure to add the cancellation reason so that Global-e can notify the customer.
Method/URL
POST https://connect.globale.com/Order/UpdateOrderStatus
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| String | Unique identifier of the Merchant on Global-e. | Yes |
| Object | Object OrderStatusDetails contains information about the status of the order on the merchant's site. | Yes |
Response
Name | Type | Description |
---|---|---|
ResponseInfo | Object | Response details regarding API call. |
Examples
Request
{ "OrderId": "00010000100000000020", "StatusCode": "canceled", "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd" }
CreateAdditionalRequiredDocuments
Used to initiate the process of requesting additional required shipping document such as the German Customs EAD document. This API does not return the document itself, rather it initiates the process to receive the document from the authorities, for example the EAD document from German Customs, using SendAdditionalRequiredDocumentsToMerchant (Global-e to Merchant)
.
Security Requirements
Headers:
JWT (optional)
MerchantGUID (optional)
Method/URL
POST https://api-<merchantName>-<environmentName>.global-e.com/additional-required-documents
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| List of | Array of | Yes |
Response
Name | Type | Description |
---|---|---|
| Class | Indicates if an API call was successful or not and why. |
Error Codes
Code | Description |
---|---|
202 | Successful request - request was accepted, and document will be provided when ready. |
4xx | Error - the request not successful, incorrect data was sent by the merchant. Reasons for failure:
|
5xx | Error - the request not successful due to an internal error on Global-e side. |
Examples
Request
{ "Orders": [ { "OrderId": "GE123874638GB", "TrackingNumbers": [ "trackingnumber1", "trackingnumber2" ] } ] }
Response
Sample 1
Example of success, with HTTP Code 200:
{ "Success":true }
Sample 2
Example of error with HTTP Code 400:
{ "Code": "B001", "Message": "Order ID not found", "Description": "The Order GE12345US provided by the merchant does not exist." }
SendAdditionalRequiredDocumentsToMerchant (Global-e to Merchant)
Posts the required shipping documents of the order to the Merchant’s site.
This notification informs the Merchant that the documents previously listed in SendorderToMerchant
notification (under AdditionalRequiredDcouments), initiated by calling CreateAdditionalRequiredDcouments
, are ready.
The document's content is included in this notification.
Security:
IP whitelist
Secret GUID
Authorization header
Method/URL
POST https://www.merchant-site-domain.com/send-additional-required-documents-url
Parameters
Request
Parameter Name | Type | Description | Mandatory |
---|---|---|---|
| Object | Additional documents to send to merchant |
Examples
Request
{ "OrderId": "Sample order id", "MerchantOrderId": "Sample order id from the merchant’s system", "CountryCode": "US", "AdditionalRequiredDocuments": [ { "TrackingNumber" "98789723874839", "DocumentData": "base 64 string", "URL": "URL do download document", "DocumentTypeCode": "11", "DocumentTypeName": "EAD", "DocumentExtension": "pdf", "DocumentReference": "24DE85123822923B8", "CreationDateTime": "2024-01-30T10:55:21" } ] }
Response:
{ "StatusCode": "200", "Success": "true", "Message": "...", "ErrorCode": "...", "ErrorText": "..." }
UpdateOrderDispatch
Note
LEGACY: For reference only. These methods do not need to be implemented by merchants anymore.
Updates the order status and delivery quantities for the products, as well as merchant’s internal Delivery Reference Number, if applicable. Optionally, you can include the list of parcels for this order shipment to the Global-e hub.
URL
https://api_domain]/Order/UpdateOrderDispatch
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
OrderStatus | Object OrderStatusDetails | Status details to update for the order specified | |
parcelsList | List <Parcel> | List of Parcel objects for this order’s shipment to the Global‑e hub | |
productsList | List Product | List of Product objects (specified in the request body) |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
ResponseInfo | Object ResponseInfo | Response details for API call |
Examples
Response
[{ "ProductCode": "1020872", "Name": "Lanolin", "Description": "Breast%20Feeding%20Ointment", "GenericHSCode": "", "OriginCountryCode": "", "Weight": "1.0000", "Height": null, "Length": null, "Volume": "60", "ImageURL": "\/a\/3\/a3c9ef_ece3bec0467310603bce72e9a58e33d3.jpg", "ImageHeight": "", "ImageWidth": "", "ListPrice": "25.0000", "OriginalListPrice": "17.7000", "SalePrice": "15.0000", "OriginalSalePrice": "17.7000", "VATRateType": { "VATRateTypeCode": 1, "Name": "Low", "Rate": "18.0000" }, "Brand": { "BrandCode": "7", "Name": "Brand2" }, "Categories": [{ "CategoryCode": "3", "Name": "Maternity" } ], "DeliveryQuantity": 1 } ]
UpdateOrderDispatchV2
Updates the order status and Delivery Quantities for the products, as well as the Merchant’s internal Delivery Reference Number, if applicable. You can also add tracking information on each parcel or on the entire order. Optionally, you can include the list of Parcels with Products for this order shipment to the Global-e hub, exceptions to report on out-of-stock items, and items that will be shipped later on.
Method/URL
https://{server_name}/Order/UpdateOrderDispatchV2
Parameters
Request
Name | Type | Description | Mandatory |
---|---|---|---|
| Object UpdateOrderDispatchRequest | Full post data including Note: |
Response
Name | Type | Description | Mandatory |
---|---|---|---|
| Object ResponseInfo | Indicates if the API call was successfull. |
Examples
Request
{ "OrderId": "GE123874638GB", //Can accept either OrderID or MerchantOrderID "MerchantOrderID": "100018322", "DeliveryReferenceNumber": "123756483", "IsCompleted": false, "Parcels": [{ "ParcelCode": "123454321", "Products": [{ "DeliveryQuantity": 1, "CartItemId": "12365", "ProductCode": "121212" }, { "DeliveryQuantity": 2, "CartItemId": "12376", "ProductCode": "131313" } ], "TrackingDetails": { "TrackingNumber": "111111122666" } } ], "Exceptions": [{ "CartItemId": "12366", "ProductCode": "121213", "ExceptionType": 1 }, { "CartItemId": "12367", "SKU": "SKU121214", "ExceptionType": 2, "ExpectedFulfilmentDate": "2018-01-18" } ], "TrackingDetails": { "TrackingNumber": "111111122666" } }