/api/v4/locations/archiveArchive locations
Schedules one or more locations for archival at the end of the current billing cycle.
Parameters
Body
| Name | Type | Required | Description |
|---|---|---|---|
| input.locationIds | array of strings | required | Base64-encoded location node IDs to archive. |
| input.clientMutationId | string | optional | Optional 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==" ] }}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.
Status values in the response:
ARCHIVE_SCHEDULED: queued for archival at end of the billing cycleARCHIVED: 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": [ "TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA==" ] } }'