Last updated Oct 24, 2023

Cart API

Overview

With the Cart API, Rokt partners can add additional products to a customer's cart within a transaction. The Cart API works with the Web SDK to help render frontend placements and provide hooks to update a customer's cart. There are two integrations needed to power upsells through Rokt:

Integrate your backend cart/checkout system with the Rokt Cart API (this documentation).
Integrate the Web SDK into your cart frontend.

A parking spot is a good example of a Rokt add-to-cart product. For example, a ticketing partner can upsell parking spots to their customers while they are purchasing event tickets. These parking spots are sourced through a third-party parking provider.

Minimal Integration

To fulfull customer orders, you need to integrate with the following hook and API endpoint.

Subscribe to V2_CART_ITEM_UPDATED events to be informed of when a user adds items to their cart.
Call /cart/confirm to confirm the successful purchase of the items.

Reserving Items

Some items needs to be reserved during checkout to guarantee that the inventory is still available when they eventually confirm. The following endpoints should be used for handling reservation.

Call /cart/reserve to reserve the items for a set period of time.
Optionally, call /cart/release to cancel a reservation and allow other customers to reserve those items.

Canceling Confirmed Items

The following endpoint is available for canceling items after they have been confirmed.

Call /confirmation/cancel

In-transaction request flow

To fulfill customer orders, partners need to adhere to the following transaction flow.

In-Transaction Request Flow

(Optional) Call /placements/any to determine whether there are any placements to display, so you can skip the cross-sell/upsell stage if not there are no relevant offers.
Based on whether /placements/any returns true or false, you can choose to show or skip the upsell page in the transaction flow. On the upsell page, you must initialize the Web SDK, which requests and displays available placements.
Once a customer opts in, the Web SDK informs the partner's frontend by sending the V2_CART_ITEM_UPDATED message. Then the normal purchase process proceeds.
(Optional) Call /cart/reserve to reserve the items for a set period of time during which the purchase must be completed and confirmed with Rokt.
Once a customer pays for the items, call /cart/confirm to confirm the successful purchase of the items. Rokt then informs the relevant provider of the products for fulfillment.
1. To cancel a reservation, call /cart/release. This is optional as reserved items that are not confirmed are automatically released after a timeout. This is suitable for high-traffic partners that require prompt release of reserved items.
2. To cancel a confirmed item, call /confirmation/cancel. This is suitable for partners who want to cancel an item after it has been confirmed.

Authentication

Please contact your Rokt account manager to set up authentication for you.

API Endpoints

POST Any Placements

Allows the partner to determine whether there are any placements to display, and potentially skip the upsell/cross-sell stage if applicable.

Description

To decide if it’s worth showing the page containing the Rokt add-to-cart placement. Based on whether this returns true or false the partner can choose to show or skip the upsell page in the transaction flow.

Sample request

POST /v1/placements/any
{
    "cartId": "1580265846172",
    "attributes": {
        "eventId": "1100526195FA115A",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36",
        "venueName": "Madison Square Garden",
        "eventdate": "20311212",
        "country": "US",
        "locale": "en-US"
    },
"pageIdentifier": "checkout.upsell"
}

Request

Path

POST /v1/Placements/any

Parameters

Name	In	Description	Required	Example
`rokt-api-key`	header	API authentication key	true	skeletonkey
`Content-Type`	header	Media type of request, 'application/json' is the only supported value at the moment		application/json
`Accept`	header	Expected media type of response, 'application/json' is the only supported value at the moment		application/json
`rokt-session-id`	header	SessionId used by Rokt internally for tracking, referral, logging and debugging. Optional for this endpoint (sessionId generated if not provided).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	Unique Rokt Tag ID	true	253_439d21r21r21321
`Accept-Language`	header	Expected locale of the consumer. This can be the full locale including language and country, or a neutral locale which only has the language. When locale is specified only placements and offers that match the locale are included for consideration.		en-US

Request body

{
  "cartId": "string",
  "pageIdentifier": "string",
  "url": "string",
  "attributes": {
    "attribute": "string"
  }
}

Response

200 OK

{
  "result": true
}

Error

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Reserve Cart Items

Allows the partner to reserve/hold the items for a set period of time during which the purchase must be completed and confirmed with Rokt. This allows partners to ensure stock and the price is locked in for the reservation duration.

Description

When the user has finalized the selection of catalog items but hasn't paid yet, reserving the cart items ensures supply of stock and locks in the price as per the returned values. If multiple cart items are passed into this method, some of them might be reserved successfully, and some might be rejected.

Sample request

    POST /v1/cart/reserve
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": 1
            }
        ]
    }

Request

Path

POST /v1/cart/reserve

Parameters

Name	In	Description	Required	Example
`rokt-api-key`	header	API authentication key	true	skeletonkey
`Content-Type`	header	Media type of request, 'application/json' is the only supported value at the moment		application/json
`Accept`	header	Expected media type of response, 'application/json' is the only supported value at the moment		application/json
`rokt-session-id`	header	SessionId used by Rokt internally for tracking, referral, logging and debugging.	true	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	Unique Rokt Tag ID	true	253_439d21r21r21321
`Accept-Language`	header	Expected locale of the consumer. This can be the full locale including language and country, or a neutral locale which only has the language. When locale is specified only placements and offers that match the locale are included for consideration.		en-US

Request body

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "quantity": 0
    }
  ],
  "isPayPalPayment": true,
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

Response

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0,
      "unitPrice": 0,
      "totalPrice": 0,
      "currency": "string",
      "expirationDateTimeUtc": "2025-10-04T10:00:00.000Z",
      "success": true
    }
  ],
  "payPalOrderId": "string"
}

Error

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Confirm Cart Items

Allows the partner to confirm the successful purchase of items. Rokt will then inform the relevant provider of the products for fulfillment.

Description

After the payment is processed for all the items in the cart. Rokt advises that this is called for all purchase events, including on all platforms, devices, environments (web/app), countries, and channels.

Sample request #1

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

Sample request #2

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": "15"
            }
        ]
    }

items collection should at least contain either

- `cartItemId` and `itemReservationId` or
- `cartItemId` and `quantity`

Request

Path

POST /v1/cart/confirm

Parameters

Name	In	Description	Required	Example
`rokt-api-key`	header	API authentication key	true	skeletonkey
`Content-Type`	header	Media type of request, 'application/json' is the only supported value at the moment		application/json
`Accept`	header	Expected media type of response, 'application/json' is the only supported value at the moment		application/json
`rokt-session-id`	header	SessionId used by Rokt internally for tracking, referral, logging and debugging. Optional on when no items included (sessionId generated if not provided).		ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	Unique Rokt Tag ID	true	253_439d21r21r21321
`Accept-Language`	header	Expected locale of the consumer. This can be the full locale including language and country, or a neutral locale which only has the language. When locale is specified only placements and offers that match the locale are included for consideration.		en-US

Request body

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0
    }
  ],
  "payPalOrderId": "string",
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

Response

200 OK

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "itemConfirmationId": "string",
      "itemConfirmationUrl": "string",
      "success": true
    }
  ]
}

Error

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Cancel Purchsed Item

Allows the partner to cancel a previously purchased (confirmed) item. Rokt will call the relevant provider to make a cancellation and relay back its response.

Description

Sample request

    POST /v1/confirmation/cancel
    {
        "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
    }

Request

Path

POST /v1/confirmation/cancel

Parameters

Name	In	Description	Required	Example
`rokt-api-key`	header	API authentication key	true	skeletonkey
`Content-Type`	header	Media type of request, 'application/json' is the only supported value at the moment		application/json
`Accept`	header	Expected media type of response, 'application/json' is the only supported value at the moment		application/json
`Accept-Language`	header	Expected locale of the consumer. This can be the full locale including language and country, or a neutral locale which only has the language. When locale is specified only placements and offers that match the locale are included for consideration.		en-US

Request body

{
  "itemReservationId": "string"
}

Response

200 OK

Error

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Release Cart Items

Allows the partner to cancel a reservation on a set of items. This is optional as reserved items that are not confirmed are automatically released after timeout. This is suitable for partners with highly bursty traffic requiring prompt release of reserved items.

Description

When the user removes a reserved item from their cart or cancels their cart/transaction altogether. Reserved cart items will eventually time out and be automatically released, but a partner may want to expedite this process if they have a bursty or high traffic environment to prevent premature or temporary exhaustion of supply.

Sample request

 POST /v1/cart/release
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

Request

Path

POST /v1/cart/release

Parameters

Name	In	Description	Required	Example
`rokt-api-key`	header	API authentication key	true	skeletonkey
`Content-Type`	header	Media type of request, 'application/json' is the only supported value at the moment		application/json
`Accept`	header	Expected media type of response, 'application/json' is the only supported value at the moment		application/json
`rokt-session-id`	header	SessionId used by Rokt internally for tracking, referral, logging and debugging.	true	ca75f48-ebbd-4d8e-83c3-fdd70893294d
`rokt-tag-id`	header	Unique Rokt Tag ID	true	253_439d21r21r21321
`Accept-Language`	header	Expected locale of the consumer. This can be the full locale including language and country, or a neutral locale which only has the language. When locale is specified only placements and offers that match the locale are included for consideration.		en-US

Request body

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string"
    }
  ],
  "attributes": {
    "attribute": "string"
  }
}

Response

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "success": true
    }
  ]
}

Error

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

Overview​

Minimal Integration​

Reserving Items​

Canceling Confirmed Items​

In-transaction request flow​

Authentication​

API Endpoints​

POST Any Placements​

Description​

Request​

Response​

Error​

POST Reserve Cart Items​

Description​

Request​

Response​

Error​

POST Confirm Cart Items​

Description​

Request​

Response​

Error​

POST Cancel Purchsed Item​

Description​

Request​

Response​

Error​

POST Release Cart Items​

Description​

Request​

Response​

Error​

Overview

Minimal Integration

Reserving Items

Canceling Confirmed Items

In-transaction request flow

Authentication

API Endpoints

POST Any Placements

Description

Request

Response

Error

POST Reserve Cart Items

Description

Request

Response

Error

POST Confirm Cart Items

Description

Request

Response

Error

POST Cancel Purchsed Item

Description

Request

Response

Error

POST Release Cart Items

Description

Request

Response

Error