> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Creating an External Installation Button

Single-click apps can be installed from outside the BigCommerce control panel. For example, an install button on your company's site that directs the merchant to download your app. This tutorial provides step-by-step instructions for creating an external install button for BigCommerce single-click apps.

## Creating an install button

First, embed an install button like the one below, at any web location from which you’d like to enable app installation.

![Install Button](/_fern-img/271477d0311729457abdd8ae9976522556fe3ae1f046194a1f9210e4951085b8.webp)

Redirect anyone who presses your button to: `https://login.bigcommerce.com/app/{CLIENT_ID}/install`.

## Configuring the button

When clicked, your button should open a modal similar to the image below. We recommend a modal sized `900px` wide by `450px` high.

![Install Button](/_fern-img/d4f3c298856aeed57196dd5a4099860c1a12451a3c9740c833a16ecfb283a1b4.webp)

Your button will link merchants to BigCommerce's install endpoint for your application. Once the merchant clicks the link, they will be prompted to sign in and authorize your application.

## Rendering success and failure pages

Modify your website's server-side code to serve either a success or failure page, depending on whether the external installation was successful or unsuccessful.

If you skip this step, your application will load in the iFrame created by your button. To ensure a good experience for your users, we strongly recommend that you return a confirmation page, instead of allowing your application to be loaded in that modal.

## Handling errors

If your application's installation was initiated and completed through an external link, BigCommerce will send your `auth` callback endpoint an extra parameter called `external_install`.

If you receive this parameter and there are no errors, make a `GET` request to the install succeeded endpoint.

```http showLineNumbers={false}
GET /app/{CLIENT_ID}/install/succeeded  HTTP/1.1
Host: login.bigcommerce.com
```

If there were errors, make a `GET` request to the install failed endpoint:

```http showLineNumbers={false}
GET /app/{CLIENT_ID}/install/failed  HTTP/1.1
Host: login.bigcommerce.com
```

Depending on which endpoint you call, BigCommerce will render a success or failure page to the modal.

## Code samples

Handling errors in Lua:

**`Example: Lua error handling`**

```lua title="Example: Lua error handling" showLineNumbers={false}
if params['external_install']
    return get 'https://login.bigcommerce.com/app/m8e1mkkmjw2xjinydqz7ie05to1y2nk/install/succeeded'
end

redirect '/'

rescue => e
if params['external_install']
    return get 'https://login.bigcommerce.com/app/m8e1mkkmjw2xjinydqz7ie05to1y2nk/install/failed'
end
```

## Next steps

* [Follow best practices](/developer/docs/integrations/apps/guide/following-best-practices).
* [Check requirements](/developer/docs/integrations/apps/guide/approval-requirements).
* [Publish your app](/developer/docs/integrations/apps/guide/publishing-apps).

## Resources

### Sample apps

* [Node / React / Next.js](https://github.com/bigcommerce-edu/starter-sc-app-next)
* [Python / Flask](https://github.com/bigcommerce/hello-world-app-python-flask)
* [PHP / Silex](https://github.com/bigcommerce/hello-world-app-php-silex)
* [Ruby / Sinatra](https://github.com/bigcommerce/hello-world-app-ruby-sinatra)
* [Laravel / React](https://github.com/bigcommerce/laravel-react-sample-app)

### Tools

* [Node API Client](https://github.com/bigcommerce/node-bigcommerce/)
* [Python API Client](https://github.com/bigcommerce/bigcommerce-api-python)
* [PHP API Client](https://github.com/bigcommerce/bigcommerce-api-php)
* [Ruby API Client](https://github.com/bigcommerce/bigcommerce-api-ruby)
* [Ruby OmniAuth Gem](https://github.com/bigcommerce/omniauth-bigcommerce)
* [BigDesign Developer Playground](https://developer.bigcommerce.com/big-design)
* [Figma Component Library](https://www.figma.com/community/file/1359989842592268260/bigdesign-component-library)

### Blog posts

* [How to Test App Authentication Locally with ngrok](https://medium.com/bigcommerce-developer-blog/how-to-test-app-authentication-locally-with-ngrok-149150bfe4cf)
* [Building a BigCommerce App Using Laravel and React](https://medium.com/bigcommerce-developer-blog/building-a-bigcommerce-app-using-laravel-and-react-711ceceb5006)
* [BigDesign Tutorial](https://medium.com/bigcommerce-developer-blog/bigdesign-build-native-looking-uis-with-the-bigcommerce-design-system-fb06a01a24f2)