> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trysend.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trysend.com/_mcp/server.

# Hold or release a package

POST https://api.trysend.com/v1/packages/{id}/notices
Content-Type: application/json

Create a notice on a package to hold or release it.
Send `action: "hold"` to hold the package at the warehouse, or `action: "release"` to release it for delivery.
Internally, `hold` is recorded as a warning notice and `release` is recorded as an info notice.
Each call records a Notice for audit trail and updates the package's hold instruction accordingly.
The response returns only the notice action result, not the full package payload.


Reference: https://docs.trysend.com/api-reference/send-parcels-api/packages/create-package-notice

## Authentication

- `X-Api-Key` header (required)

## Request

### Path parameters

- `id` (string, required) — Parcel token

### Body (application/json)

- `action` (enum, required) — `hold` maps to a warning notice; `release` maps to an info notice
  - Allowed values: `hold`, `release`
- `body` (string, optional) — Optional description of the notice

## Response

### 201

Created

- `parcel_id` (string, required) — Package token affected by the notice action.
- `action` (enum, required) — Action applied to the package.
  - Allowed values: `hold`, `release`
- `hold_instruction` (enum, required) — Current hold state after the action.
  - Allowed values: `hold`, `release`
- `hold_released_at` (datetime, required, nullable) — Set when the package has been released.
- `notice` (object, required)
  - `token` (string, optional)
  - `uuid` (string, optional)
  - `level` (enum, optional)
    - Allowed values: `info`, `warning`, `danger`
  - `body` (string, optional)
  - `active` (boolean, optional)
  - `created_at` (datetime, optional)
  - `deactivated_at` (datetime, optional, nullable)

## Examples

### Hold a package

**Request**

```json
{
  "action": "hold",
  "body": "Awaiting payment clearance"
}
```

**Response**

```json
{
  "parcel_id": "string",
  "action": "hold",
  "hold_instruction": "hold",
  "hold_released_at": "2024-01-15T09:30:00Z",
  "notice": {
    "token": "string",
    "uuid": "string",
    "level": "info",
    "body": "string",
    "active": true,
    "created_at": "2024-01-15T09:30:00Z",
    "deactivated_at": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python Hold a package
import requests

url = "https://api.trysend.com/v1/packages/PKG123456789/notices"

payload = {
    "action": "hold",
    "body": "Awaiting payment clearance"
}
headers = {
    "X-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```ruby Hold a package
require 'uri'
require 'net/http'

url = URI("https://api.trysend.com/v1/packages/PKG123456789/notices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"hold\",\n  \"body\": \"Awaiting payment clearance\"\n}"

response = http.request(request)
puts response.read_body
```

### Release a package

**Request**

```json
{
  "action": "release",
  "body": "Payment received, release for delivery"
}
```

**Response**

```json
{
  "parcel_id": "string",
  "action": "hold",
  "hold_instruction": "hold",
  "hold_released_at": "2024-01-15T09:30:00Z",
  "notice": {
    "token": "string",
    "uuid": "string",
    "level": "info",
    "body": "string",
    "active": true,
    "created_at": "2024-01-15T09:30:00Z",
    "deactivated_at": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```python Release a package
import requests

url = "https://api.trysend.com/v1/packages/PKG123456789/notices"

payload = {
    "action": "release",
    "body": "Payment received, release for delivery"
}
headers = {
    "X-Api-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```ruby Release a package
require 'uri'
require 'net/http'

url = URI("https://api.trysend.com/v1/packages/PKG123456789/notices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"release\",\n  \"body\": \"Payment received, release for delivery\"\n}"

response = http.request(request)
puts response.read_body
```