+813-444-3589+44 118 328 3220+49-231-976765-0 | Contact us

FlickRocket REST API

Welcome to FlickRocket’s REST API documentation.

Sign up and set up shop for development

To start development, you need to sign up to FlickRocket and set up your own shop. In most cases the BASIC account provides everything that is needed for app development.

Learn more about the different plans here and sign up here.

Once your development process is complete you can choose to use the app for yourself or offer it in the FlickRocket App Store.

Once you have your shop created, the next step is to create your app.

FlickRocket App Basics

Flickrocket's REST API implements JSON to manipulate each API resource in isolation, providing a RESTful interface. All API usage happens through FlickRocket apps either developed by shop owners or obtained via 3rd parties.

Any FlickRocket app that you create will use the FlickRocket API to access another shop's data. When a shop installs your app, all they're really doing is giving your app permission to access their shop's data through the API.

To properly install your app, you will need to provide your app with an authentication mechanism. Authentication mechanisms allow your app to interact with other FlickRocket stores. Flickrocket uses OAuth 2.0 as its primary authentication mechanism but many of our developers and FlickRocket advocates also have authentication mechanisms (typically referred to as gems, connectors or adapters) available through software development kits (SDK). These SDKs are available in several programming languages. Take a look at our Libraries to see what is available in your preferred programming language. You will need to authenticate your app to install it in your development store.

Note: When developing your app, please respect the API calls limit. The API call limit operates using a "leaky bucket" algorithm as a controller. You can read more about how this will affect your app here.

Checking the requests and responses

Use Fiddler for Windows, or Charles for OS X to debug your HTTP requests and responses.

Generate API credentials

In the FlickRocket admin interface select “Products / Manage Products” and click on “New Product”. Select “App” from the “Product type” dropdown and fill in all the information about your new app.

To receive your API credentials, click the “Generate” button in the “API credentials” section.

OAuth Authentication

Your app cannot access FlickRocket data without authenticating first. It must get permission from a user before gaining access to any of the resources in the REST API. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification).

Terminology

Before getting into the nitty-gritty of the authorization process, let’s go over some of the terms that we’ll be using for the rest of the guide.

  • Client - Any application that would like access to a shop’s data. A user (usually the shop’s owner) must grant permission before the client can access any data.
  • API - FlickRocket’s REST API. This is the place where the client can view and modify a shop’s data.
  • User - A Flickrocket account holder, usually a shop owner. This is the person giving permission to a client to access their shop’s data through the REST API.

Step 1: Get the client’s credentials

You will need to retrieve an Client ID and Shared Secret as the client uses them to identify itself during the authorization process. Also you'll need to specify one or more valid redirect_uris.

To do this, open Products/Manage Products and locate the “API Credentials” section

app credentials

Once you have created the credentials, the new app will also appear in the admin interface under "Extensions / Manage Apps".

Step 2: Asking for permission

The first step of the process is to get authorization from the user. This is done by displaying a prompt provided by Flickrocket:

oauth login 1
oauth login 2

To show the prompt, redirect the user to this URL:

https://admin.flickrocket.com/oauth2/auth?client_id={client_id}&scope={scopes}&access_type=offline&redirect_uri={redirect_uri}

With these substitutions made:

  • {client_id} - substitute this with the app's client id.
  • {scopes} - substitute this with a comma-separated list of scopes. For example, to read/write orders and read/write customers use scope=orders,customers.
  • {redirect_uri} - (Required) substitute this with the URL where you want to redirect the users after they authorize the client. The complete URL specified here must be identical to one of the Application Redirect URLs. Note: in older applications, this parameter was optional, and redirected to the Application Callback URL when no other value was specified.

For example:

https://admin.flickrocket.com/oauth2/auth?client_id=FRWebApp&scope=products&access_type=offline&redirect_uri=api_tester.html

Step 3: Confirming installation

During the installation will the user will be redirected to the client server as specified above. One of the parameters passed in the confirmation redirect is the Authorization Code (the other parameters will be covered later in the guide).

https://example.org/some/redirect/uri?code={refresh_token}&companyid={company_id}

After this, the refresh_token can be exchanged once for an access_token, which expires after some time. The exchange is made as follows.

POST https://admin.flickrocket.com/token/grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}

The server will respond with the following JSON containing an access_token and related information:

{
expires:"Thu, 21 Apr 2016 14:00:22 GMT",
issued:"Thu, 21 Apr 2016 13:30:22 GMT",
access_token:"gjRiyX1zl4JsmOSm_Hi3YMZo1vonyCylDDMBvW7H9iNfxCvFUdZLedxwCzGle7PSlmgFlSr-fHYlzybXaPsiuFZ0yKblYNuyvnSH-lDXPEeezfvGxijtdbT_H54HxE6aiESGmPGE0DgBN6lCxQQ7H7bsbez2OntawK8AboZqw3wKqbectPvqzV569hlIfuwn3uMAS46qLxuzTFn-0PVLQ5szd1PfLpRZmeH0pHcxEV6qVcoxIedup0tC6cY4kJnFDeqqKC3x3F5wrvH2gPPxkGal1ZfcH9MK3CYxEUETt6O3AaxjFBCqME2Y0BykPNFXikxL3vF7_O3Fq3AMAy_pcHIdqrbS8wGaGKdPEgIUTOpLaHvccsY4LluYR0TvyQf458ae0qxQyS4gIWPOIbfU3r4hMAwP1O9zBC5R_cHplL1QpfpIaKfu3zOK1AibRVES8VBOtvMRsF5a4LYXq60g6oEzmIg",
access_type:"offline",
as:client_id:"FRWebApp",
expires_in:1799,
refresh_token:"686ef3e7410b41858237daeaf4dc550b",
scope:"products,orders,customers,themes,files",
token_type:"bearer",
userName:"This email address is being protected from spambots. You need JavaScript enabled to view it."
}

It is important that the new refresh_token from the JSON above is always stored permanetly, as this is the only way to retrieve a new access_token, which is then used for authorization when calling the REST interface.

Important: If the refresh_token is lost, the only way to get access again is by manually removing permissions in the admin interface and start over again.

Step 4: Making authenticated requests

After the application obtains an access token, it can use the token to make calls to the FlickRocket REST API on behalf of a given user account or service account. To do this, you must include the access token in a request to the API by including either an access_token query parameter or an Authorization: Bearer HTTP header. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In some cases you can use a client library to set up your calls to FlickRocket APIs.

Validating an access_token

You can validate and retrieve information for an access_token with the following get:

GET http://admin.flickrocket.com/api/tokeninfo?access_token={access_token}

If the access_token is valid, information as follows is returned.

{
"issued_to": "SomeWebApp",
"user_id": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"scope": "products,orders,customers",
"expires_in": "1738",
"access_type": "offline"
}

The expires_in time is specified in seconds. If the access_token is not valid, an error is returned. Possible error values are: expired, access_token required, invalid access_token.

Scopes

Part of the authorization process requires specifying which parts of a shop’s data the client would like access to (see the “Getting permission” part of this guide). A client can ask for any of the following scopes:

products The application can get, modifiy, create and delete products and categories.
customers The application can get, modifiy, create and delete customers.
orders The application can get, modifiy and create orders.
themes The application can get, modifiy, create and delete themes.
files The application can get and create content files.
companies The application can get, modifiy, create and delete company data (own and associated)
statistics The application can get company/shop statistics.

 

Objects

Product Create and manage the products in the shop
Order Create and manage shop orders
Customer Create and manage shop customers
CustomerAddress Manage customer adresses
ThemeSetting Manage setting related to a theme (e.g. domain)
Category Create and manage product categories