# Inventory Update API (Market Data)

## Overview

There are two endpoints to update inventory data in menta tech:

1. **PUT at event level**: To update the complete inventory of an event
2. **PUT at granular level**: To update inventory in batches (by ticketOption, priceType, or combinations)

Both endpoints require authentication and the `externalReferenceId` of the event.

---

## Endpoint 1: Event-Level Update

### Request

```
PUT /v1/marketdata/events/{externalReferenceId}/inventory?showId={showId}
```

**Required headers:**
- `Authorization: {apiKey}`
- `Content-Type: application/json`

**Path parameters:**
- `externalReferenceId` (required): External identifier of the event

**Query parameters:**
- `showId` (optional): If the event has multiple shows, specify which one to update. Not needed if the event has only one show.

### Body

```json
{
  "capacity": 5000,
  "releasedTickets": 5000,
  "reservedSpace": 100,
  "soldOut": false,
  "soldPercentage": 75
}
```

All fields are optional. Only send the ones you want to update.

### Example

```bash
curl -X PUT "https://api.mentatech.io/v1/marketdata/events/EVENT_2024_001/inventory?showId=show123" \
  -H "Authorization: apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "capacity": 5000,
    "releasedTickets": 5000,
    "reservedSpace": 100,
    "soldOut": false,
    "soldPercentage": 75
  }'
```

### Response

The API returns the updated event with all its data.

---

## Endpoint 2: Batch/Granular Update

This endpoint allows you to update inventory for multiple categories, price types, or combinations in a single call. **Useful when you have multiple shows and each can have different items.**

### Request

```
PUT /v1/marketdata/events/{externalReferenceId}/inventory/details
```

**Required headers:**
- `Authorization: {apiKey}`
- `Content-Type: application/json`

**Path parameters:**
- `externalReferenceId` (required): External identifier of the event

### Body

The body is an array of items. Each item must include a `showId` and can be one of three types:

```json
[
    {
      "showId": "show123",
      "ticketOptionId": "zone_a",
      "inventory": {
        "releasedTickets": 1000,
        "reservedSpace": 50,
        "soldOut": false,
        "soldPercentage": 80
      }
    },
    {
      "showId": "show123",
      "priceTypeId": "early_bird",
      "inventory": {
        "releasedTickets": 200,
        "reservedSpace": 10,
        "soldOut": false,
        "soldPercentage": 90
      }
    },
    {
      "showId": "show456",
      "ticketOptionId": "zone_b",
      "priceTypeId": "regular",
      "inventory": {
        "releasedTickets": 500,
        "reservedSpace": 25,
        "soldOut": false,
        "soldPercentage": 70
      }
    }
  ]
```

### Item Types

1. **Only ticketOptionId**: Updates inventory for a ticket category
   ```json
   {
     "showId": "show123",
     "ticketOptionId": "zone_a",
     "inventory": { ... }
   }
   ```

2. **Only priceTypeId**: Updates inventory for a price type
   ```json
   {
     "showId": "show123",
     "priceTypeId": "early_bird",
     "inventory": { ... }
   }
   ```

3. **ticketOptionId + priceTypeId**: Updates the combination of category + price type
   ```json
   {
     "showId": "show123",
     "ticketOptionId": "zone_a",
     "priceTypeId": "early_bird",
     "inventory": { ... }
   }
   ```

### Full Example

```bash
curl -X PUT "https://api.mentatech.io/v1/marketdata/events/EVENT_2024_001/inventory/details" \
  -H "Authorization: apiKey" \
  -H "Content-Type: application/json" \
  -d '[
        {
          "showId": "show123",
          "ticketOptionId": "zone_a",
          "inventory": {
            "releasedTickets": 1000,
            "reservedSpace": 50,
            "soldOut": false,
            "soldPercentage": 80
          }
        },
        {
          "showId": "show456",
          "ticketOptionId": "zone_b",
          "priceTypeId": "early_bird",
          "inventory": {
            "releasedTickets": 500,
            "reservedSpace": 25,
            "soldOut": false,
            "soldPercentage": 70
          }
        }
    ]'
```

---

## Inventory Object Fields

These are the fields you can update in both endpoints:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `capacity` | number | No | Total ticket capacity (event-level update only) |
| `releasedTickets` | number | No | Tickets released for sale |
| `reservedSpace` | number | No | Reserved tickets (not available for purchase) |
| `soldOut` | boolean | No | Indicates if the category/event is sold out |
| `soldPercentage` | number | No | Sales percentage (0-100) |

All fields are **optional**. Only send the ones you need to update.

---

## Use Cases

### Case 1: Update entire event at once without granular data specification

If you have a simple event with a single show:

```bash
curl -X PUT "https://api.mentatech.io/v1/marketdata/events/EVENT_001/inventory" \
  -H "Authorization: apiKey" \
  -d '{
    "releasedTickets": 5000,
    "reservedSpace": 100,
    "soldPercentage": 75,
    "soldOut": false
  }'
```

### Case 2: Update only one ticket category

If you have different categories (General Admission, VIP, etc.):

```bash
curl -X PUT "https://api.mentatech.io/v1/marketdata/events/EVENT_001/inventory/details" \
  -H "Authorization: apiKey" \
  -d '[
      {
        "showId": "show_main",
        "ticketOptionId": "general_admission",
        "inventory": {
          "releasedTickets": 5000,
          "reservedSpace": 100,
          "soldPercentage": 75,
          "soldOut": false
        }
      }
    ]'
```

### Case 3: Update multiple shows and categories

```bash
curl -X PUT "https://api.mentatech.io/v1/marketdata/events/EVENT_001/inventory/details" \
  -H "Authorization: apiKey" \
  -d '[
      {
        "showId": "show_1",
        "ticketOptionId": "vip",
        "inventory": {
          "releasedTickets": 5000,
          "reservedSpace": 100,
          "soldPercentage": 75,
          "soldOut": false
        }
      },
      {
        "showId": "show_1",
        "ticketOptionId": "general",
        "inventory": {
          "releasedTickets": 5000,
          "reservedSpace": 100,
          "soldPercentage": 75,
          "soldOut": false
        }
      },
      {
        "showId": "show_2",
        "ticketOptionId": "vip",
        "inventory": {
          "releasedTickets": 5000,
          "reservedSpace": 100,
          "soldPercentage": 75,
          "soldOut": false
        }
      }
    ]'
```

---

## Important Notes

- **Authentication required**: All requests must include a valid token in the `Authorization` header
- **externalReferenceId**: Use the event identifier from your system.
- **showId in batches**: Each item in the batch must specify the `showId` it belongs to
- **Optional fields**: You don't need to send all fields; only the ones you need to update