Market API

Marketplace API

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

  • The Market API is useful when building app stores for end users to install and launch or app portals for developers and partners to submit and manage their apps
  • The Payment API is useful when building payments into your marketplace

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

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

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

Marketplace API Endpoint

https://market.openchannel.io/v2

Authentication

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

credentials

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

Example Request

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

Errors

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

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

 

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

Error with Fields

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

Error without Fields

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

User and Developer Ids

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

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

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

Query Document

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

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

Query All

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

Sample Query All

{}

Returns all results.

Equality Condition

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

Sample Equality Query

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

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

Comparison Operators

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

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

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

Sample $in Query

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

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

Sample $ne Query

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

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

Sample $gt Query

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

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

Dot Notation

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

Lets consider the following app:

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

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

Sample Document Query

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

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

AND and OR

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

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

Let’s consider the following app:

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

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

The  $and operator can help you query results where the field ‘developerId’ = ‘123’ AND 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’.

NOT and NOR

A $not query inverts the effect of a query expression and returns documents that do not match the query expression. The $not operator only affects other operators and cannot check fields and documents independently. So, use the $not operator for logical disjunctions and the $ne operator to test the contents of fields directly.

Using the $nor operator, joins query clauses with a logical NOR returns all documents that fail to match both clauses.

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 $not operator can help you query results where the field ‘developerId’ is not ‘123’ AND the field ‘name’ is not ‘my first app’.

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

Sample $not Query

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

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

Sample $nor Query

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

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

EXISTS and TYPE

A $exists query matches documents that have the specified field. When the Boolean value is true, $exists matches the documents that contain the field, including documents where the field value is null. If the Boolean value is false, the query returns only the documents that do not contain the field.

A $type query selects documents if a field is of the specified type. Querying by data type is useful when dealing with highly unstructured data where data types are not predictable. Below is a list of types:

Type Alias
Double “double”
String “string”
Object “object”
Array “array”
Boolean “bool”
Null “null”
32-bit Integer “int”
64-bit Integer “long”

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"
     ],
    "optionalField": "yes!" 
  } 
}

The $exists operator can help you query results where the “customData.optionalField” is not set (missing, null or undefined).

The $type operator can help you query results where the “customData.optionalField” value is a String.

Sample $exists Query

{
  "customData.optionalField" : 
    {
      "$exists": false
    }
}

Returns results where the field ‘customData.optionalField’ is not set.

Sample $type Query

{
  "customData.optionalField" : 
    {
      "$type": "string"
    }
}

Returns results where the field ‘customData.optionalField’ contains a string value.

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.

The $elemMatch operator selects documents if element in the array field matches all the specified $elemMatch conditions. If you specify multiple conditions using the $elemMatch operator, the array must contain at least one element that satisfies all the conditions.

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

Let’s consider the following app:

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

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

Sample Array Query

{
  "customData.categories": "books"
}

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

Sample $elemMatch Query

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

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

Sort Document

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

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

Lets consider the following app:

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

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

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

Sample Sort

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

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

Pagination

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

Attributes

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

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 about events that occur within your marketplace. Each webhook event contains an Event object which is a JSON representation of an event that has occurred and can contain different content based on the event type. To configure your webhooks, log into the Management Dashboard and click Settings -> Webhooks.

In the event where your webhook handler returns an error code or is unresponsive then the webhooks will be automatically retried. At first, the webhook will retry every 10 minutes for 30 minutes then every hour for 3 hours then finally every day for 3 days. After 3 days the event is discarded. If a 200 series code is returned then it will be assumed that the event was successfully processed and will not be retried.

Retry schedule can change at any time
Please note that the webook retry schedule can be changed at any time without notice.

Webhook Event Types

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

Webhook Security

Verifying events is important for security and ensuring that your endpoint URL isn’t being exploited by an unauthorized third party. There are two webhook verification methods that you may choose between:

Verify webhooks using signature
When setting up a webhook endpoint in your my.openchannel.io from Settings -> Webhooks you are able to specify a secret that can be used to sign the webhook event. Signed webhook events contain a “signature” attribute that can be used to verify the contents of the webhook event.

The signature is generated using a standard HMAC SHA256 algorithm. You’ll need to use a library that works with your backend language. Here are a few verified libraries:

To manually verify the signature for testing you can perform the following steps:

  1. Select any event and set target url as an endpoint generated by the https://webhook.site tool.
  2. Copy the webhook object content using the copy button with “Format JSON” and “Word-Wrap” turned off, so that it will copy the string without any space or indentation.
  3. Use this https://www.freeformatter.com/hmac-generator.html#ad-output to generate HMACSHA256.
  4. Paste the content in the string box
  5. Remove the signature field from and attribute along with any spaces to the left or right of the attribute
  6. Paste your secret used in webhook endpoint.
  7. Select digest algorithm as SHA256
  8. Click on compute HMAC
  9. Now you can verify whether the generated signature and signature which you received in wehbook object are same

Verify webhooks using the API
Any event that you receive can be verified by ignoring the message payload and retrieving the event using the GET /events/{eventId} API method.

Parameters

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

Returns

Event
The event associated with this eventId.

Errors

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

Definition

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

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/events/{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 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.

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
safeName (optional)
array(string)
A JSON array of safe names for this app
type (optional)
string
The name of the app type for this app
model (optional)
array(Model)
A JSON array representing the pricing models for this app
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
attributes (optional)
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
restrict (optional)
Restriction
JSON object to restrict users from owning or viewing this app
allow (optional)
Restriction
JSON object to restrict users from owning or viewing this app
access (optional)
array(string)
JSON array of data access requirements

Returns

App Version
Returns the newly created app version.

Errors

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

 

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

Paid Apps

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

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

App Licensing

Apps can be purchased and owned for individual users or entire organizations. There is one types of license: ‘single’. The single user license requires each user or organization to purchase an app.

API Access

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

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

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

Request URL

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

Sample Request

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

Sample Success Response

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

Sample Failure Response

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

Update App

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

This endpoint replaces the entire object to match the request (absolute update). In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update).

Parameters

appId
string
The id of the app to be updated
version
string
The version of the app to be updated
developerId
string
The unique id of the developer that is adding this app
name (optional)
string
The name of the app
type (optional)
string
The name of the app type for this app
model (optional)
array(Model)
A JSON array representing the pricing models for this app
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
attributes (optional)
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
restrict (optional)
Restriction
JSON object to restrict users from owning or viewing this app
allow (optional)
Restriction
JSON object to restrict users from owning or viewing this app
access (optional)
array(string)
JSON array of data access requirements
approvalRequired (optional)
boolean
False if updates should skip the approval process and be available immediately. Default is True

Returns

App Version
Returns the newly updated app version.

Errors

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

 

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

Definition

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

Sample Request

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

Sample Success Response

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

Sample Failure Response

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

Update App Fields

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

This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update).

Parameters

appId
string
The id of the app to be updated
version
string
The version of the app to be updated
developerId
string
The unique id of the developer that is adding this app
name (optional)
string
The name of the app
safeName (optional)
array(string)
A JSON array of safe names for this app
type (optional)
string
The name of the app type for this app
model (optional)
array(Model)
A JSON array representing the pricing models for this app
customData (optional)
CustomData
A custom JSON object that you can create and attach to this app record
attributes (optional)
JSON Object
A custom set of app attributes defined by the administrator and attached to this app
restrict (optional)
Restriction
JSON object to restrict users from owning or viewing this app
allow (optional)
Restriction
JSON object to restrict users from owning or viewing this app
access (optional)
array(string)
JSON array of data access requirements
approvalRequired (optional)
boolean
False if updates should skip the approval process and be available immediately. Default is True

Returns

App Version
Returns the newly updated app version.

Errors

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

 

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

Definition

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

Sample Request

curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/1 \
  -X PATCH \
  -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'," \
          "'author': 'Andrea'" \
        "}" \
     "}"

Sample Success Response

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

Sample Failure Response

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

Delete App Version

Deleting an app version permanently removes that version.

Parameters

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

Errors

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

Definition

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

Sample Request

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

Sample Success Response

{}

Sample Failure Response

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

Delete App

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

Parameters

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

Errors

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

Definition

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

Sample Request

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

Sample Success Response

{}

Sample Failure Response

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

Publish App Version

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

Parameters

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

Errors

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

Definition

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

Sample Request

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

Sample Success Response

{}

Sample Failure Response

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

 

List Apps

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

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

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

Parameters

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

Returns

App Pages
A page of app results

Errors

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

Definition

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

Sample Request

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

Sample Success Response

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

Sample Failure Response

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

List App Versions

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

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

Parameters

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

Returns

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

Errors

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

Definition

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

Sample Request

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

Sample Success Response

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

Sample Failure Response

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

Get an App

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

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

Parameters

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

Returns

App
A single app

Errors

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

Definition

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

Sample Request

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

Sample Success Response

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

Sample Failure Response

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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get an App Version

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


Parameters












appId




string






The id of the app to be returned










version




integer






The version number of the app










developerId (optional)




string






The unique id of the developer requesting this resource






Returns

















App Version






The version for this app.






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The app or version was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Search Apps

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


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


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


Parameters












query (optional)




string






A Query Document. Example: {“status.value”:”approved”} matches all the apps that are approved










text




string






The text that you want to search for










fields




JSON Array






A JSON Array of field names to include as part of the search. You can also use dot notation to add sub documents.










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.










userId (optional)




string






The unique id of the user requesting this resource










isOwner (optional)




boolean






Whether this result should only contain apps that are owned by this user






Returns

















App Pages






A page of app results






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get App By SafeName

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


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


Parameters












safeName




string






The safeName of the app to be returned










userId (optional)




string






The unique id of the user requesting this resource










trackViews




boolean






Whether this call should be tracked as a ‘view’ for this app. Default is false.






Returns

















App






A single app






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The app is either restricted or not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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



                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Change Live Version

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


Parameters












appId




string






The id of the app to become the live version










developerId




string






The id of the developer making this request










version




integer






The app version to become the live version






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The app was not found





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Change App Status

                                          
Changes the status of an app. This action can be performed by either administrators or developers. Only certain status changes are allowed. For instance, a developer is only able to suspend and unsuspend their app (which must already be approved). Below is a state change diagram of allowed status changes for administrators:


app state change diagram


Parameters












appId




string






The id of the app to be updated










version




string






The version of the app to be updated










status




string






The new status for this app. Can be either ‘inReview’, ‘approved’, ‘suspended’ or ‘rejected’










developerId (optional)




string






The id of the developer updating this app










modifiedBy (optional)




string






The role initiating this status change. Can be either ‘developer’ or ‘administrator’ (default)










reason (optional)




string






The reason for this status change






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The app was not found










412




Precondition Failed






The app’s new status is not valid because of the app’s current status





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/apps/5565322ae4b0a70b13a4563b/versions/3/status \
 -x POST \
 -d developerId="30" \
 -d status="suspended" \
 -d modifiedBy="developer" \
 -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 when modifiedBy is set to 'developer'"
    }
 ]
}


 

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Developers

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


A developer can either be: 


    

  1. An individual, authenticated developer account that is able to log in.
    2. 

  2. An organization which itself can have many developer accounts.
    3. 



If developers should be individuals then the developerId should be a unique user ID which represents the logged in user. However, if a developer should be an organization consisting of many developer accounts then the developerId should be the organization ID. In order to represent the individual developer accounts then user the /developerAccounts API endpoint to create the representations of these users.

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Get Developer

                                          
Retrieving an developer returns a single, specific, developer.


Paremeters












developerId




string






The unique id of the developer






Returns

















Developer






The developer






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The developer is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Developers

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


Parameters












query (optional)




string






A Query Document. Example: {“created”:{“$gt”:1498851408000}} matches all the developer accounts created after June 30th 2017










sort (optional)




string






A Sort Document. Example: {“name”:1} sorts the results by name in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.






Returns

















Developer Pages






A page of developer results






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Create/Update Developer

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


This endpoint replaces the entire object to match the request (absolute update) or creates it if it doesn’t exist. In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 


Parameters












developerId




string






The unique id of the developer










type (optional)




string






The type for this developer










username (optional)




string






The username of this developer










name (optional)




string






The name of this developer










email (optional)




string






This developer’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this developer record






Returns

















Developer






The newly created developer






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Developer Fields

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


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 


Parameters












developerId




string






The unique id of the developer










type (optional)




string






The type for this developer










username (optional)




string






The username of this developer










name (optional)




string






The name of this developer










email (optional)




string






This developer’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this developer record






Returns

















Developer






The updated 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


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


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developers/123 \ 
  -X PATCH \
  -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"
    }
 ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Developer

                                          
Deletes a single developer.








Parameters












developerId




string






The unique id of 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


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Developer Accounts

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


Parameters












query (optional)




string






A Query Document. Example: {“name”:”NASA”} matches all the developer accounts named NASA










sort (optional)




string






A Sort Document. Example: {“name”:1} sorts the results by name in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.






Returns

















Developer Account Pages






A page of developer account 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/developerAccounts


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developerAccounts? \
  query={'developerId':'123'& \
  sort={'name':1}& \



Sample Success Response


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "developerAccountId": "abc", 
      "developerId": "123",
      "name": "John",
      "email": "brian@mycompany.com",
      "customData": 
      { 
        "interests": ["Surfing", "Kittens"]
      }
    },
    {...},
    {...}
  ]
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Developer Account

                                          
Returns a single, specific, developer account.








Parameters












developerAccountId




string






The unique id of the developer account






Returns

















DeveloperAccount






The developer account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The developer account is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


GET https://market.openchannel.io/v2/developerAccounts/{developerAccountId}


Sample Request


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


Sample Success Response


{ 
  "developerAccountId": "abc", 
  "developerId": "123", 
  "name": "John",
  "email": "brian@mycompany.com", 
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Create/Update Developer Account

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


This endpoint replaces the entire object to match the request (absolute update) or creates it if it doesn’t exist. In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 








Parameters












developerAccountId




string






The unique id of the developer account










email (optional)




string






The contact email address










name (optional)




string






The name of the developer account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this record






Returns

















DeveloperAccount






The newly created/updated developer account






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






This userAccountId already exists under a different user organization











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/developerAccounts/{developerAccount}


Sample Request


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


Sample Success Response


{ 
  "developerAccountId": "abc", 
  "developerId": "123", 
  "email":"brian@mycompany.com",
  "name":"John",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Developer Account Fields

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


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 








Parameters












developerAccountId




string






The unique id of the developer account










email (optional)




string






The contact email address










name (optional)




string






The name of the developer account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this record






Returns

















DeveloperAccount






The newly created/updated developer account






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


PATCH https://market.openchannel.io/v2/developerAccounts/{developerAccount}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developerAccounts/abc \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d "{" \
        "'developerId':'123'," \
        "'email':'brian@mycompany.com'," \
        "'name':'John'," \
        "'customData':" \
        "{" \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"


Sample Success Response


{ 
  "developerAccountId": "abc", 
  "developerId": "123", 
  "email":"brian@mycompany.com",
  "name":"John",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Developer Account

                                          
Deletes a single developer account.








Parameters












developerAccountId




string






The unique id of the developer account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The developer account is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


DELETE https://market.openchannel.io/v2/developerAccounts/{developerAccountId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/developerAccounts/123 \
-X DELETE 


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Users

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


A user can either be: 


    

  1. An individual, authenticated user account that is able to log in.
    2. 

  2. An organization which itself can have many user accounts.
    3. 



If users should be individuals then the userId should be a unique user ID which represents the logged in user. However, if a user should be an organization consisting of many user accounts then the userId should be the organization ID. In order to represent the individual user accounts then user the /userAccounts API endpoint to create the representations of these users.

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Get User

                                          
Retrieving an user returns a single, specific, user.








Parameters












userId




string






The unique id of the user






Returns

















User






The user






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The user is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Users

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


Parameters












query (optional)




string






A Query Document. Example: {“created”:{“$gt”:1498851408000}} matches all the user accounts created after June 30th 2017










sort (optional)




string






A Sort Document. Example: {“name”:1} sorts the results by name in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.






Returns

















User Pages






A page of user results






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Create/Update User

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


This endpoint replaces the entire object to match the request (absolute update) or creates it if it doesn’t exist. In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 








Parameters












userId




string






The unique id of the user










type (optional)




string






The type for this user










username (optional)




string






The username of this user










name (optional)




string






The name of this user










email (optional)




string






This user’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this user record






Returns

















User






The newly created user






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update User Fields

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


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 








Parameters












userId




string






The unique id of the user










type (optional)




string






The type for this user










username (optional)




string






The username of this user










name (optional)




string






The name of this user










email (optional)




string






This user’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this user record






Returns

















User






The newly created 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


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


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/users/123 \
  -X PATCH \
  -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"
    }
 ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete User

                                          
Deletes a single user.








Parameters












userId




string






The unique id of 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


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List User Accounts

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


Parameters












query (optional)




string






A Query Document. Example: {“name”:”NASA”} matches all the user accounts named NASA










sort (optional)




string






A Sort Document. Example: {“name”:1} sorts the results by name in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 1000.






Returns

















User Account Pages






A page of user account 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/userAccounts


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/userAccounts? \
  query={'userId':'123'& \
  sort={'name':1}& \



Sample Success Response


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "userAccountId": "abc", 
      "userId": "123", 
      "name": "John",
      "email": "brian@mycompany.com",
      "customData": 
      { 
        "interests": ["Surfing", "Kittens"]
      }
    },
    {...},
    {...}
  ]
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get User Account

                                          
Returns a single, specific, user account.








Parameters












userAccountId




string






The unique id of the user account






Returns

















UserAccount






The user account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The account is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


GET https://market.openchannel.io/v2/userAccounts/{userAccountId}


Sample Request


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


Sample Success Response


{ 
  "userAccountId": "abc", 
  "userId": "123", 
  "email": "my@email.com",
  "name": "John",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete User Account

                                          
Deletes a single user account.








Parameters












userAccountId




string






The unique id of the user account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The user account is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


DELETE https://market.openchannel.io/v2/userAccounts/{userAccountId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/userAccounts/123 \
-X DELETE 


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Create/Update User Account

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


This endpoint replaces the entire object to match the request (absolute update) or creates it if it doesn’t exist. In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 








Parameters












userAccountId




string






The unique id of the user account










userId




string






The userId that this user account belongs to










email (optional)




string






The contact email address










name (optional)




string






The name for this user’s account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this record






Returns

















UserAccount






The newly created/updated user account






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






This userAccountId already exists under a different user organization











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/userAccounts/{userAccountId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/userAccounts/abc \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d "{" \
        "'userId':'123'," \
        "'email':'my@email.com'," \
        "'name':'John'," \
        "'customData':" \
        "{" \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"


Sample Success Response


{ 
  "userAccountId": "abc", 
  "userId": "123", 
  "email": "my@email.com",
  "name": "John",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update User Account Fields

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


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 








Parameters












userAccountId




string






The unique id of the user account










userId




string






The userId that this user account belongs to










email (optional)




string






The contact email address










name (optional)




string






The name for this user’s account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this record






Returns

















UserAccount






The newly created/updated user account






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


PATCH https://market.openchannel.io/v2/userAccounts/{userAccountId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/userAccounts/abc \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'userId':'123'," \
        "'email':'my@email.com'," \
        "'name':'John'," \
        "'customData':" \
        "{" \
           "'interests': ['Surfing', 'Kittens']'" \
        "}," \
     "}"


Sample Success Response


{ 
  "userAccountId": "abc", 
  "userId": "123", 
  "email": "my@email.com",
  "name": "John",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Files

                                  
Public Files


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


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


//file-openchannel.netdna-ssl.com/555bfb9cc434df81e597598b.png




File URLs have a generic protocol and do not start with ‘http:’ or ‘https:’

This allows the URL to become compatible with the native protocol of the serving web page. However, in some instances it may be necessary to pre-pend ‘http:’ or ‘https:’ to the URL.


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


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


Add the fileUrl to a customData field.

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


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


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


Private Files


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


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


    

  1. The user clicks on a link or requests to download the file
    2. 

  2. Your back end service calls the Download File API to generate a signed URL
    3. 

  3. Redirect the user to the signed URL or use javascript to initiate the download
    4. 



Don’t display signed URL’s as links on webpages.

Signed URLs are only usable for a few seconds so they shouldn’t be placed directly on webpages. Instead, they should be generated and used when the user has already decided to perform the “download” action.


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


Add the fileId to a customData field.

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


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


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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
File Upload

                                          
Parameters












file




file






The multipart form data file stream










isPrivate (optional)




boolean






If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.










hash (optional)




string






A comma separated list of hashes to return in order to verify file integrity.






Returns

















File






The metadata for the file that was uploaded






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method






 

                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
File Upload By URL

                                          
Parameters












url




string






The URL of the file to be uploaded










isPrivate (optional)




boolean






If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.










hash (optional)




string






A comma separated list of hashes to return in order to verify file integrity.






Returns

















File






The metadata for the file that was uploaded






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Response


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


Sample Failure Response


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


 

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get File Details

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


Parameters












fileldOrUrl




string






The fileId or fileUrl of the file to be returned






Returns

















File






The metadata for the file






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The file was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Download File

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


Parameters












fileld




string






The id of the file to be returned










validSeconds (optional)




integer






The number of seconds that this signed URL should be valid for. The default is 60.






Returns












url




string






The signed URL for this private file.






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The file was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Files

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


Parameters












query (optional)




string






A Query Document. Example: {“uploadDate”:{“$gt”:1498851408000}} matches all the files uploaded after June 30th 2017










sort (optional)




string






A Sort Document. Example: {“name”:1} sorts the results by name in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.






Returns

















File Pages






A page of developer results






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
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 (optional)




string






The id of the app model involved in this ownership










model (optional)




string






The overriding model that should be applied to this ownership










customData (optional)




CustomData






A custom JSON object to attach to this ownership record






Returns

















Ownership






The ownership record for this user and app






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










402




Payment Required






The App requires a user with pre-set payment details










404




Not Found






The ownership was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










409




Already Exists






The User already owns this app (or is already participating in a trial)










412




Payment Failed






The User’s payment details are invalid











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Ownership

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








Parameters












ownershipId




string






The id of the ownership record to retrieve






Returns

















Ownership






The ownership record for this user and app






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The ownership was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Ownership

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








Parameters












query (optional)




string






A Query Document. Example: {userId:”abc”} matches all the ownership records for user “abc”.










sort (optional)




string






A Sort Document. Example: {“date”:1} sorts the results by date in ascending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.






Returns

















Ownership Pages






A page of ownership records






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Uninstall App

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








Parameters












ownershipId




string






The id of the ownership to be unintalled










userId




string






The id of the User requesting to uninstall the App










cancelOwnership (optional)




boolean






True if this app must be paid for in order to be re-installed. Default is false










customData (optional)




CustomData






A custom JSON object to attach to this ownership record






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The ownership was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










409




Not Installed






App is not owned by this user











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Ownership

                                          
Updates an ownership record.


This endpoint replaces the entire object to match the request (absolute update). In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 








Parameters












ownershipId




string






The id of the ownership record to be updated










customData (optional)




CustomData






A custom JSON object to attach to this ownership record










expires (optional)




long






The date (in millis) of when this app ownership expires






Returns

















Ownership






The updated ownership record






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The ownership was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Ownership Fields

                                          
Updates an ownership record.


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 








Parameters












ownershipId




string






The id of the ownership record to be updated










customData (optional)




CustomData






A custom JSON object to attach to this ownership record










expires (optional)




long






The date (in millis) of when this app ownership expires






Returns

















Ownership






The updated ownership record






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The ownership was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Reviews

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Create Review

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








Parameters












appId




string






The id of the app being reviewed










userId




string






The unique id of the user that is reviewing this app










userAccountId (optional)




string






The unique id of the user account 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.










type (optional)




string






The type for this review










mustOwnApp (optional)




boolean






True if a review can be created only by a user that has owned the app. The default is True.










autoApprove (optional)




boolean






True if the review should be automatically approved. The default is False.










customData (optional)




CustomData






A custom JSON object that you can create and attach to this review record






Returns

















Review






The newly created review






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










403




Forbidden






Users must have owned the app before they can post a review; Anonymous users cannot post reviews










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










409




Already Exists






The User has already reviewed this app











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Review

                                          
Updating an app review allows users to modify their reviews.


This endpoint replaces the entire object to match the request (absolute update). In contrast, the PATCH version of this endpoint updates only the fields provided in the request (relative update). 








Parameters












reviewId




string






The id of the review being updated










userId




string






The unique id of the user that is updating this review










userAccountId (optional)




string






The unique id of the user account 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.










type (optional)




string






The type for this review










customData (optional)




CustomData






A custom JSON object that you can create and attach to this review record






Returns

















Review






The newly updated review






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The review is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Response


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Review Fields

                                          
Updating an app review allows users to modify their reviews.


This endpoint updates only the fields provided in the request (relative update). In contrast, the POST version of this method replaces the entire object to match the request (absolute update). 








Parameters












reviewId




string






The id of the review being updated










userId




string






The unique id of the user that is updating this review










userAccountId (optional)




string






The unique id of the user account 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.










type (optional)




string






The type for this review










customData (optional)




CustomData






A custom JSON object that you can create and attach to this review record






Returns

















Review






The newly updated review






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The review is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Response


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Review

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








Parameters












reviewId




string






The id of the review






Returns

















Review






A single review






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










404




Not Found






A review with this reviewId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Request


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


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
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. 








Parameters












query (optional)




string






A Query Document. Example: {“status.value”:”approved”} matches all the reviews that are approved.










sort (optional)




string






A Sort Document. Example: {“date”:1} sorts the results by date in ascending order










pageNumber(optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.















Review Pages






A page of reviews






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Response


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Review

                                          
Deletes a review.








Parameters












reviewId




string






The id of the review






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










404




Not Found






A review with this reviewId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/reviews/5565322ae4b0a70b13a4563b \
-X DELETE 


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Statistics

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Record Statistic

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


Parameters












field




string






The statistic type that you want to increment










appId




string






The id of the app associated with this statistical recording










userId (optional)




string






The id of the user performing the action










date (optional)




long






The time (in milliseconds) when this statistical event occurred










value (optional)




integer






The increment amount. Default is 1 if no value is provided






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Total

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


Parameters












fields




string






A comma separated list of statistic types that you want to total. Some default statistics are: “reviews”, “users”, “developers”, “views”,  “totalSales”, “downloads”










start (optional)




long






The time (in milliseconds) to begin the sum










end (optional)




long






The time (in milliseconds) to end the sum










userId (optional)




string






Query results that apply only to this userId










query (optional)




string






A Query Document for statistics based on app criteria. Example: {“status.value”:”approved”} returns statistics for all the apps that are approved






Returns

















Total






The sum of the statistic values






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Time Series

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


Parameters












period




string






The period for the series. Can be: “day” or “month”










fields




string






The field to be graphed. This also be a comma separated list of fields and the result will be a single timeseries containing the sum of all fields.










start (optional)




long






The time (in milliseconds) to begin the time series










end (optional)




long






The time (in milliseconds) to end the time series










userId (optional)




string






Query results that apply only to this userId










query (optional)




string






A Query Document for statistics based on app criteria. Example: {“status.value”:”approved”} returns statistics for all the apps that are approved






Returns

















array(array(long))






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






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Permission

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Add Permissions

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








Parameters












userId




string






The unique id of the user giving consent










appId




string






The id of the app that requires consent










date (optional)




long






The date (in milliseconds) of when this consent occurred










ip (optional)




string






The IP address of the user giving consent






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






App not found











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Permissions

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








Parameters












appId




string






The id of the app










userId




string






The id of the user






Returns

















Access






The access consent between this user and this app






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The access is not found











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Permissions

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








Parameters












userId




string






The unique id of the user giving consent










appId




string






The id of the app that requires consent






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The access is not found











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Orders

                                  
Each order record is a JSON representation of an order placed for an app by a user and describes the details of the prospective transaction.

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Create Order

                                          
Creating an order signals the intent for a user to become the owner of an app. This can be useful as an intermediate fulfillment step before the user is granted an ownership license for the app.








Parameters












appId




string






The id of the app being ordered










userId




string






The unique id of the user that is ordering this app










type (optional)




string






The type for this order










customData (optional)




CustomData






A custom JSON object that you can create and attach to this order record






Returns

















Order






The newly created order






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/orders


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/orders \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'appId':'5565322ae4b0a70b13a4563b'," \
        "'userId':'abc'," \
        "'customData': {name: 'John Smith'}" \
     "}"


Sample Success Response


{ 
  "orderId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith"
  }, 
  "created": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "status": 
  { 
    "value": "pending"
  }
}


Sample Failure Response


{
  "code": 400,
  "errors":
  [
    {
      "field": "appId",
      "message": "An approved app with this id was not found"
    }
 ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Order

                                          
Retrieving an order returns a single, specific, order record. 








Parameters












orderId




string






The id of the order






Returns

















Order






A single order






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










404




Not Found






A order with this orderId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


GET https://market.openchannel.io/v2/orders/{orderId}


Sample Request


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


Sample Success Response


{ 
  "orderId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith 2", 
  }, 
  "created": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "status": 
  { 
    "value": "processing"
  }
}


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Orders

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








Parameters












query (optional)




string






A Query Document. Example: {“status.value”:”pending”} matches all the orders that are pending.










sort (optional)




string






A Sort Document. Example: {“created”:1} sorts the results by created date in ascending order










pageNumber(optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.















Order Pages






A page of orders






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/orders


Sample Response


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


Sample Success Response


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
      "orderId": "5463cee5e4b042e3e26f1e41",
      "appId": "5565322ae4b0a70b13a4563b", 
      "userId": "abc",
      "customData": 
      { 
        "name": "John Smith 2", 
      }, 
      "created": 1432695338702, 
      "lastUpdated": 1432695338702, 
      "status": 
      { 
        "value": "processing"
      }
    },
    {...},
    {...}
  ]
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Order Fields

                                          
Updating an order allows users to modify their orders.








Parameters












orderId




string






The id for this order










type (optional)




string






The type for this order










customData (optional)




CustomData






A custom JSON object that you can create and attach to this order record






Returns

















Order






The newly updated order






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The order is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


PATCH https://market.openchannel.io/v2/orders/{orderId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/orders/5463cee5e4b042e3e26f1e41 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d "{" \
        "'customData': {name: 'John Smith 2'}" \
     "}"


Sample Success Response


{ 
  "orderId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith 2", 
  }, 
  "created": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "status": 
  { 
    "value": "pending"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Order Status

                                          
Updating an order status allows admins or systems to set the status for an order.








Parameters












orderId




string






The id for this order










status




string






The new staus for this Order. Can be one of: “pending”, “processing”, “completed”, “cancelled”.










reason




string






The reason for the status change.






Returns

















Order






The newly updated order






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The order is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/orders/{orderId}/status


Sample Request


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


Sample Success Response


{ 
  "orderId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith 2", 
  }, 
  "created": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "status": 
  { 
    "value": "processing"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Order

                                          
Deletes an order.








Parameters












orderId




string






The id of the order






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










404




Not Found






An order with this orderId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


DELETE https://market.openchannel.io/v2/orders/{orderId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/orders/5565322ae4b0a70b13a4563b \
-X DELETE 


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Forms

                                  
Each formSubmission record is a JSON representation of form submissions made by users. This can be useful for tracking contact requests and leads.

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Create Form Submission

                                          
Creating an form submission for a particular form. This can be useful for tracking leads or contact form submissions.








Parameters












formId




string






The id of the form that this form submission belongs to










appId (optional)




string






The id of the App associated with this form submission










userId (optional)




string






The unique id of the user that is associated with this form submission










name (optional)




string






The name for this form submission










email (optional)




string






The email address associated with this form submission










submittedDate (optional)




long






The date for which the form submission has been submitted. The default is the current date.










formData (optional)




FormData






A custom JSON object that you can create and attach to this record






Returns

















FormSubmission






The newly created formSubmission






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/forms/{formId}/submissions


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'name':'John Smith'," \
        "'email':'jogn@smith.com'," \
        "'appId':'5565322ae4b0a70b13a4563b'," \
        "'userId':'abc'," \
        "'formData': {'message': 'I would like to se a demo'}" \
     "}"


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "status": 
  { 
    "value": "open"
  }
}


Sample Failure Response


{
  "code": 400,
  "errors":
  [
    {
      "field": "appId",
      "message": "An approved app with this id was not found"
    }
 ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Form Submission

                                          
Retrieving a form submission returns a single, specific record. 








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to be located






Returns

















FormSubmission






A single form submission






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










404




Not Found






A form submission with this formSubmissionId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


GET https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions/5463cee5e4b042e3e26f1e41


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "status": 
  { 
    "value": "open"
  }
}


Sample Failure Request


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
List Form Submissions

                                          
Listing form submissions returns Pages based on query and sort criteria. This is useful when displaying displaying form submissions on your marketplace.








Parameters












query (optional)




string






A Query Document. Example: {“status.value”:”open”} matches all the form submissions that are open.










sort (optional)




string






A Sort Document. Example: {“submittedDate”:1} sorts the results by submitted date in ascending order










pageNumber(optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.















Form Submission Pages






A page of orders






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/forms/{formId}/submissions


Sample Response


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions? \
  query={'status.value':'pending', 'appId':'5565322ae4b0a70b13a4563b'}& \
  sort={'created':1}& \
  userId=abc


Sample Success Response


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    {
      "formId": "contact-form",
      "formSubmissionId": "5463cee5e4b042e3e26f1e41",
      "appId": "5565322ae4b0a70b13a4563b", 
      "userId": "abc",
      "formData": 
      { 
        "message": "I would like to se a demo"
      }, 
      "submittedDate": 1432695338702, 
      "status": 
      { 
        "value": "open"
      }
    },
    {...},
    {...}
  ]
}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Form Submission

                                          
Allows for the updating of form submissions.








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to update










appId




string






The id of the App associated with this form submission










userId




string






The unique id of the user that is associated with this form submission










name




string






The name for this form submission










email




string






The email address associated with this form submission










formData (optional)




FormData






A custom JSON object that you can create and attach to this order record






Returns

















Form Submission






The newly updated form submission






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The form submission is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


PATCH https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/{formId}/submissions/5463cee5e4b042e3e26f1e41 \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'appId': '5565322ae4b0a70b13a4563b'," \
        "'userId': 'abc'," \
        "'formData': {'message': 'I would like to se a demo'}" \
     "}"


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "status": 
  { 
    "value": "open"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Form Submission Status

                                          
Updating a form submission status allows admins or systems to set the status for an form submission.








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to update










status




string






The new staus for this form submission. Can be one of: “open”, “closed”.










reason




string






The reason for the status change.






Returns

















Form Submission






The newly updated form submission






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The form submission is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}/status


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions/{5463cee5e4b042e3e26f1e41}/status \
  -X POST \
  -H "Content-Type: application/json" \
  -d "{" \
        "'status': 'closed'" \
     "}"


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "status": 
  { 
    "value": "closed"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Archive Form Submission

                                          
Updating a form submission status allows admins or systems to archive a form submission.








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to update






Returns

















Form Submission






The newly updated form submission






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The form submission is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}/archive


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions/5463cee5e4b042e3e26f1e41/archive \
  -X POST \
  -H "Content-Type: application/json"


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "archived": true,
  "archivedDate": 1432695339954
  "status": 
  { 
    "value": "closed"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Unarchive Form Submission

                                          
Updating a form submission status allows admins or systems to unarchive a form submission.








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to update






Returns

















Form Submission






The newly updated form submission






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The form submission is not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


POST https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}/unarchive


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/contact-form/submissions/5463cee5e4b042e3e26f1e41/unarchive \
  -X POST \
  -H "Content-Type: application/json"


Sample Success Response


{ 
  "formId": "contact-form",
  "formSubmissionId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "formData": 
  { 
    "message": "I would like to se a demo"
  }, 
  "submittedDate": 1432695338702, 
  "archived": false,
  "archivedDate": 1432695339954
  "status": 
  { 
    "value": "closed"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Form Submission

                                          
Deletes a form submission.








Parameters












formId




string






The id of the form that this form submission belongs to










formSubmissionId




string






The id of the form submission to remove






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






An form submission with this formSubmissionId was not found





















                                        

                                      

                                                                                    

                                                 

                                                    
Definition


DELETE https://market.openchannel.io/v2/forms/{formId}/submissions/{formSubmissionId}


Sample Request


curl --user {marketplaceId}:{secret} https://market.openchannel.io/v2/forms/my-contact-form/submissions/5565322ae4b0a70b13a4563b \
-X DELETE 


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Transactions

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
List Transactions

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


Parameters












query (optional)




string






A Query Document. Example: {“type”:”payment”} matches all the payment transactions.










sort (optional)




string






A Sort Document. Example: {“date”:-1} sorts the results by name in descending order










pageNumber (optional)




integer






The result set page number to be returned










limit (optional)




integer






The maximum number of results to return per page. The absolute maximum limit to the number of objects returned at one time is 100.






Returns

















Transaction Pages






Pages of transactions that match the query.






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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


 

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Transaction

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


Parameters












transactionId




string






The id of the transaction to be returned






Returns

















Transaction






The transaction.






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The transaction was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Transaction

                                          
Updates a transaction.


Parameters












transactionId




string






The id of the transaction to be removed










customData




CustomData






A custom JSON object to attach to this ownership record






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The transaction was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Transaction

                                          
Deletes a transaction.


Parameters












transactionId




string






The id of the transaction to be removed






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










404




Not Found






The transaction was not found










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


{}


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Custom Gateway

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Add Payment

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








Parameters












ownershipId




string






The id of the ownership record involved in this transaction










amount




integer






The total amount paid in cents










date (optional)




long






The date (in milliseconds) of when this payment was made










feeAmount (optional)




integer






The fee (in cents) paid to a payment processors or third parties to process this payment. Default is 0.










marketplaceAmount (optional)




integer






The amount (in cents) paid to the marketplace owner as a commission for the purchase of this app. Defaults based on the commission amount configured for this marketplace.










developerAmount (optional)




integer






The amount (in cents) paid to the owner of the app. Defaults based on the commission amount configured for this marketplace.










customData (optional)




CustomData






A custom JSON object to attach to this transaction






Returns

















Transaction






The newly created transaction






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










412




Precondition Failed






Payments must be enabled and ‘Custom’ must be selected as the gateway in order to use this API endpoint






 







                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Add Refund

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








Parameters












ownershipId




string






The id of the ownership record involved in this transaction










amount




integer






The total amount recovered in cents










date (optional)




long






The date (in milliseconds) of when this refund was made










feeAmount (optional)




integer






The fee (in cents) recovered from a payment processors or third party. Default is 0.










marketplaceAmount (optional)




integer






The amount (in cents) recovered from the marketplace owner as a commission for the purchase of this app. Defaults based on the commission amount configured for this marketplace.










developerAmount (optional)




integer






The amount (in cents) recovered from the owner of the app. Defaults based on the commission amount configured for this marketplace.










customData (optional)




CustomData






A custom JSON object to attach to this transaction






Returns

















Transaction






The newly created transaction






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method










412




Precondition Failed






Payments must be enabled and ‘Custom’ must be selected as the gateway in order to use this API endpoint











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Stripe Gateway

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


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


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


In order to user Stripe payment processing:


    

  1. You are required to setup and configure a Stripe account for your marketplace
    2. 

  2. Developers are required to setup and configure a Stripe account
    3. 

  3. Both yourself and Developers must be from a country that is supported by Stripe (see supported countries)
    4. 



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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Get Stripe Settings

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


Returns

















Stripe Settings






Stripe settings configured for this marketplace






Errors












404




Not Found






Stripe settings have not been setup for this marketplace










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Credit Cards

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


Parameters












userId




string






The unique id of the user retrieving their credit card details






Returns

















Cards






The credit cards associated with this user’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Add Credit Card

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








Parameters












userId




string






The id of the user adding their credit card










token




string






The Stripe token returned by the Stripe.js Stripe.card.createToken call










isDefault (optional)




boolean






Set to true if this should be set to be the default credit card






Returns

















Cards






The credit cards associated with this user’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Update Credit Card

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








Parameters












userId




string






The id of the user updating their credit card










cardId




string






The id of the card to be updated










isDefault (optional)




boolean






Set to true if this should be set to be the default credit card










address_city (optional)




string






The card holder’s city










address_country (optional)




string






The card holder’s country










address_line1 (optional)




string






The card holder’s street address










address_line2 (optional)




string






The card holder’s street address










address_state (optional)




string






The card holder’s city state/province










address_zip (optional)




string






The card holder’s zip/postal code






Returns

















Cards






The credit cards associated with this user’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Delete Credit Card

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








Parameters












userId




string






The id of the user removing their credit card










cardId




string






The id of the card to be removed






Returns

















Cards






The credit cards associated with this user’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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



Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Connect Developer Account

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








Parameters












developerId




string






The id of the developer connecting their Stripe account










redirectUrl




string






The URL to redirect this developer after they have connected their Stripe account






Returns

















Developer Token






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






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Get Developer Accounts

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


Parameters












developerId




string






The unique id of the developer retrieving their account details






Returns

















Accounts






The connected Stripe accounts associated with this developer’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method





                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Disconnect Developer Account

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








Parameters












developerId




string






The id of the developer disconnecting their Stripe account










stripeId




string






The id of the Stripe account to disconnect






Returns

















Accounts






The connected Stripe accounts associated with this developer’s account






Errors












400




Bad Request






Required parameters are missing, malformed or invalid










412




Precondition Failed






Payments must be enabled and ‘Stripe’ must be selected as the gateway in order to use this API endpoint










405




Method Not Allowed






You’re calling this API with an incorrect HTTP method











                                        

                                      

                                                                                    

                                                 

                                                    
Definition


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


Sample Request


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


Sample Success Response


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


Sample Failure Response


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Apps

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
App Version Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(App Version)






An array of app versions for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Version Page


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(App)






An array of apps for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Page


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App Version

                                          
Attributes












appId




int






The id of this app










name




string






The name of this app










type (optional)




string






The type for this app










safeName




array(string)






URL safe aliases that can be used to identify this app even after name changes. The current alias is always at position 0.










status




Status






The current status of this app version










parent (optional)




Parent






The attributes of the parent (live) app










developerId




string






The id of the developer that owns 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










attributes (optional)




JSON Object






A custom set of app attributes defined by the administrator and attached to this app










rating




integer






The average review rating for this app. Reviews are rated from 100 (one star) to 500 (five star)










reviewCount




integer






The number of approved reviews for this app.










created




long






The date (in milliseconds) that this app was created










customData (optional)




CustomData






A custom JSON object that you can create and attach to this app record










allow (optional)




Restrictions






Whitelists that restrict users from accessing this app










restrict (optional)




Restrictions






Blacklists that restrict users from accessing this app










version




integer






The version number representing changes to this app’s metadata. The app.version field helps OpenChannel keep track of the app’s metadata changes and is not actually representative of the version of the app itself. For keeping track of the app’s version we recommend creating a custom field in customData.










isLive (optional)




boolean






True if this is the live version of this app










isLatestVersion (optional)




boolean






True if this is the latest version of this app





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Version


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App

                                          
Attributes












appId




int






The id of this app










name




string






The name of this app










type (optional)




string






The type for this app










safeName




array(string)






URL safe aliases that can be used to identify this app even after name changes. The current alias is always at position 0.










status




Status






The current status of this app










developerId




string






The id of the developer that owns this app










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)










reviewCount




integer






The number of approved reviews for this app.










ownership (optional)




Ownership






If this app is owned by the requesting user, this field displays the ownership information for this app. This field exists only when userId is supplied to the method and the user owns (or previously owned) the app and cannot be part of query or sort criteria.










customData (optional)




CustomData






A custom JSON object that you can create and attach to this app record










allow (optional)




Restrictions






Whitelists that restrict users from accessing this app










restrict (optional)




Restrictions






Blacklists that restrict users from accessing this app










version




integer






The version number representing changes to this app’s metadata. The app.version field helps OpenChannel keep track of the app’s metadata changes and is not actually representative of the version of the app itself. For keeping track of the app’s version we recommend creating a custom field in customData.










attributes (optional)




JSON Object






A custom set of app attributes defined by the administrator and attached to this app










access (optional)




array(string)






A custom defined list of access requirements










randomize




integer






A random number that changes periodically and is used for achieving a random sort order when displaying apps










statistics




JSON Object






A field containing summary stats about the app and is specially designed to allow apps to be sorted by popularity. Each tracked statistic like views, downloads or custom statistics are available from within the statistics field by the following values:


    

  • 30Day refers to the popularity over a 30 day period. Sorting using a 30 day value is most useful with highly trafficked marketplaces.
    • 

  • 90Day refers to the popularity over a 90 day period. Sorting using a 90 day value is most useful when starting out or operating marketplaces with lower traffic volumes.
    • 

  • Total refers to the popularity over the life of the app. The total value is not recommended for sorting but could be useful when evaluating the overall popularity of an app.
    • 



NOTE: Stats with 0 totals may not be returned.






                                        

                                      

                                                                                    

                                                 

                                                    
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, 
  "reviewCount": 6, 
  "randomize": 164825247,
  "status": 
  { 
    "value": "approved", 
    "lastUpdated": 1432696823474, 
    "modifiedBy": "administrator", 
    "reason": "" 
  },
  "statistics":
  {
    "views":{"30day":0,"90day":0,"total":0},
    "downloads":{"30day":0,"90day":0,"total":0},
    "developerSales":{"30day":0,"90day":0,"total":0},
    "totalSales":{"30day":0,"90day":0,"total":0},
    "ownerships":{"30day":0,"90day":0,"total":0},
    "reviews":{"30day":0,"90day":0,"total":0}
  },
  "isLive": true }

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App Status

                                          
Attributes












value




string






The current status of the app. Can be: “approved” or “suspended”


    

  • Approved apps are changes that have been approved by marketplace administrators and are visible to marketplace users
    • 

  • Suspended apps were once approved but is now no longer visible to marketplace users
    • 













reason (optional)




string






Text describing the reason for the current status










lastUpdated




integer






The date (in milliseconds) of the latest update










modifiedBy




string






The person responsible for making the latest change to the status. Can be: “administrator” or “developer” or “system”


    

  • Administrator changes have been made by marketplace administrators
    • 

  • Developer changes have been made by a developer that owns this app
    • 

  • System changes have been made automatically by the system
    • 








                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Status


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App Version Status

                                          
Attributes












value




string






The current status of the app version. Can be: “pending” or “inReview” or “inDevelopment” or “approved” or “rejected”


    

  • InDevelopment app versions are drafts that have not yet been submitted to the marketplace for approval
    • 

  • Pending app versions are changes that have been submitted by developers for approval and are not visible to marketplace users
    • 

  • InReview app versions are locked from additional changes and are currently being reviewed by marketplace administrators
    • 

  • Approved app versions are changes that have been approved by marketplace administrators and are visible to marketplace users
    • 

  • Rejected app versions are changes that were rejected by marketplace administrators and are not visible to marketplace users
    • 













reason (optional)




string






Text describing the reason for the current status










lastUpdated




integer






The date (in milliseconds) of the latest update










modifiedBy




string






The person responsible for making the latest change to the status. Can be: “administrator” or “developer” or “system”


    

  • Administrator changes have been made by marketplace administrators
    • 

  • Developer changes have been made by a developer that owns this app
    • 

  • System changes have been made automatically by the system
    • 








                                        

                                      

                                                                                    

                                                 

                                                                                                    

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Model

                                          
Attributes












modelId




string






The id that uniquely identifies this model










type




string






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


    

  • Free models don’t require payment to be installed
    • 

  • Single models require one-time payment in order to be installed
    • 

  • Recurring models require a recurring subscription payment in order to be installed and retain ownership
    • 













price




integer






The price of this app in cents.  The default value is 0.










license




string






The license model type. The default value is “single”.


    

  • Single licenses only apply to only a single user or organization that installed the app
    • 













customData (optional)




CustomData






A custom JSON object that is attached to this model










trial




integer






The maximum number of free trial days available.  The default value is 0.










currency




string






The ISO 4217 currency code for this price.  The default value is “USD”.










commission




integer






The marketplace commission percentage applied to this app’s model. The default is the marketplace’s configured commission percentage. The value includes two additional digits to represent fractions of a percent. Example: A value of 3050 is 30.5%.










feePayer




string






The payee that will be paying for any payment processing fees. Can be: “developer” or “marketplace”. The default value is “marketplace”.


    

  • Developer will be responsible for paying payment processing fees from their payout
    • 

  • Marketplace will be responsible for paying payment processing fees from their payout
    • 













billingPeriod




string






The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. Can be: ‘daily’, ‘weekly’ , ‘monthly’ or ‘annually’. The default value is ‘monthly’ for recurring models.


    

  • Daily app subscriptions require payment after a certain number of days (specified by billingPeriodUnit ) in order to maintain the subscription
    • 

  • Weekly app subscriptions require payment after a certain number of weeks (specified by billingPeriodUnit ) in order to maintain the subscription
    • 

  • Monthly app subscriptions require payment after a certain number of months (specified by billingPeriodUnit ) in order to maintain the subscription
    • 

  • Annually app subscriptions require payment after a certain number of years (specified by billingPeriodUnit ) in order to maintain the subscription
    • 













billingPeriodUnit




type






The billingPeriod along with the billingPeriodUnit make up the time between billing cycles. The default value is 1 for recurring models.





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Model


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Parent

                                          
Attributes












status




Status






The status of the parent (live) app.





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Parent


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Restrictions

                                          
Attributes












own (optional)




JSON Object






A JSON object describing the restriction to owning this app










view (optional)




JSON Object






A JSON object describing the restriction to viewing this app





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Blacklist


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


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


Sample Whitelist


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


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
App Field Update

                                          
Attributes












field




string






The field to be updated










value




any






The new value for this field





                                        

                                      

                                                                                    

                                                 

                                                    
Sample App Field Update


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
User

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


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


Attributes












userId




string






The unique id of the user










type (optional)




string






The type for this user










created




long






The date in milliseconds when this user was created










username (optional)




string






The username of this user










name (optional)




string






The name of this user










email (optional)




string






This user’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this user record





                                

                              

                                                                    

                                         

                                            
Sample User


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

                                        

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
User 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(UserAccount)






An array of userAccounts for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample User Account Page


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "userAccountId": "abc", 
      "userId": "123", 
      "name": "John",
      ...
    },
    {...},
    {...}
  ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
User Account

                                          
Each user account is a JSON representation of an end-user account for a user who belongs to an organization or a company which is represented by the User object.


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


Attributes












userAccountId




string






The unique id of the user account










userId




string






The unique id of the user (organization) that this user account belongs to










email (optional)




string






The contact email address










name (optional)




string






The name of the user account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this user record





                                        

                                      

                                                                                    

                                                 

                                                    
Sample User Account


{ 
  "userAccountId": "abc", 
  "userId": "123", 
  "email": "me@me.com",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
User Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(User)






An array of users for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample User Page


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Developer

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


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








Attributes












developerId




string






The unique id of the developer










type (optional)




string






The type for this developer










username (optional)




string






The username of this developer










name (optional)




string






The name of this developer










email (optional)




string






This developer’s email address










customData (optional)




CustomData






A custom JSON object that you can create and attach to this developer record










created




long






The date (in milliseconds) that this developer was created











                                

                              

                                                                    

                                         

                                            
Sample Developer


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

                                        

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Developer 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(DeveloperAccount)






An array of developerAccounts for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Developer Account Page


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "developerAccountId": "abc", 
      "developerId": "123", 
      "name": "John",
      ...
    },
    {...},
    {...}
  ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Developer Account

                                          
Each developer account is a JSON representation of an end-user account for a developer who belongs to an organization or a company which is represented by the Developer object.


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


Attributes












developerAccountId




string






The unique id of the developer account










developerId




string






The unique id of the developer (organization) that this developer account belongs to










email (optional)




string






The contact email address










name (optional)




string






The name of this developer account










customData (optional)




CustomData






A custom JSON object that you can create and attach to this user record





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Developer Account


{ 
  "developerAccountId": "abc", 
  "developerId": "123", 
  "email": "me@me.com",
  "customData": 
  { 
    "interests": ["Surfing", "Kittens"]
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Developer Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(Developer)






An array of developers for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Developer Page


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Statistics

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Total

                                          
Attributes












start




long






The time (in milliseconds) to start the sum










end




long






The time (in milliseconds) to end the sum










totals




JSON Object






A JSON object containing the fields as keys and results as values










apps




JSON Object






A JSON object containing the appIds of the participating apps as keys and Totals as values





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Total


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Files

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
File

                                          
Attributes












fieldId




string






The id of this file










name




string






The name of this file










size




integer






The size of this file










contentType (optional)




string






The internet media type of this file










isPrivate (optional)




boolean






If true, this file will be protected as a private file and require the generation of a signed URL in order to download using the Download File API. The default is false.










hash (optional)




Hash






The hashes requested for the file.










uploadDate




long






The date (in milliseconds) when this file was uploaded










fileUrl (optional)




string






The URL for this file. The fileUrl is not returned for private files since they require an additional API call in order to get a signed URL.










virusScan




Virus Scan






The virus scan results for this file.










mimeCheck




string






The mime type validation check to see if the extension of this file matches it’s content. Can be PASSED or FAILED





                                        

                                      

                                                                                    

                                                 

                                                    
Sample File


{
  "uploadDate": 1457710762784,
  "fileId": "59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv", 
  "name": "book.csv", 
  "contentType": "application/octet-stream", 
  "size": 16206, 
  "fileUrl": "//cdn.openchannel.com/files/59b0100dca753d5ed65578bg/public/56e2e6a91707a57c3f593499.csv",
  "virusScan": {
    "started": 1457710762784,
    "finished": 1457710769567,
    "status": "CLEAN", 
    "foundViruses": []
  },
  "mimeCheck": "PASSED"
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
File Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(File)






An array of apps for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample File Page


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Hash

                                          
Attributes












MD5




string






The MD5 hash for this uploaded file.










SHA-1




string






The SHA-1 hash for this uploaded file.










SHA-256




string






The SHA-256 hash for this uploaded file.





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Hash


{
  "SHA-256": "D87B252470F05A9904E80A868897CA08CA0CB8F85037ADEE86AA0F0C0A3BC9AA" 
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Virus Scan

                                          
Attributes












status




string






The status of this scan. Can be NOT_SCANNED, CLEAN or DIRTY










started (optional)




long






The date (in milliseconds) when this file started it’s scan










finished (optional)




long






The date (in milliseconds) when this file finished it’s scan










foundViruses




array(Found Virus)






The list of viruses found in this file





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Virus Scan


{
  "started": 1457710762784,
  "finished": 1457710769567,
  "status": "CLEAN", 
  "foundViruses": []
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Found Virus

                                          
Attributes












fileName




string






The name of the file










virusName




string






The name of the virus





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Found Virus


{
  "fileName": "jacks.docx",
  "virusName": "H237 Worm"
}

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Ownership

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Ownership

                                          
Attributes












ownershipId




string






The id of this ownership










date




long






The date (in milliseconds) of when this app was owned










appId




string






The id of the app that is owned










userId




string






The id of the user that owns this app










developerId




string






The id of the developer for this app










ownershipType




string






The current ownership type for this app. Can be: “full”, “subscription” or “trial”


    

  • Full ownership is a perpetual license that doesn’t require any additional payment
    • 

  • Subscription ownership requires payment on a recurring bases to maintain this ownership license
    • 

  • Trial ownership is a temporary, free license that eventually expires
    • 













ownershipStatus




string






The current ownership status for this app. Can be: “pending”, “active”, “uninstalled” or “cancelled”


    

  • Pending status signifies that the license is not yet valid and the app is not yet installed
    • 

  • Active status signifies that the license is valid and the app is installed
    • 

  • Uninstalled status signifies that the license is no longer valid and the user has uninstalled the app. Apps with a Free or Single model may be re-installed without cost
    • 

  • Cancelled signifies that the license is no longer valid and the user must re-purchase a license to re-install the app
    • 













uninstallDate (optional)




long






The date (in milliseconds) of when this app was uninstalled










expires (optional)




long






The date (in milliseconds) of when this app ownership expires










model




Model






The model for this ownership










customData (optional)




CustomData






A custom JSON object to attach to this ownership record





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Ownership


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Ownership Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(Ownership)






An array of ownership for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Ownership Page


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Reviews

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


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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Review Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(Review)






An array of reviews for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Review Pages


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Review

                                          
Attributes












reviewId




string






The id of this review










headline




string






The review’s headline. Limited to 50 characters.










description




string






The review’s description. Limited to 2000 characters.










rating




integer






The rating given within this review. The rating is represented as an integer between 100 and 500 (1 – 5 stars)










status




Review Status






The status of this Review










reportDate




long






The date (in milliseconds) this Review was posted










appId




string






The Id of the App that owns this review










appName




string






The name of the App that owns this review










userId




string






The id of the User that posted this review










userAccountId (optional)




string






The id of the UserAccount that posted this review










type (optional)




string






The type for this review










customData (optional)




CustomData






A custom JSON object that you can create and attach to this review record










user (optional)




User






The details of the user organization that posted this review










userAccount (optional)




UserAccount






The details of the individual user that posted this review





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Review


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Review Status

                                          
Attributes












value




string






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


    

  • Pending reviews have been submitted to the marketplace but are not yet visible to users
    • 

  • Approved reviews have been approved by a marketplace administrator and can be viewed by users
    • 

  • Flagged reviews have been identified by the system as possibly being spam or containing profanity
    • 

  • Spam reviews have been marked as spam by marketplace administrators
    • 













reason (optional)




string






Text describing the reason for the current status





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Review Status


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
CustomData

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


    

  • Field names cannot contain dots (.) or null characters
    • 

  • Field names cannot start with a dollar sign ($)
    • 

  • Field names cannot exceed 50 characters
    • 

  • The entire customData object cannot exceed 8 megabytes
    • 

  • The customData object cannot exceed 50 levels of nested objects
    • 


                                

                              

                                                                    

                                         

                                            
Sample CustomData


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

                                        

                                      

                                      
                            

                        

                                                                    

                            


                              

                                

                                  
Stripe Gateway

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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Stripe Settings

                                          
Attributes












clientId




string






The clientId of the Stripe connected Stripe account for this marketplace










publishableKey




string






The publishableKey of the Stripe connected Stripe account for this marketplace





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Stripe Settings


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Cards

                                          
Attributes












userId




string






The id of the user that owns these cards










cards




array(Card)






An array of credit cards for this user’s account





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Cards


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Card

                                          
Attributes












cardId




string






The id for this credit card










isDefault




boolean






True if this is the default credit card










exp_year




integer






The four digit expiration year










exp_month




integer






The two digit expiration month










last4




string






The last 4 digits of the credit card number










brand




string






The brand of the credit card. Example: Visa










name




string






The card holder’s full name










address_city (optional)




string






The card holder’s city










address_country (optional)




string






The card holder’s country










address_line1 (optional)




string






The card holder’s street address










address_line2 (optional)




string






The card holder’s street address










address_state (optional)




string






The card holder’s city state/province










address_zip (optional)




string






The card holder’s zip/postal code





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Card


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
DeveloperToken

                                          
Attributes












developerId




string






The id of the developer connecting their Stripe account










expires




long






The time (in milliseconds) when this URL expires










targetUrl




string






The URL that this developer can use to connect their Stripe account





                                        

                                      

                                                                                    

                                                 

                                                    
Sample DeveloperToken


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Account

                                          
Attributes












stripeId




string






The id of the Stripe account










accountName




string






The name of the Stripe account










country




string






The country for this Stripe account










defaultCurrency




string






The default currency for this Stripe account





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Account


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Accounts

                                          
Attributes












developerId




string






The id of the developer










accounts




array(Account)






An array of connected Stripe accounts





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Accounts


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Event

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


Attributes


 












eventId




string






The id of the this event










createdDate




long






The date (in millis) of when this event occurred










message




string






A description of the event










eventType




string






The event type. See Webhooks.










marketplaceId




string






The id of the marketplace that produced this event










developer (optional)




Developer






The developer associated with this event. This value is only provided for “developer.created”, “developer.updated”, “developer.removed”, “developer.paymentDetailsRequired” events.










app (optional)




App






The app associated with this event. This value is only provided for “app.created”, “app.updated”, “app.removed”, “app.transferred”, “app.submitted”, “app.approved”, “app.suspended”, “app.unsuspended”, “app.rejected”, “app.inReview” events.










appVersion (optional)




AppVersion






The app version associated with this event. This value is only provided for “appVersion.created”, “appVersion.updated”, “appVersion.removed” events.










review (optional)




Review






The review associated with this event. This value is only provided for “review.created”, “review.updated”, “review.approved”, “review.spam”, “review.removed” events.










file (optional)




File






The file associated with this event. This value is only provided for “file.created”, “file.scanned”, “file.removed” events.










user (optional)




User






The user associated with this event. This value is only provided for “user.created”, “user.updated”, “user.removed”, “user.invalidPaymentDetails”, “user.paymentDetailsRequired” events.










ownership (optional)




Ownership






The ownership associated with this event. This value is only provided for “app.installed”, “app.uninstalled”, “payment.required”, “ownership.expired” events.










payment (optional)




Payment






The payment associated with this event. This value is only provided for “payment.complete”, “payment.refunded” events.










permission (optional)




Permission






The permission associated with this event. This value is only provided for “permission.added”, “permission.removed” events.










target




string






The URL that is the target of this webhook event










signature




string (optional)






The HMAC SHA256 signature generated from the content of this webhook events (excluding the signature field itself)





                                

                              

                                                                    

                                         

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

                                        

                                      

                                      
                            

                        

                                                                    

                            


                              

                                

                                  
Transactions

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


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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Transaction

                                          
Attributes












transactionId




string






The id for this transaction










ownershipId




string






The id for the ownership associated with this transaction










appId




string






The id of the app involved with this transaction










developerId




string






The id of the developer involved with this transaction










userId




string






The id of the user making the transaction










date




long






The date (in millis) of when this transaction occurred










type




string






The type for this transaction. Can be: “payment” or “refund”


    

  • Payment transactions indicate that money was received to purchase an app
    • 

  • Refund transactions indicate that a payment was refunded for an app
    • 













amount




integer






The total amount paid in cents










customData (optional)




CustomData






A custom JSON object that you can create and attach to this transaction record










feeAmount (optional)




integer






The total amount paid to payment processing fees in cents










marketplaceAmount (optional)




integer






The total amount paid to the marketplace owner in cents










developerAmount (optional)




integer






The total amount paid to the developer in cents





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Transaction


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Transaction Pages

                                          
Attributes












pages




integer






The total number of pages available for this result set










count




integer






The total number of results










pageNumber




integer






The current page number for this result set










list




array(Transaction)






An array of transactions for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Transaction Pages


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Permission

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


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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Access

                                          
Attributes












appId




string






The id for the app associated with this permission










userId




string






The id of the user that has agreed this level of access










date




long






The date (in millis) of when permission was last given










access




array(string)






The access list outlining the access requirements










isValid




boolean






True if this access level is still valid. Will return false if the app’s access requirements change and permission must be granted again.





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Access


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

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Orders

                                  
Each order record is a JSON representation of an order placed for an app by a user and describes the details of the prospective transaction.


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

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Order

                                          
Attributes












orderId




string






The id of this order










appId




string






The id of the app being ordered










userId




string






The unique id of the user that is ordering this app










type (optional)




string






The type for this order










status




Order Status






The status of this Order










customData (optional)




CustomData






A custom JSON object that you can create and attach to this order record










created




long






The date (in milliseconds) this Order was created










lastUpdated




long






The date (in milliseconds) this Order was last updated





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Order


{ 
  "orderId": "5463cee5e4b042e3e26f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "customData": 
  { 
    "name": "John Smith", 
    "icon": "https://s3.amazonaws.com/cloudexchange-uat/55653202e4b0a70b13a4562d.jpg"
  }, 
  "created": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "status": 
  { 
    "value": "pending"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Order 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(Order)






An array of orders for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Order Pages


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

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Order Status

                                          
Attributes












value




string






The current status value. Can be: ‘pending’, ‘processing’, ‘completed’ or ‘cancelled’


    

  • Pending orders have not yet been processed
    • 

  • Processing orders currently being evaluated
    • 

  • Completed orders have been validated and executed
    • 

  • Cancelled orders are terminated and will not be executed
    • 













reason (optional)




string






Text describing the reason for the current status





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Order Status


{ 
  "value": "pending",
  "reason": "", 
}

                                                

                                              

                                              
                                    

                                

                                                                            

                            


                              

                                

                                  
Forms

                                  
Each form submission record is a JSON representation of a form that was submitted and describes the details of the prospective lead or contact request.


The content of a form submission is within the formData object. When creating or updating a form submission, the formData object can be set to hold fields and arrays which gives you the flexibility to completely customize the structure of your form submission. The OpenChannel platform will automatically handle your custom form submission structure based on the fields specified for the form.

                                

                              

                                                                    

                                         

                                                                                    

                                      

                                      
                            

                        

                                                        

                                    


                                      

                                        

                                          
Form Submission

                                          
Attributes












formId




string






The id of the form that this form submission belongs to










formSubmissionIdId




string






The id of the form submission










name




string






The name for this form submission










email




string






The email address associated with this form submission










appId




string






The id of the App associated with this form submission










userId




string






The unique id of the user that is associated with this form submission










status




Form Submission Status






The status of this Form Submission










formData (optional)




FormData






A custom JSON object that you can create and attach to this record










submittedDate




long






The date (in milliseconds) this form submission was submitted










archived




boolean






True if this form submission is archived










archivedDate




long






The date (in milliseconds) this form submission was archived





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Form Submission


{ 
  "formId": "5463cee5e4b042e3e26f1463",
  "formSubmissionId": "5463cee5e4b042e3213f1e41",
  "appId": "5565322ae4b0a70b13a4563b", 
  "userId": "abc",
  "name": "John Doe",
  "name": "john@doe.com",
  "formData": 
  { 
    "company": "John Smith Inc", 
    "message": "I would like a demo"
  }, 
  "submittedDate": 1432695338702, 
  "lastUpdated": 1432695338702, 
  "archived": false,
  "status": 
  { 
    "value": "open"
  }
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Form Submission 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(Form Submissions)






An array of form submissions for the current page





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Order Pages


{ 
  "count": 8, 
  "pages": 1, 
  "pageNumber": 1, 
  "list": 
  [ 
    { 
      "formId": "5463cee5e4b042e3e26f1e41", 
      "formSubmissionId": "5463cee5e4b042e3e26f1e41", 
      ...
    },
    {...},
    {...}
  ]
}

                                                

                                              

                                              
                                    

                                

                                                                

                                    


                                      

                                        

                                          
Form Submission Status

                                          
Attributes












value




string






The current status value. Can be: ‘open’ or ‘closed’


    

  • Open form submissions have not yet been processed
    • 

  • Closed form submissions have already been evaluated
    • 













reason (optional)




string






Text describing the reason for the current status





                                        

                                      

                                                                                    

                                                 

                                                    
Sample Order Status


{ 
  "value": "open",
  "reason": "", 
}