Order Methods

CreateOrderRefund

CreateOrderRefund (OrderRefundDetails OrderRefund, List<RefundProduct> refundProductList)

The method Issues a refund for the order specified in the orderRefund argument. Optionally, this method may include the list of RefundProducts to refund. If orderRefund.TotalRefundAmount is not specified, it is converted to the end customer’s currency based on the RefundAmount or OriginalRefundAmount values for the RefundProducts in the refundProductsList and their respective Product VAT rates.

If orderRefund.FullRefund is specified as true:

A full refund is created.
refundProductsList should not be provided, otherwise, the call fails with an error "Full refund requested but list of RefundProduct is not empty."
The orderRefund.TotalRefundAmount and orderRefund.OriginalTotalRefundAmount values which are provided in the call are ignored and recalculated based on the order details.

ELSE

If product.RefundAmount AND product.OriginalRefundAmount are not specified then:

product.RefundAmount AND product.OriginalRefundAmount are calculated based on the order product price.
orderRefund.TotalRefundAmount is recalculated based on the products refund amount plus the sum of all non-product related refund components
(orderRefund.ServiceGestureAmount + orderRefund.DutiesAmount + orderRefund.ShippingAmount)

If we don’t perform a full refund or the refund request/refund item quantity is not valid, we return a JSON response according to the Merchant Account Settings ReturnResponseOfErrorInfoStruct value.

if this Merchant Account Settings is true, the JSON response is in the ErrorInfo struct.

Otherwise, the response is in the ResponseInfo struct.

The ErrorInfo includes a field code containing a numeric value.

The optional values are:

1001 - Order already fully refunded or cancelledcanceled

1002 – Requested refund amount is greater than the remaining amount available for a refund for this order

1003 - Invalid quantity

1004 - Refund request must contain at least one refund component

1005 - Cartitemid {currentRefundProduct.CartItemId} doesn’t exists for order {orderRefundObj.OrderId

1006 - Cartitemid {currOrderProduct.CartItemId} exceeded the quantity of the available products to refund

SAMPLE for ReturnResponseOfErrorInfoStruct is True

Body:

{
    "Code": "1006",
    "Error": "Cartitemid 1 exceeded the available products quantity to refund",
    "Description": "After Method ValidateProducts. refund amount: 67.8700 , available loyalty points: 0.0000"
}

URL:

http://apidev.bglobale.com/Order/CreateOrderRefund?merchantGUID=1397fd89-c0e2-4eb9-95d8-f45f85e88a89&orderRefund={"OrderId":"GE181508244GB"}

Sample for the rest of the flow

Body:

[{
        "CartItemId": "134643",
        "RefundQuantity": "1",
        "RefundAmount": "42",
        "RefundReason": {
            "OrderRefundReasonCode": "RETURN",
            "Name": "RETURN"
        },
        "RefundComments": ""
    }, {
        "CartItemId": "134644",
        "RefundQuantity": "1",
        "RefundAmount": "58",
        "RefundReason": {
            "OrderRefundReasonCode": "RETURN",
            "Name": "RETURN"
        },
        "RefundComments": ""
    }
]

URL:

http://connect2.bglobale.com/Order/CreateOrderRefund?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd&orderRefund={"OrderId":"GE123874638GB","TotalRefundAmount":100,"RefundComments":"","RefundReason":{"OrderRefundReasonCode":"RETURN","Name":"RETURN"}}

The Merchant Account Settings ‘SetAllPrepaidReturnsWithRefund’ supports all prepaid returns includes free by Admin and free by Merchant that the return id will be send to NotifyOrderRefund and wiil link the OrderRefund with the return.

ACCEPTS

OrderRefundDetails orderRefund
Order refund details for the order specified
List<RefundProduct> refundProductsList (optional)
List of RefundProduct objects for this order refund. Note that this products list is mandatory if the refund is issued for Products.

RETURNS

ResponseInfo class

DispatchConsolidatedShipment

DispatchConsolodatedShipment (GetOrdersManifestRequest request)

Returns a list of details for the orders.

Can function with a list of Global‑e order IDs:

SAMPLE

Body:

{
    "OrderIds": ["GE2794623GB", "GE2794622GB", "GE2794621GB"],
    “OuterBoxesAmount”: 1
}

URL:

https://{server_name}/Order/DispatchConsolidatedShipment?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

ACCEPTS

GetOrdersManifestRequest request

Full post data list of order Ids and outer boxes amount

RETURNS

OrderDocumentsResponse class.

DispatchOrders

DispatchOrders (GetOrdersManifestRequest request)

Returns manifest documents.

Can function with either a list of global-e order ids or a list of merchant order ids. If the optional hubCode parameter is specified, then only the parcels or orders that were sent from the specified hub will be dispatched:

Body:

{
    "HubCode": "Store",
    "OrderIds": ["GE2794623GB", " GE2794622GB", " GE2794621GB"]
}

{
    "OrderIds": ["2794623", " 2794622", " 2794621"]
}

URL:

https://{server_name}/Order/DispatchOrders?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

ACCEPTS

GetOrdersManifestRequest request

Full post data list of order IDs

RETURNS

OrderDocumentsResponse class

GetOrdersDetails

GetOrdersDetails (OrderDetailsFilter filter)

Returns a list of orders and their details.

Can function with a list of Global‑e order IDs:

SAMPLE

Body:

{
    "OrderIds": ["GE2794623GB", "GE2794622GB", "GE2794621GB"]
}

URL:

https://{server_name}/Order/GetOrdersDetails?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

ACCEPTS

OrderDetailsFilter filter

Full post data list of Global‑e order Ids

RETURNS

List of Merchant.Order classes.

GetShippingDocuments

GetShippingDocuments (UpdateOrderDispatchRequest request)

Returns shipping documents.

USAGE

There are two usages:

The request includes the OrderId or MerchantOrderId, an empty list of parcels, and/or an empty list of exceptions (no hubCode is provided):
Returns the existing shipping documents for the requested order.
The request includes the OrderId / MerchantOrderId, the list of parcels, and/or the list of exceptions:
Updates order status and Delivery Quantities for the products, as well as Merchant’s internal Delivery Reference Number if applicable. Optionally may include Exceptions to report on out-of-stock items and items that will be shipped later on. In addition, there is an option to add tracking information on each parcel or on the entire order.
Update status of order and parcels to status – Received in Hub
Returns shipping documents and parcels that were sent in the request.
If the optional hubCode is provided, assign the specified parcels for the specified hub. The feature is used when an order includes parcels to be sent from different hubs.
Optional: You can add information that can be used later when the shipping request call is placed to FedEx. This is implemented by adding the ShippingAdditionalInformation property at either, the order level or the parcel level (not both).

Body for the first usage:

{
    "OrderId": "GE123874638GB",
    "MerchantOrderID": "100018322",
    "DeliveryReferenceNumber": "123756483",
    "IsCompleted": true,
    "Parcels": [],
    "Exceptions": []
}

Body for the second usage:

{
    "HubCode": "Store",
    "OrderId": "GE123874638GB",
    "MerchantOrderID": "100018322",
    "DeliveryReferenceNumber": "123756483",
    "IsCompleted": true,
    "Parcels": [{
            "ParcelCode": "123454321",
            "Products": [{
                    "DeliveryQuantity": 1,
                    "CartItemId": "12365",
                    "ProductCode": "121212"
                }, {
                    "DeliveryQuantity": 2,
                    "CartItemId": "12376",
                    "ProductCode": "131313"
                }
            ],
            "TrackingDetails": {
                "TrackingNumber": "111111122666"
            },
/*Add ShippingAdditionalInformation at the order level or at the package level, not both.*/
            "ShippingAdditionalInformation": [{
                    "name": "ITNNumber",
                    "value": "12345"
                }
            ]
        }
    ],
    "Exceptions": [{
            "CartItemId": "12366",
            "ProductCode": "121213",
            "ExceptionType": 1
        }, {
            "CartItemId": "12367",
            "SKU": "SKU121214",
            "ExceptionType": 2,
            "ExpectedFulfilmentDate": "2018-01-18"
        }
    ],
    "TrackingDetails": {
        "TrackingNumber": "111111122666"
    },
/*Add ShippingAdditionalInformation at the order level or at the package level, not both.*/
    "ShippingAdditionalInformation": [{
            "name": "ITNNumber",
            "value": "12345"
        }
    ]
}

URL:

https://{server_name}/Order/GetShippingDocuments?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

ACCEPTS

UpdateOrderDispatchRequest request

Full post data including OrderId, Exceptions, and Parcels with Products for the call.

RETURNS

OrderDocumentsResponse class

UpdateOrderDispatch

Note

LEGACY: For reference only. These methods do not need to be implemented by Merchants anymore.

(List <Product> productsList, OrderStatusDetails orderStatus, List <Parcel> parcelsList)

Updates the order status and Delivery Quantities for the products, as well as Merchant’s internal Delivery Reference Number, if applicable. Optionally, you can include the list of Parcels for this order shipment to the Global-e hub.

SAMPLE

Body:

[{
        "ProductCode": "1020872",
        "Name": "Lanolin",
        "Description": "Breast%20Feeding%20Ointment",
        "GenericHSCode": "",
        "OriginCountryCode": "",
        "Weight": "1.0000",
        "Height": null,
        "Length": null,
        "Volume": "60",
        "ImageURL": "\/a\/3\/a3c9ef_ece3bec0467310603bce72e9a58e33d3.jpg",
        "ImageHeight": "",
        "ImageWidth": "",
        "ListPrice": "25.0000",
        "OriginalListPrice": "17.7000",
        "SalePrice": "15.0000",
        "OriginalSalePrice": "17.7000",
        "VATRateType": {
            "VATRateTypeCode": 1,
            "Name": "Low",
            "Rate": "18.0000"
        },
        "Brand": {
            "BrandCode": "7",
            "Name": "Brand2"
        },
        "Categories": [{
                "CategoryCode": "3",
                "Name": "Maternity"
            }
        ],
        "DeliveryQuantity": 1
    }
]

URL:

https://{server_name}/Order/UpdateOrderDispatch?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd&orderStatus={"OrderId":"testID","OrderStatus":{"OrderStatusCode":"DEL_12","Name":"Delayed"},"OrderStatusReason":{"OrderStatusReasonCode":"1009","Name":"InventoryMissing"},"ConfirmationNumber":"1234","TrackingServiceName":"Fedex","TrackingServiceSite":"http://www.fedex.com","TrackingNumber":"1234","TrackingURL":"http://www.fedex.com/Track?id=1234","DeliveryReferenceNumber":"abc123"}&parcelsList={"ParcelCode":"12345-1"}&parcelsList={"ParcelCode":"12345-2"}

ACCEPTS

List <Product> productsList
List of Product objects (specified in the request body)
OrderStatusDetails orderStatus
Status details to update for the order specified
List <Parcel> parcelsList (optional)
List of Parcel objects for this order’s shipment to the Global‑e hub

RETURNS

ResponseInfo class

UpdateOrderDispatchV2

UpdateOrderDispatchV2 (UpdateOrderDispatchRequest request)

Updates the order status and Delivery Quantities for the products, as well as the Merchant’s internal Delivery Reference Number, if applicable. You can also add tracking information on each parcel or on the entire order. Optionally, you can include the list of Parcels with Products for this order shipment to the Global-e hub, exceptions to report on out-of-stock items, and items that will be shipped later on.

SAMPLE

Body:

{
    "OrderId": "GE123874638GB",
    "MerchantOrderID": "100018322",
    "DeliveryReferenceNumber": "123756483",
    "IsCompleted": false,
    "Parcels": [{
            "ParcelCode": "123454321",
            "Products": [{
                    "DeliveryQuantity": 1,
                    "CartItemId": "12365",
                    "ProductCode": "121212"
                }, {
                    "DeliveryQuantity": 2,
                    "CartItemId": "12376",
                    "ProductCode": "131313"
                }
            ],
            "TrackingDetails": {
                "TrackingNumber": "111111122666"
            }
        }
    ],
    "Exceptions": [{
            "CartItemId": "12366",
            "ProductCode": "121213",
            "ExceptionType": 1
        }, {
            "CartItemId": "12367",
            "SKU": "SKU121214",
            "ExceptionType": 2,
            "ExpectedFulfilmentDate": "2018-01-18"
        }
    ],
    "TrackingDetails": {
        "TrackingNumber": "111111122666"
    }
}

URL:

https://{server_name}/Order/UpdateOrderDispatchV2?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

ACCEPTS

UpdateOrderDispatchRequest request

Full post data including OrderId, Exceptions, and Parcels with Products for the call.

RETURNS

ResponseInfo class

UpdateOrderProducts

The UpdateOrderProducts API lets you update the order product's metadata and country of origin after the order has been created.

AUTHENTICATION

Add your MerchantGUID as part of the URL.

Make sure to use the appropriate MerchantGUID, depending on the Global‑e integration environment used for development or production purposes.

Optional: Global‑e supports JWT. This requires configuration on the Global‑e side.

URL

POST https://{server_name}/Order/UpdateOrderProducts?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd

REQUEST STRUCTURE

Field	Type	Mandatory	Description
`OrderId`	String	Yes	Global‑e unique identifier or merchant unique identifier of the order that requires updating.
`MetaDataUpdateType`	String	Yes	The type of metadata update. Currently, `Merge` is the only allowed value. `Merge` is used to add or update existing metadata. Metadata that is not included in the request remains unchanged.
`Products`	List `< Product>`	Yes	The list of products included in the order that requires updating.

Product

The product details and attributes. The following provides a partial structure dedicated to the update order.

Product class

Field	Type	Mandatory	Description
`ProductCode`	String	Conditional	The SKU code used to identify the product on the Merchant’s site. Conditional: Either the `ProductCode` or the `CartItemID` must be supplied.
`CartItemId`	String	Conditional	The identifier of the cart item on the Merchant’s site Conditional: Either the `ProductCode` or the `CartItemID` must be supplied.
`OriginCountryCode`	String	No (optional)	2-char ISO country code of the product’s country of Origin. The Merchant’s country will be assumed if not specified.
`MetaData`	ProductMetaData	No (optional)	Used to hold additional product data such as customer-defined product attributes. Important: The attributes provided in ProductMetaData are added when the attribute key does not exist, or the attributes are updated with new values when attributes with the same keys already exist

ProductMetaData

ProductMetaData class

Field	Type	Mandatory	Description
`Attributes`	List<CustomProductAttribute>	No (optional)	Customer-defined product attributes that allow for personalisation of the product if supported by the merchant’s site (e.g. engraving).

CustomProductAttribute

CustomProductAttribute class

Field	Type	Mandatory	Description
`AttributeKey`	String	No	The custom product attribute name used for product personalization by the end customer (e.g. engraving).
`AttributeValue`	String	No	The custom product attribute value used for product personalization by the end customer (e.g. engraving).

ACCEPTS

UpdateOrderProductsRequest class

string OrderId
Global‑e unique identifier or Merchant unique identifier of the order that requires updating.
List <Product> Products
The list of products that require updating.
string MetaDataUpdateType
The type of metadata update. Must be set to "Merge".

RESPONSE

If there is an update, the API returns a successful response.

ResponseInfo class

bool Success
Indicates if the respective API method call was successful. Success property value may be only TRUE. Otherwise, ErrorInfo will be returned instead (like in any API method, as described above in this document).
string Reason (optional) Text that optionally describes the reason for Success status.
If there is no update, the API returns a failure. See the Error Code section below.

ERROR CODE

When providing an invalid or non-existent value, the Global-e returns an “ErrorInfo” with an appropriate error message.

Code	Error	Description
D001	`Orderid %OrderId%` not found.	The provided order ID does not exist
D002	`CartItemId %CartItemId%` not found	The provided cart item ID does not exist in this order
D003	`ProductCode %ProductCode%` not found	The provided product code does not exist in this order
D004	`OriginCountryCode %OriginCountryCode%` is invalid	The provided origin country code does not exist in the system
D005	`ProductMetaData %key%` cannot have an empty value	The provided value for product meta-data is empty or null

UpdateOrderStatus

UpdateOrderStatus ( OrderStatusDetails orderStatus)

The method sends order status updates from the Merchant’s site to Global-e whenever a status is changed (for example, when the order fulfilmentfulfillment or shipping notifications are triggered).

Important

When the request is made by the merchant to cancel the order, the merchant must make sure to add the cancellation reason so that Global-e can notify the customer.

SAMPLE

URL:

https://{server_name}/Order/UpdateOrderStatus?merchantGUID=abcdabcd-abcd-abcd-abcd-abcdabcdabcd&orderStatus={"OrderId":"testID","OrderStatus":{"OrderStatusCode":"DEL_12","Name":"Delayed"},"OrderStatusReason":{"OrderStatusReasonCode":"1009","Name":"InventoryMissing"},"ConfirmationNumber":"1234","TrackingServiceName":"Fedex","TrackingServiceSite":"http://www.fedex.com","TrackingNumber":"1234","TrackingURL":"http://www.fedex.com/Track?id=1234"}

ACCEPTS

OrderStatusDetails orderStatus

Status details to update for the order specified

RETURNS

Responseinfo class

Documentation Portal

Order Methods

CreateOrderRefund

DispatchConsolidatedShipment

DispatchOrders

GetOrdersDetails

GetShippingDocuments

UpdateOrderDispatch

Note

UpdateOrderDispatchV2

UpdateOrderProducts

UpdateOrderStatus

Important