Create a Connection: the general flow

The same five steps work for every connector: pick it in the Marketplace, name the connection, fill the credentials, test, then map and activate. Plus simulation mode for when you have no keys yet.

A Connection is one configured link to one specific external system — one Shopify store, one UPS account, one ERP company. The per-connector guides (Shopify, UPS) and the connector directory give you the exact fields for each platform; this article is the flow they all share.

Before you start#

• An account on the other platform with admin (or developer) access — most credentials live behind an admin or developer page.
• The field list for your connector from the connector directory (three parts, in this section) — it tells you exactly what to collect, so you do not bounce between tabs.
• For a first connection, prefer the platform’s test / sandbox credentials when it offers them — never practise mapping on live data.

Step 1–2: pick the connector and name the connection#

1. Open Integration → Connector Marketplace, filter by category (e-commerce, carriers, aggregators, EDI, WMS, ERP…) and click your connector’s card → New connection.
2. Give the connection a name your team will recognise later, e.g. “Shopify — US main store” or “UPS — production account”. One platform can have several connections (two stores, test + production); the name is how you tell them apart.

Step 3: fill the credentials#

• The wizard shows exactly the fields this connector needs — they come from the connector registry, the same list as the connector directory. Required fields are marked; there are no hidden extra fields.
• Each field has a help line saying where the value lives on the other platform. When in doubt, the connector directory entry for your platform spells out the full path.
• Secrets (keys, tokens, passwords) are encrypted at rest and never shown back in full — after saving you see only a masked preview. If a secret is wrong, paste a fresh one; you cannot “view” the old one.
• If the connector has no registered field list (rare), the wizard falls back to a generic key-value editor plus secret inputs — fill the key names exactly as the platform’s documentation names them.

Step 4: test the connection#

Testing runs at two levels: connectivity (do the credentials work at all?) and, for document connectors, a document-level preview (one real document pulled and shown as platform fields → standard fields side by side). A failed test tells you which level failed — a 401 means credentials; a preview mismatch means mapping, not credentials. Fix and re-test as often as you need; testing changes nothing on either side.

Where the test record lives: the diagnostic log

Every connection test leaves a step-by-step record on the connection’s detail page — and, for carriers, on the carrier row’s expandable diagnostics. Open it when a test fails: it shows which step stopped and why, in the order the test ran them, so you can tell a credential problem from a mapping problem without guessing. The log records steps and outcomes only — it never stores your secrets, only which key names were used. Before any test has run, the section says so plainly: run a test once and the record appears here.

Step 5: mapping and activation#

1. Pick the preset mapping template for your connector (e.g. the Shopify standard template) and check the document preview once more — especially SKUs, quantities, addresses and any custom fields you rely on.
2. Pair your products: channel SKUs that do not match an OMS product land in Product Mapping’s pending list — pair them there, or orders arrive with unmapped lines.
3. Activate. From now on the connection syncs on its schedule (pull frequency / push triggers you set), and every run shows up in Integration → Runs and Logs. Watch the first few documents before trusting it unattended.

Managing connections afterwards#

• View and edit on their own pages: click a connection in Integration → Connections to open its detail page — status, sync settings, a configuration summary and which Flows use it, all in one place. Editing (name, sync content, frequency, credentials) happens on the connection’s Edit page; saving returns you to the detail page.
• Edit credentials: open the connection and paste the new secret — needed after a key rotation or when a token expires. Test right after editing.
• Disable instead of delete when you pause a channel: a disabled connection keeps its mapping and history, and can be re-enabled in one click. Deleting loses the setup.
• Duplicate connections are allowed where they make sense (two stores of the same platform, one test + one production). Flows pick the exact connection they use, so a test connection never accidentally goes live.