Fetch product recommendations

Use the productRecommendations query to retrieve product recommendations for the authenticated user's active cart. This API supports headless checkout flows where recommendations are displayed and added to the cart outside of the AppDirect-hosted checkout UI.

For an overview of the product recommendations capability in Checkout v2, see the release notes for Product Recommendations in Checkout v2.

The server resolves cart contents and vendor integration details from the active cart. You do not need to send cart item identifiers or vendor integration hints in the request.

Query:

query productRecommendations($input: ProductRecommendationsInput!) {
  productRecommendations(input: $input) {
    category
    source
    sourceMetadata {
      trackerId
    }
    recommendedItem {
      editionId
      pricingPlanId
    }
    product {
      id
      name
      type
      vendorName
      storefrontUrl
      iconUrl
      editions {
        id
        name
        pricingPlans {
          id
        }
      }
    }
    pricing {
      startingPrice {
        unit
        billingFrequency
        amount {
          currency
          value
        }
      }
    }
    reviewStats {
      reviewCount
      averageRating
    }
  }
}

Sample arguments:

For a generic recommendation request

{
  "input": {
    "locale": "en-US",
    "context": "GENERIC",
    "cartDetails": {
      "cartId": "65117cd8ce3df31e68af9446"
    }
  }
}

For order preview context (persists recommended items on the cart before returning)

{
  "input": {
    "locale": "en-US",
    "context": "ORDER_PREVIEW",
    "cartDetails": {
      "cartId": "65117cd8ce3df31e68af9446"
    }
  }
}

When cartDetails is omitted, the server uses the authenticated user's active cart

{
  "input": {
    "locale": "en-US",
    "context": "ORDER_PREVIEW"
  }
}

Input fields

Field	Required	Description
locale	Yes	Preferred locale for product details (for example, en-US).
context	Yes	Recommendation context. Supported values: GENERIC, ORDER_PREVIEW, RENEWAL_ORDER_PREVIEW.
cartDetails.cartId	No	Optional cart identifier. When provided, it must match the authenticated user's active cart.

Sample output

Response shape varies by source. The examples below show the two supported providers.

CO_PURCHASE response

{
  "data": {
    "productRecommendations": [
      {
        "category": "CROSS_SELL",
        "source": "CO_PURCHASE",
        "product": {
          "id": "265a9219-42c2-4e08-b207-546c6fed50b9",
          "name": "Test Product - Uday",
          "iconUrl": null,
          "storefrontUrl": "https://mycheckoutv2.test.devappdirect.me/apps/632258",
          "shortDescription": null,
          "description": null,
          "overviewImageUrl": null,
          "linkToProductWebsite": null,
          "editions": [
            {
              "id": "965ae889-ae12-4283-ad3a-fdfe73a98f3d",
              "pricingPlans": [
                {
                  "id": "81f41212-cbe2-4074-8cb7-5f4c879e9c9a",
                  "costs": [
                    {
                      "unit": "USER"
                    }
                  ]
                }
              ]
            }
          ]
        },
        "pricing": {
          "startingPrice": {
            "unit": null,
            "billingFrequency": "MONTHLY",
            "amount": [
              {
                "value": 7,
                "currency": "USD"
              }
            ]
          }
        },
        "sourceMetadata": null,
        "reviewStats": {
          "reviewCount": 2,
          "averageRating": 4
        },
        "recommendedItem": {
          "editionId": "eeaad611-3848-4663-b15d-1793a8ccc843",
          "pricingPlanId": "81f41212-cbe2-4074-8cb7-5f4c879e9c9a"
        }
      }
    ]
  }
}

ADOBE response

Adobe returns a tracking ID in sourceMetadata but does not populate recommendedItem.editionId or recommendedItem.pricingPlanId. Select the pricing plan from product.editions[].pricingPlans[] when adding the item to the cart.

{
  "data": {
    "productRecommendations": [
      {
        "category": "UPSELL",
        "source": "ADOBE",
        "sourceMetadata": {
          "trackerId": "rec-tracker-123"
        },
        "recommendedItem": {
          "editionId": null,
          "pricingPlanId": null
        },
        "product": {
          "id": "21cd2a44-213c-40bc-8d38-1c3117b4b7e4",
          "name": "Creative Cloud for Teams",
          "storefrontUrl": "https://marketplace-url/appdetail/21cd2a44-213c-40bc-8d38-1c3117b4b7e4",
          "editions": [
            {
              "id": "c424c2cc-ec60-4747-b347-3ac0dd41ddd3",
              "pricingPlans": [
                {
                  "id": "ae1acd7c-e161-4dc1-8b35-1865138874ce"
                }
              ]
            }
          ]
        },
        "pricing": {
          "startingPrice": {
            "billingFrequency": "MONTHLY",
            "amount": [
              {
                "currency": "USD",
                "value": 79.99
              }
            ]
          }
        },
        "reviewStats": {
          "reviewCount": 120,
          "averageRating": 4.5
        }
      }
    ]
  }
}

Using the response

• For CO_PURCHASE, use recommendedItem.pricingPlanId and recommendedItem.editionId directly when calling addRecommendationsToCart. sourceMetadata is typically null, so tracking fields are optional.
• For ADOBE, sourceMetadata.trackerId and source should be passed to addRecommendationsToCart as productRecommendationsTrackingId and productRecommendationsSource. Adobe does not return recommendedItem edition or pricing plan IDs, so select the appropriate pricingPlanId from product.editions[].pricingPlans[].
• category values are UPSELL, CROSS_SELL, and ADDON.
• source values are ADOBE and CO_PURCHASE.

Headless product recommendations flow

A typical headless flow looks like this:

1. Add one or more products to the cart using addItemsToCart.
2. Fetch recommendations using productRecommendations.
3. Add selected recommendations using addRecommendationsToCart.
4. Continue the checkout flow with the existing cart APIs such as removeItemsFromCart, validateCartDetails, apply/remove discount codes, and finalizeCart.

These APIs are currently available on the preview GraphQL endpoint:

https://marketplace-url/api/graphql/preview

Common errors

Error	Description
No active cart found for the user.	The authenticated user does not have an active cart. Add items to the cart before requesting recommendations.
Provided cartId ... does not match the active cart ...	The optional cartDetails.cartId value does not match the user's current active cart.

For more information on common GraphQL errors, refer to the section on Error handling.