# Sync ecommerce orders

Import orders into your product, associate them with customers and stores, and keep the imported records current. This guide starts with a read-only sync; it does not create orders or issue refunds.

## Connect one store

Follow [your first Ecommerce API call](/first-api-call?api=ecommerce) to create a consumer, connect a store through Vault, and read a record. Keep the API key on your server. Resolve the consumer from the signed-in customer's organization rather than accepting an arbitrary consumer ID from the browser.

Check the connector's [Orders, Customers, and Stores coverage](/apis/ecommerce/coverage) and setup permissions before building. Operations, filters, and available fields depend on the connector.

**Checkpoint:** a read returns records from the intended customer's store. An empty list is a valid response; confirm that the store has data before diagnosing it as an authentication failure.

## Import orders

Use [List orders](/apis/ecommerce/reference/orders?useCase=orders) with a small page size for the first request. Inspect the response before choosing which fields your product needs.

Store each order under a key that includes the consumer, connector, and source order ID. Upsert by that key so replaying a page updates an existing record instead of creating a duplicate. Preserve monetary amounts and their currency together; do not assume every store uses the same currency.

Follow the returned next cursor until pagination is complete. Save your checkpoint only after the page is persisted. See [pagination](/pagination) for the request and response format.

**Checkpoint:** running the same import twice leaves the same number of orders in your database.

## Resolve customers and stores

Use the order's customer and store references to link records from [Customers](/apis/ecommerce/reference/customers?useCase=orders) and [Stores](/apis/ecommerce/reference/stores?useCase=orders). Treat a missing customer reference as a possible guest checkout rather than dropping the order. Keep unresolved references visible so a later import can fill them in.

Avoid one customer request per order: cache customer records within the sync and fetch each missing reference once. Keep the cache scoped to the consumer and connector.

**Checkpoint:** the imported order shows its source store and either its customer or an explicit guest/unresolved state.

## Reconcile changes

Use incremental filters only when the selected connector supports them. Otherwise, schedule a paginated reconciliation and upsert by the same stable keys. Do not infer that a record was deleted from an incomplete or failed scan.

If the connector offers relevant [webhook events](/guides/webhooks), use them to trigger a read of the affected record. Keep periodic reconciliation to recover missed events. Verify cancellation and refund behavior in the connector's field mappings; a status change is not proof that money moved.

## Recover a failed import

- **401:** check the server API key, app ID, and consumer context before retrying.
- **403:** review the connection's permissions with the customer administrator.
- **429:** respect the retry delay and resume from the last persisted checkpoint.
- **Unexpected data:** inspect the request and downstream child calls in [Logs](/logs), then compare the connector's mapping with the stored order.

See [error recovery](/errors) for response details. Keep request IDs for investigation; do not put customer payloads or credentials in shared tickets.

**Checkpoint:** interrupt a sync mid-page and restart it. Previously saved orders remain intact, duplicates are not created, and the import reaches the remaining pages.

## Frequently asked questions

### Does this workflow create orders or issue refunds?

No. This guide imports orders into your application using reads. It does not create orders or move money. A cancellation or refund-related field should be interpreted using the connector’s mappings, not treated by itself as proof that a payment was reversed.

### Should I discard an order with no customer reference?

No. It may be a guest checkout or an unresolved relationship. Keep the order and show an explicit guest or unresolved state, then resolve the reference when sufficient source data is available. See [Resolve customers and stores](#resolve-customers-and-stores).

### How do I avoid duplicate orders when replaying an import?

Upsert by consumer, connector, and source order ID. Save a page checkpoint only after persisting the page, and retain currency alongside monetary amounts. Running the same import again should update existing records. See [Import orders](#import-orders).

### Do all ecommerce connectors support incremental order updates?

No. Verify filter and webhook support before using them. When incremental reads are unavailable, perform paginated reconciliation and upsert by the same stable keys. Do not infer deletion from an incomplete or failed scan. See [Reconcile changes](#reconcile-changes).