Write Restrictions of Properties over date ranges

POST/api/v1/restriction-batches

Requires restrictions.write

Stores the batch and answers at once; the changes then reach ZenHost and the Sales Channels shortly after, in submission order: on a date and field, the latest batch wins and an older change not sent yet is superseded. A value equal to the current one is not sent again. A field ZenHost will not write (Manual Override, another pricing tool, a night closed by a linked Property; see unwritable_fields of GET /restrictions) is refused and reported, never forced; the rest of the batch still applies, with no rollback. Read the outcome with GET /restriction-batches/{id}. Every POST, dry_run included, counts against the submission rate limit.

Request

curl -X POST https://app.zenhost.com/api/v1/restriction-batches \
  -H "Authorization: Bearer zh_at_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-2026-10-10" \
  -d '{
    "entries": [
      {
        "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
        "from": "2026-11-01",
        "to": "2026-11-30",
        "values": {
          "rate": 129.5,
          "min_stay": 2,
          "availability": true
        }
      }
    ],
    "dry_run": false
  }'

const response = await fetch('https://app.zenhost.com/api/v1/restriction-batches', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer zh_at_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'nightly-2026-10-10',
  },
  body: JSON.stringify({
    "entries": [
      {
        "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
        "from": "2026-11-01",
        "to": "2026-11-30",
        "values": {
          "rate": 129.5,
          "min_stay": 2,
          "availability": true
        }
      }
    ],
    "dry_run": false
  }),
});
const data = await response.json();

import requests

response = requests.post(
    "https://app.zenhost.com/api/v1/restriction-batches",
    headers={"Authorization": "Bearer zh_at_...", "Idempotency-Key": "nightly-2026-10-10"},
    json={
        "entries": [
            {
                "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
                "from": "2026-11-01",
                "to": "2026-11-30",
                "values": {
                    "rate": 129.5,
                    "min_stay": 2,
                    "availability": True,
                },
            },
        ],
        "dry_run": False,
    },
)
data = response.json()

Response

{
  "dry_run": true,
  "properties": [
    {
      "property_id": "3f6c1a52-8d0e-4b7a-9f21-5c4e8b7d2a10",
      "changes": {
        "submitted": 1,
        "changed": 1,
        "unchanged": 1,
        "refused": 1
      },
      "changed": [
        {
          "date": "2026-11-01",
          "field": "rate",
          "current": 1,
          "new": 1
        }
      ],
      "refused_fields": [
        {
          "field": "rate",
          "reason": "manual_override",
          "from": "2026-11-01",
          "to": "2026-11-30"
        }
      ]
    }
  ]
}

{
  "id": "7d1e4c09-2b5a-4e83-a6f0-91c8d3b2e4f7",
  "status": "queued"
}

{
  "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": "validation_failed",
    "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

Headers

Idempotency-Keystring
Replaying the same key on the same App Connection within 24 hours returns the batch it created instead of a new one. Reusing it with a different body answers idempotency_key_reused. Ignored with dry_run.
at most 255 characters

Request body

application/jsonRestrictionBatchRequest

Up to 20000 entries over at most 100 Properties (to cover more, send one batch per page of GET /properties). Dates run from today to today + 730 days, both in the time zone of each Property (its timezone).

entriesRestrictionBatchEntry[]required
1 to 20000 items
Show 4 child attributesHide child attributes
- property_idstring (uuid)required
- fromstring (date)required
  First night, inclusive.
- tostring (date)required
  Last night, inclusive.
- valuesRestrictionValuesrequired
  The values to write on every date of the entry; a field left out is not touched. At least one field.
  Show 5 child attributesHide child attributes
  ratenumber
  Base nightly rate, decimal, in the currency of the Property, rounded to the cent. Property Pricing Modifiers still apply on top per Sales Channel.
  min 0.01 · max 99999999.99
  min_stayinteger
  Minimum stay in nights.
  min 1 · max 365
  closed_to_arrivalboolean
  closed_to_departureboolean
  availabilityboolean
  Open (true) or close (false) the night for sale. A booked night stays closed on the Sales Channels whatever this value.
dry_runboolean
When true, nothing is stored or sent: the answer is 200 with what would change per Property.

Responses

200With dry_run: what the batch would change now.

application/jsonRestrictionBatchPreview

dry_runtruerequired
propertiesRestrictionBatchPreviewProperty[]required
Show 4 child attributesHide child attributes
- property_idstring (uuid)required
- changesobjectrequired
  Date × field changes of this Property.
  Show 4 child attributesHide child attributes
  submittedintegerrequired
  changedintegerrequired
  unchangedintegerrequired
  refusedintegerrequired
- changedRestrictionChangePreview[]required
  Every change that would be sent, in date order.
  Show 4 child attributesHide child attributes
  datestring (date)required
  fieldstringrequired
  One of: rate min_stay closed_to_arrival closed_to_departure availability
  currentnumber | boolean | nullrequired
  The value now; null when unset or not in the calendar.
  newnumber | boolean | nullrequired
- 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

202The batch is stored and queued.

application/jsonRestrictionBatchAccepted

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

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.

422Error code: validation_failed, property_out_of_scope, idempotency_key_reused.

Error codes

validation_failed The query, headers or body are invalid; details.issues points at each problem (path, message, and maximum when a value or list is too big).
property_out_of_scope A requested Property is outside the Connection Scope; details.property_ids lists them.
idempotency_key_reused This Idempotency-Key was already used on this App Connection with a different body.

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