> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seyaha.net/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /{integrationId}/availability/notify

> Push a single slot update to Seyaha without waiting for the next scheduled sync.

Call this endpoint when a specific time slot's status, capacity, or vacancies change on
your platform. Seyaha will apply the update immediately to the matching slot in its
database — no full catalog re-fetch required.

<Note>
  This endpoint is optional. If you never call it, Seyaha will pick up changes during
  the next scheduled nightly sync or when you trigger `POST /{integrationId}/sync/trigger`.
  Use this for time-sensitive changes like a slot selling out or a last-minute cancellation
  freeing capacity.
</Note>

***

## Endpoint

```
POST https://api.seyaha.net/api/v1/partner-integrations/{integrationId}/availability/notify
```

### Path parameter

| Parameter       | Description                                     |
| --------------- | ----------------------------------------------- |
| `integrationId` | Your integration ID, issued when you registered |

***

## Authentication

Seyaha does **not** use your `auth_key` for this call. Authenticate using your
`webhook_secret` in the `x-webhook-secret` header:

```http theme={null}
POST /api/v1/partner-integrations/{integrationId}/availability/notify
x-webhook-secret: <your-webhook-secret>
Content-Type: application/json
```

Your `webhook_secret` is generated when your integration is created. If you have lost
it, contact Seyaha support — the secret cannot be rotated without recreating the integration.

***

## Request body

| Field                | Type    | Required | Description                                                                                                   |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `productId`          | string  | **Yes**  | The `id` of the product from your `GET /products` response                                                    |
| `optionId`           | string  | **Yes**  | The `id` of the option from your `GET /products` response                                                     |
| `availabilityId`     | string  | **Yes**  | The `id` of the availability slot from your `POST /availability` response                                     |
| `localDateTimeStart` | string  | **Yes**  | ISO 8601 datetime with offset, e.g. `"2026-07-15T10:00:00+03:00"`                                             |
| `status`             | string  | **Yes**  | One of: `AVAILABLE`, `FREESALE`, `LIMITED`, `SOLD_OUT`, `CLOSED`                                              |
| `vacancies`          | integer | No       | Updated remaining spots. Seyaha sets both `vacancies` and `capacity` from this if `capacity` is not provided. |
| `capacity`           | integer | No       | Updated total capacity of the slot                                                                            |
| `localDateTimeEnd`   | string  | No       | ISO 8601 end time of the slot                                                                                 |
| `unitPricing`        | array   | No       | Updated per-unit prices (same shape as `POST /availability` `unitPricing`)                                    |

```json theme={null}
{
  "productId": "product_abc",
  "optionId": "option_standard",
  "availabilityId": "avail_2026-07-15-10",
  "localDateTimeStart": "2026-07-15T10:00:00+03:00",
  "status": "LIMITED",
  "vacancies": 3,
  "capacity": 20
}
```

***

## Response

```http theme={null}
200 OK
Content-Type: application/json

{
  "success": 1,
  "data": { "updated": true }
}
```

`updated: true` is always returned on success, regardless of whether the slot was
matched. See the fallback behaviour below.

### Error responses

| HTTP  | Condition                                                                                                     |
| ----- | ------------------------------------------------------------------------------------------------------------- |
| `400` | Missing `x-webhook-secret` header or missing required body fields (`productId`, `optionId`, `availabilityId`) |
| `401` | `x-webhook-secret` does not match your integration's stored secret                                            |

***

## Fallback behaviour

If Seyaha cannot match `productId` + `optionId` to an existing activity in its database
(e.g. the catalog was never synced, or the product ID changed), Seyaha automatically
triggers a full background sync for your integration. The response is still `200` with
`updated: true` — the fallback sync runs asynchronously.

```
Scenario A — slot matched:
  Partner → POST /availability/notify  { productId, optionId, availabilityId, ... }
  Seyaha  → finds activity + variation → updates slot in place → returns { updated: true }

Scenario B — product not found:
  Partner → POST /availability/notify  { productId, optionId, availabilityId, ... }
  Seyaha  → no match → fires background syncOne(integrationId) → returns { updated: true }
  (full sync will resolve the discrepancy within seconds)
```

***

## Full example

A booking was just cancelled on your platform, freeing up 2 spots on the 10:00 slot:

```http theme={null}
POST https://api.seyaha.net/api/v1/partner-integrations/64a1b2c3d4e5f67890abcdef/availability/notify
x-webhook-secret: whsec_a1b2c3d4e5f6
Content-Type: application/json

{
  "productId": "product_abc",
  "optionId": "option_standard",
  "availabilityId": "avail_2026-07-15-10",
  "localDateTimeStart": "2026-07-15T10:00:00+03:00",
  "localDateTimeEnd": "2026-07-15T16:00:00+03:00",
  "status": "AVAILABLE",
  "vacancies": 16,
  "capacity": 20
}
```

Response:

```json theme={null}
{ "success": 1, "data": { "updated": true } }
```

***

## When to use notify vs. sync/trigger

| Change                                    | Use                   |
| ----------------------------------------- | --------------------- |
| Single slot capacity or vacancies changed | `availability/notify` |
| Single slot sold out                      | `availability/notify` |
| Product added, removed, or renamed        | `sync/trigger`        |
| Pricing changed on an option              | `sync/trigger`        |
| Many slots changed at once                | `sync/trigger`        |