Building a Jumpseller App

A Jumpseller App can be anything from a simple application that injects javascript code in the online store, like a chat widget or newsletter popup, to a full fledged application that synchronizes online orders and inventory with an external software, for example.

You are free to choose any language or web framework to develop your Jumpseller App, as well as where you want to host it. Jumpseller Apps use the Jumpseller OAuth2 endpoint for authentication and the Jumpseller API to interact with the online store. Example apps that can be developed:

Example apps that can be developed:

• Facebook Pixel javascript code used for tracking your site’s events loaded in the online store HTML

• Getting products data and exporting them as a feed for Google Commerce

Register your App

App registration and management happens in the Jumpseller Partners portal (https://affiliate.jumpseller.com). From the Partners portal you manage every app you own across all your stores in one place.

The My Apps list

Go to https://affiliate.jumpseller.com and log in with your Jumpseller account.

Click Apps in the top navigation to open My Apps (affiliate.jumpseller.com/apps).

A green + Create App button sits at the top-right of this page — click it to start building a new app.

Creating an app

Clicking + Create App opens the Create App form. It’s a single form, not a step-by-step wizard: a left-hand sidebar lets you switch between sections — Cover, URLs, About, Screenshots, Features, Videos, Settings. After creating the app, you will also have access to the new + Pricing configuration screen inside the edit form.

Fields marked with * are required.

Cover

• App code - unique identifier used in URLs. Lowercase letters, numbers and hyphens only. Leave empty to generate it from the title.
• Logo - square image (PNG or JPG), at least 512×512.
• Title
• Author - name of the company or the person that is developing the app.
• Author email
• Store - dropdown to pick one of your own/test stores to associate the app with while you build it. App creation is no longer tied to being inside a specific store’s admin, but you still attach it to a store up front.
• Category - dropdown, e.g. Others, Design & Widgets, Chat & Messaging.
• Version - free text field.
• Short description - one line shown under the app name. Localized, with Default / ES (Spanish) / PT (Portuguese) tabs above the input.
• Banner color - color swatch that appears on the background of featured apps.
• Banner image - image that appears on the background of featured apps.

URLs

• App URL - URL to open the application. This is the absolute (root) URL of your web App. Read section The root route for more information.
• Redirect URL - where the user is redirected after authentication, where the app will save the access token. This URL uses the callback route.
• Product redirect URL - see Product Redirect URL below.
• Create Invoice URL - see Create Invoice URL below.
• Uninstall URL - see Uninstall URL below.

About

• App description* - detailed description shown on your listing. Take as much space as you want. Localized (Default/ES/PT tabs), multi-line textarea.

There are now two different description fields — don’t confuse them:

• Short description (Cover tab) — one line shown under the app name.
• App description (About tab) — long-form, shown on the listing.

Screenshots

• Screenshots* - upload one or more images shown on your app listing. Each uploaded screenshot has a trash/delete icon; use the Upload Image tile to add more.

Features

• What can you do - each item becomes a bullet on your listing. Use + Add item to add rows.
• How it works - each item becomes a bullet on your listing. Same structure and localization as above.
• Category by goal - free text, e.g. Others.
• Category by goal key - free text, the slug form of the above, e.g. others.

Videos

• Video URL - link to a video showcasing your app (YouTube, Vimeo, etc.), localized per language (Default/ES/PT tabs).

Pricing

In this tab, you will be able to create multiple pricing plans for your application. We support two different systems regarding pricing:

• Fixed fee - A fixed fee charged in each billing cycle
• Order fee - If your app is registered as a Payment Method, you can also leverage our Order fee. This payment system will charge a % of all orders that have the application set as the payment method. You can define the minimum number of orders that are needed to charge a merchant, and the maximum charge per month (in USD).
• Plan Update URL - see Plan Update URL below.

Settings

• Contact email - support/contact email for the app.
• Contact phone - support/contact phone number for the app.
• Support page - URL of your support page.
• Website - URL of your app or company website.

After the app is created, this tab also shows:

• Published - the app’s publish status.
• Maintenance mode - toggle that disables the app for merchants.
• Store access - input to grant access to specific stores.
• Publish button - requests a review from the Jumpseller team so your app can be made available to other merchants. See Approval & Publishing.

Once created, your app can be installed on the store you associated it with in the Cover tab, to test it. When you’re ready to make it available to other merchants, see Approval & Publishing.

Understanding Scopes

Scopes are required settings to specify which part of the Merchant’s store data your App would like to access. If your App wants to request products data, for instance, you must have the read_products scope, otherwise you are not going to be able to get this data from the Jumpseller API. Remember to only request just the necessary scopes for your App, since merchants who install it will need to authorize access to the different scopes, and may give up on installing it if you request access to unrelated resources.

Check how to Request Authorization for setting the scopes.

Authentication

By now you have concluded the first step of registering your new App. However, for now it is just an eggshell since the web App does not fully exist yet. Keep reading this article to understand the basic concepts that will allow you to build your first Jumpseller App.

Basic Concepts

The first important concept to understand is OAuth 2. When you registered your new App in Jumpseller Admin in the previous section of this article, you were in fact creating a new OAuth 2 application. This means your App needs to implement the Authorization Flow of OAuth 2.

Go to the OAuth 2 page to better understand how it works.

The OAuth 2 Credentials

In the Jumpseller Partners portal, open Apps, find your app in the My Apps list and click the desired app in the listing.

You will be redirected to the app’s overview page, where you can see install stats and a Credentials panel with the data you entered when you created your App (Code, Store) as well as two auto-generated, read-only fields: App Id and App Secret.

Copy and save your App’s id and secret somewhere secure. You are going to need it later for the OAuth 2 flow.

DO NOT share your app’s client id and client secret with anyone.

Additional App Edit Fields

These fields now live under the URLs tab of the Create/Edit App form (see Creating an app above), rather than as standalone advanced fields on a separate store-level edit page:

Product Redirect URL

• Allows you to enter the app directly from a product (e.g., from a product page).
• The developer must configure the URL, and Jumpseller will send the product_id as a parameter in the request.

Multi Product Select

• When enabled, merchants can select multiple products from the product list before opening your app.
• Instead of sending a product_id, Jumpseller will send a cache_key representing the selection.

You can then retrieve the selected products by making a GET API call to Jumpseller:

https://api.jumpseller.com/v1/products/selected/#{cache_key}.json

Create Invoice URL

• For invoicing apps, this field lets you add a URL that can be called directly from the order page to create an invoice.
• More details can be found here: Invoicing Integrations.

Uninstall URL

• Allows your app to receive a request when a merchant uninstalls it from their store.
• Use this endpoint to perform cleanup tasks, such as removing or anonymizing store-related data and revoking any active credentials in your system.

When an app is uninstalled, Jumpseller sends a POST request to your configured uninstall URL using this pattern:

https://your-app.com/uninstall/{store_id}

Example request:

POST /uninstall/12345 HTTP/1.1
Content-Type: application/json
Jumpseller-Store-Code: my-store
Jumpseller-Event: app_uninstalled
Jumpseller-Hmac-Sha256: <base64_hmac_signature>
Jumpseller-Triggered-At: 2026-03-30 14:10:22.381 UTC

{
  "app_code": "my_app",
  "app_name": "My App",
  "store_id": 12345,
  "uninstalled_at": "2026-03-30T14:10:22Z"
}

The Jumpseller-Hmac-Sha256 header is generated from the raw request body using the store hooks token. You can validate it with the same approach described in Webhook Notifications.

Plan Update URL

Lets your app know when a merchant upgrades or downgrades their subscription plan for your app, so you can keep your own records in sync. Jumpseller sends a POST request to your configured Plan Update URL whenever a merchant subscribes to, upgrades, or downgrades a plan. The payload follows this schema:

{
  "app_code": "example-app",
  "app_name": "Example App",
  "store_id": 123,
  "old_plan": "example_basic",
  "new_plan": "example_pro",
  "changed_at": "2026-08-17T12:34:56Z"
}

For a new subscription (i.e., the merchant did not previously have a plan for your app), the same notification is sent with old_plan empty. The plan codes are generated and displayed after their creation.

Mandatory Routes

When developing your Jumpseller App, you are free to decide what kind of application you are going to build and which routes it will have.

But to work with Jumpseller it is mandatory to have two of them: The root route and the callback route.

Let’s get to know them better!

The Root route

The Root route is the entry point of the App: it acts as the controller that will render the page that will be shown within an iFrame when the user opens the App in the Jumpseller store Admin Panel.

Every Jumpseller App requires some input from the Merchant, before the user is able to use it. The page rendered by this route will require the inputs needed for the initial App setup.

Our Olark App is a good example of this. In order to have the Olark’s online chat in your store, you must sign up on their website, copy and paste your Olark ID on the App form and save it.

So your Root route is responsible for presenting this kind of required settings input page for the Merchant.

Make sure your App uses an SSL certificate. Non-HTTPs URLs cannot be loaded.

The Callback route

As you already know,Jumpseller Apps use the Authorization Flow of OAuth 2. A redirect from the Jumpseller OAuth 2 service to your callback route is part of this flow.

The callback route is where you are going to be able to get your access token from the OAuth 2 service and use it to read and write to the online store API.

Visit the OAuth 2 page to better understand about the callback route and visit the API page to learn how to use the OAuth 2’s access token when you want to access the online store API.

Tutorial: creating a simple Jumpseller app

As mentioned before, you are free to choose which programming languages or web frameworks you want to use to build your App.

For now, let’s just create a really simple basic example to help reinforce what you’ve learned so far.

If you use Ruby, this Sinatra’s App Skeleton is available for you to use.

Getting started

In your terminal, create a new directory wherever you want and cd it:

> mkdir my-new-app
> cd my-new-app

After, create a simple index.html file with a Hello, World! text:

> echo 'Hello, World!' > index.html

Now you can run a really simple web application with the Python SimpleHTTPServer class:

> python -m SimpleHTTPServer 8000

You should have python installed on your computer

This example uses the port 8000 but you can change it if you want.

Open your favorite browser and visit the address http://localhost:8000. This simple web server is already running and you can see the Hello, World! message on your browser:

Testing your Jumpseller App

You have your web server up and running in your local machine. Now it is time for testing it!

As you remember, when you registered your App in the Jumpseller Admin, you had to inform a callback and an application URL.

Follow the same steps for editing your App as you did in OAuth 2 Credentials and change your application URL to http://localhost:8000:

Save it, go to the Installed tab, find your App and click on it.

You’ll realize that you still can’t see anything. That is because Jumpseller Admin can’t access the web server in your local machine, at least not yet, while you use the localhost.

Let’s fix that!

Tunneling your Web Application

A simple solution for making your local web application publicly available is tunneling it. There are lots of solutions for tunneling, but we will use ngrok in this tutorial. You can consult ngrok’s Quick Start Guide for instructions on how to install and configure it.

Once you have it installed, let’s execute it:

> ngrok http 8000

As you can see above, ngrok creates a public URL and manages the tunneling for your local web server, i.e., every request this public URL receives, ngrok handles and makes it reach your local web server.

Access this public URL on your browser and you will see the same as in http://localhost:8000, the Hello, World! message.

Updating again your App URL

Now you can once again edit your App in Jumpseller Admin and change the Application URL field to:

Save it and try to access your App again clicking on it within the Installed tab on the Apps section. The “Hello, World!” message is visible, i.e., the Jumpseller App was able to load your local web application inside its iframe.

Next steps

Congratulations! Your Jumpseller App is installed and loading your web application. Once you have it done, you can deploy it for any hosting service (or host it yourself if you’re feeling daring!) and change the Application URL (and Callback URL) to your production-ready URL.

You can now improve your Jumpseller App with the Jumpseller API but for this you’ll need to understand the authorization flow of OAuth 2 and how to get your access token for API requests.

UI Design Guidelines

To ensure consistency and a better user experience across all Jumpseller Apps, please read and follow the official UI Design Guidelines Presentation:

These guidelines include recommendations on:

• Layout and navigation
• Typography and color usage
• Buttons and form elements

Approval & Publishing

Before your app can be made public, our team needs to review it. Once you’ve created your app, thouroughly tested it, and are ready to have it published on our app gallery go to the Settings tab and click Publish to request a review.

Our team will review your app and contact you regarding approval and publishing.