尋找地點，並封存您不再管理的地點
依關鍵字搜尋、批次查找門市代碼與 id 對應的地點、排程在計費週期結束時封存已歇業的分店，以及取消已排程的封存。
三個讀取端點可依不同的索引鍵尋找地點：自由文字搜尋、門市代碼查詢及 id 查詢。封存是一項排程寫入作業：地點會維持運作，直到目前的計費週期結束，之後便停止同步及計費。在此之前，您都可以取消封存。
1. 依關鍵字搜尋
GET /locations/search?query= 會將搜尋詞與名稱、街道地址、城市及商店 id 進行比對，並傳回游標連線：包含 pageInfo.endCursor 的 edges[].node，使用 first 和 after 進行分頁。省略 query 即可分頁瀏覽整個帳戶的地點。
curl "https://listingsapi.com/api/v4/locations/search?query=Acme&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "searchLocations": { "edges": [ { "cursor": "TG9jYXRpb246MTgwMDI4OQ==", "node": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "storeId": "ACME-NYC-001", "approved": "APPROVED", "archived": false, "archivalScheduledAt": null } } ], "pageInfo": { "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "hasNextPage": false, "total": 1 } } }}edges 陣列為空表示沒有符合項目；當您不確定商店是否已存在時，應在建立前執行這項檢查。兩個 SDK 都接受 fields，將比對範圍限制為僅 name 或 store_id。
2. 依門市代碼查詢
如果您的系統使用自訂門市代碼作為地點的索引鍵，可使用 GET /locations-by-store-codes 直接查找對應的地點。storeCodes 參數是經過 URL 編碼的 JSON 陣列。沒有符合項目的代碼不會出現在結果中。
curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME-NYC-001","ACME-NYC-002"]' \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "getLocationsByStoreCodes": [ { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "storeId": "ACME-NYC-001", "name": "Acme Kitchen", "archived": false } ] }}3. 批次取得 id 對應的完整記錄
當您已持有來自自身資料庫或 webhook 承載資料的 base64 id 時，GET /locations-by-ids 可透過一次呼叫傳回所有這些 id 的完整記錄。已封存的地點也能查得，因此請讀取 archived 和 archivedAt 加以區分。未知的 id 會直接略過且不另行通知；請比對數量。
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "getLocationsByIds": [ { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "archived": false, "archivedAt": null }, { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "name": "Acme Kitchen Brooklyn", "archived": false, "archivedAt": null } ] }}若要在伺服器端篩選整個帳戶中的部分地點，例如依核准狀態篩選，GET /locations 也接受經過 JSON 編碼的 filter 參數。請參閱列出所有地點。
4. 封存您不再管理的地點
POST /locations/archive 接受 input.locationIds，並為每個地點傳回一筆 result 項目。封存會排程執行，並非立即生效：每個地點會進入 ARCHIVE_SCHEDULED，持續同步直到目前的計費週期結束，並在產生下一張帳單時封存。自此，地點便停止同步至發布平台，也停止計費。
curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="] }}'{ "data": { "archiveLocations": { "errors": null, "result": [ { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }, { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null } ] } }}請讀取每筆項目的 success：單一無效的 id 不會阻擋批次中的其他項目。封存已排程時，清單與搜尋結果中的地點會設定 archivalScheduledAt 欄位。已封存的地點必須重新啟用後才能更新。如果已設定 webhook，便會觸發 profile.deleted 事件；這是軟刪除，且不提供硬刪除。
5. 取消已排程的封存
在週期結束前，使用相同的 id 呼叫 POST /locations/cancel_archive，即可將這些地點恢復為 ACTIVE，並持續計費。一旦地點已完成封存，此呼叫便會為該地點傳回 404。取消封存不會發出 webhook 事件。
curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'{ "data": { "cancelLocationsArchive": { "errors": null, "result": [ { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null } ] } }}兩個 SDK 都需要兩個額外的位置引數，分別是選取類型與 changedBy 識別碼，並會將這些引數與 locationIds 一併傳送。REST 請求主體只需要 id。