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.

Authentication

bearerAuth

You can create a JSON Web Token (JWT) via the authenticate endpoint. Usage format: Bearer <JWT>

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

V2

All operations related to vouchers

Patch voucher

Authorizations:
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

201

Patched asset

401

Unauthorized

403

Invalid privileges

422

Cannot create resource

patch /v2/vouchers/{id}

Staging Server

https://staging-v2.inplayer.com/v2/vouchers/{id}

Production Server

https://services.inplayer.com/v2/vouchers/{id}

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "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
}

V1

All operations related to vouchers

Creates a voucher code

Authorizations:
Request Body schema: application/x-www-form-urlencoded
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

rules
Array of objects

Rules collection

Responses

200

Discounted price

401

Unauthorized

403

Invalid privileges

422

Cannot create resource

post /vouchers

Staging Server

https://staging-v2.inplayer.com/vouchers

Production Server

https://services.inplayer.com/vouchers

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "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:
query Parameters
search
Array of strings
Example: search=id%3A123,name%3AFoo

Search parameters

page
integer >= 1

Page

Responses

200

Voucher collection

401

Unauthorized

403

Invalid privileges

get /vouchers

Staging Server

https://staging-v2.inplayer.com/vouchers

Production Server

https://services.inplayer.com/vouchers

Request samples

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

Response samples

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

Get voucher details

Authorizations:
path Parameters
id
required
integer

Voucher id

Responses

200

Voucher details

401

Unauthorized

403

Invalid privileges

404

Resource not found

get /vouchers/{id}

Staging Server

https://staging-v2.inplayer.com/vouchers/{id}

Production Server

https://services.inplayer.com/vouchers/{id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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:
path Parameters
id
required
integer

Voucher id

Request Body schema: application/x-www-form-urlencoded
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

rules
Array of objects

Rules collection

Responses

200

Updated voucher

401

Unauthorized

403

Invalid privileges

404

Resource not found

422

Cannot create resource

put /vouchers/{id}

Staging Server

https://staging-v2.inplayer.com/vouchers/{id}

Production Server

https://services.inplayer.com/vouchers/{id}

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "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":
    [