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 from the API Credentials tab on the Settings page.

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.

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.

Quotes required for dot notation
Quotes around JSON field names are always required when using 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.

Quotes required for dot notation
Quotes around JSON field names are always required when using 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.

Quotes required for dot notation
Quotes around JSON field names are always required when using dot notation.

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

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. Events are POSTed to the endpoint URL that you specify in your marketplace settings.

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.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.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)
Model
A JSON object representing the pricing model type 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)
Model
A JSON object representing the pricing model type 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"
    }
 ]
}

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
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 developer payment details must be setup before this app can be listed
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.

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

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: "//s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg"
  },
 ... 
}

File Upload

Parameters

file
file
The multipart form data file stream

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 \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/file.jpg"

Sample Response

{
  uploadDate: 1457710762784,
  fileId: "56e2e6a91707a57c3f593499.csv",
  name: "book.csv",
  contentType: "application/octet-stream",
  size: 16206,
  fileUrl: "//s3.amazonaws.com/cloudexchange-uat/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

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 \
  -X POST \
  -d url="http://myurl.com/example.jpg"

Sample Response

{
  uploadDate": 1457711070540,
  fileId: "56e2e7dd1707a57c3f5934ba.jpg",
  name: "example.jpg",
  contentType: "image/jpeg",
  size: 206836,
  fileUrl: "//s3.amazonaws.com/cloudexchange-uat/56e2e7dd1707a57c3f5934ba.jpg"
}

Sample Failure Response

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

 

Get File

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

Parameters

field
string
The id 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/{fileId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/files/56e2e6a91707a57c3f593499.csv

Sample Response

{
  uploadDate: 1457710762784,
  fileId: "56e2e6a91707a57c3f593499.csv",
  name: "book.csv",
  contentType: "application/octet-stream",
  size: 16206,
  fileUrl: "//s3.amazonaws.com/cloudexchange-uat/56e2e6a91707a57c3f593499.csv"
}

Sample Failure Response

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

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"
    }
 ]
}

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"
    }
 ]
}

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/series/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”
field
string
The statistic type that you want to return. Some default statistics are: “reviews”, “users”, “developers”, “views”,  “totalSales”, “downloads”
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}/{field}

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
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.

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
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.

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"
    }
 ]
}

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"
    }
 ]
}

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

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",
  productKey: "3245-4235-6344-2356",
  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

appId
string
The id of the app
userId
string
The unique id of the user that owns this app

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",
  productKey: "3245-4235-6344-2356",
  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”.

Query must narrow results using at least one of the following fields: appId, developerId, userId, ownershipId, groupId

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

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",
      productKey: "3245-4235-6344-2356",
      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

Uninstalling an app will will remove ownership of this app for this user.

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

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/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: "uninstalled",
  productKey: "3245-4235-6344-2356",
  uninstallDate: 1427466892711
  model:
  { 
    type: "free", 
    price: 0, 
    trial: 0, 
    license: "single", 
    modelId: "1", 
    currency: "USD"
  }
}

Sample SuccessRequest

{}

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.
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",
  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",
  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.

Parameters

reviewId
string
The id of the review

Returns

Review
A single 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

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",
  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.

Query must narrow results using at least one of the following fields: appId, reviewId, userId

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
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",
      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 allow an app to access data on their behalf. Before an app is able to access API resources on behalf of a user, the user must first consent to the app’s access request.

Add Permissions

Indicates that this user consents to the data access 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/permissions/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/permissions/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 data access 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/permissions/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/permissions/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}",
  categoryGroups: [
    {
      name: "My Test Group",
      categories: [
        {
          name: "Cat 1",
          description: "This is sample 1"
        },
        {
          name: "Cat 2",
          description: "This is sample 2"
        },
        {
          name: "Cat 3",
          description: ""
        }
      ]
    }
  ]
}

 

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.

Query must narrow results using at least one of the following fields: appId, developerId, userId, ownershipId, transactionId

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

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.

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"
    }
 ]
}

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: "refund", 
  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 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",
      address_zip: "90210"
    }
  ]
}

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_15463cee5e4b042e",
      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_15463cee5e4b042e \
  -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

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.

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”
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”

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”
price
integer
The price of this app in cents
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”
customData (optional)
CustomData
A custom JSON object that is attached to this model
trial
integer
The maximum number of free trial days available
currency
string
The ISO 4217 currency code for this price
commission
integer
The marketplace commission percentage applied to this app’s model. The default is the marketplace’s configured commission percentage. The value is multiplied by 100 to include two digits for fractions of a percent. Example: 3000 is 30%.
billingPeriod
string
The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. Can be: ‘daily’, ‘weekly’ , ‘monthly’ or ‘annually’. The default is ‘monthly’ for recurring models.
billingPeriodUnit
type
The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. The default 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.

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
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"]
  }
}

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
}

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
  }
}

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
uploadDate
long
The date (in milliseconds) when this file was uploaded
fileUrl
string
The URL for this file

Sample File

{
  uploadDate: 1457710762784,
  fileId: "56e2e6a91707a57c3f593499.csv",
  name: "book.csv",
  contentType: "application/octet-stream",
  size: 16206,
  fileUrl: "//s3.amazonaws.com/cloudexchange-uat/56e2e6a91707a57c3f593499.csv"
}

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”
ownershipStatus
string
The current ownership status for this app. Can be: “active”, “uninstalled” or “cancelled”
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
productKey
string
A unique and secure key that represents the ownership of this app by this user
model
Model
The model for this ownership

Sample Ownership

{
  ownershipId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  ownershipType: "full",
  ownershipStatus: "active",
  productKey: "3245-4235-6344-2356",
  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
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

Sample Review

{ 
  reviewId: "5463cee5e4b042e3e26f1e41",
  appId: "5565322ae4b0a70b13a4563b", 
  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’
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.

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.owned”, “app.disowned”, “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", 
    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
  }
}

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
categoryGroups (optional)
array(CategoryGroup)
The category groups supported by 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}",
  "categoryGroups": [
    {
      "name": "My Test Group",
      "categories": [
        {
          "name": "Cat 1",
          "description": "This is sample 1"
        },
        {
          "name": "Cat 2",
          "description": "This is sample 2"
        },
        {
          "name": "Cat 3",
          "description": ""
        }
      ]
    }
  ]
}

 

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"
}

Category

Attributes

name
string
The name of this category
description
string
The description of this category

Sample Category

{ 
  "name": "Cat 1",
  "description": "This is sample 1"
}

 

CategoryGroup

Attributes

name
string
The name of this category group
categories
array(Category)
The categories supported by this category group

Sample CategoryGroup

{ 
  "name": "My Test Group",
  "categories": [
    {
      "name": "Cat 1",
      "description": "This is sample 1"
    },
    {
      "name": "Cat 2",
      "description": "This is sample 2"
    },
    {
      "name": "Cat 3",
      "description": ""
    }
  ]
}

 

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”
amount
integer
The total amount paid in cents
customData (optional)
CustomData
A custom JSON object that you can create and attach to this transactionrecord
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

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", 
      ...
    },
    {...},
    {...}
  ]
}