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

# Inventory

> Check real-time availability and flash deals

# Check Inventory

<Note>
  Real-time inventory sync with venues. Use this to check availability before booking or to find flash deals.
</Note>

## Use This Endpoint When

<CardGroup cols={2}>
  <Card title="Availability check" icon="calendar-check">
    * "Is this available tomorrow?"
    * "Any slots left for Saturday?"
    * "Can we book for 6 people?"
  </Card>

  <Card title="Deal hunting" icon="tags">
    * "Any deals today?"
    * "What's on sale?"
    * "Cheapest options available"
  </Card>
</CardGroup>

## Request Parameters

<ParamField query="city" type="string" required>
  City name (e.g., `Bangkok`, `Phuket`, `Bali`)
</ParamField>

<ParamField query="date" type="string">
  ISO 8601 date format. Defaults to today.
</ParamField>

<ParamField query="activity_id" type="string">
  Check specific activity availability
</ParamField>

<ParamField query="category" type="string">
  Filter by category: `spa`, `dinner`, `theme-park`, `zoo`, `aquarium`, `adventure`, `cultural`, `nightlife`
</ParamField>

<ParamField query="flash_deals_only" type="boolean" default="false">
  Only return activities with active flash deals (30-50% off)
</ParamField>

<ParamField query="min_slots" type="number" default="1">
  Minimum available slots required
</ParamField>

<ParamField query="max_price" type="number">
  Maximum price filter
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum results (1-50)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Properties">
    <ResponseField name="inventory" type="array">
      List of available activities

      <Expandable title="Inventory Item">
        <ResponseField name="activity_id" type="string">
          Activity identifier
        </ResponseField>

        <ResponseField name="title" type="string">
          Activity title
        </ResponseField>

        <ResponseField name="category" type="string">
          Activity category
        </ResponseField>

        <ResponseField name="available_slots" type="number">
          Number of slots available
        </ResponseField>

        <ResponseField name="price" type="number">
          Current price
        </ResponseField>

        <ResponseField name="original_price" type="number">
          Original price (if flash deal)
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code
        </ResponseField>

        <ResponseField name="is_flash_deal" type="boolean">
          Whether this is a limited-time deal
        </ResponseField>

        <ResponseField name="flash_deal_expires" type="string">
          When the deal expires (if applicable)
        </ResponseField>

        <ResponseField name="discount_percent" type="number">
          Discount percentage (if flash deal)
        </ResponseField>

        <ResponseField name="operating_hours" type="string">
          Activity operating hours
        </ResponseField>

        <ResponseField name="last_updated" type="string">
          When inventory was last synced
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      <Expandable title="Properties">
        <ResponseField name="total_results" type="number">
          Total matching results
        </ResponseField>

        <ResponseField name="flash_deals_count" type="number">
          Number of flash deals available
        </ResponseField>

        <ResponseField name="query_date" type="string">
          Date queried
        </ResponseField>

        <ResponseField name="city" type="string">
          City queried
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Check City Inventory

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.privetag.com/api/b2a/inventory?city=Bangkok&date=2025-12-15" \
    -H "x-api-key: pk_a1b2c3..."
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.privetag.com/api/b2a/inventory",
      headers={"x-api-key": "pk_a1b2c3..."},
      params={
          "city": "Bangkok",
          "date": "2025-12-15"
      }
  )

  inventory = response.json()
  for item in inventory['data']['inventory']:
      print(f"{item['title']}: {item['available_slots']} slots at {item['price']} {item['currency']}")
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    city: 'Bangkok',
    date: '2025-12-15'
  });

  const response = await fetch(`https://api.privetag.com/api/b2a/inventory?${params}`, {
    headers: {
      'x-api-key': 'pk_a1b2c3...'
    }
  });

  const inventory = await response.json();
  inventory.data.inventory.forEach(item => {
    console.log(`${item.title}: ${item.available_slots} slots`);
  });
  ```
</CodeGroup>

### Flash Deals Only

```bash theme={null}
curl -X GET "https://api.privetag.com/api/b2a/inventory?city=Phuket&flash_deals_only=true" \
  -H "x-api-key: pk_a1b2c3..."
```

### Specific Activity Availability

```bash theme={null}
curl -X GET "https://api.privetag.com/api/b2a/inventory?activity_id=act_abc123&date=2025-12-15" \
  -H "x-api-key: pk_a1b2c3..."
```

### Category Filter with Price Cap

```bash theme={null}
curl -X GET "https://api.privetag.com/api/b2a/inventory?city=Bangkok&category=spa&max_price=2000" \
  -H "x-api-key: pk_a1b2c3..."
```

## Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "inventory": [
      {
        "activity_id": "act_abc123",
        "title": "Safari World Bangkok",
        "category": "zoo",
        "available_slots": 45,
        "price": 1500,
        "currency": "THB",
        "is_flash_deal": false,
        "operating_hours": "09:00 - 17:00",
        "last_updated": "2025-12-10T08:00:00Z"
      },
      {
        "activity_id": "act_def456",
        "title": "Oasis Spa - Signature Package",
        "category": "spa",
        "available_slots": 8,
        "price": 1800,
        "original_price": 3000,
        "currency": "THB",
        "is_flash_deal": true,
        "flash_deal_expires": "2025-12-10T18:00:00Z",
        "discount_percent": 40,
        "operating_hours": "10:00 - 22:00",
        "last_updated": "2025-12-10T08:00:00Z"
      }
    ],
    "metadata": {
      "total_results": 42,
      "flash_deals_count": 7,
      "query_date": "2025-12-10",
      "city": "Bangkok"
    }
  }
}
```

## Flash Deals

<Info>
  **Flash Deals** are same-day discounts (30-50% off) offered by venues to fill remaining capacity. These are exclusive to AI agent bookings and expire at a specific time.
</Info>

### How Flash Deals Work

```mermaid theme={null}
graph LR
    A[Venue has empty slots] --> B[Creates flash deal]
    B --> C[30-50% discount]
    C --> D[AI agents see deal]
    D --> E[Book via API]
    E --> F[Venue fills capacity]
```

### Flash Deal Response Fields

| Field                | Description                    |
| -------------------- | ------------------------------ |
| `is_flash_deal`      | `true` if currently discounted |
| `original_price`     | Price before discount          |
| `price`              | Current discounted price       |
| `discount_percent`   | Percentage off (30-50)         |
| `flash_deal_expires` | When deal ends                 |

## Inventory Sync

Our inventory is synced with venues in real-time:

| Sync Type | Frequency    | Description                 |
| --------- | ------------ | --------------------------- |
| Real-time | Instant      | When bookings are made      |
| Periodic  | Every 15 min | Full inventory refresh      |
| On-demand | On request   | When you call this endpoint |

<Warning>
  **Low Availability Warning**: When `available_slots` is low (\< 5), book quickly as slots can sell out between checking and booking.
</Warning>

## Use Cases

<AccordionGroup>
  <Accordion title="Display available activities">
    Use this endpoint to show users what's available before they decide. Better than `/recommend` when the user wants to browse all options.
  </Accordion>

  <Accordion title="Find last-minute deals">
    Set `flash_deals_only=true` to find discounted activities for same-day booking. Great for spontaneous travelers.
  </Accordion>

  <Accordion title="Verify before booking">
    Always check availability before calling `/execute_booking` to ensure a smooth booking experience.
  </Accordion>

  <Accordion title="Price comparison">
    Use `category` filter to compare prices across similar activities.
  </Accordion>
</AccordionGroup>

## Error Responses

| Code                 | Description                               |
| -------------------- | ----------------------------------------- |
| `INVALID_CITY`       | City not found in our service area        |
| `INVALID_DATE`       | Date format incorrect or in the past      |
| `ACTIVITY_NOT_FOUND` | Specified activity\_id doesn't exist      |
| `NO_INVENTORY`       | No activities available matching criteria |

## Supported Cities

Currently available in Southeast Asia:

| Country        | Cities                                      |
| -------------- | ------------------------------------------- |
| 🇹🇭 Thailand  | Bangkok, Phuket, Chiang Mai, Pattaya, Krabi |
| 🇻🇳 Vietnam   | Ho Chi Minh, Hanoi, Da Nang, Nha Trang      |
| 🇮🇩 Indonesia | Bali, Jakarta, Yogyakarta                   |
| 🇲🇾 Malaysia  | Kuala Lumpur, Penang, Langkawi              |
| 🇸🇬 Singapore | Singapore                                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Recommendations" icon="wand-magic-sparkles" href="/api-reference/b2a/recommend">
    Get personalized activity recommendations
  </Card>

  <Card title="Execute Booking" icon="ticket" href="/api-reference/b2a/execute-booking">
    Book an activity from inventory
  </Card>
</CardGroup>