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 three 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 buy and launch apps
When performing requests, GET request parameters are always sent as 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. 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 selecting the API button in the left navigation menu.

Marketplace API Endpoint

https://market.openchannel.io/v2

Authentication

Authenticate your account when making calls to the Marketplace API by using basic authentication and providing your marketplaceId and secret as the username and password. You can get your marketplaceId and secret from the 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 while codes in the 4xx range indicate an error with your API request.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 us 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 us 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. 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.
Query Operators
$eq
Matches values that are equal to a specified value.
$gt
Matches values that are greater than a specified value.
$gte
Matches values that are greater than or equal to a specified value.
$lt
Matches values that are less than a specified value.
$lte
Matches values that are less than or equal to a specified value.
$ne
Matches all values that are not equal to a specified value.
$in
Matches any of the values specified in an array.
$nin
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)

Sample Sort

{
  name: 1,
  votes: -1
}
Returns results sorted first by name in ascending order then by the number of votes in descending order.

Pagination

API methods that accept pageNumber and limit parameters have pagination built into the response. There are three attributes returned as part of the result set that help with paging:
Attributes
pages
integer
The total number of pages for this result set
count
integer
The total number of results
pageNumber
integer
The current page number
list
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.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
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
string
The name of the app type for this app
model
A JSON object representing the pricing model type for this app
customData
A custom JSON object that you can create and attach to this app record
restrict
JSON object to restrict users from owning or viewing this app
JSON object to restrict users from owning or viewing this app
access
array(string)
JSON array of data access requirements
Returns
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 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",
  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
string
The name of the app
type
string
The name of the app type for this app
model
A JSON object representing the pricing model type for this app
customData
A custom JSON object that you can create and attach to this app record
restrict
JSON object to restrict users from owning or viewing this app
JSON object to restrict users from owning or viewing this app
access
array(string)
JSON array of data access requirements
Returns
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. App versions can only be queried from GET /apps/versions.

Definition

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

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/{appId}/versions/{version} \
  -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",
  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/{appId} \
  -X DELETE \
  -d developerId="123"

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/{appId}/versions/{version} \
  -X DELETE \
  -d developerId="123"

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
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
developerId
string
The unique id of the developer requesting this resource
Returns
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 \
  -d developerId="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",
      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
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/{appId}/publish \
  -X POST \
  -d appId="5565322ae4b0a70b13a4563b" \
  -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
string
The unique id of the developer requesting this resource
Returns
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/{appId}/versions/{version} \
 -d 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",
  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/{appId}/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
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/{appId}/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 and stored on the OpenChannel platform. Files are automatically distributed through a global content delivery network.

File Upload

Files can be uploaded from the API. 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.File Upload
Parameters
file
file
The multipart form data file stream
Returns
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
File Upload With URL
Parameters
url
string
The URL of the file to be uploaded
Returns
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
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 30 days.
For example, here is an app with a file attached to the 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"
  },
 ... 
}

Definition From File

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

Sample Request From File

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 From File

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

Sample File Failure Response

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

Definition From URL

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

Sample Request From URL

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

Sample Response From URL

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

Sample URL 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
fileId
string
The id of the file to be returned
Returns
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"
    }
 ]
}

Download File

Files can be downloaded from the standard fileUrl. With fileUrl if you wanted to track the number of downloads, it is necessary to call the statistics increment API method separately. However, we do supply a URL template that can automatically track download counts and redirect the user to the download. In order to automatically track downloads, format the download URL as:
https://market.openchannel.io/v2/files/download/{marketplaceId}/{appId}/{fileId}

As an example, the file:

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

Would be stored in a app as follows:

{
  appId: "5565322ae4b0a70b13a4563b", 
  name: "my first app",
  developerId: "123",
  customData: 
  { 
    summary: "Automatically set on/off timers...", 
    description: "HPWHs use electricity to move heat...", 
    download: "https://market.openchannel.io/v2/files/download/5463cee5e4b042e3e26f1e41/5565322ae4b0a70b13a4563b/56e2e6a91707a57c3f593499.csv"
  },
 ... 
}

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.
Parameters
developerId
string
The unique id of the developer
Returns
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/{developerId}

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
string
The username of this developer
name
string
The name of this developer
email
string
This developer’s email address
groupId
string
This developer’s group
customData
A custom JSON object that you can create and attach to this developer record
Returns
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/{developerId} \ 
  -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
long
The time (in milliseconds) to begin the sum
end
long
The time (in milliseconds) to end the sum
query
string
A Query Document. Example: {“status.value”:”approved”} returns statistics for all the apps that are approved
Returns
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/series/total \
  -d start=1455062400000 \
  -d end=1457568000000 \
  -d fields=views,downloads \
  -d 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
long
The time (in milliseconds) to begin the time series
end
long
The time (in milliseconds) to end the time series
query
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 \
  -d start=1455062400000 \
  -d end=1457568000000 \
  -d 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"
    }
 ]
}

Purchases

A Purchase tracks the relationship between a user and a paid app. Each purchase can have one or more payments. Multiple payments occur if the app requires a recurring, monthly payments or if the app is refunded by the developer.

List Purchases

Listing purchases returns Purchase Pages based on query and sort criteria. This is useful when displaying purchases to developers within your developer portal.
Parameters
query
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
Pages of purchases 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/purchases

Sample Request

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

Sample Success Response

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      purchaseId: "5463cee5e4b042e3e26f1e41",
      date: 1427466717262,
      appId: "5565322ae4b0a70b13a4563b",
      userId: "abc",
      developerId: "123",
      status: "active",
      share: 
      {
        fee: 47,
        marketplace: 128,
        developer: 987
      },
      model:
      { 
        type: "free", 
        price: 0, 
        trial: 0, 
        license: "single", 
        modelId: "1", 
        currency: "USD" 
      } 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

Get Purchase

Retrieving a purchase returns a single, specific purchase. This API is most suitable for displaying the details of a purchase to a developer.
Parameters
purchaseId
string
The id of the purchase to be returned
Returns
The purchase.
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The purchase was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/purchase/{purchaseId}

Sample Request

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

Sample Success Response

{ 
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  status: "active",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  },
  model:
  { 
    type: "free", 
    price: 0, 
    trial: 0, 
    license: "single", 
    modelId: "1", 
    currency: "USD" 
  }
}

Sample Failure Response

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

List Payments

Listing payments returns Payment Pages based on query and sort criteria. This is useful when displaying payments to developers within your developer portal.
Parameters
query
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
Pages of payments 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/payments

Sample Request

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

Sample Success Response

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      paymentId: "5463j675e4b04jgh626f13k9",
      type: "payment",
      purchaseId: "5463cee5e4b042e3e26f1e41",
      date: 1427466717262,
      appId: "5565322ae4b0a70b13a4563b",
      userId: "abc",
      developerId: "123",
      amount: 1162,
      currency: "USD",
      share: 
      {
        fee: 47,
        marketplace: 128,
        developer: 987
      } 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

Get Payment

Retrieving a payment returns a single, specific payment. This API is most suitable for displaying the details of a payment to a user.
Parameters
paymentId
string
The id of the payment to be returned
Returns
The payment
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The payment was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/payment/{paymentId}

Sample Request

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

Sample Success Response

{ 
  paymentId: "5463j675e4b04jgh626f13k9",
  type: "payment",
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  amount: 1162,
  currency: "USD",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  }
}

Sample Failure Response

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

Gateways

Gateways allow developers to connect their Stripe account in order to receive payments for apps.

Create Connect URL

Creates a URL that a developer can use to connect their Stripe account to this 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
The URL that the developer can use to connect their Stripe account
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Payments must first be enabled for this marketplace

Definition

POST https://market.openchannel.io/v2/gateways/stripe/accounts/token

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/gateways/stripe/accounts/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "developerId:'123'", \
        "redirectUrl:'https://my-site.com/completed'", \
     "}"

Sample Success Response

{ 
  developerId: "123",
  expires: 1460562039452,
  redirectUrl: "http://my-site.com/complete",
  targetUrl: "https://market.openchannel.io/5463cee5e4b042e3e26f1e41?token=5e4b042e3e2"
}

Sample Failure Response

{
  code: 400,
  errors:
  [
    {
      field: "redirectUrl",
      message: "must be a valid URL"
    }
 ]
}

Disconnect Account

Disconnects a developers connected Stripe account.
Parameters
developerId
string
The id of the developer disconnecting their Stripe account
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

DELETE https://market.openchannel.io/v2/gateways/stripe/accounts/{stripeId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/gateways/stripe/accounts/{stripeId} \
  -X DELETE \
  -d developerId="30"

Sample Success Response

{}

Get Accounts

Returns a developers connected Stripe accounts.
Parameters
developerId
string
The id of the developer connecting their Stripe account
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
The paged list of connected accounts.
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

GET https://market.openchannel.io/v2/gateways/stripe/accounts

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/gateways/stripe/accounts \
  -d developerId="30"

Sample Success Response

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      developerId: "30", 
      stripeId: "acct_17fJClG587jwu5Ch", 
      accountName: "My Account",
      country: "US",
      defaultCurrency: "cad",
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

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
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
userId
string
The unique id of the user requesting this resource
isOwned
boolean
Whether this result should only contain apps that are owned by this user
Returns
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 \
  -d query="{'status.value':'approved'}" \
  -d 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",
      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: "" 
      }, 
      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
string
The unique id of the user requesting this resource
Returns
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/{appId} \
  -d 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",
  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: "" 
  }, 
  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
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
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
userId
string
The unique id of the user requesting this resource
isOwned
boolean
Whether this result should only contain apps that are owned by this user
Returns
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 \
  -d query="{'status.value':'approved'}" \
  -d text="electricity" \
  -d fields="['name','customData.summary','customData.description']" \
  -d 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",
      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: "" 
      }, 
      isLive: true 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

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
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/{userId}

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
string
This user’s groupId
username
string
The username of this user
name
string
The name of this user
email
string
This user’s email address
customData
A custom JSON object that you can create and attach to this user record
Returns
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/{userId} \
  -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
purchaseMethodId
string
The id of the preferred purchase method. This can be a cardId, bankId or any other id from a purchase method.
Returns
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/apps/{appId}

Sample Request

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

Sample Success Response

{
  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 Response

{
  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
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/apps/{appId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/ownership/apps/{appId} \
  -d userId="abc"

Sample Success Response

{
  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 Response

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

List Ownership

Listing ownership returns App Pages based on query and sort criteria.
Parameters
query
string
Query Document. Example: {userId:”abc”} matches all the ownership records for user “abc”
sort
string
A Sort Document. Example: {“date”:1} sorts the results by date in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
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 \ 
  -d query="{userId:'abc'}" \
  -d sort="{date:1}"

Sample Success Response

{ 
  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 Response

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

Uninstall App

Disowning an app uninstalls this app for this user.
Parameters
appId
string
The id of the app
userId
string
The unique id of the user performing this action
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

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

Sample Request

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

Sample Success Response

{}

Sample Failure Response

{
  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
A custom JSON object that you can create and attach to this review record
Returns
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: 409,
  errors:
  [
    {
      field: "name",
      message: "The User has already reviewed this app"
    }
 ]
}

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
A custom JSON object that you can create and attach to this review record
Returns
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 Request

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
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 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: 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
string
Query Document. Example: {“status.value”:”approved”} matches all the reviews that are approved
sort
string
A Sort Document. Example: {“date”:1} sorts the results by date in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
userId
string
The unique id of the user requesting this resource
Returns
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 Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews \
  -d query="{'status.value':'approved', appId:'5565322ae4b0a70b13a4563b'}" \
  -d sort="{date:1}" \
  -d 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
string
The id of the user performing the action
date
long
The time (in milliseconds) when this statistical event occurred
value
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/supportRequests \
  -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"
    }
 ]
}

Purchases

A Purchase tracks the relationship between a user and a paid app. Each purchase can have one or more payments. Multiple payments occur if the app requires a recurring, monthly payments or if the app is refunded by the developer.

List Purchases

Listing purchases returns Purchase Pages based on query and sort criteria. This is useful when displaying purchases to developers within your developer portal.
Parameters
query
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
Pages of purchases 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/purchases

Sample Request

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

Sample Success Response

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      purchaseId: "5463cee5e4b042e3e26f1e41",
      date: 1427466717262,
      appId: "5565322ae4b0a70b13a4563b",
      userId: "abc",
      developerId: "123",
      status: "active",
      share: 
      {
        fee: 47,
        marketplace: 128,
        developer: 987
      },
      model:
      { 
        type: "free", 
        price: 0, 
        trial: 0, 
        license: "single", 
        modelId: "1", 
        currency: "USD" 
      } 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

Sample Failure Response

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

Get Purchase

Retrieving a purchase returns a single, specific purchase. This API is most suitable for displaying the details of a purchase to a user.
Parameters
purchaseId
string
The id of the purchase to be returned
Returns
The purchase.
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The purchase was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/purchase/{purchaseId}

Sample Request

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

Sample Success Response

{ 
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  status: "active",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  },
  model:
  { 
    type: "free", 
    price: 0, 
    trial: 0, 
    license: "single", 
    modelId: "1", 
    currency: "USD" 
  }
}

Sample Failure Response

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

Sample Failure Response

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

List Payments

Listing payments returns Payment Pages based on query and sort criteria. This is useful when displaying payments to developers within your developer portal.
Parameters
query
string
Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved
sort
string
A Sort Document. Example: {“name”:1} sorts the results by name in ascending order
pageNumber
integer
The result set page number to be returned
limit
integer
The maximum number of results to return per page
Returns
Pages of payments 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/payments

Sample Request

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

Sample Success Response

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      paymentId: "5463j675e4b04jgh626f13k9",
      type: "payment",
      purchaseId: "5463cee5e4b042e3e26f1e41",
      date: 1427466717262,
      appId: "5565322ae4b0a70b13a4563b",
      userId: "abc",
      developerId: "123",
      amount: 1162,
      currency: "USD",
      share: 
      {
        fee: 47,
        marketplace: 128,
        developer: 987
      } 
    },
    {...},
    {...}
  ]
}

Sample Failure Response

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

Sample Failure Response

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

Get Payment

Retrieving a payment returns a single, specific payment. This API is most suitable for displaying the details of a payment to a user.
Parameters
paymentId
string
The id of the payment to be returned
Returns
The payment
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
404
Not Found
The payment was not found
405
Method Not Allowed
You’re calling this API with an incorrect HTTP method

Definition

GET https://market.openchannel.io/v2/payment/{paymentId}

Sample Request

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

Sample Success Response

{ 
  paymentId: "5463j675e4b04jgh626f13k9",
  type: "payment",
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  amount: 1162,
  currency: "USD",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  }
}

Sample Failure Response

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

Sample Failure Response

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

Gateways

A gateway allows the user to setup and manage their credit card. A user must setup their credit card details before a paid app can be owned. Once setup, the marketplace will remember the user’s credit card details for future transactions.

Create Card

An credit card can be created and added to a user’s account.
Parameters
userId
string
The unique id of the user adding the credit card
token
string
The Stripe token returned by the Stripe.js Stripe.card.createToken call
isDefault
boolean
Set to true if this should be set to be the default credit card
Returns
The credit cards for this user’s account
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

POST https://market.openchannel.io/v2/gateways/stripe/cards

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/gateways/stripe/cards \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "userId:'abc'" \
        "token:'5463cee5e4b042e3e26f1e41'" \
     "}"

Sample Success Response

{ 
  userId: "abc"
  cards: 
  [
    {
      isDefault: true,
      exp_year: 2019,
      exp_month: 3,
      last4: 5478,
      brand: "visa",
      name: "John Smith",
      address_city: "New York",
      address_country: "US",
      address_line1: "123 folsom street",
      address_line2: "unit 1407",
      address_state: "New York",
      address_zip: "57847"
    }
  ]
}

Sample Failure Response

{
  code: 400,
  errors:
  [
    {
      field: "token",
      message: "Invalid Stripe token"
    }
 ]
}

Get Cards

Retrieving cards returns an array of credit cards for a single user. This API is most suitable for displaying the credit card details to a user.
Parameters
userId
string
The id of the user whose credit cards are to be returned
Returns
The credit cards for this user’s account.
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

GET https://market.openchannel.io/v2/gateways/stripe/cards

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/gateways/stripe/cards?userId=abc

Sample Success Response

{ 
  userId: "abc"
  cards: 
  [
    {
      isDefault: true,
      exp_year: 2019,
      exp_month: 3,
      last4: 5478,
      brand: "visa",
      name: "John Smith",
      address_city: "New York",
      address_country: "US",
      address_line1: "123 folsom street",
      address_line2: "unit 1407",
      address_state: "New York",
      address_zip: "57847"
    }
  ]
}

Update Card

Certain details about a user’s credit card can be updated.
Parameters
userId
string
The unique id of the user updating the credit card
cardId
string
The id of the card to be updated
isDefault
boolean
Set to true if this should be set to be the default credit card
address_city
string
The card holder’s city
address_country
string
The card holder’s city
address_line1
string
The card holder’s street address
address_line2
string
The card holder’s street address
address_state
string
The card holder’s city state/province
address_zip
string
The card holder’s zip/postal code
Returns
The credit cards for this user’s account
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

POST https://market.openchannel.io/v2/gateways/stripe/cards/{cardId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/gateways/stripe/cards/{cardId} \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "userId:'abc'," \
        "address_city:'New York'," \
        "address_country:'US'," \
        "address_line1:'123 folsom street'," \
        "address_line2:'unit 1407'," \
        "address_state:'New York'," \
        "address_zip:'57847'" \
     "}"

Sample Success Response

{ 
  userId: "abc"
  cards: 
  [
    {
      isDefault: true,
      exp_year: 2019,
      exp_month: 3,
      last4: 5478,
      brand: "visa",
      name: "John Smith",
      address_city: "New York",
      address_country: "US",
      address_line1: "123 folsom street",
      address_line2: "unit 1407",
      address_state: "New York",
      address_zip: "57847"
    }
  ]
}

Sample Failure Response

{
  code: 400,
  errors:
  [
    {
      field: "exp_year",
      message: "Invalid four digit year"
    }
 ]
}

Delete Card

An credit card can be removed from a user’s account.
Parameters
userId
string
The unique id of the user removing the credit card
cardId
string
The id of the card to be removed
Errors
400
Bad Request
Required parameters are missing, malformed or invalid

Definition

DELETE https://market.openchannel.io/v2/gateways/stripe/cards/{cardId}

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/gateways/stripe/cards/{cardId}?userId=abc \
  -X DELETE

Sample Success Response

{}

Sample Failure Response

{
  code: 400,
  errors:
  [
    {
      field: "cardId",
      message: "Invalid card id"
    }
 ]
}

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
long
The date (in milliseconds) of when this consent occurred
ip
string
The IP address of the user giving consent
group
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/{appId} \
  -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
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/{appId}?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/{appId}?userId=abc \
  -X DELETE 

Sample Success Response

{}

Sample Failure Response

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

Single-Sign-On

Enables a user to become securely identified within an app without having to provide credentials.

Create SSO Token

Creates a secure token that the app can use to identify the user.
Parameters
userId
string
The unique id of the user launching the app
appId
string
The id of the app to be launched
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
412
Precondition Failed
Permission must be given to allow the app to access data on behalf of the user.
417
Expectation Failed
The user must first own this app

Definition

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

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/sso/apps/{appId} \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "userId:'abc'" \
     "}"

Sample Success Response

{
  token: "ahTjDrsaxLwcyRAdasvQSPzzG6YatKky",
  expires: 1460582466451
}

Sample Failure Response

{
  code: 417,
  errors:
  [
    {
      message: "The user must first own this app"
    }
 ]
}

Validate SSO Token

Returns a user identity in exchange for a valid, unexpired SSO token.
Parameters
token
string
The token to be validated for this app
appId
string
The id of the app to be launched
Returns
The ownership record for this user and app
Errors
400
Bad Request
Required parameters are missing, malformed or invalid
404
Precondition Failed
This token/app combination is invalid.

Definition

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

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/sso/apps/{appId} \
  -d token="ahTjDrsaxLwcyRAdasvQSPzzG6YatKky"

Sample Success Response

{
  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 Response

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

Markets

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

Get This Market

Retrieving this market returns a single record representing the settings of the current market.
Returns
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": ""
        }
      ]
    }
  ]
}

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
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
string
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
The current status of this app
parent
The attributes of the parent (live) app
developerId
string
The id of the developer that owns this app
groupId
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
A custom JSON object that you can create and attach to this app record
Whitelists that restrict users from accessing this app
restrict
Blacklists that restrict users from accessing this app
version
integer
The version number for this app
attributes
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
access
array(string)
A custom defined list of access requirements
isLive
boolean
True if this is the live version of this app
isLatestVersion
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
string
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
The current status of this app
developerId
string
The id of the developer that owns this app
groupId
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
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
customData
A custom JSON object that you can create and attach to this app record
Whitelists that restrict users from accessing this app
restrict
Blacklists that restrict users from accessing this app
version
integer
The version number for this app
attributes
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
access
array(string)
A custom defined list of access requirements

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, 
  status: 
  { 
    value: "approved", 
    lastUpdated: 1432696823474, 
    modifiedBy: "administrator", 
    reason: "" 
  }, 
  isLive: true }

Status

Attributes
value
string
The current status. Can be: “pending” or “inReview” or “inDevelopment” or “approved” or “suspended” or “rejected”
reason
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
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

Sample App Model

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

Parent

Attributes
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
JSON Object
A JSON object describing the restriction to owning this app
view
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.

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.
Attributes
userId
string
The unique id of the user
username
string
The username of this user
name
string
The name of this user
email
string
This user’s email address
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"]
  }
}

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.
Attributes
developerId
string
The unique id of the developer
username
string
The username of this developer
name
string
The name of this developer
email
string
This developer’s email address
groupId
string
This developer’s group
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
  }
}

Files

Attributes
fileId
string
The id of this file
name
string
The name of this file
size
integer
The size of this file
contentType
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
app
The app associated with this ownership
userId
string
The id of the user that owns this app
developerId
string
The id of the developer for this app
groupId
string
The id of the group that owns this app
ownershipType
string
The current ownership type for this app. Can be: “full” or “subscription” or “trial” or “cancelled”
ownershipStatus
string
The current ownership status for this app. Can be: “active” or “uninstalled”
uninstallDate
long
The date (in milliseconds) of when this app was uninstalled
expires
long
The date (in milliseconds) of when this app ownership expires
productKey
string
A unique id that represents the ownership of this app by this user
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)
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
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
string
Text describing the reason for the current status

Sample Review

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

Purchases

A Purchase tracks the relationship between a user and a paid app. Each purchase can have one or more payments. Multiple payments occur if the app requires a recurring, monthly payments or if the app is refunded by the developer.

Purchase 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(Purchase)
An array of purchases for the current page

Sample Purchase Page

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      purchaseId: "5565322ae4b0a70b13a4563b", 
      status: "active",
      ...
    },
    {...},
    {...}
  ]
}

Payment 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(Payment)
An array of payments for the current page

Sample Payment Page

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      paymentId: "5565322ae4b0a70b13a4563b", 
      type: "payment",
      ...
    },
    {...},
    {...}
  ]
}

Purchase

Attributes
purchaseId
string
The id of this purchase
date
long
The date (in milliseconds) of when this app was purchased
appId
string
The id of the app that is owned
app
The app associated with this purchase
userId
string
The id of the user that owns this app
developerId
string
The id of the developer for this app
groupId
string
The id of the group that owns this app
purchaseMethodId
string
The id of the preferred purchase method
model
The model for this ownership
status
string
The current purchase status for this app. Can be: “active” or “cancelled” or “pending”
share
The revenue share for this purchase

Sample Purchase

{
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  status: "active",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  },
  model:
  { 
    type: "free", 
    price: 0, 
    trial: 0, 
    license: "single", 
    modelId: "1", 
    currency: "USD" 
  }
}

Payment

Attributes
paymentId
string
The id of this payment
purchaseId
string
The id of the purchase that this payment belongs to
type
string
The type for this transaction. Can be: “payment” or “refund”
date
long
The date (in milliseconds) of when this payment was made
appId
string
The id of the app that is involved in this transaction
app
The app associated with this transaction
appName
string
The name of the app that is involved in this transaction
userId
string
The id of the user that owns this app
developerId
string
The id of the developer for this app
purchaseMethod
Object
The purchase method details for this transaction. This can be a Card, Bank Account or any other purchase method.
customData
A custom JSON object that you can create and attach to this payment record
referencePaymentId
string
An id that references another related transaction
amount
integer
The total amount paid in cents
currency
string
The currency for this payment
share
The revenue share for this payment

Sample Payment

{
  paymentId: "5463j675e4b04jgh626f13k9",
  type: "payment",
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  amount: 1162,
  currency: "USD",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  }
}

Sample Refund

{
  paymentId: "5463j675e4b04jgh626f13h3",
  type: "refund",
  purchaseId: "5463cee5e4b042e3e26f1e41",
  date: 1427466717262,
  appId: "5565322ae4b0a70b13a4563b",
  userId: "abc",
  developerId: "123",
  amount: 1162,
  referencePaymentId: "5463j675e4b04jgh626f13k9",
  currency: "USD",
  share: 
  {
    fee: 47,
    marketplace: 128,
    developer: 987
  }
}

Share

Attributes
fee
integer
The payment processor fee (in cents)
marketplace
integer
The amount owed to the marketplace owner (in cents)
developer
integer
The amount owed to the developer (in cents)

Sample Share

{
  fee: 47,
  marketplace: 128,
  developer: 987}

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

Gateways

Gateway objects hold payment 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: 
  [
    {
      isDefault: true,
      exp_year: 2019,
      exp_month: 3,
      last4: 5478,
      brand: "visa",
      name: "John Smith",
      address_city: "New York",
      address_country: "US",
      address_line1: "123 folsom street",
      address_line2: "unit 1407",
      address_state: "New York",
      address_zip: "57847"
    }
  ]
}

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
string
The card holder’s city
address_country
string
The card holder’s country
address_line1
string
The card holder’s street address
address_line2
string
The card holder’s street address
address_state
string
The card holder’s city state/province
address_zip
string
The card holder’s zip/postal code

Sample Card

{ 
  isDefault: true,
  exp_year: 2019,
  exp_month: 3,
  last4: 5478,
  brand: "visa",
  name: "John Smith",
  address_city: "New York",
  address_country: "US",
  address_line1: "123 folsom street",
  address_line2: "unit 1407",
  address_state: "New York",
  address_zip: "57847"
}

DeveloperToken

Attributes
developerId
string
The id of the developer connecting their Stripe account
expires
long
The time (in milliseconds) when this URL expires
redirectUrl
string
The URL that this developer will be redirected to after they have connected their account
targetUrl
string
The URL that this developer can use to connect their Stripe account

Sample DeveloperStatus

{ 
  developerId: "123",
  expires: 1460562039452,
  redirectUrl: "http://my-site.com/complete",
  targetUrl: "https://market.openchannel.io/5463cee5e4b042e3e26f1e41?token=5e4b042e3e2"
}

Account

Attributes
stripeId
string
The id of the Stripe account
developerId
string
The id of the developer connecting their 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

{ 
   developerId: "30", 
   stripeId: "acct_17fJClG587jwu5Ch", 
   accountName: "My Account",
   country: "US",
   defaultCurrency: "cad",
}

Account 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(Account)
An array of accounts for the current page

Sample Account Pages

{ 
  count: 8, 
  pages: 1, 
  pageNumber: 1, 
  list: 
  [ 
    { 
      developerId: "30", 
      stripeId: "acct_17fJClG587jwu5Ch", 
      accountName: "My Account",
      country: "US",
      defaultCurrency: "cad",
    },
    {...},
    {...}
  ]
}

Access

The Access object represents a user’s consent to allow an app to access data on behalf of a user. 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.
Attributes
appId
string
The id of the app that owns this access key
userId
integer
The id for this user
groupId
integer
The group id for this user
date
string
The time (in milliseconds) of when the user agreed to the access request
ip
integer
The ip address of the user agreeing to the access request
access
array(string)
The approved access restrictions for this app
isValid
boolean
True if this access is up to date with the current version of the app

Sample Access

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

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. Can be: “app.submitted”, “app.approved”, “app.suspended”, “app.unsuspended”, “app.rejected”, “app.inReview”, “app.owned”, “app.disowned”, “review.created”, “review.updated”, “review.approved”, “review.spam”, “review.removed”, “user.invalidPaymentDetails”, “user.paymentDetailsRequired”, “developer.paymentDetailsRequired”, “permission.added”, “permission.removed”, “payment.complete”, “payment.refunded”
marketplaceId
string
The id of the marketplace that produced this event
developer
The developer associated with this event. This value is only provided for “developer.paymentDetailsRequired” events.
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
The review associated with this event. This value is only provided for “review.created”, “review.updated”, “review.approved”, “review.spam”, “review.removed” events.
user
The user associated with this event. This value is only provided for “user.invalidPaymentDetails”, “user.paymentDetailsRequired” events.
ownership
The ownership associated with this event. This value is only provided for “app.owned”, “app.disowned” events.
payment
The payment associated with this event. This value is only provided for “payment.complete”, “payment.refunded” events.
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
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
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
values
string
A comma seperated 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
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": ""
    }
  ]
}

Log in with your credentials

Forgot your details?