# Bundles

The Bundles API lets you group multiple listings into a single purchasable unit with a bundle price.

## Bundle types

### Fixed bundle
A curated set of listings sold together. The admin or seller defines exactly which items are included and in what quantity. Buyers purchase the bundle as-is.

**Example:** "Starter Kit" — 1× Notebook + 2× Pens + 1× Bag for $49.99

### Mix & Match bundle
Buyers choose their own items from a defined pool. The bundle sets a minimum (and optional maximum) quantity, and the buyer selects that many items from the pool.

**Example:** "Pick Any 3" — choose 3 products from a catalogue of 20 options for $29.99

## How to create a bundle

1. Create a listing via `POST /v1/listings` with `type: "bundle"`
2. For **fixed bundles**: add components via `POST /v1/bundles/:listing_id/items`
3. For **mix & match**: set `metadata.bundle_type: "mix_and_match"`, `metadata.min_quantity`, and `metadata.max_quantity` on the listing, then populate the pool via `POST /v1/bundles/:listing_id/pool`

## How purchase works

When a buyer purchases a bundle listing via the standard checkout flow, the system automatically:
- Creates individual order lines per component (one per branch/account)
- Decrements component stock
- Enables per-seller fulfilment via the existing multi-shipment flow

## Authentication

Authenticate client requests with the Bearer token only. Tenant and user identity are carried by the token and resolved by the API gateway; do not add `tenant_id`, `user_id`, `admin`, or `X-Auth-Key` headers.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Curl examples

Create the listing through the Listings API, then use its returned ID in the
bundle endpoints. This example assumes the new listing ID is `729379`.

```bash
curl -X POST "$API/v1/listings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "listing": {
      "title": "Aurelia Bridal Set - Pick 2",
      "description": "Choose any two items from the bridal collection.",
      "type": "bundle",
      "list_price": 120000,
      "currency_id": 13,
      "metadata": {
        "bundle_type": "mix_and_match",
        "min_quantity": 2,
        "max_quantity": 2
      }
    }
  }'
```

### Fixed bundle components

```bash
curl "$API/v1/bundles/729379/items" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "$API/v1/bundles/729379/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "component_listing_id": 370,
    "quantity": 1,
    "order_by": 1
  }'

curl -X PUT "$API/v1/bundles/729379/items/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "quantity": 1,
    "order_by": 1
  }'

curl -X DELETE "$API/v1/bundles/729379/items/1" \
  -H "Authorization: Bearer $TOKEN"
```

### Mix-and-match bundle pool

```bash
curl "$API/v1/bundles/729379/pool" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "$API/v1/bundles/729379/pool" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "component_listing_id": 370,
    "order_by": 1
  }'

curl -X POST "$API/v1/bundles/729379/pool" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "component_listing_id": 371,
    "order_by": 2
  }'
```

### Select bundle items

Submit the buyer's selection before adding the bundle listing to the cart. Save
the returned `selection_id` and use it for both cart creation and checkout.

```bash
curl -X POST "$API/v1/bundles/729379/select" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "selected_listing_ids": [370, 371],
    "quantity": 1
  }'
```

The examples below assume the selection endpoint returned `selection_id: 6`.

### Check stock

```bash
curl "$API/v1/bundles/729379/stock?quantity=1" \
  -H "Authorization: Bearer $TOKEN"
```

### Add the bundle to cart

```bash
curl -X POST "$API/v1/cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "listing_id": 729379,
    "quantity": 1,
    "type": "bundle",
    "selection_id": 6
  }'
```

### Checkout

```bash
curl -X POST "$API/v1/cart/checkout" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "order": {
      "payment_method_id": 7175,
      "type": "bundle",
      "selection_id": 6
    }
  }'
```

### Retrieve selected components for fulfilment

Replace `6563` with the order ID returned by checkout.

```bash
curl "$API/v1/bundles/729379/orders/6563/components" \
  -H "Authorization: Bearer $TOKEN"
```

Sellers can only add their own listings as fixed components or pool items.