Skip to content
/Product Operations

Media Jay Basket API - v2 (2025-09-15)

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 or contact Transfermedia support@transfermedia.de.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Production server

https://live.basket.api.jay-metadata.com/v2/

Guest Baskets

Operations

Basket Operations

Operations

Product Operations

Operations

Assigns a product to the shopping basket.

Request

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.

Security
Basket-API-Endpoints
Path
userIdstring(Userid)[ 1 .. 256 ] charactersrequired

The platform specific user identifier representing a user.

productIdstring(product identifier)required

The product identifier uniquely identifying a product from a playout.

Query
provider_idstring(Provider Id)

Optional provider identifier to use as a fallback when tracking session is unavailable or does not contain provider information. This ensures tracking events can still be attributed to the correct provider.

Example: provider_id=netflix
Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-Trackingstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
x-jay-api-versionstring(X-Jay-Api-Version)

The version of the API to use. Defaults to 2025-09-15.

Default 2025-09-15
Bodyapplication/jsonrequired
countinteger(The order count)>= 0required

The absolute number of products to order. A value above zero place the product in the cart. A value equal to zero places the product in the saved list.

curl -i -X POST \
  'https://live.basket.api.jay-metadata.com/v2/baskets/users/{userId}/products/{productId}?provider_id=netflix' \
  -H 'Authorization: Bearer <YOUR_Bearer_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-Tracking: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9' \
  -H 'x-jay-api-version: 2025-09-15' \
  -d '{
    "count": 0
  }'

Responses

Successfully assigned a product to the shopping basket.

Bodyapplication/json
dataobject(The response data)

The response data.

Example: {"expires":"2025-06-29T08:12:34Z","lastChanged":"2025-06-04T12:34:56Z","cart":[{"productId":"prod-123","count":2},{"productId":"prod-456","count":1}],"saved":[{"productId":"prod-789","count":1}],"checkout":[{"productId":"prod-123","count":1},{"productId":"prod-456","count":1}]}
nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "data": {
    "expires": "2025-06-29T08:12:34Z",
    "lastChanged": "2025-06-04T12:34:56Z",
    "cart": [ … ],
    "saved": [ … ],
    "checkout": [ … ]
  }
}

Removes a product from the shopping basket.

Request

Removes a product from the shopping basket (from cart and saved list).

Security
Basket-API-Endpoints
Path
userIdstring(Userid)[ 1 .. 256 ] charactersrequired

The platform specific user identifier representing a user.

productIdstring(product identifier)required

The product identifier uniquely identifying a product from a playout.

Query
provider_idstring(Provider Id)

Optional provider identifier to use as a fallback when tracking session is unavailable or does not contain provider information. This ensures tracking events can still be attributed to the correct provider.

Example: provider_id=netflix
Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-Trackingstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
x-jay-api-versionstring(X-Jay-Api-Version)

The version of the API to use. Defaults to 2025-09-15.

Default 2025-09-15
curl -i -X DELETE \
  'https://live.basket.api.jay-metadata.com/v2/baskets/users/{userId}/products/{productId}?provider_id=netflix' \
  -H 'Authorization: Bearer <YOUR_Bearer_HERE>' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-Tracking: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9' \
  -H 'x-jay-api-version: 2025-09-15'

Responses

Successfully removed an existing product from the shopping basket.

Bodyapplication/json
dataobject(The response data)

The response data.

Example: {"expires":"2025-06-29T08:12:34Z","lastChanged":"2025-06-04T12:34:56Z","cart":[{"productId":"prod-123","count":2},{"productId":"prod-456","count":1}],"saved":[{"productId":"prod-789","count":1}],"checkout":[{"productId":"prod-123","count":1},{"productId":"prod-456","count":1}]}
nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "data": {
    "expires": "2025-06-29T08:12:34Z",
    "lastChanged": "2025-06-04T12:34:56Z",
    "cart": [ … ],
    "saved": [ … ],
    "checkout": [ … ]
  }
}

Updates an existing product in the shopping basket.

Request

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.
Security
Basket-API-Endpoints
Path
userIdstring(Userid)[ 1 .. 256 ] charactersrequired

The platform specific user identifier representing a user.

productIdstring(product identifier)required

The product identifier uniquely identifying a product from a playout.

Query
provider_idstring(Provider Id)

Optional provider identifier to use as a fallback when tracking session is unavailable or does not contain provider information. This ensures tracking events can still be attributed to the correct provider.

Example: provider_id=netflix
Headers
X-API-Keystring(X-Api-Key)required

Required. API access key for authorized use of the checkout endpoints. Partners, please contact Transfermedia to retrieve a valid key.

X-JAY-Trackingstring(X-Jay-Tracking)

Tracking session header for user tracking and analytics. This is set by the /playouts/tracking/session endpoint.

Example: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9
x-jay-api-versionstring(X-Jay-Api-Version)

The version of the API to use. Defaults to 2025-09-15.

Default 2025-09-15
Bodyapplication/jsonrequired
countinteger(The order count)>= 0

The absolute number of products to order. A value above zero place the product in the cart. A value equal to zero places the product in the saved list.

curl -i -X PATCH \
  'https://live.basket.api.jay-metadata.com/v2/baskets/users/{userId}/products/{productId}?provider_id=netflix' \
  -H 'Authorization: Bearer <YOUR_Bearer_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: string' \
  -H 'X-JAY-Tracking: eyJzZXNzaW9uX2lkIjoiZXhhbXBsZS1zZXNzaW9uLWlkLTEyMzQiLCJzdGFydF90aW1lIjoiMjAyNS0wMS0wMVQxMjowMDowMC4wMDAwMDAiLCJzb3VyY2UiOiJqYXkuYXBpLnBsYXlvdXQuZXhhbXBsZSJ9' \
  -H 'x-jay-api-version: 2025-09-15' \
  -d '{
    "count": 0
  }'

Responses

Successfully updated an existing product in the shopping basket.

Bodyapplication/json
dataobject(The response data)

The response data.

Example: {"expires":"2025-06-29T08:12:34Z","lastChanged":"2025-06-04T12:34:56Z","cart":[{"productId":"prod-123","count":2},{"productId":"prod-456","count":1}],"saved":[{"productId":"prod-789","count":1}],"checkout":[{"productId":"prod-123","count":1},{"productId":"prod-456","count":1}]}
nextTokenstring(Next token)

The token, which can be used to retrieve the next page of data.

errorobject(The error response)

Details of the error that occurred during the API request, including error code and message. This field is only present when the request results in an error.

Response
application/json
{
  "data": {
    "expires": "2025-06-29T08:12:34Z",
    "lastChanged": "2025-06-04T12:34:56Z",
    "cart": [ … ],
    "saved": [ … ],
    "checkout": [ … ]
  }
}

Product Details

Operations

Checkout Sessions

Operations

Basket Transfer

Operations

Basket Follow-up Operations

Operations

API information

Operations