Skip to main content

Documentation Portal

Merchant REST API

ClientApplyLoyaltyVouchers

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.

ClientApplyLoyaltyVouchers (Merchant.CartAction cartAction)

Validates Loyalty Vouchers and applies them to the current user’s cart if all the vouchers in the list are valid and applicable.

If at least one Loyalty Voucher in the list is invalid, Merchant.ResponseInfo.Success is set to FALSE.

If all Loyalty Vouchers are valid, the Merchant’s server should re-calculate the cart pricing and execute before returning a response, the SendCart API call with the CartToken argument value returned from the previous call to SendCart for the current user.

Use this method to validate the Loyalty Vouchers selected by the user from the list that has been provided in the loyaltyVouchersList argument of the SendCart API call for the current user’s checkout page. This method can only be executed from within the context of the current user’s client session.

SAMPLE

Body:

{"LoyaltyVouchers":["123456","123467"]}

URL:

https://www.merchant-site-domain.com/client-apply-loyalty-vouchers-url

ACCEPTS

Merchant.CartAction cartAction

RETURNS

Merchant.ResponseInfo class

GetCheckoutCartInfo

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.

The GetCheckoutCartInfo API returns all cart contents, including customer information for logged-in customers.

This method is called from:

  • A Global‑e server with the cart token rendered in a cookie or in HTML DOM

  • The client session to calculate price totals.

Note

This API only returns products that are in stock. If stock validation for products in the basket requires special handling on the Merchant side (for example, calls to an external system), Global-e can specify an additional URL argument for this method, to indicate the cases when stock validation is specifically required.

Note

If the cart data is unavailable, the checkout will not open and an error message will appear in the browser development console. Please make every effort to minimize this occurrence.

USAGE

  • Totals on the basket page

  • Open checkout

  • Validate order (SendOrderToMerchant)

SECURITY

  • Client-side: Session and cart token

  • Server-side: Cart token IP whitelist Secret GUID Authorization header

REQUEST (SAMPLE URL)

  • Client-side: GET

  • Server-side: GET/ POST (default GET)

https://www.merchant-site-domain.com/get-checkout-cart-info-url

ACCEPTS 

Request Parameters

Name

Type

Description

Mandatory

countryCode

String

2-char ISO code of the shipping country

No

currencyCode

String

3-char currency code of the shipping country

No

merchantCartToken

String

This is the identifier used for the cart on the Merchant’s site

RESPONSE

Name

Type

Description

CheckoutCartInfo

Class CheckoutCartInfo

Retrieves cart information.

SAMPLE RESPONSE BODY

Response Example

{
    "productsList": [{
            "ProductCode": "9632261340000",
            "ProductGroupCode": "9632261_c340000",
            "CartItemId": "6601",
            "ParentCartItemId": "",
            "CartItemOptionId": "",
            "Name": "name of product",
            "Description": "product description",
            "Keywords": "product keywords",
            "URL ": "product page url",
            "GenericHSCode ": "",
            "OriginCountryCode": "CHN",
            "Weight": 0.0,
            "Height": 0,
            "Width": 0,
            "Length": 0,
            "Volume": 0,
            "ImageURL": "",
            "ImageHeight": 533,
            "ImageWidth": 414,
            "IsFixedPrice": "true",
            "ListPrice": null,
            "OriginalListPrice": 20.0000,
            "SalePrice": 0.0,
            "SalePriceBeforeRounding": 0.0,
            "OriginalSalePrice": 20.0000,
            "OrderedQuantity": 2,
            "DeliveryQuantity": 2,
            "IsBlockedForGlobalE": false,
            "VATRateType": "",
            "LocalVATRateType": "",
            "Brand": {
                "BrandCode": "7",
                "Name": "Brand2"
            },
            "Categories": null,
            "Attributes": [{
                    "AttributeCode": "26",
                    "Name": "26",
                    "AttributeTypeCode": "size"
                }, {
                    "AttributeCode": "Geranium Red/Cut Out",
                    "Name": "Geranium Red/Cut Out",
                    "AttributeTypeCode": "color"
                }
            ],
        }
    ],
    "shippingDetails": {
        "UserId": "",
        "UserIdNumber": "",
        "UserIdNumberType": {
            "UserIdNumberTypeCode": null,
            "Name": "Shipping"
        },
        "FirstName": "",
        "LastName": "",
        "MiddleName": "",
        "Salutation": "",
        "Phone1": "",
        "Phone2": "",
        "Fax": "",
        "Email": "",
        "Address1": "",
        "Address2": "",
        "City": "",
        "StateOrProvince": "",
        "StateCode": "",
        "Zip": "",
        "CountryCode": "",
        "CountryName": ""
    },
    "billingDetails": {
        "UserId": "",
        "UserIdNumber": "",
        "UserIdNumberType": {
            "UserIdNumberTypeCode": null,
            "Name": "Billing"
        },
        "FirstName": "",
        "LastName": "",
        "MiddleName": "",
        "Salutation": "",
        "Phone1": "",
        "Phone2": "",
        "Fax": "",
        "Email": "",
        "Address1": "",
        "Address2": "",
        "City": "",
        "StateOrProvince": "",
        "StateCode": "",
        "Zip": "",
        "CountryCode": "",
        "CountryName": ""
    },
    "discountsList": [{
            "OriginalDiscountValue": 10.0000,
            "DiscountType": "percentage",
            "Name": "discount name",
            "Description": "",
            "DiscountCode": null,
            "ProductCartItemId": 6601,
            "CouponCode": null
        }
    ]
}
Sample Response: Dynamic Prices
{
    "productsList": [{
            "CartItemId": "676106",
            "ProductCode": "676106",
            "ProductGroupCode": "CS16577",
            "Name": "+Warmers",
            "Description": "Product List Description",
            "IsFixedPrice": false,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https://www.mystore.co.uk/product/[myproduct]",
            "Volume": 0.12,
            "Weight": 0.08,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 0
            },
            "OriginalSalePrice": 29.17,
            "Categories": [{
                    "CategoryCode": 161,
                    "Name": "Cycle Clothing > Armwarmers"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 2,
                    "Name": "Black"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 869,
                    "Name": "M"
                }
            ],
            "OriginalListPrice": 35,
            "ImageURL": "https://www.mystore.co.uk/product-media/[myproductimpage.jpg]",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 38,
                "Name": "Castelli"
            },
            "SalePrice": 0,
            "ListPrice": 0,
            "ProductClassCode": "expensive_warmers"
        }, {
            "CartItemId": "678197",
            "ProductCode": "678197",
            "ProductGroupCode": "7MESH-1507",
            "Name": "Resistance Jacket",
            "Description": "With its ...... short or long sleeve.",
            "IsFixedPrice": false,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https:\/\/www.mysite.co.uk\/item\/7Mesh\/Jacket\/EAM",
            "Volume": 1,
            "Weight": 0.115,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 20
            },
            "OriginalSalePrice": 150,
            "Categories": [{
                    "CategoryCode": 151,
                    "Name": "Cycle Clothing > Jacket Wind"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 3,
                    "Name": "Blue"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 367,
                    "Name": "M"
                }
            ],
            "OriginalListPrice": 180,
            "ImageURL": "https:\/\/dbyvw4efi.cloudfront.net\Jacket-blue.jpg",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 705,
                "Name": "7Mesh"
            },
            "SalePrice": 0,
            "ListPrice": 0
        }
    ],
    "discountsList": [{
            "OriginalDiscountValue": 3.398,
            "DiscountType": null,
            "Name": "GLOBALE20",
            "Description": null,
            "DiscountCode": "GLOBALE20",
            "ProductCartItemId": null,
            "CouponCode": "GLOBALE20",
            "CalculationMode": 1,
            "DiscountValue": 0
        }
    ],
    "billingDetails": {
        "UserId": "1144404",
        "Email": "[email protected]",
        "Salutation": "",
        "FirstName": "john",
        "LastName": "doe",
        "Address1": "basel 25",
        "Address2": "",
        "City": "petah tikva",
        "StateOrProvince": "",
        "Zip": "11223344",
        "CountryCode": "ISR",
        "CountryName": "Israel",
        "Phone1": "0000000000",
        "Phone2": ""
    },
    "shippingDetails": {
        "UserId": "1144404",
        "Email": "[email protected]",
        "Salutation": "",
        "FirstName": "john",
        "LastName": "winer",
        "Address1": "basel 25",
        "Address2": "",
        "City": "petah tikva",
        "StateOrProvince": "",
        "Zip": "11223344",
        "CountryCode": "ISR",
        "CountryName": "Israel",
        "Phone1": "0000000000",
        "Phone2": ""
    }
}
Sample Response: Fixed Prices
{
    "productsList": [{
            "CartItemId": "676106",
            "ProductCode": "676106",
            "ProductGroupCode": "CS16577",
            "Name": "N+ Warmers",
            "Description": "The Warmers .... and water resistance.",
            "IsFixedPrice": true,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https:\/\/www.mysite.co.uk\/Warmers\/HOG",
            "Volume": 0.12,
            "Weight": 0.08,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 20
            },
            "OriginalSalePrice": 0,
            "VATRateType": {
                "VATRateTypeCode": "vat10.5",
                "Rate": 10.5
            },
            "Categories": [{
                    "CategoryCode": 161,
                    "Name": "Cycle Clothing > Warmers"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 2,
                    "Name": "Black"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 869,
                    "Name": "M"
                }
            ],
            "OriginalListPrice": 0,
            "ImageURL": "https:\/\/offpi.cloudfront.net\/Warmer.jpg",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 38,
                "Name": "BandNamei"
            },
            "SalePrice": 120,
            "ListPrice": 120,
            "ProductClassCode": "expensive_warmers"
        }, {
            "CartItemId": "678197",
            "ProductCode": "678197",
            "ProductGroupCode": "7MESH-1507",
            "Name": "Resistance Jacket",
            "Description": "With its .... your short or long sleeves.",
            "IsFixedPrice": true,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https:\/\/www.mysite.co.uk\/Jacket\/JAM",
            "Volume": 1,
            "Weight": 0.115,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 20
            },
            "OriginalSalePrice": 0,
            "Categories": [{
                    "CategoryCode": 151,
                    "Name": "Cycle Clothing > Jacket Wind"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 3,
                    "Name": "Blue"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 367,
                    "Name": "M"
                }
            ],
            "OriginalListPrice": 0,
            "ImageURL": "https:\/\/offpi.cloudfront.net\/Jacket-blue.jpg",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 705,
                "Name": "Mesh"
            },
            "SalePrice": 180,
            "ListPrice": 150
        }
    ],
    "discountsList": [{
            "OriginalDiscountValue": 0,
            "DiscountType": null,
            "Name": "GLOBALE20",
            "Description": null,
            "DiscountCode": "GLOBALE20",
            "ProductCartItemId": null,
            "CouponCode": "GLOBALE20",
            "CalculationMode": 3,
            "DiscountValue": 50
        }
    ],
    "billingDetails": {
        "UserId": "1144404",
        "Email": "[email protected]",
        "Salutation": "",
        "FirstName": "john",
        "LastName": "doe",
        "Address1": "basel 25",
        "Address2": "",
        "City": "petah tikva",
        "StateOrProvince": "",
        "Zip": "11223344",
        "CountryCode": "ISR",
        "CountryName": "Israel",
        "Phone1": "0000000000",
        "Phone2": ""
    },
    "shippingDetails": {
        "UserId": "1144404",
        "Email": "[email protected]",
        "Salutation": "",
        "FirstName": "john",
        "LastName": "doe",
        "Address1": "basel 25",
        "Address2": "",
        "City": "petah tikva",
        "StateOrProvince": "",
        "Zip": "11223344",
        "CountryCode": "ISR",
        "CountryName": "Israel",
        "Phone1": "0000000000",
        "Phone2": ""
    }
}
Sample Response: Multi Addresses
{
    "productsList": [{
            "CartItemId": "676106",
            "ProductCode": "676106",
            "ProductGroupCode": "CS16577",
            "Name": "N+ Warmers",
            "Description": "The <a href=\"https:\/\/www.mysite.co.uk\/brand\/... and water resistance.",
            "IsFixedPrice": true,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https:\/\/www.mysite.co.uk\/item\/Warmers\/HOG",
            "Volume": 0.12,
            "Weight": 0.08,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 21
            },
            "OriginalSalePrice": 0,
            "Categories": [{
                    "CategoryCode": 161,
                    "Name": "Cycle Clothing > Warmers"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 2,
                    "Name": "Black"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 869,
                    "Name": "M"
                }
            ],
            "MetaData": {
                "Attributes": [{
                        "AttributeKey": "Name",
                        "AttributeValue": "Alex"
                    }
                ]
            },
            "OriginalListPrice": 0,
            "ImageURL": "https:\/\/offpi.cloudfront.net\/Warmer.jpg",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 38,
                "Name": "BrandName"
            },
            "SalePrice": 50,
            "ListPrice": 123,
            "ProductClassCode": "expensive_warmers"
        }, {
            "CartItemId": "678197",
            "ProductCode": "678197",
            "ProductGroupCode": "7MESH-1507",
            "Name": "Resistance Jacket",
            "Description": "With its ... your short or long sleeve.",
            "IsFixedPrice": false,
            "IsBlockedForGlobalE": false,
            "OrderedQuantity": 1,
            "URL": "https:\/\/www.mysite.co.uk\/Jacket\/JAM",
            "Volume": 1,
            "Weight": 0.115,
            "LocalVATRateType": {
                "VATRateTypeCode": "NORMAL",
                "Rate": 20
            },
            "OriginalSalePrice": 150,
            "Categories": [{
                    "CategoryCode": 151,
                    "Name": "Cycle Clothing > Jacket"
                }, {
                    "CategoryCode": "WORLDWIDE",
                    "Name": "WORLDWIDE"
                }
            ],
            "Attributes": [{
                    "AttributeTypeCode": "colour_or_flavour",
                    "AttributeCode": 3,
                    "Name": "Blue"
                }, {
                    "AttributeTypeCode": "size",
                    "AttributeCode": 367,
                    "Name": "M"
                }
            ],
            "OriginalListPrice": 180,
            "ImageURL": "https:\/\/offpi.cloudfront.net\/Jacket-blue.jpg",
            "ImageHeight": 145,
            "ImageWidth": 145,
            "Brand": {
                "BrandCode": 705,
                "Name": "Mesh"
            },
            "SalePrice": 0,
            "ListPrice": 0
        }
    ],
    "discountsList": [{
            "OriginalDiscountValue": 0,
            "DiscountType": null,
            "Name": "GLOBALE20",
            "Description": null,
            "DiscountCode": "GLOBALE20",
            "ProductCartItemId": "676106",
            "CouponCode": "GLOBALE20",
            "CalculationMode": 3,
            "DiscountValue": 3.398
        }
    ],
    "userDetails": {
        "UserId": "1144404",
        "AddressDetails": [{
                "Email": "[email protected]",
                "Salutation": "",
                "FirstName": "john",
                "LastName": "doe",
                "Address1": "basel 25",
                "Address2": "",
                "City": "petah tikva",
                "StateOrProvince": "",
                "Zip": "11223344",
                "CountryCode": "IL",
                "CountryName": "Israel",
                "Phone1": "0000000000",
                "Phone2": "",
                "IsShipping": true,
                "IsBilling": false,
                "IsDefaultShipping": true,
                "IsDefaultBilling": false,
                "AddressBookId": 111
            }, {
                "Email": "[email protected]",
                "Salutation": "",
                "FirstName": "john",
                "LastName": "doe",
                "Address1": "basel 25",
                "Address2": "",
                "City": "petah tikva",
                "StateOrProvince": "",
                "Zip": "11223344",
                "CountryCode": "IL",
                "CountryName": "Israel",
                "Phone1": "0000000000",
                "Phone2": "",
                "IsShipping": false,
                "IsBilling": true,
                "IsDefaultShipping": false,
                "IsDefaultBilling": true,
                "AddressBookId": 222
            }, {
                "Email": "[email protected]",
                "Salutation": "",
                "FirstName": "john",
                "LastName": "doe3",
                "Address1": "basel 253",
                "Address2": "",
                "City": "petah tikva",
                "StateOrProvince": "",
                "Zip": "11223344",
                "CountryCode": "IL",
                "CountryName": "Israel",
                "Phone1": "0000000000",
                "Phone2": "",
                "IsShipping": true,
                "IsBilling": true,
                "IsDefaultShipping": false,
                "IsDefaultBilling": false,
                "AddressBookId": 333
            }
        ]
    },
    "allowMailsFromMerchant": true
}
GetRefundDetails

This API provides information about refunds associated with an order. The information includes all the refund details and the refundable amount for each product in the order.

Method/URL

GET https://{globale_api_domain}/v1/orders/{orderId}/refunds

Response Parameters

Name

Type

Description

MerchantInternalOrderId

String

Unique internal order identifier on the merchant's site.

MerchantOrderID

String

Unique order identifier on the merchant’s site.

OrderID

String

Unique Global‑e order identifier.

RefundableAmount

Class RefundableAmount

Object containing details about the refundable amount for the order.

Refunds

Class Refunds

Object containing details about the order refunds.

WebStoreCode

String

Code used on the Merchant’s side to identify the web store.

WebStoreInstanceCode

String

Code used on the Merchant’s side to identify the web store instance.

Examples

Response Example

{
  "OrderId": "string",
  "MerchantOrderId": "string",
  "MerchantInternalOrderId": "string",
  "WebStoreCode": "string",
  "WebStoreInstanceCode": "string",
  "Refunds": [
    {
      "RefundID": "string",
      "RMANumber": "string",
      "MerchantRMANumber": "string",
      "FullRefund": true,
      "ProductsDutiesRefund": true,
      "ShippingRefund": true,
      "RefundAsGiftCard": null,
      "TotalRefundAmount": "string",
      "OriginalTotalRefundAmount": "string",
      "ServiceGestureAmount": "string",
      "TotalMoneyRefundAmount": "string",
      "DutiesAmount": "string",
      "ShippingAmount": "string",
      "CustomerPrepaidRefundAmount": "string",
      "OriginalCustomerPrepaidRefundAmount": "string",
      "TotalGiftCardsRefundAmount": "string",
      "TotalGiftCardsRefundAmountinMerchantCurrency": 0,
      "TotalLoyaltyPointsRefunded": 0,
      "TotalLoyaltyPointsRefundAmount": 0,
      "GiftCardsData": [
        {
          "CardId": 0,
          "OtherFields": "..."
        }
      ],
      "ExternalReference": "string",
      "InitiatedBy": "string",
      "CurrencyCode": "string",
      "OriginalCurrencyCode": "string",
      "RefundReason": {
        "OrderRefundReasonCode": "string",
        "Name": "string"
      },
      "RefundProducts": [
        {
          "CartItemId": "string",
          "RefundQuantity": "string",
          "RefundAmount": "string",
          "OriginalRefundAmount": "string",
          "RefundAmountPercent": "string",
          "RefundReason": "string",
          "RefundComments": "string",
          "Sku": "string",
          "ProductCode": "string",      
          "productGroupCode": "string",            
          "ProductCodeSecondary": "string",
          "productGroupCodeSecondary": "string"      
        }
      ],
      "RefundComponents": [
        {
          "Amount": "string",
          "OriginalAmount": "string",
          "IsChargedToMerchant": "string",
          "ComponentType": "string"
        }
      ],
      "RefundComments": "string",
      "RefundDocument": [
        {
          "DocumentData": "string",
          "CreditNoteUrl": "string",
          "DocumentTypeCode": "string",
          "DocumentTypeName": "string",
          "DocumentExtension": "string"
        }
      ]
    }
  ],
  "RefundableAmount": {
    "CurrencyCode": "string",
    "TotalCreditAmount": 0,
    "RefundableShippingAmount": 0,
    "RefundableDutiesAmount": 0,
    "ProductRefundableAmount": [
      {
        "CartItemId": "string",      
        "Sku": "string", 
        "ProductCode": "string",      
        "productGroupCode": "string",            
        "ProductCodeSecondary": "string",
        "productGroupCodeSecondary": "string",        
        "RefundableTotalAmount": 0,
        "RefundableQuantity":1
      }
    ]
  }
}

Error Response

{
   "error": {
        "code": "String",
	"message": "String",
	"description": "String"	
   }
}

Error Codes

Code

Description

400

Bad Request.

Information cannot be parsed or violates Global-e policies. For example: Order ID not found.

500

Request was successfully parsed with no violations detected, but there was a failure during request handling.

NotifyOrderRefund

NotifyOrderRefund ( Merchant.OrderRefund orderRefund) 

The NotifyOrderRefund method notifies the merchant about Global-e initiated refund issued to the end customer.

If implemented on the merchant’s site, the Global‑e servers post the information about customer refunds, in cases where such refunds are initiated on the Global‑e side.

SAMPLE

Body:

{
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "MerchantOrderId": "14123332",
    "Products": [{
            "CartItemId": 12365,
            "RefundQuantity": "3",
            "OriginalRefundAmount": "114.5300",
            "RefundAmount": "170.1000",
            "RefundReason": {
                "OrderRefundReasonCode": "DAMAGED-ITEM-CODE",
                "Name": "Damaged Item"
            },
            "RefundComments": "Fully refunded order"
        }
    ],
    "OrderId": "GE69488861GB",
    "RefundId": 789,
    "RMANumber": 6543,
    "CurrencyCode": “CAD”,
    "OriginalCurrencyCode": “USD”,
    "TotalRefundAmount": "170.10",
    "RefundReason": {
        "OrderRefundReasonCode": "DAMAGED-ITEM-CODE",
        "Name": "Damaged Item"
    },
    "RefundComments": "Fully refunded order",
    "OriginalTotalRefundAmount": "114.53",
    "ServiceGestureAmount": "0.00",
    "WebStoreCode": null
}

URL:

https://www.merchant-site-domain.com/order-refund-url

ACCEPTS

Merchant.OrderRefund orderRefund

RETURNS

Merchant.ResponseInfo class

PerformOrderPayment

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.

Posts order payment details to the Merchant's site and performs the payment.

Only order.OrderId and order.PaymentDetails members are mandatory for this method. For Mixed orders, "Subs" is mandatory.

SecurityRequirements

  • Merchant GUID - In request payload (required)

  • Custom header (optional)

  • IP whitelist (optional)

  • HTTP Basic Authentication (optional)

  • JWT (optional)

Retry Logic

There is no retry upon a merchant failure response or timeout. The timeout period is 5 minutes and this cannot be adjusted. Requests that fail to initiate from Global-e side will trigger an alert to the Global-e NOC team for manual review. Merchant failure responses or timeouts will trigger an alert to the Global-e NOC team for manual review. Requests that fail to initiate from Global-e side will trigger a retry once a minute for up to 3 attempts after which an alert will trigger for manual review.

Method/URL

POST https://www.merchant-site-domain.com/order-payment-only-url

Parameters

Request Parameter

Name

Type

Description

Mandatory

order

Class Merchant.Order

Merchant.Order objects contain information about orders.

SAMPLE

Body:

{
    "OrderId": "00010000100000000020",
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "PaymentDetails": {
        "OwnerFirstName": "Nir",
        "OwnerLastName": "Debbi",
        "OwnerName": "GlobalE",
        "CardNumber": "0000-0000-0000-0000",
        "CVVNumber": "000",
        "PaymentMethodName": "Visa",
        "PaymentMethodCode": "VI",
        "PaymentMethodTypeCode": "cc",
        "ExpirationDate": "2016-10-31",
        "CountryName": "Israel",
        "CountryCode": "IL",
        "StateOrProvince": "",
        "City": "Petach Tikva",
        "Zip": "12345",
        "Address1": "Kiryat Arye",
        "Address2": "",
        "Phone1": "",
        "Phone2": "",
        "Fax": "",
        "Email": ""
    }
}

ACCEPTS

  {
  "AllowMailsFromMerchant":false,
  "AllowSMSFromMerchant":null,
  "AllowDirectCommunicationFromMerchant":null,
  "ReservationRequestId":null,
  "ClearCart":false,
  "CurrencyCode":null,
  "Customer":{
    "EmailAddress":null,
    "IsEndCustomerPrimary":false,
    "SendConfirmation":false
  },
  "CustomerComments":null,
  "Discounts":[
  ],
  "DoNotChargeVAT":false,
  "FreeShippingCouponCode":null,
  "IsFreeShipping":false,
  "IsSplitOrder":false,
  "LoyaltyCode":null,
  "LoyaltyPointsEarned":null,
  "LoyaltyPointsSpent":null,
  "Markups":[
  ],
  "OriginalMerchantTotalProductsDiscountedPrice":0.0,
  "OTVoucherAmount":null,
  "OTVoucherCode":null,
  "OTVoucherCurrencyCode":null,
  "InitialCheckoutCultureCode":null,
  "CultureCode":null,
  "HubId":null,
  "HubCode":null,
  "PrimaryShipping":{
    "Address1":null,
    "Address2":null,
    "AddressBookId":null,
    "City":null,
    "Company":null,
    "CountryCode":null,
    "CountryCode3":null,
    "CountryName":null,
    "Email":null,
    "Fax":null,
    "FirstName":null,
    "LastName":null,
    "MiddleName":null,
    "Phone1":null,
    "Phone2":null,
    "Salutation":null,
    "StateCode":null,
    "StateOrProvince":null,
    "Zip":null,
    "CollectionPointId":null,
    "AddressBookName":null,
    "CustomerTaxId":null
  },
  "Products":[
  ],
  "RoundingRate":0.0,
  "SameDayDispatch":false,
  "SameDayDispatchCost":0.0,
  "SecondaryShipping":{
    "Address1":null,
    "Address2":null,
    "AddressBookId":null,
    "City":null,
    "Company":null,
    "CountryCode":null,
    "CountryCode3":null,
    "CountryName":null,
    "Email":null,
    "Fax":null,
    "FirstName":null,
    "LastName":null,
    "MiddleName":null,
    "Phone1":null,
    "Phone2":null,
    "Salutation":null,
    "StateCode":null,
    "StateOrProvince":null,
    "Zip":null,
    "CollectionPointId":null,
    "AddressBookName":null,
    "CustomerTaxId":null
  },
  "ShippingMethodCode":null,
  "ShipToStoreCode":null,
  "UrlParameters":null,
  "IsReplacementOrder":false,
  "OriginalOrder":null,
  "TotalDutiesAndTaxesPrice":0.0,
  "CCFPrice":0.0,
  "UserId":null,
  "GiftCards":[
  ],
  "PreferredCultureCode":null,
  "ShippingVATRate":null,
  "OrderPaymentMethods":[
    {
      "PaymentMethodId":1,
      "PaymentMethodName":"Visa",
      "IsGiftCard":false,
      "GiftCardFields":null,
      "PaidAmountInCustomerCurrency":393.5600,
      "PaidAmountInMerchantCurrency":235.74993308058803207162312511,
      "PaymentMethodTypeCode":"1",
      "PaymentMethodTypeName":"Credit Card"
    }],
  "CustomerDTBreakdown":null,
  "MerchantDTBreakdown":null,
  "TotalDutiesPaidByCustomerPrice":null,
  "CookieConsent":0,
  "IsMoto":false,
  "ModifiedProduct":null,
  "TaxCalculationRule":"CIF",
  "TotalValueForCustoms":393.5600,
  "USSalesTax":0.0,
  "ImporterDetails":null,
  "PaymentDetails":{
    "Address1":"200 west 41st street",
    "Address2":"9th floor",
    "CardNumber":null,
    "City":"New York",
    "CountryCode":"US",
    "CountryCode3":"USA",
    "CountryName":"United States",
    "CVVNumber":null,
    "Email":"[email protected]",
    "ExpirationDate":"2040-09-22",
    "Fax":null,
    "OwnerFirstName":"Global-e",
    "OwnerLastName":"US Inc.",
    "OwnerName":"Global-e US Inc.",
    "PaymentMethodCode":"OT",
    "PaymentMethodName":"Undefined",
    "PaymentMethodTypeCode":"globaleintegration",
    "Phone1":"+1 (212) 634-3952",
    "Phone2":null,
    "StateCode":"NY",
    "StateOrProvince":"New York",
    "Zip":"10036"
  },
  "PrimaryBilling":{
    "Address1":"t",
    "Address2":null,
    "AddressBookId":null,
    "City":"t",
    "Company":null,
    "CountryCode":"NZ",
    "CountryCode3":"NZL",
    "CountryName":"New+Zealand",
    "Email":"[email protected]",
    "Fax":null,
    "FirstName":"FirstName",
    "LastName":"LastName",
    "MiddleName":null,
    "Phone1":"2125551212",
    "Phone2":null,
    "Salutation":null,
    "StateCode":null,
    "StateOrProvince":null,
    "Zip":"2345",
    "CollectionPointId":null,
    "AddressBookName":null,
    "CustomerTaxId":null
  },
  "SecondaryBilling":{
    "Address1":"200 west 41st street",
    "Address2":"9th floor",
    "AddressBookId":null,
    "City":"New York",
    "Company":"GlobalE",
    "CountryCode":"US",
    "CountryCode3":"USA",
    "CountryName":"United States",
    "Email":"[email protected]",
    "Fax":null,
    "FirstName":"Global-e",
    "LastName":"US Inc.",
    "MiddleName":null,
    "Phone1":"+1 (212) 634-3952",
    "Phone2":null,
    "Salutation":null,
    "StateCode":"NY",
    "StateOrProvince":"New York",
    "Zip":"10036",
    "CollectionPointId":null,
    "AddressBookName":null,
    "CustomerTaxId":null
  },
  "CartHash":"3A29A654B1A5DD8D758D19C827B69E83",
  "CartToken":null,
  "GlobalECartToken":null,
  "CartId":"f9847639-95e8-4e75-b198-9031a205e001:384880634",
  "DiscountedShippingPrice":221.15,
  "InternationalDetails":{
    "ConsignmentFee":0.0000,
    "CurrencyCode":"NZD",
    "DeliveryDaysFrom":9,
    "DeliveryDaysTo":15,
    "DiscountedShippingPrice":369.1900,
    "DutiesGuaranteed":false,
    "OrderTrackingNumber":null,
    "OrderTrackingUrl":"https%3a%2f%2fwww.bglobale.com%2fOrder%2fTrack%2fmZz5%3fOrderId%3dGE01812420US%26ShippingEmail%3dtest%40test.com",
    "OrderWaybillNumber":null,
    "PaymentMethodCode":"1",
    "PaymentMethodName":"Visa",
    "RemoteAreaSurcharge":0.0000,
    "SameDayDispatchCost":0.0000,
    "ShippingMethodCode":"40049745",
    "ShippingMethodName":"DHL api Express Worldwide",
    "ShippingMethodTypeCode":"Express",
    "ShippingMethodTypeName":"Express Courier (Air)",
    "SizeOverchargeValue":17.0000,
    "TotalCCFPrice":0.0000,
    "TotalDutiesPrice":0.000000000,
    "TotalPrice":393.56,
    "TotalShippingPrice":369.1900,
    "TransactionCurrencyCode":"NZD",
    "TransactionTotalPrice":393.5600,
    "ParcelsTracking":null,
    "CardNumberLastFourDigits":null,
    "ExpirationDate":null,
    "ShippingVATRate":0.0000,
    "CashOnDeliveryFee":0.0,
    "CustomerDTBreakdown":null,
    "MerchantDTBreakdown":null,
    "DeliveryDateFrom":"25.03",
    "DeliveryDateTo":"04.04",
    "ShipmentLocation":null,
    "ShipmentStatusUpdateTime":null,
    "ShippingMethodStatusCode":"Undefined",
    "ShippingMethodStatusName":"undefined"
  },
  "MerchantGUID":"12345678-1234-1234-1234-123456789012",
  "MerchantOrderId":"123456789",
  "OrderId":"GE01812420US",
  "PriceCoefficientRate":1.150000,
  "StatusCode":"N/A",
  "WebStoreCode":"en-nz",
  "WebStoreInstanceCode":"en-nz"
}
Classes for PerformOrderPayment API
RedeemGiftCard

RedeemGiftCard sends the amount of the used card balance. This information is saved on your platform.

Add the GiftCardData.RedeemTransactionId for each gift card during this call.

SAMPLE

Body:

{
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "ShippingCountryCode": "IL",
    "Cards": [{
            "CardId": 2864,
            "BalanceInGiftCardCurrency": 365.930000,
            "BalanceInCustomerCurrency": 1286.210000,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "ILS",
            "BalanceUsedInCardCurrency": 94.910000,
            "BalanceUsedInCustomerCurrency": 333.590000,
            "CardFields": {
                "CardId": "111111"
            }
        }
    ],
    "OrderId": " GE927127",
    "MerchantCartToken": "cf270ce6b2d4ce6d2d882536b8741a01"
}

URL:

https://www.merchant-site-domain.com/redeem-gift-card-url

Response Body:

{
    "Cards": [{
            "CardId": 2864,
            "BalanceInGiftCardCurrency": 365.93,
            "BalanceInCustomerCurrency": 1286.21,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "ILS",
            "BalanceUsedInCardCurrency": 94.91,
            "BalanceUsedInCustomerCurrency": 333.59,
            "RedeemTransactionId": 2,
            "CardFields": {
                "CardId": "111111"
            }
        }
    ],
    "ErrorCode": null,
    "ErrorText": null
}

ACCEPTS

RedeemGiftCardRequest class

RETURNS

RedeemGiftCardResponse class

RefundGiftCard

Call RefundGiftCard to return the used gift card balance when the order is cancelledcanceled or a new Refund has been created.

Global‑e sends the list of all applied gift cards and the total amount to refund for gift cards in both currencies (customer currency and gift card currency), as well as the conversion rate. The Merchant’s platform determines the actual refund values to be refunded for each gift card and returns the respective values in the API response accordingly.

For each gift card, set the following in response:

GiftCardData.RefundedBalanceInGiftCardCurrency – must not exceed the provided value of GiftCardData.BalanceUsedInCardCurrency

GiftCardData.RefundedBalanceInCustomerCurrency – must not exceed the provided value of GiftCardData.BalanceUsedInCustomerCurrency

GiftCardData.IsRefundSuccess

  • Set to true: If the two previous values for the card and values are successfully refunded.

  • Set to false: If the refund was added but something went wrong.

If no refunds are added for the particular card, do not set these values.

SAMPLE

Body:

{
    "MerchantGUID": " abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "Cards": [{
            "CardId": 2290,
            "BalanceInGiftCardCurrency": 1000.000000,
            "BalanceInCustomerCurrency": 906.270000,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "EUR",
            "BalanceUsedInCardCurrency": 273.990000,
            "BalanceUsedInCustomerCurrency": 248.3100,
            "RedeemTransactionId": "TestSuccessRedeemTransaction",
            "CardFields": {
                "CardId": "card1000"
            }
        }
    ],
    "TotalToRefundInCustomerCurrency": 115.0,
    "TotalToRefundInGiftCardCurrency": 126.89,
    "ConversionRate": 0.906269,
    "OrderId": "GE927127"
}

URL:

https://www.merchant-site-domain.com/refund-gift-card-url

Response Body:

{
    "Cards": [{
            "CardId": 2290,
            "BalanceInGiftCardCurrency": 1000.000000,
            "BalanceInCustomerCurrency": 906.270000,
            "GiftCardCurrencyCode": "USD",
            "CustomerCurrencyCode": "EUR",
            "BalanceUsedInCardCurrency": 273.990000,
            "BalanceUsedInCustomerCurrency": 248.3100,
            "RedeemTransactionId": "TestSuccessRedeemTransaction",
            "CardFields": {
                "CardId": "card1000"
            },
            "RefundedBalanceInGiftCardCurrency": 126.89,
            "RefundedBalanceInCustomerCurrency": 115.0,
            "IsRefundSuccess": true
        }
    ],
    "TotalToRefundInCustomerCurrency": 115.0,
    "TotalToRefundInGiftCardCurrency": 126.89,
    "ConversionRate": 0.906269,
    "OrderId": "GE2991190US"
}

ACCEPTS

RefundGiftCardRequest class

RETURNS

RefundGiftCardResponse class

RemoveRestrictedProducts

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 removes restricted products from the merchant cart; it notifies you that restricted products were removed from the cart, so you should also update the cart on your side.

SAMPLE

Body:

{
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
     "CartToken": "d3b9d91b-cbc9-4485-9f37-b0490c419338",
     "CartId": "37296D5PJE",
     "UserId": null,
     "CountryCode": "VN",
     "CurrencyCode": "VND",
     "WebStoreCode": null,
     "WebStoreInstanceCode": null,
     "RemovedProductCodes": ["1601893OPK0XS"]
}

URL:

https://www.merchant-site-domain.com/remove-restricted-products-url

Response Body:

{"IsSuccess": true}

ACCEPTS

Merchant.RemoveRestrictedProductsRequest request

RETURNS

Merchant.RemoveRestrictedProductsResponse class

SendAdditionalRequiredDocumentsToMerchant

SendAdditionalRequiredDocumentsToMerchant ( SendAdditionalRequiredDocumentsToMerchantRequestrequest)

Description

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.

Method: POST

Security: IP whitelist, Secret GUID, Authorization header

Sample

Request Body:

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

{	
	"StatusCode": "200",
	"Success": "true",
	"Message": "...",
	"ErrorCode": "...",
	"ErrorText": "..."
}
SendOrderToMerchant

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 the Merchant.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 fulfilmentfulfillment until the documents are ready and provided to the merchant in the SendAdditionalRequiredDocumentsToMerchant webhook.

Security Requirements

  • Merchant GUID - In request payload (required)

  • Custom header (optional)

  • IP whitelist (optional)

  • HTTP Basic Authentication (optional)

  • JWT (optional)

Retry Logic

There is no retry upon a merchant failure response or timeout. The timeout period is 5 minutes but can be adjusted if necessary. Merchant failure responses or timeouts will trigger an alert to the Global-e NOC team for manual review. Requests that fail to initiate from Global-e side will trigger a retry once a minute for up to 3 attempts, after which an alert will trigger for manual review.

Method/URL

POST https://www.merchant-site-domain.com/order-update-create-url

Parameters

Request Parameters

Name

Type

Description

Mandatory

order

Class Merchant.Order

Array of OrderInfoForAdditionalDocuments objects with information about orders for which additional shipping documents are required.

Response Parameters

Name

Type

Description

Mandatory

ResponseInfo

Class Merchant.ResponseInfo

Indicates if an API call was successful or not and why.

Example

Request Examples

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",
    },
  ]
}

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",
    }
   ]
}
Classes for SendOrderToMerchant API
SendRMAToMerchant

Use API to send the Global‑e RMA number to the merchant. Sends MerchantReturn object to the merchant.

Method/URL

POST https://www.merchant-site-domain.com/rma-info-to-merchant-url

MerchantAppSetting, SendRMAInfoToMerchantURI must be set to turn on this feature.

Parameters

Request Parameters

Request classes MerchantOrder and MerchantReturn.

Name

Type

Description

Mandatory

merchantOrder

Class merchantOrder

Provides order return details.

merchantReturn

Class merchantReturn

Provides merchant return information. Includes the following information:

  • CreatedBy

  • MerchantGUID

  • MerchantOrderId

  • OrderId

  • ReturnedProducts

  • ReturnShippingCost

  • ReturnTrackingNumber

  • RMANumber

  • ShipperName

  • TrackingURL

Return Parameters

Name

Type

Description

Mandatory

merchant.ResponseInfo

Class Merchant.ResponseInfo

Provides API call response info.

Example

Request Example

{
    "OrderId": "GE24192321GB",
    "MerchantOrderId": "71144",
    "RMANumber": "223878",
    "ShipperName": "DHL",
    "ReturnTrackingNumber": "857854854778",
    "TrackingURL": "www.dhl.com/Tracking?TrackingNumber=857854854778",
    "CreatedBy": "Customer",
    "ReturnedProducts": [
        {
            "SKU": "ProductD",
            "Name": "Blue jacket",
            "CartItemId": "2",
            "ReturnQuantity": 1,
            "ReturnReasonName": "Arrived too late",
            "MerchantReturnReasonCode": null,
            "MerchantReturnReasonName": null
        }
    ],
    "MerchantGUID": "7e3d5523-d86a-4c56-8f47-5a48b829e3b7",
    "CurrencyCode": "EUR",
    "ReturnShippingCost": 10.00
}

Response Example

{
    "Success": "True",
    "Message": "success message",
    "Description": "success description"
}
Classes for SendRMAToMerchant API
UpdateOrderShippingInfo

UpdateOrderShippingInfo ( Merchant.Order order)

Updates the order's international shipping information on the Merchant site.

Only order.OrderId and order.InternationalDetails members are mandatory for this method.

SAMPLE

Body:

{
    "OrderId": "00010000100000000020",
    "InternationalDetails": {
        "OrderTrackingNumber": "1265443",
        " OrderTrackingUrl": "http://www.somecarrier.com/?1265443"
    },
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd"
}

URL:

https://www.merchant-site-domain.com/order-shipping-info-update-only-url

ACCEPTS

Merchant.Order order

RETURNS

Merchant.ResponseInfo class

UpdateOrderStatus

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.

UpdateOrderStatus ( Merchant.Order order)

Updates order status of the order on the Merchant’s site. Only order.OrderId and order.StatusCode members are mandatory for this method.

When implementing a Global-e extension or plug-in, this method is required to support order cancellation when it is initiated on Global-e’s side. It can also be used for reporting other order status updates as they occur in the Global-e’s system, and reflect them in the Merchant’s system.

SAMPLE

Body:

{
    "OrderId": "00010000100000000020",
    "StatusCode": "canceled",
    "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd"
}

URL:

https://www.merchant-site-domain.com/order-status-update-only-url

ACCEPTS

Merchant.Order order

RETURNS

Merchant.ResponseInfo class

UpdateRMA

Call the UpdateRMA API to set or update the MerchantRMANumber and send an email to the customer.

SAMPLE

Body:

{
    “OrderId”: ”12345”, (optional)
    “MerchantOrderId”: ”09876”, (optional)
    ”RMANumber”: ”852147”, 
    ”MerchantRMANumber”: ”265646925”
}

URL:

https://{server_name}/Return/UpdateRMA?merchantGUID= F3BE2R-8546-FC38-90SJ-1C780SG8F90SBS

ACCEPTS

UpdateRMANumber updateRMANumber

RETURNS

HttpResponseMessage class

ValidateGiftCard

The ValidateGiftCard request sends the gift card data to the platform, gets the card amount, and makes sure that the card is valid.

ValidateGiftCard is called when the user fills out all gift card fields on the checkout page.

SAMPLE

Body:

{
    "MerchantGUID": abcdabcd - abcd - abcd - abcd - abcdabcdabcd ",
    	" ShippingCountryCode ":" UA ",
    	" CardFields ":{" CardId ":" 111111 "},
    	" MerchantCartToken ":" 2c5c7b3db2ed101426cba38d9c534086 "
}

URL:

https://www.merchant-site-domain.com/validate-gift-card-url

Response Body:

For valid cards:

{
    "IsValid": true,
    "Balance": 1000,
    "CurrencyCode": "GBP",
    "IsGlobalEGiftCard": false,
    "ErrorCode": null,
    "ErrorText": null
}

For invalid cards:

{
    "IsValid": false,
    "Balance": null,
    "CurrencyCode": null,
    "IsGlobalEGiftCard": false,
    "ErrorCode": null,
    "ErrorText": "Invalid Card"
}

ACCEPTS

ValidateGiftCardRequest class

RETURNS

ValidateGiftCardResponse class

ValidateStock

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.

ValidateStock (Merchant.CartValidationData cartValidationData)

The Merchant Cart Validation checks basic cart validity and validates the product’s stock availability.

If a product line cart item listed in order.Products does not have full stock availability for the specified quantity, this cart item is included in the AmendedProducts array with an indication of the quantity actually available. If all items are in stock, the AmendedProducts array is empty.

If required, the ValidateStock API is called when the customer is in the Global‑e checkout. If the AmendedProducts array is not empty, the list of out-of-stock products is displayed to the customer.

Note

In the GEM integration method, the GetCheckoutCartInfo API may be reused for stock validation purposes.

SAMPLE

Body:

{
    "GlobalECartToken": "1da35dc3-cbe6-4cd8-81d6-ce433466d715",
    "PreferredCultureCode": null,
    "AuthToken": "34sdfdg43erfg43234fwsedfsdf423",
    "SessionId": "12345",
    "DateCreated": "0001-01-01T00:00:00",
    "CurrencyName": null,
    "Parcels": null,
    "AllowMailsFromMerchant": false,
    "AllowDirectCommunicationFromMerchant": false,
    "ClearCart": false,
    "UserId": null,
    "CurrencyCode": "ILS",
    "Products": [{
            "Attributes": null,
            "Sku": "648340636",
            "Price": 157.7000,
            "PriceBeforeRoundingRate": null,
            "PriceBeforeGlobalEDiscount": null,
            "Quantity": 1,
            "VATRate": null,
            "CustomerVATRate": null,
            "InternationalPrice": 649.0000,
            "InternationalDiscountedPriceInMerchantCurrency": null,
            "CartItemId": "ci21000088",
            "ParentCartItemId": null,
            "CartItemOptionId": null,
            "HandlingCode": null,
            "GiftMessage": null,
            "RoundingRate": 0.0,
            "IsBackOrdered": false,
            "BackOrderDate": null,
            "DiscountedPrice": null,
            "InternationalDiscountedPrice": null,
            "ProductCodeSecondary": "MKC1120A~N~040~~NS",
            "Brand": null,
            "Categories": null,
            "ListPrice": 0.0,
            "InternationalListPrice": 0.0,
            "GenericHSCode": null,
            "DiscountedPriceForCustoms": 0.0,
            "InternationalDiscountedPriceForCustoms": 0.0,
            "IsGiftCard": false,
            "IsFixedPrice": true
        }
    ],
    "Customer": {
        "EmailAddress": null,
        "IsEndCustomerPrimary": false,
        "SendConfirmation": false
    },
    "PrimaryShipping": {
        "FirstName": "sdfsdf",
        "LastName": "sdfsdf",
        "MiddleName": null,
        "Salutation": null,
        "Company": null,
        "Address1": "asdasd+234",
        "Address2": "",
        "City": "asdasd",
        "StateCode": null,
        "StateOrProvince": null,
        "Zip": "1234567",
        "Email": "sdfsdf%40asdasd.com",
        "Phone1": "0000000000",
        "Phone2": null,
        "Fax": null,
        "CountryCode": "IL",
        "CountryCode3": null,
        "CountryName": null,
        "AddressBookId": null,
        "AddressBookName": null,
        "SaveAddress": false
    },
    "SecondaryShipping": {
        "FirstName": "GlobalE",
        "LastName": "GE-UK@EMA-Norsk",
        "MiddleName": null,
        "Salutation": null,
        "Company": "",
        "Address1": "Building 436, Argosy Road",
        "Address2": "East Midlands Airport",
        "City": "Derby",
        "StateCode": "NN",
        "StateOrProvince": null,
        "Zip": "DE74 2SA",
        "Email": "[email protected]",
        "Phone1": "01332 818723",
        "Phone2": null,
        "Fax": null,
        "CountryCode": "GB",
        "CountryCode3": "GBR",
        "CountryName": "United Kingdom",
        "AddressBookId": null,
        "AddressBookName": null,
        "SaveAddress": false
    },
    "ShippingMethodCode": "Express Courier (Air)",
    "Discounts": [],
    "Markups": [],
    "LoyaltyPointsSpent": null,
    "LoyaltyPointsEarned": null,
    "SameDayDispatch": false,
    "SameDayDispatchCost": 0.0,
    "DoNotChargeVAT": false,
    "CustomerComments": null,
    "IsFreeShipping": false,
    "FreeShippingCouponCode": null,
    "ShipToStoreCode": null,
    "RoundingRate": 0.0,
    "UrlParameters": "[{\"Key\":\"ClientCookie\",\"Value\":\"JSESSIONID=null\"},{\"Key\":\"userId\",\"Value\":\"1148993\"},{\"Key\":\"orderId\",\"Value\":\"w748807\"},{\"Key\":\"locale\",\"Value\":\"en_IL\"}]",
    "OriginalMerchantTotalProductsDiscountedPrice": 0.0,
    "LoyaltyCode": null,
    "OTVoucherCode": null,
    "OTVoucherAmount": null,
    "OTVoucherCurrencyCode": null,
    "IsSplitOrder": false,
    "PrePayOffered": false,
    "InitialCheckoutCultureCode": null,
    "CultureCode": null,
    "HubId": 0,
    "IsReplacementOrder": false,
    "OriginalOrder": null,
    "ReservationRequestId": null,
    "IsSuppressPersonalInformation": false,
    "TotalDutiesAndTaxesPrice": 0.0,
    "USSalesTax": 0.0,
    "CCFPrice": 0.0,
    "PaymentDetails": null,
    "PrimaryBilling": {
        "FirstName": null,
        "LastName": null,
        "MiddleName": null,
        "Salutation": null,
        "Company": null,
        "Address1": null,
        "Address2": null,
        "City": 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
    },
    "SecondaryBilling": {
        "FirstName": null,
        "LastName": null,
        "MiddleName": null,
        "Salutation": null,
        "Company": null,
        "Address1": null,
        "Address2": null,
        "City": 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
    },
    "OrderId": null,
    "StatusCode": null,
    "MerchantGUID": "7f132fc6-bdbc-420e-a2ce-fd35ab5c06d0",
    "CartId": "_2S0DVucAbjgfHAR-SUmRshWaS3pB5F9Bk7OfgWBR9ujllKrTw5H!17426857!1596453641116",
    "MerchantOrderId": null,
    "PriceCoefficientRate": 0.0,
    "CartHash": "94210A58BAC3B3AB292DE94382910C87",
    "WebStoreCode": "en_IL",
    "WebStoreInstanceCode": "GlobalEDefaultStoreInstance",
    "DiscountedShippingPrice": 0.0,
    "InternationalDetails": null,
    "GiftCards": null
}

URL:

https://www.merchant-site-domain.com/checkout-validate-cart-stock-url

Response body:

Example of generic error:

Error code 3 is expected. An appropriate error message is shown to the customer and a new clean cart is generated.

{
    "AmendedProducts": [],
    "Error": "3",
    "StackTrace": " at CallSite.Target(Closure , CallSite , Object )\r\n at GlobalE.GEM.BL.GEMProviders.BaseProviders.BaseGEMProvider.ParseReservationInfo(Object reservationInfo) in C:\\jenkins\\workspace\\GEPI\\787e4b5b9a7709ca06b57fcfbeb2bdb2\\GlobalE.GEM.BL\\GEMProviders\\BaseProviders\\BaseGEMProvider.cs:line 844",
    "ReservationRequestId": null
}

Example of invalid email error:

Error code 2 is expected. An appropriate error message is shown to the customer and a new clean cart is generated.

{
    "AmendedProducts": [],
    "Error": "2",
    "StackTrace": null,
    "ReservationRequestId": null
}

Example of invalid cart content error:

Error code 1 is expected. One of the cart fields is invalid. An appropriate error message is shown to the customer and a new clean cart is generated.

{
    "AmendedProducts": [],
    "Error": "1",
    "StackTrace": null,
    "ReservationRequestId": null
}

If all products are in stock:

{
    "AmendedProducts": [],
    "ReservationRequestId": null,
    "Error": null
}

If some products are out of stock:

{
    "AmendedProducts": [{
            "CartItemID": "11007",
            "QuantityInStock": 1
        }
    ],
    "ReservationRequestId": null
}

ACCEPTS

Merchant.Order order

RETURNS

Merchant.StockValidationResponse class

ValidateVoucher

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.

Merchant Validation of Vouchers/coupons on the Checkout page

If the voucher is valid, the merchant’s platform is responsible for applying this voucher to the respective user’s basket and executing a new SendCart / SendCartV2 API call to Global‑e, with an indication of the newly generated discount for this voucher or coupon. The new CartToken returned from this call is returned in the CartToken attribute.

SAMPLE

Body:

 {
    "CartHash": "",
    "CartId": "36048",
    "CartToken": "f8a78edd-7cea-4cb7-835c-57c7f0b13c56",
    "CountryCode": "IL",
    "CurrencyCode": "ILS",
    "Discounts": [],
    "FreeShippingCouponCode": "",
    "IsFreeShipping": false,
    "MerchantGUID": "e967e65e-f69e-479c-949d-91289a7f6875",
    "Products": [],
    "UserId": null,
    "VoucherCode": "10Perc",
    "VoucherType": 1,
    "WebStoreCode": null,
    "WebStoreInstanceCode": "GlobalEDefaultStoreInstance"
}

URL:

https://www.merchant-site-domain.com/checkout-validate-cart-voucher-url

Response Body:

{
    "IsVoucherValid": true,
    "VoucherType": 1,
    "CartToken": "f8a78edd-7cea-4cb7-835c-57c7f0b13c56",
    "VoucherValidationRestriction": [],
    "ValidationFaliureMessage": ""
}

ACCEPTS

Merchant.CartVoucherValidation request

RETURNS

Merchant.VoucherValidationResponse class