08 / Reference

Reference

Exact contracts for agents and developers. The tables on this page render from the running code, so they match what your agent sees over MCP.

• MCP server
• Tools
• Event types
• The handler
• Context by scope
• Mutations
• Store and console
• Webhooks
• Errors
• Limits
• Retention

MCP server

Setup is on Connect your agent. The changelog is also an MCP resource: resource://pulsify/changelog.md.

Most tools take account, an id from connection_status. Reads without it cover every connected account and label each row with its account. Writes with an account parameter require it when several accounts are connected; queue_mutations resolves ownership from each target's local identity.

Tools

Reads never change anything. Writes change something in Pulsify or queue a request to Amazon. If your only connection is a Vendor Central account, seller tools are hidden. The demo leaves out a few more.

archive_automation

Archive an automation. Deactivates it first if live, drops it from your list, and keeps its history. There is no hard delete.

connection_status

Whether the user's Amazon SP-API (selling) and Ads connections are live, per connected account. accounts lists every account: id (the account argument the other tools take), name, and both connections. For each connection: connected means authorized with Amazon; active means connected with billing in good standing. Check this first when events or automations seem inactive. ads.profiles lists the advertising profiles (marketplace, country, currency, account name and id); use them to scope the advertising read tools - profiles are per country and currency. entity_type is vendor for a Vendor Central account, which has no listings and no seller sales. changelog lists recent Pulsify product changes; the full history is the MCP resource resource://pulsify/changelog.md.

No parameters.

create_automation

Create a new draft automation for an Amazon event type. Inactive until you activate it. Returns its id. With more than one connected account, account names which one owns it. Use run_automation to dry-run the code before activating; its missing_field_reads catches a wrong payload shape.

describe_stream_type

The contract for automation code on one event type: what handle(event, context) receives, field by field, with units and nullability. Read it before writing or editing automation JavaScript. event is the payload Amazon sends, shown as a complete fixture because a live event carries only the fields that changed. context is the object your code reads and writes. Every currency value on context is in major units (15.27); list_listings reports the same figures in minor units (1527). Queue changes in context.mutations as { target, action, payload }; get_mutation_schema describes native payloads.

duplicate_automation

Copy any automation's code into a new draft for the same event type. Works on an active or a draft source. Returns the new id.

get_ads_summary

Advertising spend and attributed sales per marketplace profile. Money fields are integer minor units of each row's currency (USD cents; JPY whole yen); never sum across rows, the currencies differ. sales is Amazon's 7-day attributed figure, not shipped revenue, and recent days are still maturing (Amazon restates roughly the last 14), so the last days of a window read low and acos high - do not report that as a trend. acos is cost/sales, null when sales is 0. Empty rows mean unsynced data or no activity, never confirmed zero spend; check each row's latest_report_date and freshness.entities_synced_at for staleness, and connection_status for the full profile list. Windows cut on report date (profile-local), default trailing 30 days. Rows carry account_id and account_name, ordered by account then country; pass account to read one.

get_automation

One automation in full, including its JavaScript code.

get_event

The full payload (SP-API notification, Amazon Marketing Stream record, or a synthetic row with stream_type: null and synthetic: true: a polled listing-detail read, or Amazon's answer to a listing push Pulsify made) plus identity for one event, by id. Use this after list_events to see exactly what changed, or to replay the event against an automation.

get_mutation_schema

Payload schema for queue_mutations and automation { target, action, payload } output. Ads schemas describe native unified Sponsored Products updates, including nested bidding settings, and native create objects. For a creation, target_type is the parent: AdvertisingProfile for create_campaign, Campaign for create_ad_group and campaign-level create_target, AdGroup for create_ad and create_target. Pulsify derives adProduct, the parent ID and a campaign's marketplaceScope, so they are optional. Money uses major units of the target profile currency. Archives require {}. Listing attribute values come from get_product_type_schema. Native data and local identities are available from list_ads_entities and automation context.

get_product_type_schema

Get Amazon's full JSON Schema for a product type before writing listing patches or automation mutations. Includes required attributes, allowed values, conditional requirements and nested selectors. schema.properties describes /attributes/; required fields describe a full listing, not every patch. Values are specific to the target seller and marketplace and cached for 24 hours.

get_sales_summary

Your sales over a date range, one row per marketplace. revenue is in minor units of that row's currency (USD cents; JPY has no subunits, so whole yen) and rows are never summed together - an account spanning several currencies has no single revenue number, and converting is your call, not this tool's. Revenue is confirmed-order revenue: orders that are Shipped, Unshipped, or PartiallyShipped count, unless later Canceled - Amazon reports cancellation the same way whether it happened before or after shipping, so every canceled order is excluded, matched case-insensitively. Pending orders carry no line items and are excluded too. A return or refund after shipping is untracked and still counts as revenue, since no refund data is synced. freshness tells you how much is missing: orders_without_items counts in-window orders with no line items yet, and earliest_order_at and last_order_at mark the boundaries of synced order history. No rows means no confirmed sales in the window, which is not the same as zero sales - check freshness before reporting a number. A response with no freshness at all means the Amazon connection isn't set up; use connection_status for that. When compare_to_previous is set, previous is biased: the current window always holds more orders still Pending or awaiting item backfill than the settled window before it, so a flat month can render as a decline - each block's own orders_without_items lets you size the effect. since and until are ISO 8601 and cover whole days in the marketplace's local time; the default window is the trailing 30 days and the span is capped at 400. Rows carry account_id and account_name, one row per account and marketplace; freshness spans every account in the response. Pass account to read one.

list_ads_entities

Native observed Amazon Ads entities with stable local type/id targets, profile currency, pending requests and the latest provider outcome. Native data keeps Amazon's keys and major currency units, including nested bidding settings. Pass campaign_id to inspect its ad groups, ads or targets. All Target types are included, exclusions too: each target row states negative, level (AD_GROUP or CAMPAIGN) and its local parents. AdvertisingProfile rows are the parents of create_campaign. A creation's receipt sits on its parent, and its created names the new entity once Amazon confirms it. Use queue_mutations to create, update or archive; get_mutation_schema describes the payloads. Submitted requests are separate from observed data.

list_automation_actions

Decisions your automations recorded. For kind mutation, applied means the request passed validation; its separate mutation receipt reports provider acceptance, rejection, partial or uncertain outcomes. Most rows are one change to one target; rows with kind "warning" instead report a probable event-shape mismatch (missing_fields lists event keys the code read that the payload lacked). For a Listing or Ad target the row carries its asin, sku, marketplace_id, and title. value is in the marketplace's major currency unit: dollars for USD (list_listings reports cents); JPY has no subunits, so both report whole yen. status is queued, applied, failed, or blocked: withheld and never sent, because the source listing is blocked or the target's campaign has its Automation switch off (the switch also sets error_message). Filter by automation_id, status, or since (ISO8601). Rows carry account_id and account_name; pass account to read one account.

list_automations

Your automations, for each Amazon event type. Returns metadata only (id, event type, state, title) plus subscription: active means events are flowing, none means no subscription yet (expected for a draft, not a fault), failed means the subscription errored. Use get_automation for the code. Rows carry account_id and account_name; pass account to read one account.

list_campaigns

Your ad campaigns with a performance rollup over the window (default trailing 30 days, cut on profile-local report date). Money fields (budget_amount, cost, sales) are integer minor units of the row's currency. asin returns campaigns advertising that ASIN; the rollup stays campaign-level, so treat per-ASIN spend as exact only for single-product campaigns. sales is 7-day attributed and recent days are still maturing. acos is cost/sales, null when sales is 0. A campaign with no metrics in the window shows zeros; zeros everywhere plus a stale freshness block means unsynced data, not zero spend. Pass id to list_keywords as campaign_id to drill in. Rows carry account_id and account_name; pass account to read one account.

list_events

Recent Amazon events (SP-API notifications, Amazon Marketing Stream records, and synthetic rows with stream_type: null and synthetic: true: polled listing-detail reads) for this account, newest first by occurred_at. Each summary names the listing by ASIN, SKU, and title, with associated listings in a listings array. A shared event is counted once; SKU is null when targets have different SKUs. since and until are ISO 8601: a full timestamp is an exact instant, a bare date covers the whole UTC day, and until is exclusive at an instant but inclusive of its named day. total counts every event the filters matched, before limit, so counting questions never need to pull rows. Filter by stream type, exact ASIN or SKU, marketplace, or time; use get_event for a full payload. Rows carry account_id and account_name; pass account to read one account.

list_keywords

Your keywords (search targets) with a performance rollup over the window (default trailing 30 days). Default order is cost descending, so rows with high cost and sales 0 at the top are wasted spend. Money fields (bid, cost, sales) are integer minor units of the row's currency. sales is 7-day attributed and recent days are still maturing. acos is cost/sales, null when sales is 0. Filter by campaign_id (the id from list_campaigns), state, or match_type. Empty rows with a stale freshness block mean unsynced data, not zero activity. Keywords only; auto and product targets live in list_targets. Rows carry account_id and account_name; pass account to read one account.

list_listings

Your listings, found by keyword, ASIN, or SKU. keyword matches a substring of the title or SKU, or an exact ASIN; asin and sku are exact. A SKU is one listing per marketplace, so a SKU can return several rows: each row is a single (SKU, marketplace) listing that states its currency, with floor, ceiling, and price in minor units of it (USD cents; JPY has no subunits, so values are whole yen). conditionType is Amazon's full condition token; condition is its family. Never generalize a floor or ceiling (or its absence) across marketplaces. price, floor, ceiling, b2b_price, handling_time, restock_date and shipping_group are Amazon's last reading; mutations shows all queued requests and the latest submitted one, with each id, immutable payload, accepted (true, false) and Amazon's raw response, oldest first. Use patch_listing for Amazon attributes and update_listing to block or allow automated changes. status is null until a crawl reports listing status. active is true only when Amazon reports BUYABLE or DISCOVERABLE; it is false while status is unknown. data retains raw Amazon sources: FBA stock under fba.inventory, MFN attributes and availability under listings_item, and the latest stock notification envelopes under notifications. Keys and units are unchanged. since and until window on when the listing was added (ISO 8601; a bare date covers the whole UTC day). Ordering is newest first. total counts every match before limit. Filter by marketplace for EU accounts that span several. Rows carry account_id and account_name; pass account to read one account.

list_sales_by_listing

What sold, broken down by listing. One row per (ASIN, SKU, marketplace), so a SKU sold in two marketplaces is two rows in two currencies. revenue is in minor units of that row's currency (USD cents; JPY has no subunits, so whole yen). Revenue is confirmed-order revenue: Shipped, Unshipped, and PartiallyShipped count, unless later Canceled - Amazon reports cancellation the same way whether it happened before or after shipping, so every canceled order is excluded, matched case-insensitively. Pending orders carry no line items and are excluded too. A return or refund after shipping is untracked and still counts as revenue, since no refund data is synced. Ranking by revenue needs marketplace_id when the account spans several currencies, because yen and cents cannot be ordered against each other; order_by units works across all of them. title is null when the listing has since been deleted. freshness.earliest_order_at and freshness.last_order_at mark the boundaries of synced order history, and freshness.orders_without_items is the account-wide count of in-window orders with no line items yet, so an empty rows list can be told apart from an unsynced account. A response with no freshness at all means the Amazon connection isn't set up; use connection_status for that. since and until are ISO 8601 and cover whole days in the marketplace's local time; the default window is the trailing 30 days and the span is capped at 400. Rows carry account_id and account_name; freshness spans every account in the response. Pass account to read one.

list_streams

Your event subscriptions and whether each is live. status answers 'did the subscription actually happen': active means events are flowing, inactive means not subscribed, and pending means an Amazon Marketing Stream subscription is waiting on Amazon to confirm. Rows carry account_id and account_name; pass account to read one account.

list_targets

Your Sponsored Products targets of every kind: keywords, auto-targeting buckets (close-match, loose-match, substitutes, complements), and product targets, with a performance rollup over the window (default trailing 30 days). Auto and product targets are where auto campaigns spend; list_keywords shows keywords only. Default order is cost descending, so rows with high cost and sales 0 at the top are wasted spend. Money fields (bid, cost, sales) are integer minor units of the row's currency. sales is 7-day attributed and recent days are still maturing. acos is cost/sales, null when sales is 0. Filter by campaign_id (the id from list_campaigns), state, or target_type (keyword, auto, product, product_category). Empty rows with a stale freshness block mean unsynced data, not zero activity. Rows carry account_id and account_name; pass account to read one account.

patch_listing

Queue Amazon JSON Patch operations against one listing's attributes. Any writable attribute of its product type is supported; Amazon validates the attribute names and values. Each request creates its own immutable mutation, preserving the patches and their order. Each patch names op (add, replace, delete or merge), path (/attributes/) and the value required by Amazon's Product Type Definitions. Call get_product_type_schema to look up attribute shapes, allowed values and selectors before patching. Include the attribute's required selectors, such as marketplace_id, currency and audience for purchasable_offer. merge can update a pricing sub-attribute without resending other prices or bounds. product_type defaults to the listing's known product type, or PRODUCT when unknown. The request is queued immediately for a worker; list_listings shows queued mutations and the latest submitted one, with accepted and Amazon's raw response. Listing fields remain Amazon's last reading until a new reading arrives. A SKU in several marketplaces needs marketplace_id. With several connected accounts, account identifies whose listing to change.

query_data

Run one read-only SQL SELECT over the curated views below and get rows back. Prefer the dedicated
tools for lookups; use this for set questions where a join is the filter (e.g. ASINs with ad
spend but no organic sales). One statement, 3s timeout. The views cover every account you have
connected and expose account_id on every row so you can group or filter by account across connections
(or pass account to scope one call to one account). Results under 500 rows return inline. Larger
results (or queries with export: true) return a downloadable compressed CSV URL with column definitions
and a 5-row preview.

v_sales_lines - one row per order line, confirmed orders only (cancellations excluded; pending
orders carry no lines). Columns: order_id uuid, amazon_order_id text, sold_at timestamptz
(UTC), order_status text, is_business_order boolean, marketplace_id text, currency text, asin
text, sku text, title text (null when the listing is gone), price integer (line total, minor
units), quantity integer, account_id uuid. Seller accounts only.

v_ad_performance - one row per campaign per day. Columns: campaign_id uuid, campaign_name
text, campaign_state text, advertising_profile_id uuid, marketplace_id text, currency text,
report_date date (profile-local), impressions integer, clicks integer, cost integer (minor
units), attributed_sales_7d integer (minor units; 7-day ad-attributed sales, never comparable
to organic revenue), account_id uuid. The most recent ~14 days of report_date read artificially low
while Amazon restates them.

v_advertised_products - one row per product ad. Columns: campaign_id uuid, asin text, sku
text, state text (enabled/paused/archived), advertising_profile_id uuid, marketplace_id text,
account_id uuid. Spend is campaign-level; joining it through this view shares cost across every product
the campaign advertises.

v_listings - one row per SKU per marketplace: sku, asin, marketplace_id, title, account_id.
Presence means the listing record exists, not that it is buyable. Seller accounts only.

v_listing_mutations - one row per listing mutation: sku text, marketplace_id text, account_id uuid,
status text (queued/submitted), payload jsonb, submission_id text, submitted_at timestamptz,
created_at timestamptz. Seller accounts only.

v_catalog_items - one row per ASIN per marketplace: asin text, gtin text (GTIN-14, zero-padded,
null until the catalog sync lands), identifiers jsonb (identifier type to values, e.g. EAN, UPC,
GTIN, ISBN), marketplace_id text, title text, data jsonb (the full raw Amazon catalog payload
including dimensions, bullet points, and classifications), account_id uuid. Accessible to seller
and advertiser accounts.

v_marketplaces - reference data (23 rows): marketplace_id, name, country_code, domain_name,
currency.

v_search_query_performance - Amazon Brand Analytics Search Query Performance, seller accounts
only. One row per ASIN per search query per closed reporting window: report_period is WEEK/MONTH/QUARTER
and start_date/end_date bound that window. Grain matters — summing across periods, or across more
than one window of the same period, double- or triple-counts. Columns: asin text, report_period
text, start_date date, end_date date, search_query text, search_query_score bigint,
search_query_volume bigint, total_query_impression_count bigint, asin_impression_count bigint,
asin_impression_share numeric (0-1), total_click_count bigint, total_click_rate numeric (0-1),
asin_click_count bigint, asin_click_share numeric (0-1), total_median_click_price integer
(minor units), asin_median_click_price integer (minor units), total_cart_add_count bigint,
total_cart_add_rate numeric (0-1), asin_cart_add_count bigint, asin_cart_add_share numeric
(0-1), total_median_cart_add_price integer (minor units), asin_median_cart_add_price integer
(minor units), total_purchase_count bigint, total_purchase_rate numeric (0-1),
asin_purchase_count bigint, asin_purchase_share numeric (0-1), total_median_purchase_price
integer (minor units), asin_median_purchase_price integer (minor units), marketplace_id text,
account_id uuid. total_* columns describe the whole search query across every ASIN Amazon tracks
for it; asin_* columns describe this seller's ASIN specifically. Join v_marketplaces on
marketplace_id for currency.

v_coupon_performance - Amazon coupon performance, seller accounts only. One row per coupon per
marketplace. Totals are lifetime as of reported_at (the last refresh), not per day, and Amazon
finalizes them 1 or more days after the coupon ends. Columns: coupon_id text, name text,
website_message text, customer_segment text, discount_type text (PERCENT_OFF_LIST_PRICE or
AMOUNT_OFF_LIST_PRICE), discount_amount numeric, clips bigint, redemptions bigint, total_discount
bigint (minor units), sales bigint (minor units), budget bigint (minor units), budget_spent bigint
(minor units), budget_remaining bigint (minor units), budget_percentage_used numeric (0-100),
currency_code text, asins text[], starts_at timestamptz, ends_at timestamptz, reported_at
timestamptz, marketplace_id text, account_id uuid. Money is minor units of currency_code (JPY: whole
yen). discount_amount is a percentage (0-100) when discount_type is PERCENT_OFF_LIST_PRICE, and a
decimal amount in major units of currency_code when it is AMOUNT_OFF_LIST_PRICE, unlike the
minor-unit money columns. There is no per-ASIN breakdown: filter with asins @> ARRAY['B0...'] or
unnest it.

v_promotion_performance - Amazon promotion performance (Best Deal, Lightning Deal, Price Discount), seller accounts
only. Grain is promotion x ASIN: one row per included product, or one row with a null asin for a
promotion that has none. promotion_* columns are the promotion's own totals and repeat on every ASIN
row of that promotion, so summing them across rows multiplies them by the ASIN count. Sum product_*
columns instead, or SELECT DISTINCT promotion_id first. Totals are lifetime as of reported_at.
Columns: promotion_id text, promotion_name text, type text, status text, creation_channel text,
starts_at timestamptz, ends_at timestamptz, promotion_units_sold bigint, promotion_revenue bigint
(minor units), promotion_glance_views bigint, currency_code text, reported_at timestamptz, asin text,
product_name text, product_units_sold bigint, product_revenue bigint (minor units),
product_glance_views bigint, marketplace_id text, account_id uuid. Money is minor units of
currency_code (JPY: whole yen). Join v_listings, v_seller_economics or v_catalog_items on asin and
marketplace_id.

v_seller_economics - Data Kiosk Seller Economics, seller accounts only. One row per SKU per
day. Columns: sku text, asin text, date date, marketplace_id text, currency text,
ordered_product_sales bigint (minor units), net_product_sales bigint (minor units), referral_fee
bigint, fulfillment_fee bigint, storage_fee bigint, other_fees bigint, total_fees bigint, net_proceeds
bigint, net_proceeds_per_unit bigint, net_units_sold integer, units_ordered integer, units_refunded
integer, account_id uuid. Fees are signed - charges are negative, so net_product_sales + total_fees =
net_proceeds; add, don't subtract. referral_fee + fulfillment_fee + storage_fee + other_fees
always equals total_fees, where other_fees is whatever Amazon charged under a label the three
named columns don't recognise; a named column is null on a day carrying no such fee, and
storage is billed monthly so most days carry none. The most recent ~7 days restate while
Amazon settles them. Grain matters - several SKUs can share an ASIN, so grouping on asin, or
joining to order-line-grain v_sales_lines, double-counts unless this view is aggregated first.

v_vendor_metrics - Data Kiosk vendor analytics, for vendor accounts only. One row per view per
marketplace per day per ASIN, plus a row with a null asin carrying that day's catalog-wide
totals - filter on asin IS NOT NULL unless you want both grains. Columns: marketplace_id text,
view text (manufacturing or sourcing), date date, asin text, currency text, ordered_units
bigint, ordered_revenue bigint (minor units), unfilled_ordered_units bigint, net_ordered_gms
bigint (minor units), net_shipment_gms bigint (minor units), shipped_units bigint,
shipped_revenue bigint (minor units), average_selling_price bigint (minor units), glance_views
bigint, lost_featured_offer numeric, net_ppm numeric, shipped_cogs bigint (minor units),
contra_cogs bigint (minor units), sales_discount bigint (minor units), sell_through_rate
numeric, sellable_on_hand_units bigint, unsellable_on_hand_units bigint,
sellable_in_transit_units bigint, sourceable_roos numeric, open_purchase_order_units bigint,
confirmed_units bigint, net_received_units bigint, received_fill_rate numeric,
vendor_confirmation_rate numeric, overall_vendor_lead_time numeric, account_id uuid. The two
views overlap: manufacturing covers every ASIN the vendor makes, sourcing only those it sells
directly to Amazon, so summing across both double-counts - always filter on view. Orders and
traffic columns are null in the sourcing view, which does not expose them. Inventory and
sourcing columns are end-of-day snapshots captured once, so they carry a value on recent days
only and must never be summed across dates. Data lands two days late; the most recent two days
are empty by design.

Money is integer minor units of the row's currency (JPY: whole yen). Never sum across
currencies; group by marketplace_id or currency instead. Empty results can mean data not yet
synced, not zero sales.

queue_mutations

Queue immutable Amazon requests using { target: { type, id }, action, payload }. Listing supports update with productType and patches. Sponsored Products Campaign, AdGroup, Ad and Target support native update and archive with an empty payload. A creation targets the authorized parent with Amazon's native create object: create_campaign on an AdvertisingProfile, create_ad_group on a Campaign, create_ad on an AdGroup, create_target on an AdGroup or, for an exclusion, a Campaign. Get payload shapes with get_mutation_schema. Use local target IDs from list_listings or list_ads_entities. Provider and parent IDs are resolved from your target; conflicting IDs are rejected. Native money uses the profile's major currency units. Each result is independent. Queued means durable admission, not Amazon acceptance; inspect mutations on the target for provider outcomes. A creation returns nothing synchronously: read created on the parent's receipt later and target it for the next step. An identical creation is refused while one is pending. A creation whose reply is lost is never sent again; Pulsify asks Amazon what exists and settles it as accepted, absent or unresolved. Blocked requests are never released by a later unblock.

report_bug

File a bug report with the Pulsify team for something that broke or behaved wrong. Summarize the problem in your own words. Do NOT paste raw event payloads, listing data, or other Amazon business data into the report.

run_automation

Dry-run a saved automation, or JavaScript you pass as code, against a sample or real event and return the changes it would make, plus its console output. Nothing is applied: no webhooks fire and no data is written. Pass automation_id to run a saved automation, or code with stream_type to try JavaScript before saving it. By default it uses a canned sample for the event type. Pass event_id to replay one of your real events, or sample_event to supply your own JSON. Choose listing_id when a real event has multiple listing targets. When fabricating, copy the shape of a real event and set marketplaceId to one of your connected marketplaces; pricing events carry marketplace-specific currency and thresholds. missing_field_reads lists event keys the code read that are absent from the payload, with the keys actually available at that level — a non-empty list usually means the code expects the wrong payload shape.

suggest_idea

Suggest a feature or improvement to the Pulsify team. Summarize the idea in your own words. Do NOT paste raw event payloads, listing data, or other Amazon business data into the suggestion.

update_automation

Edit an automation's code or title, and optionally activate it. Activating deactivates any other live automation for the same event type and subscribes the stream. The subscribe call can be slow; on a hiccup the automation is active but the subscription stays pending, visible via list_streams. Use run_automation to dry-run the code before activating; its missing_field_reads catches a wrong payload shape.

update_listing

Block or allow automated changes to your listings. true stops Pulsify sending this listing's changes, and its advertising changes, to Amazon; the automation still runs and its request is recorded. false allows them again, without replaying anything blocked earlier. Each row names a sku and blocked. Each row is independent and reports saved. Use patch_listing for all Amazon attribute changes, including prices, bounds and quantity. Listing fields show Amazon's last reading; mutations includes queued requests and the latest submission. A SKU in several marketplaces needs marketplace_id. With several connected accounts, account identifies whose listings to change.

Event types

Each automation handles 1 event type. describe_stream_type returns the full contract for any of them, with a complete sample payload. Context names the shape of context, described below.

SP-API notifications

These need a selling connection. Envelopes are PascalCase (NotificationType, EventTime, Payload) except PRICING_HEALTH, ACCOUNT_STATUS_CHANGED, FEED_PROCESSING_FINISHED, ITEM_SALES_EVENT_CHANGE, DETAIL_PAGE_TRAFFIC_EVENT, which use camelCase (notificationType, eventTime, payload).

Amazon Marketing Stream

These need an advertising connection. event is the Marketing Stream message, and its keys differ by dataset.

The handler

An automation is JavaScript that defines handle(event, context) with exactly 2 parameters. Saving checks the syntax and that signature. Saving never runs the code.

function handle(event, context) {
  // Read event and context, decide, then queue changes:
  // context.mutations.push({ ... });
  return context;
}

The return value is ignored. After handle returns, Pulsify reads context.mutations. The templates return context by convention.

event is the payload exactly as Amazon sent it, with no flattened fields. A live event carries only the fields that changed. This fixture is complete.

Reading a key the payload doesn't have is recorded. run_automation returns those reads as missing_field_reads. When a live run changes nothing and read a top-level key the payload lacks, Pulsify records a warning action, at most 1 a day per automation.

Projected currency values on context are in major units (15.27). Raw data snapshots retain Amazon's units and types. The list_listings tool reports the same figures in minor units (1527). Never mix them. Some advertising amounts arrive as decimal strings rather than numbers; each says so, and they need parseFloat before arithmetic.

Context by scope

The shape of context depends on what the event is about. Every context also carries mutations, webhooks and store.

Listing

Event types: ANY_OFFER_CHANGED, B2B_ANY_OFFER_CHANGED, PRICING_HEALTH, LISTINGS_ITEM_STATUS_CHANGE, LISTINGS_ITEM_ISSUES_CHANGE, LISTINGS_ITEM_MFN_QUANTITY_CHANGE, ORDER_CHANGE, FBA_INVENTORY_AVAILABILITY_CHANGES, BRANDED_ITEM_CONTENT_CHANGE.

Selling partner

Event types: ACCOUNT_STATUS_CHANGED, FEED_PROCESSING_FINISHED, FBA_OUTBOUND_SHIPMENT_STATUS, FULFILLMENT_ORDER_STATUS, ITEM_SALES_EVENT_CHANGE, DETAIL_PAGE_TRAFFIC_EVENT.

Campaign or portfolio

Event types: BUDGET_USAGE.

Hourly metrics

Event types: SP_TRAFFIC, SP_CONVERSION.

Entity change

Event types: CAMPAIGN_CHANGE, AD_GROUP_CHANGE, AD_CHANGE, TARGET_CHANGE.

Mutations

Every request is { target, action, payload }. Push it onto context.mutations; Pulsify validates it after handle returns. Use the target object the context gave you. Its explicit type and local id identify the authorized record; other fields cannot change its ownership or provider identity.

Agents can read native Ads data and pending receipts with list_ads_entities, discover a payload with get_mutation_schema, and submit it with queue_mutations. The MCP target is { type: "Campaign", id: "local-id" }. The same native validation runs in automations and dry runs.

Listing patches

context.mutations.push({
  target: context.listing,
  action: "update",
  payload: {
    productType: context.listing.productType || "PRODUCT",
    patches: [{
      op: "replace",
      path: "/attributes/purchasable_offer",
      value: [{ our_price: [{ schedule: [{ value_with_tax: 19.99 }] }] }],
    }],
  },
});

Include the marketplace, currency and audience selectors your attribute requires. Ask get_product_type_schema for its native value shape. productType is required inside the payload, and patches must be non-empty. Flat fields such as price and quantity are rejected. A listing-triggered run can update only its source listing.

patch_listing remains a convenience tool for a SKU: it resolves the listing and the optional product_type, then uses the same validator and immutable ledger. Listing updates never copy requested values into observed listing data.

Advertising changes

context.mutations.push({ target: campaign, action: "update", payload: { state: "PAUSED" } });
context.mutations.push({ target: adGroup, action: "update", payload: { bid: { defaultBid: 0.75 } } });
context.mutations.push({ target: target, action: "archive", payload: {} });

Sponsored Products campaigns, ad groups, ads and all target categories support native update and archive. Archiving is permanent and requires an empty payload. Listing and advertising events use the same target set. keywords remains the keyword subset of targets. Exclusions, meaning negative keywords and negative product targets at ad-group and campaign level, sit in negativeTargets. Nothing bids on them and Amazon reports no performance for them, so they carry no bid and no metrics. Update and archive them like any target.

get_mutation_schema describes supported nested fields. Amounts use the profile currency's major units. Raw data keeps Amazon's keys and types. Provider IDs are resolved from the target; conflicting IDs fail validation. References stay within its profile and parent chain. A portfolio must belong to the same profile; audience, product-refinement and video-asset references must already be observed on that exact target.

Creating campaigns, ad groups, ads and targets

A creation targets the parent that will hold the new entity, and its payload is Amazon's native create object. Pulsify derives adProduct, the parent's ID and a campaign's marketplaceScope from the parent, so leave them out; a value you do supply must match. Keywords, product targets and their negative variants are all targets: set targetType, negative, state, bid and targetDetails as Amazon defines them.

context.mutations.push({
  target: adGroup,
  action: "create_target",
  payload: {
    targetType: "KEYWORD",
    negative: false,
    state: "ENABLED",
    bid: { bid: 0.75 },
    targetDetails: { keywordTarget: { keyword: "blue ceramic mug", matchType: "EXACT" } }
  }
});

• A campaign-level target must be an exclusion, with negative: true. An exclusion takes no bid. An advertised product must be a SKU or ASIN your account already has in the profile's marketplace. Audience, refinement, video and global-store references are refused on creation, and so are LOCATION targets. Amazon decides the finer rules, and its rejections appear on the receipt as it sent them.
• Nothing comes back when you push a creation. The receipt sits on the parent's mutations, and once Amazon confirms the entity its created holds { type, id, providerId }. Pass created as the target of the next request. A launch therefore spans several runs: campaign, then ad group, then ads and targets. There is no all-or-nothing launch. What was created stays if a later step fails, and pausing or archiving it is your script's decision.
• A listing's context reaches the campaigns, ad groups and targets its own automation created, even before any ad links them to the listing. A created campaign starts with its Automation switch on. Creating inside a campaign obeys that campaign's switch; creating a campaign requires an authorized advertising connection and, on a listing event, an unblocked listing.
• While a creation is queued, submitting or uncertain, an identical one on the same parent is refused as invalid output. Pulsify does not otherwise deduplicate. Your script decides what should exist, from the entities and receipts in context.
• Amazon offers no way to repeat a creation safely, so Pulsify never sends one twice. If the reply is lost, the receipt stays uncertain without holding back other requests for the parent, and Pulsify asks Amazon what exists. The outcome becomes accepted when exactly 1 matching entity appeared after the attempt, absent when none did after 10 minutes, or unresolved when several could be it. After absent, request the creation again if you still want it. unresolved is a final status of its own, so a script that waits on queued, submitting or uncertain requests moves on; the receipt lists the candidates.

Requests and outcomes

• Each push creates a separate immutable receipt, including repeated requests. Targets must belong to your accounts. Invalid automation output records a failed decision; MCP and dry runs return validation errors.
• Automation decisions and provider receipts are separate. applied on a decision means the request passed validation and was admitted. Inspect its receipt for Amazon's response.
• Receipts report queued, submitting, submitted, blocked, uncertain or, for a creation only, unresolved, plus outcome, accepted, HTTP status and raw response. HTTP 207 can contain rejections or partial results. Partial and ambiguous results stay uncertain and stop later requests for that target; Pulsify never blindly resends them. An uncertain creation is the exception: it is reconciled against Amazon and does not stop its parent's other requests.
• Known retryable rejections retry the same payload. Listing blocks and campaign switches are checked again under locks before dispatch. Unblocking never releases a blocked request.
• Acceptance is separate from observation. Ads data can update from a matching, current entity Amazon returns; requested values are never copied into observations. A confirmed archive records its terminal effect even if Amazon returns only its identity. Scheduled refreshes and events continue updating readings.

Store and console

context.store keeps small JSON values between runs of 1 automation. Values expire 1 day after they're written. Dry runs get an empty store of their own, so they never read or change the live one.

const last = context.store.get("last-price");
context.store.set("last-price", 19.99);
context.store.delete("last-price");

console.log, .warn, .error and .info write to 1 buffer per run. run_automation returns it as logs. Live runs don't keep their logs.

Webhooks

Add a webhook under Settings with a name, a URL and optional headers. The name must be a valid JavaScript identifier, because scripts call it by name:

context.webhooks.alerts?.post({ text: "Stock hit zero on " + context.listing.asin });

The ?. keeps the script working when no enabled webhook has that name. Dry runs never post.

• Pulsify sends a JSON POST with your headers and an X-Pulsify-Delivery-Id header. A string payload becomes { "text": ... }. A webhook of type Slack always sends Slack's text shape.
• Delivery is asynchronous. Timeouts, network errors, 429 and 5xx retry with backoff, up to 5 attempts. Other 4xx responses don't retry.
• The delivery id stays the same across retries of 1 delivery. If Pulsify reruns the automation after a failed run, that run posts again with a new id, so make your endpoint tolerate repeats.
• Each enabled webhook has a Send test button in Settings. Activity lists every delivery with its status and response.

Limits

Automation code has no network or file access. Use a webhook to reach your own systems.

Retention

Daily sales, traffic and economics, daily advertising metrics, vendor and search query metrics, and order history are kept. When Amazon reports a listing as deleted, Pulsify removes it the next night. Its receipts and sales history stay. Queued requests become blocked; an already-started submission remains uncertain until its outcome is resolved.