Notices API

View as Markdown Open in Claude

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	`GET /v1/sites/{site}/notice_settings`
Update notice settings	`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

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 object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/notice_settings \
  -u "$CHECKBOX_SECRET_KEY:"

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);

import os
from checkbox import Checkbox

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

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

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

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 · 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 object.

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

Errors use the standard envelope with a stable code and, where useful, next_action.

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"
}'

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);

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)

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"
  }
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Notices API

#The NoticeSettings object

#Retrieve notice settings

#Parameters

#Returns

#Update notice settings

#Parameters

#Body

#Returns

The NoticeSettings object

Retrieve notice settings

Parameters

Returns

Update notice settings

Parameters

Body

Returns