DEV Community: Nexscope Team

Build a Codex Amazon Product Research Workflow with Approval Gates

Nexscope Team — Sat, 05 Sep 2026 02:30:00 +0000

An Amazon product research workflow becomes useful when every candidate is processed by the same rules. Codex can orchestrate files, scripts, web research, REST APIs, and MCP tools, but it still needs an explicit contract for evidence, rejection criteria, scoring, and human approval.

This tutorial builds the decision layer. It does not ask an Agent to “find winning products.” It turns messy inputs into qualified, verify, or rejected records with traceable reasons.

Define the Input Contract

Start with a normalized record that keeps provenance beside each value:

/** @typedef {number|null} MaybeNumber */

/**
 * @typedef {Object} Candidate
 * @property {string} asin
 * @property {string} marketplace
 * @property {{value: MaybeNumber, source: string, retrievedAt: string, estimated: boolean}} monthlySales
 * @property {{value: MaybeNumber, source: string, retrievedAt: string, estimated: boolean}} price
 * @property {{value: MaybeNumber, source: string, retrievedAt: string, estimated: boolean}} reviewCount
 * @property {{value: MaybeNumber, source: string, retrievedAt: string, estimated: boolean}} rating
 * @property {{value: MaybeNumber, source: string, retrievedAt: string, estimated: boolean}} landedCost
 */

Missing data stays null. Zero is a real observed value and must not be used as a substitute for unknown.

Configure Hard Filters

Hard filters represent requirements that should not be negotiated by a scoring model:

const rules = {
  minPrice: 18,
  maxPrice: 80,
  minMonthlySales: 150,
  maxReviewCount: 1200,
  minRating: 3.5,
  maxLandedCostShare: 0.35,
};

function hardFilter(candidate) {
  const missing = [];
  const rejected = [];

  for (const key of ["price", "monthlySales", "reviewCount", "rating", "landedCost"]) {
    if (candidate[key].value == null) missing.push(key);
  }

  const price = candidate.price.value;
  const sales = candidate.monthlySales.value;
  const reviews = candidate.reviewCount.value;
  const rating = candidate.rating.value;
  const cost = candidate.landedCost.value;

  if (price != null && (price < rules.minPrice || price > rules.maxPrice)) rejected.push("price_range");
  if (sales != null && sales < rules.minMonthlySales) rejected.push("insufficient_demand");
  if (reviews != null && reviews > rules.maxReviewCount) rejected.push("review_barrier");
  if (rating != null && rating < rules.minRating) rejected.push("quality_risk");
  if (price != null && cost != null && cost / price > rules.maxLandedCostShare) rejected.push("landed_cost_share");

  return { missing, rejected };
}

A candidate with missing economics belongs in verify, not qualified. A candidate that fails a non-negotiable requirement belongs in rejected, even if other signals look attractive.

Add Transparent Scoring

Only candidates that survive hard filters should receive a score. Keep each component visible:

const clamp = (n, min = 0, max = 100) => Math.max(min, Math.min(max, n));

function scoreCandidate(c) {
  const sales = c.monthlySales.value;
  const reviews = c.reviewCount.value;
  const rating = c.rating.value;
  const price = c.price.value;
  const cost = c.landedCost.value;

  if ([sales, reviews, rating, price, cost].some(v => v == null)) return null;

  const demand = clamp((sales / 1000) * 100);
  const competition = clamp(100 - (reviews / 1500) * 100);
  const margin = clamp(((price - cost) / price) * 100);
  const quality = clamp(((rating - 3) / 2) * 100);

  const components = { demand, competition, margin, quality };
  const total = demand * 0.35 + competition * 0.25 + margin * 0.25 + quality * 0.15;
  return { total: Number(total.toFixed(1)), components };
}

Weights should be versioned with the report. Changing a threshold or weight changes the decision system and should be treated like a code change.

Create Approval Gates

Some work can be automated safely. Other actions create legal, financial, or operational exposure.

function classify(candidate) {
  const filter = hardFilter(candidate);
  if (filter.rejected.length) {
    return { status: "rejected", reasons: filter.rejected, score: null };
  }
  if (filter.missing.length) {
    return { status: "verify", reasons: filter.missing.map(x => `missing:${x}`), score: null };
  }
  return { status: "qualified", reasons: [], score: scoreCandidate(candidate) };
}

const approvalGates = [
  "supplier_sample_approved",
  "landed_cost_confirmed",
  "patent_and_trademark_reviewed",
  "compliance_owner_approved",
  "purchase_order_approved",
];

Codex can prepare evidence for these gates. It should not approve a supplier, legal conclusion, payment, or purchase order on behalf of the responsible team.

Produce an Auditable Report

Every output should include:

Original and normalized values
Source and retrieval timestamp
Estimate status
Hard-filter result and reason
Score components and weight version
Missing-data queue
Required human approvals

function buildReport(candidates) {
  return candidates.map(candidate => ({
    asin: candidate.asin,
    marketplace: candidate.marketplace,
    decision: classify(candidate),
    evidence: candidate,
    approvalGates,
  }));
}

The result is a shortlist with evidence, not a promise that a product will succeed.

Connect Structured Data

Nexscope provides ecommerce data through REST API and MCP access for a team's own Agent and workflow. Use the current endpoint documentation to define supported fields, marketplaces, request parameters, and missing-value behavior before mapping responses into the contract above.

Explore Ecommerce Data APIs →

Disclosure: This article was prepared with AI-assisted editing using current published documentation as its technical source of truth.

Build a Product-Led TikTok Creative Testing System

Nexscope Team — Fri, 04 Sep 2026 10:00:00 +0000

Going viral is not a production setting. For an ecommerce team, the useful goal is to build a TikTok creative testing system that produces clear learning: which hook stopped attention, when the product became understandable, and whether that attention led to product action.

A controlled system keeps the product, audience, offer, and landing destination stable while changing one meaningful creative variable at a time. That makes the next decision easier than publishing ten unrelated videos and guessing why one performed differently.

Define the Product Job

Start with the job the product must perform inside the story. It might resolve a visible problem, create a transformation, reveal a result, or make the ending possible.

Use a simple removal test: if the product can disappear and the story still works, the concept is probably entertainment with a late product shot. Rewrite the sequence so the product causes the turning point.

Record four facts before production:

The buyer problem shown on screen
The verified product feature used to address it
The moment the product first appears
The single action requested at the end

Break References Into Functions

A useful reference can show pacing and structure without becoming a template to copy. Analyze an authorized reference by function:

Segment	Function	New creative decision
0-3 seconds	Create an unanswered question	Original hook using the same problem type
3-7 seconds	Establish the conflict	New person, place, and action
7-12 seconds	Introduce the product	Approved product image and verified feature
12-18 seconds	Resolve the tension	Truthful demonstration or result
Final frame	Create product recall	Product, benefit, and one CTA

Keep the function. Replace another creator's face, voice, script, music, branding, and distinctive scenes. Only use references the brand owns, licenses, or has permission to adapt.

Write One Hypothesis

Every test needs one sentence that can be disproved. For example:

Showing the result before the process will improve three-second retention without reducing product clicks.

The hypothesis determines what changes and what stays fixed. A practical test card looks like this:

Product: Travel organizer
Audience: Frequent flyers
Offer: Unchanged
Landing page: Unchanged

Control: Problem-first opening
Variant A: Result-first opening
Variant B: Question-first opening

Primary metric: 3-second view rate
Guardrail: Product click-through rate
Decision: Scale, revise, or stop

Two or three variants are usually enough for a first pass. Changing the hook, creator, music, duration, benefit, and CTA together makes the result difficult to interpret.

Add a Review Gate

Fast production still needs a release check. Review the final render for:

Product shape, color, packaging, label, and included accessories
Hands, faces, object contact, and physical continuity
Spoken and visible claims against approved product information
Third-party people, logos, music, and protected assets
AI-generated-content disclosure requirements
Platform-specific captions, aspect ratio, and safe zones

The output remains a production draft until these checks pass. A visually impressive clip with an inaccurate package or unsupported result should not enter the test.

Match Metrics to the Creative Job

Views alone do not show whether shoppers understood the product. Use a small metric ladder:

Question	Useful signals
Did the hook stop attention?	2-second and 3-second views
Did the story hold attention?	Average watch time and completion rate
Did viewers show interest?	Saves, shares, comments, profile visits
Did the product create action?	Product clicks, add-to-cart rate, conversion rate
Did paid distribution work?	CPC, CPA, conversion value, ROAS

Choose one primary metric and one commercial guardrail. A hook that raises retention but weakens product clicks is not automatically a winner.

Scale One Learning at a Time

When a variant produces a stable improvement, preserve the winning variable and test the next one. A result-first hook can move into several settings. A strong product entry can work with different creators. A useful story structure can become localized versions for other markets.

Keep an evidence log with the hypothesis, assets, publication date, audience, spend, primary result, guardrail result, and next decision. This prevents a team from repeating failed ideas after the original context has been forgotten.

Next Step

Nexscope Video Clone can turn an authorized reference and approved product images into a product-specific draft for review and controlled testing.

Try Video Clone →

Disclosure: This article was prepared with AI-assisted editing using current published product and platform guidance as its source of truth.

Build an Amazon Review Analysis Pipeline with Node.js

Nexscope Team — Sun, 30 Aug 2026 02:30:00 +0000

Review analysis becomes useful when every theme can be traced back to its evidence. A count such as “23 durability complaints” is incomplete without the ASIN, variation, marketplace, rating, review date, and the text that matched the rule.

This tutorial builds a Node.js pipeline that collects controlled review samples, keeps missing fields explicit, applies an auditable keyword taxonomy, and outputs both aggregates and supporting records.

Design the Sample Before Calling the API

The Amazon Reviews List API accepts one ASIN and a marketplace domainCode. The current documentation lists 15 marketplaces: com, ca, co.uk, in, de, fr, it, es, co.jp, com.au, com.br, nl, se, com.mx, and ae.

Separate fields request one- through five-star reviews. Each defaults to 10 and currently supports up to 100. That structure makes a balanced sample possible instead of relying only on the most visible reviews.

export NEXSCOPE_API_KEY="nk_your_key_here"
export AMAZON_ASINS="B072MQ5BRX,B0XXXXXXXXX"

For a real competitor study, choose ASINs with a comparable use case, price band, size, and audience. A larger sample does not repair a mismatched comparison set.

Build the Review Client

The endpoint uses a bearer-authenticated POST request. Keep the credential on the server and send ASINs sequentially until the account's actual limits are known.

const API_KEY = process.env.NEXSCOPE_API_KEY;
const ENDPOINT =
  "https://api.nexscope.ai/api/skill-api/v1/skills/amazon-reviews-list/run";

if (!API_KEY) throw new Error("Set NEXSCOPE_API_KEY first");

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function fetchReviews(body, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let response;

    try {
      response = await fetch(ENDPOINT, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      });
    } catch (error) {
      lastError = error;
      if (attempt < maxAttempts) {
        await wait(500 * 2 ** (attempt - 1));
        continue;
      }
      break;
    }

    if (response.ok) return response.json();

    const message = await response.text();
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable) throw new Error(`Request failed (${response.status}): ${message}`);

    lastError = new Error(`Transient API failure (${response.status})`);
    if (attempt < maxAttempts) await wait(500 * 2 ** (attempt - 1));
  }

  throw lastError;
}

Collect a Controlled Sample

The request below deliberately includes every rating band and recent verified-purchase reviews. Those are sampling choices, not a universal standard.

async function collectAsin(asin, domainCode = "com") {
  return fetchReviews({
    asin,
    domainCode,
    star1Num: 25,
    star2Num: 25,
    star3Num: 40,
    star4Num: 25,
    star5Num: 25,
    filterByKeyword: "",
    sortBy: "recent",
    reviewerType: "avp_only_reviews",
    mediaType: "all_contents",
    formatType: "all_formats",
  });
}

const asins = process.env.AMAZON_ASINS
  .split(",")
  .map((value) => value.trim())
  .filter(Boolean);

const rawRuns = [];
for (const asin of asins) {
  rawRuns.push({ asin, payload: await collectAsin(asin, "com") });
}

Normalize Without Filling the Gaps

Documented review fields include reviewId, asin, title, text, rating, date, userName, verified, vine, numberOfHelpful, media URLs, product context, and variation fields. Optional values should stay null.

function extractRows(payload) {
  if (Array.isArray(payload?.data)) return payload.data;
  if (Array.isArray(payload?.columns)) return payload.columns;
  if (Array.isArray(payload)) return payload;
  return [];
}

function numberOrNull(value) {
  if (value === null || value === undefined || value === "") return null;
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

function normalizeReview(row, requestedAsin, domainCode) {
  return {
    reviewId: row.reviewId ?? null,
    asin: row.asin ?? requestedAsin,
    title: row.title ?? null,
    text: row.text ?? null,
    rating: numberOrNull(row.rating),
    date: row.date ?? null,
    userName: row.userName ?? null,
    verified: row.verified ?? null,
    vine: row.vine ?? null,
    helpful: numberOrNull(row.numberOfHelpful),
    variationId: row.variationId ?? null,
    variationList: Array.isArray(row.variationList) ? row.variationList : null,
    domainCode: row.domainCode ?? domainCode,
    imageUrls: Array.isArray(row.imageUrlList) ? row.imageUrlList : null,
    videoUrls: Array.isArray(row.videoUrlList) ? row.videoUrlList : null,
  };
}

const reviews = rawRuns.flatMap(({ asin, payload }) =>
  extractRows(payload).map((row) => normalizeReview(row, asin, "com")),
);

Keep the raw payload with a run ID. The fallback extractor is defensive; it does not guarantee that every response uses the same wrapper.

Apply an Explicit Theme Taxonomy

For a first pass, a small regular-expression taxonomy is easier to audit than an opaque sentiment score. The rules below are examples and must be adapted to the category and language.

const THEMES = {
  durability: /\b(broke|broken|crack(?:ed)?|fell apart|stopped working)\b/i,
  fit: /\b(too small|too large|too tight|too loose|does not fit)\b/i,
  battery: /\b(battery|charge|charging|battery life)\b/i,
  packaging: /\b(box|packaging|damaged on arrival|missing parts?)\b/i,
  instructions: /\b(instructions?|manual|setup|hard to assemble)\b/i,
};

function classify(review) {
  const evidence = [review.title, review.text].filter(Boolean).join("\n");
  const themes = Object.entries(THEMES)
    .filter(([, pattern]) => pattern.test(evidence))
    .map(([name]) => name);

  return { ...review, themes };
}

const classified = reviews.map(classify);

A keyword match is an indicator, not a verdict. Negation, sarcasm, quoted text, and category-specific language can produce false positives. Inspect supporting records before changing a product or listing.

Aggregate Counts and Preserve Evidence

The report keeps both the summary and a limited evidence sample for each theme. It also records the collection design so a later run can be compared fairly.

function aggregateByTheme(rows) {
  const output = {};

  for (const review of rows) {
    for (const theme of review.themes) {
      output[theme] ??= { mentions: 0, ratings: [], evidence: [] };
      output[theme].mentions += 1;
      if (review.rating !== null) output[theme].ratings.push(review.rating);
      if (output[theme].evidence.length < 5) {
        output[theme].evidence.push({
          reviewId: review.reviewId,
          asin: review.asin,
          variationId: review.variationId,
          rating: review.rating,
          date: review.date,
          verified: review.verified,
          text: review.text,
        });
      }
    }
  }

  return Object.fromEntries(
    Object.entries(output).map(([theme, value]) => [theme, {
      mentions: value.mentions,
      averageRating: value.ratings.length
        ? Number((value.ratings.reduce((a, b) => a + b, 0) / value.ratings.length).toFixed(2))
        : null,
      evidence: value.evidence,
    }]),
  );
}

const report = {
  schemaVersion: 1,
  collectedAt: new Date().toISOString(),
  requestedAsins: asins,
  domainCode: "com",
  sampleDesign: {
    sortBy: "recent",
    reviewerType: "avp_only_reviews",
    requestedByStars: [25, 25, 40, 25, 25],
  },
  receivedReviews: classified.length,
  themes: aggregateByTheme(classified),
};

console.log(JSON.stringify(report, null, 2));

For large reports, store full text in access-controlled storage and put only record IDs and short excerpts in downstream dashboards. Review data can contain user-supplied text and names; minimize retention to what the research task requires.

Interpret the Output Carefully

The requested count is not necessarily the number returned.
A balanced star sample is not the listing's natural rating distribution.
verified, Vine status, helpful votes, and media are segmentation signals, not authenticity scores.
Keep variation and marketplace context; do not generalize one variant's defect to an entire family.
Recent-review results depend on the collection date and the endpoint's available coverage.
A theme correlation does not prove the cause of returns, rating changes, or sales movement.
Source, freshness, coverage, and fixed rate limits should not be assumed when the API definition does not specify them.

The goal is a reproducible evidence queue for human review—not an automatic claim about customers or competitors.

Next Step

The Amazon Reviews List API provides controlled review collection by marketplace, rating count, sort order, reviewer type, media type, and format.

Build with the Amazon Reviews List API →

Disclosure: This article was prepared with AI-assisted editing using the current published API documentation as its technical source of truth.

How to Build an Amazon Price Monitoring Pipeline

Nexscope Team — Sat, 29 Aug 2026 02:30:00 +0000

A price monitor needs more than a scheduled HTTP request. Amazon product pages can expose a Buy Box price, list price, deal price, Prime price, coupon-adjusted price, FBA and FBM prices, and periods where a curve is absent. Collapsing those observations into one ambiguous number creates noisy alerts.

This tutorial builds a small Node.js pipeline that requests selected price curves, preserves missing values, saves a timestamped snapshot, and detects changes against the previous run.

Define the Monitoring Contract

The current Amazon Product Price Series API accepts one ASIN, a marketplace domain, and a history window. The documented domain IDs are:

Domain	Marketplace	Domain	Marketplace
`1`	US	`2`	UK
`3`	Germany	`4`	France
`5`	Japan	`6`	Canada
`8`	Italy	`9`	Spain
`10`	India	`11`	Mexico
`12`	Brazil

The optional days field defaults to 90 and supports up to 365 days. Curve flags let the caller request only the signals needed by the application.

Store the API key in the server environment:

export NEXSCOPE_API_KEY="nk_your_key_here"
export AMAZON_ASIN="B072MQ5BRX"

Request Price History

The client retries network failures, HTTP 429 responses, and server errors. Invalid input and authentication errors fail immediately.

const API_KEY = process.env.NEXSCOPE_API_KEY;
const ENDPOINT =
  "https://api.nexscope.ai/api/skill-api/v1/skills/amazon-product-price-series/run";

if (!API_KEY) throw new Error("Set NEXSCOPE_API_KEY first");

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function fetchPriceSeries(body, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let response;

    try {
      response = await fetch(ENDPOINT, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      });
    } catch (error) {
      lastError = error;
      if (attempt < maxAttempts) {
        await wait(500 * 2 ** (attempt - 1));
        continue;
      }
      break;
    }

    if (response.ok) return response.json();

    const message = await response.text();
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable) throw new Error(`Request failed (${response.status}): ${message}`);

    lastError = new Error(`Transient API failure (${response.status})`);
    if (attempt < maxAttempts) await wait(500 * 2 ** (attempt - 1));
  }

  throw lastError;
}

const payload = await fetchPriceSeries({
  asin: process.env.AMAZON_ASIN,
  domain: 1,
  days: 90,
  showPrice: true,
  showPriceList: true,
  showPriceDeal: true,
  showPricePrime: true,
  showPriceFba: true,
  showPriceFbm: true,
  showPriceCoupon: true,
  showSellerCount: true,
});

Do not put this request in client-side browser code. A browser bundle would expose the bearer token.

Normalize Curves Without Inventing Data

The documented response can contain curves such as buyboxPrice, price, priceList, priceDeal, pricePrime, priceFba, priceFbm, priceCoupon, and sellerCount. Preserve every timestamp and keep absent curves as null.

const CURVES = [
  "buyboxPrice",
  "price",
  "priceList",
  "priceDeal",
  "pricePrime",
  "priceFba",
  "priceFbm",
  "priceCoupon",
  "sellerCount",
];

function normalizePoint(point) {
  if (Array.isArray(point)) {
    return { at: point[0] ?? null, value: point[1] ?? null };
  }
  return {
    at: point?.timestamp ?? point?.time ?? point?.date ?? null,
    value: point?.value ?? point?.price ?? null,
  };
}

function normalizeCurve(value) {
  if (!Array.isArray(value)) return null;
  return value.map(normalizePoint).filter((point) => point.at !== null);
}

function normalizePricePayload(payload, context) {
  const source = payload?.data ?? payload ?? {};
  const curves = Object.fromEntries(
    CURVES.map((name) => [name, normalizeCurve(source[name])]),
  );

  return {
    schemaVersion: 1,
    asin: context.asin,
    domain: context.domain,
    collectedAt: new Date().toISOString(),
    currency: source.currency ?? null,
    curves,
  };
}

This normalizer is deliberately defensive. Verify the actual response shape in a test account before promoting it to production, and keep the raw response for debugging.

Save One Snapshot Per Run

For a local demonstration, Node's file APIs are enough. A production monitor should use durable object storage or a database, make writes idempotent, and retain a run ID.

import { mkdir, readFile, rename, writeFile } from "node:fs/promises";

const STATE_DIR = new URL("./price-state/", import.meta.url);
const STATE_FILE = new URL(`${process.env.AMAZON_ASIN}-us.json`, STATE_DIR);

async function readPrevious() {
  try {
    return JSON.parse(await readFile(STATE_FILE, "utf8"));
  } catch (error) {
    if (error.code === "ENOENT") return null;
    throw error;
  }
}

async function saveAtomically(snapshot) {
  await mkdir(STATE_DIR, { recursive: true });
  const temporary = new URL(`${STATE_FILE.pathname}.tmp`, "file://");
  await writeFile(temporary, JSON.stringify(snapshot, null, 2));
  await rename(temporary, STATE_FILE);
}

Atomic replacement prevents readers from opening a half-written JSON file. A database implementation should enforce a unique key such as (asin, domain, collectedAt).

Detect Meaningful Changes

The latest point is not necessarily “now.” Record its source timestamp, and compare like with like: same ASIN, marketplace, curve, and currency.

function latest(curve) {
  if (!Array.isArray(curve) || curve.length === 0) return null;
  return curve
    .filter((point) => Number.isFinite(Number(point.value)))
    .sort((a, b) => String(a.at).localeCompare(String(b.at)))
    .at(-1) ?? null;
}

function detectChange(previous, current, curveName, thresholdPercent = 3) {
  const before = latest(previous?.curves?.[curveName]);
  const after = latest(current?.curves?.[curveName]);

  if (!before || !after) return null;
  const oldValue = Number(before.value);
  const newValue = Number(after.value);
  if (!Number.isFinite(oldValue) || !Number.isFinite(newValue) || oldValue === 0) {
    return null;
  }

  const percent = ((newValue - oldValue) / oldValue) * 100;
  if (Math.abs(percent) < thresholdPercent) return null;

  return {
    curve: curveName,
    oldValue,
    newValue,
    percent: Number(percent.toFixed(2)),
    previousAt: before.at,
    currentAt: after.at,
  };
}

const context = { asin: process.env.AMAZON_ASIN, domain: 1 };
const current = normalizePricePayload(payload, context);
const previous = await readPrevious();

const alerts = ["buyboxPrice", "priceDeal", "priceCoupon"]
  .map((curve) => detectChange(previous, current, curve, 3))
  .filter(Boolean);

console.log(JSON.stringify({ context, alerts }, null, 2));
await saveAtomically(current);

Emit an alert only after the snapshot is valid, but decide whether to save before or after notification based on the retry guarantees of the messaging system. A production queue should attach an idempotency key so a retried job does not send the same alert twice.

Schedule the Collector

Run the script with an external scheduler such as cron, a cloud scheduler, or a job queue. This is safer than leaving a long-running setInterval process responsible for business-critical timing.

# Every six hours; use an explicit server timezone and monitor failures.
15 */6 * * * /usr/bin/node /srv/price-monitor/index.mjs

The API documentation does not publish a fixed rate limit or freshness guarantee. Start sequentially, measure real responses, add backoff, and size the schedule to the account's actual limits and monitoring goal.

Production Checks

Preserve marketplace, currency, ASIN, curve, and source timestamp with every observation.
Treat missing curves as unknown, not as zero price or out of stock.
Test coupons, Prime-only prices, variations, multiple sellers, and unavailable products.
Require confirmation across repeated observations before triggering automated repricing.
Monitor job failures separately from “no price change.”
Do not treat a price movement as proof of demand, inventory, or competitor intent.

Next Step

The Amazon Product Price Series API exposes selectable price and marketplace curves for a single ASIN request.

Build with the Amazon Product Price Series API →

Disclosure: This article was prepared with AI-assisted editing using the current published API documentation as its technical source of truth.

7 Seedance 2.5 Video Workflows for Ecommerce Sellers

Nexscope Team — Fri, 28 Aug 2026 02:30:00 +0000

Ecommerce sellers rarely need “an AI video” in the abstract. They need a product demonstration that keeps the item recognizable, a vertical hook that works without sound, a localized version for another market, or a set of ad variations that can be reviewed before launch.

Seedance 2.5 is useful in that context because it combines longer storytelling, multimodal references, and more precise control. ByteDance says the model can generate up to 30-second audio-video clips in a single pass, accept up to 30 images, 10 video clips, and 10 audio clips as references, and support timestamp-level editing. The exact controls exposed by each product interface can differ, so production teams should check the live settings before planning a batch.

This guide turns those model capabilities into seven practical workflows for product pages, marketplaces, social commerce, and paid campaigns.

1. Build a 30-Second Product Story

A longer generation is most valuable when the extra time answers buyer questions. Without a storyboard, a 30-second clip can become a sequence of attractive shots that never explains why the product matters.

A simple structure is:

Time	Purpose	Example
0-3 seconds	Hook	Show the problem, result, or strongest visual change
3-10 seconds	Product introduction	Put the product in a recognizable use environment
10-22 seconds	Demonstration	Show materials, controls, steps, or visible results
22-27 seconds	Decision evidence	Add a comparison or reason to believe
27-30 seconds	Next action	Finish with one restrained call to action

The sequence should change with the category. A fashion video may move from a full outfit view to walking motion and fabric detail. A beauty video can cover packaging, texture, application, and the finished look. An appliance video may need to show the setting, controls, operating steps, and result.

Every time segment should answer a buyer question or support the next part of the story. Longer output does not replace planning. It makes timing and continuity more important.

2. Create a Product Reference Pack

Product videos often begin with more than one image. Sellers may already have packshots, model photos, lifestyle scenes, packaging details, brand colors, previous videos, and examples of the desired camera movement.

Seedance 2.5 can use several media types together at the model level. That makes it possible to assign different creative roles to different references:

Product identity: front, back, side, packaging, texture, controls, and accessories
People: model appearance, wardrobe, pose, expression, and interaction
Environment: studio, home, retail, outdoor, or product-use context
Brand direction: color, lighting, composition, and approved campaign style
Motion: camera paths, gestures, transitions, and pacing
Audio: voice, music direction, sound effects, and timing cues

More references do not automatically produce a better result. Give every file one clear job, and state that job in the prompt. Conflicting product views, lighting directions, or style examples can create ambiguity.

Reference packs also need category-specific checks. Fashion teams should include fabric and fit details. Beauty teams should preserve packaging, shade, and texture. Electronics teams should capture ports, buttons, proportions, and operating steps. Small text, logos, dimensions, and safety-critical actions always require manual review.

3. Turn Product Images Into Demonstrations

When approved product images already exist, image-to-video is usually the shortest path to useful motion. It works well for product reveals, camera orbits, material close-ups, simple demonstrations, and lifestyle movement.

A useful motion brief should identify four things:

What moves: the product, a hand, a model, the camera, or an environmental element
What stays fixed: product shape, logo, packaging, color, proportions, or text
How the camera behaves: push-in, orbit, overhead move, close-up, or locked shot
What the selling moment is: a visible feature, transformation, interaction, or result

For example:

Keep the bottle shape, label colors, cap, and proportions consistent.
Start with a clean front view on a bathroom counter. The camera slowly
pushes in as a hand picks up the bottle, rotates it once, and dispenses
one drop onto the palm. Use soft daylight and restrained motion. End on
a stable close-up of the product with the label facing the camera.

The prompt describes the commercial job of the shot without relying on vague terms such as “make it cinematic.” It also names the elements that cannot drift.

Sellers can test this workflow in the Seedance 2.5 online generator. The current interface accepts JPG, PNG, and WebP images, supports up to 30 references, and exposes duration, resolution, and aspect-ratio controls.

4. Produce UGC-Style Social Videos

UGC-style content needs a different structure from a polished product commercial. The opening must feel native to the channel, the product benefit should appear early, and the script should avoid presenting a generated person as an independent customer.

A practical UGC-style sequence is:

Hook: show a recognizable problem or outcome in the first seconds
Context: explain who the product is for and when it is used
Demonstration: make the product action visible rather than relying only on speech
Proof: use approved product facts, not fabricated testimonials or results
Close: give one next action that fits the platform

Product images can anchor the item while a creator-style concept provides the pacing and presentation. The output still needs review for hands, faces, packaging, spoken claims, captions, pronunciation, and disclosure requirements.

For TikTok Shop, Reels, and Shorts, plan a vertical composition from the beginning. Important product details, faces, subtitles, and calls to action should remain inside the safe area. A landscape master cropped after generation may lose the detail that makes the video persuasive.

5. Reuse an Authorized Video Structure

A reference video can supply a proven hook, scene order, camera rhythm, or demonstration pattern. This is useful when a team wants to apply one approved creative structure to several products.

The reference should be chosen for structure, not copied branding. Before using it, confirm that the team has the right to use the video and remove any third-party logos, music, people, claims, or proprietary creative elements that are not licensed for reuse.

A safe brief separates what to keep from what to replace:

Keep	Replace
Shot order	Product and packaging
Camera pacing	Brand colors and text
Demonstration logic	Claims and call to action
Transition pattern	Music, voice, and protected assets

This approach works for repeatable product reveals, unboxing structures, before-and-after demonstrations, and creator-style hooks. Each resulting clip should still be treated as a new commercial asset with its own rights, accuracy, and policy review.

6. Localize One Concept for Multiple Markets

One approved product concept can become the starting point for several countries and channels. The product references, shot structure, and main demonstration may remain stable while the language, buying reason, format, and call to action change.

Localization should cover more than translation:

Buying reasons and customer objections
Currency, measurements, and date formats
Product claims, disclaimers, and regulated language
Voice, pronunciation, captions, and cultural context
Aspect ratio, safe zones, and channel-specific calls to action

Native-language review is especially important for product names, numbers, claims, and pronunciation. A shared reference pack can preserve the visual system, but the commercial message still needs local approval.

The same master concept may become a 16:9 product-page video, a 9:16 social-commerce hook, a square paid-social variation, and a silent-autoplay version with stronger visible product action. The buyer question should determine the edit, not the platform name alone.

7. Edit and Review Without Restarting

One incorrect detail should not force a team to abandon everything that already works. Seedance 2.5 introduces timestamp-level control and targeted editing at the model level, which can help isolate a change while preserving more of an accepted sequence.

Potential edits include:

Correcting product color while keeping the model's movement
Replacing an environment while preserving the demonstration
Changing a local action without rebuilding the whole sequence
Adjusting camera movement while retaining the subject and timing
Updating a product or selling point inside an approved creative structure

The edit request should name both the intended change and the elements that must remain unchanged. Afterward, review the complete clip, not only the modified frame. A local edit may affect continuity, lighting, product geometry, or movement before and after the target segment.

Use a consistent approval checklist:

Product shape, color, packaging, logo, and text
Claims, demonstrations, and visible results
Hands, faces, motion, and physical plausibility
Audio, pronunciation, captions, and synchronization
Aspect ratio, safe zones, and platform requirements
Rights for every image, video, person, logo, voice, and music asset

Generated video should remain a draft until these checks are complete. ByteDance also notes that complex motion and interactions among multiple subjects still have room for improvement.

Optional API Workflow for Production Teams

Teams producing many approved variations may want to move from manual testing to a repeatable API workflow. The current Seedance 2.5 API documentation describes an asynchronous create-and-query process:

Submit one generation request.
Store the returned taskId.
Poll the result endpoint with progressive backoff.
Stop on SUCCESS, FAILED, or TIMEOUT.
Send successful output to human review before distribution.

The following Node.js example shows the control flow. It uses placeholders and does not expose a real API key.

const API_KEY = process.env.NEXSCOPE_API_KEY;
const API_BASE = "https://api.nexscope.ai/api/skill-api/v1/skills";
const SKILL = "seedance-2-5-video-generation";

if (!API_KEY) throw new Error("Set NEXSCOPE_API_KEY first");

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

async function createVideo() {
  const response = await fetch(`${API_BASE}/${SKILL}/run`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      videoTime: 10,
      resolution: "720p",
      aspectRatio: "9:16",
      imageUrl: "https://example.com/approved-product-image.jpg",
      prompt: [
        "Keep the product shape, packaging, and logo consistent.",
        "Use a slow push-in, then show one clear product interaction.",
        "Finish on a stable front view with the product centered.",
      ].join(" "),
    }),
  });

  if (!response.ok) {
    throw new Error(`Create failed: ${response.status} ${await response.text()}`);
  }

  return response.json();
}

const waits = [5, 10, 20, 30];

async function waitForResult(taskId) {
  let attempt = 0;

  while (true) {
    const seconds = waits[Math.min(attempt, waits.length - 1)];
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));

    const response = await fetch(`${API_BASE}/${SKILL}/tasks/${taskId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    if (!response.ok) {
      throw new Error(`Status check failed: ${response.status}`);
    }

    const result = await response.json();

    if (result.status === "SUCCESS") return result;
    if (["FAILED", "TIMEOUT"].includes(result.status)) {
      throw new Error(`Generation ended with ${result.status}`);
    }

    attempt += 1;
  }
}

const created = await createVideo();
if (!created.taskId) throw new Error("No taskId returned");

const completed = await waitForResult(created.taskId);
console.log("Ready for human review:", completed);

In production, add request validation, a maximum polling duration, idempotency, secure asset storage, cost controls, and logs that exclude credentials. Do not submit another generation request while the first task is PENDING or RUNNING.

Final Takeaway

Seedance 2.5 gives ecommerce teams more room to combine product storytelling, reference assets, channel variations, and targeted edits. The useful part is the workflow around the model: approved source assets, a specific selling objective, controlled prompts, clear versioning, and human review.

Nexscope provides an online Seedance 2.5 generator for hands-on creation and a documented API for repeatable production pipelines. The current online experience starts at $0.10 per generated second, while the live interface and API documentation remain the source of truth for available settings and usage.

Try Seedance 2.5 Online →

Sources

Disclosure: This article was prepared with AI-assisted editing using current published product and API documentation as its technical source of truth.

Build a Four-Stage Amazon ASIN Research Pipeline with Node.js

Nexscope Team — Thu, 27 Aug 2026 02:30:00 +0000

An ASIN is a useful starting key, but one endpoint rarely answers a complete product-research question. Traffic exposure, reverse-ASIN keywords, comparable products, and niche-level demand describe different parts of the market.

This tutorial connects four Amazon data APIs into one Node.js pipeline. The result is a reviewable JSON report with explicit missing values, per-stage errors, and enough provenance to prevent a visibility score from being mistaken for verified sessions or sales.

Pipeline Design

The pipeline uses four stages:

Stage	Endpoint	Research question
Traffic summary	`amazon-asin-traffic-summary`	Where does the ASIN appear to gain or lose exposure?
Reverse keywords	`amazon-asin-keywords`	Which organic and paid keywords are associated with the ASIN?
Related products	`amazon-related-asins`	Which same-niche products should enter the competitor set?
Niche validation	`amazon-niche-info-by-asin`	What demand, concentration, and opportunity signals describe the niche?

The current documentation exposes all four as authenticated POST requests under the same base path:

https://api.nexscope.ai/api/skill-api/v1/skills/{skill}/run

Set the API key on the server. Do not place it in browser code or commit it to a repository.

export NEXSCOPE_API_KEY="nk_your_key_here"
export AMAZON_ASIN="B072MQ5BRX"

Build a Resilient Client

The client below retries transient network failures, HTTP 429 responses, and server errors. It fails immediately on invalid input or authentication errors because repeating the same request will not fix either condition.

const API_KEY = process.env.NEXSCOPE_API_KEY;
const API_BASE = "https://api.nexscope.ai/api/skill-api/v1/skills";

if (!API_KEY) throw new Error("Set NEXSCOPE_API_KEY first");

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function callSkill(skill, body, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let response;

    try {
      response = await fetch(`${API_BASE}/${skill}/run`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      });
    } catch (error) {
      lastError = error;
      if (attempt < maxAttempts) {
        await wait(500 * 2 ** (attempt - 1));
        continue;
      }
      break;
    }

    if (response.ok) return response.json();

    const message = await response.text();
    const retryable = response.status === 429 || response.status >= 500;

    if (!retryable) {
      throw new Error(`${skill} failed (${response.status}): ${message}`);
    }

    lastError = new Error(`${skill} transient failure (${response.status})`);
    if (attempt < maxAttempts) await wait(500 * 2 ** (attempt - 1));
  }

  throw lastError;
}

The published API definitions do not specify a fixed rate limit. Start with sequential requests, measure actual behavior, and only add concurrency after confirming the limits that apply to the account.

Define the Four Requests

The request fields below match the current live documentation. Traffic summary supports up to ten comma-separated ASINs, while the reverse-keyword endpoint accepts one ASIN per call. Related-ASIN and niche-by-ASIN currently document US, JP, and DE country codes.

async function collectResearch(asin, country = "US") {
  const traffic = await callSkill("amazon-asin-traffic-summary", {
    searchValue: asin,
    country,
    last7d: true,
    pageNum: 1,
    pageSize: 10,
    desc: true,
  });

  const keywords = await callSkill("amazon-asin-keywords", {
    asin,
    country,
    timePieceType: "latelyDay",
    timePieceValue: "7",
    pageNum: 1,
    pageSize: 100,
    desc: true,
  });

  const related = await callSkill("amazon-related-asins", {
    asin,
    countryCode: country,
    page: 1,
    pageSize: 50,
  });

  const niches = await callSkill("amazon-niche-info-by-asin", {
    asin,
    countryCode: country,
    count: 10,
  });

  return { traffic, keywords, related, niches };
}

For production work, make country validation endpoint-specific. Passing UK to an endpoint that currently documents only US, JP, and DE should be rejected before the request is sent.

Normalize Optional Fields

Direct upstream payloads can contain optional fields. A missing value should remain null, not become 0. Zero means the API observed a value of zero; null means the field was absent or unusable.

function numberOrNull(value) {
  if (value === null || value === undefined || value === "") return null;
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

function arrayOrEmpty(value) {
  return Array.isArray(value) ? value : [];
}

function normalizeTraffic(payload) {
  const row = arrayOrEmpty(payload?.data)[0] ?? {};

  return {
    asin: row.asin ?? null,
    periodStart: row.dataPeriodStartDate ?? null,
    totalExposureScore: numberOrNull(row.totalExposureScore),
    totalKeywordCount: numberOrNull(row.totalTrafficKeywordCount),
    incomingKeywordCount: numberOrNull(row.totalTrafficKeywordCountIn),
    outgoingKeywordCount: numberOrNull(row.totalTrafficKeywordCountOut),
    naturalExposureScore: numberOrNull(row.naturalSearchExposureScore),
    sponsoredExposureScore: numberOrNull(row.sponsoredProductsExposureScore),
  };
}

function normalizeRows(payload) {
  if (Array.isArray(payload?.data)) return payload.data;
  if (Array.isArray(payload?.items)) return payload.items;
  if (Array.isArray(payload)) return payload;
  return [];
}

The flexible row extractor is defensive. It does not invent records or promise that every endpoint uses the same wrapper. Keep the original payload beside the normalized report when auditability matters.

Produce a Research Report

The report records the endpoint, marketplace, collection time, and result count for every stage. Those fields make later comparisons safer.

function stageReport(endpoint, rows) {
  return {
    endpoint,
    recordCount: rows.length,
    records: rows,
  };
}

async function buildReport(asin, country = "US") {
  const raw = await collectResearch(asin, country);

  return {
    schemaVersion: 1,
    asin,
    country,
    collectedAt: new Date().toISOString(),
    traffic: normalizeTraffic(raw.traffic),
    keywords: stageReport("amazon-asin-keywords", normalizeRows(raw.keywords)),
    competitors: stageReport("amazon-related-asins", normalizeRows(raw.related)),
    niches: stageReport("amazon-niche-info-by-asin", normalizeRows(raw.niches)),
  };
}

const report = await buildReport(process.env.AMAZON_ASIN, "US");
console.log(JSON.stringify(report, null, 2));

Do not rank competitors solely because the related-ASIN endpoint returned them. Review product function, price band, variation structure, and customer need before treating a product as a direct competitor.

Handle Partial Failures

Research pipelines are more useful when one failed stage does not erase three successful stages. Wrap each stage independently and expose the error without leaking credentials or full request headers.

async function capture(name, task) {
  try {
    return { name, ok: true, data: await task() };
  } catch (error) {
    return { name, ok: false, error: String(error.message ?? error) };
  }
}

const asin = process.env.AMAZON_ASIN;

const stages = [];
stages.push(await capture("traffic", () => callSkill(
  "amazon-asin-traffic-summary",
  { searchValue: asin, country: "US", last7d: true, pageNum: 1, pageSize: 10 },
)));
stages.push(await capture("keywords", () => callSkill(
  "amazon-asin-keywords",
  { asin, country: "US", pageNum: 1, pageSize: 100, desc: true },
)));

console.log(JSON.stringify({ asin, collectedAt: new Date().toISOString(), stages }, null, 2));

Persist the successful stage outputs with a run identifier. Retry failed stages later instead of resubmitting the complete pipeline blindly.

Evidence Boundaries

Several safeguards matter before the report influences sourcing or ad decisions:

Exposure scores are composite research signals, not verified sessions, clicks, orders, or revenue.
Keyword volume, rank, conversion, sales, and opportunity fields may be estimated or modeled unless the documentation explicitly states otherwise.
Related products may include substitutes, accessories, bundles, or adjacent solutions.
Source, freshness, coverage, and rate-limit details are not documented for every endpoint.
A missing optional field should remain missing.

The pipeline should support a decision, not hide uncertainty behind one combined score.

Next Step

Nexscope Amazon Data API provides the traffic, keyword, competitor, niche, review, price, sales, and product-data endpoints used to build research workflows through REST API or MCP.

Explore Amazon Data API →

Sources

Disclosure: This article was prepared with AI-assisted editing using the current published API documentation as its technical source of truth.

How to Build an Amazon Product Search Tool with Node.js

Nexscope Team — Wed, 26 Aug 2026 02:38:05 +0000

Amazon product search data becomes much more useful when an application can preserve the context behind every result: the keyword, marketplace, language, page, device, delivery location, and collection time.

This tutorial builds a small server-side Amazon product search workflow with Node.js. It sends a request to the Nexscope Amazon Search API, validates the response, normalizes product records, keeps sponsored and organic placements separate, and adds the reliability controls needed for a production integration.

The finished workflow can support:

Keyword rank checks for a known ASIN
Competitor and new-product discovery
Price and rating comparisons
Sponsored-placement analysis
Search-result snapshots for later comparison

The examples require Node.js 18 or newer because they use the built-in fetch API.

What the API returns

An Amazon storefront search API is different from a catalog API.

Amazon's official Catalog Items API is designed for authorized catalog search and item retrieval. The Amazon Creators API SearchItems operation serves approved affiliate and creator experiences.

The Nexscope Amazon Search API focuses on observed storefront search results. Its documented product fields can include:

ASIN, title, brand, and product URL
Displayed and extracted prices
Rating and rating count
Search position
Sponsored status
Image, delivery, fulfillment, badges, and offers
Additional research signals when returned by the provider

The response is a direct payload. The products array is at the top level rather than inside data or result.

Send the first request

The production endpoint is:

POST https://api.nexscope.ai/api/skill-api/v1/skills/amazon-search/run

Create an API key from the Nexscope API access page, then store it in a server-side environment variable:

export NEXSCOPE_API_KEY="nk_your_key_here"

Never place the key in browser JavaScript, commit it to a repository, or include it in application logs.

A minimal request needs a keyword and page:

curl -X POST \
  "https://api.nexscope.ai/api/skill-api/v1/skills/amazon-search/run" \
  -H "Authorization: Bearer $NEXSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "phone case",
    "page": 1
  }'

For repeatable comparisons, include the storefront context:

const searchContext = {
  keyword: "phone case",
  amazonDomain: "amazon.com",
  language: "en_US",
  sort: "relevanceblender",
  page: 1,
  deliveryZip: "10001",
  device: "desktop",
};

Amazon search results can change with each of these inputs. A rank without its marketplace, device, ZIP code, sort order, page, and collection time is incomplete data.

Build the Node.js client

Create amazon-search.js:

const ENDPOINT =
  "https://api.nexscope.ai/api/skill-api/v1/skills/amazon-search/run";

function requireApiKey() {
  const apiKey = process.env.NEXSCOPE_API_KEY;

  if (!apiKey) {
    throw new Error("NEXSCOPE_API_KEY is not set");
  }

  return apiKey;
}

async function searchAmazon(context) {
  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${requireApiKey()}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(context),
  });

  const responseText = await response.text();

  if (!response.ok) {
    throw new Error(
      `Amazon search failed: ${response.status} ${responseText}`
    );
  }

  let payload;

  try {
    payload = JSON.parse(responseText);
  } catch {
    throw new Error("Amazon search returned invalid JSON");
  }

  if (!payload || typeof payload !== "object") {
    throw new Error("Amazon search returned an invalid payload");
  }

  return {
    ...payload,
    products: Array.isArray(payload.products) ? payload.products : [],
  };
}

The client validates the HTTP status before parsing the payload. It also protects the rest of the application from a missing or malformed products field.

Normalize product records

Upstream fields are optional, so production code should never assume that every product contains a price, rating, position, or sponsored flag.

function normalizeProduct(product, context) {
  return {
    asin: product.asin ?? null,
    title: product.title ?? null,
    brand: product.brand ?? null,
    price: product.extractedPrice ?? product.price ?? null,
    oldPrice:
      product.extractedOldPrice ?? product.oldPrice ?? null,
    currency: product.currency ?? null,
    rating: product.rating ?? null,
    ratingCount: product.ratings ?? null,
    position: product.position ?? null,
    sponsored: product.sponsored ?? null,
    imageUrl: product.imageUrl ?? null,
    productUrl: product.asinUrl ?? null,
    keyword: product.keyword ?? context.keyword,
    marketplace: context.amazonDomain,
    language: context.language,
    page: context.page,
    deliveryZip: context.deliveryZip,
    device: context.device,
    sort: context.sort,
    collectedAt: new Date().toISOString(),
  };
}

Missing values should remain null or unknown. Converting a missing price to 0 creates a fake price. Converting an absent sponsored value to false can incorrectly classify an unknown placement as organic.

Keep paid and organic results separate

Sponsored and organic positions answer different questions. Combining them into one rank metric can hide the difference between advertising visibility and organic search visibility.

function classifyPlacement(product) {
  if (product.sponsored === true) return "sponsored";
  if (product.sponsored === false) return "organic";
  return "unknown";
}

function buildSearchObservations(payload, context) {
  return payload.products.map((product) => ({
    ...normalizeProduct(product, context),
    placementType: classifyPlacement(product),
  }));
}

For a keyword rank check, match the target ASIN and store at least:

Absolute position
Placement type
Page number
Marketplace and language
Delivery ZIP and device
Sort order
Collection timestamp

A single run is a snapshot. Historical rank tracking requires repeated collection with the same context.

Run the complete workflow

Add the execution code:

const context = {
  keyword: "phone case",
  amazonDomain: "amazon.com",
  language: "en_US",
  sort: "relevanceblender",
  page: 1,
  deliveryZip: "10001",
  device: "desktop",
};

try {
  const payload = await searchAmazon(context);
  const observations = buildSearchObservations(payload, context);

  const summary = {
    keyword: payload.keyword ?? context.keyword,
    returnedProducts: observations.length,
    sponsored: observations.filter(
      (item) => item.placementType === "sponsored"
    ).length,
    organic: observations.filter(
      (item) => item.placementType === "organic"
    ).length,
    unknown: observations.filter(
      (item) => item.placementType === "unknown"
    ).length,
  };

  console.log(summary);
  console.log(observations.slice(0, 3));
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}

Run it with:

node amazon-search.js

The normalized records can feed a competitor table, price distribution, sponsored-share report, product-discovery queue, or scheduled rank monitor.

Add production safeguards

A working HTTP request is only the first step. A reliable integration needs retry, caching, schema validation, and observability.

Retry only transient failures

Requests that return 400, 401, or 403 normally need a corrected request, credential, or access setting. Repeating them unchanged wastes time and credits.

Use capped exponential backoff with jitter for 429 and selected 5xx responses:

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function withRetry(task, maxAttempts = 4) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await task();
    } catch (error) {
      lastError = error;

      const status = Number(error.message.match(/failed: (\d{3})/)?.[1]);
      const retryable = status === 429 || status >= 500;

      if (!retryable || attempt === maxAttempts) throw error;

      const baseDelay = 500 * 2 ** (attempt - 1);
      const jitter = Math.floor(Math.random() * 250);
      await sleep(baseDelay + jitter);
    }
  }

  throw lastError;
}

In a larger application, use a typed error object instead of extracting the status code from an error message.

Cache by complete context

A cache key based only on the keyword can mix incompatible searches. Include every parameter that can affect the storefront view:

function createCacheKey(context) {
  const stableContext = {
    keyword: context.keyword,
    amazonDomain: context.amazonDomain,
    language: context.language,
    node: context.node ?? null,
    sort: context.sort,
    page: context.page,
    deliveryZip: context.deliveryZip,
    device: context.device,
  };

  return JSON.stringify(stableContext);
}

The cache duration should follow the business decision. A product-research dashboard can usually tolerate a longer cache than a short-interval rank monitor.

Record useful telemetry

Track:

Request duration
HTTP status
Returned product count
Retry count
Credit cost when present in the response
A non-secret request identifier

Never log the bearer token or complete authorization headers.

Common mistakes

Expecting a response wrapper: Read products from the top-level payload.
Dropping the search context: Store marketplace, language, ZIP, device, sort, page, and collection time with every observation.
Combining paid and organic results: Keep sponsored, organic, and unknown placements separate.
Treating missing as zero: Optional response fields should remain unknown when absent.
Exposing the API key: Call the API from a trusted backend, not directly from browser code.
Assuming built-in history: Live search results become historical data only after an application stores consistent snapshots.
Overcalling the endpoint: Cache identical request contexts and collect only as often as the decision requires.

Next steps

The complete request parameters, response schema, error behavior, and MCP example are maintained in the Amazon Search API documentation.

Start with one keyword and one marketplace. Preserve the full request context, inspect the raw payload, normalize only the fields the application needs, and add scheduled collection after the single-request workflow is stable.

Disclosure: This article was prepared with AI-assisted editing using the current published API documentation as its technical source of truth.