SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-shopee-store-ads

linkfox-shopee-store-ads

Coding & development

View repository

Updated 10-16 00:00

About this skill

Shopee store Ads

Shopee Open Platform Ads module(23 APIs, excluding the soon-to-be-retired auto product ads).Depends on linkfox-shopee-store-auththe target store must have appType=ad authorization. Via POST /shopee/developerProxy pass in shopId(or merchantId）+ api/v2/ads/... path, the server automatically uses the AD app Token (Do notpass accessToken / appType）。

Call method

  • API endpoint：POST /shopee/developerProxy(different operations are distinguished by the request body; for complete parameters/responses/error codes see references/api.md）
  • Python script：python scripts/<脚本名>.py '<JSON 参数>' [--inline](available scripts are listed in the script overview above)
  • Cost constraints: this tool consumes compute; on failure/empty results do not automatically change keywords, paginate, or repeatedly probe; when continued searching is needed, first explain to the user that it will incur additional consumption.

Output strategy (script default behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-shopee-store-ads-<timestamp>.json（<cwd> is the working directory when the script is executed, in Claude Code this is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated by user task;Writing to /tmp is prohibited, if the current directory is not writable then report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, length of the largest list field + first 3 sample entries)
  • Add --inline to force full printing to stdout (also written to disk)

Data reading suggestions: first check the summary to judge whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, so as to avoid putting the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide resolving the issue:

Abnormal situations

  • API Key not configured: environment variable not configured LINKFOX_AGENT_API_KEY, and also not configured LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值", or content with a similar meaning.

Official reference

Ads module index:v2.ads.get_total_balance

Prerequisites (must read first)

  1. Run python scripts/check_auth_dependency.py；exit code 42 → first install linkfox-shopee-store-auth。
  2. Do notimplement authorization/token logic within this skill; authorization always goes through the auth skill.
  3. Calling business API before, use auth's authorized_stores.py to confirm the target store has appType=ad：
    • Only has appType=erp(or historical empty value) → cannottreat ads as authorized; guide authorize_url.py and pass appType=ad
    • both are missing → if the user only wants ads, just enable AD authorization (no need to enable ERP first)
  4. The Ads API also requires ad capability to be enabled on the Shopee side; not all sites/stores are available.
  5. Prohibitedto developerProxy pass accessToken or appType; use path api/v2/ads/** to route to AD on the server side.

Core Concepts

  • AD and ERP are separate: Ad Token and ERP Token are independent; a store existing in the list ≠ ads are authorized
  • Forwarding chain：developerProxy（shopId/merchantId + api/v2/ads/..., server injects AD token) → Ziniao shopee-proxy/ad/... → Shopee API
  • Balance：get_total_balance query ad account balance
  • Manual product ads：create_manual_product_ads → edit_manual_product_ads / edit_manual_product_ad_keywords
  • Performance reports：get_all_cpc_ads_*_performance、get_product_campaign_*_performance
  • GMS：create_gms_product_campaign and other series
  • Not included：create_auto_product_ads、edit_auto_product_ads(officially marked coming offline soon)
  • Affiliate marketing AMS(module=127) → not this skill

Available scripts (23 APIs in the Ads module)

Group Script
Account/Recommendations get_total_balance.py、get_shop_toggle_info.py、get_recommended_keyword_list.py、get_recommended_item_list.py
CPC performance get_all_cpc_ads_daily_performance.py、get_all_cpc_ads_hourly_performance.py
Product ads create_manual_product_ads.py、edit_manual_product_ads.py、get_product_level_campaign_id_list.py etc.
GMS create_gms_product_campaign.py、get_gms_campaign_performance.py etc.
General entry ads_api.py(JSON contains api field)

See references/api.mdfor the full list. Shared:_shopee_ads_common.py、_ads_endpoints.py、_ads_api_runner.py。

API documentation (by API)

Input parameters and response details are in references/apis/, the SKILL only keeps the index.

API Documentation
check_create_gms_product_campaign_eligibility references/apis/check-create-gms-product-campaign-eligibility.md
create_gms_product_campaign references/apis/create-gms-product-campaign.md
create_manual_product_ads references/apis/create-manual-product-ads.md
edit_gms_item_product_campaign references/apis/edit-gms-item-product-campaign.md
edit_gms_product_campaign references/apis/edit-gms-product-campaign.md
edit_manual_product_ad_keywords references/apis/edit-manual-product-ad-keywords.md
edit_manual_product_ads references/apis/edit-manual-product-ads.md
get_ads_facil_shop_rate references/apis/get-ads-facil-shop-rate.md
get_all_cpc_ads_daily_performance references/apis/get-all-cpc-ads-daily-performance.md
get_all_cpc_ads_hourly_performance references/apis/get-all-cpc-ads-hourly-performance.md
get_create_product_ad_budget_suggestion references/apis/get-create-product-ad-budget-suggestion.md
get_gms_campaign_performance references/apis/get-gms-campaign-performance.md
get_gms_item_performance references/apis/get-gms-item-performance.md
get_product_campaign_daily_performance references/apis/get-product-campaign-daily-performance.md
get_product_campaign_hourly_performance references/apis/get-product-campaign-hourly-performance.md
get_product_level_campaign_id_list references/apis/get-product-level-campaign-id-list.md
get_product_level_campaign_setting_info references/apis/get-product-level-campaign-setting-info.md
get_product_recommended_roi_target references/apis/get-product-recommended-roi-target.md
get_recommended_item_list references/apis/get-recommended-item-list.md
get_recommended_keyword_list references/apis/get-recommended-keyword-list.md
get_shop_toggle_info references/apis/get-shop-toggle-info.md
get_total_balance references/apis/get-total-balance.md
list_gms_user_deleted_item references/apis/list-gms-user-deleted-item.md

Module overview / Feedback see references/api.md。

Usage Scenarios

0. Confirm AD authorization (at the start of every task)

  1. auth：authorized_stores.py → find target shopId and appType=ad
  2. missing → auth:authorize_url.py pass appType=ad, prompt the user to completeadauthorization (URL valid for 1 hour)
  3. After completion, proceed to the following business scenarios; when receiving 1004 , first suspect missing AD authorization, do not force calls using ERP records

1. Query balance and recommendations

  1. get_total_balance.py
  2. get_recommended_item_list.py / get_recommended_keyword_list.py

2. Create manual product ads

  1. get_create_product_ad_budget_suggestion.py
  2. create_manual_product_ads.py pass complete body
  3. get_product_campaign_daily_performance.py query performance

Calling principles

  • First confirm appType=ad, then call the script
  • First look at developerProxy.httpStatus / gateway errcode, then read the *Response field
  • GET: put business parameters at the top level of JSON
  • POST: pass bodyfor complex APIs; for create/edit it is recommended to pass a unique reference_id to prevent duplicates
  • Each script docstring contains official documentation URL（module=117）
  • Do not first storeTokens fetch the raw token, and do not stuff accessToken

Not Applicable

  • Store authorization → linkfox-shopee-store-auth
  • Product listing → linkfox-shopee-store-product
  • Affiliate marketing AMS (module=127) → linkfox-shopee-store-ams
  • Amazon ads → linkfox-amazon-ads-* series

Compute consumption rules

No compute consumed.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.