Custom API integrations

Custom API integrations are a different feature from the Apps marketplace. The Apps page lists pre-built connectors (Stripe, Shippo, Google & YouTube, and so on) you install in one click. A Custom API integration is for everything else: a warehouse system, a POS, an internal tool, or any external API that doesn't have a pre-built Brainerce app. You reach it from Custom APIs in the dashboard, not from the Apps page.

Creating an integration

1. Open Custom APIs and click Add Custom API.

2. Basic info: give it a name (for your own reference) and its base URL (the root URL of the external API, without a trailing slash). An optional description helps if you or a teammate revisit this later.

3. Authentication: choose how the external API expects to be called:

   Type	What you provide
   API Key	A header name (defaults to X-API-Key) and the key value.
   Bearer Token	A token, sent as Authorization: Bearer <token>.
   Basic Auth	A username and password, sent as a standard Authorization: Basic header.
   OAuth 2.0	Not available yet. Shown in the list for visibility into what's coming, but you cannot select it today.

   Credentials are encrypted before they're stored and are never shown again in full once saved. The dashboard only confirms that a key, token, or username/password is on file.

4. Sync direction and data: choose Inbound Only (import from the API), Outbound Only (export to the API), or Bidirectional, and check which of Products, Orders, and Inventory the integration is meant to cover.

What "sync direction" and "data to sync" actually do today

This is worth being precise about. Saving a sync direction and a set of data types records your intent: it does not, by itself, start moving any data. There is currently no scheduled job or background sync that reads these settings and imports or exports products, orders, or inventory automatically. If you're connecting a custom API expecting Brainerce to immediately start pulling in orders or pushing out stock levels the way an installed marketplace app does, that automatic movement isn't there yet. Treat these fields as documentation of what the integration is for, not as an active pipeline.

Testing a connection

Click Test on a saved integration to send a single request to its base URL using the credentials you configured. This checks two things at once: that the URL is reachable, and that your credentials are accepted (a wrong API key or bad Basic Auth typically comes back as an HTTP 401/403, which the test surfaces as the actual status code and text the external API returned). A successful test marks the integration Connected; a failure marks it Error and records the reason, visible next to the integration afterward.

A successful test only confirms reachability and auth. It does not confirm the API returns data in a shape Brainerce understands, because (per the section above) nothing reads or writes catalog data through this connection yet.

Managing an integration

• Status shows as Connected, Disconnected, Paused, or Error, based on the last test or (if this changes in the future) sync attempt.
• Enable/disable without deleting it, if you want to keep the configuration on file but stop using it for now.
• Editing credentials merges what you type with what's already saved. You don't have to re-enter every field just to change one, and leaving a credential field blank on an edit keeps the existing value rather than clearing it.
• Deleting an integration removes its configuration and stored credentials permanently. It does not undo anything already moved through it (not that anything currently is, per the section above), and cannot be recovered once removed.

Who can manage these

Viewing the list of Custom API integrations needs the View store settings permission. Creating, editing, deleting, or testing one needs Manage integrations, the same permission that gates installing and configuring marketplace apps.

What's next?

• Apps & marketplace: the pre-built connectors to check before building a custom one.