API endpoint reference

Every endpoint MerchDash’s public API answers, with its parameters, its response fields, and what it refuses. This page is generated from the API’s own contract, so it cannot drift from what the server actually does. For how to get a key and how the review model works, start at Public API.

All endpoints sit under https://app.merchdash.net/api/v1/ and take Authorization: Bearer md_live_…. Collections answer { data, nextCursor }; single resources answer { data }. Reads are served from MerchDash’s synced archive rather than live from Amazon.

Limits

Rate limits are per key and per account, and are described on the Public API page.

Every endpoint

GET /api/v1/profiles

Every marketplace this account owns and has synced.

Not "the marketplaces currently ticked in the switcher", the switcher is a UI preference. This is every advertising profile the account owns and has synced at least once, which is exactly the set of profileIds the other endpoints accept.

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending

GET /api/v1/campaigns

Campaigns with their metrics for a window.

One row per campaign in the marketplace's snapshot, including campaigns that delivered nothing in the window, their metrics are zero rather than absent. Archived campaigns are included; every row carries state, so filter on it after reading.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then campaignId ascending

GET /api/v1/portfolios

Portfolios with their budget caps.

One row per portfolio Amazon lists for the marketplace, including portfolios that hold no campaigns. No metric window: a portfolio has no report of its own, sum its campaigns from GET /api/v1/campaigns, which carry portfolioId. The budget cap is read as of the last sync; change it with the set_portfolio_budget operation of POST /api/v1/changes.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then portfolioId ascending

GET /api/v1/videos

The Sponsored Brands videos in the account's Creative Asset Library, with their names.

One row per video in Amazon's Creative Asset Library for the marketplace. Archived and deleted videos are left out. The library is copied during a sync, at most once a day, and only for a marketplace that runs Sponsored Brands ads; a video uploaded through MerchDash is listed straight away. name is what a rule's addVideoAd(video: "…") looks a video up by. A freshly uploaded video reads PROCESSING until refresh=true asks Amazon again (a rule run checks for itself).

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then assetId ascending

POST /api/v1/videos/uploads

Start uploading a Sponsored Brands video into the account's Creative Asset Library: returns the URL to PUT the file to.

Step 1 of 3. MerchDash asks Amazon for a pre-signed upload URL; step 2 is yours: PUT the file's bytes to uploadUrl (with the contentType given, no Authorization header, the URL carries its own signature) before expiresAt; step 3 is POST /api/v1/videos/uploads/:uploadId/complete. The file goes straight to Amazon's storage and never through MerchDash. Nothing is in the library until step 3. Once registered, a rule finds the video by name: ad_group.addVideoAd(video: "<name>", asin: "B0…") builds a Sponsored Brands video ad from it. An assistant without a way to send a file (no shell) cannot do step 2; the owner can upload in Amazon Ads instead, which MerchDash copies with its daily sync.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/videos/uploads/:uploadId/complete

Register an uploaded video in the Creative Asset Library, step 3 after PUTting the file.

Amazon processes the video for about a minute: ready turns true (status ACTIVE) in GET /api/v1/videos?refresh=true, and only then can an ad use it. specFailures lists what Amazon's Sponsored Brands video checks flagged (aspect ratio, length, resolution); a video with any is unlikely to pass Amazon's ad review. Repeating the call for the same uploadId answers the first result again rather than registering twice. Amazon has no way to delete a library video. An unknown or expired uploadId (55 minutes, or a MerchDash restart) is 404: start again.

Headers

Parameters

Request body

Response

Single resource, { data: { … } }.

GET /api/v1/images

The logos and custom images in an account's Creative Asset Library, by name.

What MerchDash holds of the image library. It is copied only when something asks for it, a rule's addSbAd(logo: "…"), the app, or refresh=true here, so it can be empty for an account that has images. refresh=true walks the library at Amazon first (spending one request of the key's write budget, like a live read). name is what addSbAd(logo: "<name>") looks a logo up by. Most Merch accounts have no logo: they have no Brand Registry.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: name ascending, ignoring case, then assetId

POST /api/v1/images/uploads

Start uploading a Sponsored Brands logo or custom image: returns the URL to PUT the file to.

The image twin of POST /api/v1/videos/uploads, the same three steps: start here, PUT the bytes to uploadUrl, then POST /api/v1/images/uploads/:uploadId/complete. A rule then uses a logo by name: ad_group.addSbAd(from: FIND_SB_AD("…"), logo: "<name>"). Amazon wants a logo of at least 400×400 pixels and a custom image of at least 1200×628; MerchDash cannot see the pixels here, so a smaller file is refused by Amazon later.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/images/uploads/:uploadId/complete

Register an uploaded logo or image in the Creative Asset Library, step 3 after PUTting the file.

Listed in GET /api/v1/images at once; ready turns true when Amazon has processed it. Repeating the call for the same uploadId answers the first result again. An unknown or expired uploadId is 404: start again.

Headers

Parameters

Request body

Response

Single resource, { data: { … } }.

GET /api/v1/stores

The account's Amazon Stores and their pages, the landing pages a Sponsored Brands ad may point to.

Asked of Amazon at request time (remembered for 30 minutes), so it spends one request of the key's write budget, like a live read. A page's name or url is what addSbAd(landingPage: "…") takes. Empty for an account without a store, which is most Merch accounts.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: as Amazon lists them

GET /api/v1/ad-groups

Ad groups with their metrics for a window.

One row per ad group in the snapshot. campaignId narrows the read to one campaign.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then adGroupId ascending

GET /api/v1/keywords

Keywords with their metrics for a window.

Positive keywords only. Negative keywords are read from GET /api/v1/negative-keywords. A Sponsored Brands keyword is listed once MerchDash has proven it positive (it delivered, or Amazon confirmed it): Amazon's old SB export mixed unmarked negatives in, and those are left out.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then keywordId ascending

GET /api/v1/targets

Targeting clauses with their metrics for a window.

Positive targeting clauses, product targets, categories, and an auto campaign's close-match / loose-match / substitutes / complements clauses. Negative targets are read from GET /api/v1/negative-targets. A Sponsored Brands clause is listed once MerchDash has proven it positive, as for keywords.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then targetId ascending

GET /api/v1/asins

Advertising performance aggregated per ASIN.

An ASIN-LEVEL AGGREGATION, not a list of product ads. One row per advertised ASIN, summing every ad of it across every campaign and ad group in the marketplace. ads is how many distinct product ads contributed. To act on one ad, find its adId with GET /api/v1/product-ads?asin=… (or ?adGroupId=…).

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: asin ascending

GET /api/v1/product-ads

Product ads (an ASIN/SKU in one ad group) with their metrics for a window.

One row per product ad in the snapshot, the adId that set_state with entityType: "productAd" needs. Sponsored Products and Sponsored Display only: Sponsored Brands ads are a different kind of entity and are not listed here. Archived ads are left out unless includeArchived=true. state is the ad's OWN state; whether it can deliver also depends on its ad group and campaign, which live answers. Amazon's Sponsored Display report does not name the ad, so an SD ad's metrics are its ad group's for its ASIN.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then adId ascending

GET /api/v1/sb-ads

Sponsored Brands ads (creatives) with their metrics for a window.

One row per Sponsored Brands ad in the snapshot. An SB ad is a creative, a headline, a brand, a landing page and up to five ASINs, or a video, and Amazon reports its traffic per ad, not per ASIN, so metrics belong to the ad as a whole. Metrics come from Amazon's per-ad report, which MerchDash keeps for the last 60 days; an ad that did not deliver in the window has zeros. Archived ads are left out unless includeArchived=true.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then adId ascending

GET /api/v1/sb-purchased-products

What shoppers bought after Sponsored Brands ads, per purchased ASIN, for a window.

One row per (campaign, ad group, purchased ASIN, attribution type) with purchases in the window, from Amazon's Sponsored Brands purchased-product report (kept for the last 60 days). The purchased ASIN is not always one the ad showed: attributionType says Promoted for an advertised product and Brand Halo for another product of the same brand. Sales-side only, Amazon reports no impressions, clicks or cost here.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then campaignId, adGroupId, purchasedAsin and attributionType ascending

GET /api/v1/negative-keywords

Negative keywords at campaign and ad-group scope.

One row per negative keyword in the snapshot. Sponsored Products negatives are swept from Amazon at both scopes on every state sweep. Amazon offers no Sponsored Brands list, so SB negatives are read from the SB targets export instead, which only the full sweep (about every ten days) fetches: one added in the Amazon console shows up after the next full sweep, and one removed there is archived by it. Archived negatives are left out unless includeArchived=true. Remove one with the remove_negative_keyword operation of POST /api/v1/changes.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then negativeKeywordId ascending

GET /api/v1/negative-targets

Negative product targets (excluded ASINs and brands) at campaign and ad-group scope.

One row per negative targeting clause in the snapshot, with the same sweep coverage and Sponsored Brands timing as GET /api/v1/negative-keywords. asin is set for an excluded ASIN, brandId for an excluded brand, and both are null for any other clause. Archived clauses are left out unless includeArchived=true. Remove one with the remove_negative_target operation of POST /api/v1/changes.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then negativeTargetId ascending

GET /api/v1/audiences

The audiences a marketplace's Sponsored Products campaigns can carry a bid adjustment for.

One row per audience Amazon offers for bid adjustments (its own, and the advertiser's Amazon Marketing Cloud ones), as last read. Served from MerchDash's stored copy and never calls Amazon, so a marketplace nothing has read audiences for yet lists none: a sync fills it. Use audienceId or name as the audience of the set_audience_bid operation.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then audienceId ascending

GET /api/v1/placements

Metrics per campaign and placement for a window, Sponsored Products and Sponsored Brands.

One row per (campaign, placement) that delivered in the window. For Sponsored Products, the placements the bid adjustments on GET /api/v1/campaigns act on. Sponsored Brands placements are listed too, with adProduct saying which is which; they have no placementCode, because set_placement_bid changes Sponsored Products campaigns only. A campaign with no placement traffic in the window has no rows.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId ascending, then campaignId ascending, then placement ascending

POST /api/v1/recommendations/bids

Amazon's suggested bids for keywords and auto-targeting clauses in an existing Sponsored Products ad group.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Amazon answers per theme (CONVERSION_OPPORTUNITIES always, plus an event such as PRIME_DAY around one), each with a low, a medium and a high suggested bid per expression and, when it has them, the weekly clicks and orders similar products got at each of those bids.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/recommendations/sb-bids

Amazon's suggested bids for keywords and product targets in a Sponsored Brands campaign.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). One answer per keyword and per target sent, in the order sent: Amazon's suggested bid with the low and high end of its range, or error when Amazon had no suggestion for it. Bids depend on the ad format, so say adFormat when the campaign's ads are video.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/recommendations/keywords

Amazon's ranked keyword suggestions, with suggested bids, for an ad group or a set of ASINs.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Send adGroupId for keywords that fit an existing Sponsored Products ad group, or asins for keywords that fit products you have not advertised yet, exactly one of the two.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/recommendations/categories

The product categories Amazon recommends targeting for a set of ASINs.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash).

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/recommendations/products

The products Amazon suggests targeting for a set of your advertised ASINs (Sponsored Products product targeting).

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Send the ASINs you advertise; Amazon answers with other products worth targeting with a product (ASIN) target, ranked in its own order, each with the themes that led it there. Only the first page of Amazon's answer is returned unless you page on with cursor. Send adGroupId to have each suggestion say whether that ad group already targets the product (read from MerchDash's snapshot of its targets, as a rule's alreadyTargeted is); without it alreadyTargeted is null. Page on until nextCursor is null; rank restarts at 1 on every page.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/recommendations/budgets

Amazon's suggested daily budget for campaigns, with what running out of budget cost them (Sponsored Products and Sponsored Brands).

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Pairs with set_campaign_budget. Amazon reads the last 7 days the campaign delivered in, about 3 days behind, a long-dormant campaign answers for an old week, so check windowEnd. GET /api/v1/campaigns has the suggestion as of the last sync.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/negative-brands/search

Find brands by keyword, Amazon's ids for the brands a Sponsored Products negative can exclude.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Returns Amazon's brand ids, what an excluded-brand negative targets. Pass one as brandId of the add_negative_target operation of POST /api/v1/changes to exclude the brand, and match it against the brandId of GET /api/v1/negative-targets to see whether it already is.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/eligibility

Whether ASINs can be advertised, and Amazon's reasons when they cannot.

A LIVE Amazon read: Amazon is asked at request time, through the marketplace's own connection and its own Amazon rate limit, so it is slower than a snapshot read and Amazon's answer may change from one call to the next. Nothing is written. Besides the read budget, each call spends one request of the key's write budget. Amazon's refusals come back in this API's own codes: a request Amazon rejects is validation, an id Amazon does not know (gone since the last sync) is not_found, Amazon throttling is rate_limited, Amazon being down or not answering within 30 seconds is temporarily_unavailable, and a connection Amazon no longer accepts is conflict (reconnect the account in MerchDash). Ask before creating product ads: an ineligible ASIN is refused by Amazon when the ad is created.

Headers

Request body

Response

Single resource, { data: { … } }.

GET /api/v1/search-terms

Shopper search terms with their metrics for a window.

One row per (campaign, ad group, keyword, search term) as Amazon reported it. For a product-targeting campaign the "search term" may be an ASIN rather than a shopper query, that is Amazon's own shape.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: profileId, campaignId, adGroupId, keywordId, searchTerm, all ascending

GET /api/v1/metrics/daily

Account totals for each day in a window.

One row per report day, summing every campaign in the marketplace, the same daily totals the MerchDash dashboard charts. This is the endpoint to ask "what did we spend on this day"; the entity reads above answer "what did this campaign do over this window", and summing a page of them is neither cheaper nor more correct. A day the archive holds nothing for is absent rather than zero, before the first sync covered it, no spend and no data look identical, and only GET /api/v1/sync/status can tell them apart. When the marketplace is one half of a linked pair the row is the sum of both, exactly as the dashboard shows it, so a row carries no profileId of its own. There is no paging: the whole window comes back in one response, which the 365-day window cap bounds at 365 rows.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: date ascending

GET /api/v1/sync/status

How current the synced archive is for a marketplace.

The freshness of the data every read above answers from, and whether proposals are unlocked, they are refused with sync_incomplete until its first full backfill has completed, and again while any full sync (a full re-sync included) is queued or running.

Parameters

Response

Single resource, { data: { … } }.

POST /api/v1/sync/start

Sync a marketplace now, the dashboard's Sync button.

Refreshes the last 7 days of reports and the current entities (a marketplace whose first backfill never completed runs that instead), on both accounts of a linked pair. Returns at once; poll GET /api/v1/sync/status until syncing is false. An account already syncing, or synced in the last 15 minutes (unless its first backfill is still owed, which has no cooldown), is not started, results says which; 429 rate_limited when all were recent. MerchDash's own writes reach the snapshot at once. Writes nothing to Amazon; starting one spends one request of the key's write budget.

Headers

Request body

Response

Single resource, { data: { … } }.

GET /api/v1/runs

Automation runs for a marketplace, newest activity first.

Every run MerchDash recorded for the marketplace, proposals made through this API and runs made by the account's own automation rules alike. trigger says which.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: most recent activity first, then runId, a run whose mode is review enters the list when it is approved, not when it was proposed

GET /api/v1/runs/:runId

One run, the polling target for the runId a proposal returned.

The same object the list returns. An unknown id and a run belonging to another account answer identically with 404 not_found: telling them apart would describe somebody else's account.

Parameters

Response

Single resource, { data: { … } }.

Fields: same as runs.list

GET /api/v1/runs/:runId/changes

The individual changes a run proposed, and what became of each.

One row per change the run itself proposed. The revert records a later revert writes are excluded: they belong to the revert, not to this run, and status: reverted on the original already says it happened.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: changeId ascending

GET /api/v1/changes

Change history: what MerchDash wrote to Amazon, for one entity or the whole marketplace.

Changes MerchDash wrote to Amazon, by rules, API proposals, bulk edits and reverts, newest first. Read it before changing a bid, so you do not undo a recent change or fight a rule. Pending and failed changes are in their run (GET /api/v1/runs); changes made in the Amazon console are not recorded.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: appliedAt descending, then changeId descending

POST /api/v1/changes

Propose a batch of bid, state, negative, campaign-setting and portfolio changes, for a human to approve, or to apply at once.

Writes a run and returns immediately; the writing to Amazon, when there is any, happens in the background. On a review key, the default, and what every key is until its owner says otherwise, nothing reaches Amazon here at all: the proposal waits in MerchDash's review queue until a human applies or turns it down there, or a key with the automation scope does so through POST /api/v1/runs/:runId/apply or /discard. On an auto-apply key, or with "applyMode": "auto", MerchDash applies the batch itself as soon as it is accepted. Either way GET /api/v1/runs/:runId reports the outcome. No key can revert a run.

Headers

Request body

Operation: set_bid

Set a keyword's or target's bid. Refused when the keyword or target, its ad group or its campaign is archived, Amazon takes no changes there.

Operation: set_state

Enable or pause an entity, a portfolio included, and a Sponsored Products negative keyword or negative target. Refused when the entity, its ad group or its campaign is archived, Amazon takes no changes there. A portfolio may have one state change waiting for approval at a time, a pending rename or budget change does not block it, and a negative one change (409 conflict).

Operation: set_auto_clause_bids

Set the bids of an auto campaign's four predefined targeting clauses, the same action as Actions → Adjust Auto Targeting Bid in the dashboard. This is the only operation that reads from Amazon while it compiles: an auto campaign's clauses appear in MerchDash's own snapshot only once they have delivered, so the clauses are enumerated live and the request expands into one target-bid change per clause it actually alters. Expect it to be slower than the other operations, and to answer 503 temporarily_unavailable when Amazon cannot be reached, no proposal is created in that case.

Operation: set_portfolio_budget

Set a portfolio's budget cap, the most all of its campaigns may spend together, including its type and dates. The cap is one object on Amazon, so it is recorded and reverted whole: History shows the cap before and after, and a revert restores the previous cap exactly. Because the whole cap is written, a portfolio may have one budget change waiting for approval at a time: while one is proposed (or being applied), another, this operation or remove_portfolio_budget_cap, is 409 conflict. If MerchDash has not yet read the portfolio's current cap (a portfolio synced before caps were, or created since the last sync), the change still applies but cannot be reverted, there is no previous cap to put back.

Operation: remove_portfolio_budget_cap

Take a portfolio's budget cap off, so its campaigns spend against their own daily budgets only. A revert puts the previous cap back. If MerchDash has not yet read the portfolio's current cap (a portfolio synced before caps were, or created since the last sync), the change still applies but cannot be reverted, there is no previous cap to put back.

Operation: rename_portfolio

Rename a portfolio.

Operation: add_negative_keyword

Add a negative keyword at campaign or ad-group scope. Sponsored Products and Sponsored Brands campaigns only, a Sponsored Display campaign is refused, as is an archived campaign or ad group.

Operation: add_negative_target

Add a negative product target, one ASIN, or a whole brand, at campaign or ad-group scope. Send exactly one of asin and brandId. Sponsored Products and Sponsored Brands campaigns only, a Sponsored Display campaign is refused, as is an archived campaign or ad group. An excluded brand is written as an ASIN_BRAND_SAME_AS clause; that write has not yet run against Amazon, so check the applied change in History the first time you use it.

Operation: remove_negative_keyword

Remove (archive) a negative keyword at either scope. Reverting it from History creates it again with the same text, match type and scope; a negative that was paused when removed is not revertible, since the re-created one would be enabled. Removing a negative and adding the same one back in one batch is refused. A negative may have one change (pause, enable or removal) waiting for approval at a time: while one is pending in another proposal, this is 409 conflict.

Operation: remove_negative_target

Remove (archive) a negative product target at either scope. Reverting re-creates an excluded ASIN or brand; a negative that was paused when removed can be removed but not reverted. Removing a negative and adding the same one back in one batch is refused. A negative may have one change (pause, enable or removal) waiting for approval at a time: while one is pending in another proposal, this is 409 conflict.

Operation: set_placement_bid

Set a Sponsored Products campaign's bid adjustment for one placement (placement + percent) or for several at once (placements), what a rule's setPlacementBid() does. Placements you do not name and the bidding strategy are kept. One such change per campaign per batch: a second set_placement_bid or set_bidding_strategy for the same campaign is refused, so name every placement you want in one change. placements becomes one change per placement in the review, none depending on another (leave one out, or revert one, and the rest stand); a placement already at its value is skipped. And one waiting for approval at a time: while a placement or bidding-strategy change for the campaign (from another batch or a rule run) is still proposed, a new one is 409 conflict naming that run, retry once that run has been applied or turned down (one being applied now only needs to finish).

Operation: set_audience_bid

Set a Sponsored Products campaign's bid adjustment for one audience, what a rule's setAudienceBid() does. Only that audience changes: the campaign's other audiences, placements and bidding strategy are kept as Amazon holds them when the change is written, so several audiences on one campaign can go in one batch (the same audience twice is refused). A percent of 0 removes the adjustment. Refused when the campaign is not Sponsored Products or is archived, when the adjustment already has that value, when the audience matches nothing the marketplace offers (or a name matches several, use the id), and when it would be the campaign's 11th (Amazon allows 10). A campaign may have one change to a given audience waiting for approval at a time: while one is proposed (from another batch or a rule run), a new one for the same audience is 409 conflict naming that run. Reverting puts the previous value back, or removes the adjustment if there was none. The Amazon request shape is taken from its OpenAPI spec and has not yet been confirmed against a live account.

Operation: set_campaign_budget

Set a campaign's daily budget, what a rule's setBudget() does on a campaign. Sponsored Products, Sponsored Brands and Sponsored Display. Refused when the campaign is archived, when its budget is not a daily one (a Sponsored Brands lifetime budget, Amazon cannot change a budget's type), and when the budget is already that amount. A campaign may have one budget change waiting for approval at a time: while one is proposed (from another batch or a rule run), a new one is 409 conflict naming that run, retry once that run has been applied or turned down (one being applied now only needs to finish). The proposed amount can be changed before it is applied with PATCH /api/v1/runs/:runId/changes/:changeId. Reverting puts the previous budget back.

Operation: set_bidding_strategy

Set a Sponsored Products campaign's bidding strategy (dynamic bids), what a rule's setBiddingStrategy() does. The placement bid adjustments are kept. A Sponsored Brands or Display campaign is refused (they have no such setting), as is an archived one and a strategy the campaign already has. It shares the campaign's one placement slot with set_placement_bid, because both write the whole placement map: one of the two per campaign per batch, and while either is waiting for approval for the campaign (from another batch or a rule run), a new one is 409 conflict naming that run. Reverting puts the previous strategy back, unless it was one MerchDash cannot set, such as Amazon's rule-based bidding.

Operation: rename_campaign

Rename a campaign, what a rule's rename() does on a campaign. Sponsored Products, Sponsored Brands and Sponsored Display. Refused when the campaign is archived or already has that exact name. A campaign may have one rename waiting for approval at a time (409 conflict). Reverting puts the previous name back.

Operation: set_campaign_portfolio

Move a campaign into a portfolio, or take it out of the one it is in, what a rule's moveToPortfolio() does. Refused when the campaign is archived or already where it is asked to go, and when the portfolio is archived, unknown, or belongs to the other Amazon account of a linked marketplace (a campaign can only be in a portfolio of its own account). A campaign may have one move waiting for approval at a time (409 conflict), and none is accepted into a portfolio that a waiting proposal archives. Reverting moves the campaign back to the portfolio it was in; a campaign that was in none cannot be reverted out again.

Operation: archive_portfolio

Archive a portfolio, what a rule's portfolio.archive() does. PERMANENT on Amazon: an archived portfolio cannot be enabled, renamed, given a cap or have campaigns moved into it, by anyone, ever again, and this change has no revert. It is its own operation, never a set_state value, so it cannot be sent by accident. Refused when the portfolio is already archived; when the same batch also changes it (its state, cap or name) or moves a campaign into it; and, 409 conflict, while another proposal waiting for approval does either. Equally, while an archive waits for approval nothing else for that portfolio is accepted.

Response

Single resource, { data: { … } }.

POST /api/v1/structures

Propose new campaigns, ad groups, product ads, keywords and targeting clauses for a human to approve.

Takes a nested graph and turns it into durable creation intents plus one run. On a review key, the default, nothing reaches Amazon here: the proposal is applied from the review queue (or by a key with the automation scope, through POST /api/v1/runs/:runId/apply), and only then is the structure built, parents before children. On an auto-apply key, or with "applyMode": "auto", MerchDash starts building it immediately, in that same dependency order. Because a create cannot be made idempotent by value, the id does not exist yet, each container is RESERVED under a stable identity at proposal time, so it is never built twice. A retry with the same Idempotency-Key replays the first answer. A second proposal naming a campaign, ad group or new portfolio that another run has already reserved is refused with 409 creation_conflict naming that run: retry once that run has been applied or turned down, or, for one Amazon is still creating, a little later, and an automation rule asking for it skips it as already pending.

Headers

What this endpoint will not do

• Builds Sponsored Products structures. Sponsored Brands only as far as an ad group that ALREADY EXISTS (by adGroupId, or by name inside an existing SB campaign): keywords or targets, never both in one SB ad group, and not the other kind than it already holds, because Amazon keeps the two apart, and no ASINs (an SB ad advertises through its creative). A new SB ad group needs an ad first, which this API cannot supply, so it is refused, and Amazon refuses a keyword in an existing SB ad group that has no ad yet. Sponsored Display is refused (an SD ad group needs a tactic).
• Auto-targeting campaigns take no keywords and no positive targeting clauses. Amazon creates their close match, loose match, substitutes and complements clauses with the ad group and lets nothing be added to them; only negatives are accepted there, through POST /api/v1/changes.
• Created entities start ENABLED unless a node says "state": "PAUSED", and campaigns are created with no start date, so a proposal begins spending when the human applies it.
• A campaign or ad group that already exists, named by id, or matched by the name you gave, is added to, never modified: its budget, bid, targeting and state are not changed here. alreadyPresent reports a container matched by name, with its id (one you named by id is not echoed back); it does not echo settings that were ignored. A request in which everything already exists proposes nothing and is refused with 400 validation ("Everything in this request already exists"), its bounded details listing the first of the matched entries in the alreadyPresent shape ({ kind, value, …Id }, never a { message, path } problem, which is how a client tells this refusal from any other validation), with no count, so a re-send of a structure that was already built is that refusal, not a second run.
• At most 2000 campaigns and ad groups, and 20000 ASINs, keywords and targeting clauses, per request.
• Character limits (label, names, keyword text, reason) count UTF-16 code units, as JavaScript's length does: an emoji or another character outside the Basic Multilingual Plane counts as two.

Request body

Node: campaign (new)

Node: campaign (existing)

Node: adGroup (new)

Node: adGroup (existing)

Node: keyword

Node: target

Response

Single resource, { data: { … } }.

GET /api/v1/rules

The marketplace's automation rules.

Every automation rule saved for the marketplace, with its script. The same rules the Automation page lists. Rules belong to one marketplace: the same rule in two marketplaces is two rules.

Parameters

Response

Collection, { data: [ … ], nextCursor }, and nextCursor is null on the last page.

Order: the order the Automation page shows them in. Not paginated: nextCursor is always null.

GET /api/v1/rules/:ruleId

One automation rule.

The same object the list returns. An unknown id and a rule belonging to another account both answer 404 not_found.

Parameters

Response

Single resource, { data: { … } }.

Fields: same as rules.list

POST /api/v1/rules

Create an automation rule.

Saves a rule the same way the Automation page's editor does. The script is checked first, and a script that would not run is refused with validation and the line it failed on. A rule name the marketplace already uses is refused with 409 conflict, and details carries the existing rule's id. Send an Idempotency-Key when retrying after a timeout so the exact first response is replayed.

Headers

Request body

Response

Single resource, { data: { … } }.

Fields: the created rule, same as rules.list

POST /api/v1/rules/copy

Copy saved rules into other marketplaces of the same account.

The dashboard's copy dialog. Only the rule travels, its script, schedule, mode and season, never its runs or History. A name a target marketplace already uses (compared trimmed, whitespace-collapsed and case-insensitively) is skipped and listed in skipped, never duplicated. A copy keeps the source rule's mode, so an auto rule is copied as auto. Copies start switched off unless activate is true, and even then a rule with no schedule or a script that would not run stays off. A schedule only an operator may set is copied as manual (so that copy stays off too). An unknown rule id is 404; a marketplace this account does not own is 404.

Headers

Request body

Response

Single resource, { data: { … } }.

PATCH /api/v1/rules/:ruleId

Edit an automation rule: its script, name, schedule, mode, category, season, or whether it is on.

Only the fields you send change. A new script is checked the same way a create checks it. Turning a rule on also re-checks its current script, so an old rule that no longer runs cannot be switched on. The edit applies from the rule's next run; a run already in flight keeps the script it started with. A run still queued for a slot picks up a new script when it starts, but whether it writes to Amazon (mode, or the apply it was asked with) was settled when it was accepted.

Headers

Parameters

Request body

Response

Single resource, { data: { … } }.

Fields: the updated rule, same as rules.list

DELETE /api/v1/rules/:ruleId

Delete an automation rule.

Stops a run of the rule that is waiting in the queue or in flight, its own evaluation and the writes it makes by itself; an apply of one of its reviews that a person approved is that person's and carries on, and removes the rule. Its runs and change history are kept, so every change it ever made stays readable and revertible in History. Pending reviews from the deleted rule leave the review queue; their run and proposed rows remain retained as audit data, but there is no longer a rule card from which to approve them, and POST /api/v1/runs/:runId/apply refuses them with 409 conflict (their creation reservations were released), discard them instead.

Parameters

Response

Single resource, { data: { … } }.

POST /api/v1/rules/:ruleId/run

Run an automation rule now, the same as pressing Run on the Automation page.

Starts the run in the background and returns immediately. Poll GET /api/v1/rules/:ruleId/run until status is no longer queued or running, then follow its runId. A rule in review mode proposes its changes, and they wait in the review queue; approve them with POST /api/v1/runs/:runId/apply. A rule in auto mode writes its changes to Amazon itself. Asking again while the rule is already queued or running attaches to that run and does not start a second one, except a run in the other mode, or one MerchDash is still finishing after an update or an interruption, which is 409 run_in_progress. Refused with sync_incomplete until the rule's marketplace, and its linked partner, which the run also evaluates and writes, has completed its first full backfill, and while a full sync (a full re-sync included) is queued or running in either; that gate is checked first, so during a full sync asking again under a new Idempotency-Key, or from a dashboard session, which sends none, is sync_incomplete even while the rule is queued or running (a retry with the same key still replays; or follow the run through GET /api/v1/rules/:ruleId/run). During a MerchDash deploy it is refused with 503 restarting before anything starts, so it is safe to send again.

Headers

Parameters

Request body

Response

Single resource, { data: { … } }.

Fields: same as rules.runStatus

POST /api/v1/rules/:ruleId/run/cancel

Take a rule's run out of the queue before it starts.

Only a run still WAITING for a run slot is removed, including one a MerchDash update set aside to start again (GET /api/v1/rules/:ruleId/run reads it queued). A run that has already started is NOT stopped, it is writing to the live Amazon account, and abandoning it halfway is an operator decision, and running says so. After a cancel, retrying POST /api/v1/rules/:ruleId/run with the same Idempotency-Key reports the cancelled run (status: "failed" with the reason in error) instead of starting it; a new key starts a new run. A cancelled apply run gives back the auto-apply token its start spent.

Headers

Parameters

Request body

Response

Single resource, { data: { … } }.

GET /api/v1/rules/:ruleId/run

The progress and outcome of the rule's latest manual run.

The polling target after POST /api/v1/rules/:ruleId/run. MerchDash keeps a finished run's outcome here for about 15 minutes. A live run remains visible across replicas and restarts through its durable execution marker. After the retained outcome expires, status is idle and runId is the rule's last recorded run, which GET /api/v1/runs/:runId still answers. Polling never uses up the result, so two callers polling the same rule both see it.

Parameters

Response

Single resource, { data: { … } }.

POST /api/v1/rules/validate

Check a rule script without saving or running it.

The same check the rule editor runs as you type, and the one POST /api/v1/rules and PATCH run before saving. A script that fails is still answered 200, with valid: false, because asking whether a script is valid is not a bad request. The language is described in /docs/language.md.

Headers

Request body

Response

Single resource, { data: { … } }.

POST /api/v1/rules/preview

Dry-run a script: what it would change right now, without saving it and without writing anything.

The rule editor's Dry run. The script is evaluated against the marketplace's synced data, and each change it proposes is checked against Amazon's current state, so a change that would do nothing is left out. Nothing is saved and nothing is written to Amazon. It runs in the background: poll GET /api/v1/rules/preview/:jobId for the result, usually within seconds and on a large account within minutes. A script that would not run is refused with validation before anything starts. Refused with sync_incomplete until the marketplace and its linked partner (both evaluated) have completed their first full backfill, and while a full sync (a full re-sync included) is queued or running in either, and with 503 restarting during a MerchDash deploy. Send an Idempotency-Key when retrying after a timeout so the first job id is replayed instead of starting the same dry-run twice.

Headers

Request body