---
title: Stock Formats
description: The Stock Formats API manages the sheet formats your shop buys: list them, fetch any version, add, edit, and retire your own, and hide or show standard ones.
---

# Stock Formats

The Stock Formats API manages the sheet formats your shop buys: list them, fetch any version, add, edit, and retire your own, and hide or show standard ones.

> **Auto-generated** from the public OpenAPI spec — this page never
> drifts from the running API. Base URL `https://api.arcnm.io`. Authenticate with
> the `X-API-Key` header (see [Authentication](../authentication.md)).

## List Stock Formats

`GET /api/v1/stock-formats`

The stock formats your organization prices with, its own first.

That is every format of your own plus each standard format you have
not hidden. Every row says in `resolution` what calculations do with it.

The response is a plain array, so the page position travels in the
`Link` (RFC 8288) and `X-Next-Cursor` / `X-Has-More` response headers.

> **Paginated.** Pass `cursor` (from the previous response) to fetch the next page; `limit` caps the page size.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | `sheet` \| `plate` \| `bar` \| `tube` | no | Which purchased stock form to list: `sheet`, `plate`, `bar` or `tube`. One kind per list. |
| `include_suppressed` | query | boolean | no | Also list the standard formats your organization has hidden, marked `suppressed`. Off by default, so the list is exactly the formats calculations price with. |
| `at` | query | string | no | Read the list as it stood on this date (`YYYY-MM-DD`): the formats a calculation dated then prices with. Defaults to today (UTC). |
| `cursor` | query | string | no | Opaque position token from the previous page's `next_cursor` (or the `Link` / `X-Next-Cursor` response header). Omit it for the first page. Keep every other query parameter identical for the whole walk — a cursor replayed against different filters is rejected. |
| `limit` | query | integer | no | Maximum rows to return in one page. |
| `offset` | query | integer | no | Rows to skip. Superseded by `cursor`, which is stable under concurrent writes; kept for existing integrations. Bounded — past the cap, page with `cursor`. |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X GET https://api.arcnm.io/api/v1/stock-formats \
  -H "X-API-Key: $ARCNM_API_KEY"
```

```python title="Python"
import requests

resp = requests.get(
    "https://api.arcnm.io/api/v1/stock-formats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `200` | Successful Response |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


## Create Stock Format

`POST /api/v1/stock-formats`

Add a format your shop buys ("GF 3000 × 1500", or a 6 m bar).

Calculations price with it from today on, beside the standard formats
of its kind you have not hidden. Each kind states its own dimensions —
see `kind`.

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `diameter_mm` | number | no |  |
| `gauge_max_mm` | number | no |  |
| `gauge_min_mm` | number | no |  |
| `key` | string | yes | A short identifier of lowercase letters, digits, `-` and `_`, starting with a letter or digit — unique among your current formats, and kept by every later version of this one. |
| `kind` | `sheet` \| `plate` \| `bar` \| `tube` | no | Which purchased stock form this is. A sheet states length_mm and width_mm; a plate adds thickness_mm to its largest size; a bar states length_mm and, optionally, diameter_mm; a tube states length_mm, diameter_mm and wall_mm. |
| `label` | string | yes | The format's name, e.g. `GF 3000 × 1500`, as calculations and quotes show it. Invisible formatting is removed — direction controls and zero-width characters — and a name with nothing left to read is refused. |
| `length_mm` | number | yes |  |
| `material_category` | `carbon_steel` \| `alloy_steel` \| `stainless_steel` \| `tool_steel` \| `cast_iron` \| `aluminium` \| `copper_alloy` \| `nickel_alloy` \| `titanium_alloy` \| `magnesium_alloy` \| `zinc_alloy` \| `thermoplastic` \| `thermoset` \| `elastomer` \| `composite` \| `other` | no |  |
| `thickness_mm` | number | no |  |
| `wall_mm` | number | no |  |
| `width_mm` | number | no |  |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X POST https://api.arcnm.io/api/v1/stock-formats \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "string",
    "label": "string",
    "length_mm": 0
  }'
```

```python title="Python"
import requests

resp = requests.post(
    "https://api.arcnm.io/api/v1/stock-formats",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "key": "string",
        "label": "string",
        "length_mm": 0
    },
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "key": "string",
    "label": "string",
    "length_mm": 0
  }),
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `201` | Successful Response |
| `409` | One of your current formats already uses this key (`stock_format_key_taken`). |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `409` | `conflict` | A conflicting change, or an `Idempotency-Key` reused with a different body. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `201`

| Field | Type | Description |
| --- | --- | --- |
| `diameter_mm` | number | Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres. |
| `gauge_max_mm` | number | Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind. |
| `gauge_min_mm` | number | Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind. |
| `id` | string | Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key. |
| `is_platform` | boolean | True for a standard format. You can hide a standard format for your organization, but not edit or retire it. |
| `key` | string | Stable identifier shared by every version. |
| `kind` | `sheet` \| `plate` \| `bar` \| `tube` | The purchased stock form: `sheet`, `plate` (ordered cut to size), `bar` (round bar) or `tube`. Each kind states its own dimensions. |
| `label` | string | Display name, e.g. `GF 3000 × 1500`. |
| `length_mm` | number | Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres. |
| `material_category` | `carbon_steel` \| `alloy_steel` \| `stainless_steel` \| `tool_steel` \| `cast_iron` \| `aluminium` \| `copper_alloy` \| `nickel_alloy` \| `titanium_alloy` \| `magnesium_alloy` \| `zinc_alloy` \| `thermoplastic` \| `thermoset` \| `elastomer` \| `composite` \| `other` | Material category this format is bought in; null for every material. |
| `org_id` | string | Your organization's id on a format of your own; null on a standard format. |
| `resolution` | `priced` \| `suppressed` \| `closed` | What calculations do with this format on the date read — `at` on the list, today otherwise. `priced`: they price with it. `suppressed`: a standard format your organization has hidden. `closed`: this version wasn't in force on that date — it was retired, or replaced by a newer version. |
| `thickness_mm` | number | Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind. |
| `valid_from` | string | Date this version took effect. |
| `valid_to` | string | Date this version was retired or replaced by a newer version; null while it is current. |
| `wall_mm` | number | Tube: the wall thickness, in millimetres. Null on every other kind. |
| `width_mm` | number | Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube. |

**Example response**

```json
{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}
```

## Retire Stock Format

`DELETE /api/v1/stock-formats/{format_id}`

Stop buying this format.

It closes today and stays readable by id, so calculations priced on it
keep their numbers when they are run again. A format added today that
no calculation has used yet is removed instead.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format_id` | path | string | yes | Identifier of the format. |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X DELETE https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY"
```

```python title="Python"
import requests

resp = requests.delete(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `200` | Successful Response |
| `404` | None of your own formats has this id (`stock_format_not_found`). A standard format can be hidden, but not edited or retired. |
| `409` | This version is already closed (`stock_format_superseded`), or retiring it would leave no format to price with (`stock_format_last_remaining`). |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `404` | `not_found` | A referenced resource doesn't exist or isn't visible to your organisation. |
| `409` | `conflict` | A conflicting change, or an `Idempotency-Key` reused with a different body. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `200`

| Field | Type | Description |
| --- | --- | --- |
| `message` | string |  |

**Example response**

```json
{
  "message": "string"
}
```

## Get Stock Format

`GET /api/v1/stock-formats/{format_id}`

One stock format by id, in any version — including one retired or
replaced since.

The format a calculation was priced on stays readable here after it
leaves the list. `resolution` says what calculations dated today do
with it.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format_id` | path | string | yes | Identifier of the format. |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X GET https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY"
```

```python title="Python"
import requests

resp = requests.get(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "GET",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `200` | Successful Response |
| `404` | No format with this id is visible to your organization (`stock_format_not_found`). |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `404` | `not_found` | A referenced resource doesn't exist or isn't visible to your organisation. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `200`

| Field | Type | Description |
| --- | --- | --- |
| `diameter_mm` | number | Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres. |
| `gauge_max_mm` | number | Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind. |
| `gauge_min_mm` | number | Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind. |
| `id` | string | Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key. |
| `is_platform` | boolean | True for a standard format. You can hide a standard format for your organization, but not edit or retire it. |
| `key` | string | Stable identifier shared by every version. |
| `kind` | `sheet` \| `plate` \| `bar` \| `tube` | The purchased stock form: `sheet`, `plate` (ordered cut to size), `bar` (round bar) or `tube`. Each kind states its own dimensions. |
| `label` | string | Display name, e.g. `GF 3000 × 1500`. |
| `length_mm` | number | Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres. |
| `material_category` | `carbon_steel` \| `alloy_steel` \| `stainless_steel` \| `tool_steel` \| `cast_iron` \| `aluminium` \| `copper_alloy` \| `nickel_alloy` \| `titanium_alloy` \| `magnesium_alloy` \| `zinc_alloy` \| `thermoplastic` \| `thermoset` \| `elastomer` \| `composite` \| `other` | Material category this format is bought in; null for every material. |
| `org_id` | string | Your organization's id on a format of your own; null on a standard format. |
| `resolution` | `priced` \| `suppressed` \| `closed` | What calculations do with this format on the date read — `at` on the list, today otherwise. `priced`: they price with it. `suppressed`: a standard format your organization has hidden. `closed`: this version wasn't in force on that date — it was retired, or replaced by a newer version. |
| `thickness_mm` | number | Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind. |
| `valid_from` | string | Date this version took effect. |
| `valid_to` | string | Date this version was retired or replaced by a newer version; null while it is current. |
| `wall_mm` | number | Tube: the wall thickness, in millimetres. Null on every other kind. |
| `width_mm` | number | Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube. |

**Example response**

```json
{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}
```

## Update Stock Format

`PATCH /api/v1/stock-formats/{format_id}`

Edit one of your own formats. Standard formats are not editable.

Changing the size, gauge band or material starts a new version: this
one closes today, so calculations priced on it keep their numbers,
and the response is the new version — a new `id` under the same
`key`. A version that took effect today changes in place instead,
unless a calculation has already been pinned to it or priced on it; a
new `label` always changes in place. A value sent unchanged changes
nothing.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format_id` | path | string | yes | Identifier of the format. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `diameter_mm` | number | no |  |
| `gauge_max_mm` | number | no |  |
| `gauge_min_mm` | number | no |  |
| `label` | string | no | The format's name, e.g. `GF 3000 × 1500`, as calculations and quotes show it. Invisible formatting is removed — direction controls and zero-width characters — and a name with nothing left to read is refused. |
| `length_mm` | number | no |  |
| `material_category` | `carbon_steel` \| `alloy_steel` \| `stainless_steel` \| `tool_steel` \| `cast_iron` \| `aluminium` \| `copper_alloy` \| `nickel_alloy` \| `titanium_alloy` \| `magnesium_alloy` \| `zinc_alloy` \| `thermoplastic` \| `thermoset` \| `elastomer` \| `composite` \| `other` | no |  |
| `thickness_mm` | number | no |  |
| `wall_mm` | number | no |  |
| `width_mm` | number | no |  |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X PATCH https://api.arcnm.io/api/v1/stock-formats/{format_id} \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "diameter_mm": 0,
    "gauge_max_mm": 0,
    "gauge_min_mm": 0,
    "label": "string",
    "length_mm": 0,
    "material_category": "carbon_steel",
    "thickness_mm": 0,
    "wall_mm": 0,
    "width_mm": 0
  }'
```

```python title="Python"
import requests

resp = requests.patch(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "diameter_mm": 0,
        "gauge_max_mm": 0,
        "gauge_min_mm": 0,
        "label": "string",
        "length_mm": 0,
        "material_category": "carbon_steel",
        "thickness_mm": 0,
        "wall_mm": 0,
        "width_mm": 0
    },
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}", {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "diameter_mm": 0,
    "gauge_max_mm": 0,
    "gauge_min_mm": 0,
    "label": "string",
    "length_mm": 0,
    "material_category": "carbon_steel",
    "thickness_mm": 0,
    "wall_mm": 0,
    "width_mm": 0
  }),
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `200` | Successful Response |
| `404` | None of your own formats has this id (`stock_format_not_found`). A standard format can be hidden, but not edited or retired. |
| `409` | This version is closed, so its size, gauge band and material can't change (`stock_format_superseded`). Edit the current version instead. |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `404` | `not_found` | A referenced resource doesn't exist or isn't visible to your organisation. |
| `409` | `conflict` | A conflicting change, or an `Idempotency-Key` reused with a different body. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `200`

| Field | Type | Description |
| --- | --- | --- |
| `diameter_mm` | number | Bar: the one diameter this length is stocked in, null for every standard diameter. Tube: the outside diameter. Null on a sheet and a plate. In millimetres. |
| `gauge_max_mm` | number | Sheet: the thickest sheet this format is bought in, in millimetres; null for no upper limit. Null on every other kind. |
| `gauge_min_mm` | number | Sheet: the thinnest sheet this format is bought in, in millimetres; null for no lower limit. Null on every other kind. |
| `id` | string | Identifier of this version of the format. Changing a format's size, gauge band or material starts a new version, with a new id under the same key. |
| `is_platform` | boolean | True for a standard format. You can hide a standard format for your organization, but not edit or retire it. |
| `key` | string | Stable identifier shared by every version. |
| `kind` | `sheet` \| `plate` \| `bar` \| `tube` | The purchased stock form: `sheet`, `plate` (ordered cut to size), `bar` (round bar) or `tube`. Each kind states its own dimensions. |
| `label` | string | Display name, e.g. `GF 3000 × 1500`. |
| `length_mm` | number | Sheet: the longer edge. Plate: the longest plate the supplier cuts to size. Bar and tube: the length bought. In millimetres. |
| `material_category` | `carbon_steel` \| `alloy_steel` \| `stainless_steel` \| `tool_steel` \| `cast_iron` \| `aluminium` \| `copper_alloy` \| `nickel_alloy` \| `titanium_alloy` \| `magnesium_alloy` \| `zinc_alloy` \| `thermoplastic` \| `thermoset` \| `elastomer` \| `composite` \| `other` | Material category this format is bought in; null for every material. |
| `org_id` | string | Your organization's id on a format of your own; null on a standard format. |
| `resolution` | `priced` \| `suppressed` \| `closed` | What calculations do with this format on the date read — `at` on the list, today otherwise. `priced`: they price with it. `suppressed`: a standard format your organization has hidden. `closed`: this version wasn't in force on that date — it was retired, or replaced by a newer version. |
| `thickness_mm` | number | Plate: the thickness the plate is cut to size in, in millimetres. Null on every other kind. |
| `valid_from` | string | Date this version took effect. |
| `valid_to` | string | Date this version was retired or replaced by a newer version; null while it is current. |
| `wall_mm` | number | Tube: the wall thickness, in millimetres. Null on every other kind. |
| `width_mm` | number | Sheet: the shorter edge. Plate: the widest plate the supplier cuts to size. Null on a bar and a tube. |

**Example response**

```json
{
  "diameter_mm": 0,
  "gauge_max_mm": 0,
  "gauge_min_mm": 0,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "is_platform": true,
  "key": "string",
  "kind": "sheet",
  "label": "string",
  "length_mm": 0,
  "material_category": "carbon_steel",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resolution": "priced",
  "thickness_mm": 0,
  "valid_from": "2026-06-01",
  "valid_to": "2026-06-01",
  "wall_mm": 0,
  "width_mm": 0
}
```

## Unsuppress Stock Format

`DELETE /api/v1/stock-formats/{format_id}/suppression`

Show a standard format you had hidden.

Calculations price with it again from today on.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format_id` | path | string | yes | Identifier of the format. |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X DELETE https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression \
  -H "X-API-Key: $ARCNM_API_KEY"
```

```python title="Python"
import requests

resp = requests.delete(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression", {
  method: "DELETE",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
  },
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `200` | Successful Response |
| `404` | No format with this id is visible to your organization (`stock_format_not_found`). |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `404` | `not_found` | A referenced resource doesn't exist or isn't visible to your organisation. |
| `409` | `conflict` | A conflicting change, or an `Idempotency-Key` reused with a different body. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `200`

| Field | Type | Description |
| --- | --- | --- |
| `message` | string |  |

**Example response**

```json
{
  "message": "string"
}
```

## Suppress Stock Format

`POST /api/v1/stock-formats/{format_id}/suppression`

Hide a standard format your shop doesn't buy, for your organization
only.

Calculations stop pricing with it from today on; earlier calculations
keep the formats they were priced with. The hide holds for the format,
so it stays hidden when a newer version of it replaces this one. A
format of your own is retired instead.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format_id` | path | string | yes | Identifier of the format. |

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no |  |

**Request**

<CodeTabs>

```bash title="cURL"
curl -X POST https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression \
  -H "X-API-Key: $ARCNM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "string"
  }'
```

```python title="Python"
import requests

resp = requests.post(
    "https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "reason": "string"
    },
)
resp.raise_for_status()
print(resp.json())
```

```typescript title="TypeScript"
const resp = await fetch("https://api.arcnm.io/api/v1/stock-formats/{format_id}/suppression", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ARCNM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "string"
  }),
})
const data = await resp.json()
```

</CodeTabs>

**Responses**

| Status | Description |
| --- | --- |
| `201` | Successful Response |
| `404` | No format with this id is visible to your organization (`stock_format_not_found`). |
| `409` | The format is one of your own, which you retire instead (`stock_format_own_row_use_retire`), this version of it is closed (`stock_format_superseded`), or hiding it would leave no format to price with (`stock_format_last_remaining`). |
| `422` | Validation Error |

**Errors**

Standard error responses — see the [Errors catalog](../errors.md) for the full envelope, `request_id`, and retry-safety table.

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key` | Missing, malformed, or revoked API key. |
| `403` | `insufficient_scope` | The key is valid but lacks a scope this endpoint requires. |
| `404` | `not_found` | A referenced resource doesn't exist or isn't visible to your organisation. |
| `409` | `conflict` | A conflicting change, or an `Idempotency-Key` reused with a different body. |
| `429` | `rate_limited` | Per-key or per-org rate limit exceeded — back off with jitter and retry. |


**Response body** `201`

| Field | Type | Description |
| --- | --- | --- |
| `message` | string |  |

**Example response**

```json
{
  "message": "string"
}
```