CreateOrder
Overview
This section describes how to create a replacement order in Global‑e.
CreateOrder (Merchant to Global-e)
The CreateOrder API is used to create a replacement order in Global‑e.
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. Please explain
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.
Method/URL
POST https://[globale_api_domain]/checkout/CreateOrder
CreateOrder Specification
The following classes are used by the API methods defined in this document.
CartUserDetails
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| List<AddressDetails> | All available addresses are taken from the registered customer address book or any other address provided for the replacement. | No |
| String | Internal User identifier on the Merchant’s site | No |
SendCartData
(Partial structure with relevant attributes)
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| List<Discount> | List of Discounts to be applied to the cart. Discounts of any type (“cart”, “shipping”, etc.) may be specified. | N |
| String | The 2-character ISO country code representing the country to which this hub belongs. | |
| Decimal | Identifier of the Global‑e’s Local Hub previously returned by the | |
| String | Unique identifier of Merchant order ID. | N |
| String | The amended Merchant's price for duties. Can be used to declare a value for a free item for customs purposes. Note: Either Used by SendCartV2 API. | |
| String | Name of the Product. Min length: 1 char. No length limit. | Y |
| String | The original Merchant's price for duties. Can be used to declare a value for a free item for customs purposes. Note: Either Used by SendCartV2 API. | |
| List<Product> | List of Product objects. | |
| String | List of JSON-serialized For example, to instruct Global‑e to include the “ | |
| Class CartUserDetails | All available details of the user including all relevant addresses. | |
| String | 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. | N |
| String | 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. | N |
CustomProductAttribute
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| String | Custom product attribute name that is used for product personalization by the end customer (e.g. engraving) | |
| String | Custom product attribute value that is used for product personalization by the end customer (e.g. engraving). |
ReplacedProduct
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| String | Cart item ID | No |
| Decimal | Item quantity | |
| String | SKU of the product if cart item id is not available | Conditional |
ProductMetaData
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| List<CustomProductAttribute> | Customer-defined product attributes that allow the personalisation of the product if supported by the merchant’s site (e.g. engraving) | No |
OrderReplacementData
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| Number | The type of replacement:
| No |
| String | The original Order Id | |
| List< ReplacedProduct> | A list of replaced products |
SendOrderData
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| Class SendCartData | Provides the cart data that is used to create the new order. | |
| Class OrderReplacementData | Information about replaced order and product. | |
| String | The shipping method used to ship the replacement. If empty then the same service level as the original order will be selected |
Discount
Parameter Name | Type | Description | Mandatory |
|---|---|---|---|
| String | Merchant Coupon Code used for this discount (applicable to coupon-based discounts only) | No |
| String | Discount textual description | No |
| String | Discount code used to identify the discount on the Merchant’s site. This property may be optionally specified in the | No |
| Decimal | One of the following possible enum values of | |
| Decimal | Discount value as displayed to the customer, after applying country coefficient, FX conversion and | |
| String | Code used on the Merchant’s site to identify the Loyalty Voucher that this discount is based on | No |
| String | Discount name | |
| String | Identifier of the product cart item related to this discount on the Merchant’s site. This property may be optionally specified in the | No |
Discount Type Options
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. |
Calculation Mode Options
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": "[email protected]"
}
]
},
"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}