> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync Server connectors

> A connector is a JSON definition, not code — and one field in it decides whether an ambiguous failure becomes a duplicate shipment.

Adding a warehouse or 3PL to the Sync Server is a **catalog entry**, not a code
change. A connector is a JSON definition — auth, endpoints, pagination, cursors
— plus one or more mapping rule sets, run by a generic runtime through the same
resilience, ingestion, checkpoint and crash-safe submission machinery every
hand-written integration uses.

<Note>
  Hand-written integrations are reserved for the strategic platforms where depth
  justifies compiled code — Shopify, NetSuite, Amazon, DCL. Everything else is a
  definition, and existing per-partner code migrates by attrition: when one
  needs a fix, it is ported to a catalog entry rather than patched.
</Note>

## What a definition carries

| Section           | Describes                                                        |
| ----------------- | ---------------------------------------------------------------- |
| `auth`            | How to authenticate — the scheme and where credentials come from |
| `endpoints`       | The partner's URLs, per operation                                |
| `pagination`      | How to walk a result set                                         |
| `cursors`         | Where to resume after a restart                                  |
| `dedupPolicy`     | What happens when a submission fails ambiguously                 |
| Mapping rule sets | How partner fields map to commerce records, per flow             |

A definition in outline:

```json theme={null}
{
  "name": "acme-wms",
  "auth": { "type": "bearer", "credential": "ACME_WMS_TOKEN" },
  "endpoints": {
    "order_push": { "method": "POST", "path": "/v2/orders" },
    "shipment_pull": { "method": "GET", "path": "/v2/shipments" }
  },
  "pagination": { "style": "cursor", "param": "after", "limit": 100 },
  "cursors": { "shipment_pull": "updated_at" },
  "dedupPolicy": "no_retry_after_ambiguous",
  "idempotencyHeader": "Idempotency-Key"
}
```

## dedupPolicy — read this before shipping a push flow

An **ambiguous failure** is a timeout or dropped connection where the remote may
already have accepted the order. You cannot tell from your side whether it did.
One field decides what happens next, and it drives all three layers — transport
retries, the submission guard, and the stale-in-flight watchdog — so they can
never disagree with each other.

| Value                                    | On an ambiguous failure                     | Transport retries                                     |
| ---------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
| `no_retry_after_ambiguous` **(default)** | The order parks in-flight for manual review | Never                                                 |
| `safe_to_retry`                          | Released for normal backoff retry           | Permitted, and only with `idempotencyHeader` declared |

<Warning>
  **The wrong answer here is how duplicate shipments happen.** Choose
  `safe_to_retry` only when you have *proof* the remote deduplicates — a
  documented idempotency key it honours, not an assumption that a second
  identical order would be rejected. A dedup claim without `idempotencyHeader`
  still gets exactly one send, because the platform will not take your word for
  it.
</Warning>

<Note>
  The default parks the order rather than retrying, which means a real outage
  produces a queue of orders awaiting review instead of a queue of possible
  duplicates. That is the intended trade: a human looking at ten parked orders
  is cheaper than a customer receiving two shipments.
</Note>

## Shipping one

```bash theme={null}
# validate a definition against its golden fixtures before it goes in the catalog
stateset-sync connectors validate ./connectors/acme-wms.json

# dry-run a flow against the fixtures, with no partner traffic
stateset-sync connectors test ./connectors/acme-wms.json --flow order_push
```

A catalog entry ships with golden fixtures, so a mapping change that silently
drops a field fails review rather than production. Several long-tail ports have
found long-standing silent mapping failures in the code they replaced —
fixtures are the reason.

## Next steps

<CardGroup cols={2}>
  <Card title="API contract" icon="file-contract" href="/stateset-sync-server-api-contract">
    Envelopes, error codes and correlation ids.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/stateset-sync-server-troubleshooting">
    Circuit breakers, stuck orders and rate limits.
  </Card>

  <Card title="gRPC dispatch" icon="server" href="/stateset-sync-server-grpc-dispatch">
    Getting orders into the Sync Server durably.
  </Card>

  <Card title="gRPC flow" icon="diagram-project" href="/stateset-sync-server-grpc-flow">
    What happens to an order once it is accepted.
  </Card>
</CardGroup>