Place Action Links

Manage a location's Google action buttons (ordering, delivery, takeout, reservation, appointment) through the listingsAPI.

Place action links are the action buttons Google shows on a business's profile: Order online, Get delivery, Reserve a table, Book an appointment, and so on. listingsAPI manages them as part of a location, so you set them through the same create and update endpoints you already use, and read them back on every location read endpoint.

The `placeActionLinks` field

Both create and update accept a placeActionLinks array on input. Each element:

Field	Type	Required	Description
`placeActionType`	enum	yes	One of the valid types below.
`uri`	string	yes	Destination URL.
`isPreferred`	boolean	no	Marks this link preferred for its type. At most one preferred per type.
`action`	string	no	`add` (the default) or `delete`. Only used on update.
`name`	string	no	The link's identifier, returned by the read endpoints once the link has synced to Google. Optional on write; include it when available to target a specific saved link most accurately.

Valid placeActionType values:

APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATION
FOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

How a link is matched (for edit / delete): by name if present, otherwise by placeActionType + uri. Include name when you have it (from a read) for the most accurate match. A newly added link that hasn't synced to Google yet has no name, so it is matched by placeActionType + uri.

Actions

The write model is append/upsert, not replace. On update, only the links you reference are affected; links you don't include are left unchanged.

Action	Purpose	Match
`add`	Add a new link, or update a saved link's `uri` / `isPreferred` in place.	`name` if present, else `placeActionType` + `uri`
`delete`	Remove a saved link and queue its removal from Google.	`name` if present, else `placeActionType` + `uri`

To change a link's URL, remove the old one and add the new one in the same request (see Change a link's URL).

Recommended flows

There are two supported ways a location's place action links get populated and kept in sync with Google.

Flow 1: create in Google first, then connect

The merchant sets up the place action links directly in their Google Business Profile.
That Google Business Profile location is connected to listingsAPI.
On connect, listingsAPI pulls the live links from Google into the location's managed set. You don't need to re-enter them through the API.

Flow 2: create in listingsAPI first, then connect

Create the location in listingsAPI with its place action links (create a location), or add them later (update a location).
On connect to Google Business Profile, listingsAPI fetches the live links and merges them with the managed set:
- links that match cleanly join the managed set;
- anything Google has that can't be auto-merged (or that simply isn't in the managed set yet) is surfaced under discoveredPlaceActionLinks for you to review.
On every submission to Google, listingsAPI re-checks the live links. Any new link found directly in Google Business Profile that listingsAPI doesn't manage is added to discoveredPlaceActionLinks.

Discovered links

Discovered links are place action links that exist on the business's Google profile but aren't managed in listingsAPI. They are pulled in by the flows above (extra links found on connect, or new links found on a later submission) and are returned separately from your managed links, under discoveredPlaceActionLinks (same shape as placeActionLinks), by every read endpoint: list, by IDs, by store codes, and search.

{
  "id": "TG9jYXRpb246MTgwMTAyMQ==",
  "placeActionLinks": [ /* links you already manage */ ],
  "discoveredPlaceActionLinks": [
    {
      "placeActionType": "APPOINTMENT",
      "uri": "https://book.example.com",
      "isPreferred": false,
      "name": "locations/1944.../placeActionLinks/abc123",
      "providerType": "MERCHANT",
      "isEditable": true
    }
  ]
}

Adopt a discovered link

To start managing a discovered link, send it to update a location with action: "add", the same call as adding any link (identified by placeActionType + uri). Other links are untouched.

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "id": "<encoded-location-id>",
      "placeActionLinks": [
        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }
      ]
    }
  }'

After this the link appears under placeActionLinks and is removed from discoveredPlaceActionLinks. A discovered link you don't adopt simply stays listed (and drops off on its own if it later disappears from Google); no action is required.

Examples

Every update returns the location's full, current placeActionLinks set (reflecting the change). Right after a write, a link's name and submissionStatus are null; they populate once the link syncs to Google.

Add a link

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "id": "<encoded-location-id>",
      "placeActionLinks": [
        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }
      ]
    }
  }'

Change a link's URL

A URL change is a remove of the old link plus an add of the new one, in the same request. If the old link has synced to Google, include its name on the delete for the most accurate match; otherwise placeActionType + uri is used.

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "id": "<encoded-location-id>",
      "placeActionLinks": [
        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },
        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }
      ]
    }
  }'

To change only isPreferred (same URL), resend the link with action: "add" and the new value.

Remove a link

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "id": "<encoded-location-id>",
      "placeActionLinks": [
        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }
      ]
    }
  }'

Create a location with links

On create, every link is new, so action defaults to add.

curl -X POST 'https://listingsapi.com/api/v4/locations' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "name": "Acme Dental",
      "description": "<business description, minimum 200 characters>",
      "countryIso": "US",
      "city": "New York",
      "subCategoryId": 1432,
      "placeActionLinks": [
        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },
        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }
      ]
    }
  }'

Notes

At most one preferred link per type.
A link's submissionStatus reflects the last sync to Google (success, failed, and so on), with a human-readable submissionMessage.
Google applies place action links only to verified locations.