Skip to content
Metronome Docs

Handling Data Expiry

Having defined policies and sent telemetry to Metronome, the final steps in proper data handling are to delete unused PII once it has served all the many purposes your business needed it for. This is the purpose of expiry notices. You can read expiry notices for a specific date in the past or future, and when expiring data in the past, you inform Metronome that data has been correctly deleted on time. This marks the items as deleted and updates their data handling logs to prove your correct handling when you are audited for data privacy compliance.

Reading Expiry Notices

Section titled “Reading Expiry Notices”

To read expiry notices, we must create an instance of the DataExpiryApi client then call the getExpiryNotices method which has the following signature: getExpiryNotices(date). You can inspect dates in the past or future.

read-expiry-notices.ts
import { DataExpiryApi, ItemExpiry, SubItemExpiry, PendingExpiries, CompletedExpiries, ServerConfiguration, createConfiguration } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const expiryApiClient = new DataExpiryApi(clientConfig);


try {
    const response = await expiryApiClient.getExpiryNotices(new Date(2026, 5, 19));


    // Pending expiries may change with use before the reported date.  They are advisory only.
    console.log("There are %d pending expiries on %s", response.pending.length, response.expiryDate);
    response.pending.forEach( (notice: PendingExpiries) => {
        if(notice instanceof ItemExpiry) {
            console.log("Item %s might expire on %s", notice.itemId, response.expiryDate);
        } else if(notice instanceof SubItemExpiry) {
            console.log("Sub-item %s of item %s might expire on %s", notice.subItemId, notice.parentItemId, response.expiryDate);
        }
    });


    // Completed expiries indicate that the data has been deleted by you on this date after which you posted to Metronome to finalise the expiry.
    console.log("There are %d completed expiries on %s", response.completed.length, response.expiryDate);
    if (response.completed) {
        response.completed.forEach( (notice: CompletedExpiries) => {
            if(notice instanceof ItemExpiry) {
                console.log("Item %s did expire on %s", notice.itemId, response.expiryDate);
            } else if(notice instanceof SubItemExpiry) {
                console.log("Sub-item %s of item %s did expire on %s", notice.subItemId, notice.parentItemId, response.expiryDate);
            }
        });
    }
} catch (err) {
    explainError(err);
}

Deleting Expired Data

Section titled “Deleting Expired Data”

When data has served all of the purposes which the person authorised you to hold the data for, you must by law delete that data. To do this, you might set a daily job which queries expiry notices for the day before, thus being sure that the day ended and no other action extended the retention. Each pending notice must be deleted in your PII stores by your software. Having completed all of these expiries, you notify Metronome that all the data for that day was successfully expired by calling the putExpiryNotices method of the DataExpiryApi client, with the only parameter being the date in question.

put-expiry-notices.ts
import { DataExpiryApi, ServerConfiguration, createConfiguration } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const expiryApiClient = new DataExpiryApi(clientConfig);


try {
    await expiryApiClient.putExpiryNotices(new Date(2026, 5, 19));
    console.log("Expiry notices finalised successfully");
} catch (err) {
    explainError(err);
}