Locations

Create or update a location

Changed on

Adds a location to your program, or updates one already in it.

An id updates that location; failing that a known external_id does; failing both, the address is matched against locations already known to Ekho and a new one is created only if nothing matches. Sending the same external_id again updates rather than conflicts, so a nightly full sync is safe to run.

Neither identifier is required. Omit external_id and work off the id returned. Renaming an external_id means sending id alongside the new value.

Adding a location needs name and address. An update, by id or by a known external_id, may omit either and keeps what is stored. A name on an update sets what your program calls the location and takes effect at checkout. An address naming the same building is accepted however it is spelled. One naming a different building moves the location when Ekho created it through this API for your program alone and the new address is in the same state; otherwise it returns 409 for Ekho to review, and nothing is changed.

A new external_id whose address matches a location your program already holds under another external_id returns 409 rather than taking that location over. Update it by its id instead. Prices are never sent or returned, and each service is charged at your program's own rate.

post/locations

Request

  • Base URL: https://api.ekho.com
  • URL: https://api.ekho.com/locations
  • Auth: HTTP bearer

Request body

idstring

An Ekho location id. Updates that location, and is required to change its external_id.

external_idstring

Your own id for this location. Unique within your program.

servicesstring[] required

The services this location performs for your program.

namestring

What your program calls this location. This is the name a buyer sees at checkout. Required to add a location; an update that omits it keeps the current name.

emailstring email

Business contact, not a person. Every write saves it for your program and reads return it as you sent it; an update that omits it keeps the last value.

phonestring

Business contact, not a person. Every write saves it for your program and reads return it as you sent it; an update that omits it keeps the last value.

Example request

{
  "id": "svp_7Ye2kQp91LmXw4Za",
  "external_id": "APEX-4471",
  "name": "Apex Powersports of Charlotte",
  "address": {
    "address_line_one": "1100 Apex Commerce Dr",
    "address_line_two": "Suite 120",
    "city": "Charlotte",
    "state": "NC",
    "zip": "28217"
  },
  "email": "service@apexpowersports.example",
  "phone": "+17045550143"
}

Response

An existing location was updated.

Example response

{
  "data": {
    "id": "svp_7Ye2kQp91LmXw4Za",
    "external_id": "APEX-4471",
    "name": "Apex Powersports of Charlotte",
    "email": "service@apexpowersports.example",
    "phone": "+17045550143",
    "address": {
      "address_line_one": "1100 Apex Commerce Dr",
      "address_line_two": "Suite 120",
      "city": "Charlotte",
      "state": "NC",
      "zip": "28217",
      "lat": 35.2271,
      "lng": -80.8431
    }
  }
}

Changes

  • c83d76f6a847Revision changes
    • info

      the request property became optional

    • info

      the request property became optional

  • c4f268c2d91bRevision changes
    • breaking

      removed the enum value delivery of the request property /

    • warning

      removed the request property

    • warning

      added the new last_leg_delivery enum value to the // response property for the response status

    • warning

      added the new last_leg_delivery enum value to the // response property for the response status

    • info

      added the new last_leg_delivery enum value to the request property /

    • info

      removed the delivery enum value from the // response property for the response status

    • info

      removed the delivery enum value from the // response property for the response status