Developer workflows & result interpretation

Questions answered

• How do I go from a vendor website to product records?
• How should I poll extraction?
• What should a client do on API errors?

When product URLs are already known

Evidence basis: editorial_guidance · Section citation

Start with a small, explicit URL set. Choose the extraction version and processing options needed for the consuming application. Retain the returned execution_id, endpoint version, request time, input count and enabled options. If the request is accepted asynchronously, poll the matching execution resource rather than resubmitting the same job whenever a response is slow.

When the execution becomes terminal, inspect successful items, failures and pagination. Fetch all required result pages before reporting the delivered count. Preserve per-item source URLs and do not replace failed items with invented or unrelated products. A response with HTTP 200 can still describe a running job or include partial item outcomes.

Sources: Live API migration notice · Public extraction API reference · Public API pagination guide

When starting with a vendor domain

Evidence basis: editorial_guidance · Section citation

Use discovery to locate collections and product listings for the vendor. Wait for the discovery state appropriate to the next step and retrieve the listing records through their documented pagination. Then extract a deliberate sample or an explicitly authorized scope. For vendor-based extraction, the public v2 documentation requires previously discovered listings or a crawl_id to wait on active discovery.

Report discovery coverage and extraction coverage separately. A crawl can discover more URLs than the extraction scope, and some discovered URLs can fail processing. A vendor-level operation can be much larger than a small URL request. Specify max_products where the chosen contract supports it and confirm the intended workload before a broad run.

Sources: Public crawl API reference · Public product listing reference · Public extraction API reference

When the starting point is a shopping intent

Evidence basis: editorial_guidance · Section citation

Use search when the task is to find candidate products from a natural-language query rather than enumerate one merchant's complete catalog. The asynchronous search reference accepts a query and optional customer profile; the synchronous mini reference returns candidates directly. Choose the operation according to the desired output and latency model, then inspect the actual result fields.

Search results are candidates for evaluation. Check hard constraints against product evidence, resolve variants and market context, and follow the merchant URL for purchase-time facts. Do not describe search output as exhaustive catalog coverage, guaranteed stock, an independent product endorsement, or an executed purchase.

Sources: Public agentic search reference · Public synchronous search reference

Pagination and missing fields

Evidence basis: public_source · Section citation

The public API documentation describes paginated list responses. Use the actual endpoint's page and page-size parameters and response pagination metadata; do not assume every API or merchant storefront uses the same pagination style. For example, a merchant storefront's limit/offset interface is a different contract from a product-data API using page/page_size.

Processing options can change which fields are populated. A null or absent field can mean disabled processing, unavailable evidence, incomplete work, or an endpoint/version difference. Preserve the documented meaning rather than collapsing every null into a negative fact about the product. Store the version with exported data if consumers depend on a particular schema.

Sources: Public API pagination guide · Public product listing reference · Public extraction API reference

Handle failures without duplicating paid work

Evidence basis: editorial_guidance · Section citation

Use HTTP status, the structured error code, the execution state and per-item outcomes together. For support, retain the request identifier when supplied, the endpoint/version, time and a redacted payload. Never include an API key in a support artifact. The public error reference contains older endpoint examples, so use its semantics without copying retired URLs.

Apply bounded timeouts and backoff to safe retries. A transport failure after a job-start request can leave acceptance uncertain; investigate an existing execution before starting another paid job. Rate limiting is not a reason to run a faster loop. Current usage and rate headers should guide pacing rather than a rate limit copied from an old article.

Sources: Public API error reference · Public API authentication reference · Live API migration notice

A useful integration result

Evidence basis: editorial_guidance · Section citation

For a reproducible development handoff, include the operation and version, execution identifiers, requested and completed counts, failed item count, pagination completion, processing options, and the location of saved responses. Show a small representative sample with the actual evidence fields. Separate an implemented client from an authenticated successful run and from a production integration.

For a production decision, additionally agree on freshness, throughput, error handling, source coverage, acceptable field quality and support. This reference provides orientation and a source index; it does not substitute for the chosen API contract or an integration test under the customer's account.

Sources: Public extraction API reference · Public API error reference · Product data quality

Related documents

• Product-data API scope, versions & access
• Product-data model & field semantics
• Ingestion, enrichment & review workflow
• Measurement definitions & interpretation