Class AdsManager

Returns AdsManager

Returns Promise<CheckCreateGmsProductCampaignEligibilityResponse>

Response containing eligibility status

This API is used to check if the seller is eligible to create a GMS (Gross Merchandise Sales) Campaign. The response indicates eligibility and provides a reason if the seller is not eligible.

Possible reasons for ineligibility:

• active_campaign: There is already an existing GMS Campaign that is active
• not_whitelisted: The seller is not whitelisted to sz_shop_gmv_max_feature
• not_have_enough_sku: The seller does not have enough valid items in the shop
• exclusive_with_other_campaign: Seller is whitelisted to sz_ads_auto_boost

Returns Promise<CreateGmsProductCampaignResponse>

Response containing the created campaign ID

This API is used to create a GMS (Gross Merchandise Sales) Campaign.

ROAS Target behavior:

• No input or 0: GMV Max Auto Bidding (Shop)
• Greater than 0: GMV Max Custom ROAS (Shop)
• Value is rounded to 1 decimal place (e.g., 10.123456 becomes 10.1)

Returns Promise<CreateManualProductAdsResponse>

Response containing the created campaign ID

This API is used to create Manual Selection Product Ads, which allow you to manually select products, keywords, and bidding strategies for your advertising campaigns.

For manual bidding mode, you must specify selected_keywords and/or discovery_ads_locations. For auto bidding mode, you can set the roas_target parameter.

Returns Promise<EditGmsItemProductCampaignResponse>

Response containing the campaign ID

This API is used to add or remove items from a GMS Campaign. You can add or remove between 1 and 30 items per request.

Returns Promise<EditGmsProductCampaignResponse>

Response containing the campaign ID

This API is used to edit existing GMS Campaign settings such as budget, campaign duration, and ROAS target.

Returns Promise<EditManualProductAdKeywordsResponse>

Response containing the campaign ID

This API is used to edit keywords for Manual Selection Product Ads. You can add new keywords, edit existing keywords, or delete keywords.

Returns Promise<EditManualProductAdsResponse>

Response containing the campaign ID

This API is used to edit existing Manual Selection Product Ads. You can update various campaign settings including budget, duration, bidding settings, and ad placement locations.

Returns Promise<GetAdsFacilShopRateResponse>

Response containing the shop rate

This API is used to get the shop rate for the Ads Facil Program, which is a special advertising program available in certain regions.

Returns Promise<GetAllCpcAdsDailyPerformanceResponse>

Response containing daily performance metrics

This API is used to get Shop level CPC ads multiple-days daily performance. The date range must be today or earlier than today (up to 6 months ago), and cannot exceed 1 month. Start date must be earlier than end date and cannot be equal to end date.

The response includes an array of daily performance metrics with the following details for each day:

• date: The date the performance record belongs to
• impression: Number of times buyers see ads
• clicks: Total number of clicks on the ad
• ctr: Click-through rate (Clicks / Impressions)
• direct_order: Orders placed within 7 days after clicking on the clicked ad
• broad_order: Orders placed within 7 days after clicking on any ad from the same shop
• direct_conversions: Direct conversion rate (clicked ad orders / total clicks)
• broad_conversions: Broad conversion rate (any shop orders / total clicks)
• direct_item_sold: Items sold from the clicked ad
• broad_item_sold: Items sold from the shop after any ad click
• direct_gmv: Total sales from the clicked ad
• broad_gmv: Total sales from the shop after any ad click
• expense: Ad expenditure
• cost_per_conversion: Average cost per sales conversion
• direct_roas: Direct return on ad spend (direct GMV / expense)
• broad_roas: Broad return on ad spend (broad GMV / expense)

Use this API to analyze daily ad performance trends over a time period.

Returns Promise<GetAllCpcAdsHourlyPerformanceResponse>

Response containing hourly performance metrics

This API is used to get Shop level CPC ads single-date hourly performance. The date must be today or earlier than today (up to 6 months ago).

The response includes an array of hourly performance metrics with the following details for each hour:

• hour: The hour the performance record belongs to
• date: The date the performance record belongs to
• impression: Number of times buyers see ads
• clicks: Total number of clicks on the ad
• ctr: Click-through rate (Clicks / Impressions)
• direct_order: Orders placed within 7 days after clicking on the clicked ad
• broad_order: Orders placed within 7 days after clicking on any ad from the same shop
• direct_conversions: Direct conversion rate (clicked ad orders / total clicks)
• broad_conversions: Broad conversion rate (any shop orders / total clicks)
• direct_item_sold: Items sold from the clicked ad
• broad_item_sold: Items sold from the shop after any ad click
• direct_gmv: Total sales from the clicked ad
• broad_gmv: Total sales from the shop after any ad click
• expense: Ad expenditure
• cost_per_conversion: Average cost per sales conversion
• direct_roas: Direct return on ad spend (direct GMV / expense)
• broad_roas: Broad return on ad spend (broad GMV / expense)

Use this API to analyze hourly ad performance patterns for optimization.

Returns Promise<GetCreateProductAdBudgetSuggestionResponse>

Response containing budget suggestions

This API is used to get budget suggestions before creating product ads. The suggestions include minimum, maximum, and recommended budget values based on the campaign parameters.

Returns Promise<GetGmsCampaignPerformanceResponse>

Response containing campaign performance data

This API is used to get performance data for a GMS Campaign. The date range can span up to 3 months and go back up to 6 months from today.

Performance metrics include impressions, clicks, CTR, expense, GMV, ROAS, and orders.

Returns Promise<GetGmsItemPerformanceResponse>

Response containing item performance data

This API is used to get performance data for items in a GMS Campaign. The response is sorted by item_id and only items with performance data are returned.

The date range can span up to 3 months and go back up to 6 months from today. Results are paginated with offset and limit parameters.

Returns Promise<GetProductCampaignDailyPerformanceResponse>

Response containing detailed campaign performance metrics

This API is used to get product-level ads performance data across multiple days. The date range must be today or earlier than today (up to 6 months ago), and cannot exceed 1 month. Start date must be earlier than end date and cannot be equal to end date.

The response is structured hierarchically with:

• shop_id and region information
• Detailed campaign list with campaign_id, ad_type, campaign_placement, and ad_name
• Comprehensive daily metrics for each campaign including:
  • Impressions, clicks, and CTR
  • Expense (ad spend)
  • Direct and broad performance metrics (orders, GMV, ROI)
  • Conversion rates and cost efficiency metrics

Direct metrics refer to performance of the advertised product specifically, while broad metrics account for any purchases from the shop after an ad click.

Use this API to analyze campaign effectiveness at the product level and optimize your advertising strategy based on detailed performance data.

Returns Promise<GetProductCampaignHourlyPerformanceResponse>

Response containing detailed hourly campaign performance metrics

This API is used to get product-level ads hourly performance data for a single day. The date must be today or earlier than today (up to 6 months ago).

The response is structured hierarchically with:

• shop_id and region information
• Detailed campaign list with campaign_id, ad_type, campaign_placement, and ad_name
• Comprehensive hourly metrics for each campaign including:
  • Hour the performance record belongs to
  • Impressions, clicks, and CTR
  • Expense (ad spend)
  • Direct and broad performance metrics (orders, GMV, ROI)
  • Conversion rates and cost efficiency metrics

Direct metrics refer to performance of the advertised product specifically, while broad metrics account for any purchases from the shop after an ad click.

Use this API to analyze hourly campaign patterns and performance fluctuations throughout the day to optimize timing of ad campaigns and budget allocation.

Returns Promise<GetProductLevelCampaignIdListResponse>

Response containing campaign IDs and pagination info

This API is used to fetch all product campaign IDs displayed on the advertiser platform for a specific shop. The results can be filtered by ad type and paginated using offset and limit parameters.

The response contains:

• shop_id: The unique identifier for the shop
• region: The region where the shop is located
• has_next_page: Indicates if there are more campaigns on the next page
• campaign_list: List of campaigns with ad_type and campaign_id

Use this API to retrieve campaign IDs that can then be used with other APIs like getProductCampaignDailyPerformance or getProductCampaignHourlyPerformance to fetch detailed performance metrics.

Returns Promise<GetProductLevelCampaignSettingInfoResponse>

Response containing detailed campaign settings

This API is used to retrieve detailed configuration settings for product-level ad campaigns. Depending on the info_type_list parameter, different types of information will be returned:

Info type 1 (Common Info) includes:

• Ad type (auto or manual)
• Ad name and status
• Bidding method and placement
• Campaign budget and duration
• List of item IDs in the campaign

Info type 2 (Manual Bidding Info) includes:

• Enhanced CPC setting
• Selected keywords with match types and bid prices
• Discovery ads placement settings

Info type 3 (Auto Bidding Info) includes:

• ROAS (Return on Ad Spend) target

Info type 4 (Auto Product Ads Info) includes:

• Product name and status
• Item IDs

Use this API to analyze and understand the detailed settings of your ad campaigns, which can help with optimization and decision-making for future campaign management.

Returns Promise<GetProductRecommendedRoiTargetResponse>

Response containing recommended ROI targets

This API is used to get recommended Return on Investment (ROI) target values for a product's ad campaign. These recommendations help sellers set competitive ROI targets for their advertising campaigns.

The response includes three recommendation levels:

• Lower bound: A more competitive target (e.g., value=3.5, percentile=80) that makes the ad more competitive than 80% of similar ads.

• Exact (mid-level): A balanced target (e.g., value=5.9, percentile=50) that makes the ad more competitive than 50% of similar ads.

• Upper bound: A less competitive target (e.g., value=10.8, percentile=20) that makes the ad more competitive than 20% of similar ads.

Each recommendation includes:

• value: The recommended ROI target value
• percentile: Indicates how competitive this target is compared to similar ads

Use this API to help determine optimal ROI targets for your advertising strategy based on competitive marketplace data.

Returns Promise<GetRecommendedItemListResponse>

Response containing recommended items

This API is used to get the list of recommended SKU (Shop level) with the corresponding tag, i.e top search/best selling/best ROI tag.

The response includes an array of items with the following details for each item:

• item_id: Recommended SKU's item id
• item_status_list: Status of items (indicates whether an item is eligible for ads or not)
• sku_tag_list: Tags such as "best selling", "best ROI", "top search"
• ongoing_ad_type_list: Current status of ads on this item (e.g., search ads, discovery ads)

Use this API to identify high-potential items for advertising campaigns.

Returns Promise<GetRecommendedKeywordListResponse>

Response containing recommended keywords

This API is used to get the list of recommended keywords by item and optionally a search keyword.

The response includes:

• item_id: The item ID for which keywords are recommended
• input_keyword: The keyword provided in the request (if any)
• suggested_keywords: List of suggested keywords with quality score, search volume, and suggested bid

Use this API to get keyword suggestions to improve item discoverability in search results.

Returns Promise<GetShopToggleInfoResponse>

Response containing toggle statuses

This API returns the seller's toggle status information indicating whether certain features are enabled or disabled at the shop level.

The response includes:

• data_timestamp: The time when the information was retrieved
• auto_top_up: Whether automatic top-up is enabled (true) or disabled (false)
• campaign_surge: Whether campaign surge is enabled (true) or disabled (false)

These settings affect how ads campaigns are managed and funded.

Returns Promise<GetTotalBalanceResponse>

Response containing the total balance and timestamp

This API returns the seller's real-time total balance of their ads credit, including both paid credits and free credits.

The response includes:

• data_timestamp: The time when the balance snapshot was taken
• total_balance: The total ads credit balance

Note: This balance is real-time and represents the current available credit that can be used for advertising campaigns.

Returns Promise<ListGmsUserDeletedItemResponse>

Response containing deleted item IDs

This API is used to list items that have been removed from a GMS Campaign by the seller. Results are paginated with offset and limit parameters.