Manage metadata

Metadata is your own data attached to a paper, such as a category, a customer ID or an amount. Every operation that changes metadata returns the updated paper.

Attach on upload

const paper = await paperful.papers.upload({
  file,
  fileName: "invoice.pdf",
  metadata: {
    category: "invoice",
    amount: 150,
  },
});

Read metadata

Metadata is returned with the paper, whether you retrieve it, list it or find it through search.

const paper = await paperful.papers.get("00000000-0000-0000-0000-000000000000");

console.log(paper.metadata.category);

Update metadata

The keys you pass are merged into the existing metadata. Keys you leave out are kept.

const paper = await paperful.papers.update("00000000-0000-0000-0000-000000000000", {
  metadata: {
    category: "receipt",
    paid: true,
  },
});

Remove a key

Set a key to null to remove it.

const paper = await paperful.papers.update("00000000-0000-0000-0000-000000000000", {
  metadata: {
    amount: null,
  },
});

Replace all metadata

Replace the paper's metadata with exactly what you pass. Every other key is removed.

const paper = await paperful.papers.metadata.replace("00000000-0000-0000-0000-000000000000", {
  category: "receipt",
});

To remove all metadata, replace it with an empty object.

const paper = await paperful.papers.metadata.replace("00000000-0000-0000-0000-000000000000", {});

Filter by metadata

Use metadata to narrow down lists and searches. Pass a value to match it exactly, an array to match any of the values, or gt, gte, lt and lte to match a numeric range.

const { items } = await paperful.papers.list({
  metadata: {
    category: ["invoice", "receipt"],
    amount: { gte: 100 },
  },
});

const results = await paperful.search.query("total amount", {
  metadata: { category: "invoice" },
});

Values

Metadata values can be strings, numbers, booleans, arrays of a single type, or objects nested up to 3 levels. See Limits for the maximum size of metadata.