# Law updates API

> Changes in automatic-renewal law that Checkbox applies, with their effect on your sites.

Subscribe to the law.changed webhook to hear about them.

| Operation | Endpoint |
|---|---|
| [List law updates](#listLawUpdates) | `GET /v1/law_updates` |
| [Retrieve a law update](#retrieveLawUpdate) | `GET /v1/law_updates/{law_update}` |

## The LawUpdate object

A change in the law Checkbox applies, and its effect on your sites.

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the law update (law_…). |
| `object` | enum | String representing the object's type. Always "law_update". |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `source` | enum | catalog_change: Checkbox updated the legal catalog; effective / sunset: a dated rule started or ended. One of `catalog_change`, `effective`, `sunset`. |
| `date` | string | Date of the change (YYYY-MM-DD). |
| `summary` | string | What changed. |
| `jurisdictions` | array of enum | Jurisdictions changed. |
| `changes` | array of LawChanges | Changed requirements. |
| `impacts` | array of LawSiteImpacts | Effects on this account's sites (in this mode). |
| `created` | integer | When Checkbox recorded the change. Unix timestamp in seconds. |

## List law updates {#listLawUpdates}

`GET /v1/law_updates`

Law changes newest first, each with its effect on this account's sites.

**Scope** `law_updates:read` · **Operation** `listLawUpdates`

SDK: `checkbox.lawUpdates.list()` (Node) · `checkbox.law_updates.list()` (Python). MCP / agents: operation `listLawUpdates`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `limit` | query | integer | Number of objects to return, 1-100 (default 10). |
| `starting_after` | query | string | Cursor: an object id; returns the objects after it (older). |
| `ending_before` | query | string | Cursor: an object id; returns the objects before it (newer). |
| `since` | query | string | Only changes on or after this date (YYYY-MM-DD). |

#### Returns

Returns a list (`{ object: "list", data, has_more, url }`) of [LawUpdate](https://checkbox.site/docs/api/law-updates#the-lawupdate-object) objects.

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

```curl
curl -G https://app.checkbox.site/v1/law_updates \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3
```
```node
import Checkbox from '@checkbox-site/cli';

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

const lawUpdates = await checkbox.lawUpdates.list({ limit: 3 });
console.log(lawUpdates.data);
```
```python
import os
from checkbox import Checkbox

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

law_updates = checkbox.law_updates.list(limit=3)
print(law_updates.data)
```

```json title="Response"
{
  "object": "list",
  "data": [
    {
      "id": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "law_update",
      "livemode": false,
      "source": "effective",
      "date": "2026-11-01",
      "summary": "New York online-cancellation rule takes effect.",
      "jurisdictions": [
        "US-NY"
      ],
      "changes": [
        {
          "requirement_id": "US-NY.527-a.1",
          "change": "effective",
          "jurisdiction": "US-NY",
          "citation": "N.Y. Gen. Bus. Law § 527-a",
          "title": "Online cancellation",
          "summary": null,
          "effective_date": "2026-11-01",
          "sunset_date": null,
          "source_url": "https://www.nysenate.gov/legislation/laws/GBS/527-A"
        }
      ],
      "impacts": [
        {
          "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
          "summary": "1 check now fails under the new rule.",
          "score_before": 90,
          "score_after": 84,
          "affected_checks": [
            {
              "check_id": "cancellation.online_cancel_available",
              "title": "Customers can cancel online",
              "severity": "critical",
              "before": "pass",
              "after": "fail"
            }
          ],
          "evaluated": 1793318400
        }
      ],
      "created": 1793318400
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}
```

## Retrieve a law update {#retrieveLawUpdate}

`GET /v1/law_updates/{law_update}`

One law change with its effect on this account's sites.

**Scope** `law_updates:read` · **Operation** `retrieveLawUpdate`

SDK: `checkbox.lawUpdates.retrieve()` (Node) · `checkbox.law_updates.retrieve()` (Python). MCP / agents: operation `retrieveLawUpdate`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `law_update` **required** | path | string | Unique identifier of the law update (law_…). |

#### Returns

Returns a [LawUpdate](https://checkbox.site/docs/api/law-updates#the-lawupdate-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/law_updates/law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

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

const lawUpdate = await checkbox.lawUpdates.retrieve('law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(lawUpdate);
```
```python
import os
from checkbox import Checkbox

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

law_update = checkbox.law_updates.retrieve("law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(law_update)
```

```json title="Response"
{
  "id": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "law_update",
  "livemode": false,
  "source": "effective",
  "date": "2026-11-01",
  "summary": "New York online-cancellation rule takes effect.",
  "jurisdictions": [
    "US-NY"
  ],
  "changes": [
    {
      "requirement_id": "US-NY.527-a.1",
      "change": "effective",
      "jurisdiction": "US-NY",
      "citation": "N.Y. Gen. Bus. Law § 527-a",
      "title": "Online cancellation",
      "summary": null,
      "effective_date": "2026-11-01",
      "sunset_date": null,
      "source_url": "https://www.nysenate.gov/legislation/laws/GBS/527-A"
    }
  ],
  "impacts": [
    {
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "summary": "1 check now fails under the new rule.",
      "score_before": 90,
      "score_after": 84,
      "affected_checks": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "severity": "critical",
          "before": "pass",
          "after": "fail"
        }
      ],
      "evaluated": 1793318400
    }
  ],
  "created": 1793318400
}
```