Endpoints: Actions & recommendations

Fetches your active recommendations across all types (pricing, ads, inventory), newest first. Each carries its type, shop, status, expected uplift, and risk metrics. Use this to populate the main Actions dashboard, or filter by shop/region/platform/type.

Request body

RecommendationFilter

Response — Array of Recommendation

…and more — see the full schema in the OpenAPI spec.

Returns recommendations whose apply operation failed, paired with the captured failure reason. The failure is terminal (the recommendation is dismissed).

Request body — RecommendationFilter (same fields as above).

Response — Array of FailedRecommendation — all Recommendation fields plus failureReason (string) and failedAt (date).

Returns the state-change log for a recommendation — every transition (proposed → approved → executing → completed, or paused/stopped/rolled_back/rejected), who triggered it, and any captured reason.

Request body

RecommendationStateChangeLogFilter

Response — Array of RecommendationStateChangeLog — entries with fromStatus, toStatus, changedBy, reason, metadata, createdAt.

Fetches price-buffer (margin-defence) recommendations for Shopee or TikTok — each protects your margin against fee/cost increases by recommending a price change. Returns a summary per recommendation; call /items for per-product detail.

Request body

FetchPriceBufferDiscountRecommendationsRequest

Response — Array of PriceBufferDiscountRecommendationResponse — recommendationId, shopId, region, platform, status, expectedUpliftValue, plus a nested items summary. …and more — see the full schema in the OpenAPI spec.

Expands recommendations to per-item detail: current/proposed/promotion prices, discount %, the protection reason, and buyer-price impact.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of PriceBufferDiscountRecommendationItemResponse — recommendationId, itemId, unit count, current/proposed/promotion prices, discount %, reason (e.g. fee_increase, cost_increase), buyerPriceDelta, and cost-breakdown fields.

Per-variant (model) price breakdown for the recommended items: current/proposed/promotion prices and buyer-price delta.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of PriceBufferDiscountRecommendationModelResponse — recommendationId, itemId, modelId, current/proposed/promotion price, discount %, buyer-price delta.

Returns which of the given item ids already have an active (non-rejected) price-buffer recommendation, so a UI can pre-filter them from a "generate new" flow.

Request body

CheckPriceBufferDiscountDedupRequest

Response — Set<Long> — the subset of itemIds that already have an active recommendation (empty = all available).

Platform-neutral dedup: pass platform-native item ids (e.g. TikTok product ids as strings) instead of numeric Shopee item ids.

Request body

CheckPriceBufferDiscountPlatformDedupRequest

Response — Set<String> — the subset of platformItemIds that already have an active recommendation.

Fetches Shopee bundle-deal recommendations — product groupings to offer as a bundle to lift basket size and AOV. Returns a summary per recommendation; call /details or /items for expanded data.

Request body

BundleDealRecommendationFilter

Response — Array of BundleDealRecommendation — recommendationId, shopId, region, status, expected uplift, and the bundle structure. …and more — see the full schema in the OpenAPI spec.

Expands bundle recommendations: full bundle structure (items, variants, per-item pricing) and rationale.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of BundleDealRecommendationDetail — recommendationId, bundle name/description, bundled items with prices/discounts, expected basket impact, reason.

Per-item details within bundles: current vs bundled price, discount, margin impact, and contribution to uplift.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of BundleDealRecommendationItem — recommendationId, itemId, current/bundled price, discount %, estimated sales lift, margin delta.

Returns which item ids already have an active bundle-deal recommendation.

Request body

CheckBundleDealDedupRequest

Response — Set<Long> — the subset of itemIds that already have an active recommendation.

Fetches margin-defence actions for a Shopee shop facing an upcoming commission-rate increase. Each recommends a discount-trim or price-raise per item/variant to preserve the protected margin.

Request body

CommissionAdjustShopRequest

Response — Array of CommissionAdjustActionResponse — recommendationId, shopId, region, status, commissionEffectiveDate, protectedMarginPct, impacted items with margin snapshot and estimated profit impact, and per-model recommended lever. …and more — see the full schema in the OpenAPI spec.

Fetches Shopee product-boost recommendations — which products to boost in search/feed to increase visibility and sales. Call /items for the full product list.

Request body

BoostRecommendationFilter

Response — Array of BoostRecommendation — recommendationId, shopId, region, status, expected uplift, and the nested product list.

Expands boost recommendations to the product list, current metrics, and expected uplift.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of BoostRecommendationItem — recommendationId, itemId, current sales/profit, expected sales uplift %, estimated profit impact, and ranking.

Returns true if the shop already has a non-rejected boost recommendation — so a UI can gate the "Create new" control.

Request body

CheckBoostDedupRequest

Response — boolean — true if an active boost recommendation exists.

Fetches Shopee single-campaign ads recommendations — budget and bid adjustments to optimize ad-spend ROI. Each targets a specific campaign. Call /details or /keywords for expanded data.

Request body

ShopeeAdsRecommendationFilter

Response — Array of ShopeeAdsRecommendation — recommendationId, shopId, campaignId, status, current vs proposed budget/bids, expected ROAS/ROI uplift. …and more — see the full schema in the OpenAPI spec.

Expands a campaign ads recommendation: current vs proposed performance (spend, sales, ROAS), reason, confidence, and risk.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of ShopeeAdsRecommendationDetailResponse — recommendationId, current/proposed budget/bid/spend/sales/ROAS, expected uplift %, reason, confidence, risk.

For keyword-optimization recommendations: the keywords to add/modify/remove and their estimated impact on relevance and CPC.

Request body — Array of recommendation ids (integer; max 500).

Response — Array of ShopeeAdsRecommendationKeywordChange — recommendationId, keyword, action (add/modify/remove), current/proposed bid, estimated CPC impact, relevance score.

Returns true if the campaign already has a non-rejected ads recommendation.

Request body

CheckAdsDedupRequest

Response — boolean — true if an active recommendation exists for the campaign.

Returns true if the recommendation is in a state that can be applied/resumed (proposed/paused), false if it's mid-flight or terminal — so a UI can show a refresh prompt.

Request body

CheckAdsDedupRequest

Response — boolean — true if the recommendation can be applied/resumed.

Fetches margin-based target-ROAS recommendations for Shopee GMV-Max product campaigns. Each derives a ROAS target from product margin, break-even, and your desired net margin. Returns the recommendation plus current detail.

Request body

ShopeeAdsRecommendationFilter

Response — Array of TargetRoasRecommendationView — recommendation (full object), detail (current/proposed/break-even ROAS, margin %), and editedByUser flag.

Given a product margin and desired net margin, returns break-even ROAS and recommended target ROAS (and optionally the implied margin for a desired ROAS). No writes — backs the margin/ROAS slider.

Request body

TargetRoasPreviewRequest

Response — TargetRoasPreviewResponse — breakEvenRoas, recommendedRoasTarget, targetMarginInfeasible, impliedMarginForDesiredRoas, and a human-readable explanation.

Money-based sibling of preview: given a margin, absolute target profit, and ad spend, returns break-even ROAS and recommended target ROAS. No writes.

Request body

TargetProfitPreviewRequest

Response — TargetProfitPreviewResponse — breakEvenRoas, recommendedRoasTarget, targetProfitInfeasible, impliedProfitForDesiredRoas, explanation.

Same as target-ROAS fetch, for Shopee GMS (GMV-Max shop) campaigns.

Request body — ShopeeAdsRecommendationFilter (same fields as target-roas/fetch).

Response — Array of TargetRoasRecommendationView — recommendation + current detail + editedByUser flag.

The margin → target-ROAS preview for GMS campaigns. No writes.

Request body — TargetRoasPreviewRequest (same fields as target-roas/preview).

Response — TargetRoasPreviewResponse — break-even and recommended ROAS, feasibility, and explanation.

A price simulator for Shopee campaign enrollment: returns the lowest discounted price that keeps your target margin, whether it beats the 90-day low (Shopee's floor), and the full fee breakdown at that price. No writes.

Request body

CampaignEnrollmentEligibilityRequest

Response — CampaignEnrollmentEligibilityResponse — status (ELIGIBLE, NOT_LOWEST_IN_90D, INELIGIBLE_RATING, COGS_UNKNOWN, MARGIN_INFEASIBLE), recommendedDiscountedPrice, current price, minPrice90d, discount amount/%, target/shop/achieved margins, COGS + source, rating, cost breakdown, and explanation.

Returns the pre-computed eligibility pool for a shop (one row per item/model), refreshed hourly and on COGS write — browse every product's status and recommended discounted price without a per-item re-check.

Request body

CampaignEnrollmentShopRequest

Response — Array of ShopeeCampaignEnrollmentEligibility — itemId, modelId, status, recommendedDiscountedPrice, current price, minPrice90d, discount %, margins, COGS, rating, and fee breakdown.

Returns the shop-level campaign-join recommendation with its enrollable variants (the full export payload).

Request body

CampaignEnrollmentShopRequest

Response — Array of CampaignEnrollmentActionResponse — recommendationId, shopId, region, and enrollable variants with prices, discounts, and fee breakdown. …and more — see the full schema in the OpenAPI spec.

Fetches budget-adjust recommendations for budget-constrained TikTok GMV Max campaigns — an optimal daily budget to maximize profit given the constraint. Returns the recommendation plus current detail.

Request body

TikTokAdsRecommendationFilter

Response — Array of TikTokBudgetRecommendationView — recommendation (full object) and detail (current/proposed daily budget in ad-account currency, shop-currency equivalents, optimizer context).

Fetches margin-based target-ROAS recommendations for TikTok GMV Max campaigns (Minimum-ROAS bidding). Returns the recommendation plus current detail.

Request body — TikTokAdsRecommendationFilter (same fields as budget/fetch).

Response — Array of TikTokTargetRoasRecommendationView — recommendation (full object), detail (current/proposed ROI target, break-even ROAS, margin %), and editedByUser flag.

The margin → target-ROAS preview for TikTok. No writes.

Request body — TargetRoasPreviewRequest (shopId, region required; margin, targetMargin, desiredRoas optional).

Response — TargetRoasPreviewResponse — break-even and recommended ROAS, feasibility, and explanation.

Returns the current ads portfolio (if any) for a shop — the campaigns grouped for joint budget optimization, portfolio-level metrics, and allocation mode.

Query parameters

Response — AdsPortfolio (or null) — portfolioId, shopId, region, campaigns, portfolioStatus, totalBudget, performanceMetrics, mode.

Returns the campaigns added to a portfolio: id, name, current daily budget, and optimizer status.

Request body

FetchPortfolioCampaignsRequest

Response — Array of AdsPortfolioCampaign — campaignId, campaignName, currentDailyBudget, currency, optimizerStatus, addedAt.

Returns the per-campaign budget allocation a portfolio recommendation suggests — how much of the total budget to give each campaign to maximize overall profit. For preview before apply.

Query parameters

Response — Array of AdsPortfolioAllocation — campaignId, campaignName, currentDailyBudget, recommendedDailyBudget, budgetDelta, currency, expectedRoiUplift, confidence.

Returns experiments (A/B and multivariate tests) tied to recommendations and policies — each tracks expected uplift, dates, and a performance time series.

Request body

PolicyExperimentFilter

Response — Array of PolicyExperiment — experimentId, shopId, region, platform, name, description, status, expectedUpliftValue, startedAt, endedAt. …and more — see the full schema in the OpenAPI spec.

Returns policies — the levers and feature gates that govern which recommendations are generated, how they're applied, and when they expire. Parameters live in the history; call /history/fetch.

Request body

PolicyFilter

Response — Array of Policy — policyId, shopId, region, platform, isActive, status, currentHistoryId, createdAt, updatedAt.

Returns the audit trail for a policy: each version of its parameters, when it was valid, which experiment it was tied to, and who changed it.

Request body

PolicyHistoryFilter

Response — Array of PolicyHistory — policyHistoryId, policyId, controller, params (JSON), version, validFrom, validTo, isCurrent, experimentId, changedBy, changeReason, createdAt.