A customer needs to have at least 1 address stored on their account to place an order. All requests require an access token in the Authorization HTTP header. Addresses are verified against the US Postal Service data..

Create Location

HTTP Request

POST /customer/location

Request Body

{   
    "street"    : "235 Park Ave S",
    "unit_number"     : "Floor 5",
    "city"      : "New York",
    "state"     : "NY",
    "phone"     : "555-555-5555",
    "zip_code"  : "10003",
    "company"   : "Delivery.com",  
    "cross_streets" : "85th and 1st",
}
Property Name Type Notes
Required Properties
street String Must be >= 5 characters.
city String Must be >= 2 characters.
state String Must be exactly 2 characters.
zip_code String Must be exactly 5 characters.
phone String The customer’s phone number at this location. Must be 10-12 characters.
Optional Properties
unit_number String Used for apartment number, suite, floor, etc.
company String Sometimes there are multiple businesses on the same floor of a building. This is useful for the merchant in that case.
cross_streets String Nearest major cross streets.

Success Response

HTTP 200 OK
If successful, the API returns you the location_id of the address you just inserted. This is required for the checkout API.

{
    "message": [],
    "location": {
        "cross_streets": "Fulton Street",
        "company": null,
        "phone": "555-555-5555",
        "unit_number": null,
        "street": "199 WATER ST",
        "city": "NEW YORK",
        "state": "NY",
        "zip_code": "10038",
        "location_id": 1574911,
        "longitude": "-74.0042710304260300",
        "latitude": "40.7068885740958600"
    }
}

Bad Address Response

You receive this response when all your input is valid, but we couldn’t verify your address against the USPS database.
HTTP 400 Bad Request

{
    "message"   : [
        {	"code" 	: 	"bad_loc",
            "user_msg"	:	"We could not find the address that you submitted. Please double check all the fields and try again.",
            "dev_msg"	: 	"Address was not verified.",
        },
    ]
}

Invalid Request

You receive this response when at least 1 of your input fields doesn’t pass our validation rules.
HTTP 400 Bad Request

{
    "message"   : [
        {	"code" 	: 	"bad_street",
            "field"     :   "street",
            "user_msg"	:	"The street must be at least 2 characters.",
            "dev_msg"	: 	"The street must be at least 2 characters.",
        },
        {	"code" 	: 	"bad_city",
            "field"     :   "city",
            "user_msg"	:	"The city must be at least 2 characters.",
            "dev_msg"	: 	"The city must be at least 2 characters.",
        },
        {	"code" 	: 	"bad_state",
            "field"     :   "state",
            "user_msg"	:	"The state must be 2 characters.",
            "dev_msg"	: 	"The state must be 2 characters.",
        },
        {	"code" 	: 	"bad_zip_code",
            "field"     :   "zip_code",
            "user_msg"	:	"The zip code field must be 5 characters.",
            "dev_msg"	:   "The zip code field must be 5 characters.",
        },
        {	"code" 	: 	"bad_phone",
            "field"     :   "phone",
            "user_msg"	:	"The phone must be at least 10 characters."
            "dev_msg"	:   "The phone must be at least 10 characters."
        }
    ]
}

Update Location

HTTP Request

PUT /customer/location/{location_id}
Update location behaves similarly to Create Location except you have to pass the location_id as part of the URL and only the fields that need to be changed. In addition, there is one other possible response.

Request Body

{
  "unit_number": "Floor 3"
}

Success Response

HTTP 200 OK

{
    "message": [
        {
            "code": "loc_update_success",
            "user_msg": "Address was successfully updated.",
            "dev_msg": "Address was successfully updated."
        }
    ],
    "location": {
        "street": "199 WATER ST",
        "city": "NEW YORK",
        "state": "NY",
        "zip_code": "10038",
        "longitude": "-74.0042710304260300",
        "latitude": "40.7068885740958600",
        "location_id": "1574907",
        "phone": "555-555-5555",
        "cross_streets": "Fulton Street",
        "unit_number": "Floor 3",
        "company": "Delivery.com"
    }
}

Invalid Location Id

{
    "message"   : [
        {	"code" 	: 	"bad_loc_id",
            "user_msg"	:	"Sorry, but we weren't able to delete this address from your account.",
            "dev_msg"	: 	"Could no_cct find address for location id 8",
        },
    ]
}

Delete Location

HTTP Request

DELETE /customer/location/{location_id}
This endpoint returns a HTTP 200 if successful, or a HTTP 400 if an invalid location_id is passed.

Get Locations

HTTP Request

GET/customer/location/

Optional Parameters

Sometimes you have a user’s address (including coordinates) from the user’s search results, but you don’t know if that user already has that address on their account. You can filter your results to a certain location by passing coordinates in. This also means you don’t need to ask the user for extra info (like phone number) if it’s already on the location stored on their account.

Name Type Description
latitude Float latitude that you want to filter results by. Only used if passed with a longitude.
longitude Float longitude that you want to filter results by. Only used if passed with a latitude.

Success Response

HTTP 200 OK

{
    "message": [],
    "locations": [
        {
            "location_id": "952563",
            "street": "232 PARK AVE S",
            "city": "NEW YORK",
            "state": "NY",
            "phone": "555-555-5555",
            "zip_code": "10003",
            "cross_streets": "19th Street",
            "unit_number": "",
            "company": "",
            "longitude": "-73.9883770000000000",
            "latitude": "40.7375940000000000"
        },
        {
            "location_id": "992053",
            "street": "235 PARK S AVE",
            "city": "NEW YORK",
            "state": "NY",
            "phone": "555-555-5555",
            "zip_code": "10003",
            "cross_streets": "19th street",
            "unit_number": "floor 5",
            "company": "",
            "longitude": "-73.9879490000000000",
            "latitude": "40.7377100000000000"
        }
    ]
}
Property Type Description
locations Customer Location[] The locations on this customer’s account.