# Notices API

> Checkbox sends the legally required acknowledgment, trial-ending, renewal, yearly-terms and price-change emails for the merchant, timed from the legal catalog.

| Operation | Endpoint |
|---|---|
| [Retrieve notice settings](#retrieveNoticeSettings) | `GET /v1/sites/{site}/notice_settings` |
| [Update notice settings](#updateNoticeSettings) | `POST /v1/sites/{site}/notice_settings` |

## The NoticeSettings object

Checkbox Notices for a site: the legally required emails Checkbox sends on the merchant's behalf.

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the notice settings (ntcs_…). |
| `object` | enum | String representing the object's type. Always "notice_settings". |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `site` | string | The site. |
| `enabled_kinds` | array of enum | Notices Checkbox sends for the merchant. |
| `brand_name` | string \| null | Brand shown in notices (defaults to the site name). |
| `product_name` | string \| null | Product name used in notices. |
| `logo_url` | string \| null | Logo URL (https). |
| `support_email` | string \| null | Reply-to / support address. |
| `cancel_url` | string \| null | Where subscribers cancel online (site domain, hosted cancellation page or billing portal). |
| `brand_color` | string \| null | Hex brand colour. |
| `from_local_part` | string | Mailbox name of the sender. |
| `policy` | object \| null | Confirmed cancellation policy (required before notices go out). |
| `policy.cancel_timing` | enum | When a cancellation takes effect. One of `period_end`, `immediately`. |
| `policy.confirmed` | integer | When the policy was confirmed. Unix timestamp in seconds. |
| `sender` | object \| null | Sending address, when one is available. |
| `sender.from` | string | From header. |
| `sender.own_domain` | boolean | Sent from the merchant's verified domain. |
| `sending_domain` | object | Custom sending domain status (set it up in the dashboard). |
| `sending_domain.domain` | string \| null | Custom sending domain. |
| `sending_domain.status` | string | none, pending, verified or failed. |
| `delivery_configured` | boolean | This Checkbox deployment can send email. |
| `kinds` | array of objects | Every notice kind. |
| `updated` | integer \| null | Last change. Unix timestamp in seconds. |
| `next_action` | NextAction \| null | What the caller (often an AI agent) should do next. |

## Retrieve notice settings {#retrieveNoticeSettings}

`GET /v1/sites/{site}/notice_settings`

Which notices Checkbox sends for the site and what is missing before they can go out (next_action).

**Scope** `notices:read` · **Operation** `retrieveNoticeSettings`

SDK: `checkbox.noticeSettings.retrieve()` (Node) · `checkbox.notice_settings.retrieve()` (Python). MCP / agents: operation `retrieveNoticeSettings`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |

#### Returns

Returns a [NoticeSettings](https://checkbox.site/docs/api/notices#the-noticesettings-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/notice_settings \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const noticeSetting = await checkbox.noticeSettings.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(noticeSetting);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice_setting = checkbox.notice_settings.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(notice_setting)
```

```json title="Response"
{
  "id": "ntcs_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "notice_settings",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "enabled_kinds": [
    "acknowledgment",
    "renewal_reminder"
  ],
  "brand_name": "Acme Coffee Club",
  "product_name": "Coffee subscription",
  "logo_url": null,
  "support_email": "help@acme.example",
  "cancel_url": "https://acme.example/account/cancel",
  "brand_color": "#1f2937",
  "from_local_part": "notices",
  "policy": {
    "cancel_timing": "period_end",
    "confirmed": 1793318400
  },
  "sender": {
    "from": "Acme Coffee Club <notices@acme.example>",
    "own_domain": true
  },
  "sending_domain": {
    "domain": "acme.example",
    "status": "verified"
  },
  "delivery_configured": true,
  "kinds": [
    {
      "kind": "renewal_reminder",
      "label": "Renewal reminder",
      "description": "Sent before an annual renewal.",
      "enabled": true,
      "check_ids": [
        "reminder.annual_renewal_notice"
      ]
    }
  ],
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "url": "https://checkbox.site/docs/api/activation"
  }
}
```

## Update notice settings {#updateNoticeSettings}

`POST /v1/sites/{site}/notice_settings`

Turns notices on or off and sets branding, cancel_url and the confirmed cancellation policy. Turning a notice on requires cancel_url, a confirmed policy, a connected Stripe or Recharge account and a sending address; otherwise resource_conflict explains what is missing.

**Scope** `notices:write` · **Idempotent** (send `Idempotency-Key`) · **Live mode needs [activation](https://checkbox.site/docs/concepts/activation)** · **Operation** `updateNoticeSettings`

SDK: `checkbox.noticeSettings.update()` (Node) · `checkbox.notice_settings.update()` (Python). MCP / agents: operation `updateNoticeSettings`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |

#### Body

| Field | Type | Description |
|---|---|---|
| `enabled_kinds` | array of enum | Notices to send (turning one on needs cancel_url, a confirmed policy and a connected Stripe/Recharge account). trial_reminder is accepted as an alias of trial_ending. |
| `brand_name` | string \| null | Brand name. |
| `product_name` | string \| null | Product name. |
| `logo_url` | string \| null | Logo URL (https). |
| `support_email` | string \| null | Support address. |
| `cancel_url` | string \| null | Online cancellation URL. |
| `brand_color` | string \| null | Hex colour. |
| `from_local_part` | string | Sender mailbox name. |
| `policy` | object \| null | Cancellation policy the notices state. |
| `policy.cancel_timing` **required** | enum | When a cancellation takes effect (must match your Terms). One of `period_end`, `immediately`. |
| `policy.confirm` **required** | enum | Confirms this matches your Terms and your cancellation flow. |

#### Returns

Returns a [NoticeSettings](https://checkbox.site/docs/api/notices#the-noticesettings-object) object.

In live mode before activation: `403 account_not_activated` with `next_action.operation_id: "createDomainVerification"`.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/notice_settings \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "brand_name": "Acme Coffee Club"
}'
```
```node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const noticeSetting = await checkbox.noticeSettings.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { brand_name: 'Acme Coffee Club' });
console.log(noticeSetting);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice_setting = checkbox.notice_settings.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", brand_name="Acme Coffee Club")
print(notice_setting)
```

```json title="Response"
{
  "id": "ntcs_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "notice_settings",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "enabled_kinds": [
    "acknowledgment",
    "renewal_reminder"
  ],
  "brand_name": "Acme Coffee Club",
  "product_name": "Coffee subscription",
  "logo_url": null,
  "support_email": "help@acme.example",
  "cancel_url": "https://acme.example/account/cancel",
  "brand_color": "#1f2937",
  "from_local_part": "notices",
  "policy": {
    "cancel_timing": "period_end",
    "confirmed": 1793318400
  },
  "sender": {
    "from": "Acme Coffee Club <notices@acme.example>",
    "own_domain": true
  },
  "sending_domain": {
    "domain": "acme.example",
    "status": "verified"
  },
  "delivery_configured": true,
  "kinds": [
    {
      "kind": "renewal_reminder",
      "label": "Renewal reminder",
      "description": "Sent before an annual renewal.",
      "enabled": true,
      "check_ids": [
        "reminder.annual_renewal_notice"
      ]
    }
  ],
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "url": "https://checkbox.site/docs/api/activation"
  }
}
```