Feeds and Bulk Data

This guide covers moving product data at volume: supplying a feed for your catalog, what a feed must contain, how cadence, rate limits, and backpressure work, and how bulk export carries your data out. Feeds are scheduled, high-volume, and designed for completeness over latency. Individual calls are covered in Catalog; feeds are how you keep ten thousand products correct, not ten. Change notifications in near-real time are a different tool: Webhooks: and the two combine: bulk for the baseline, events for the changes.

Choosing the path

• A few hundred changes a day: individual API calls with idempotency keys are simpler and fresher. Do not build feed machinery you do not need.
• A full catalog, or thousands of daily changes: supply a feed (inbound) and take exports (outbound). The rest of this guide assumes this scale.
• Either way: never poll resource collections row by row in a tight loop to imitate a feed. That pattern is what rate limits (Rate Limit Headers) exist to stop, and it produces the stalest copy at the highest cost.

Supplying a product feed

A feed is a machine-readable product list the Platform reads on an agreed cadence: your product identifiers, names, descriptions, brand, images, variants with their codes and barcodes, prices, weights and dimensions where shipping needs them, and availability. Agree the feed location and cadence with the Company when your integration is set up (support@aapawz.com); the rules below are the contract your feed is read against.

1. Identifiers are forever. The same product carries the same product code on every read. That code is how the Platform matches a feed line to the existing product. Changed codes make every product look new: duplicate listings, orphaned price history, lost placement. Never change a code; never reuse a retired code.
2. Send complete lines. A line missing images, a price, or a variant code creates a product someone must fix by hand: or worse, a product that lists wrong. Validate the feed against the field requirements in Catalog Endpoints before the Platform reads it, not after a sync fails.
3. Flag discontinuations explicitly. A product that vanishes from the feed is ambiguous: ended, or a feed defect? Mark discontinued products as discontinued, so they are withdrawn from sale in an orderly way and their history stays intelligible.
4. Normalize on your side. Brand names exactly as the brand directory holds them (Brand and Manufacturer), consistent units, consistent variant naming. A feed that arrives clean lists faster, with fewer interventions, than one the Platform must untangle.
5. Change only what changed. Cosmetic churn: reworded descriptions that differ only in whitespace, reordered fields, regenerated values: defeats change detection and burns the sync budget re-processing products that did not change. Stable output for stable inputs is a feed-quality requirement.

How a sync run behaves

Understanding the run keeps you from fighting it

• The Platform reads the feed on the agreed cadence and compares before it writes: lines whose substance is unchanged are skipped, and only genuine changes flow through: new products, price updates, stock changes, new images, discontinuations.
• Category placement never changes on re-sync. Placement is merchandising; a price or stock sync that re-placed products would undo merchandising work on every run. Set placement through the catalog path, not through the feed.
• A run reports what it did: lines read, changed, skipped, and rejected, with the reason for each rejection. Read the report. A rejected line retried unchanged will be rejected again; the fix is in your data.

Rate limits and backpressure

1. Serve the feed fast, completely, and at a stable location. The read budget per run is bounded; a feed that takes very long to serve risks an incomplete read and a partial sync.
2. If your side must throttle a consumer of your data, answer 429 with retry guidance rather than timing out. A timeout is ambiguous: did the read happen? A 429 is explicit, and consumers built to this contract back off for the stated window and resume, while other work continues.
3. Expect the same discipline toward you: if your systems call the Platform faster than your tier allows, you receive 429 responses with the headers in Rate Limit Headers. Back off for the stated window; do not retry harder. Steady-state 429s mean the design is wrong: polling where feeds or webhooks belong.

Bulk export

The outbound path mirrors the inbound one

• Exports carry your products, variants, prices, placements, and availability as point-in-time snapshots, stamped with the time they were generated.
• Use exports for replication: a local reporting copy, a marketing platform's catalog, a warehouse baseline: never for real-time decisions. A snapshot begins aging the moment it is generated.
• For fresher data than the export cadence, combine: export for the baseline, webhooks for the changes, and a periodic export to prove the two agree.
• Keep exported buyer-adjacent data within the retention limits that govern it (Data Use, Retention and Deletion); an export is a copy you are responsible for, not an archive exempt from deletion duties.

Failure handling

• Products duplicated after a feed change: your codes changed. Restore the original codes, and have the duplicates resolved with support@aapawz.com before the next run multiplies them further.
• A sync changed nothing you expected it to change: compare what the feed actually contains now against what you believe it contains; in most cases the feed did not update, or the lines churned cosmetically in a way that hid the substantive change among noise.
• Rejections concentrated in one category: a field requirement changed or your source data degraded for that range. Fix at the source system; per-line hand edits are undone by the next run.
• Feed endpoint down at read time: the run is skipped, not half-applied. Products keep their last good state. Restore the endpoint; do not compensate by hammering individual calls beyond your rate budget.

What good looks like

Codes never change, lines arrive complete and normalized, discontinuations are explicit, reports are read after every run, and exports reconcile against the live catalog on a schedule. A clean feed gets products live faster and keeps them right; a disordered one waits on manual review: the difference is entirely in the data you send.