OpenChannel API

Marketplace API

The Marketplace API is a RESTful API that allows your server-side code to integrate with OpenChannel to query objects and perform operations for your marketplace on behalf of users and developers. The Marketplace API is divided into distinct sections:

  • The Developer API is useful when building a portal for developers and partners to submit and manage their apps
  • The User API is useful when building an app store for end users to install and launch apps
  • The Payment API is useful when building payments into your marketplace

When performing requests, GET request parameters are always sent with URL query parameters. POST request parameters can be sent as either URL parameters or by specifying the contentType as ‘application/json’ and providing JSON in the request body.

  • Sending a request as ‘application/json’ content-type requires parameters to be placed in a JSON object in the POST body
  • Sending a request as ‘application/x-www-form-urlencoded’ content-type requires parameters to be placed as a query string

Responses from the API are always formatted using JSON. Within this documentation there are examples of how to perform common functions. You can make API calls directly from your Management Dashboard by clicking the API button in the top left navigation menu.

Marketplace API Endpoint

https://market.openchannel.io/v2

Authentication

Authenticate your account when making calls to the Marketplace API using basic authentication and providing your marketplaceId and secret as the username and password. You can get your marketplaceId and secret by logging into the Management Dashboard and clicking on Settings -> API Credentials.

credentials

All requests must be made over HTTPS.
Any requests made over HTTP will fail.
Keep your secret confidential.
Avoid storing it in plain text – especially within source code or other publicly accessible areas.

Example Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/apps

Errors

The Marketplace API returns HTTP response codes to indicate the success or failure of an API request.

Error codes in the 2xx range will indicate success
Error codes in the 4xx range indicate an error with your API request.
Error codes in the 5xx range indicate an issue with the OpenChannel API.

 

Depending on the type of error, the ‘field’ may not be included within the Error Message which indicates that the error is general and not field specific. On the other hand, error messages returned with field values are designed to be passed directly to the user. In some cases, you may encounter errors with codes ranging from 500 – 599 which indicate a request processing error within our servers. These types of errors are rare and a notification is sent that will automatically alert OpenChannel to the issue.

Error with Fields

{
  "code": 400,
  "errors":
  [
    {
      "field": "name",
      "message": "This field is required."
    }
 ]
}

Error without Fields

{
     "code": 412,
     "errors":
     [
         {
            "message": "The credit card has been declined."
         }
     ]
}

User and Developer Ids

The API revolves around actions performed on behalf of users and developers. By utilizing this perspective it allows OpenChannel to offer an API that is quick and simple to integrate. A userId always refers to the unique id that identifies the end users consuming the apps while a developerId always refers to the unique id that identifies the authors creating the apps.

You don’t need to explicitly create users or developers on the OpenChannel platform. When you provide a new userId as part of an action, a user record is created automatically if a user with that id doesn’t already exist – the same goes for developers.

For security reasons, never reuse or hash userIds or developerIds.
Providing unique ids to the Marketplace API is important for the proper operation of your marketplace.

Query Document

In the Marketplace API, several methods are provided for retrieving results such as apps, reviews and payments using the query document. The query document is a JSON based object used to specify and limit the results returned by the API.

 URL’s must be properly encoded! Un-encoded characters like { ” } [ ] : may result in the return of a 400 error.

Query All

To return all results for an API method, don’t specify a query parameter. Not specifying a query parameter to the API method is equivalent to specifying an empty query document {}.

Sample Query All

{}

Returns all results.

Equality Condition

To return specific results where a field equals a certain value, use an equality condition. An equality condition can be specified by using the query document syntax { <field>: <value> } to select all records that contain the <field> with the specified <value>.

Sample Equality Query

{
  "developer": "123",
  "name": "my first app"
}

Returns results where the field ‘developerId’ = ‘123’ and the field ‘name’ = ‘my first app’.

Operators

To return specific results where a field equals at least one of many values, use the $in query operator. An $in query operator can be specified by using the query document syntax { <field>: {“$in”: [ <value1> , <value2> ]}} to select all results that contain the <field> with either <value1> or <value2>.

Although you can express this query using the $or operator, use the $in operator rather than the $or operator when performing equality checks on the same field.

$eq (optional)
Matches values that are equal to a specified value.
$gt (optional)
Matches values that are greater to a specified value.
$gte (optional)
Matches values that are greater than or equal to a specified value.
$lt (optional)
Matches values that are less than a specified value.
$lte (optional)
Matches values that are less than or equal to a specified value.
$ne (optional)
Matches all values that are not equal to a specified value.
$in (optional)
Matches any of the values specified in an array.
$nin (optional)
Matches none of the values specified in an array.

Sample $in Query

{
  "name": 
  {
    "$in":
    [
      "my first app",
      "my second app",
      "my third app"
    ]
  }
}

Returns results where the field ‘name’ is equal to ‘my first app’, ‘my second app’ or ‘my third app’.

Sample $ne Query

{
  "name": 
  {
    "$ne": "my first app"
  }
}

Returns results where the field ‘name’ is not equal to ‘my first app’.

Sample $gt Query

{
  "rating": 
  {
    "$gt": 200
  }
}

Returns results where the integer field ‘rating’ is is greater than 200.

Dot Notation

Use the dot notation to match by specific fields in an embedded document. Equality matches for specific fields in an embedded document will select results from the API method where the embedded document contains the specified fields with the specified values. The embedded document can contain additional fields.

Lets consider the following app:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "model": 
  {
    "type": "single",
    "price": 499,
    "license": "single",
    "trial": 0,
    "currency": "USD"
  },
  ...
}

The ‘model.price’ field can be used in queries by using the dot notation.

Sample Document Query

{
  "model.price": {"$gte": 499}
}

Returns results where the field ‘price’ (within the model object) is greater than or equal to 499.

AND and OR

A $and compound query can specify conditions for more than one field in the API’s method. Implicitly, a logical AND conjunction connects the clauses of a compound query so that the query selects the results that match all the conditions.

Using the $or operator, you can specify a compound query that joins each clause with a logical OR conjunction so that the query selects the results from the API method that match at least one condition.

Let’s consider the following app:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "model": 
  {
    "type": "single",
    "price": 499,
    "license": "single",
    "trial": 0,
    "currency": "USD"
  },
  "customData": 
  { 
    "categories":
    [
      "movies", 
      "books",
      "music"
     [ 
  } 
}

The  $or operator can help you query results where the field ‘developerId’ = ‘123’ OR the field ‘name’ = ‘my first app’.

Sample $and Query

{
  "$and" : 
  [
    {
      "developerId": "123"
    },
    {
      "name": "my first app"
    }
  ]
}

Returns results where the field ‘developerId’ = ‘123’ and the field ‘name’ = ‘my first app’.

Sample $or Query

{
  "$or" : 
  [
    {
      "developerId": "123"
    },
    {
      "name": "my first app"
    }
  ] 
}

Returns results where the field ‘developerId’ = ‘123’ or the field ‘name’ = ‘my first app’.

Arrays

When the field holds an array, you can query for an exact array match or for specific values in the array. If the array holds embedded documents, you can query for specific fields in the embedded documents using dot notation.

If you specify multiple conditions using the $elemMatch operator, the array must contain at least one element that satisfies all the conditions.

If you specify multiple conditions without using the $elemMatch operator, then some combination of the array elements, not necessarily a single element, must satisfy all the conditions; i.e. different elements in the array can satisfy different parts of the conditions.

Let’s consider the following app:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "model": 
  {
    "type": "single",
    "price": 499,
    "license": "single",
    "trial": 0,
    "currency": "USD"
  },
  "customData": 
  { 
    "categories":
    [
      "movies", 
      "books",
      "music"
     [ 
  } 
}

The ‘customData.categories’ field can be used in queries by using the dot notation.

Sample Array Query

{
  "customData.categories": "books"
}

Returns results where the array ‘categories’ (within the customData object) contains at least one value of “books”.

Sample $elemMatch Query

{
  "customData.categories":
  {
    "$elemMatch":
    {
      "$ne": "music",
      "$ne": "books"
    }
  }
}

Returns results where the array ‘categories’ (within the customData object) does not contain “books” and does not contain “music”.

Sort Document

Sort parameters are useful for sorting the result of an API call. A sort document is a JSON object that contains a field and a value of 1 (ascending) or -1 (descending).

Use the dot notation to sort by specific fields in an embedded document. 

Lets consider the following app:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "model": 
  {
    "type": "single",
    "price": 499,
    "license": "single",
    "trial": 0,
    "currency": "USD"
  },
  ...
}

The ‘model.price’ field can be used in sorting results by using the dot notation.

 URL’s must be properly encoded! Unencoded characters like { ” } [ ] : may result in the return of a 400 error.

Sample Sort

{
  "name": 1,
  "statistics.views.total": -1
}

Returns results sorted first by name in ascending order then by the total number of views in descending order.

Pagination

API methods that accept pageNumber and limit parameters have pagination built into the response. There are four attributes returned as part of the result set that help with paging:

Attributes

pages (optional)
integer
The total number of pages for this result set
count (optional)
integer
The total number of results
pageNumber (optional)
integer
The current page number
list (optional)
array
The array of results for this page. The absolute maximum limit to the number of objects returned at one time is 1000.

With paging variables, it is easy to construct functionality to move to next and previous pages as well as skipping to a specific page.

Sample Paged Response

{
  "pages": 4,
  "count": 457
  "pageNumber": 1,
  "list":
  [
    {...},
    {...},
    {...},
 ]
}

 

App Restrictions

Apps can be restricted by setting the allow or restrict fields. Allow and restrict fields match against fields on a user’s customData field in order to allow or restrict the viewing and owning of apps.

Lets consider the following three users:

{
  "userId":"12",
  "customData":{"country":"Canada","gender":"Male"}
},
{
  "userId":"13",
  "customData":{"country":"Mexico","gender":"Male"}
},
{
  "userId":"14",
  "customData":{"country":"France","gender":"Female"}
}

Apps are able to setup restrictions that set criteria based on the user’s customData object.

Sample Whitelist

"allow": 
{
  "view": 
  { 
    "country":
    [
      "Canada",
      "Mexico"
    ]
  },
  "own":
  {
    "country": "Canada"
  }
}

An app with this restriction can only be viewed by users whose country is Canada or Mexico but can only be owned by a user whose country is Canada.

Sample Blacklist

"restrict": 
{
  "view": {},
  "own":
  {
    "gender": "Male"
  }
}

An app with this restriction can be viewed by anyone but cannot be owned by users whose gender is Male.

Webhooks

Webhooks allow you to be notified programatically about events that occur within your marketplace. Each event is a JSON representation of an event that has occurred and can contain different content based on the event type. To configure your webhooks, log into the Management Dashboard and click Settings -> Webhooks.

Webhook Event Types

Event Type Description
app.submitted Occurs when an app is submitted for approval by a developer.
app.approved Occurs when an app is approved by a marketplace administrator.
app.suspended Occurs when an app is suspended by a marketplace administrator or the app developer.
app.unsuspended Occurs when an app is un-suspended by a marketplace administrator or the app developer.
app.rejected Occurs when an app is rejected by a marketplace administrator.
app.inReview Occurs when an app is placed in-review by a marketplace administrator.
app.installed Occurs when an app is purchased or installed by a user.
app.uninstalled Occurs when an app is uninstalled by a user.
review.created Occurs when a review is created for an app by a user.
review.updated Occurs when a review is updated by the user.
review.approved Occurs when a review is approved by a marketplace administrator
review.spam Occurs when a review is marked as spam by a marketplace administrator
review.removed Occurs when a review is removed by a marketplace administrator or a user.
user.created Occurs when a new user has signed up.
user.updated Occurs when a user is updated.
user.removed Occurs when a user is removed.
user.invalidPaymentDetails Occurs when a user’s payment details are no longer valid.
user.paymentDetailsRequired Occurs when a user’s payment details are removed and as a result, a purchase fails to execute.
developer.created Occurs when a new developer signs up.
developer.updated Occurs when a developer is updated.
developer.removed Occurs when a developer is removed.
developer.paymentDetailsRequired Occurs when a developer’s payment account details are removed and as a result, a purchase fails to execute.
permission.added Occurs when a user grants permission for an app.
permission.removed Occurs when a user revokes permission for an app.
payment.complete Occurs when a user’s payment for an app is successful.
payment.refunded Occurs when a user’s payment for an app is refunded.
payment.required Occurs a payment is required in order to renew a subscription.
ownership.expired Occurs when a subscription goes unpaid an expires.

Any event that you receive can be verified by ignoring the message payload and retrieving the event using the GET /events/{eventId} API method. Verifying events is important for security and ensuring that your endpoint URL isn’t being exploited by an unauthorized third party.

Parameters

eventId
string
The id of the event that you would like to retrieve

Returns

Event
The event associated with this eventId.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The event was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/event/{eventId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/event/{eventId}

Sample Success Response

{ 
  "eventId": "5463cee5e4b042e3e26f1e41",
  "createdDate": 1427466717262,
  "message": "An app draft has been submitted by a developer.",
  "eventType": "app.submitted",
  "marketplaceId": "5565322ae4b0a70b13a4563b",
  "app": { 
    "appId": "5565322ae4b0a70b13a4563b", 
    "customData": 
    { 
      "summary": "Automatically set on/off timers...", 
      "description": "HPWHs use electricity to move heat...", 
      "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
      "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
      "images": 
      [ 
        "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
        "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
      ], 
      "categories": 
      [ 
        "Hot Water", 
        "Smart Pump" 
      ], 
      "author": "Andrea" 
    }, 
    "lastUpdated": 1432695338702, 
    "version": 1, 
    "name": "Hot Water Assist",
    "developerId": "30", 
    "model": 
    [ 
      { 
        "type": "free", 
        "price": 0, 
        "trial": 0, 
        "license": "single", 
        "modelId": "1", 
        "currency": "USD" 
      } 
    ], 
    "access": 
    [
      "billing - readonly"
    ], 
    "restrict": 
    {
      "own":
      {
        "country":["Canada","Mexico"]
      },
      "view":
      {
        "country":["Canada","Mexico"]
      }
    }, 
    "allow": {}, 
    "submittedDate": 1432695339005, 
    "created": 1432695338702, 
    "attributes": {}, 
    "rating": 400, 
    "parent":
    {
      "status": 
      { 
        "value": "approved", 
        "lastUpdated": 1432696823474, 
        "modifiedBy": "administrator", 
        "reason": "" 
      } 
    },
    "status": 
    { 
      "value": "approved", 
      "lastUpdated": 1432696823474, 
      "modifiedBy": "administrator", 
      "reason": "" 
    }, 
    "isLive": true
  }
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This event was not found"
    }
 ]
}

Apps

Each app is a JSON representation of an application submitted by a developer. The structure of an app can be customized using the customData object. When creating or updating an app, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your app. The OpenChannel platform will automatically detect and handle your custom app structure.

Create App

An app version can be created by a developer but cannot be viewed by a marketplace administrator until the developer publishes the app. An app can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

developerId
string
The unique id of the developer that is adding this app
name
string
The name of the app
type (optional)
string
The name of the app type for this app
model (optional)
array(Model)
A JSON array representing the pricing models for this app
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
restrict (optional)
Restriction
JSON object to restrict users from owning or viewing this app
allow (optional)
Restriction
JSON object to restrict users from owning or viewing this app
access (optional)
array(string)
JSON array of data access requirements

Returns

App Version
Returns the newly created app.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Already Exists
An app with this name already exists

 

An app version will not be visible to administrators right away.
An app version must be published before it can be visible on the Management Dashboard. App versions can only be queried from the GET /apps/versions API.

Paid Apps

Apps created without setting a Model will default to a free model and require no payment to be owned. To create apps that require payment, add a Model to the app with a type of either ‘single’ or ‘recurring’. A user purchasing an app with a ‘single’ model will need to pay a one-time fee in order to own the app. A user purchasing an app with a ‘recurring’ model will need to pay a monthly or annual fee to maintain their subscription to the app.

An app can have many models that a user can choose from. Each model has a distinct modelId that appears in the ownership record and allows the app to provide the appropriate level of service for each model. A ‘single’ or ‘recurring’ model can also have a trial period that gives the user a certain number of days to try the app before payment is required.

App Licensing

Apps can be purchased and owned for individual users or entire organizations. There are two types of licenses: ‘single’ and ‘group’ – if no license is specified then ‘single’ is set by default. The single user license requires each user to purchase and own their apps while the group license allows a user to purchase and own an app for an entire organization.

The groupId on the User object determines the users that are part of the same organization. If an app has a group license and a user purchases that app then every user with the same groupId of that user also gains ownership of that app.

API Access

Apps can request access to specific data within the API by enumerating the data requirements within the access array. The access array data will be available to users (when asking for access permission) and as part of the API key request.

A user must give permission before an app will be granted the API credentials required for access.

For an app to require access, add access requirements to the access field. You can provide anything within the JSON array like strings, numbers or JSON objects. When an app requests access for a user, the OpenChannel platform will provide this list to you as part of the API credential request.

Request URL

POST https://market.openchannel.io/v2/apps

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'name':'Hot Water Assist'," \
        "'developerId':'30'," \
        "'customData':" \
        "{" \
          "'summary': 'Automatically set on/off timers...'," \
          "'description': 'HPWHs use electricity to move heat...'," \
          "'video': 'https://www.youtube.com/watch?v=i73n-LTXPIM'," \
          "'icon': 'https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg'," \
          "'images':" \
          "[" \
            "'https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg'," \
            "'https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg'" \
          "]," \
          "'categories':" \
          "[" \
            "'Hot Water'," \
            "'Smart Pump'" \
          "]," \
          "'author': 'Andrea'" \
        "}," \
        "'model':" \
        "[" \
          "{" \
            "'type': 'free'," \
            "'price': 0," \
            "'trial': 0," \
            "'license': 'single'," \
            "'modelId': '1'," \
            "'currency': 'USD'" \
          "}" \
        "]",
        "'access':" \
        "[" \
          "'my access role 1'," \
          "'my access role 2'," \
        "]," \          
     "}"

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "restrict": {}, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "access":
  [
   "my access role 1",
   "my access role 2",
  ],
  "status": 
  { 
    "value": "inDevelopment", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "developer", 
    "reason": "" 
  }
}

Sample Failure Response

{
  "code": 409,
  "errors":
  [
    {
      "field": "name",
      "message": "An app with this name already exists"
    }
 ]
}

Update App

An app can be updated by a developer but the update may create a new app version that cannot be viewed by a marketplace administrator until the developer publishes the new app version. An app can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

appId
string
The id of the app to be updated
version
string
The version of the app to be updated
developerId
string
The unique id of the developer that is adding this app
name (optional)
string
The name of the app
type (optional)
string
The name of the app type for this app
model (optional)
array(Model)
A JSON array representing the pricing models for this app
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
restrict (optional)
Restriction
JSON object to restrict users from owning or viewing this app
allow (optional)
Restriction
JSON object to restrict users from owning or viewing this app
access (optional)
array(string)
JSON array of data access requirements

Returns

App Version
Returns the newly updated app.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid.
404
Not Found
The app is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Already Exists
An app with this name already exists

 

An app version will not be visible to administrators right away.
An app version must be published before it can be visible on the Management Dashboard.

Definition

POST https://market.openchannel.io/v2/apps/{appId}/versions/{version}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/1 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'name':'Hot Water Assist'," \
        "'developerId':'30'," \
        "'customData':" \ 
         "{" \
          "'summary': 'Automatically set on/off timers...'," \
          "'description': 'HPWHs use electricity to move heat...'," \
          "'video': 'https://www.youtube.com/watch?v=i73n-LTXPIM'," \
          "'icon': 'https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg'," \
          "'images':" \
          "[" \
            "'https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg'," \
            "'https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg'" \
          "]," \
          "'categories':" \
          "[" \
            "'Hot Water'," \
            "'Smart Pump'" \
          "]," \
          "'author': 'Andrea'" \
        "}," \
        "'model':" \
        "[" \
          "{" \
            "'type': 'free'," \
            "'price': 0," \
            "'trial': 0," \
            "'license': 'single'," \
            "'modelId': '1'," \
            "'currency': 'USD'" \
          "}" \
        "]" \          
     "}"

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 2, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist", "some-old-name"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "restrict": {}, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "status": 
  { 
    "value": "inDevelopment", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "developer", 
    "reason": "" 
  }
}

Sample Failure Response

{
  "code": 409,
  "errors":
  [
    {
      "field": "name",
      "message": "An app with this name already exists"
    }
 ]
}

Update App Fields

An app can be updated by a developer but the update may create a new app version that cannot be viewed by a marketplace administrator until the developer publishes the new app version. An app can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

appId
string
The id of the app to be updated
version
string
The version of the app to be updated
developerId
string
The unique id of the developer that is adding this app
fields
array(App Field Update)
JSON array of the fields to be updated

Returns

App Version
Returns the newly updated app.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid.
404
Not Found
The app is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Already Exists
An app with this name already exists

Definition

POST https://market.openchannel.io/v2/apps/{appId}/versions/{version}/fields

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/1/fields \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'developerId':'30'," \
        "'fields': [" \ 
            "{'field': 'name', 'value': 'Hot Water Assist'}," \
            "{'field': 'customData.summary', 'value': 'Automatically set on/off timers...'}," \
            "{'field': 'images', 'value':" \
              "[" \
                "'https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg'," \
                "'https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg'" \
              "]" \
            "}" \
         "]" \
     "}"

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 2, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist", "some-old-name"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "restrict": {}, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "status": 
  { 
    "value": "inDevelopment", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "developer", 
    "reason": "" 
  }
}

Sample Failure Response

{
  "code": 409,
  "errors":
  [
    {
      "field": "name",
      "message": "An app with this name already exists"
    }
 ]
}

Delete App

Deleting apps permanently removes the app and all app versions. This is useful when a developer no longer wishes to submit or maintain their app.

Parameters

appId
string
The id of the app to be deleted
developerId
string
The unique id of the developer that is deleting this app

Errors

404
Not Found
The app was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

DELETE https://market.openchannel.io/v2/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b? \
  developerId=123 \
  -X DELETE 

Sample Success Response

{}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "The app was not found"
    }
 ]
}

Delete App Version

Deleting an app version permanently removes that version.

Parameters

appId
string
The id of the app to be deleted
version
integer
The version of the app
developerId
string
The unique id of the developer that is deleting this app

Errors

404
Not Found
The app was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

DELETE https://market.openchannel.io/v2/apps/{appId}/versions/{version}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/2? \ 
 developerId=123 \
 -X DELETE 

Sample Success Response

{}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "The app was not found"
    }
 ]
}

List App Versions

Listing app versions returns App Pages based on query and sort criteria. This is useful when displaying apps to developer within your developer portal.

It’s important to know that returned apps are all of the versions and drafts ever created by developers and are not necessarily live or submitted apps. This API is most suitable for displaying app versions and drafts to developers. When listing apps for developers, it is important to provide the id of the developer making the request. If a developerId is provided, only the app versions belonging to the developer is returned.

Parameters

query (optional)
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort (optional)
string
Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.
developerId (optional)
string
The unique id of the developer requesting this resource

Returns

App Version Pages
Pages of app versions that match the query.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps/versions

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/versions? \
    developerId=123& \
    query={"$or": [{"status.value":"rejected","isLatestVersion":true},{"isLive":true},{"status.value":{"$in":["inDevelopment","inReview","pending"]}}]}& \
    sort={"status":1}

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "appId": "5565322ae4b0a70b13a4563b", 
      "customData": 
      { 
        "summary": "Automatically set on/off timers...", 
        "description": "HPWHs use electricity to move heat...", 
        "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
        "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
        "images": 
        [ 
          "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
          "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
        ], 
        "categories": 
        [ 
          "Hot Water", 
          "Smart Pump" 
        ], 
        "author": "Andrea" 
      }, 
      "lastUpdated": 1432695338702, 
      "version": 1, 
      "name": "Hot Water Assist",
      "safeName": ["hot-water-assist", "some-old-name"],
      "developerId": "30", 
      "model": 
      [ 
        { 
          "type": "free", 
          "price": 0, 
          "trial": 0, 
          "license": "single", 
          "modelId": "1", 
          "currency": "USD" 
        } 
      ], 
      "access": 
      [
        "billing - readonly"
      ], 
      "restrict": 
      {
        "own":
        {
          "country":["Canada","Mexico"]
        },
        "view":
        {
          "country":["Canada","Mexico"]
        }
      }, 
      "allow": {}, 
      "submittedDate": 1432695339005, 
      "created": 1432695338702, 
      "attributes": {}, 
      "parent":
      {
        "status": 
        { 
          "value": "approved", 
          "lastUpdated": 1432696823474, 
          "modifiedBy": "administrator", 
          "reason": "" 
        } 
      },
      "status": 
      { 
        "value": "approved", 
        "lastUpdated": 1432696823474, 
        "modifiedBy": "administrator", 
        "reason": "" 
      }, 
      "isLive": true 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON"
    }
 ]
}

Publish App Version

When a developer creates or updates an app, a new app version is created but is not yet visible to users or administrators. Publishing apps makes the app visible to the administrator and signals the app’s readiness for entry to the public marketplace. This is useful when developers have created an app draft and are ready to submit their app for approval.

Parameters

appId
string
The id of the app to be published
version
integer
The version number of the app
developerId
string
The unique id of the developer publishing this app
autoApprove (optional)
boolean
True if this app should be approved automatically

Errors

202
Accepted
Publishing succeeded but there are restrictions
400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app or version was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Conflict
An app with that name already exists

Definition

POST https://market.openchannel.io/v2/apps/{appId}/publish

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/publish \
  -X POST \
  -d version=1 \
  -d developerId="123"

Sample Success Response

{}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

 

Get an App Version

Retrieving an app version returns a single, specific version of an app. This API is most suitable for displaying an app version to a developer. When retrieving an app for a developer, it is important to provide the id of the developer making the request. If a developerId is provided, only the app version belonging to the developer is returned. Deleted app versions can be retrieved using this API method.

Parameters

appId
string
The id of the app to be returned
version
integer
The version number of the app
developerId (optional)
string
The unique id of the developer requesting this resource

Returns

App Version
The version for this app.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app or version was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps/{appId}/versions/{version}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/1? \
 developerId=30

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist", "some-old-name"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "access": 
  [
    "billing - readonly"
  ], 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "parent":
  {
    "status": 
    { 
      "value": "approved", 
      "lastUpdated": 1432696823474, 
      "modifiedBy": "administrator", 
      "reason": "" 
    } 
  },
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  }, 
  "isLive": true 
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

Change Live Version

Changes the live version of the app to a previously approved version.

Parameters

appId
string
The id of the app to become the live version
developerId
string
The id of the developer making this request
version
integer
The app version to become the live version

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app was not found

Definition

POST https://market.openchannel.io/v2/apps/{appId}/live

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/live \
 -x POST \
 -d developerId="30" \
 -d version=2

Sample Success Response

{}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

Status Change

Suspending an app temporarily hides the app from users and prevents new users from owning this app.

Parameters

appId
string
The id of the app to be suspended
developerId
string
The id of the developer suspending this app
status
string
The status change operation. Can be either ‘suspend’ or ‘unsuspend’
reason (optional)
string
The reason why this developer is suspending this app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app was not found

Definition

POST https://market.openchannel.io/v2/apps/{appId}/status

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/status \
 -x POST \
 -d developerId="30" \
 -d status="suspend" \
 -d reason="I'm having issues with my hosting provider"

Sample Success Response

{}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

 

Files

Public Files

Public files can be uploaded from the API and are automatically distributed through a global content delivery network.

In return you will receive a JSON object containing a fileUrl that looks something like this:

//file-openchannel.netdna-ssl.com/555bfb9cc434df81e597598b.png
File URLs have a generic protocol and do not start with ‘http:’ or ‘https:’
This allows the URL to become compatible with the native protocol of the serving web page. However, in some instances it may be necessary to pre-pend ‘http:’ or ‘https:’ to the URL.

There are two available methods for uploading files. You can either upload a file directly to the API using multipart form data or you can supply a URL and the OpenChannel platform will download the file.

After uploading a file, add the fileUrl to any app, review, user or developer’s customData object.

Add the fileUrl to a customData field.
Any files that do not have a URL within an app, user, developer, or review customData field will be deleted after a few days.

For example, here is an app with a file attached to an app’s customData.icon field:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "icon": "//cdn.openchannel.io/files/55653202e4b0a70b13a4562d.jpg"
  },
 ... 
}

Private Files

Private files can be uploaded from the API and are automatically distributed through a global content delivery network. Unlike with public files, private files are not publicly accessible and do not have an associated fileUrl. Instead, it’s required that the Download File API method be called in order to get a signed, short lived URL which a user can use to download the file.

Since the signed URLS can only be used for a few seconds, the best way to implement file download is:

  1. The user clicks on a link or requests to download the file
  2. Your back end service calls the Download File API to generate a signed URL
  3. Redirect the user to the signed URL or use javascript to initiate the download
Don’t display signed URL’s as links on webpages.
Signed URLs are only usable for a few seconds so they shouldn’t be placed directly on webpages. Instead, they should be generated and used when the user has already decided to perform the “download” action.

After uploading a file, add the fileId to any app, review, user or developer’s customData object.

Add the fileId to a customData field.
Any files that do not have a fileId within an app, user, developer, or review customData field will be deleted after a few days.

For example, here is an app with a file attached to an app’s customData.myFile field:

{
  "appId": "5565322ae4b0a70b13a4563b", 
  "name": "my first app",
  "developerId": "123",
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "myFile": "59b0100dca753d5ed65578bb/private/55653202e4b0a70b13a4562d.jpg"
  },
 ... 
}

File Upload

Parameters

file
file
The multipart form data file stream
isPrivate (optional)
boolean
If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.
hash (optional)
string
A comma separated list of hashes to return in order to verify file integrity.

Returns

File
The metadata for the file that was uploaded

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

 

Definition

POST https://market.openchannel.io/v2/files

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files?isPrivate=false \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/file.jpg"

Sample Response

{
  "uploadDate": 1457710762784,
  "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
  "name": "book.csv", 
  "contentType": "application/octet-stream", 
  "size": 16206, 
  "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "file",
      "message": "The file must be submitted as multipart form data"
    }
 ]
}

File Upload By URL

Parameters

url
string
The URL of the file to be uploaded
isPrivate (optional)
boolean
If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.
hash (optional)
string
A comma separated list of hashes to return in order to verify file integrity.

Returns

File
The metadata for the file that was uploaded

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/files/url

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files/url?isPrivate=false \
  -X POST \
  -d url="http://myurl.com/example.jpg"

Sample Response

{
  "uploadDate": 1457710762784,
  "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
  "name": "book.csv", 
  "contentType": "application/octet-stream", 
  "size": 16206, 
  "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "url",
      "message": "This URL does not contain a valid file"
    }
 ]
}

 

Get File Details

The details for a File can be returned by providing the fileId or fileUrl.

Parameters

fileldOrUrl
string
The fileId or fileUrl of the file to be returned

Returns

File
The metadata for the file

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The file was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/files/byIdOrUrl

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files/byIdOrUrl?fileIdOrUrl=59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv

Sample Response

{
  "uploadDate": 1457710762784,
  "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
  "name": "book.csv", 
  "contentType": "application/octet-stream", 
  "size": 16206, 
  "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "fileId",
      "message": "This field is required"
    }
 ]
}

Download File

A signed URL for downloading a private file can be returned by providing the fileId.

Parameters

fileld
string
The id of the file to be returned
validSeconds (optional)
integer
The number of seconds that this signed URL should be valid for. The default is 60.

Returns

url
string
The signed URL for this private file.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The file was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/files/download?fileId={fileId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files/download?fileId=59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv

Sample Response

{
  "url": "https://d3grfap2l5ikgv.cloudfront.net/59b0100dca753d5ed6557895/public/5b982203c472e41786090c33.json?Expires=1536696937&Signature=PX7x~TDzxjI7GdkV7MZpQg5432HYhK3AySaSuvj2vu9-heY2Yrufj2oOv0MTDtulBP443Wi3q7QyO77mR5KDk1mNKpe4s5maZZ64f8ozIw5qB2VaoVA--MXgIrNDX5eUo5MVwQA1YmpdlnpVvsXHHHrG~9gCwsJAM53cblfku5eNxrlHT9TF7wQ~OI8sMD6VVFZpp6wF1Cf04zdHyHqNp0ToD8le6sI-LLiXgc00xKnhyZTdC3UpX9Sf5qY6ZIWUcyAwh9sq~ChfeMqn-QdxTNlEzPLZ8~HP8yfehDhUayoldoexCs1vdw1Ssg3zxprtSqiNsyucAj3ALeYb1XQCw__&Key-Pair-Id=APKAIAMDQUKRE4E2A46Q" 
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "fileId",
      "message": "This field is required"
    }
 ]
}

List Files

Listing files returns File Pages based on query and sort criteria. This is useful when gathering information about the files stored on your marketplace.

Parameters

query (optional)
string
A Query Document. Example: {“uploadDate”:{“$gt”:1498851408000}} matches all the files uploaded after June 30th 2017
sort (optional)
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.

Returns

File Pages
A page of developer results

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/files

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files? \
  query={'uploadDate':{'$gt':1498851408000}}& \
  sort={'name':1}& \

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
        "uploadDate": 1457710762784,
        "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
        "name": "book.csv", 
        "contentType": "application/octet-stream", 
        "size": 16206, 
        "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Developers

Each developer is a JSON representation of an active, authenticated developer that can be uniquely identified by a developerId.

The structure of an developer can be customized using the customData object. When creating or updating a developer, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your developer. The OpenChannel platform will automatically detect and handle your custom developer structure.

Get Developer

Retrieving an developer returns a single, specific, developer.

Paremeters

developerId
string
The unique id of the developer

Returns

Developer
The developer

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The developer is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/developers/{developerId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers/123

Sample Success Response

{ 
  "developerId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }, 
  "created": 1432695338702
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

List Developers

Listing developers returns Developer Pages based on query and sort criteria. This is useful when gathering information about the developers registered on your marketplace.

Parameters

query (optional)
string
A Query Document. Example: {“created”:{“$gt”:1498851408000}} matches all the developer accounts created after June 30th 2017
sort (optional)
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.

Returns

Developer Pages
A page of developer results

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/developers

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers? \
  query={'created':{'$gt':1498851408000}}& \
  sort={'name':1}& \

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "developerId": "123", 
      "name": "Brian",
      "email": "brian@mycompany.com",
      "customData": 
      { 
        "companyName": "Automatic",
        "interests": ["Surfing", "Kittens"]
      }, 
      "created": 1432695338702
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Create/Update Developer

An developer can be updated and can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

developerId
string
The unique id of the developer
username (optional)
string
The username of this developer
name (optional)
string
The name of this developer
email (optional)
string
This developer’s email address
groupId (optional)
string
This developer’s group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this developer record

Returns

Developer
The newly created developer

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/developers/{developerId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers/123 \ 
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'name':'Brian'," \
        "'email':'brian@mycompany.com'," \
        "'customData':" \
        "{" \
           "'companyName': 'Automatic'," \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"

Sample Success Response

{ 
  "developerId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }, 
  "created": 1432695338702
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "developerId",
      "message": "This field is required"
    }
 ]
}

Get Developer Group

Returns a single, specific, developer group.

Parameters

groupId
string
The unique id of the group

Returns

DeveloperGroup
The developer group

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The group is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/developers/groups/{groupId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers/groups/abc

Sample Success Response

{ 
  "groupId": "abc", 
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

Create/Update Developer Group

An developer group can be updated and can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

groupId
string
The unique id of the group
email
string
The contact email address for the group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this record

Returns

DeveloperGroup
The newly created/updated developer group

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/developers/groups/{groupId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers/groups/abc \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'customData':" \
        "{" \
           "'companyName': 'Automatic'," \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"

Sample Success Response

{ 
  "groupId": "abc", 
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "customData",
      "message": "Malformed JSON object"
    }
 ]
}

Statistics

Statistics are recorded to help you and developers gain insight into the performance and operation of apps. Although the OpenChannel platform keeps track of a few statistics like views, developer count and number of downloads by default, you have the ability to define and record your own custom statistics to suit your unique needs.

Get Total

A sum of statistics can be returned for any app statistic recorded within your marketplace. This is useful when displaying statistical totals for developers.The response includes the sum for each individual app that satisfies the query as well as a grand total.

Parameters

fields
string
A comma separated list of statistic types that you want to total. Some default statistics are: “reviews”, “users”, “developers”, “views”,  “totalSales”, “downloads”
start (optional)
long
The time (in milliseconds) to begin the sum
end (optional)
long
The time (in milliseconds) to end the sum
query (optional)
string
A Query Document. Example: {“status.value”:”approved”} returns statistics for all the apps that are approved

Returns

Total
The sum of the statistic values

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/stats/total

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stats/total? \
  start=1455062400000& \
  end=1457568000000& \
  fields=views,downloads& \
  query={'developerId':'123'}

Sample Success Response

{
  "apps": {
    "551569dde4b09c3f7fe5461f": {
      "views": 12,
      "downloads": 1
    },
    "56ddebd81707a5648b8c5193": {
      "views": 4785,
      "downloads": 374
    }
  },
  "totals": {
    "views": 4797,
    "downloads": 375
  }
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "fields",
      "message": "This field is required"
    }
 ]
}

Get Time Series

A time series can be returned for any app statistic recorded within your marketplace and is returned as an array of date and value pairs. This is useful when displaying statistics charts for developers.

Parameters

period
string
The period for the series. Can be: “day” or “month”
fields
string
The field to be graphed. This also be a comma separated list of fields and the result will be a single timeseries containing the sum of all fields.
start (optional)
long
The time (in milliseconds) to begin the time series
end (optional)
long
The time (in milliseconds) to end the time series
query (optional)
string
A Query Document. Example: {“status.value”:”approved”} returns statistics for all the apps that are approved

Returns

array(array(long))
A time series array containing the date (in milliseconds) and the value

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/stats/series/{period}/{fields}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stats/series/day/views? \
  start=1455062400000& \
  end=1457568000000& \
  query={'developerId':'123'}

Sample Success Response

[
  [1455062400000,22],
  [1455148800000,65],
  [1455235200000,4],
  [1455321600000,0],
  [1455408000000,342],
  [1455494400000,345],
  [1455580800000,665],
  [1455667200000,43],
  [1455753600000,11],
  [1455840000000,2],
  [1455926400000,3],
  [1456012800000,44],
  [1456099200000,32],
  [1456185600000,56],
  [1456272000000,78],
  [1456358400000,34],
  [1456444800000,3],
  [1456531200000,23],
  [1456617600000,0],
  [1456704000000,0],
  [1456790400000,0],
  [1456876800000,0],
  [1456963200000,0],
  [1457049600000,0],
  [1457136000000,0],
  [1457222400000,0],
  [1457308800000,30],
  [1457395200000,0],
  [1457481600000,21],
  [1457568000000,35]
]

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "period",
      "message": "This field is required"
    }
 ]
}

Apps

Each app is a JSON representation of an application submitted by a developer that has already been approved by a Marketplace administrator.

The structure of an app can be customized using the customData object. When creating or updating an app, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your app. The OpenChannel platform will automatically detect and handle your custom app structure.

List Apps

Listing apps returns App Pages based on query and sort criteria. This is useful when displaying combinations of apps to end users on your marketplace such as all, sorted and by category or tag.

It’s important to know that returned apps include both approved and suspended apps. This API will only return apps that have been submitted and approved by the administrator and is most suitable for displaying apps to end users. When listing apps on your public marketplace, it is important to filter out suspended apps from the results. This can be achieved by adding the “status.value”: “approved” clause to your query parameter.

Results can be returned with additional user-specific data in the app listing by providing the userId. When the userId is provided, app ownership details are automatically added to the app results; statistics are gathered on usage and app restrictions are enforced. Always supply the userId when an authenticated user requests an app listing.

Parameters

query (optional)
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort (optional)
string
Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.
userId (optional)
string
The unique id of the user requesting this resource
isOwner (optional)
boolean
Whether this result should only contain apps that are owned by this user

Returns

App Pages
A page of app results

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps? \
  query={'status.value':'approved'}& \
  sort={'randomize':1}& \
  userId=123

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "appId": "5565322ae4b0a70b13a4563b", 
      "customData": 
      { 
        "summary": "Automatically set on/off timers...", 
        "description": "HPWHs use electricity to move heat...", 
        "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
        "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
        "images": 
        [ 
          "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
          "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
        ], 
        "categories": 
        [ 
          "Hot Water", 
          "Smart Pump" 
        ], 
        "author": "Andrea" 
      }, 
      "lastUpdated": 1432695338702, 
      "version": 1, 
      "name": "Hot Water Assist",
      "safeName": ["hot-water-assist", "some-old-name"],
      "developerId": "30", 
      "model": 
      [ 
        { 
          "type": "free", 
          "price": 0, 
          "trial": 0, 
          "license": "single", 
          "modelId": "1", 
          "currency": "USD" 
        } 
      ], 
      "access": 
      [
        "billing - readonly"
      ], 
      "restrict": 
      {
        "own":
        {
          "country":["Canada","Mexico"]
        },
        "view":
        {
          "country":["Canada","Mexico"]
        }
      }, 
      "allow": {}, 
      "submittedDate": 1432695339005, 
      "created": 1432695338702, 
      "attributes": {}, 
      "rating": 400, 
      "status": 
      { 
        "value": "approved", 
        "lastUpdated": 1432696823474, 
        "modifiedBy": "administrator", 
        "reason": "" 
      }, 
      "statistics":
      {
        "views":{"30day":0,"90day":0,"total":0},
        "downloads":{"30day":0,"90day":0,"total":0},
        "developerSales":{"30day":0,"90day":0,"total":0},
        "totalSales":{"30day":0,"90day":0,"total":0},
        "ownerships":{"30day":0,"90day":0,"total":0},
        "reviews":{"30day":0,"90day":0,"total":0}
      },
      "isLive": true 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Get an App

Retrieving an app returns a single, specific, live app. This API will only return apps that have been submitted and approved by the administrator and is most suitable for displaying apps to end users.

Results can be returned with additional user-specific data in the app by providing the userId. When the userId is provided, app ownership details are automatically added to the app results; statistics are gathered on usage and app restrictions are enforced. Always supply the userId when an authenticated user requests an app. Deleted apps can be retrieved using this API method.

Parameters

appId
string
The id of the app to be returned
userId (optional)
string
The unique id of the user requesting this resource
trackViews
boolean
Whether this call should be tracked as a ‘view’ for this app. Default is false.

Returns

App
A single app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app is either restricted or not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b? \
  userId=abc

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist", "some-old-name"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "access": 
  [
    "billing - readonly"
  ], 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "rating": 400, 
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  }, 
  "statistics":
  {
    "views":{"30day":0,"90day":0,"total":0},
    "downloads":{"30day":0,"90day":0,"total":0},
    "developerSales":{"30day":0,"90day":0,"total":0},
    "totalSales":{"30day":0,"90day":0,"total":0},
    "ownerships":{"30day":0,"90day":0,"total":0},
    "reviews":{"30day":0,"90day":0,"total":0}
  },
  "isLive": true 
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

                                                

Search Apps

Searching apps returns App Pages based on query and text criteria. You can search for apps by specifying the text that you want to search for as well as a list of fields that you want to include in the search. The results will include apps that contain the search text within any of the specified fields. This is useful when allowing end users to search through available apps.

It’s important to know that returned apps include both approved and suspended apps. This API will only return apps that have been submitted and approved by the administrator and is most suitable for displaying apps to end users. When listing apps on your public marketplace, it is important to filter out suspended apps from the results. This can be achieved by adding the “status.value”: “approved” clause to your query parameter.

Results can be returned with additional user-specific data in the app listing by providing the userId. When the userId is provided, app ownership details are automatically added to the app results; statistics are gathered on usage and app restrictions are enforced. Always supply the userId when an authenticated user requests an app listing.

Parameters

query (optional)
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
text
string
The text that you want to search for
fields
JSON Array
A JSON Array of field names to include as part of the search. You can also use dot notation to add sub documents.
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.
userId (optional)
string
The unique id of the user requesting this resource
isOwner (optional)
boolean
Whether this result should only contain apps that are owned by this user

Returns

App Pages
A page of app results

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps/textSearch

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/textSearch? \
  query={'status.value':'approved'}& \
  text=electricity& \
  fields=['name','customData.summary','customData.description']& \
  userId=123

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "appId": "5565322ae4b0a70b13a4563b", 
      "customData": 
      { 
        "summary": "Automatically set on/off timers...", 
        "description": "HPWHs use electricity to move heat...", 
        "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
        "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
        "images": 
        [ 
          "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
          "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
        ], 
        "categories": 
        [ 
          "Hot Water", 
          "Smart Pump" 
        ], 
        "author": "Andrea" 
      }, 
      "lastUpdated": 1432695338702, 
      "version": 1, 
      "name": "Hot Water Assist",
      "safeName": ["hot-water-assist", "some-old-name"],
      "developerId": "30", 
      "model": 
      [ 
        { 
          "type": "free", 
          "price": 0, 
          "trial": 0, 
          "license": "single", 
          "modelId": "1", 
          "currency": "USD" 
        } 
      ], 
      "access": 
      [
        "billing - readonly"
      ], 
      "restrict": 
      {
        "own":
        {
          "country":["Canada","Mexico"]
        },
        "view":
        {
          "country":["Canada","Mexico"]
        }
      }, 
      "allow": {}, 
      "submittedDate": 1432695339005, 
      "created": 1432695338702, 
      "attributes": {}, 
      "rating": 400, 
      "status": 
      { 
        "value": "approved", 
        "lastUpdated": 1432696823474, 
        "modifiedBy": "administrator", 
        "reason": "" 
      }, 
      "statistics":
      {
        "views":{"30day":0,"90day":0,"total":0},
        "downloads":{"30day":0,"90day":0,"total":0},
        "developerSales":{"30day":0,"90day":0,"total":0},
        "totalSales":{"30day":0,"90day":0,"total":0},
        "ownerships":{"30day":0,"90day":0,"total":0},
        "reviews":{"30day":0,"90day":0,"total":0}
      },
      "isLive": true 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "fields",
      "message": "This field is required"
    }
 ]
}

Get App By SafeName

Retrieving an app returns a single, specific, live app. This API will only return apps that have been submitted and approved by the administrator and is most suitable for displaying apps to end users.

Results can be returned with additional user-specific data in the app by providing the userId. When the userId is provided, app ownership details are automatically added to the app results; statistics are gathered on usage and app restrictions are enforced. Always supply the userId when an authenticated user requests an app. Deleted apps can be retrieved using this API method.

Parameters

safeName
string
The safeName of the app to be returned
userId (optional)
string
The unique id of the user requesting this resource
trackViews
boolean
Whether this call should be tracked as a ‘view’ for this app. Default is false.

Returns

App
A single app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The app is either restricted or not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/apps/bySafeName/{safeName}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/bySafeName/hot-water-assist? \
  userId=abc

Sample Success Response

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist", "some-old-name"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "access": 
  [
    "billing - readonly"
  ], 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "rating": 400, 
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  }, 
  "statistics":
  {
    "views":{"30day":0,"90day":0,"total":0},
    "downloads":{"30day":0,"90day":0,"total":0},
    "developerSales":{"30day":0,"90day":0,"total":0},
    "totalSales":{"30day":0,"90day":0,"total":0},
    "ownerships":{"30day":0,"90day":0,"total":0},
    "reviews":{"30day":0,"90day":0,"total":0}
  },
  "isLive": true 
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

                                                

Users

Each user is a JSON representation of an active, authenticated user that can be uniquely identified by a userId.

The structure of an user can be customized using the customData object. When creating or updating a user, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your user. The OpenChannel platform will automatically detect and handle your custom user structure.

Get User

Retrieving an user returns a single, specific, user.

Parameters

userId
string
The unique id of the user

Returns

User
The user

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The user is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/users/{userId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users/123

Sample Success Response

{ 
  "userId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

List Users

Listing users returns User Pages based on query and sort criteria. This is useful when gathering information about the users registered on your marketplace.

Parameters

query (optional)
string
A Query Document. Example: {“created”:{“$gt”:1498851408000}} matches all the user accounts created after June 30th 2017
sort (optional)
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.

Returns

User Pages
A page of user results

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/users

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users? \
  query={'created':{'$gt':1498851408000}}& \
  sort={'name':1}& \

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "userId": "123", 
      "name": "Brian",
      "email": "brian@mycompany.com",
      "customData": 
      { 
        "companyName": "Automatic",
        "interests": ["Surfing", "Kittens"]
      }, 
      "created": 1432695338702
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Create/Update User

An user can be updated and can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

userId
string
The unique id of the user
groupId (optional)
string
This user’s groupId
username (optional)
string
The username of this user
name (optional)
string
The name of this user
email (optional)
string
This user’s email address
customData (optional)
CustomData
A custom JSON object that you can create and attach to this user record

Returns

User
The newly created user

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/users/{userId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users/123 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'name':'Brian'," \
        "'email':'brian@mycompany.com'," \
        "'customData':" \
        "{" \
           "'companyName': 'Automatic'," \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"

Sample Success Response

{ 
  "userId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "customData",
      "message": "Malformed JSON object"
    }
 ]
}

Get User Group

Returns a single, specific, user group.

Parameters

groupId
string
The unique id of the group

Returns

UserGroup
The user group

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The group is not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/users/groups/{groupId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users/groups/abc

Sample Success Response

{ 
  "groupId": "abc", 
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

Create/Update User Group

An user group can be updated and can contain customizable fields, media and text by populating the customData field with a JSON object.

Parameters

groupId
string
The unique id of the group
email
string
The contact email address for the group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this record

Returns

UserGroup
The newly created/updated user group

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/users/groups/{groupId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users/groups/abc \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'customData':" \
        "{" \
           "'companyName': 'Automatic'," \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"

Sample Success Response

{ 
  "groupId": "abc", 
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "customData",
      "message": "Malformed JSON object"
    }
 ]
}

Ownership

Each ownership record is a JSON representation of an users ownership of an app and describes the details of the relationship.

Install App

Owning apps tracks the ownership relationship between a user and an app. This is useful when users wish to use, launch or associate their account with an app.

Parameters

appId
string
The id of the app
userId
string
The unique id of the user performing this action
modelId
string
The id of the app model involved in this ownership
customData (optional)
CustomData
A custom JSON object to attach to this ownership record

Returns

Ownership
The ownership record for this user and app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
402
Payment Required
The App requires a user with pre-set payment details
404
Not Found
The ownership was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Already Exists
The User already owns this app (or is already participating in a trial)
412
Payment Failed
The User’s payment details are invalid

Definition

POST https://market.openchannel.io/v2/ownership/install

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership/install \
  -X POST \
  -d appId="5565322ae4b0a70b13a4563b" \
  -d userId="abc" \
  -d modelId="1"

Sample Success Request

{
  "ownershipId": "5463cee5e4b042e3e26f1e41",
  "date": 1427466717262,
  "appId": "5565322ae4b0a70b13a4563b",
  "userId": "abc",
  "developerId": "123",
  "ownershipType": "full",
  "ownershipStatus": "active",
  "model":
  { 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
  }
}

Sample Failure Request

{
  "code": 400,
  "errors":
  [
    {
      "field": "modelId",
      "message": "This field is required"
    }
 ]
}

Get Ownership

Retrieving an ownership returns a single, ownership record representing the relationship between a user and app.

Parameters

ownershipId
string
The id of the ownership record to retrieve

Returns

Ownership
The ownership record for this user and app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The ownership was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/ownership/{ownershipId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership/5463cee5e4b042e3e26f1e41

Sample Success Request

{
  "ownershipId": "5463cee5e4b042e3e26f1e41",
  "date": 1427466717262,
  "appId": "5565322ae4b0a70b13a4563b",
  "userId": "abc",
  "developerId": "123",
  "ownershipType": "full",
  "ownershipStatus": "active",
  "model":
  { 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
  }
}

Sample Failure Request

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

List Ownership

Listing ownership returns App Pages based on query and sort criteria.

Parameters

query (optional)
string
Query Document. Example: {userId:”abc”} matches all the ownership records for user “abc”.
sort (optional)
string
Sort Document. Example: {“date”:1} sorts the results by date in ascending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.

Returns

Ownership Pages
A page of ownership records

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/ownership

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership \ 
  query={'userId':'abc'}& \
  sort={'date':1}

Sample Success Request

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
      "ownershipId": "5463cee5e4b042e3e26f1e41",
      "date": 1427466717262,
      "appId": "5565322ae4b0a70b13a4563b",
      "userId": "abc",
      "developerId": "123",
      "ownershipType": "full",
      "ownershipStatus": "active",
      "model":
      { 
        "type": "free", 
        "price": 0, 
        "trial": 0, 
        "license": "single", 
        "modelId": "1", 
        "currency": "USD" 
      },
    }
    {...},
    {...}
  ]
}

Sample Failure Request

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Uninstall App

Uninstalls a license for a particular user and app (uninstalls app).

Parameters

ownershipId
string
The id of the ownership to be unintalled
userId
string
The id of the User requesting to uninstall the App
cancelOwnership (optional)
boolean
True if this app must be paid for in order to be re-installed. Default is false
customData (optional)
CustomData
A custom JSON object to attach to this ownership record

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The ownership was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Not Installed
App is not owned by this user

Definition

POST https://market.openchannel.io/v2/ownership/uninstall/{ownershipId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership/uninstall/5565322ae4b0a70b13a4563b \
  -X POST \
  -d userId="abc"

Sample Success Request

{
  "ownershipId": "5463cee5e4b042e3e26f1e41",
  "date": 1427466717262,
  "appId": "5565322ae4b0a70b13a4563b",
  "userId": "abc",
  "developerId": "123",
  "ownershipType": "full",
  "ownershipStatus": "active",
  "model":
  { 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
  }
}

Sample Failure Request

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

Update Ownership

Updates an ownership record.

Parameters

ownershipId
string
The id of the ownership record to be updated
customData (optional)
CustomData
A custom JSON object to attach to this ownership record
expires (optional)
long
The date (in millis) of when this app ownership expires

Returns

Ownership
The updated ownership record

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The ownership was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/ownership/{ownershipId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership/5463cee5e4b042e3e26f1e41 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'customData': {'department': 'billing'}" \
     "}"

Sample Success Request

{
  "ownershipId": "5463cee5e4b042e3e26f1e41",
  "date": 1427466717262,
  "appId": "5565322ae4b0a70b13a4563b",
  "userId": "abc",
  "developerId": "123",
  "ownershipType": "full",
  "ownershipStatus": "active",
  "model":
  { 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD"
  }
}

Sample Failure Request

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not found"
    }
 ]
}

Reviews

Each review is a JSON representation of a review that has been submitted by a user for an app.

Create Review

Posting an app review allows users that already own this app to create a review record. This is useful when allowing users to voice their opinion about an app.

Parameters

appId
string
The id of the app being reviewed
userId
string
The unique id of the user that is reviewing this app
headline
string
The review’s headline. Limited to 50 characters.
rating
integer
The rating given within this review. The rating is represented as an integer between 0 and 500 (0 – 5 stars)
description
string
The review’s description. Limited to 2000 characters.
mustOwnApp (optional)
boolean
True if a review can be created only by a user that has owned the app. The default is True.
autoApprove (optional)
boolean
True if the review should be automatically approved. The default is False.
customData (optional)
CustomData
A custom JSON object that you can create and attach to this review record

Returns

Review
The newly created review

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
403
Forbidden
Users must have owned the app before they can post a review; Anonymous users cannot post reviews
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
409
Already Exists
The User has already reviewed this app

Definition

POST https://market.openchannel.io/v2/reviews

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'appId':'5565322ae4b0a70b13a4563b'," \
        "'userId':'abc'," \
        "'headline':'Great experience!'," \
        "'rating':500," \
        "'description':'I loved everything about this app...'," \
        "'customData': {summary: 'some value'}" \
     "}"

Sample Success Response

{
  "reviewId": "55b58003e4b0c7e279e2335e",
  "rating": 500,
  "description": "I loved everything about this app...",
  "headline": "Great experience!",
  "appId": "5565322ae4b0a70b13a4563b",
  "appName": "My App",
  "userId": "abc",
  "appVersion": 1,
  "status":
  {
    "value": "pending"
  },
  "customData":
  {
    "summary": "some value"
  },
  "reportDate": 1437958147165
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "rating",
      "message": "Must be a number between 0 and 500"
    }
 ]
}

Update Review

Updating an app review allows users to modify their reviews.

Parameters

reviewId
string
The id of the review being updated
UserId
string
The unique id of the user that is updating this review
headline
string
The review’s headline. Limited to 50 characters.
rating
integer
The rating given within this review. The rating is represented as an integer between 0 and 500 (0 – 5 stars)
description
string
The review’s description. Limited to 2000 characters.
customData (optional)
CustomData
A custom JSON object that you can create and attach to this review record

Returns

Review
The newly updated review

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/reviews/{reviewId}

Sample Response

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews/55b58003e4b0c7e279e2335e \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'userId':'abc'," \
        "'headline':'Great experience!'," \
        "'rating':500," \
        "'description':'I loved everything about this app...'," \
        "'customData': {summary: 'some value'}" \
     "}"

Sample Success Response

{
  "reviewId": "55b58003e4b0c7e279e2335e",
  "rating": 500,
  "description": "I loved everything about this app...",
  "headline": "Great experience!",
  "appId": "5565322ae4b0a70b13a4563b",
  "appName": "My App",
  "userId": "abc",
  "appVersion": 1,
  "status":
  {
    "value": "pending"
  },
  "customData":
  {
    "summary": "some value"
  },
  "reportDate": 1437958147165
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "rating",
      "message": "Must be a number between 0 and 500"
    }
 ]
}

Get Review

Retrieving a review returns a single, specific, review record. This API will return a review even if it has not yet been approved by the administrator. Deleted reviews can be retrieved using this API method.

Parameters

reviewId
string
The id of the review

Returns

Review
A single review

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
404
Not Found
A review with this reviewId was not found

Definition

GET https://market.openchannel.io/v2/reviews/{reviewId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews/55b58003e4b0c7e279e2335e

Sample Success Request

{
  "reviewId": "55b58003e4b0c7e279e2335e",
  "rating": 500,
  "description": "I loved everything about this app...",
  "headline": "Great experience!",
  "appId": "5565322ae4b0a70b13a4563b",
  "appName": "My App",
  "userId": "abc",
  "appVersion": 1,
  "status":
  {
    "value": "pending"
  },
  "customData":
  {
    "summary": "some value"
  },
  "reportDate": 1437958147165
}

Sample Failure Request

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not Found"
    }
 ]
}

Get Review By AppId/UserId

Retrieving a review returns a single, specific, review record. This API will return a review even if it has not yet been approved by the administrator.

Parameters

appId
string
The id of the user that posted the review
userId
string
The id of the app this review belongs to

Returns

Review
A single review

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
404
Not Found
A review with this userId and appId was not found

Definition

GET https://market.openchannel.io/v2/reviews/apps/{appId}/users/{userId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews/appId/55b58003e4b0c7e279e2335e/users/abc

Sample Success Request

{
  "reviewId": "55b58003e4b0c7e279e2335e",
  "rating": 500,
  "description": "I loved everything about this app...",
  "headline": "Great experience!",
  "appId": "5565322ae4b0a70b13a4563b",
  "appName": "My App",
  "userId": "abc",
  "appVersion": 1,
  "status":
  {
    "value": "pending"
  },
  "customData":
  {
    "summary": "some value"
  },
  "reportDate": 1437958147165
}

Sample Failure Request

{
  "code": 404,
  "errors":
  [
    {
      "message": "Not Found"
    }
 ]
}

List Reviews

Listing reviews returns Pages based on query and sort criteria. This is useful when displaying reviews to end users on your marketplace.

When listing reviews on your public marketplace, it is important to filter out unapproved reviews from the results. This can be achieved by adding the “status.value”: “approved” clause to your query parameter. It is important to provide the id of the user making the request. If a userId is provided, users will be able to see their own reviews even before a review is approved.

Parameters

query (optional)
string
Query Document. Example: {“status.value”:”approved”} matches all the reviews that are approved.
sort (optional)
string
Sort Document. Example: {“date”:1} sorts the results by date in ascending order
pageNumber(optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.
userId (optional)
string
The unique id of the user requesting this resource

Returns

Review
A page of reviews

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/reviews

Sample Response

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews? \
  query={'status.value':'approved', 'appId':'5565322ae4b0a70b13a4563b'}& \
  sort={'date':1}& \
  userId=abc

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
      "reviewId": "55b58003e4b0c7e279e2335e",
      "rating": 400,
      "description": "This App was incredibly easy to use and only took a few moments to get set up. Highly recommend this app! I have been using it everyday since.",
      "headline": "Cannot live without it",
      "appId": "556536b6e4b0a70b13a456e5",
      "appName": "My App",
      "userId": "11",
      "appVersion": 1,
      "status": 
      {
        "value": "approved"
      },
      "customData": 
      {
        "summary": "some value"
      },
      "reportDate": 1437958147165
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON object"
    }
 ]
}

Statistics

Statistics are recorded to help you and developers gain insight into the performance and operation of apps. Although the OpenChannel platform keeps track of a few statistics like views, developer count and number of downloads by default, you have the ability to define and record your own custom statistics to suit your unique needs.

Record Statistic

To record your own custom statistics, choose a field name that doesn’t conflict with the native statistic fields (example: “leads”) and use that custom field name when calling the increment API method. The value field also accepts negative integers in order to decrement the statistic.

Parameters

field
string
The statistic type that you want to increment
appId
string
The id of the app associated with this statistical recording
userId (optional)
string
The id of the user performing the action
date (optional)
long
The time (in milliseconds) when this statistical event occurred
value (optional)
integer
The increment amount. Default is 1 if no value is provided

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/stats/increment/{field}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stats/increment/downloads \
  -X POST \
  -d appId=5565322ae4b0a70b13a4563b \
  -d date=1457568000000 \
  -d value=1 \
  -d userId="123"

Sample Success Response

{}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "value",
      "message": "This must be a number"
    }
 ]
}

Permission

Permission methods let a user give consent to the requirements of an app. Before an app can be installed, it must consent to the requirements of this app. The term “requirements” is broad and can be anything including: Terms and conditions, data access requirements or hardware access requirements.

Add Permissions

Indicates that this user consents to the requirements of this app.

Parameters

userId
string
The unique id of the user giving consent
appId
string
The id of the app that requires consent
date (optional)
long
The date (in milliseconds) of when this consent occurred
ip (optional)
string
The IP address of the user giving consent
group (optional)
boolean
True if this permission should be added for all members of the user’s group

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
App not found

Definition

POST https://market.openchannel.io/v2/permission/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/permission/apps/5565322ae4b0a70b13a4563b \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'userId':'abc'", \
        "'ip':'254.34.120.4'" \
     "}"

Sample Success Response

{}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "App not found"
    }
 ]
}

Get Permissions

Retrieving permissions returns the status of consent between an app and a user.

Parameters

appId
string
The id of the app
userId
string
The id of the user

Returns

Access
The access consent between this user and this app

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The access is not found

Definition

GET https://market.openchannel.io/v2/permission/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/permission/apps/5565322ae4b0a70b13a4563b? \
  userId=abc

Sample Success Response

{ 
  "appId": "56f57d00f8db622cbc78cf06",
  "userId": "abc",
  "date": 1460577727245,
  "ip": "254.34.120.4",
  "access": [
    "GPS",
    "Billing"
  ]
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This access was not found"
    }
 ]
}

Delete Permissions

Indicates that this user no longer consents to the requirements of this app.

Parameters

userId
string
The unique id of the user giving consent
appId
string
The id of the app that requires consent

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The access is not found

Definition

DELETE https://market.openchannel.io/v2/permission/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/permission/apps/5565322ae4b0a70b13a4563b? \
  userId=abc \
  -X DELETE

Sample Success Response

{}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This access is not found"
    }
 ]
}

Markets

The market contains the settings for the current marketplace and includes the category and attribute configurations.

Get Market

Retrieving this market returns a single record representing the settings of the current market.

Returns

Market
The current market

Errors

405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/markets/this

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/markets/this

Sample Success Response

{ 
  "marketplaceId": "551ec66be4b0ad30c5437e70",
  "name": "demo1",
  "attributes": [
    {
      "name": "My Test Attribute",
      "type": "select",
      "values": "val 1,val 2,val 3"
    }
  ],
  "minPrice": 99,
  "maxPrice": 99999,
  "currency": "USD",
  "viewAppUrl": "https://market.my-site.com/apps/{appId}",
  "previewAppUrl": "https://market.my-site.com/apps/{appId}/{version}"
}

Transactions

A Transaction tracks the relationship between a user and a paid app. Each transaction can can represent a payment or refund. Multiple payments for a single app occur if the app has a recurring payment model.

List Transactions

Listing transactions returns Transaction Pages based on query and sort criteria. This is useful when displaying payments or refunds to developers or users.

Parameters

query (optional)
string
Query Document. Example: {“type”:”payment”} matches all the payment transactions.
sort (optional)
string
Sort Document. Example: {“date”:-1} sorts the results by name in descending order
pageNumber (optional)
integer
The result set page number to be returned
limit (optional)
integer
The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.

Returns

Transaction Pages
Pages of transactions that match the query.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/transactions

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/transactions

Sample Success Response

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "transactionId": "5463cee5e4b042e3e26f1e41",
      "ownershipId": "55653202e4b0a70b13a4562d", 
      "appId": "5565322ae4b0a70b13a4563b", 
      "userId": "abc",
      "developerId": "123",
      "customData": 
      { 
        "department": "billing", 
      }, 
      "date": 1432695338702, 
      "type": "payment", 
      "amount": 1000,
      "feeAmount": 0,
      "marketplaceAmount": 200,
      "developerAmount": 800
    },
    {...},
    {...}
  ]
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "query",
      "message": "Malformed JSON"
    }
 ]
}

 

Get Transaction

Retrieving a transaction returns a single, specific payment or refund. This API is most suitable for displaying the details of a transaction for a user or developer. Deleted transactions can be retrieved using this API method.

Parameters

transactionId
string
The id of the transaction to be returned

Returns

Transaction
The transaction.

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The transaction was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/transactions/{transactionId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/transaction/5463cee5e4b042e3e26f1e41

Sample Success Response

{ 
  "transactionId": "5463cee5e4b042e3e26f1e41",
  "ownershipId": "55653202e4b0a70b13a4562d", 
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "developerId": "123",
  "customData": 
  { 
    "department": "billing", 
  }, 
  "date": 1432695338702, 
  "type": "payment", 
  "amount": 1000,
  "feeAmount": 0,
  "marketplaceAmount": 200,
  "developerAmount": 800
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This transaction was not found"
    }
 ]
}

Update Transaction

Updates a transaction.

Parameters

transactionId
string
The id of the transaction to be removed
customData
CustomData
A custom JSON object to attach to this ownership record

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The transaction was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/transactions/{transactionId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/transaction/5463cee5e4b042e3e26f1e41 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'customData': {'department': 'billing'}" \
     "}"

Sample Success Response

{ 
  "transactionId": "5463cee5e4b042e3e26f1e41",
  "ownershipId": "55653202e4b0a70b13a4562d", 
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "developerId": "123",
  "customData": 
  { 
    "department": "billing", 
  }, 
  "date": 1432695338702, 
  "type": "payment", 
  "amount": 1000,
  "feeAmount": 0,
  "marketplaceAmount": 200,
  "developerAmount": 800
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This transaction was not found"
    }
 ]
}

Delete Transaction

Deletes a transaction.

Parameters

transactionId
string
The id of the transaction to be removed

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The transaction was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

DELETE https://market.openchannel.io/v2/transactions/{transactionId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/transaction/5463cee5e4b042e3e26f1e41 \
-X DELETE

Sample Success Response

{}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "This transaction was not found"
    }
 ]
}

Custom Gateway

The Custom Gateway API along with webhooks allow a custom payment processing or billing system to be integrated with your OpenChannel marketplace. Payments must be enabled and ‘Custom’ must be selected as the gateway in order to use these API endpoints.

Add Payment

Adding a payment allows users and developers to track payments for apps. This is useful when integrating a custom payment processor or billing system.

Parameters

ownershipId
string
The id of the ownership record involved in this transaction
amount
integer
The total amount paid in cents
date (optional)
long
The date (in milliseconds) of when this payment was made
feeAmount (optional)
integer
The fee (in cents) paid to a payment processors or third parties to process this payment. Default is 0.
marketplaceAmount (optional)
integer
The amount (in cents) paid to the marketplace owner as a commission for the purchase of this app. Defaults based on the commission amount configured for this marketplace.
developerAmount (optional)
integer
The amount (in cents) paid to the owner of the app. Defaults based on the commission amount configured for this marketplace.
customData (optional)
CustomData
A custom JSON object to attach to this transaction

Returns

Transaction
The newly created transaction

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
412
Precondition Failed
Payments must be enabled and ‘Custom’ must be selected as the gateway in order to use this API endpoint

 

Definition

POST https://market.openchannel.io/v2/custom-gateway/payment/{ownershipId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/custom-gateway/payment/55653202e4b0a70b13a4562d \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'amount':1000," \
        "'customData': {'department': 'billing'}" \
     "}"

Sample Success Response

{ 
  "transactionId": "5463cee5e4b042e3e26f1e41",
  "ownershipId": "55653202e4b0a70b13a4562d", 
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "developerId": "123",
  "customData": 
  { 
    "department": "billing", 
  }, 
  "date": 1432695338702, 
  "type": "payment", 
  "amount": 1000,
  "feeAmount": 0,
  "marketplaceAmount": 200,
  "developerAmount": 800
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "amount",
      "message": "Must be a valid number"
    }
  ]
}

Add Refund

Adding a refund allows users and developers to track refunds for apps. This is useful when integrating a custom payment processor or billing system.

Parameters

ownershipId
string
The id of the ownership record involved in this transaction
amount
integer
The total amount recovered in cents
date (optional)
long
The date (in milliseconds) of when this refund was made
feeAmount (optional)
integer
The fee (in cents) recovered from a payment processors or third party. Default is 0.
marketplaceAmount (optional)
integer
The amount (in cents) recovered from the marketplace owner as a commission for the purchase of this app. Defaults based on the commission amount configured for this marketplace.
developerAmount (optional)
integer
The amount (in cents) recovered from the owner of the app. Defaults based on the commission amount configured for this marketplace.
customData (optional)
CustomData
A custom JSON object to attach to this transaction

Returns

Transaction
The newly created transaction

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method
412
Precondition Failed
Payments must be enabled and ‘Custom’ must be selected as the gateway in order to use this API endpoint

Definition

POST https://market.openchannel.io/v2/custom-gateway/refund/{ownershipId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/custom-gateway/refund/55653202e4b0a70b13a4562d \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'amount':1000," \
        "'customData': {'department': 'billing'}" \
     "}"

Sample Success Response

{ 
  "transactionId": "5463cee5e4b042e3e26f1e41",
  "ownershipId": "55653202e4b0a70b13a4562d", 
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "developerId": "123",
  "customData": 
  { 
    "department": "billing", 
  }, 
  "date": 1432695338702, 
  "type": "payment", 
  "amount": 1000,
  "feeAmount": 0,
  "marketplaceAmount": 200,
  "developerAmount": 800
}

Sample Failure Response

{
  "code": 400,
  "errors":
  [
    {
      "field": "amount",
      "message": "Must be a valid number"
    }
 ]
}

Stripe Gateway

The Stripe Gateway API allows marketplace payments to be processed and distributed automatically using Stripe.

Marketplace payment processing using Stripe is the quickest and easiest method of implementing payments for your marketplace.

OpenChannel’s Stripe integration manages user credit cards and payment processing, automatically deposits the the commission into your Stripe account and deposits the remaining balance into the developer’s Stripe account.

In order to user Stripe payment processing:

  1. You are required to setup and configure a Stripe account for your marketplace
  2. Developers are required to setup and configure a Stripe account
  3. Both yourself and Developers must be from a country that is supported by Stripe (see supported countries)

Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use these API endpoints.

Get Stripe Settings

Retrieving Stripe settings returns the Stripe settings configured for this marketplace.

Returns

Stripe Settings
Stripe settings configured for this marketplace

Errors

404
Not Found
Stripe settings have not been setup for this marketplace
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/stripe-gateway/settings

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/settings

Sample Success Response

{
  "clientId": "ca_JFSl5d75f444gFDddlRanjuyGG4455d",
  "publishableKey": "pk_live_8hTo798fg89SGdfg78dfg87"
}

Sample Failure Response

{
  "code": 404,
  "errors":
  [
    {
      "message": "Stripe settings have not been setup for this marketplace"
    }
 ]
}

Get Credit Cards

Retrieving credit cards returns a list of credit cards configured for this user.

Parameters

userId
string
The unique id of the user retrieving their credit card details

Returns

Cards
The credit cards associated with this user’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/stripe-gateway/user/{userId}/cards

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/user/abc/cards

Sample Success Response

{
  "userId": "abc",
  "cards": 
  [
    { 
      "cardId": "5463cee5e4b042e3e26f1e41",
      "isDefault": true, 
      "exp_year": 21,
      "exp_month": 11,
      "last4": "8702", 
      "brand": "visa", 
      "name": "John Smith"
    }
  ]
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
 ]
}

Add Credit Card

Posting an credit card allows users to purchase apps without the need to repeatedly enter credit card details. This is useful when implementing payments for the marketplace and requires the use of the Stripe.js library.

Parameters

userId
string
The id of the user adding their credit card
token
string
The Stripe token returned by the Stripe.js Stripe.card.createToken call
isDefault (optional)
boolean
Set to true if this should be set to be the default credit card

Returns

Cards
The credit cards associated with this user’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/stripe-gateway/user/{userId}/cards

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/user/abc/cards \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'token': '55DfDR65tre322ae4b0a70bgf13DFa4563b'," \
        "'isDefault': true" \
     "}"

Sample Success Response

{
  "userId": "abc",
  "cards": 
  [
    { 
      "cardId": "5463cee5e4b042e3e26f1e41",
      "isDefault": true, 
      "exp_year": 21,
      "exp_month": 11,
      "last4": "8702", 
      "brand": "visa", 
      "name": "John Smith"
    }
  ]
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
 ]
}

Update Credit Card

Updating an credit card allows users to modify a configured credit card.

Parameters

userId
string
The id of the user updating their credit card
cardId
string
The id of the card to be updated
isDefault (optional)
boolean
Set to true if this should be set to be the default credit card
address_city (optional)
string
The card holder’s city
address_country (optional)
string
The card holder’s country
address_line1 (optional)
string
The card holder’s street address
address_line2 (optional)
string
The card holder’s street address
address_state (optional)
string
The card holder’s city state/province
address_zip (optional)
string
The card holder’s zip/postal code

Returns

Cards
The credit cards associated with this user’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/stripe-gateway/user/{userId}/cards/{cardId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/user/abc/cards/5463cee5e4b042e3e26f1e41 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'address_zip': '90210'," \
        "'isDefault': true" \
     "}"

Sample Success Response

{
  "userId": "abc",
  "cards": 
  [
    { 
      "cardId": "5463cee5e4b042e3e26f1e41",
      "isDefault": true, 
      "exp_year": 21,
      "exp_month": 11,
      "last4": "8702", 
      "brand": "visa", 
      "name": "John Smith"
    }
  ]
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
 ]
}

Delete Credit Card

Deleting a credit card allows users to remove a configured credit card from their account.

Parameters

userId
string
The id of the user removing their credit card
cardId
string
The id of the card to be removed

Returns

Cards
The credit cards associated with this user’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

DELETE https://market.openchannel.io/v2/stripe-gateway/user/{userId}/cards/{cardId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/user/abc/cards/5463cee5e4b042e3e26f1e41 \
  -X DELETE

Sample Success Response

{
  "userId": "abc",
  "cards": []
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
  ]
}

Connect Developer Account

Generates a temporary URL to help a developer connect their Stripe deposit account. The developer will be temporarily directed to approve the connection of their Stripe account before being redirected back to your marketplace.

Parameters

developerId
string
The id of the developer connecting their Stripe account
redirectUrl
string
The URL to redirect this developer after they have connected their Stripe account

Returns

Developer Token
A target URL that this developer can use to connect their Stripe account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

POST https://market.openchannel.io/v2/stripe-gateway/developer/{developerId}/accounts

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/developer/123/accounts \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'redirectUrl': 'https://my-market.com/land-here'" \
     "}"

Sample Success Response

{ 
  "developerId": "123",
  "expires": 1432695338702, 
  "targetUrl": "https://connect.stripe.com/oauth/authorize?response_type=code&client_id=clientId&scope=read_write&state=token"
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
  ]
}

Get Developer Accounts

Retrieving developer accounts returns a list of connected Stripe accounts for this developer.

Parameters

developerId
string
The unique id of the developer retrieving their account details

Returns

Accounts
The connected Stripe accounts associated with this developer’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/stripe-gateway/developer/{developerId}/accounts

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/developer/123/accounts

Sample Success Response

{
  "developerId": "123",
  "accounts":
  [
    { 
      "stripeId": "acct_15462cee5e4b942e",
      "accountName": "my account",
      "country": "US",
      "defaultCurrency": "usd"
    }
  ]
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
  ]
}

Disconnect Developer Account

Deleting an account allows a developer to disconnect their Stripe deposit account.

Parameters

developerId
string
The id of the developer disconnecting their Stripe account
stripeId
string
The id of the Stripe account to disconnect

Returns

Accounts
The connected Stripe accounts associated with this developer’s account

Errors

400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

DELETE https://market.openchannel.io/v2/stripe-gateway/developer/{developerId}/accounts/{stripeId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/stripe-gateway/developer/123/accounts/acct_15462cee5e4b942e \
  -X DELETE

Sample Success Response

{
  "developerId": "123",
  "accounts":[]
}

Sample Failure Response

{
  "code": 412,
  "errors":
  [
    {
      "message": "Payments must be enabled and 'Stripe' must be selected as the gateway in order to use this API endpoint"
    }
  ]
}

Apps

Each app is a JSON representation of an application submitted by a developer. The structure of an app can be customized using the customData object. When creating or updating an app, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your app. The OpenChannel platform will automatically detect and handle your custom app structure.

App Version Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(App Version)
An array of app versions for the current page

Sample App Version Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "appId": "5565322ae4b0a70b13a4563b", 
      "name": "my first app",
      ...
    },
    {...},
    {...}
  ]
}

App Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(App)
An array of apps for the current page

Sample App Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "appId": "5565322ae4b0a70b13a4563b", 
      "name": "my first app",
      ...
    },
    {...},
    {...}
  ]
}

App Version

Attributes

appId
int
The id of this app
name
string
The name of this app
safeName
array(string)
URL safe aliases that can be used to identify this app even after name changes. The current alias is always at position 0.
status
Status
The current status of this app
parent (optional)
Parent
The attributes of the parent (live) app
developerId
string
The id of the developer that owns this app
groupId (optional)
string
The id of the group of developer’s that own this app
model
array(Model)
The models that describes the cost and pricing for this app
lastUpdated
long
The date (in milliseconds) that this app was last modified
created
long
The date (in milliseconds) that this app was created
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
allow (optional)
Restrictions
Whitelists that restrict users from accessing this app
restrict (optional)
Restrictions
Blacklists that restrict users from accessing this app
version
integer
The version number representing changes to this app’s metadata. The app.version field helps OpenChannel keep track of the app’s metadata changes and is not actually representative of the version of the app itself. For keeping track of the app’s version we recommend creating a custom field in customData.
attributes (optional)
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
attributes (optional)
array(string)
A custom defined list of access requirements
isLive (optional)
boolean
True if this is the live version of this app
isLatestVersion (optional)
boolean
True if this is the latest version of this app
isDeleted (optional)
boolean
True if this has been deleted

Sample App Version

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "access": 
  [
    "billing - readonly"
  ], 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "parent":
  {
    "status": 
    { 
      "value": "approved", 
      "lastUpdated": 1432696823474, 
      "modifiedBy": "administrator", 
      "reason": "" 
    } 
  },
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  }, 
  "isLive": true,
  "isLatestVersion": true
}

App

Attributes

appId
int
The id of this app
name
string
The name of this app
safeName
array(string)
URL safe aliases that can be used to identify this app even after name changes. The current alias is always at position 0.
status
Status
The current status of this app
developerId
string
The id of the developer that owns this app
groupId (optional)
string
The id of the group of developer’s that own this app
model
array(Model)
The models that describes the cost and pricing for this app
lastUpdated
long
The date (in milliseconds) that this app was last modified
created
long
The date (in milliseconds) that this app was created
submittedDate
long
The date (in milliseconds) that this app was submitted for approval
rating
integer
The average review rating for this app. Reviews are rated from 100 (one star) to 500 (five star)
ownership (optional)
Ownership
If this app is owned by the requesting user, this field displays the ownership information for this app. This field exists only when userId is supplied to the method and the user owns (or previously owned) the app and cannot be part of query or sort criteria.
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
allow (optional)
Restrictions
Whitelists that restrict users from accessing this app
restrict (optional)
Restrictions
Blacklists that restrict users from accessing this app
version
integer
The version number representing changes to this app’s metadata. The app.version field helps OpenChannel keep track of the app’s metadata changes and is not actually representative of the version of the app itself. For keeping track of the app’s version we recommend creating a custom field in customData.
attributes (optional)
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
access (optional)
array(string)
A custom defined list of access requirements
randomize
integer
A random number that changes periodically and is used for achieving a random sort order when displaying apps
statistics
JSON Object
A field containing summary stats about the app and is specially designed to allow apps to be sorted by popularity. Each tracked statistic like views, downloads or custom statistics are available from within the statistics field by the following values:

  • 30Day refers to the popularity over a 30 day period. Sorting using a 30 day value is most useful with highly trafficked marketplaces.
  • 90Day refers to the popularity over a 90 day period. Sorting using a 90 day value is most useful when starting out or operating marketplaces with lower traffic volumes.
  • Total refers to the popularity over the life of the app. The total value is not recommended for sorting but could be useful when evaluating the overall popularity of an app.

NOTE: Stats with 0 totals may not be returned.

isDeleted (optional)
boolean
True if this has been deleted

Sample App

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
    "images": 
    [ 
      "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
      "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
    ], 
    "categories": 
    [ 
      "Hot Water", 
      "Smart Pump" 
    ], 
    "author": "Andrea" 
  }, 
  "lastUpdated": 1432695338702, 
  "version": 1, 
  "name": "Hot Water Assist",
  "safeName": ["hot-water-assist"],
  "developerId": "30", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  "access": 
  [
    "billing - readonly"
  ], 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {}, 
  "submittedDate": 1432695339005, 
  "created": 1432695338702, 
  "attributes": {}, 
  "rating": 400, 
  "randomize": 164825247,
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  },
  "statistics":
  {
    "views":{"30day":0,"90day":0,"total":0},
    "downloads":{"30day":0,"90day":0,"total":0},
    "developerSales":{"30day":0,"90day":0,"total":0},
    "totalSales":{"30day":0,"90day":0,"total":0},
    "ownerships":{"30day":0,"90day":0,"total":0},
    "reviews":{"30day":0,"90day":0,"total":0}
  },
  "isLive": true }

Status

Attributes

value
string
The current status. Can be: “pending” or “inReview” or “inDevelopment” or “approved” or “suspended” or “rejected”

  • InDevelopment apps are drafts that have not yet been submitted to the marketplace for approval
  • Pending apps are changes that have been submitted by developers for approval and are not visible to marketplace users
  • InReview apps are locked from additional changes and are currently being reviewed by marketplace administrators
  • Approved apps are changes that have been approved by marketplace administrators and are visible to marketplace users
  • Suspended apps were once approved but is now no longer visible to marketplace users
  • Rejected apps are changes that were rejected by marketplace administrators and are not visible to marketplace users
reason (optional)
string
Text describing the reason for the current status
lastUpdated
integer
The date (in milliseconds) of the latest update
modifiedBy
string
The person responsible for making the latest change to the status. Can be: “administrator” or “developer” or “system”

  • Administrator changes have been made by marketplace administrators
  • Developer changes have been made by a developer that owns this app
  • System changes have been made automatically by the system

Sample App Status

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  }, 
  ...
}

Model

Attributes

modelId
string
The id that uniquely identifies this model
type
string
The pricing model type. Free has no cost, single has a one time purchase cost and recurring requires a monthly subscription. Can be: “free” or “single” or “recurring”. The default value is “free”.

  • Free models don’t require payment to be installed
  • Single models require one-time payment in order to be installed
  • Recurring models require a recurring subscription payment in order to be installed and retain ownership
price
integer
The price of this app in cents.  The default value is 0.
license
string
The license model type. Single allows a purchase to only apply to one owner while Group allows a purchase for an entire group. Can be: “single” or “group”.  The default value is “single”.

  • Single licenses only apply to only a single user that installed the app
  • Group licenses apply to all users that share the installing user’s groupId
customData (optional)
CustomData
A custom JSON object that is attached to this model
trial
integer
The maximum number of free trial days available.  The default value is 0.
currency
string
The ISO 4217 currency code for this price.  The default value is “USD”.
commission
integer
The marketplace commission percentage applied to this app’s model. The default is the marketplace’s configured commission percentage. The value includes two additional digits to represent fractions of a percent. Example: A value of 3050 is 30.5%.
feePayer
string
The payee that will be paying for any payment processing fees. Can be: “developer” or “marketplace”. The default value is “marketplace”.

  • Developer will be responsible for paying payment processing fees from their payout
  • Marketplace will be responsible for paying payment processing fees from their payout
billingPeriod
string
The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. Can be: ‘daily’, ‘weekly’ , ‘monthly’ or ‘annually’. The default value is ‘monthly’ for recurring models.

  • Daily app subscriptions require payment after a certain number of days (specified by billingPeriodUnit ) in order to maintain the subscription
  • Weekly app subscriptions require payment after a certain number of weeks (specified by billingPeriodUnit ) in order to maintain the subscription
  • Monthly app subscriptions require payment after a certain number of months (specified by billingPeriodUnit ) in order to maintain the subscription
  • Annually app subscriptions require payment after a certain number of years (specified by billingPeriodUnit ) in order to maintain the subscription
billingPeriodUnit
type
The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. The default value is 1 for recurring models.

Sample App Model

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "model": 
  [ 
    { 
      "type": "free", 
      "price": 0, 
      "trial": 0, 
      "license": "single", 
      "modelId": "1", 
      "currency": "USD" 
    } 
  ], 
  ... 
}

Parent

Attributes

status
Status
The status of the parent (live) app.

Sample App Parent

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "parent":
  {
    "status": 
    { 
      "value": "approved", 
      "lastUpdated": 1432696823474, 
      "modifiedBy": "administrator", 
      "reason": "" 
    }
  },
  ...
}

Restrictions

Attributes

own (optional)
JSON Object
A JSON object describing the restriction to owning this app
view (optional)
JSON Object
A JSON object describing the restriction to viewing this app

Sample Blacklist

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "restrict": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  "allow": {},
  ...
}

This restriction states that all users with the customData field ‘country’ equal to ‘Canada’ or ‘Mexico’ will NOT be able to view or own this app.

Sample Whitelist

{ 
  "appId": "5565322ae4b0a70b13a4563b", 
  "restrict": {},
  "allow": 
  {
    "own":
    {
      "country":["Canada","Mexico"]
    },
    "view":
    {
      "country":["Canada","Mexico"]
    }
  }, 
  ...
}

This restriction states that ONLY users with the customData field ‘country’ equal to ‘Canada’ or ‘Mexico’ will be able to view or own this app.

App Field Update

Attributes

field
string
The field to be updated
value
any
The new value for this field

Sample App Field Update

{ 
  "field": "customData.agreement", 
  "value": {'signed': true, 'ip': '10.0.0.1'}
}

User

Each user is a JSON representation of an active, authenticated user that can be uniquely identified by a userId.

The structure of an user can be customized using the customData object. When creating or updating a user, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your user. The OpenChannel platform will automatically detect and handle your custom user structure.

Attributes

userId
string
The unique id of the user
created
long
The date in milliseconds when this user was created
username (optional)
string
The username of this user
name (optional)
string
The name of this user
email (optional)
string
This user’s email address
customData (optional)
CustomData
A custom JSON object that you can create and attach to this user record

Sample User

{ 
  "userId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

User Group

Each user group is a JSON representation of a valid group of users (like an organization or a company) identified by a groupId.

The structure of an user group can be customized using the customData object. When creating or updating a user group, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your user group. The OpenChannel platform will automatically detect and handle your custom user group structure.

Attributes

groupId
string
The unique id of the group
email
string
The contact email address for the group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this user record

Sample User Group

{ 
  "groupId": "abc", 
  "email": "me@me.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

User Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(User)
An array of users for the current page

Sample User Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "userId": "5565322ae4b0a70b13a4563b", 
      "name": "Brian",
      ...
    },
    {...},
    {...}
  ]
}

Developer

Each developer is a JSON representation of an active, authenticated developer that can be uniquely identified by a developerId.

The structure of an developer can be customized using the customData object. When creating or updating a developer, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your developer. The OpenChannel platform will automatically detect and handle your custom developer structure.

Attributes

developerId
string
The unique id of the developer
username (optional)
string
The username of this developer
name (optional)
string
The name of this developer
email (optional)
string
This developer’s email address
groupId (optional)
string
This developer’s group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this developer record
created
long
The date (in milliseconds) that this developer was created

Sample Developer

{ 
  "developerId": "123", 
  "name": "Brian",
  "email": "brian@mycompany.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }, 
  "created": 1432695338702
}

Developer Group

Each developer group is a JSON representation of a valid group of developers (like an organization or a company) identified by a groupId.

The structure of an developer group can be customized using the customData object. When creating or updating a developer group, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your developer group. The OpenChannel platform will automatically detect and handle your custom developer group structure.

Attributes

groupId
string
The unique id of the group
email
string
The contact email address for the group
customData (optional)
CustomData
A custom JSON object that you can create and attach to this user record

Sample Developer Group

{ 
  "groupId": "abc", 
  "email": "me@me.com",
  "customData": 
  { 
    "companyName": "Automatic",
    "interests": ["Surfing", "Kittens"]
  }
}

Developer Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(Developer)
An array of developers for the current page

Sample Developer Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "developerId": "5565322ae4b0a70b13a4563b", 
      "name": "Brian",
      ...
    },
    {...},
    {...}
  ]
}

Statistics

Statistics can be recorded and queried to build charts for developers. Custom statistics can be added to the statistics engine by recording statistics with a custom field identifier.

Total

Attributes

start
long
The time (in milliseconds) to start the sum
end
long
The time (in milliseconds) to end the sum
totals
JSON Object
A JSON object containing the fields as keys and results as values
apps
JSON Object
A JSON object containing the appIds of the participating apps as keys and Totals as values

Sample Total

{
  "apps": {
    "551569dde4b09c3f7fe5461f": {
      "views": 12,
      "downloads": 1
    },
    "56ddebd81707a5648b8c5193": {
      "views": 4785,
      "downloads": 374
    }
  },
  "totals": {
    "views": 4797,
    "downloads": 375
  }
}

Files

Files can be uploaded from the API and are automatically distributed through a global content delivery network.

File

Attributes

fieldId
string
The id of this file
name
string
The name of this file
size
integer
The size of this file
contentType (optional)
string
The internet media type of this file
isPrivate (optional)
boolean
If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.
hash (optional)
Hash
The hashes requested for the file.
uploadDate
long
The date (in milliseconds) when this file was uploaded
fileUrl (optional)
string
The URL for this file. The fileUrl is not returned for private files since they require an additional API call in order to get a signed URL.

Sample File

{
  "uploadDate": 1457710762784,
  "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
  "name": "book.csv", 
  "contentType": "application/octet-stream", 
  "size": 16206, 
  "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
}

File Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(File)
An array of apps for the current page

Sample File Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
        "uploadDate": 1457710762784,
        "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
        "name": "book.csv", 
        "contentType": "application/octet-stream", 
        "size": 16206, 
        "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv" 
    },
    {...},
    {...}
  ]
}

Hash

Attributes

MD5
string
The MD5 hash for this uploaded file.
SHA-1
string
The SHA-1 hash for this uploaded file.
SHA-256
string
The SHA-256 hash for this uploaded file.

Sample Hash

{
  "SHA-256": "D87B252470F05A9904E80A868897CA08CA0CB8F85037ADEE86AA0F0C0A3BC9AA" 
}

Ownership

Each ownership is a JSON representation of the ownership relationship between a user and an app.

Ownership

Attributes

ownershipId
string
The id of this ownership
date
long
The date (in milliseconds) of when this app was owned
appId
string
The id of the app that is owned
userId
string
The id of the user that owns this app
developerId
string
The id of the developer for this app
groupId (optional)
string
The id of the group that owns this app
ownershipType
string
The current ownership type for this app. Can be: “full”, “subscription” or “trial”

  • Full ownership is a perpetual license that doesn’t require any additional payment
  • Subscription ownership requires payment on a recurring bases to maintain this ownership license
  • Trial ownership is a temporary, free license that eventually expires
ownershipStatus
string
The current ownership status for this app. Can be: “pending”, “active”, “uninstalled” or “cancelled”

  • Pending status signifies that the license is not yet valid and the app is not yet installed
  • Active status signifies that the license is valid and the app is installed
  • Uninstalled status signifies that the license is no longer valid and the user has uninstalled the app. Apps with a Free or Single model may be re-installed without cost
  • Cancelled signifies that the license is no longer valid and the user must re-purchase a license to re-install the app
uninstallDate (optional)
long
The date (in milliseconds) of when this app was uninstalled
expires (optional)
long
The date (in milliseconds) of when this app ownership expires
model
Model
The model for this ownership
customData (optional)
CustomData
A custom JSON object to attach to this ownership record

Sample Ownership

{
  "ownershipId": "5463cee5e4b042e3e26f1e41",
  "date": 1427466717262,
  "appId": "5565322ae4b0a70b13a4563b",
  "userId": "abc",
  "developerId": "123",
  "ownershipType": "full",
  "ownershipStatus": "active",
  "model":
  { 
    "type": "free", 
    "price": 0, 
    "trial": 0, 
    "license": "single", 
    "modelId": "1", 
    "currency": "USD" 
  }
}

Ownership Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(Ownership)
An array of ownership for the current page

Sample Ownership Page

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "ownershipId": "5565322ae4b0a70b13a4563b", 
      "date": 1427466717262,
      ...
    },
    {...},
    {...}
  ]
}

Reviews

Each review is a JSON representation of an app review submitted by a user.

The structure of an review can be customized using the customData object. When creating or updating a review, the customData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your review. The OpenChannel platform will automatically detect and handle your custom review structure.

Review Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(Review)
An array of reviews for the current page

Sample Review Pages

{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "reviewId": "5463cee5e4b042e3e26f1e41", 
      "rating": 400, 
      ...
    },
    {...},
    {...}
  ]
}

Review

Attributes

reviewId
string
The id of this review
headline
string
The review’s headline. Limited to 50 characters.
description
string
The review’s description. Limited to 2000 characters.
rating
integer
The rating given within this review. The rating is represented as an integer between 100 and 500 (1 – 5 stars)
status
Review Status
The status of this Review
reportDate
long
The date (in milliseconds) this Review was posted
appId
string
The Id of the App that owns this review
appName
string
The name of the App that owns this review
userId
string
The id of the User that posted this review
customData (optional)
CustomData
A custom JSON object that you can create and attach to this review record
isDeleted (optional)
boolean
True if this has been deleted
user (optional)
User
The details of the user that posted this review

Sample Review

{ 
  "reviewId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "appName": "My App", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg"
  }, 
  "reportDate": 1432695338702, 
  "rating": 400, 
  "headline": "Great App!",
  "description": "It works great and looks good too.",
  "status": 
  { 
    "value": "approved",
    "reason": "" 
  }
}

Review Status

Attributes

value
string
The current status value. Can be: ‘pending’, ‘spam’, ‘flagged’ or ‘approved’

  • Pending reviews have been submitted to the marketplace but are not yet visible to users
  • Approved reviews have been approved by a marketplace administrator and can be viewed by users
  • Flagged reviews have been identified by the system as possibly being spam or containing profanity
  • Spam reviews have been marked as spam by marketplace administrators
reason (optional)
string
Text describing the reason for the current status

Sample Review

{ 
  "value": "approved",
  "reason": "", 
}

CustomData

All apps, reviews, users and developers have a customData field that you can use to attach a custom JSON object. The purpose of these fields is to allow for maximum customizability and flexibility of objects. However, there are the following restrictions:

  • Field names cannot contain dots (.) or null characters
  • Field names cannot start with a dollar sign ($)
  • Field names cannot exceed 50 characters
  • The entire customData object cannot exceed 8 megabytes
  • The customData object cannot exceed 50 levels of nested objects

Sample CustomData

{
  "customData": 
  { 
    "summary": "Automatically set on/off timers...", 
    "description": "HPWHs use electricity to move heat...", 
    "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg",
    "categories": 
    [ 
      "movies", 
      "books", 
      "music" 
    ] 
  },
 ... 
}

Stripe Gateway

Stripe Gateway objects hold account and credit card details for users and developers.

Stripe Settings

Attributes

clientId
string
The clientId of the Stripe connected Stripe account for this marketplace
publishableKey
string
The publishableKey of the Stripe connected Stripe account for this marketplace

Sample Stripe Settings

{ 
  "clientId": "ca_JFSl5d75f444gFDddlRanjuyGG4455d",
  "publishableKey": "pk_live_8hTo798fg89SGdfg78dfg87"
}

Cards

Attributes

userId
string
The id of the user that owns these cards
cards
array(Card)
An array of credit cards for this user’s account

Sample Cards

{
  "userId": "abc",
  "cards": 
  [
    { 
      "cardId": "5463cee5e4b042e3e26f1e41",
      "isDefault": true, 
      "exp_year": 21,
      "exp_month": 11,
      "last4": "8702", 
      "brand": "visa", 
      "name": "John Smith"
    }
  ]
}

Card

Attributes

cardId
string
The id for this credit card
isDefault
boolean
True if this is the default credit card
exp_year
integer
The four digit expiration year
exp_month
integer
The two digit expiration month
last4
string
The last 4 digits of the credit card number
brand
string
The brand of the credit card. Example: Visa
name
string
The card holder’s full name
address_city (optional)
string
The card holder’s city
address_country (optional)
string
The card holder’s country
address_line1 (optional)
string
The card holder’s street address
address_line2 (optional)
string
The card holder’s street address
address_state (optional)
string
The card holder’s city state/province
address_zip (optional)
string
The card holder’s zip/postal code

Sample Card

{ 
  "cardId": "5463cee5e4b042e3e26f1e41",
  "isDefault": true, 
  "exp_year": 21,
  "exp_month": 11,
  "last4": "8702", 
  "brand": "visa", 
  "name": "John Smith"
}

DeveloperToken

Attributes

developerId
string
The id of the developer connecting their Stripe account
expires
long
The time (in milliseconds) when this URL expires
targetUrl
string
The URL that this developer can use to connect their Stripe account

Sample DeveloperToken

{ 
  "developerId": "123",
  "expires": 1432695338702, 
  "targetUrl": "https://connect.stripe.com/oauth/authorize?response_type=code&client_id=clientId&scope=read_write&state=token"
}

Account

Attributes

stripeId
string
The id of the Stripe account
accountName
string
The name of the Stripe account
country
string
The country for this Stripe account
defaultCurrency
string
The default currency for this Stripe account

Sample Account

{ 
  "stripeId": "acct_15463cee5e4b042e",
  "accountName": "my account",
  "country": "US",
  "defaultCurrency": "usd"
}

Accounts

Attributes

developerId
string
The id of the developer
accounts
array(Account)
An array of connected Stripe accounts

Sample Accounts

{
  "developerId": "123",
  "accounts":
  [
    { 
      "stripeId": "acct_15463cee5e4b042e",
      "accountName": "my account",
      "country": "US",
      "defaultCurrency": "usd"
    }
  ]
}

Event

Each event is a JSON representation of an event that has occurred and can contain different content based on the event type. Events are POSTed to the endpoint URL that you specify in your marketplace settings.

Attributes

eventId
string
The id of the this event
createdDate
long
The date (in millis) of when this event occurred
message
string
A description of the event
eventType
string
The event type. See Webhooks.
marketplaceId
string
The id of the marketplace that produced this event
developer (optional)
Developer
The developer associated with this event. This value is only provided for “developer.paymentDetailsRequired” events.
app (optional)
App
The app associated with this event. This value is only provided for “app.submitted”, “app.approved”, “app.suspended”, “app.unsuspended”, “app.rejected”, “app.inReview” events.
review (optional)
Review
The review associated with this event. This value is only provided for “review.created”, “review.updated”, “review.approved”, “review.spam”, “review.removed” events.
user (optional)
User
The user associated with this event. This value is only provided for “user.invalidPaymentDetails”, “user.paymentDetailsRequired” events.
ownership (optional)
Ownership
The ownership associated with this event. This value is only provided for “app.installed”, “app.uninstalled”, “payment.required”, “ownership.expired” events.
payment (optional)
Payment
The payment associated with this event. This value is only provided for “payment.complete”, “payment.refunded” events.
permission (optional)
Permission
The permission associated with this event. This value is only provided for “permission.added”, “permission.removed” events.

Sample Event

{ 
  "eventId": "5463cee5e4b042e3e26f1e41",
  "createdDate": 1427466717262,
  "message": "An app draft has been submitted by a developer.",
  "eventType": "app.submitted",
  "marketplaceId": "5565322ae4b0a70b13a4563b",
  "app": { 
    "appId": "5565322ae4b0a70b13a4563b", 
    "customData": 
    { 
      "summary": "Automatically set on/off timers...", 
      "description": "HPWHs use electricity to move heat...", 
      "video": "https://www.youtube.com/watch?v=i73n-LTXPIM", 
      "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg", 
      "images": 
      [ 
        "https://s3.amazonaws.com/cloudexchange-uat/55653218e4b0a70b13a45633.jpg", 
        "https://s3.amazonaws.com/cloudexchange-uat/55653215e4b0a70b13a45631.jpg"
      ], 
      "categories": 
      [ 
        "Hot Water", 
        "Smart Pump" 
      ], 
      "author": "Andrea" 
    }, 
    "lastUpdated": 1432695338702, 
    "version": 1, 
    "name": "Hot Water Assist",
    "developerId": "30", 
    ...
  }
}

Market

Attributes

marketplaceId
string
The id of this marketplace
attributes
array(Attribute)
The different app attributes supported by this marketplace
viewAppUrl
string
The URL template for viewing apps on this marketplace
previewAppUrl
string
The URL template for previewing apps on this marketplace

Sample Market

{ 
  "marketplaceId": "551ec66be4b0ad30c5437e70",
  "name": "demo1",
  "attributes": [
    {
      "name": "My Test Attribute",
      "type": "select",
      "values": "val 1,val 2,val 3"
    }
  ],
  "minPrice": 99,
  "maxPrice": 99999,
  "currency": "USD",
  "viewAppUrl": "https://market.my-site.com/apps/{appId}",
  "previewAppUrl": "https://market.my-site.com/apps/{appId}/{version}"
}

 

Attribute

Attributes

name
string
The name of this attribute
type
string
The type of this attribute. This value can be: “select”, “text”, “multiselect”.
values
string
A comma separated list of values allowed for this attribute

Sample Attribute

{ 
  "name": "My Test Attribute",
  "type": "select",
  "values": "val 1,val 2,val 3"
}

Transactions

Each transaction is a JSON representation of a payment or refund associated with an app and performed on behalf of a user.

The structure of an transaction can be customized using the customData object. Transactions are created either manually or automatically using gateways.

Transaction

Attributes

transactionId
string
The id for this transaction
ownershipId
string
The id for the ownership associated with this transaction
appId
string
The id of the app involved with this transaction
developerId
string
The id of the developer involved with this transaction
userId
string
The id of the user making the transaction
date
long
The date (in millis) of when this transaction occurred
type
string
The type for this transaction. Can be: “payment” or “refund”

  • Payment transactions indicate that money was received to purchase an app
  • Refund transactions indicate that a payment was refunded for an app
amount
integer
The total amount paid in cents
customData (optional)
CustomData
A custom JSON object that you can create and attach to this transaction record
feeAmount (optional)
integer
The total amount paid to payment processing fees in cents
marketplaceAmount (optional)
integer
The total amount paid to the marketplace owner in cents
developerAmount (optional)
integer
The total amount paid to the developer in cents
isDeleted (optional)
boolean
True if this has been deleted

Sample Transaction

{ 
  "transactionId": "5463cee5e4b042e3e26f1e41",
  "ownershipId": "55653202e4b0a70b13a4562d", 
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "developerId": "123",
  "customData": 
  { 
    "department": "billing", 
  }, 
  "date": 1432695338702, 
  "type": "payment", 
  "amount": 1000,
  "feeAmount": 0,
  "marketplaceAmount": 200,
  "developerAmount": 800
}

Transaction Pages

Attributes

pages
integer
The total number of pages available for this result set
count
integer
The total number of results
pageNumber
integer
The current page number for this result set
list
array(Transaction)
An array of transactions for the current page

Sample Transaction Pages

{ 
  "count": 8, 
  "pages":1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "transactionId": "5463cee5e4b042e3e26f1e41", 
      "type": "payment", 
      ...
    },
    {...},
    {...}
  ]
}

Permission

Each permission is a JSON representation of permissions required by the app that must be accepted by the user.

The structure of an access array can contain custom strings that represent individual access requirements. 

Access

Attributes

appId
string
The id for the app associated with this permission
userId
string
The id of the user that has agreed this level of access
date
long
The date (in millis) of when permission was last given
access
array(string)
The access list outlining the access requirements
isValid
boolean
True if this access level is still valid. Will return false if the app’s access requirements change and permission must be granted again.

Sample Access

{ 
  "appId": "5463cee5e4b042e3e26f1e41",
  "userId": "abc",
  "access": 
  [ 
    "billing",
    "users",
  ], 
  "date": 1432695338702, 
  "isValid": true
}