> ## 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.

# Create Your App

> Register an ecommerce app, configure its OAuth and capabilities, and submit it for review.

## Register an app

Create your app with a single authenticated request. Authentication uses your Vambe API key
in the `x-api-key` header.

```bash theme={null}
curl --request POST 'https://api.vambe.me/api/ecommerce-app' \
  --header 'x-api-key: your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Ecommerce X",
    "description": "Connects My Ecommerce X stores to Vambe.",
    "logo_url": "https://cdn.myecommerce.com/vambe/logo.png",
    "website_url": "https://myecommerce.com",
    "developer_name": "My Ecommerce X Inc.",
    "contact_email": "integrations@myecommerce.com",
    "contact_phone": "+56912345678",
    "oauth": {
      "authorize_url": "https://myecommerce.com/oauth/authorize",
      "token_url": "https://myecommerce.com/oauth/token",
      "client_id": "vambe-client-id",
      "client_secret": "vambe-client-secret",
      "scopes": ["read_orders", "read_products"],
      "account_info_url": "https://api.myecommerce.com/vambe/account"
    },
    "capabilities": {
      "inbound_events": ["order", "checkout", "fulfillment", "product"],
      "outbound": {
        "order_get": { "url": "https://api.myecommerce.com/vambe/orders" },
        "stock_get": { "url": "https://api.myecommerce.com/vambe/stock" },
        "checkout_create": { "url": "https://api.myecommerce.com/vambe/checkout" }
      }
    }
  }'
```

The response includes a **`signing_secret`**:

```json theme={null}
{
  "id": "f1e2d3c4-…",
  "slug": "my-ecommerce-x",
  "status": "draft",
  "signing_secret": "9b1f…(64 hex chars)…",
  "...": "..."
}
```

<Warning>
  The `signing_secret` is returned **only on creation** (and on rotation). Store it securely —
  you need it to sign every inbound webhook. You can rotate it later, but it is never shown
  again on read.
</Warning>

## Fields

### Metadata

<ParamField path="name" type="string" required>Display name shown to merchants.</ParamField>
<ParamField path="slug" type="string">Stable identifier. Auto-derived from `name` if omitted; must be unique.</ParamField>
<ParamField path="description" type="string" required>Short description shown in the connect UI.</ParamField>
<ParamField path="logo_url" type="string (https)" required>Public URL of your app logo.</ParamField>
<ParamField path="website_url" type="string (https)">Your marketing/site URL.</ParamField>

### Contact (required)

The Vambe team uses these to reach you during review and operations.

<ParamField path="developer_name" type="string" required>Your company/organization name.</ParamField>
<ParamField path="contact_email" type="string" required>Contact email.</ParamField>
<ParamField path="contact_phone" type="string" required>Contact phone number.</ParamField>

### OAuth

See [OAuth Connection](/docs/app-platform/oauth-connection) for the full flow.

<ParamField path="oauth.authorize_url" type="string (https)" required>Where Vambe redirects the merchant to approve scopes.</ParamField>
<ParamField path="oauth.token_url" type="string (https)" required>Where Vambe exchanges the authorization code for tokens.</ParamField>
<ParamField path="oauth.client_id" type="string" required>The client id you issued for Vambe.</ParamField>
<ParamField path="oauth.client_secret" type="string" required>The client secret you issued for Vambe. Stored encrypted at rest.</ParamField>
<ParamField path="oauth.scopes" type="string[]">Scopes requested during authorization.</ParamField>
<ParamField path="oauth.account_info_url" type="string (https)">Optional. Lets Vambe fetch the store identity after connection — required for multi-store apps.</ParamField>

### Capabilities

<ParamField path="capabilities.inbound_events" type="string[]">
  Which canonical events you commit to pushing: any of `order`, `checkout`, `fulfillment`,
  `product`. See [Inbound Webhooks](/docs/app-platform/inbound-webhooks).
</ParamField>

<ParamField path="capabilities.outbound" type="object">
  URLs Vambe calls on demand. Each entry is `{ "url": "https://..." }`. Supported keys:
  `order_get`, `stock_get`, `checkout_create`. If you omit a key, Vambe simply won't offer
  that assistant tool for your app. See [Outbound Capabilities](/docs/app-platform/outbound-capabilities).
</ParamField>

## Manage and submit

<Steps>
  <Step title="Iterate (draft)">
    Update the app while it is `draft` or `rejected`:

    ```bash theme={null}
    curl --request PATCH 'https://api.vambe.me/api/ecommerce-app/{id}' \
      --header 'x-api-key: your_api_key_here' \
      --header 'Content-Type: application/json' \
      --data '{ "description": "Updated copy" }'
    ```
  </Step>

  <Step title="Submit for review">
    ```bash theme={null}
    curl --request POST 'https://api.vambe.me/api/ecommerce-app/{id}/submit' \
      --header 'x-api-key: your_api_key_here'
    ```

    This moves the app to `pending_review` and notifies the Vambe team.
  </Step>

  <Step title="Get approved">
    Once Vambe approves it, the app becomes `approved` and is installable by any account.
    Until then it is visible only to your account.
  </Step>
</Steps>

### Other endpoints

| Method   | Path                                    | Purpose                                  |
| -------- | --------------------------------------- | ---------------------------------------- |
| `GET`    | `/api/ecommerce-app`                    | List your apps.                          |
| `GET`    | `/api/ecommerce-app/{id}`               | App detail (no secret).                  |
| `POST`   | `/api/ecommerce-app/{id}/rotate-secret` | Generate a new signing secret.           |
| `DELETE` | `/api/ecommerce-app/{id}`               | Delete the app.                          |
| `GET`    | `/api/ecommerce-app/available`          | Apps installable by the current account. |

<Note>
  Editing an `approved` app is blocked — only `draft`/`rejected` apps are editable. Editing a
  `rejected` app moves it back to `draft` so you can resubmit.
</Note>