Docs navigation
Home / Docs / Building a partner app

Building a partner app

How back-office integrations install into a Foundry organization — scoped keys, webhook endpoints, and the curated partner program.

A partner app is a back-office integration that a Foundry customer installs into their organization — accounting sync, EDI, analytics, a CRM bridge. Foundry provisions the credentials your app needs automatically, so you never ask a customer to hand-create and paste an API key.

App vs. channel

Foundry draws a firm line:

  • If your integration sells or lists products through a storefront-like presence, it’s a channel — build against the Storefront API.
  • If it syncs data with a back-office system (accounting, EDI, CRM, analytics), it’s an app — build against the Partner API.

This page is about apps.

The install model

Every app declares up front the permission scopes it needs and the webhook events it subscribes to. Those are reviewed as a set, and an installation’s credential carries exactly the scopes declared — nothing more. An app built to read invoices and purchase orders can’t touch anything else, the same least-privilege model as any scoped key.

How the credential reaches your app depends on who built it.

Apps built by outside developers — OAuth

Your app sends the merchant to Foundry, they approve a consent screen listing exactly what you asked for, and your server receives the token directly. The merchant never sees or handles a credential, so there’s nothing to paste into a config field, leak in a screenshot, or hunt down later to revoke.

This is the path for every app Foundry didn’t build, including in your own sandbox. The full flow — endpoints, parameters, error codes — is in connecting an app with OAuth.

Two things that surprise people:

  • You register your own webhook endpoint after you hold a token. Nothing is provisioned for you, because the endpoint belongs to you rather than the merchant.
  • Re-authorizing replaces your credential. The previous token is revoked immediately.

Apps built by Foundry

QuickBooks Sync and ShipStation mint their key at install and show the customer the credentials once, along with a webhook endpoint subscribed to the app’s events. This path predates OAuth and stays as it is; it isn’t available to outside developers.

Either way

Uninstalling revokes the key and removes any webhook endpoint. Your app runs on your own infrastructure — there’s no app runtime inside Foundry. It uses the Partner API for reads and writes and receives webhook events for changes, like any other client.

A concrete example

An accounting-sync app might declare the scopes invoices.read, pos.read, and orders.read, and subscribe to invoice.created, purchase_order.status_changed, and order.created. Once connected it holds a token limited to those reads, and an endpoint that fires when an invoice is recorded, a PO is received (toStatus: "RECEIVED"), or an order lands — everything an integration needs to keep the books in sync, and nothing it doesn’t.

Working with us

Developer access is granted, not requested — there’s no open signup. Talk to us about what you’re building; if it’s a fit we link your organization to a developer identity and provision you a seeded sandbox.

After that you’re self-serve: you build against your sandbox, submit versions, and most releases publish without anyone touching them. The full path — sandbox, submission, the automated checks, and what sends a review to a human — is in publishing an app.