Skip to content

ads.md

Latest commit

 

History

History
168 lines (123 loc) · 6.02 KB

ads.md

File metadata and controls

168 lines (123 loc) · 6.02 KB
Raw

AdsManager

The AdsManager handles Shopee advertising campaigns and promotions.

Overview

The AdsManager provides comprehensive methods for managing advertising campaigns on Shopee, including:

  • Creating and managing Auto Product Ads and Manual Product Ads
  • Creating and managing GMS (Gross Merchandise Sales) campaigns
  • Setting budgets, bids, and ROAS targets
  • Tracking ad performance (hourly and daily)
  • Managing ad keywords and targeting
  • Getting budget suggestions and ROI recommendations

Quick Start

// Get total balance
const balance = await sdk.ads.getTotalBalance();
console.log('Available balance:', balance.response.total_balance);

// Get recommended items for advertising
const recommendedItems = await sdk.ads.getRecommendedItemList();
console.log('Recommended items:', recommendedItems.response);

// Get campaign IDs
const campaigns = await sdk.ads.getProductLevelCampaignIdList({
  ad_type: 'all',
  offset: 0,
  limit: 50,
});

Important Notes

  1. Permissions Required: Advertising features require special permissions from Shopee
  2. Availability: Not all regions support the Ads API
  3. Reference ID: Use a unique reference_id for create/edit operations to prevent duplicates
  4. Date Format: All dates use DD-MM-YYYY format
  5. Documentation: Refer to Shopee Open API Ads documentation

API Methods

Account & Shop Information

  • getTotalBalance() - Get real-time ads credit balance
  • getShopToggleInfo() - Get shop toggle status (auto top-up, campaign surge)
  • getAdsFacilShopRate() - Get shop rate for Ads Facil Program

Recommendations & Suggestions

  • getRecommendedItemList() - Get recommended SKUs with tags (best selling, best ROI, top search)
  • getRecommendedKeywordList() - Get recommended keywords for an item
  • getProductRecommendedRoiTarget() - Get recommended ROI targets
  • getCreateProductAdBudgetSuggestion() - Get budget suggestions before creating ads

Auto Product Ads

⚠️ DEPRECATION WARNING: Auto Product Ads endpoints are being deprecated and will be removed in a future version. Please migrate to alternative advertising methods.

  • createAutoProductAds() - ⚠️ DEPRECATED - Create Auto Product Ads
  • editAutoProductAds() - ⚠️ DEPRECATED - Edit existing Auto Product Ads (budget, duration, status)

Manual Product Ads

  • createManualProductAds() - Create Manual Product Ads with full control
  • editManualProductAds() - Edit existing Manual Product Ads
  • editManualProductAdKeywords() - Add/edit/delete keywords for Manual Product Ads

GMS Campaigns

  • checkCreateGmsProductCampaignEligibility() - Check eligibility for creating GMS campaign
  • createGmsProductCampaign() - Create GMS campaign
  • editGmsProductCampaign() - Edit GMS campaign settings
  • editGmsItemProductCampaign() - Add/remove items from GMS campaign
  • listGmsUserDeletedItem() - List items removed from GMS campaign

Campaign Information

  • getProductLevelCampaignIdList() - Get list of all campaign IDs
  • getProductLevelCampaignSettingInfo() - Get detailed campaign settings (4 info types)

Performance Metrics

  • getAllCpcAdsHourlyPerformance() - Shop-level hourly performance
  • getAllCpcAdsDailyPerformance() - Shop-level daily performance
  • getProductCampaignDailyPerformance() - Product-level campaign daily performance
  • getProductCampaignHourlyPerformance() - Product-level campaign hourly performance
  • getGmsCampaignPerformance() - GMS campaign performance
  • getGmsItemPerformance() - GMS item-level performance

Example: Complete Campaign Lifecycle

// 1. Check balance
const balance = await sdk.ads.getTotalBalance();

// 2. Get recommended items
const items = await sdk.ads.getRecommendedItemList();
const topItem = items.response[0];

// 3. Get budget suggestion
const budget = await sdk.ads.getCreateProductAdBudgetSuggestion({
  reference_id: 'budget-001',
  product_selection: 'manual',
  campaign_placement: 'all',
  bidding_method: 'auto',
  item_id: topItem.item_id,
});

// 4. Create campaign
const campaign = await sdk.ads.createManualProductAds({
  reference_id: 'campaign-001',
  budget: budget.response.budget.recommended_budget || 100.0,
  start_date: '01-01-2024',
  bidding_method: 'auto',
  item_id: topItem.item_id,
  roas_target: 3.0,
});

// 5. Monitor performance
const perf = await sdk.ads.getProductCampaignDailyPerformance({
  start_date: '01-01-2024',
  end_date: '31-01-2024',
  campaign_id_list: campaign.response.campaign_id.toString(),
});

Best Practices

  1. Use Reference IDs - Generate unique IDs to prevent duplicate campaigns
  2. Check Eligibility - Use checkCreateGmsProductCampaignEligibility() before creating GMS campaigns
  3. Get Suggestions - Use budget and ROI suggestions for optimal campaign setup
  4. Monitor Regularly - Track performance metrics to optimize campaigns
  5. Optimize Keywords - Regularly review and update keywords based on performance

Performance Metrics Explained

Direct vs Broad Metrics

  • Direct: Performance of the advertised product specifically
  • Broad: Performance of any shop product after ad click

Key Metrics

  • CTR: Click-Through Rate (Clicks / Impressions × 100%)
  • CR: Conversion Rate (Conversions / Clicks × 100%)
  • ROAS: Return on Ad Spend (GMV / Expense)
  • CPC: Cost Per Click (Expense / Clicks)

Common Errors

Error Code Description Solution
error_permission_denied No ads permission Contact Shopee Support
ads.campaign.error_budget_range Invalid budget Use budget suggestion API
ads.campaign.error_date_setting Invalid date Ensure start >= today
ads.rate_limit.exceed_api Too many requests Reduce request rate

Resources

Note: This manager requires special permissions. Contact Shopee Partner Support to enable advertising features.