Skip to main content

Locations

Locations API provides merchant profiles a way to add an address for their physical or mobile businesses to the merchant directory.

info

Customers will be able to search for businesses on a map near their current location via geolocation.

Saving a Location​

An approved merchant profile can add their location to the directory with the following.

A location can be of PHYSICAL or MOBILE type indicating a storefront or a moving business such as a food truck.

It can also be ACTIVE or INACTIVE which allows you to set if location should be visible in the merchant directory.

Phone number and address validation are the same as for Profiles registration.

POST /profiles/:profile_id/locations
{
  "id": "d6cca60a-5ac1-466a-9021-de592e6b2a62",
  "name": "Downtown",
  "type": "PHYSICAL",
  "status": "ACTIVE",
  "website_url": "https://www.example.com",
  "business_name": "Happy Shoes",
  "business_type": "CLOTHING_RETAILER",
  "coordinates": {
    "latitude": 0.1,
    "longitude": 0.1
  },
  "address": {
    "street1": "1 Fake St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "USA"
  },
  "phone_number": "5555555555"
}

Response:

{
  "id": "d6cca60a-5ac1-466a-9021-de592e6b2a62",
  "created_dt": "2022-07-27T19:58:53.967295Z",
  "updated_dt": "2022-07-27T19:58:53.967304Z",
  "name": "Downtown",
  "type": "PHYSICAL",
  "status": "ACTIVE",
  "website_url": "https://www.example.com",
  "program_id": "e73fdc55-04b3-4931-aff2-db510f0eb252",
  "profile_id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
  "business_name": "Happy Shoes",
  "business_type": "CLOTHING_RETAILER",
  "business_hours": [],
  "coordinates": {
    "latitude": 0.1,
    "longitude": 0.1
  },
  "address": {
    "street1": "1 Fake St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "USA"
  },
  "phone_number": "5555555555"
}
info

A merchant profile can have up to 10 total locations.

Retrieve Locations​

You can retrieve all the locations associated with a merchant profile.

GET /profiles/:profile_id/locations

Response:

[
  {
    "id": "d6cca60a-5ac1-466a-9021-de592e6b2a62",
    "created_dt": "2022-07-27T19:58:53.967295Z",
    "updated_dt": "2022-07-27T19:58:53.967304Z",
    "name": "Downtown",
    "type": "PHYSICAL",
    "status": "ACTIVE",
    "website_url": "https://www.example.com",
    "program_id": "e73fdc55-04b3-4931-aff2-db510f0eb252",
    "profile_id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
    "business_name": "Happy Shoes",
    "business_type": "CLOTHING_RETAILER",
    "business_hours": [],
    "coordinates": {
      "latitude": 0.1,
      "longitude": 0.1
    },
    "address": {
      "street1": "1 Fake St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "USA"
    },
    "phone_number": "5555555555"
  }
]

Update a Location​

Location details can be updated. You need to provide at least one field in an update request.

PATCH /profiles/:profile_id/locations/:location_id
{
  "name": "Downtown",
  "type": "PHYSICAL",
  "status": "INACTIVE",
  "website_url": "https://www.example.com/changed",
  "business_name": "Happy Shoes 2",
  "business_type": "CLOTHING_RETAILER",
  "coordinates": {
    "latitude": -1.0,
    "longitude": 1.0
  },
  "address": {
    "street1": "1 Fake St",
    "street2": "Unit 2B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94108",
    "country": "USA"
  },
  "phone_number": "5555553333"
}

Response:

{
  "id": "d6cca60a-5ac1-466a-9021-de592e6b2a62",
  "created_dt": "2022-07-27T19:58:53.967295Z",
  "updated_dt": "2022-07-29T19:58:53.967304Z",
  "name": "Downtown",
  "type": "PHYSICAL",
  "status": "INACTIVE",
  "website_url": "https://www.example.com/changed",
  "program_id": "e73fdc55-04b3-4931-aff2-db510f0eb252",
  "profile_id": "423d2f77-697a-4f1e-8d7a-3b3362917d7c",
  "business_name": "Happy Shoes 2",
  "business_type": "CLOTHING_RETAILER",
  "business_hours": [],
  "coordinates": {
    "latitude": -1.0,
    "longitude": 1.0
  },
  "address": {
    "street1": "1 Fake St",
    "street2": "Unit 2B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94108",
    "country": "USA"
  },
  "phone_number": "5555553333"
}
info

The above example shows a location being changed to INACTIVE status. This will temporarily remove it from the merchant directory. You can change it back to ACTIVE with another update.

Delete a Location​

If you are no longer at a location, you should remove it from the merchant directory. 

DELETE /profiles/:profile_id/locations/:location_id

This will permanently remove this location from the system.