CreateOrder
This section describes how to create a replacement order in Global‑e.
In this section:
CreateOrder API Call
POST https://[globale_api_domain]/checkout/CreateOrder
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
CreateOrder
API must be implemented using the cart item ID.An
OrderReplacementCreated
email 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
OrderPerformPayment
andSendOrderToMerchant
API 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
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| List<AddressDetails> | All available addresses are taken from the registered customer address book or any other address provided for the replacement. | N |
| String | Internal User identifier on the Merchant’s site | N |
AddressDetails
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| String | Address line 1. | N |
| String | Address line 2. | N |
| String | Id of the current address from within the address book | N |
| String | Name of the current address from within the address book | N |
| String | City name. | N |
| String | Company name | N |
| String | 2-char ISO country code. Note: for the replacement order use always same country code as the original order. | N |
| String | E-mail address | N |
| String | Fax | N |
| String | First name | N |
| String | First name in local culture | N |
| Bool | Indicates that the current address can be used as a billing address | N |
| Bool | Indicates that the current address is the default billing address | N |
| Bool | Indicates that the current address is the default shipping address | N |
| Bool | Indicates that the current address can be used as a shipping address | N |
| String | Last name | N |
| String | Last name in local culture | N |
| String | Middle name | N |
| String | Phone #1 | N |
| String | Phone #2 | N |
| String | Salutation or title (e.g. Dr., Mr., etc.). | N |
| String | State or province ISO code such as AZ for Arizona (if applicable) | N |
| String | State or province name | N |
| String | User’s personal ID document number | N |
| Class UserIdNumberType | User’s personal ID document type (e.g. Passport, ID card, etc.) | N |
| String | Zip or postal code | N |
SendCartData
(Partial structure with relevant attributes)
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| 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 |
Product
(Partial structure with relevant attributes)
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| String | Identifier of the cart item on the Merchant’s site. This property may be optionally specified in the | N |
| Bool | Indicates if the product represents a set of products. TRUE - The product represents a set of other products. If a bundled product has non-zero prices specified (i.e. FALSE - The product does not represent a set of other products. | N |
| Bool | Indicates if the product’s price is fixed by the Merchant, in the default currency for the country. TRUE - The product’s price is fixed. In this case, all price modifications are disabled for this product. Setting fixed prices is only allowed for the Countries where the FALSE - The product's price is not fixed. | N |
| Class VATRateType | 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 | N |
| Class ProductMetaData | Used to hold additional product data such as customer-defined product attributes. | N |
| Decimal | Ordered quantity for the product (to be used in Checkout / Order methods described below, as needed) | N |
| String | Identifier of the current item’s parent cart item on the Merchant’s site. This value must be specified if the current cart item is related to a parent item ( | N |
| String | SKU code used to identify the product on the Merchant’s site (to be mapped on the Global‑e side) | |
| Class VATRateType | Product’s VAT rate type or class | N |
ProductMetaData
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| List<CustomProductAttribute> | Customer-defined product attributes that allow the personalisation of the product if supported by the merchant’s site (e.g. engraving) | N |
CustomProductAttribute
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| 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 (Y/N) |
---|---|---|---|
| String | Cart item ID | N |
| Decimal | Item quantity | |
| String | SKU of the product if cart item id is not available | Conditional |
OrderReplacementData
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| Number | The type of replacement:
| N |
| String | The original Order Id | |
| List< ReplacedProduct> | A list of replaced products |
SendOrderData
Parameter Name | Type | Description | Mandatory (Y/N) |
---|---|---|---|
| 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 (Y/N) |
---|---|---|---|
| String | Merchant Coupon Code used for this discount (applicable to coupon-based discounts only) | N |
| String | Discount textual description | N |
| String | Discount code used to identify the discount on the Merchant’s site. This property may be optionally specified in the | N |
| 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 | N |
| 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 | N |
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}