Global Finalist2026 Amazon Ads Partner Awards

Developer API · Prompt library · 05 of 10

Top-of-search placement optimizer

Finds campaigns where top-of-search converts far better than the rest, proposes a placement bid change, and applies it when you say so.

Key scope
WRead-and-write key
Build time
45 minutes
Stack
Python script, run on demand

For: PPC managers tuning Sponsored Products by hand.

Paste this into Claude, ChatGPT or Cursor

Read https://www.sellermate.ai/api-docs first. It documents the SellerMate Public API: REST over HTTPS, X-API-Key auth, and every tool with its parameters is on that page. Every tool is POST https://api.sellermate.ai/public/v1/tools/{name} with a JSON body.

Build me a placement optimizer for Sponsored Products in one account.

- Pull the last 30 days of placement data with get_placement_performance
- For each campaign, compare ACoS and conversion rate at top of search versus product pages and rest of search
- Propose a placement bid adjustment: raise top-of-search by up to [25] points where its ACoS is at least [20]% better than the campaign average and it has at least [20] orders; lower it by up to 25 points where it is worse
- Print a table: campaign, current adjustment, proposed adjustment, reason
- With --apply, send the changes through update_campaign using dynamic_bidding.placementBidding, keeping all other settings. Without --apply, change nothing.

Resolve the account with get_user_context.

Rules:
- My key is in the SELLERMATE_API_KEY environment variable. Send it as the X-API-Key header. Never hard-code it or log it.
- Call get_user_context first and use the accounts it returns. Don't invent account ids.
- Report tools are paginated (page, page_size up to 500, pagination.hasMore). Walk every page.
- On a 429, wait for the Retry-After header and retry. On a 401 or 403, stop and tell me.
- Show me the plan and the code before running anything that writes.

Stack: Python 3 with requests.

Fill in anything in [brackets] before you paste, or leave it and the assistant will ask. The first line sends it to the docs, where every tool is listed.

What you get

  • A proposal table with a reason per campaign
  • Changes that only touch placement bidding and leave the rest of the campaign alone
  • An apply mode gated behind a flag, with guardrails checked by SellerMate on every write

Before you paste

  • Needs a read-and-write key. Limit it to the account you are tuning.
  • Placement adjustments are a percentage from 0 to 900. Your workspace bid guardrails still apply.
  • Run without --apply a few times and sanity-check the proposals against SellerMate.

Make it yours

Once it works, ask the assistant for one of these.

  • Do the same per ad group with update_ad_group default bids.
  • Schedule it weekly and post the proposal table to Slack for approval before applying.
Book Demo