listingsAPIlistingsAPI
Get API keySign in
POST/api/v4/locations/archive

Archive locations

Schedules one or more locations for archival at the end of the current billing cycle.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

NameTypeRequiredDescription
input.locationIdsarray of stringsrequiredBase64-encoded location node IDs to archive.
input.reasonstringoptionalOptional free-text reason recorded with the archival.
input.clientMutationIdstringoptionalOptional idempotency/echo token returned unchanged in the response.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

{
  "input": {
    "locationIds": [
      "TG9jYXRpb246MTgwMDI4OQ==",
      "TG9jYXRpb246MTgwMDI5MA=="
    ],
    "reason": "Franchise closed this branch"
  }
}

Responses

200Locations scheduled for archival. Returns per-location status.
{
  "data": {
    "archiveLocations": {
      "clientMutationId": null,
      "bulkEditTaskId": null,
      "errors": null,
      "success": null,
      "result": [
        {
          "locationId": "TG9jYXRpb246MTgwMDI4OQ==",
          "status": "ARCHIVE_SCHEDULED",
          "success": true,
          "errors": null
        },
        {
          "locationId": "TG9jYXRpb246MTgwMDI5MA==",
          "status": "ARCHIVE_SCHEDULED",
          "success": true,
          "errors": null
        }
      ]
    }
  }
}
400Bad request — invalid or empty `locationIds`.
401Unauthenticated — missing or invalid API key.
403Forbidden — insufficient permissions to archive.

Archives one or more locations. Archiving is not immediate: each location is put into ARCHIVE_SCHEDULED and stays live until the end of the current billing cycle. When the next invoice is generated the location is fully archived and billing for it stops.

Use case — offboard closed branches at cycle end. When a franchise permanently closes several stores, submit their base64 IDs in one call so billing lapses at the next invoice rather than mid-cycle. Inspect result[] in the response: each entry reports the status and a success flag for that specific location, so a partial failure (one bad ID) does not block the rest of the batch. Record the optional reason for your own audit trail.

Status values in the response:

  • ARCHIVE_SCHEDULED — queued for archival at end of the billing cycle
  • ARCHIVED — already archived

Reversal: to undo a still-scheduled archival before the cycle closes, call cancel scheduled archival with the same IDs. Archived locations cannot be updated until they are reactivated.

curl -X POST 'https://listingsapi.com/api/v4/locations/archive' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input.locationIds": "<input.locationIds>",
    "input.reason": "<input.reason>",
    "input.clientMutationId": "<input.clientMutationId>"
  }'
Run in playground