Notify order refund (Global-e to Merchant)

Notify the merchant of a Global-e initiated refund

curl --request POST \
  --url https://{merchant_site_domain}/order-refund-url \
  --header 'Content-Type: application/json' \
  --data '
{
  "MerchantGUID": "<MERCHANT_GUID>",
  "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
}
'

import requests

url = "https://{merchant_site_domain}/order-refund-url"

payload = {
    "MerchantGUID": "<MERCHANT_GUID>",
    "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": None
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    MerchantGUID: '<MERCHANT_GUID>',
    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
  })
};

fetch('https://{merchant_site_domain}/order-refund-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{merchant_site_domain}/order-refund-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'MerchantGUID' => '<MERCHANT_GUID>',
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{merchant_site_domain}/order-refund-url"

	payload := strings.NewReader("{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{merchant_site_domain}/order-refund-url")
  .header("Content-Type", "application/json")
  .body("{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{merchant_site_domain}/order-refund-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}"

response = http.request(request)
puts response.read_body

{
  "Description": "<string>",
  "ErrorCode": "<string>",
  "InternalOrderId": "<string>",
  "Message": "<string>",
  "OrderId": "<string>",
  "PaymentAmount": "<string>",
  "PaymentCurrencyCode": "<string>",
  "StatusCode": "<string>",
  "Success": true
}

POST

order-refund-url

Notify the merchant of a Global-e initiated refund

curl --request POST \
  --url https://{merchant_site_domain}/order-refund-url \
  --header 'Content-Type: application/json' \
  --data '
{
  "MerchantGUID": "<MERCHANT_GUID>",
  "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
}
'

import requests

url = "https://{merchant_site_domain}/order-refund-url"

payload = {
    "MerchantGUID": "<MERCHANT_GUID>",
    "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": None
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    MerchantGUID: '<MERCHANT_GUID>',
    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
  })
};

fetch('https://{merchant_site_domain}/order-refund-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{merchant_site_domain}/order-refund-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'MerchantGUID' => '<MERCHANT_GUID>',
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{merchant_site_domain}/order-refund-url"

	payload := strings.NewReader("{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{merchant_site_domain}/order-refund-url")
  .header("Content-Type", "application/json")
  .body("{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{merchant_site_domain}/order-refund-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"MerchantGUID\": \"<MERCHANT_GUID>\",\n  \"MerchantOrderId\": \"14123332\",\n  \"Products\": [\n    {\n      \"CartItemId\": 12365,\n      \"RefundQuantity\": \"3\",\n      \"OriginalRefundAmount\": \"114.5300\",\n      \"RefundAmount\": \"170.1000\",\n      \"RefundReason\": {\n        \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n        \"Name\": \"Damaged Item\"\n      },\n      \"RefundComments\": \"Fully refunded order\"\n    }\n  ],\n  \"OrderId\": \"GE69488861GB\",\n  \"RefundId\": 789,\n  \"RMANumber\": 6543,\n  \"CurrencyCode\": \"CAD\",\n  \"OriginalCurrencyCode\": \"USD\",\n  \"TotalRefundAmount\": \"170.10\",\n  \"RefundReason\": {\n    \"OrderRefundReasonCode\": \"DAMAGED-ITEM-CODE\",\n    \"Name\": \"Damaged Item\"\n  },\n  \"RefundComments\": \"Fully refunded order\",\n  \"OriginalTotalRefundAmount\": \"114.53\",\n  \"ServiceGestureAmount\": \"0.00\",\n  \"WebStoreCode\": null\n}"

response = http.request(request)
puts response.read_body

{
  "Description": "<string>",
  "ErrorCode": "<string>",
  "InternalOrderId": "<string>",
  "Message": "<string>",
  "OrderId": "<string>",
  "PaymentAmount": "<string>",
  "PaymentCurrencyCode": "<string>",
  "StatusCode": "<string>",
  "Success": true
}

Part of the Refunds Notifications (Global-e to Merchant) integration guide — see it for when and how to use this endpoint.

Some values in the payload are encoded and must be decoded by the merchant — for example URLs, addresses, emails, and phone numbers.

Body

application/json

Contains information about order refunds.

OrderId

string

required

Global-e order unique identifier.

OriginalTotalRefundAmount

string

required

The refund amount in the original Merchant currency including the local Merchant's VAT (currency is specified in CurrencyCode property of the respective Merchant.Order).

TotalRefundAmount

string

required

The total refund amount in the end customer's currency used for this order's payment (currency is specified in InternationalDetails.CurrencyCode property for the respective Merchant.Order).

Components

Merchant.RefundComponent · object[]

The list of RefundComponent objects for this order refund.

Show child attributes

MerchantGUID

string

Unique identifier of the Merchant on Global-e.

MerchantOrderId

string

Order unique identifier on the Merchant's site returned from a previous call to the SendOrderToMerchant method for this order.

MerchantRMANumber

string

The Merchant's Returned Merchandize Authorization Number

Products

Merchant.RefundProduct · object[]

List of RefundProduct objects for this order refund.

Show child attributes

RefundComments

string

Comments for the order refund

RefundReason

Merchant.OrderRefundReason · object

Reason for the order refund

Show child attributes

RMANumber

string

The RMA number taken from the related Return.

ServiceGestureAmount

string

The "Service gesture" amount in the customer's currency is included in the TotalRefundAmount. "Service gesture" denotes any additional refund granted to the user, on top of the refund related to other components.

WebStoreCode

string | null

Code used on the Merchant's side to identify the web store, as specified in the WebStoreCode argument for the SendCart method for the cart converted to this order on Global-e.

RefundId

string

CurrencyCode

string

OriginalCurrencyCode

string

Response

200 - application/json

The merchant returns a Merchant.ResponseInfo object. Some response values are encoded and require the merchant to decode them, for example URLs, addresses, emails, and phone numbers.

Provides response data regarding the API call.

Description

string

Optional response description. In case of an error, this property indicates the error message description.

ErrorCode

string

Error code to be returned when an error occurs.

InternalOrderId

string

Order unique identifier on the Merchant's site

Message

string

Optional response message. In case of an error, this property indicates the error message text.

OrderId

string

Order identifier on the Merchant's site used for display and reporting purposes only. Unlike the InternalOrderId, this identifier is not necessarily unique over time, as the Merchant's site may potentially reuse it (for example after deleting the old order having the same OrderId).

PaymentAmount

string

The total payment amount in PaymentCurrency charged for the order (if payment was processed in the respective API method call).

PaymentCurrencyCode

string

3-char ISO currency code for the order (if payment was processed in the respective API method call).

StatusCode

string

Code denoting the order status on the Merchant's site (to be mapped on the Global-e side).

Success

boolean

Indicates if the call has succeeded. TRUE - Call succeeded. FALSE - Denotes an error or failure.

Overview

Shipping

Orders

Returns

Gift Cards

Checkout

Pricing

Browsing & Catalog

Subscriptions

Webhooks

Shared Objects

Notify order refund (Global-e to Merchant)

Body

Response