---
title: "Open a hold"
method: POST
path: "/v1/holds"
tags: ["Holds"]
---

# Open a hold

`POST /v1/holds`

## Request

- Base URL: `https://inventories-api.paymongo.com`
- URL: `https://inventories-api.paymongo.com/v1/holds`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Reserve quantities against one or more inventory items. Validation is all-or-nothing: if any line lacks availability, the whole hold is refused and nothing is held.

## Request body

- CreateHoldRequestDTO: Hold to open; checkout defaults expires_at to now+24h and accepts an earlier future value, judged on the server clock: up to a minute past now+24h is clamped to it, later is rejected with 422; order/pack forbid it, manual accepts an optional future value
  - `expires_at` integer
  - `lines` CreateHoldLineRequestDTO[], required
    - `inventory_item_id` string, required
    - `quantity` integer, required: Quantity is a pointer so a legitimate zero value is not mistaken for an absent field by binding's "required" check; the domain layer rejects a non-positive quantity (422).
  - `livemode` boolean: LiveMode is required for S2S callers; ignored for merchant secret-key callers.
  - `reason` string, required

## Response `200`

OK

- object: Standard response containing data and its metadata if any
  - `data` HoldResponseDTO: A time-boxed reservation against one or more inventory items
    - `closed_at` integer
    - `created_at` integer
    - `expires_at` integer
    - `id` string
    - `lines` HoldLineResponseDTO[]
      - `consumed_quantity` integer
      - `id` string
      - `inventory_item_id` string
      - `quantity` integer
      - `released_quantity` integer
    - `livemode` boolean
    - `reason` string
    - `state` string
    - `updated_at` integer
  - `has_more` boolean

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paymongo/apis/inventories.md) - [All operations](https://skmtc.dev/paymongo/apis/inventories/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/inventories/revisions/7307fa6b0b16?raw)