# How to use the Basket API

The Jay Basket API provides a comprehensive solution for managing shopping baskets in your integration. This guide covers the key operations and best practices when working with the Basket API.

## Requirements

- **Authentication**: A bearer token is required for all API requests. Contact Jay to obtain your token.
- **Product Data**: Products must be listed in the Playout API before they can be added to a basket.
- **Product Identifiers**: Use the `basketProductId` from the Playout API as the `productId` parameter in Basket API calls.


## Checking Product Availability

Products may have limited stock availability. Before adding items to a basket or proceeding to checkout, always check product availability to provide users with accurate information.

### API Route: `/baskets/products/details`

This endpoint allows you to retrieve detailed information about multiple products, including their current stock availability.


```json
// Request
POST /v2/baskets/products/details
Content-Type: application/json

[
  "product-123",
  "product-456"
]

// Response
{
  "products": [
    {
      "productId": "product-123",
      "name": "Sample Product",
      "currentStockCount": 10,
      "price": "29.99",
      "currency": "EUR"
      // Additional product details...
    },
    {
      "productId": "product-456",
      "name": "Another Product",
      "currentStockCount": 0,
      "price": "19.99",
      "currency": "EUR",
      "outOfStock": true
      // Additional product details...
    }
  ]
}
```

**Use cases:**

- Check availability before displaying products to users
- Tag products as "sold out" when no stock is available
- Show remaining stock information when inventory is low


## Managing Products in the Basket

The Basket API provides endpoints for adding, updating, and removing products from a user's basket.

### Adding Products

**API Route:** `/baskets/users/{userId}/products/{productId}`


```json
// Request
POST /v2/baskets/users/user-123/products/product-456
Content-Type: application/json

{
  "count": 1
}

// Response
{
  "lastChanged": "2025-05-19T10:30:45Z",
  "cart": [
    {
      "productId": "product-456",
      "count": 1
    }
  ],
  "saved": [],
  "checkout": []
}
```

**Note:** Setting `count` to 0 will add the product to the saved list instead of the cart.

### Updating Products

**API Route:** `/baskets/users/{userId}/products/{productId}`


```json
// Request
PATCH /v2/baskets/users/user-123/products/product-456
Content-Type: application/json

{
  "count": 2
}

// Response
{
  "lastChanged": "2025-05-19T10:35:22Z",
  "cart": [
    {
      "productId": "product-456",
      "count": 2
    }
  ],
  "saved": [],
  "checkout": []
}
```

**Note:** To move a product from cart to saved list, update with `count: 0`.

### Removing Products

**API Route:** `/baskets/users/{userId}/products/{productId}`


```json
// Request
DELETE /v2/baskets/users/user-123/products/product-456

// Response
{
  "lastChanged": "2025-05-19T10:40:15Z",
  "cart": [],
  "saved": [],
  "checkout": []
}
```

## Working with Product Variants (Sizes)

Many products have variants, such as different sizes. The checkout process requires a selected size for applicable products.

### Checking available Sizes

Use the product details endpoint to retrieve information about available sizes:


```json
// Request
POST /v2/baskets/products/details
Content-Type: application/json

[
  "product-789"
]

// Response
{
  "products": [
    {
      "productId": "product-789",
      "name": "T-Shirt",
      "sizes": [
        {
          "id": "size-S",
          "short": "S",
          "long": "Small",
          "currentStockCount": 5,
          "availability": "AVAILABLE"
        },
        {
          "id": "size-M",
          "short": "M",
          "long": "Medium",
          "currentStockCount": 3,
          "availability": "AVAILABLE"
        },
        {
          "id": "size-L",
          "short": "L",
          "long": "Large",
          "currentStockCount": 0,
          "availability": "OUT_OF_STOCK"
        }
      ]
    }
  ]
}
```

### Adding Products with Size Variants

You have two options for handling products with size variants:

1. **Adding the main product first, then selecting a size in the basket view:**



```json
// Step 1: Add the main product to the basket
POST /v2/baskets/users/user-123/products/product-789
Content-Type: application/json

{
  "count": 1
}

// Step 2: In your UI, allow the user to select a size 
// Step 3: Add the selected size variant to the basket
POST /v2/baskets/users/user-123/products/size-M
Content-Type: application/json

{
  "count": 1
}
```

1. **Adding the size variant directly to the basket:**



```json
// Add the size variant directly
POST /v2/baskets/users/user-123/products/size-M
Content-Type: application/json

{
  "count": 1
}
```

**Important:** For checkout, a size variant must be selected for products that have size options.

## Basket During Checkout

When a user initiates the checkout process, the basket is locked for 30 minutes to prevent concurrent modifications.

### Checkout Session Behavior

- The basket remains locked for 30 minutes after initiating checkout
- Products in checkout are moved to a separate "checkout" list in the basket
- The basket can be unlocked by either completing the checkout or canceling it


### Managing Checkout Sessions

To initiate or finalize a checkout session, use the following endpoints:

- Start checkout: `/baskets/users/{userId}/checkout/sessions`
- Finish checkout: `/baskets/users/{userId}/checkout/sessions/finish-active`


For complete details about the checkout process, including integration with Stripe for payment processing, please refer to the [How to Checkout with Stripe](/platform/how-to/checkout-stripe) guide.

Support
For any questions or support needs during implementation, please contact the [Jay Support Team](mailto:support@transfermedia.de).