CreateOrder
This section describes how to create a replacement order in Global‑e.
In this section:
API Call
API Endpoint: CreateOrder
POST request URL: https://[globale domain]/checkout/CreateOrder?merchantGUID=XXXXX
Assumptions
Replacement orders must include products that are recognized by Global‑e. Each product must be provided to Global‑e in advance.
By default, the replacement order is created with the same shipping service and shipping details as the original order, unless explicitly requested in the create order call.
The end customer is not charged additional costs associated with the shipper upgrade. This includes the shipping cost difference and fees such as remote area fees.
The destination country of the replacement order must be the same as the original order – the country cannot be changed.
The replacement order is automatically created as Delivered Duty Paid (DDP), if supported by the shipper.
The Merchant must validate the status of the original order. Global‑e does not implement order status validation.
For example, Global-e will not prevent the creation of a replacement order for orders that have not yet been delivered.
Billing details cannot be changed.
Added value replacement is not supported.
Global‑e does not save the relationship between the replaced products and replacement products.
Authentication method: Merchant GUID.
The
CreateOrderAPI must be implemented using the cart item ID.An
OrderReplacementCreatedemail is sent upon successful replacement creation.The reconciliation file will only reflect shipping and D&T charges for the replacement order. Replaced Products will not appear in the reconciliation report.
The
OrderPerformPaymentandSendOrderToMerchantAPI calls to the e-commerce platform can be controlled by a setting on the Global-E end.
CreateOrder Specification
The following classes are used by the API methods defined in this document.
CartUserDetails
string UserId (optional) Internal User identifier on the Merchant’s site.
List<AddressDetails> AddressDetails (optional)
All available addresses are taken from the registered customer address book or any other address provided for the replacement.
AddressDetails
string UserIdNumber (optional)
User’s personal ID document number
UserIdNumberType UserIdNumberType (optional)
User’s personal ID document type (e.g. Passport, ID card, etc.)
string FirstName (optional)
First name
string LastName (optional)
Last name
string FirstNameInLocalCulture (optional)
First name in local culture
string LastNameInLocalCulture (optional)
Last name in local culture
string MiddleName (optional)
Middle name
string Salutation (optional)
Salutation or title (e.g. Dr., Mr., etc.)
string Phone1 (optional)
Phone #1
string Phone2 (optional)
Phone #2
string Fax (optional)
Fax
string Email (optional)
E-mail address
string Company (optional)
Company name
string Address1 (optional)
Address line 1
string Address2 (optional)
Address line 2
string City (optional)
City name
string StateOrProvice (optional)
State or province name
string StateCode (optional)
State or province ISO code such as AZ for Arizona (if applicable)
string Zip (optional)
Zip or postal code
string CountryCode (optional)
2-char ISO country code.
Note: for the replacement order use always same country code as the original order.
bool IsShipping (optional)
Indicates that the current address can be used as a shipping address
bool IsBilling (optional)
Indicates that the current address can be used as a billing address
bool IsDefaultShipping (optional)
Indicates that the current address is the default shipping address
bool IsDefaultBilling (optional)
Indicates that the current address is the default billing address
string AddressBookId (optional)
ID of the current address from within the address book.
string AddressBookName (optional)
Name of the current address from within the address book.
SendCartData
(Partial structure dedicated for the replacement)
List<Product> Products
List of Product objects.
Int64 HubId (optional)
Identifier of the Global‑e Local Hub previously returned by ActiveHubDetails method.
If not SendOrderData specified, the same hub as the original order will be used.
CartUserDetails UserDetails
All available details of the user including all relevant addresses.
string UrlParameters (optional)
List of JSON-serialized KeyValuePairs that denote parameter values to be specified in the respective Merchant’s RESTFul API action URLs.
For example, to instruct Global‑e to include “en-AU” locale in the SendOrderToMerchant call for this cart, urlParameters should include the following KeyValuePair: [{"Key":"locale", "Value":"en-AU"}].
In this example “locale” parameter should be configured for the SendOrderToMerchant URL for this merchant on the Global‑e side
string WebStoreCode (optional)
Code used on the merchant’s side to identify the web store where the current cart is originating from. This code should be used in case of a multi-store setup on the merchant’s site.
string WebStoreInstanceCode (optional)
Code used on the merchant’s side to identify the web store instance where the current cart is originating from. This code should be used in case of multi-store domains set up on the merchant’s site.
string MerchantOrderId (optional)
A string that represents merchant order id if it’s known already at the point when the user is still in the cart page on the merchant’s store.
List<Discount> Discounts (optional)
List of Discounts to be applied to the cart. Discounts of any type (“cart”, “shipping”, etc.) may be specified.
Product
(Partial structure dedicated for the replacement)
string ProductCode
SKU code used to identify the product on the Merchant’s site (to be mapped on the Global‑e side)
string CartItemId
Identifier of the cart item on the Merchant’s site.
string ParentCartItemId (optional)
Identifier of the current item’s parent cart item on the Merchant’s site.
decimal SalePrice
Product sale price as displayed to the customer, after applying country coefficient, FX conversion, rounding rule (if applicable), and IncludeVAT handling.
bool IsFixedPrice (optional)
Setting this to TRUE indicates that the product’s price is fixed by the Merchant, in the default currency for the country.
In this case, all price modifications are disabled for this product.
Setting fixed prices is only allowed for the Countries where SupportsFixedPrices flag is set to TRUE.
Int64 OrderedQuantity
Ordered quantity for the product.
bool IsBundle (optional)
Setting this to TRUE indicates that the product represents a set of other products.
VATRateType VATRateType (optional)
The Product’s VAT rate type or class.
VATRateType LocalVATRateType (optional)
VAT rate type or class that would be applied to this product if the order was placed by the local customer.
This value must be specified if UseCountryVAT for the current Country is TRUE, and therefore VATRateType
ProductMetaData MetaData (optional)
Used to hold additional product data such as customer-defined product attributes.
ProductMetaData
List<CustomProductAttribute> Attributes (optional)
Customer-defined product attributes that allow the personalisation of the product if supported by the Merchant’s site (e.g. engraving).
CustomProductAttribute
string AttributeKey
Custom product attribute name that is used for product personalization by the end customer (e.g. engraving)
string AttributeValue
Custom product attribute value that is used for product personalization by the end customer (e.g. engraving).
ReplacedProduct
string CartItemId (optional)
The cart item id of the line item in the original order
string SKU (conditional)
SKU of the product if cart item id is not available
long Quantity
Quantity replaced
OrderReplacementData
string OriginalOrderId
The Id of the replaced order supports the global-e order id and merchant order ID.
List<ReplacedProduct> ReplacedProducts
List of replaced product identifiers and quantities.
OrderReplacementType
Optional field. The type of replacement:
1 - repair service
0 - regular replacement order (default)
SendOrderData
SendCartData CartData
Cart data is used to create the new order.
String ShippingMethodCode
The shipping method used to ship the replacement. If empty then the same service level as the original order will be selected.
OrderReplacementData OrderReplacement
Information about replaced order and product/s.
Discount
decimal DiscountValue Discount value as displayed to the customer, after applying country coefficient, FX conversion, and IncludeVAT handling.
string Name
Discount name
string Description (optional)
Discount textual description
string CouponCode (optional)
Merchant coupon code used for this discount (applicable to coupon-based discounts only)
string ProductCartItemId
Identifier of the product cart item related to this discount on the Merchant site.
string DiscountCode (optional)
Discount code used to identify the discount on the Merchant site.
string LoyaltyVoucherCode (optional)
Code used on the Merchant’s site to identify the Loyalty Voucher that this discount is based on.
Int64 DiscountType
One of the following possible values of DiscountTypeOptions enumeration denoting a type of discount:
DiscountType Option Value | Name | Description |
|---|---|---|
1 | Cart discount | Discount related to volume, amount, coupon, or another promotion value. |
2 | Shipping discount | Discount aimed to sponsor international shipping. |
3 | Loyalty points discount | Discount applied against the Merchant’s loyalty points to be spent for this purchase. |
4 | Duties discount | Discount aimed to sponsor taxes & duties pre-paid by the end customer in Global‑e checkout. |
5 | Checkout Loyalty Points Discount | Discount applied against the Merchant’s loyalty points in Global‑e checkout. |
6 | Payment Charge | Discount aimed to sponsor the “Cash on Delivery” fee. |
Int64 CalculationMode (optional)
One of the following possible values of CalculationModeOptions enumeration denoting the calculation mode of a discount to be implemented by GEM:
CalculationMode Option Value | Name | Description |
|---|---|---|
1 (default) | Percentage discount | The discount value specified in OriginalDiscountValue should be used for calculating the discount’s |
2 | Fixed in original currency | The discount value specified in OriginalDiscountValue denotes the fixed value in the Merchant’s currency. When calculating the discount’s |
3 | Fixed in customer currency | The discount value specified in |
CreateOrder Request (JSON)
{
"orderReplacement": {
"replacedProducts": [
{
"quantity": 1.0,
"cartItemId": "1"
}
],
"originalOrderId": "GE10097473894NL"
},
"cartData": {
"products": [
{
"productCode": "460011778068",
"isFixedPrice": true,
"orderedQuantity": 1.0,
"salePrice": "17.90",
"cartItemId": "",
"parentCartItemId": "1"
}
],
"userDetails": {
"addressDetails": [
{
"email": "talyuval5@gmail.com"
}
]
},
"discounts": [
{
"productCartItemId": "",
"discountType": 1,
"discountValue": 1.79
}
],
"shippingMethodCode": "",
"merchantOrderId": "Y73186844546755"
}
}CreateOrder Response (JSON)
{
"DateCreated": "1900-01-01T00:00:00Z",
"CurrencyName": "Euro",
"Parcels": [],
"AllowMailsFromMerchant": false,
"AllowDirectCommunicationFromMerchant": false,
"TnCConsent": null,
"ClearCart": true,
"UserId": null,
"CurrencyCode": "EUR",
"Products": [
{
"Attributes": null,
"Sku": "460011778068",
"Price": 14.4400,
"PriceBeforeRoundingRate": 14.4400,
"PriceBeforeGlobalEDiscount": 14.4400,
"Quantity": 1,
"VATRate": 0.000000,
"CustomerVATRate": 24.000000,
"InternationalPrice": 17.9000,
"InternationalDiscountedPriceInMerchantCurrency": 16.11,
"CartItemId": "1",
"ParentCartItemId": "1",
"CartItemOptionId": null,
"HandlingCode": "",
"GiftMessage": "",
"RoundingRate": 0.8067039106145251396648044693,
"IsBackOrdered": false,
"BackOrderDate": null,
"DiscountedPrice": 11.70,
"InternationalDiscountedPrice": 16.1100,
"ProductCodeSecondary": null,
"Brand": null,
"Categories": null,
"ListPrice": 0.00,
"InternationalListPrice": 0.00,
"GenericHSCode": "950300",
"DiscountedPriceForCustoms": 13.00,
"InternationalDiscountedPriceForCustoms": 16.11,
"DTBreakdown": {
"Duties": 0.00,
"SalesTaxes": 0.00,
"Subsidy": 0.0
},
"InternationalDTBreakdown": {
"Duties": 0.00,
"SalesTaxes": 0.00,
"Subsidy": 0.0
},
"IsGiftCard": false,
"IsFixedPrice": true,
"EstimatedDeliveryDate": null,
"IsParentBundleProductMoved": true
}
],
"Customer": {
"EmailAddress": null,
"IsEndCustomerPrimary": true,
"SendConfirmation": false
},
"PrimaryShipping": {
"FirstName": "ES6d%2baTo9sqWUbTiaoRV6Q%3d%3d",
"LastName": "jKuexmRWYR%2fbqDrzOFv1iQ%3d%3d",
"FirstNameInLocalCulture": "",
"LastNameInLocalCulture": "",
"MiddleName": null,
"Salutation": null,
"Company": "",
"Address1": "t3ODmjz9nc25%2bLHjNAtvDgl6EE6TZYuoWRqsTk47pDQ%3d",
"Address2": "",
"City": "4gVF9VRnP9QVeeiDwDSEJw%3d%3d",
"CityRegion": "",
"StateCode": null,
"StateOrProvince": null,
"Zip": "ugWciWrRFjU7jR11pEf4jg%3d%3d",
"Email": "fci85oZUXWy2WFFvJO5MQv15Y4EtZjHw1O7yIF4qEA4%3d",
"Phone1": "CfjORCMc0mNKrwQ4MYcYKQ%3d%3d",
"Phone2": "",
"Fax": "",
"CountryCode": "GR",
"CountryCode3": "GRC",
"CountryName": "Greece",
"AddressBookId": "",
"AddressBookName": "",
"SaveAddress": false,
"VATRegistrationNumber": null,
"CustomerTaxId": null,
"CollectionPointId": null
},
"SecondaryShipping": {
"FirstName": "GlobalE",
"LastName": "CEVA Logistics",
"FirstNameInLocalCulture": null,
"LastNameInLocalCulture": null,
"MiddleName": null,
"Salutation": null,
"Company": "",
"Address1": "Boekerman 5",
"Address2": null,
"City": "Roosendaal (Oud Gastel)",
"CityRegion": null,
"StateCode": "NN",
"StateOrProvince": "undefined",
"Zip": "4751XK",
"Email": null,
"Phone1": "000000000",
"Phone2": null,
"Fax": null,
"CountryCode": "NL",
"CountryCode3": "NLD",
"CountryName": "Netherlands",
"AddressBookId": null,
"AddressBookName": null,
"SaveAddress": false,
"VATRegistrationNumber": null,
"CustomerTaxId": null,
"CollectionPointId": null
},
"ShippingMethodCode": "globaleintegration_standard",
"Discounts": [
{
"Name": "Replacement order-Duties",
"Description": "Discount thant generated by global-e to discount the duties in case of replacement order",
"Price": 0.0000,
"DiscountType": 4,
"VATRate": 0.000000,
"LocalVATRate": 21.000000,
"CouponCode": null,
"InternationalPrice": 0.0000,
"DiscountCode": "",
"ProductCartItemId": null,
"LoyaltyVoucherCode": null
},
{
"Name": "",
"Description": "",
"Price": 2.7400,
"DiscountType": 1,
"VATRate": 24.000000,
"LocalVATRate": 0.000000,
"CouponCode": null,
"InternationalPrice": 1.7900,
"DiscountCode": "",
"ProductCartItemId": null,
"LoyaltyVoucherCode": null
}
],
"Markups": [
{
"Name": "Replacement order-Shipping discount",
"Description": "Discount thant generated by global-e to discount the shipping cost in case of replacement order",
"Price": 19.9000,
"DiscountType": 2,
"VATRate": 0.000000,
"LocalVATRate": 21.000000,
"CouponCode": null,
"InternationalPrice": 19.9000,
"DiscountCode": "",
"ProductCartItemId": null,
"LoyaltyVoucherCode": null
}
],
"LoyaltyPointsSpent": 0.0,
"LoyaltyPointsEarned": 0.0,
"SameDayDispatch": false,
"SameDayDispatchCost": 0.0,
"DoNotChargeVAT": false,
"CustomerComments": "",
"IsFreeShipping": true,
"FreeShippingCouponCode": "",
"ShipToStoreCode": null,
"RoundingRate": 0.8067039106145251396648044693,
"UrlParameters": null,
"OriginalMerchantTotalProductsDiscountedPrice": 0.0000,
"LoyaltyCode": null,
"OTVoucherCode": null,
"OTVoucherAmount": null,
"OTVoucherCurrencyCode": null,
"IsSplitOrder": false,
"PrePayOffered": false,
"InitialCheckoutCultureCode": "en-GB",
"CultureCode": "en-GB",
"HubId": 1001034,
"HubCode": null,
"IsReplacementOrder": true,
"OriginalOrder": {
"OrderId": "GE10097473894NL",
"MerchantOrderId": "EUQA1116048",
"MerchantInternalOrderId": "EUQA1116048"
},
"ReservationRequestId": null,
"IsSuppressPersonalInformation": false,
"TotalDutiesAndTaxesPrice": 0.00,
"USSalesTax": 0.0,
"CCFPrice": 0.0,
"CustomerDTBreakdown": {
"Duties": 0.000000000,
"SalesTaxes": 0.000000000,
"Other": 0.000000000
},
"MerchantDTBreakdown": {
"Duties": 0.000000000,
"SalesTaxes": 0.000000000,
"Other": 0.000000000,
"Subsidy": 0.0
},
"ExporterDetails": {
"VATRegistrationNumber": "NL859146492B01",
"EORINumber": "NL859146492",
"IOSSNumber": null
},
"ImporterDetails": {
"Company": "",
"VATRegistrationNumber": "",
"CustomerTaxId": null,
"ImporterType": 0,
"Address": {
"Name": "ES6d+aTo9sqWUbTiaoRV6Q==jKuexmRWYR/bqDrzOFv1iQ==",
"Address1": "t3ODmjz9nc25+LHjNAtvDgl6EE6TZYuoWRqsTk47pDQ=",
"Address2": null,
"City": "4gVF9VRnP9QVeeiDwDSEJw==",
"StateCode": "NN",
"StateOrProvince": "undefined",
"Zip": "ugWciWrRFjU7jR11pEf4jg==",
"CountryCode": "GR",
"Country": "Greece"
}
},
"OrderPaymentMethods": [],
"OrderDocuments": [
{
"URL": "https://connect2.bglobale.com/Document/VATInvoice?documentParam=iI9FwInOzaNSAGbwFqpq9foxt%2f7OckWHnJnlegRFId7ccSF3hvqwR%2f2yjQeB%2bI%2fgqy6jYmUKwhUAIHHBB6%2beQYbw0iTmHatSDPpl0nglor8jR6bSG0gsVCRIiIeH0fA6t0INS0gr8EzlEhZT3uPi4I1a9isRex4W5CexHbZrV8EDxm2Ae6w%2fajMBbDQZd%2fmlA8YohMx7nwvL8UEnZFLSPA%3d%3d",
"DocumentTypeCode": "5",
"DocumentTypeName": "VATInvoice",
"DocumentExtension": "pdf",
"ErrorMessage": null
}
],
"ShippingVATRate": 0.0,
"TotalDutiesPaidByCustomerPrice": 0.00,
"OrderCreationSource": 0,
"IsB2B": false,
"CookieConsent": 0,
"BillingCustomFields": null,
"ShippingCustomFields": null,
"IsTaxExemption": false,
"OrderCreationSourceInfo": null,
"Subs": [],
"PaymentDetails": null,
"PrimaryBilling": {
"FirstName": null,
"LastName": null,
"FirstNameInLocalCulture": null,
"LastNameInLocalCulture": null,
"MiddleName": null,
"Salutation": null,
"Company": null,
"Address1": null,
"Address2": null,
"City": null,
"CityRegion": null,
"StateCode": null,
"StateOrProvince": null,
"Zip": null,
"Email": null,
"Phone1": null,
"Phone2": null,
"Fax": null,
"CountryCode": null,
"CountryCode3": null,
"CountryName": null,
"AddressBookId": null,
"AddressBookName": null,
"SaveAddress": false,
"VATRegistrationNumber": null,
"CustomerTaxId": null,
"CollectionPointId": null
},
"SecondaryBilling": {
"FirstName": null,
"LastName": null,
"FirstNameInLocalCulture": null,
"LastNameInLocalCulture": null,
"MiddleName": null,
"Salutation": null,
"Company": null,
"Address1": null,
"Address2": null,
"City": null,
"CityRegion": null,
"StateCode": null,
"StateOrProvince": null,
"Zip": null,
"Email": null,
"Phone1": null,
"Phone2": null,
"Fax": null,
"CountryCode": null,
"CountryCode3": null,
"CountryName": null,
"AddressBookId": null,
"AddressBookName": null,
"SaveAddress": false,
"VATRegistrationNumber": null,
"CustomerTaxId": null,
"CollectionPointId": null
},
"CashOnDeliveryFee": 0.0,
"OrderId": "GE10098224286NL",
"StatusCode": "N/A",
"OrderStatusReason": null,
"MerchantGUID": "5c8df18d-2e60-4fa0-988f-4cab0f309f2d",
"CartId": null,
"MerchantOrderId": "Y73186844546755",
"MerchantInternalOrderId": null,
"PriceCoefficientRate": 1.000000,
"CartHash": null,
"WebStoreCode": null,
"WebStoreInstanceCode": "GlobalEDefaultStoreInstance",
"DiscountedShippingPrice": 0.0,
"InternationalDetails": {
"CurrencyCode": "EUR",
"TotalPrice": 16.11,
"TransactionCurrencyCode": "EUR",
"TransactionTotalPrice": 0.0,
"TotalShippingPrice": -19.90,
"SameDayDispatchCost": 0.0,
"TotalCCFPrice": 0.0,
"TotalDutiesPrice": 0.000000000,
"USSalesTax": 0.0,
"ShippingMethodCode": "GLOBALE",
"ShippingMethodName": "DHL api Express Worldwide",
"PaymentMethodCode": "39",
"PaymentMethodName": "CouponPayment",
"CardNumberLastFourDigits": null,
"ExpirationDate": null,
"DutiesGuaranteed": false,
"OrderTrackingNumber": null,
"OrderTrackingUrl": "https%3a%2f%2fwww2.bglobale.com%2fOrder%2fTrack%2fmZPd%3fOrderId%3dGE10098224286NL%26ShippingEmail%3dfci85oZUXWy2WFFvJO5MQv15Y4EtZjHw1O7yIF4qEA4%3d",
"OrderWaybillNumber": null,
"ShippingMethodTypeCode": "Standard",
"ShippingMethodTypeName": "Standard Courier",
"DeliveryDaysFrom": 1,
"DeliveryDaysTo": 2,
"DeliveryDateFrom": "24.02",
"DeliveryDateTo": "24.02",
"ConsignmentFee": 0.0000,
"SizeOverchargeValue": 0.0000,
"RemoteAreaSurcharge": 0.0000,
"DiscountedShippingPrice": 0.0000,
"CashOnDeliveryFee": 0.0,
"ParcelsTracking": [],
"TotalVATAmount": 3.12,
"CustomerDTBreakdown": {
"Duties": 0.000000000,
"SalesTaxes": 0.000000000,
"Other": 0.000000000
},
"MerchantDTBreakdown": {
"Duties": 0.000000000,
"SalesTaxes": 0.000000000,
"Other": 0.000000000,
"Subsidy": 0.0
},
"ShippingVATRate": 24.000000,
"ShippingMethodStatusCode": "Undefined",
"ShippingMethodStatusName": "undefined",
"ShipmentStatusUpdateTime": null,
"ShipmentLocation": null
},
"GiftCards": null,
"DeclarativeShippingPriceInCustomerCurrency": null,
"TotalValueForCustoms": null,
"TaxCalculationRule": null,
"PaymentTransactionResponseDataExtended": null}