Home > widget-integration > RecommendationAPI > buildRecommendationBodyPayload

RecommendationAPI.buildRecommendationBodyPayload() method

Builds and enhances the request body payload for recommendation API requests.

This method provides an extension point for modifying the recommendation request body before it's sent to the API. The default implementation returns the payload unchanged, serving as a pass-through that allows Technical Support teams to intercept and enhance the payload with shop-specific data, filters, or context.

Unlike query parameters (which are URL-based), the body payload contains the core recommendation context like product IDs, widget configuration, and customer data that determines which products to recommend.

Signature:

protected buildRecommendationBodyPayload(bodyPayload: RecommendationPayload): RecommendationPayload;

Parameters

Returns:

RecommendationPayload

Enhanced body payload with any shop-specific modifications applied. The returned payload will be serialized to JSON and sent as the HTTP POST body.

Remarks

The default implementation is intentionally minimal (pass-through), making this a pure extension point. Override this method to: - Add custom filtering criteria (tags, availability, price ranges) - Inject additional context data (customer segments, session info) - Modify recommendation algorithms or weights - Add shop-specific business rules

Common use cases include: - Excluding specific product types or tags from recommendations - Adding customer-specific context for personalization - Injecting A/B test parameters - Applying shop-specific inventory or availability filters

Performance note: Keep payload modifications lightweight to maintain fast API response times. Avoid heavy computations or synchronous API calls in this method.

Example 1

Override to add custom product filtering:

protected buildRecommendationBodyPayload(bodyPayload: RecommendationPayload): RecommendationPayload {
  const enhanced = super.buildRecommendationBodyPayload(bodyPayload);

  // Exclude out-of-stock and discontinued products
  enhanced.filters = {
    ...enhanced.filters,
    excludeTags: ['out-of-stock', 'discontinued', 'coming-soon'],
    inStock: true,
    published: true
  };

  return enhanced;
}

Example 2

Override to add customer personalization context:

protected buildRecommendationBodyPayload(bodyPayload: RecommendationPayload): RecommendationPayload {
  const enhanced = super.buildRecommendationBodyPayload(bodyPayload);

  // Add customer context for personalized recommendations
  const customer = this.platformLoader.platform.customer;
  if (customer) {
    enhanced.customerContext = {
      id: customer.id,
      segment: this.getCustomerSegment(customer),
      purchaseHistory: customer.ordersCount,
      preferredCategories: this.getCustomerPreferences(customer)
    };
  }

  return enhanced;
}

Example 3

Override to add price range filtering based on cart value:

protected buildRecommendationBodyPayload(bodyPayload: RecommendationPayload): RecommendationPayload {
  const enhanced = super.buildRecommendationBodyPayload(bodyPayload);

  // Add price filtering based on average cart value
  const cart = this.platformLoader.platform.cart;
  if (cart) {
    const avgItemPrice = cart.total_price / cart.item_count;

    // Recommend products within similar price range
    enhanced.filters = {
      ...enhanced.filters,
      minPrice: avgItemPrice * 0.7,
      maxPrice: avgItemPrice * 1.5
    };
  }

  return enhanced;
}

Example 4

Override to add A/B testing parameters:

protected buildRecommendationBodyPayload(bodyPayload: RecommendationPayload): RecommendationPayload {
  const enhanced = super.buildRecommendationBodyPayload(bodyPayload);

  // Add A/B test variant information
  enhanced.experimentId = this.getActiveExperimentId();
  enhanced.variant = this.getAssignedVariant();

  // Modify recommendation strategy based on variant
  if (enhanced.variant === 'similar-products') {
    enhanced.recommendationType = 'similarity-based';
  } else if (enhanced.variant === 'trending') {
    enhanced.recommendationType = 'popularity-based';
  }

  return enhanced;
}