Read the outcome of a Restriction Batch

GET/api/v1/restriction-batches/{id}

Requires restrictions.write

Per Property: changes applied, unchanged, superseded, refused (and why) and failed (and why), as runs of dates. Only batches of the calling App Connection are visible; another one answers not_found.

Request

curl https://app.zenhost.com/api/v1/restriction-batches/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7 \
  -H "Authorization: Bearer zh_at_..."

const response = await fetch('https://app.zenhost.com/api/v1/restriction-batches/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7', {
  headers: {
    Authorization: 'Bearer zh_at_...',
  },
});
const data = await response.json();

import requests

response = requests.get(
    "https://app.zenhost.com/api/v1/restriction-batches/7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
    headers={"Authorization": "Bearer zh_at_..."},
)
data = response.json()

Response

{
  "id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
  "status": "queued",
  "created_at": "2026-10-10T08:00:00.000Z",
  "completed_at": "2026-10-10T08:00:00.000Z",
  "properties": [
    {
      "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
      "status": "pending",
      "changes": {
        "submitted": 1,
        "pending": 1,
        "applied": 1,
        "unchanged": 1,
        "superseded": 1,
        "refused": 1,
        "failed": 1,
        "cancelled": 1
      },
      "refused_fields": [
        {
          "field": "rate",
          "reason": "manual_override",
          "from": "2026-11-01",
          "to": "2026-11-30"
        }
      ],
      "failures": [
        {
          "field": "rate",
          "code": "sales_channel_rejected",
          "message": "A human-readable explanation",
          "from": "2026-11-01",
          "to": "2026-11-30"
        }
      ]
    }
  ]
}

{
  "error": {
    "code": "unauthorized",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "subscription_blocked",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "app_suspended",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "A human-readable explanation",
    "details": {}
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "A human-readable explanation",
    "details": {}
  }
}

Parameters

Path parameters

idstring (uuid)required

Responses

200The Restriction Batch and its outcome.

application/jsonRestrictionBatch

idstring (uuid)required
statusstringrequired
queued then processing while changes wait for the Sales Channels (each Property is sent at a pace the Sales Channels accept, and retried when they are unavailable); final: completed (nothing failed), partially_failed, failed (nothing applied), cancelled.
One of: queued processing completed partially_failed failed cancelled
created_atstring (date-time)required
completed_atstring (date-time) | nullrequired
propertiesRestrictionBatchProperty[]required
Show 5 child attributesHide child attributes
- property_idstring (uuid)required
- statusstringrequired
  pending: changes still wait. applied: some changes were applied or already current and none failed (refused, superseded or cancelled ones aside, see changes). failed: some changes failed, see failures. refused: every change was refused. superseded: nothing was sent, every change not refused was replaced by a later batch first. cancelled: nothing was sent because the App Connection was revoked or paused by ZenHost, the Property left its Property Access, or the App lost restrictions.write.
  One of: pending applied failed refused superseded cancelled
- changesobjectrequired
  Date × field changes of this Property, by outcome.
  Show 8 child attributesHide child attributes
  submittedintegerrequired
  pendingintegerrequired
  appliedintegerrequired
  unchangedintegerrequired
  Already the current value: nothing was sent.
  supersededintegerrequired
  Replaced by a later batch on the same date and field before being sent; not a failure.
  refusedintegerrequired
  failedintegerrequired
  cancelledintegerrequired
  Not sent: the App Connection was revoked or paused by ZenHost first, the Property left its Property Access, or the App lost restrictions.write.
- refused_fieldsRefusedField[]required
  Show 4 child attributesHide child attributes
  fieldstringrequired
  One of: rate min_stay closed_to_arrival closed_to_departure availability
  reasonstringrequired
  One of: manual_override managed_by_another_pricing_tool blocked_by_linked_property
  fromstring (date)required
  tostring (date)required
- failuresRestrictionBatchFailure[]required
  Show 5 child attributesHide child attributes
  fieldstringrequired
  One of: rate min_stay closed_to_arrival closed_to_departure availability
  codestringrequired
  sales_channel_rejected: the Sales Channels refused the change. sales_channel_unavailable: the Sales Channels could not be reached, after retries spread over about 15 minutes. sales_channel_mapping_missing: the Property is not fully connected to its Sales Channels. property_not_configured: the Property has no primary rate plan or room in ZenHost. not_in_calendar: ZenHost holds no Restriction for that date. property_not_found: the Property no longer exists. write_failed: ZenHost could not store the change. New codes may be added.
  One of: sales_channel_rejected sales_channel_unavailable sales_channel_mapping_missing property_not_configured not_in_calendar property_not_found write_failed
  messagestringrequired
  fromstring (date)required
  tostring (date)required

401Error code: unauthorized, connection_revoked.

Error codes

unauthorized The access token is missing, unknown, expired or revoked, or was issued before the account connected the App again. Refresh it; if refreshing fails, ask the owner to connect again.
connection_revoked The owner revoked the App Connection (or your App revoked its own refresh token). Stop calling for this account and drop its tokens.

402Error code: subscription_blocked.

Error codes

subscription_blocked The ZenHost subscription of the account is blocked (unpaid, cancelled…). The connection is kept: tell your customer, calls work again once the subscription is restored.

403Error code: app_suspended, forbidden_permission.

Error codes

app_suspended ZenHost suspended your App, or no longer allows it on this account. Stop calling and contact ZenHost.
forbidden_permission Your App was not granted the Permission this endpoint requires.

404Error code: not_found.

Error codes

not_found The resource does not exist or is outside the Connection Scope (both look the same), or the path is not an endpoint of /api/v1.

429Error code: rate_limited.

Header Retry-After — Seconds to wait before the next call is allowed. Limits per App Connection: 60 reads (GET), 10 writes (other POST) and 30 messages sent to guests per minute.

Error codes

rate_limited Too many calls on this App Connection. Wait for the number of seconds in Retry-After.

500Error code: internal_error.

Error codes

internal_error ZenHost failed to answer. Retry later with a back-off.

Every error code and what to do