InPlayer API (2.0.0)

Download OpenAPI specification:Download

INTRODUCTION

InPlayer equips you to run a detailed subscription business model, to build and grow your consumer base, and drive significant revenues. Our paywall supports recurring payments and billing cycles, consumer acquisition, subscriber lifecycle management, and provides you with consumer retention CRM tools.

Once you create an InPlayer Merchant Account, you are entitled to using our InPlayer dashboard for publishing, managing, and selling your premium content. Moreover, you can always integrate with our APIs for a full custom integration..

INPLAYER API

The InPlayer API follows the REST architectural style and uses standard HTTP response codes to indicate success requests (2xx) or API errors (4xx, 5xx). Each of the InPlayer Core Resources (Accounts & Authentication, Asset & Access, Payments & Subscriptions, Vouchers & Promotions, Branding, Restrictions & Rules, Reporting, Analytics, and Features) has their own URL and each of the operations involved (POST, PUT, PATCH, GET, and DELETE) carries a specific meaning like creating, updating, fetching, deleting data, and much more.

All API requests should contain Content-Type:application/x-www-form-urlencoded header. The responses are always returned in JSON object(s), both for the successful requests and the failed attempts (errors).

DOCS TERMINOLOGY

The following section defines the domain language used across our platform. Proceed reading to introduce yourself to the terms employed for each of our Core Resources before you start working on your custom integration.

Accounts and Account Types

Term Explanation
merchant The Merchants are those who have ownership of the premium content.
consumer The Consumers are those who can view or buy the premium content.
customer The Customers are those who have made at least one purchase.
uuid Stands for the Unique Identifier of the Merchant. You can find it on the InPlayer's dashboard at the Account Details section as Account ID.

Items/Assets and Item Types

Term Explanation
items The digital Assets that Merchants can protect and sell. Asset is an Item with applied pricing and access options.
item_type The type of the digital content that can be created in the InPlayer platform. According to the type of the premium content, we distinguish between a few item types. Currently, we support HTML/Text (where you can store HTML code or any IFRAME code), video, file, and RSS type of asset.
content The content of the Item is the premium content that you can store and protect. Once the Customer has access to the Item, they can view the content.
metadata An unlimited key-value store containing additional info of the Item concerned.

Access Types

Term Explanation
access_type The supported types of granting access in the system (pay-per-view and subscription).
period The period of the access entitlement that consumers get after purchasing the asset.

Access Fees

Term Explanation
access_fee The applied access_type and price to an Item.

Items Packages

Term Explanation
package The Packages are a collection of multiple Items (a group of Items). You can set up a Package Access Fee as an additional pricing option for Items that are part of a given Package. Once the Customer buys the Package Access Fee, they will have access to every Item that belongs to that Package.

API ENVIRONMENTS

To make the API as explorable as possible, we have two different environments for production related and testing purposes. There is no switch for changing between modes, so just refer to the URL you need.

ERRORS

InPlayer uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with InPlayer's servers.

Not all errors map cleanly onto HTTP response codes, however. For instance, when a request is valid but does not complete successfully (e.g. if asset access is not found), we return a 402 error code.

List of status codes

Status code Explanation
200 OK Everything worked as expected.
201 Created The resource has been created.
202 Accepted The request has been accepted for processing but the processing has not been completed.
204 No Content The server has fulfilled the request but does not need to return an entity-body.
400 Bad Request The request was unacceptable often due to omission of a required parameter.
401 Unauthorized No valid access token provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource does not exist.
409 Conflict The request conflicts with another request.
429 Too Many Requests Too many requests have been sent to the API in a short amount of time. We recommend using exponential backoff for your requests.
500, 502, 503, 504 Server Errors Something went wrong on InPlayer's end.

V2

All operations related to vouchers

Patch voucher

Authorizations:
bearerAuth
path Parameters
id
required
integer

Unique voucher ID

Request Body schema: application/x-www-form-urlencoded
code
string

The voucher's content

name
string

The name of the voucher

discount
integer <int64>

Discount amount

rebill_discount
integer <int64>

Discount rebill amoun

usage_limit
integer <int64>

Usage limit

discount_duration
integer <int64>

Discount duration

discount_period
string
Enum: "once" "repeating" "forever"

Discount period type

start_date
string

Voucher start date

end_date
string

Voucher end date

Responses

Request samples

curl -X PATCH https://services.inplayer.com/v2/vouchers/{id} \
    -H "Authorization:Bearer <token>" \
    -d name="Foo bar" \
    -d discount=50

Response samples

Content type
application/json
{
  • "id": 14,
  • "name": "50% discount",
  • "discount": 50,
  • "rebill_discount": 50,
  • "start_date": "2018-08-23T00:00:00.000Z",
  • "end_date": "2018-09-30T00:00:00.000Z",
  • "code": "F00B4R!@",
  • "usage_limit": 10,
  • "usage_counter": 10,
  • "discount_period": "once",
  • "discount_duration": 5
}

Get gift vouchers

Authorizations:
bearerAuth
query Parameters
page
integer >= 1

Page number of the results

size
integer >= 1

Number of results in a page

Responses

Request samples

curl https://services.inplayer.com/vouchers/gifts?page=1&limit=15 \
  -H "Authorization: Bearer <token>"

Response samples

Content type
application/json
{
  • "total": 25,
  • "page": 30,
  • "size": 25,
  • "collection": [
    ]
}

Get gift voucher

Authorizations:
bearerAuth
path Parameters
id
required
integer

Unique gift voucher ID

Responses

Request samples

curl https://services.inplayer.com/v2/vouchers/gifts/{id} \
    -H "Authorization:Bearer <token>"

Response samples

Content type
application/json
{
  • "id": 14,
  • "code": "F00B4R!@",
  • "item_title": "The Gift Asset",
  • "item_id": 21,
  • "buyer_email": "buyer_email@inpalyer.com",
  • "receiver_email": "receiver_email@inpalyer.com",
  • "is_used": true,
  • "access_fee_id": 17,
  • "access_fee_description": "The description of the purchased access fee",
  • "amount": 5,
  • "currency": "USD"
}

V1

All operations related to vouchers

Creates a voucher code

Authorizations:
bearerAuth
Request Body schema: application/x-www-form-urlencoded
One of
name
required
string

Voucher name

discount
required
integer [ 1 .. 100 ]

Discount amount in percentage

start_date
required
string <date-time>

Voucher is valid from this date forward

end_date
string <date-time>

Voucher validation ends on this date

code
string >= 5

Code provided by the merchant instead of generating it automatically

length
integer >= 1

Code length

prefix
string

Code prefix

suffix
string

Code suffix

usage_limit
integer

Limit the number of times for voucher usage

discount_period
string
Enum: "once" "repeating" "forever"

In case this voucher is used for a subscription, you can use a discount period for the recurrent payments

discount_duration
integer

In case the discount_period is repeating this field is required, for number of months to repeat the discount

Array of objects

Rules collection

Responses

Request samples

curl -X POST https://services.inplayer.com/vouchers \
    -H 'Authorization: Bearer <token>' \
    -d name='Voucher title' \
    -d length=7 \
    -d perfix=AB17 \
    -d perfix=BA17 \
    -d discount=30 \
    -d start_date=2017-01-10 \
    -d end_date=2017-03-12 \
    -d usage_limit=50

Response samples

Content type
application/json
Example
{
  • "id": 14,
  • "name": "50% discount",
  • "discount": 50,
  • "start_date": "2018-08-23T00:00:00.000Z",
  • "end_date": "2018-09-30T00:00:00.000Z",
  • "code": "F00B4R!@",
  • "length": 10,
  • "prefix": "foo-",
  • "suffix": "-bar",
  • "usage_limit": 10,
  • "discount_period": "once",
  • "discount_duration": 5,
  • "rules": [
    ]
}

Get vouchers

Authorizations:
bearerAuth
query Parameters
search
Array of strings
Example: search=id:123&search=name:Foo

Search parameters

page
integer >= 1

Page

Responses

Request samples

curl https://services.inplayer.com/vouchers?page=1&limit=15 \
    -H 'Authorization:Bearer <token>'

Response samples

Content type
application/json
{
  • "collection": [
    ],
  • "total": 100,
  • "page": 2,
  • "offset": 15,
  • "limit": 15
}

Get voucher details

Authorizations:
bearerAuth
path Parameters
id
required
integer

Voucher id

Responses

Request samples

curl https://services.inplayer.com/vouchers/{id} \
    -H 'Authorization:Bearer <token>'

Response samples

Content type
application/json
Example
{
  • "id": 14,
  • "name": "50% discount",
  • "discount": 50,
  • "start_date": "2018-08-23T00:00:00.000Z",
  • "end_date": "2018-09-30T00:00:00.000Z",
  • "code": "F00B4R!@",
  • "length": 10,
  • "prefix": "foo-",
  • "suffix": "-bar",
  • "usage_limit": 10,
  • "discount_period": "once",
  • "discount_duration": 5,
  • "rules": [
    ]
}

Update voucher

Authorizations:
bearerAuth
path Parameters
id
required
integer

Voucher id

Request Body schema: application/x-www-form-urlencoded
One of
name
required
string

Voucher name

discount
required
integer [ 1 .. 100 ]

Discount amount in percentage

start_date
required
string <date-time>

Voucher is valid from this date forward

end_date
string <date-time>

Voucher validation ends on this date

code
string >= 5

Code provided by the merchant instead of generating it automatically

length
integer >= 1

Code length

prefix
string

Code prefix

suffix
string

Code suffix

usage_limit
integer

Limit the number of times for voucher usage

discount_period
string
Enum: "once" "repeating" "forever"

In case this voucher is used for a subscription, you can use a discount period for the recurrent payments

discount_duration
integer

In case the discount_period is repeating this field is required, for number of months to repeat the discount

Array of objects

Rules collection

Responses

Request samples

curl -X PUT https://services.inplayer.com/vouchers/{id} \
    -H 'Authorization: Bearer <token>' \
    -d name='Voucher title' \
    -d discount=50 \
    -d start_date=2017-01-10 \
    -d end_date=2017-05-10 \
    -d usage_limit=100

Response samples

Content type
application/json
Example
{
  • "id": 14,
  • "name": "50% discount",
  • "discount": 50,
  • "start_date": "2018-08-23T00:00:00.000Z",
  • "end_date": "2018-09-30T00:00:00.000Z",
  • "code": "F00B4R!@",
  • "length": 10,
  • "prefix": "foo-",
  • "suffix": "-bar",
  • "usage_limit": 10,
  • "discount_period": "once",
  • "discount_duration": 5,
  • "rules": [
    ]
}

Delete voucher

Authorizations:
bearerAuth
path Parameters
id
required
integer

Voucher id

Responses

Request samples

curl -X DELETE https://services.inplayer.com/vouchers/{id} \
  -H 'Authorization:Bearer <token>'

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "Invalid auth token"
}

Create new voucher with rule type

Creates a new voucher with the corresponding rule type

Authorizations:
bearerAuth
path Parameters
id
required
integer

Voucher id

rule_type
required
string
Enum: "assets" "packages" "emails"

Voucher's rule type can be one of the provided examples

Request Body schema: application/x-www-form-urlencoded
value
required
integer

Value of usable vouchers

Responses

Request samples

curl -X POST https://services.inplayer.com/vouchers/{id}/{rule_type} \
    -H 'Authorization: Bearer <token>' \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d value=160

Response samples

Content type
application/json
{
  • "id": 123,
  • "message": "Voucher rule was successfully added.",
  • "code": 200
}

Voucher discount price

Authorizations:
bearerAuth
Request Body schema: application/x-www-form-urlencoded
voucher_code
required
string

Voucher code

access_fee_id
integer

Access fee id

item_id
integer

Item id

Responses

Request samples

curl -X POST https://services.inplayer.com/vouchers/discount \
    -H 'Authorization: Bearer Access-Token' \
    -d voucher_code=FOOrGmv60pT \
    -d access_fee_id=134 \
    -d item_id=1

Response samples

Content type
application/json
{
  • "amount": 20
}