Skip to main content

Work with live Amazon operations

Beyond the warehouse, the platform passes through to Amazon itself: live retail lookups, report generation, pricing, and advertising operations, all using the authorization your accounts already have through MixShift. You skip the developer applications entirely, and the token plumbing (minting, refresh, regional routing) is handled server-side.

Naming the merchant you mean

Every call below acts for one merchant. Two identifiers name one, and there is no merchantId parameter:

  • sellerId, the merchant token assigned by Amazon (the A... / ENTITY... string). Enough on its own only when the token maps to a single row; a seller trading in several marketplaces also needs marketplace.
  • legacySellerId, the integer MixShift seller id. Identifies exactly one merchant row and takes precedence. Prefer it when you have it.

GET /api/amazon/merchants returns both for every merchant you can act for, and GET /api/amazon/spapi/operations returns the same contract as a merchantIdentifiers object next to the operation list, so your code never has to hardcode it. Full detail, including why the same distinction matters when you query the warehouse: Identify a merchant.

Reading from Amazon

  • GET /api/amazon/merchants lists the merchants your credential can act for.
  • Cataloged operations: GET /api/amazon/spapi/operations and GET /api/amazon/ads/operations list every callable operation with its parameters; POST /api/amazon/spapi/call and POST /api/amazon/ads/call invoke one. The catalogs cover retail (catalog, inventory, FBA inbound shipments, orders, finances, fees, pricing, listings) and advertising (campaigns, ad groups, keywords, targets, budgets, recommendations).
  • FBA inbound shipments: read the shipments on their way to Amazon, not just the stock already received. You get shipment status and destination, the items on a shipment across a date range, and the item list for a single shipment id, which is what you need to reconcile what you sent against what Amazon received.
  • Reports: submit a report request, poll it, and download the document through /api/amazon/reports. Pricing has its own batch surface under /api/amazon/pricing. Report types Amazon has retired fail immediately and name the live replacement to use instead, rather than returning an opaque error from Amazon.

Updating Sponsored Brands entities

Changing an existing Sponsored Brands keyword, product target or negative target needs the ad group's id alongside the entity's own id. A campaign id does not substitute for it, and Amazon rejects the call without it. Negative targets are identified by targetId, not negativeTargetId, which Amazon rejects outright as an unrecognised field.

You do not have to remember either rule. Every operation publishes the fields it requires as requiredItemFields in the operations catalog (GET /api/amazon/ads/operations), so you can validate a body before calling, and the dry run now checks them too and names what is missing per operation rather than letting a bad body preview clean and fail against a live account.

Creating a Sponsored Brands ad

Building a full Sponsored Brands ad from nothing takes an ad group plus one ad-type-specific create, because Amazon exposes a separate endpoint per creative type rather than one shared ad shape. Build in order: create the campaign, create the ad group, then create the ad itself as brand video, video, product collection, or store spotlight, each with its own required creative fields.

Two acceptance rules Amazon enforces that a preview cannot check for you:

  • Every asset id (video, brand logo, custom image) must already exist in the Creative Asset Library. There is no upload operation on this surface, so a new video or logo goes in through the Amazon console first; the Creative Asset Library lookup below gives you the id afterward.
  • On the ad types that land on your Store, every advertised product must already appear on that Store page, or Amazon rejects the ad.

A dry run checks request shape only and never reaches Amazon, so neither rule above is validated until you commit. Amazon validates per ad, so commit one ad first and read its result before sending the rest of a batch.

Look up Creative Asset Library assets

Read the newest page of a profile's Creative Asset Library: asset ids, type, approval status, and file metadata (resolution and duration for video, dimensions and aspect ratio for images). Use it to find the id of something just uploaded in the console, or to check which ad programs an asset already qualifies for before building an ad around it.

It returns only the newest page, not the whole library, and the library is scoped per profile, not account-wide: a profile returning no assets does not mean the account has none.

Advertising writes, with the safety on

Writes to your ad accounts are opt-in (the credential needs the write scope) and default to a dry run:

  1. Call the write with default settings and you get a preview: validation, a snapshot of current state, and the exact change list. Nothing touches Amazon.
  2. Send the explicit commit flag to apply. Changes are capped per call, and every commit is audit-logged with the pre-write snapshot.

This is the same preview-then-confirm model the plugin uses; your own tools get it too.

Listing content writes

Product listing edits (title, highlights, bullets, description, search keywords, ingredients, item form, images) run as a strict two-call contract:

  1. Preview validates the change against Amazon for up to ten SKUs and returns a change-set id and hash. Nothing is applied.
  2. Commit takes that id and hash and replays exactly what was previewed. If anything drifted in between, the affected SKU fails closed instead of applying a stale change.

Identifiers, brand fields, compliance and safety attributes, variations, price, quantity, fulfillment, and deletes are refused by design. Images apply asynchronously on the Amazon side (Amazon re-hosts them), so verify by checking that the image slot changed and the listing has no new issues, not by comparing URLs.

Still have questions?
Ask Shifty

Shifty is the MixShift docs assistant. Pick a question or open the chat for anything else.

Back to Knowledge Base