Publishing an API App

• Overview
• Step 1: Obtain a Sandbox Site
• Step 2: Develop Your Integration
• Step 3: Request App Publishing Privileges
• Step 4: Publish your App
• Troubleshooting

Overview

App developers can create integrations with AmeriCommerce using the REST API. To do so, the application needs to be authenticated. One way authenticate is to manually create an app in Tools > Apps and Addons > Apps and Integrations, which generates an app secret and token for the individual store the app was created on. This will allow the integration to connect with that specific store, but what if the developer would like to make the integration available to all AmeriCommerce site's without requiring store owners to manually create a token during installation? This is where published apps come in. When an app is published, any site on AmeriCommerce will be able to install the application via an OAuth2 Permission Grant. This means AmeriCommerce users will be able to give the application permission by clicking an Allow button during the OAuth flow, rather than manually creating a token for their store.

Published App Rate Limits: An additional benefit of a published app is that they get put into a separate rate limit bucket of 50 calls per 10 second window. So, regardless of the site's normal API rate limit based on plan level, a published app doesn't hit that rate limit; instead all published apps for a site share a 50/10 rate limit separately from the normal API rate limit.

In order to publish an app, developers will need to: 

1. Obtain a Sandbox Site - This is where the app settings will be configured and published.
2. Develop the integration - before publishing privileges have been granted, developers can create a custom app token and secrete to use for testing. These credentials will only work for the sandbox site itself.
3. Request App Publishing Privileges

Step 1: Obtain a Sandbox Site

Developers wishing to create a published app will first need to obtain a sandbox site. To obtain a sandbox, submit an App Developer Sandbox Request here. 

Step 2: Develop Your Integration

Once a sandbox site is obtained, work can begin on the integration. To get started:

1. login to the sandbox
2. create an OAuth2 app in Tools > App and Addons > Apps and Integrations
3. Use the App Secret and App ID** to Authenticate your App during testing

If they need basic support for the API, the triage owner (or other designated agent) will assist with answering the questions in the ticket. More technical or in-depth support may require the purchase of developer support hours. Once it is indicated that the app is ready to be published, the questionnaire will be sent via the ticket.

** Once you publish the app, an installation ID will be generated. Update your code such that the client_id parameter uses the installation ID in place of the App ID (which will only work on your sandbox site). Otherwise, other sites will not be able to grant access to your application. 

Step 3: Request App Publishing Privileges

 In order to publish an application your sandbox site must have app publishing privileges enabled. Before app publishing privileges are enabled on your sandbox, your app must first be reviewed by a software developer. A software developer will provide additional information and communicate with you about the review process in the ticket generated from the App Developer Sandbox Request form submission, so be sure check your email or login to your support account for ticket updates.

Step 4: Publish Your App

Once App Publishing is enabled on your sandbox, you will be able to publish apps you created in Tools > Apps and Addons > Apps and Integrations. To publish an app,

1. login to your sandbox site
2. navigate to Tools > Apps and Addons > Apps and Integrations
3. Create a new OAuth2 App, follow screen prompts, and save
4. Edit the app you just created and check Make Application Public. 
5. Configure publishing settings as required
6. Save - Once you save an installation ID will be generated.
7. Update your code to use the new apps App Secret and replace the App ID passed to client_id parameter with the newly generated Installation ID (near bottom of app edit screen).

If properly configured, any site on AmeriCommerce will be able to grant access when using your application.

Note: Publishing does not cause your app to be listed in Tools > Apps & Addons (like Facebook Login, for example).

Troubleshooting

Here's some common things to check when your published app is failing during the OAuth2 flow:

• For published apps, the value of the client_id param should be the Installation ID (long string of numbers and letters) generated on the Application Details screen (as opposed to the App ID, which is an integer).
• The the value of the redirect_uri param should match a URL in Allowed callback URLS in the app settings. This is case sensitive, so make sure they match exactly