# Media Jay Basket API - v2 The basket API provides shopping baskets. It is designed fast access for a big amount of users. #### Authentication To access the endpoints you require a **X-API-Key** in the header. Partners, please contact Transfermedia to retrieve one. All endpoints are protected with a standard Authentication Bearer JWT token. We provide two mechanisms here: 1. A JWT token provided on partner side. Signature validation is required. This allows **comfort functions** like: - the customer id to prevent users to re-enter their data multiple times - a payment token to checkout with a single click This requires: - that the JWT token can be validated on partners side. - the user id is specified in the 'sub' field of the payload. - optionally a static issuer is specified in the 'iss' field of the payload. - optionally a static audience is specified in the 'aud' field of the payload. 2. A JWT token and a user id is generated on an endpoint in the basket api for **guest users**. In such a case the basket has some limitations: - the basket is a fresh one (filled only with the products specified) - no comfort functions are available - the JWT token expires after 30 days #### Versioning To use a specific implementation version of this API place it to the request header **X-API-Version**. If the header is missed the latest implementation version **2025-09-15** is used. The response header **X-API-Version** contains the implementation version the request was processed with. #### Shopping basket A **shopping basket** contains three product lists: - *cart*: holding up to 20 products planned to buy - *saved*: holding the products to remember for later usage (aka wishlist) - *checkout*: holding the products currently in the order process (in the active checkout session) Products can be added, updated and deleted to/from the cart or saved list. #### Products *Products* are represented by a product identifier with an order count. A product can be a main product or a product variant (e.g. a shoe in a specific size). #### Checkout session When the user decides to *start the order process* the checkout is the first step in the order process. It communicates with the payment service provider (PSP) responsible to manage the payment. If the payment succeeds an order process starts in the background. #### Transfer basket The API provides the ability to transfer a basket e.g., to a web shop. Optionally a QR code image can be created to be presented to a customer. For security reasons the transfer needs to be finished within 1 minute. #### Further documentation For further details please visit the [documentation](https://docs.jay-metadata.com/) or contact Transfermedia . Version: 2025-09-15 ## Servers Production server ``` https://live.basket.api.jay-metadata.com/v2 ``` ## Security ### Basket-API-Endpoints Provides an authorization mechanism to access the Basket API Endpoints Type: http Scheme: bearer Bearer Format: Bearer ## Download OpenAPI description [Media Jay Basket API - v2](https://docs.jay-metadata.com/_spec/apis/basket/@latest/openapi.yaml) ## Guest Baskets ### Creates a fresh guest shopping basket. - [POST /baskets/guests](https://docs.jay-metadata.com/apis/basket/latest/openapi/guest-baskets/createguestbasket.md): Creates a fresh guest (aka anonymous) shopping basket. If the query parameter "jayToken" is specified this methods creates the credentials to access a transferred basket.Products can be added directly to this basket. Some restrictions apply on a guest basket:- no comfort functions are available- a guest basket is accessible for 30 daysIf you add the same product multiple times they become a single product entry in the basket. ## Basket Operations ### Gets the shopping basket of the specified user. - [GET /baskets/users/{userId}](https://docs.jay-metadata.com/apis/basket/latest/openapi/basket-operations/getbasket.md): Retrieves the shopping basket of a user. An empty basket is returned if it does not exist yet. A shopping basket contains - a cart containing the products to buy - a saved list containing the products to remember for later usage - a checkout list containing the products in the active checkout session ### Deletes a shopping basket of the specified user. - [DELETE /baskets/users/{userId}](https://docs.jay-metadata.com/apis/basket/latest/openapi/basket-operations/deletebasket.md): Deletes the shopping basket of a user. ### Update basket comfort settings - [PATCH /baskets/users/{userId}/comfort](https://docs.jay-metadata.com/apis/basket/latest/openapi/basket-operations/updatecomfortbasketsettings.md): Allows to update basket comfort settings. This is a user specific comfort function available to validated users only. Important: The streaming provider needs to provide an authentication endpoint providing a JWT token so Jay is able to validate the user. ## Product Operations ### Assigns a product to the shopping basket. - [POST /baskets/users/{userId}/products/{productId}](https://docs.jay-metadata.com/apis/basket/latest/openapi/product-operations/assignproducttobasket.md): Assigns a product to the shopping basket. If the product exists it will be overwritten.- A product with an order "count" == 0 will be added to the saved list (and removed from cart).- A product with an order "count" > 0 will be added to the cart (and removed from saved list).Note that at max 20 products can be put into the cart. ### Removes a product from the shopping basket. - [DELETE /baskets/users/{userId}/products/{productId}](https://docs.jay-metadata.com/apis/basket/latest/openapi/product-operations/deleteproductfrombasket.md): Removes a product from the shopping basket (from cart and saved list). ### Updates an existing product in the shopping basket. - [PATCH /baskets/users/{userId}/products/{productId}](https://docs.jay-metadata.com/apis/basket/latest/openapi/product-operations/updateproductinbasket.md): Updates an existing product in the shopping basket. - A product with an order "count" == 0 will be added to the saved list (and removed from cart). - A product with an order "count" > 0 will be added to the cart (and removed from saved list). - If the order "count" is None the product is not changed. ## Product Details ### Get detailed information about multiple products. - [POST /baskets/products/details](https://docs.jay-metadata.com/apis/basket/latest/openapi/product-details/getproductinformation.md): Retrieves detailed information about multiple products. This contains the name, brand, images, the current stock count and much more. ## Checkout Sessions ### Checkout the shopping basket of the specified user. - [POST /baskets/users/{userId}/checkout/sessions](https://docs.jay-metadata.com/apis/basket/latest/openapi/checkout-sessions/checkoutbasket.md): Contacts the payment service provider (PSP) to prepare a checkout of the products in the cart. Creates an order for this checkout. ### Finish the active checkout. - [POST /baskets/users/{userId}/checkout/sessions/finish-active](https://docs.jay-metadata.com/apis/basket/latest/openapi/checkout-sessions/finishactivecheckout.md): Finish the active checkout in the shopping basket. ## Basket Transfer ### Transfer the basket to another system (e.g. a web shop). - [POST /baskets/users/{userId}/transfer](https://docs.jay-metadata.com/apis/basket/latest/openapi/basket-transfer/transferbasket.md): Transfer the basket over a common url or a QR code to another system (e.g. a web shop). The transfer token is valid for 1 minute only. Use POST /baskets/gusts with jayToken set to the transfer token to get access to the basket again. ## Basket Follow-up Operations ### Lists shopping baskets. - [GET /baskets](https://docs.jay-metadata.com/apis/basket/latest/openapi/basket-follow-up-operations/listbaskets.md): Retrieves a list of shopping baskets. This might be used to implement follow up actions.It may happen that the returned list is empty but the next_token has a value. This means that there might be more elements available. Please repeat calling this method until next_token is empty.Available since X-API-Key 2025-09-12 ## API information ### Api Version - [GET /version](https://docs.jay-metadata.com/apis/basket/latest/openapi/api-information/api_version_version_get.md)