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.

// 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}

// 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}

// 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}

// 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:

// 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:

// 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
}

2. Adding the size variant directly to the basket:

// 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 guide.