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

# Custom Ecommerce Apps Overview

> Build a full ecommerce integration with Vambe by registering an app. You write the code on your side; Vambe never has to write code to integrate with you.

## What are Custom Ecommerce Apps?

**Custom Ecommerce Apps** let any ecommerce provider build a first-class integration with
Vambe — products, orders, abandoned checkouts, fulfillment and live assistant tools —
**without Vambe writing any code for you**. You register an app, implement a small,
well-defined contract, and Vambe handles the rest.

It works in two directions:

<CardGroup cols={2}>
  <Card title="Inbound — you push to Vambe" icon="arrow-right-to-bracket">
    Your platform sends canonical webhooks (orders, checkouts, fulfillment, products)
    to Vambe. Vambe ingests them into the same pipeline used by native integrations.
  </Card>

  <Card title="Outbound — Vambe calls you" icon="arrow-right-from-bracket">
    When the AI assistant needs live data (order status, stock, a checkout link),
    Vambe calls URLs you declared, authenticated with the merchant's OAuth token.
  </Card>
</CardGroup>

## Core model

There are two distinct concepts:

| Concept          | What it is                                                                                                            | Who owns it                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **App**          | The integration definition you register once: metadata, OAuth config, and which capabilities you support.             | You (the provider)             |
| **Installation** | A single merchant connecting their store to your app via OAuth. Each installation holds that merchant's access token. | A Vambe account (the merchant) |

One approved app can be installed by many merchants. Every webhook and every outbound call
is scoped to a single installation.

## How a provider integrates — end to end

<Steps>
  <Step title="Register your app">
    Create the app with your metadata, contact details, OAuth endpoints, and the
    capabilities you support. You receive a **signing secret** (shown once).
  </Step>

  <Step title="Test on your own account">
    While unapproved, your app is visible only to the account that created it. Install it
    on your own store and exercise the full flow.
  </Step>

  <Step title="Submit for review">
    Submit the app. The Vambe team is notified and reviews it. Once approved, the app
    becomes available to every Vambe account.
  </Step>

  <Step title="Merchants connect via OAuth">
    A merchant clicks **Connect** in Vambe and is redirected to your site to approve
    permissions. Vambe exchanges the code for an access token and stores the installation.
  </Step>

  <Step title="Data flows both ways">
    You push canonical webhooks; Vambe calls your capability URLs on demand. No
    per-provider code on Vambe's side.
  </Step>
</Steps>

## App lifecycle

An app moves through these states:

| State            | Visible to   | Meaning                                                       |
| ---------------- | ------------ | ------------------------------------------------------------- |
| `draft`          | Creator only | Being built/edited.                                           |
| `pending_review` | Creator only | Submitted; awaiting Vambe approval.                           |
| `approved`       | All accounts | Live and installable by any merchant.                         |
| `rejected`       | Creator only | Needs changes; edit and resubmit.                             |
| `suspended`      | Nobody       | Disabled by Vambe; stops receiving events and outbound calls. |

<Note>
  The connection between a merchant and your app is **always OAuth 2.0**. Merchants never
  type API keys into Vambe — they approve scopes on your own page.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Create your app" icon="rocket" href="/docs/app-platform/create-your-app">
    Register the app and get your signing secret.
  </Card>

  <Card title="OAuth connection" icon="key" href="/docs/app-platform/oauth-connection">
    Implement the merchant connection flow.
  </Card>

  <Card title="Inbound webhooks" icon="arrow-right-to-bracket" href="/docs/app-platform/inbound-webhooks">
    Push orders, checkouts, fulfillment and products.
  </Card>

  <Card title="Outbound capabilities" icon="arrow-right-from-bracket" href="/docs/app-platform/outbound-capabilities">
    Answer the assistant's live data requests.
  </Card>
</CardGroup>