---
title: "Buy a retention quote"
method: POST
path: "/v1/retention/purchases"
tags: ["Retention"]
---

# Buy a retention quote

`POST /v1/retention/purchases`

## Request

- Base URL: `https://api.ironfang.com/audit`
- URL: `https://api.ironfang.com/audit/v1/retention/purchases`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Buys a quote exactly as quoted, in one step: the quoted quantity of
`audit.retention_extension` is admitted by the billing account, every
quoted deadline moves to its quoted date, and the usage is committed -
all of it or none. Needs billing.manage from a signed-in person with a
verified email address: API keys and connected apps are refused
(`insufficient_scope`, `person_required`), as for every billing change.
A refusal from the billing account (paid usage not enabled, a budget
reached) is the shared billing answer. A quote past its `expires_at`,
made in another month or at another catalogue version, that the
account's position would now price differently, or whose evidence has
changed since (deleted, or its deadline moved) is `quote_expired`: ask
for a new quote. Buying a quote that is already bought returns it with
200 and charges nothing more.

## Request body

- object
  - `quote_id` string, uuid, required

## Response `200`

Already bought; the quote as it was bought.

- RetentionQuote
  - `amount` string, required: The fixed price, exact, before tax, in pounds.
  - `amount_minor` integer, required: The price rounded to pence.
  - `artifacts` integer, required
  - `audit_ids` string[], required
  - `bytes` integer, required: Hosted bytes the quote covers.
  - `catalogue_version` string, required
  - `created_at` string, date-time, required
  - `currency` 'GBP', required
  - `deadlines` object[]
    - `artifact_id` string, uuid, required
    - `audit_id` string, uuid, required
    - `byte_length` integer, required
    - `expires_after` string, date-time, required
    - `expires_before` string, date-time, required
  - `expires_at` string, date-time, required: The quote can be bought until then.
  - `id` string, uuid, required
  - `meter` 'audit.retention_extension', required
  - `months` integer, required
  - `prices_exclude_tax` true, required
  - `purchased_at` string, date-time
  - `quantity` integer, required: In the meter's unit (unit): the bytes rounded up to the unit's share of a decimal gigabyte, times months, at least ten GB-months.
  - `status` 'open' | 'expired' | 'purchased', required
  - `unit` string, required: The meter's unit, for example 0.1 GB-month.

## Other responses

- `201`: Bought; the quote with its new deadlines.
- `400`: Problem response
- `401`: Problem response
- `402`: Problem response
- `403`: Problem response
- `404`: Problem response
- `409`: Problem response
- `422`: Problem response
- `429`: Problem response
- `503`: Problem response

---

[API](https://skmtc.dev/ironfang/apis/ironfang-audit-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-audit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-audit-api/revisions/7430deff2cbd?raw)