Systems Integrations

Most integrations do not connect to "the API" in the abstract: they connect a specific system of yours: your ERP, your product information tooling, your warehouse system, your accounting package, your shipping tools. This guide maps each of your systems to the part of the Platform it talks to, the mapping discipline that keeps the two sides agreeing, the sync cadence each flow wants, and the reconciliation that proves the sync is honest. Your systems stay yours: the Platform does not dictate your vendors or your internal design. It dictates the shape of the conversation at the boundary.

The pattern every system follows

Whatever the system, the integration has the same skeleton

1. Mapping first. Before any sync runs, write down the field mapping: which of your fields correspond to which API fields, how your identifiers match the Platform's opaque ids (your codes ride on the records; see Catalog), how units, currencies, and date formats convert, and what happens to values your side cannot represent. Most sync defects are mapping defects that were never written down.
2. One direction of authority per field. For every field, one side is the source of truth and the other is a copy. Your warehouse is authoritative for stock counts; the Platform is authoritative for order state. A field with two authorities oscillates; a field with none rots.
3. Cadence matched to the data. Prices and stock move fast; product descriptions move slowly; orders must move the moment they exist. Set each flow's cadence from the data's own rate of change, inside your rate budget (Rate Limit Headers).
4. Reconciliation on a schedule. Every flow gets a periodic comparison that proves both sides agree: and an owner who reads the report. A sync without reconciliation is a hope with a schedule.

ERP: your system of record for products and costs

Your ERP typically holds cost, purchasing, and product master data.

• Product and cost data flow from the ERP to the Platform through the catalog path: individual calls (Catalog) at low volume, feeds at volume (Feeds and Bulk Data).
• Your ERP supplies your costs and your product facts. The selling price is set through the pricing resource as a price (Pricing): whether your ERP computes it or your pricing team does, the value that crosses the boundary is the finished price, never a formula for the Platform to evaluate.
• Orders and returns flow back to the ERP for fulfillment planning and financial posting, from Orders Endpoints and Returns Endpoints, keyed by Platform order id mapped to your ERP's order reference.

Product information management

Where a PIM or content tool owns the sellable story: names, descriptions, images, attributes, placements: it works against Catalog Endpoints and nothing else

• The PIM's discipline is completeness: every sellable product has a name, a description, at least one image, a brand named exactly (Brand and Manufacturer), and a placement. The integration flags gaps rather than publishing around them.
• The PIM never writes prices or stock. Those belong to pricing and inventory respectively; a content tool that "fixes" a price while editing a description has created an untraceable price change.

Warehouse and inventory systems

For stock you hold yourself, your warehouse system is the inventory authority

• It publishes availability to the Platform as Inventory describes: on change where possible, on a short cadence otherwise: and answers for the accuracy of what it publishes.
• The contract is conservative: report what you can ship, correct zero promptly, and revalidate live stock before confirming fulfillment of an order (Fulfillment).
• Order flow into the warehouse is the paid-and-unshipped queue from Orders; shipment flow back out is the ship-and-report step in Fulfillment, with carrier and tracking attached to the right lines every time.

Order management systems

If you run your own OMS between the Platform and your warehouse

• The Platform's order is the authority for the sale: its lines, its prices as charged, its state. Your OMS orchestrates work against it; it does not restate it.
• Keep the two in sync by event (Webhooks) with a reconciliation walk behind it, and resolve every conflict toward the Platform's record, then find the missed event that caused the drift.
• Cancellations, address problems, and exceptions are communicated through the API the moment your OMS knows them. An exception held in your OMS while the Platform shows a healthy order is a buyer being misled by silence.

Accounting

Your accounting system consumes the money trail: orders, payments, refunds, fees, and payouts.

• Read the settlement record through Payments Endpoints and reconcile as Payments describes: charge, deductions, and payout as three distinct facts, matched per order, in decimal, in currency.
• Reconcile daily. Daily reconciliation finds a missing refund the day it happens; monthly reconciliation finds thirty of them, aged and entangled.
• An accounting integration that cannot explain the flow of funds for any transaction: from order to payout, with every deduction named: is incomplete, however tidy its exports look.

Shipping systems

Your shipping tools quote, label, and track

• Labels are bought against the order's address exactly as given; an address that cannot be used stops the shipment for resolution, never for a guessed correction (Fulfillment).
• Tracking is reported back the moment the carrier takes the parcel, against the correct lines, and every shipment is followed until delivery or a named exception.
• One parcel, one current label: replacing a label is a deliberate act recorded as such, never a second purchase made because the first was hard to find.

Customer and marketing systems

Customer-facing systems of yours: a CRM, an email platform, a reviews tool: read Platform data under strict consent discipline

• Marketing contact requires the buyer's opt-in, recorded and revocable; every send honors the channel preferences the buyer set. A CRM sync that imports buyers as marketing targets by default is a compliance incident (Security and Compliance), not a growth tactic.
• Product data for ads and campaigns comes from the catalog and export paths (Feeds and Bulk Data) and must carry the price of record and true availability: an advertisement promising a price or a stock state the Platform does not show is a false-advertising problem.
• Transactional notifications about orders are the Platform's to send; how notification email works from your side of the boundary is covered in Email Architecture. Your systems do not duplicate order confirmations or shipping notices: a buyer who receives two of everything trusts neither.
• Deletion and consent-withdrawal propagate: when a buyer exercises those rights, every system you synced their data into honors them (Data Use, Retention and Deletion).

Failure handling across systems

• Mapping drift: a field changes meaning on one side (a unit change, a new status value) and the sync keeps "working" while producing wrong data. Version your mappings, alert on values your mapping does not recognize, and treat unrecognized values as stop conditions, not nulls.
• Duplicate application: a retried sync applies twice. Every flow writes idempotently (Idempotency Keys) and matches on stable identifiers, so replays converge instead of duplicating.
• Silent staleness: a flow fails and nobody notices for a week. Every flow reports its last successful run, its counts, and its disagreements; a flow whose report nobody reads does not exist for practical purposes.

What good looks like

Each of your systems has a written mapping, a named authority per field, a cadence matched to its data, and a reconciliation report a human reads. The ERP does not set display prices by formula, the PIM does not touch stock, the OMS does not restate the sale, marketing does not invent prices, and accounting can explain every cent. The boundary stays boring: which is exactly what a boundary is for.

Questions about a systems integration: support@aapawz.com.