API Guide :: Shipping rejected items in a transaction

Shipping rejected items in a transaction

If a transaction's items have been rejected by the buyer, we will instruct the buyer to return the goods. Shipment can be both physical delivery and non physical delivery.

Physical delivery refers to items that are shipped via courier and can be tracked via a tracking number. Non physical delivery is for electronic items such as domain names. While these don't require a tracking number, we do accept other ways of determining that the seller has received the rejected goods. For example, with domain names we track the changes to the WHOIS information.

Marking all items as returned

Similarly to marking all items as shipped, marking a transaction and all of its items as returned is a simple patch request to the transaction endpoint with theaction attribute set toship_return. As with theship action,tracking_information may also be set.

If the API call is successful, it will return the updated transaction object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl "https://api.escrow.com/2017-09-01/transaction/29292" \
    -X PATCH \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
  "action": "ship_return",
  "shipping_information": {
    "tracking_information": {
      "carrier": "UPS",
      "tracking_id": "1Z999AA10123456784",
      "carrier_contact": "1-234-567-8912"
    }
  }
}'

Marking domain name items as returned

The ship return endpoint is also used to mark a domain name as transferred in return. For domains, you must indicate the authorization type you used to transfer the domain. The allowed values for authorization_type arepush, authorization_code orusername_password.

1
2
3
4
5
6
7
8
9
10
11
curl "https://api.escrow.com/2017-09-01/transaction/29292" \
    -X PATCH \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
  "action": "ship_return",
  "shipping_information": {
    "authorization_type": "push"
  }
}'

Marking individual items as returned

For milestone transactions, you must mark individual items on a transaction as returned. The request is similar to marking all of the items as returned on a transaction, however you perform the patch request on the item subresource of the transaction.

If the API call is successful, it will return the updated transaction object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl "https://api.escrow.com/2017-09-01/transaction/29292/item/12345" \
    -X PATCH \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
{
  "action": "ship_return",
  "shipping_information": {
    "tracking_information": {
      "carrier": "UPS",
      "tracking_id": "1Z999AA10123456784",
      "carrier_contact": "1-234-567-8912",
    },
  }
}'