Location Hub API overview (beta)

Before you begin

Check out our general API overview to make sure you're ready to get started with specific endpoints.

🚧

Beta

The Location Hub API is in beta. Send the revision: 2026-10-15.pre header to call these endpoints. Endpoints may change before general availability.

Use the Location Hub API to manage physical locations and in-person events, and the segments that target profiles near them.

Use cases

Here are example use cases supported by the Location Hub API:

• Sync your store list from a point-of-sale or store locator system.
• Create a pop-up event and a segment of profiles within 10 miles of it.
• Show which segments target a given store.

Required scopes

Resources

Locations and live events are separate resources. Requesting a live event ID at /api/locations/{id}, or a location ID at /api/location-live-events/{id}, returns a 404.

Create a location

A location must be placeable on a map. Include at least one of the following:

• address1
• city and region
• latitude and longitude

Klaviyo geocodes the address and fills in the fields it can resolve. Until geocoding finishes, latitude and longitude may be null; check geocode_status, which is pending, queued, successful, or failed. A location that fails geocoding can't be used for proximity segmentation.

curl --request POST \
  --url 'https://a.klaviyo.com/api/locations' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'content-type: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre' \
  --data '
{
  "data": {
    "type": "location",
    "attributes": {
      "name": "Klaviyo Boston",
      "address1": "125 Summer St",
      "address2": "Floor 6",
      "city": "Boston",
      "region": "MA",
      "zip": "02110",
      "country": "US",
      "type_label": "Flagship store",
      "phone_number": "+16175551234"
    }
  }
}
'

Update a location or live event

PATCH changes only the fields you send:

• Omit a field to leave it unchanged.
• Send null to clear an optional field, such as description, url, or phone_number.
• name, the address fields (address1, address2, city, region, zip, country), latitude, and longitude can't be set to null, and neither can starts_at on a live event. Sending null for any of them returns a 400.
• Send latitude and longitude together.

Sending any address or coordinate field re-geocodes the record, which resets geocode_status.

curl --request PATCH \
  --url 'https://a.klaviyo.com/api/locations/01HQ8V5X9K2M4N6P8R0T2W4Y6A' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'content-type: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre' \
  --data '
{
  "data": {
    "type": "location",
    "id": "01HQ8V5X9K2M4N6P8R0T2W4Y6A",
    "attributes": {
      "phone_number": "+16175559876",
      "description": null
    }
  }
}
'

Create a live event

Live events follow the same placement and geocoding rules as locations, and also require starts_at. timezone is read-only and is resolved from the event's address.

Use the host-locations relationship to link the locations hosting the event. On PATCH, host-locations replaces the full list; send an empty data array to remove all host locations.

curl --request POST \
  --url 'https://a.klaviyo.com/api/location-live-events' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'content-type: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre' \
  --data '
{
  "data": {
    "type": "location-live-event",
    "attributes": {
      "name": "Summer Pop-Up",
      "starts_at": "2026-07-01T18:00:00Z",
      "ends_at": "2026-07-01T22:00:00Z",
      "address1": "125 Summer St",
      "city": "Boston",
      "region": "MA"
    },
    "relationships": {
      "host-locations": {
        "data": [
          {
            "type": "location",
            "id": "01HQ8V5X9K2M4N6P8R0T2W4Y6A"
          }
        ]
      }
    }
  }
}
'

Target profiles near a location

To create a segment of profiles near a location and link it:

1. Call POST /api/proximity-segment-definitions to get a suggested name and definition. radius defaults to 30 and unit to miles (or kilometers). The location needs a zip and country.
2. Call Create Segment (POST /api/segments) with the returned name and definition.
3. Call POST /api/locations/{id}/relationships/segments with the new segment's ID.

Query a proximity segment definition

curl --request POST \
  --url 'https://a.klaviyo.com/api/proximity-segment-definitions' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'content-type: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre' \
  --data '
{
  "data": {
    "type": "proximity-segment-definition",
    "attributes": {
      "radius": 10,
      "unit": "miles"
    },
    "relationships": {
      "location": {
        "data": {
          "type": "location",
          "id": "01HQ8V5X9K2M4N6P8R0T2W4Y6A"
        }
      }
    }
  }
}
'

Link segments to a location

curl --request POST \
  --url 'https://a.klaviyo.com/api/locations/01HQ8V5X9K2M4N6P8R0T2W4Y6A/relationships/segments' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'content-type: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre' \
  --data '
{
  "data": [
    {
      "type": "segment",
      "id": "UUvyMc"
    }
  ]
}
'

Linking and unlinking work as follows:

• A segment targets at most one location. Linking a segment that's already linked to another location moves it to this one.
• Link and unlink are idempotent. Segments already linked are left alone, and unlinking a segment that isn't linked is ignored.
• Unlinking doesn't delete the segment.
• A location can have up to 20 linked segments. Each request accepts 1 to 100 segment IDs.
• Segment endpoints only accept location IDs. A live event ID returns a 404.

Get a location's segments

GET /api/locations/{id}/segments returns each linked segment's name, definition, and linked_at. Segment details are cached for up to five minutes.

To get only the segment IDs and a count, use ?include=segments on Get Location or Get Live Event (not supported on list endpoints).

curl --request GET \
  --url 'https://a.klaviyo.com/api/locations/01HQ8V5X9K2M4N6P8R0T2W4Y6A?include=segments' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre'

Pagination and sorting

List endpoints use cursor pagination. Pass page[size] (default 25, maximum 100) and follow the links.next URL for the next page.

Get Locations and Get Live Events sort newest first by default. Pass sort with name, created_at, or updated_at (and starts_at for live events), prefixed with - for descending order. Changing sort while paginating returns a 400; restart from the first page instead.

curl --request GET \
  --url 'https://a.klaviyo.com/api/locations?sort=name&page[size]=50' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/vnd.api+json' \
  --header 'revision: 2026-10-15.pre'

Limitations

• No filtering. List endpoints support sorting and pagination only.
• No hours field. Opening hours aren't exposed yet.

Additional resources

• Segments API overview
• Rate limits, status codes, and errors