Escrow Offer Documentation

What is Escrow Offer?

Escrow Offer is the easiest way to introduce the power of price negotiation for escrow transactions to your website, online store, mobile app or classifieds site. With a single call to the Escrow Offer API, you can set up a negotiation between a seller and one or more prospective buyers. It works like this:

• A buyer browsing on an integrated application sees an item they would like to purchase. However, they don't feel comfortable making the purchase outright, as they would like to negotiate with the seller.
• The buyer clicks the listing's Make Offer button, which has been integrated with the Escrow Offer API. The API sets up a negotiation between the prospective buyer and seller. The buyer is redirected to a form to make their initial offer to the seller.
• Once an offer is made, the seller is informed via email. Both parties may view the negotiation history on the offer management page as well as accept, counter, or reject any offer or counter offer made to them.
• Multiple buyers may negotiate with a seller on a given listing during this time. When a seller accepts an offer, the buyer is guided through the payment process. When payment is secured by Escrow.com for the listing, the negotiation is formally closed.

Learn more about Escrow Offer and its benefits here.

Calling the Escrow Offer API

The call to the Escrow Offer API specifies how the transaction should be configured. This includes details about the item(s) being transacted, the buyer, the seller, the terms of the transaction, and optionally a broker for marketplace or commission scenarios.

Special attributes can be added to the call to enable the following: Offers made above accept_amount (if specified) will automatically be accepted. Offers made below reject_amount (if specified) will be automatically rejected. If include_buy_now is not set to false then buyers will be able to make an offer which will be automatically accepted at the price specified by the transaction.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
curl "https://api.escrow.com/integration/2018-08-01/auction" \
    -X POST \
    -u "email-address:your-api-key" \
    -H "Content-Type: application/json" \
    -d '
    {
        "transaction": {
           "parties":[
              {
                "customer":"buyer_user",
                "role":"buyer",
                "agreed": true,
                "initiator": true
              },
              {
                "role": "seller",
                "customer": [email protected]",
                "agreed": true,
                "first_name": "John",
                "last_name": "Wick",
                "address": {
                  "line1": "1829 West Lane",
                  "line2": "Apartment 301020",
                  "city": "San Francisco",
                  "state": "CA",
                  "country": "US",
                  "post_code": "10203"
                },
                "phone_number": "8885118600"
                "date_of_birth": "1994-2-28",
            }
           ],
           "currency":"usd",
           "description":"2008 BMW 328xi",
           "listing_reference":"listing-xyz456",
           "items": [
                {
                    "title": "2008 BMW 328xi",
                    "description": "A great car for the snow",
                    "type": "motor_vehicle",
                    "inspection_period": 259200,
                    "quantity": 1,
                    "schedule": [
                        {
                            "amount": 5000.0,
                            "payer_customer": "buyer_user",
                            "beneficiary_customer": "[email protected]"
                        }
                    ],
                    "extra_attributes": {
                        "make": "BMW",
                        "model": "328xi",
                        "year": 2008
                    }
                }
            ]
        }
    }'

Example Response

1
2
3
4
5
{
    "make_offer_page": "https://www.escrow.com/offer?token=2d2afb9f-364f-4f9f-82a5-803344d60432&source=api",
    "offer_management_page": "https://www.escrow.com/offer-management?token=2d2afb9f-364f-4f9f-82a5-803344d60432&source=api",
    "token": "2d2afb9f-364f-4f9f-82a5-803344d60432"
}

make_offer_page attribute

The make_offer_page attribute contains the link to which the buyer should be redirected. The buyer will then be able to make an offer to the seller.

Prefilling of fields is also supported by appending extra queries to the url. Supported queries for prefilling fields are:

• email

offer_management_page attribute

The offer_management_page attribute contains the link to which both the seller and any buyers may be redirected. Those users can then participate and track the negotiation.

token attribute

The token attribute contains the Escrow.com negotiation identifier that was created by the call to the Escrow Offer API.

For help on making API calls and configuring transactions, please review the links below. The Webhooks section may be of interest, as it will allow you to receive notifications in real-time to any transactions created as a result of a successful Escrow Offer negotiation.