NAV
json

Introduction

  _____                   _
 |  __ \            /\   | |
 | |__) | __ ___   /  \  | |__   ___  _ __   ___
 |  ___/ '__/ _ \ / /\ \ | '_ \ / _ \| '_ \ / _ \
 | |   | | | (_) / ____ \| |_) | (_) | | | | (_) |
 |_|   |_|  \___/_/    \_\_.__/ \___/|_| |_|\___/

Welcome to the ProAbono API Live documentation.

API Live is lightweight and straigtforward. It’s designed to craft your end-users experience in a few hours.

ProAbono is organized around a RESTful Architecture.
Note that this API is designed to be used from a server to a server, and NOT from a client to server in javascript. This is very important for security purpose.

Core concepts

Getting Started

  1. Sign up.
  2. Get your API Keys and Endpoints from “My Profile” / Integration.
  3. Try it out! Create your first customer.

Your First Requests

POST /v1/Customer
Accept: application/json
Accept-Encoding: gzip, deflate, compress

{
    Email: 'john@doe.com',
    Name: 'Mr Doe'
}
...

GET https://api-2.proabono.com/v1/Customer?ReferenceCustomer=123456

The API works with JSON.

To ensure maximal compatibility, use the Accept in all requests :

All requests must be made over HTTPS.

Authentication

 ______     __  __     ______   __  __
/\  __ \   /\ \/\ \   /\__  _\ /\ \_\ \
\ \  __ \  \ \ \_\ \  \/_/\ \/ \ \  __ \
 \ \_\ \_\  \ \_____\    \ \_\  \ \_\ \_\
  \/_/\/_/   \/_____/     \/_/   \/_/\/_/

All API requests must be made over HTTPS.
Each request requires authentication.

Notice : The requests must be server to server. Do not joke with security.

API KEYS & API ENDPOINTs

Get your API Keys (Agent key and API key) and API EndPoint from “My Profile” / Integration.

BASIC AUTHENTICATION

Authentication to the API occurs via HTTP Basic Auth.

To authenticate your request, you have to add a valid Authorization header.

3 STEPS TO BUILD THE AUTHORIZATION HEADER

POST /v1/Customer
Accept: application/json
Authorization: Basic YzdmYTU3YjgtNDg2MS00ODU3OmY2Nzk3YWYxLTc5MWItNDBiMQ==

{
    Email: 'john@doe.com',
    Name: 'Mr Doe'
}

  1. Concatenate agent_key and api_key separated with ’:’ -> agent_key:api_key
    c7fa57b8-4861-4857:f6797af1-791b-40b1

  2. Base-64 encode the string
    YzdmYTU3YjgtNDg2MS00ODU3OmY2Nzk3YWYxLTc5MWItNDBiMQ==

  3. Use the encoded string in the header of your request
    Authorization: Basic YzdmYTU3YjgtNDg2MS00ODU3OmY2Nzk3YWYxLTc5MWItNDBiMQ==

Sign up in order to get your Agent Key and API Key.

Convention

HTTP Response Codes

  _______     ______      ______           ______    __   ___
 /"     "\   /    " \    /    " \         /    " \  |/"| /  ")
(__/\    :) // ____  \  // ____  \       // ____  \ (: |/   /
    / ___/ /  /    ) :)/  /    ) :)     /  /    ) :)|    __/
   // \___(: (____/ //(: (____/ //     (: (____/ // (// _  \
  (:  /  "\\        /  \        /       \        /  |: | \  \
   \_______)\"_____/    \"_____/         \"_____/   (__|  \__)

ProAbono uses conventional HTTP response codes to indicate success or failure of an API request.

In general,

The table below describes the response codes that will be issued and gives potential reasons as to why they may have been sent back.

Successful Response Codes
200 OK: Successful request
201 Created: Successfully created the resource.
204 No Content: Successfully processed the request, but no content was sent back
Unsuccessful Response Codes
400 Bad Request: Invalid or missing request parameters
Inspect the request parameters and ensure that all required parameters are supplied.

Check the response body : ProAbono may supply a hint on how to fix the problem.
401 Unauthorized: Invalid or no credentials passed in the request
Inspect the authorisation header and ensure that a valid authentication has been provided.
403 Forbidden: The operation cannot be processed. The response contains a JSON error object with more information
404 Not Found: The requested Resource was not found
Check your URL syntax or parameters.
405 Method not allowed: The requested resource does not support the supplied HTTP method
Check the API documentation, you are doing something unhealthy.
406 Not Acceptable: Provided Content-Type or Accept header is not supported.
You should probably use application/json.
422 Unprocessable Entity: Request syntax is correct, but its content is not.
The response body will contains a list of errors that will tell you exactly where the problems are.
See Errors section.
500 Internal Server Error: An internal error occurred when processing the request.
Attempt the request again and if the HTTP 500 error re-occurs contact support@proabono.com
501 Method Not Implemented: The requested resource is not implemented yet.
Found any ? You probably are a very advanced user. Contact tech support to know more about the release date.

Errors

Example of an error
{
    "Target": "AmountRecurrence",
    "Code": "Error.Property.ConvertValue.Exception", 
    "Message": "Exception while converting given value for the property",
    "Exception": "Input string was not in a correct format"
}

If your request results in a 4xx or 5xx HTTP code, the response body does contain an error.

Property Description Always returned?
Target The related property No
Code The error code Yes
Message A message localized in your language Yes
Exception More about the error No 
Example of a list of errors
[
    {
        "Target": "AmountRecurrence",
        "Code": "Error.Property.ValueRequired",
        "Message": "A value is required for the property"
    },
    {
        "Target": "Ammount",
        "Code": "Error.Property.UnexpectedProperty",
        "Message": "Unexpected property"
    }
]

List of Errors

Errors list is just a JSON array of errors.

Pagination

{
    "Page": 2,          
    "SizePage": 3,     
    "Count": 3,        
    "TotalItems": 40,   
    "DateGenerated": "2014-12-11T12:45:05.1234714Z",
    "Items": [
        { 
            "item":"1"
        },
        { 
            "item":"2"
        },
        { 
            "item":"3"
        }       
    ],
    "Links": [
        {
            "rel": "prev",
            "href": "/Subscriptions?page=1&SizePage=3"
        },
        {
            "rel": "next",
            "href": "/Subscriptions?page=3&SizePage=3"
        }
    ]
}

Requests that contain multiple items will be paginated by default.

 

Filters

 GET https://api-2.proabono.com/Subscriptions?ReferenceSegment=Sandbox-eur&Page=3&SizePage=20

Every objects collection has multiple available filters that can be passed in the URL.

Available filters are detailled for each object collection below.

Data Formats

Dates

Example
{
  "DateStart": "2017-08-09T12:38:55.00Z"
}

Dates are in universal time : UTC.

They are sent and received in ISO 8601 format : YYYY-MM-DDTHH:MM:SSZ

Time Unit

Unit Description
Day
Week
Month
Year

Languages

ProAbono supports all languages.
Proabono supports language in ISO 639-1 format.

However you are responsible for the translation.

Common language code are :

Code Language
de German
en English
es Spanish
fr French
nl Dutch
pt Portuguese
it Italian

Countries

Proabono supports country codes in ISO_3166-1 alpha2 format.

Common Country Codes are :

Code Country
AU Australia
BR Brazil
CA Canada
DE Germany
ES Spain
FR France
GB United Kingdom of Great Britain
IT Italy
NL Netherlands
US United States of America

Region/Province/State

Proabono supports Region/Province/State codes in ISO_3166-2 format

Common Region/Province/State Codes are :

Country Code Region/Province/State code list Url Country
AU ISO_3166-2:AU Australia
BR ISO_3166-2:BR Brazil
CA ISO_3166-2:CA Canada
DE ISO_3166-2:DE Germany
ES ISO_3166-2:ES Spain
FR ISO_3166-2:FR France
GB ISO_3166-2:GB United Kingdom of Great Britain
IT ISO_3166-2:IT Italy
NL ISO_3166-2:NL Netherlands
US ISO_3166-2:US United States of America

State Subscription

State Subscription Description
InitiatedCustomer Subscription has been initiated from hosted pages
InitiatedAgent Subscription has been initiated by an Agent
Delayed Subscription has been validated by the Customer AND the status will turn into Running at DateStart. See Subscription Object.
Running Subscription is running
SuspendedCustomer Subscription has been suspended by the Customer
SuspendedPaymentInfoMissing Subscription has been suspended because a payment is missing
SuspendedPaymentDue Subscription has been suspended because of payment due
SuspendedAgent Subscription has been suspended by an Agent
SuspendedSystem Subscription has been suspended by the system (technical problem)
TerminatedAtRenewal Subscription will be terminated at the next renewal (i.e. at the end of the current period)
History Subscription is over
Terminated Subscription has been terminated
Deleted Subscription has been deleted

State Life

State Life Description
Ok Enabled
ToModerate To validate
DisabledUser Disabled
DisabledModeration Rejected (moderation)
DisabledSystem Locked
Deleted Deleted

Type Feature

Type Feature Description
OnOff For features like Module, Content Access, …
Limitation Type for Feature which must be counted BUT its quantity will NOT be reset at each subscription renewal.
Consumption Type for Feature which must be counted AND its quantity will be reset at each subscription renewal.

Address Resource

Example
{
    "Company": "John Doe LLC",
    "FirstName": "John",
    "LastName": "Doe",
    "AddressLine1": "123 avenue des Champs Elysées",
    "AddressLine2": "1st Floor",
    "ZipCode": "75008",
    "City": "Paris",
    "Country": "FR",
    "Region": "FR-75",
    "Phone": "+33102030405",
    "TaxInformation":"FR1234567890"
}
Property Description Type
Id Id of the Address Object Integer
Company Name of the Company String
FirstName - String
LastName - String
AddressLine1 Line 1 of the Address String
AddressLine2 Line 2 of the Address String
ZipCode ZipCode of the Address String
City Name of the City String
Country Code of Country of the Address CountryCode
Region Region stands for Subdivision, Department, Region, Province, State of the Country RegionCode
TaxInformation Tax Information (VAT id, Num TVA Intra, GST…) String
Phone Phone Number String

Metadata

Example Request "Create a Customer"
POST https://api-2.proabono.com/v1/Customer
{
    "ReferenceCustomer": "123456",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "ReferenceOffer": "premium-pro-plus",
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        }
}

A set of key/value pairs that you can add to an object (Customer, Subscription, …). It can be useful for storing additional information about the object in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.

At most 5 key/value pairs per object.
Max length of a value is 450 characters.

API - Customers

Customers are the users of your online service.

Each customer contains a ReferenceCustomer. It’s a free field used to uniquely identify a customer.

GET or POST on a customer returns customer-specific links you can use to have the customer access the customer portal, or embed in a iframe. See ’Customer Portal - how it works’

Customer Resource

Example Response
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "ReferenceAffiliation": "janesmith",
    "DateAffiliation": "2016-12-03T17:07:35.04Z",
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        }
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
        }       
    ]
}
Parameter Description Type
Id Id of your customer Integer
IdSegment Id of the Segment in which your Customer has been created Integer
ReferenceCustomer The unique identifier used within your own application for this customer String
ReferenceSegment Reference of the Segment in which your customer has been created/added. String
Email Email of your customer String
Name Fullname of your customer String
Language Language of your customer Langage
ReferenceAffiliation Reference of the affiliate who brought the customer String
Metadata A set of key/value pairs that you can add to a customer Metadata
Links Collection of Links -

Collection of links

Rel Description
hosted-collection-offers Unique encrypted link to the page which contains all visible offers available for the concerned Customer.
hosted-home Unique encrypted link to the page which contains all subscriptions of the concerned Customer
hosted-subscribe Unique encrypted link to redirect the concerned Customer to the subscription page of the offer related to the mentioned ReferenceOffer.
Only available when ReferenceOffer has been mentioned in the request.
hosted-collection-upgrade Unique encrypted link to the page which contains all visible offers available for upgrade for the concerned Customer.
Only available when a customer has already a Running Subscription.

Create a Customer

Definition
POST /v1/Customer

Example Request 1
POST https://api-2.proabono.com/v1/Customer
{
    "ReferenceCustomer": "123456",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en"
}

Example Response 1
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
        }       
    ]
}

Example Request 2
POST https://api-2.proabono.com/v1/Customer
{
    "ReferenceCustomer": "123456",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "ReferenceOffer": "premium-pro-plus",
    "ReferenceAffiliation": "janesmith",
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        }
}

Example Response 2
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "ReferenceAffiliation": "janesmith",
    "DateAffiliation": "2016-12-03T17:07:35.04Z",   
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        },
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/subscriptions/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-subscribe",
            "href": "https://sandbox-eur.proabono.com/subscribe-offer/{Unique-Encrypted-URL3}"
        }
    ]
}

Customers are the users of your online service.

Each customer contains a ReferenceCustomer. It’s a free field used to uniquely identify a customer.

Creating a customer returns customer-specific links you can use to have the customer access the customer portal, or embed in a iframe. See ’Customer Portal - how it works’.

Request Parameters

Parameter Required? Description Type
Email No Email of your customer String
Name No Fullname of your customer String
ReferenceCustomer No The unique identifier used within your own application for this customer String
Language No Language of your customer (By Default, ProAbono will set the language of the segment.) Language
ReferenceSegment (Yes, only if you need/have more than 1 segment) Reference of the segment in which the customer will be created. String
ReferenceOffer No Reference of the offer your customer wants to subscribe. If creation succeed, the responses will contain a direct subscription URL you can redirect the customer to. String
ReferenceAffiliation No Reference of the affiliate who brought the customer String
Metadata No A set of key/value pairs that you can add to a customer. Useful for storing additional information about the customer in a structured format. Metadata

Returns

Retrieve a Customer

GET /v1/Customer?ReferenceCustomer={ref}

Example Request
GET https://api-2.proabono.com/v1/Customer?ReferenceCustomer=123456

Example Response
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        },
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/offers/{Another-Unique-Encrypted-URL}"
        }       
    ]
}

To retrieve a Customer, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String
ReferenceOffer No Reference of the offer your customer wants to subscribe. If creation succeed, the responses will contain a direct subscription URL you can redirect the customer to. String

Returns

Update a Customer

Creating or updating a customer is the same operation in the ProAbono API. If a customer with the same ReferenceCustomer is posted, then it’s just updated. See Create a customer.

List Customers

Definition
GET /v1/Customers

Example Request
GET https://api-2.proabono.com/v1/Customers

Example Response
{
    "Page": 1,
    "SizePage": 10,
    "Count": 3,
    "TotalItems": 3,
    "DateGenerated": "2015-05-10T18:33:16.28Z",
    "Items": [
        {
            "Id": 342883,
            "IdSegment": 3,
            "ReferenceCustomer": "user-0d85bd4c",
            "ReferenceSegment": "sandbox-eur",
            "Name": "John Doe",
            "Email": "john@doe.com",
            "Language": "en"
        },
        {
            "Id": 342856,
            "IdSegment": 3,
            "ReferenceCustomer": "user-0cb58042",
            "ReferenceSegment": "sandbox-eur",
            "Name": "Erika Mustermann",
            "Email": "erika@mustermann.de",
            "Language": "de"
        },
        {
            "Id": 342855,
            "IdSegment": 3,
            "ReferenceCustomer": "user-f90f9f12",
            "ReferenceSegment": "sandbox-eur",
            "Name": "Paul Martin",
            "Email": "paul@martin.fr",
            "Language": "fr"
        }
    ]
}

Retrieve all Customers

Optional Querystring Parameters

Parameters Description Type
ReferenceSegment List all Customers created in a specific Segment String
ReferenceFeature List all Customers with an active subscription containing a specific Feature. See List Customers by Feature. String
Page Indicate the page returned by ProAbono to a request. See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

You can combine these parameters to get exactly what you are looking for.

Example:

GET https://api-2.proabono.com/v1/Customers?SizePage=20

Returns

List Customers by Feature

Definition
GET /v1/Customers?ReferenceFeature={Ref}

Example Request
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=users

Example Response
{
    "Page": 1,
    "SizePage": 10,
    "Count": 3,
    "TotalItems": 3,
    "DateGenerated": "2015-05-10T18:33:16.28Z",
    "Items": [
        {
            "Id": 342883,
            "IdSegment": 3,
            "ReferenceCustomer": "user-0d85bd4c",
            "ReferenceSegment": "sandbox-eur",
            "Name": "John Doe",
            "Email": "john@doe.com",
            "Language": "en",
            "QuantityIncluded": 3,
            "QuantityCurrent": 3,
            "DatePeriodStart": "2015-08-25T15:55:54.98Z",
            "DatePeriodEnd": "2015-09-03T15:55:54.98Z"
        },
        {
            "Id": 342856,
            "IdSegment": 3,
            "ReferenceCustomer": "user-0cb58042",
            "ReferenceSegment": "sandbox-eur",
            "Name": "Erika Mustermann",
            "Email": "erika@mustermann.de",
            "Language": "de",
            "QuantityIncluded": 10,
            "QuantityCurrent": 15,
            "DatePeriodStart": "2015-08-20T07:28:53.95Z",
            "DatePeriodEnd": "2015-09-20T07:28:53.95Z"
        },
        {
            "Id": 342855,
            "ReferenceCustomer": "user-f90f9f12",
            "ReferenceSegment": "sandbox-eur",
            "Name": "Paul Martin",
            "Email": "paul@martin.fr",
            "Language": "fr",
            "QuantityIncluded": 1,
            "QuantityCurrent": 1,
            "DatePeriodStart": "2015-08-26T08:43:15.12Z",
            "DatePeriodEnd": "2015-09-26T08:43:15.12Z"
        }
    ]
}

Retrieve all Customers with an active subscription containing a specific Feature AND describe the relation between each Customer and the specific Feature.

Request Parameters

Parameter Required? Description Type
ReferenceFeature yes Reference of the Feature (ReferenceFeature property) String

Examples:

GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=module-a
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=users
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=text-messages

Returns

Additionnal Data

Parameter Description Type
QuantityIncluded (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature available to the user. It’s aggregated if the customer has multiple subscriptions. If not provided it means ‘unlimited’. Integer
QuantityCurrent (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature currently used by the user. It’s aggregated if the customer has multiple subscriptions. If not provided it means ‘unlimited’. Integer
IsIncluded (Only for OnOff feature) It indicates if the feature is included in any active subscription of the customer. False indicates that the feature can be enabled. Boolean
IsEnabled (Only for OnOff feature) It indicates if the feature is enabled in any active subscription of the customer. Boolean
DatePeriodStart This is the start of the considered billing period. Used to enforce quota (like 10 emails per months). DateTime
DatePeriodEnd This is the end of the considered billing period. Used to enforce quota DateTime

Retrieve Billing Address

GET /v1/CustomerBillingAddress?ReferenceCustomer={ref}

Example Request
GET https://api-2.proabono.com/v1/CustomerBillingAddress?ReferenceCustomer=123456

Example Response
{
    "Company": "John Doe LLC",
    "FirstName": "John",
    "LastName": "Doe",
    "AddressLine1": "123 avenue des Champs Elysées",
    "AddressLine2": "1st Floor",
    "ZipCode": "75008",
    "City": "Paris",
    "Country": "FR",
    "Region": "FR-75",
    "Phone": "+33102030405",
    "TaxInformation":"FR1234567890"
}

To retrieve a Customer Billing Address, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String

Returns

Update Billing Address

POST /v1/CustomerBillingAddress?ReferenceCustomer={ref}

Example Request
POST https://api-2.proabono.com/v1/CustomerBillingAddress?ReferenceCustomer=123456
{
    "Company": "John Doe LLC",
    "FirstName": "John",
    "LastName": "Doe",
    "AddressLine1": "123 avenue des Champs Elysées",
    "AddressLine2": "1st Floor",
    "ZipCode": "75008",
    "City": "Paris",
    "Country": "FR",
    "Region": "FR-75",
    "Phone": "+33102030405",
    "TaxInformation":"FR1234567890"
}

Example Response
{
    "Company": "John Doe LLC",
    "FirstName": "John",
    "LastName": "Doe",
    "AddressLine1": "123 avenue des Champs Elysées",
    "AddressLine2": "1st Floor",
    "ZipCode": "75008",
    "City": "Paris",
    "Country": "FR",
    "Region": "FR-75",
    "Phone": "+33102030405",
    "TaxInformation":"FR1234567890"
}

To update/set a Customer Billing Address, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String

Returns

Retrieve Payment Settings

GET /v1/CustomerSettingsPayment?ReferenceCustomer={ref}

Example Request
GET https://api-2.proabono.com/v1/CustomerSettingsPayment?ReferenceCustomer=123456

Example Response
{
    "TypePayment": "Card",
    "DateNextBilling": "2016-08-29T20:36:53.00Z"
}

To retrieve a Customer Payment Settings, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String

Returns

Update Payment Settings

POST /v1/CustomerSettingsPayment?ReferenceCustomer={ref}

Example Request
POST https://api-2.proabono.com/v1/CustomerSettingsPayment?ReferenceCustomer=123456
{
    "TypePayment": "ExternalBank",
    "DateNextBilling": "2017-08-30T20:36:53.00Z"
}

Example Response
{
    "TypePayment": "ExternalBank",
    "DateNextBilling": "2017-08-30T20:36:53.00Z"
}

To update/set a Customer Payment Settings, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String
DateNextBilling no Date of the next billing DateTime
TypePayment no Set a manual payment method here. Automated payment methods are handled automatically in the Customer Portal. Possible values: ExternalBank, ExternalCash, ExternalCheck, ExternalOther.

Returns

Anonymize Customer

POST /v1/Customer/Anonymization?ReferenceCustomer={ref}

Example Request
POST https://api-2.proabono.com/v1/Customer/Anonymization?ReferenceCustomer=123456

Example Response
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Language": "en",
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
        }       
    ]
}

To anonymize a Customer, use the ReferenceCustomer you provided when creating the Customer.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String

Returns

POST /v1/Customer/LinksRevokation?ReferenceCustomer={ref}

Example Request
POST https://api-2.proabono.com/v1/Customer/LinksRevokation?ReferenceCustomer=123456

Example Response
{
    "Id": 72461,
    "IdSegment": 3,
    "ReferenceCustomer": "123456",
    "ReferenceSegment": "sandbox-eur",
    "Name": "John Doe",
    "Email": "john@doe.com",
    "Language": "en",
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/offers/{New-Unique-Encrypted-URL}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/subscriptions/{Another-New-Unique-Encrypted-URL}"
        }       
    ]
}

To revoke all crypted URLs of the Customer Portal, use the ReferenceCustomer you provided when creating the Customer. More about Crypted URLs.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer (ReferenceCustomer property) String

Returns

API - Usages

Context

A Customer has subscribed to one of your offers.
(Your Offers can contain several Features.)
And now, your site/service needs to :

Example of an Offer

Let’s say you have created an offer called “Premium Offer” for $39 per month.
This offer can have several features. Here are some examples of features of your offer :

Features & Usages are core for your business. Usages describe what you sell and how you sell.

Usage Resource

Example Usage for OnOff Feature
{
    "IdSegment": 3,
    "IdFeature": 47,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "module-a",
    "ReferenceCustomer": "123456",
    "TypeFeature": "OnOff",
    "IsIncluded": true,
    "IsEnabled": true,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Example Usage for Limitation and Consumption Feature
{
    "IdSegment": 3,
    "IdFeature": 48,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "TypeFeature": "Limitation",
    "QuantityIncluded": 3,
    "QuantityCurrent": 4,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Property Description Type
IdSegment Id of the Segment in which the Customer has been created. Integer
IdFeature Id of the Feature related to this Usage Integer
IdCustomer Id of the Customer related to this Usage Integer
IdSubscription Id of the Subscription related to this Usage. If not returned, it means multiple subscriptions matches that usage. Integer
ReferenceSegment Reference of the segment in which the customer has been created. String
ReferenceFeature Reference of the Feature shared with your site/service and ProAbono. String
ReferenceCustomer The unique identifier used within your own application for this customer String
TypeFeature Type of the Feature (OnOff, Limitation, Consumption) FeatureType
IsIncluded (Only for OnOff feature) It indicates if the feature is included in the subscription of the customer. False indicates that the feature can be enabled. Boolean
IsEnabled (Only for OnOff feature) It indicates if the feature is enabled in the subscription of the customer. Boolean
QuantityIncluded (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature available in the Subscription of the Customer. If not provided it means ‘unlimited’. Integer
QuantityCurrent (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature currently used in the Subscription of the Customer. If not provided it means ‘unlimited’. Integer
DatePeriodStart This is the start of the considered billing period. Used to enforce quota (like 10 emails per months). DateTime
DatePeriodEnd This is the end of the considered billing period. Used to enforce quota DateTime

Retrieve Usages for a Customer

Definition
GET /v1/Usages?ReferenceCustomer={ReferenceCustomer}

Example Request
GET https://api-2.proabono.com/v1/Usages?ReferenceCustomer=123456

Example Response
{
    "Page": 1,
    "SizePage": 10,
    "Count": 4,
    "TotalItems": 4,
    "DateGenerated": "2016-03-29T21:54:19.51Z",
    "Items": [
        {
            "IdSegment": 3,
            "IdFeature": 47,
            "IdCustomer": 77722,
            "IdSubscription": 10738,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "module-a",
            "ReferenceCustomer": "123456",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true,
            "DatePeriodStart": "2016-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
        },
        {
            "IdSegment": 3,
            "IdFeature": 48,
            "IdCustomer": 77722,
            "IdSubscription": 10738,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "users",
            "ReferenceCustomer": "123456",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 3,
            "QuantityCurrent": 4,
            "DatePeriodStart": "2016-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
        },
        {
            "IdSegment": 3,
            "IdFeature": 49,
            "IdCustomer": 77722,
            "IdSubscription": 10738,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "module-b",
            "ReferenceCustomer": "123456",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false,
            "DatePeriodStart": "2016-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
        },
        {
            "IdSegment": 3,
            "IdFeature": 50,
            "IdCustomer": 77722,
            "IdSubscription": 10738,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "text-messages",
            "ReferenceCustomer": "123456",
            "TypeFeature": "Consumption",
            "QuantityIncluded": 0,
            "QuantityCurrent": 57,
            "DatePeriodStart": "2016-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
        }
    ]
}

Retrieve Usages of all Features available for a Customer using your own ReferenceCustomer that you or site/service provided to ProAbono.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer Yes Reference of the Customer (ReferenceCustomer property) String
IdSubscription No Id of the Subscription to retrieve only usages from this subscription String

Returns

Example

Let’s say your application is a CRM platform (Customer RelationShip Management).
The Customer 123456 subscribed to an Offer which contains 4 Features :

According the Response, your Customer 123456 subscribed to an Offer at 39 $ per month which:

Retrieve Usages for a Feature

Definition
GET /v1/Usages?ReferenceFeature={ReferenceFeature}

Example Request
GET https://api-2.proabono.com/v1/Usages?ReferenceFeature=users

Example Response
{
    "Page": 1,
    "SizePage": 10,
    "Count": 2,
    "TotalItems": 2,
    "DateGenerated": "2016-03-29T22:02:45.63Z",
    "Items": [
        {
            "IdSegment": 3,
            "IdFeature": 48,
            "IdCustomer": 77722,
            "IdSubscription": 10738,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "users",
            "ReferenceCustomer": "123456",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 3,
            "QuantityCurrent": 17,
            "DatePeriodStart": "2016-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
        },
        {
            "IdSegment": 3,
            "IdFeature": 48,
            "IdCustomer": 77723,
            "IdSubscription": 10739,
            "ReferenceSegment": "sandbox-eur",
            "ReferenceFeature": "users",
            "ReferenceCustomer": "abcdef",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 10,
            "QuantityCurrent": 10,
            "DatePeriodStart": "2016-03-29T22:02:38.00Z",
            "DatePeriodEnd": "2016-04-29T22:02:38.00Z"
        }
    ]
}

Retrieve all Usages related to a specific Feature.

Request Parameters

Parameter Required? Description Type
ReferenceFeature Yes Reference of the Feature (ReferenceFeature property) String

Returns

Retrieve a Single Usage

Definition
GET /v1/Usage?ReferenceFeature={ReferenceFeature}&ReferenceCustomer={ReferenceCustomer}

Example Request 1
GET https://api-2.proabono.com/v1/Usage?ReferenceFeature=users&ReferenceCustomer=123456

Example Response 1
{
    "IdSegment": 3,
    "IdFeature": 48,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "TypeFeature": "Limitation",
    "QuantityIncluded": 3,
    "QuantityCurrent": 17,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Example Request 2
GET https://api-2.proabono.com/v1/Usage?ReferenceFeature=module-a&ReferenceCustomer=123456

Example Response 2
{
    "IdSegment": 3,
    "IdFeature": 47,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "module-a",
    "ReferenceCustomer": "123456",
    "TypeFeature": "OnOff",
    "IsIncluded": true,
    "IsEnabled": true,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Retrieve the Usage of 1 specific Feature for a Customer using your own ReferenceFeature AND your ReferenceCustomer that your site/service provided to ProAbono.

Request Parameters

Parameter Required? Description Type
ReferenceCustomer Yes Reference of the Customer (ReferenceCustomer property) String
IdSubscription No Id of the Subscription to retrieve the usage of the feature of this subscription Integer
ReferenceFeature Yes Reference of the Feature (ReferenceFeature property) String

Returns

Update Usage by Increment

Definition
POST /v1/Usage

Example Request
POST https://api-2.proabono.com/v1/Usage
{
    "ReferenceFeature": "text-messages",
    "ReferenceCustomer": "123456",
    "Increment":57,
    "DateStamp": "2016-03-29T19:33:50.65Z"
}

Example Response
{
    "IdSegment": 3,
    "IdFeature": 50,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "text-messages",
    "ReferenceCustomer": "123456",
    "TypeFeature": "Consumption",
    "QuantityIncluded": 0,
    "QuantityCurrent": 57,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Increment the usage of a Feature. Only valid for Feature with types Limitation or Consumption.

Request Parameters

Parameter Required? Description Type
ReferenceFeature Yes Reference of the Feature String
ReferenceCustomer Yes, unless IdSubscription is provided Reference of the Customer String
IdSubscription No, unless ReferenceCustomer is not provided Related subscription Integer
Increment Yes Usage Increment to apply to the Feature of the Customer Integer
DateStamp Yes Date Stamp of this modification DateTime

Returns

Note : A feature of type consumption sees its QuantityCurrent attribute reset at each subscription renewal.

Update Usage by Current Quantity

Definition
POST /v1/Usage

Example Request
POST https://api-2.proabono.com/v1/Usage
{
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "QuantityCurrent":17,
    "DateStamp": "2016-03-29T19:35:51.65Z"
}

Example Response
{
    "IdSegment": 3,
    "IdFeature": 48,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "TypeFeature": "Limitation",
    "QuantityIncluded": 3,
    "QuantityCurrent": 17,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Set the new current quantity of a Feature. Only valid for Feature with type Limitation.

Request Parameters

Parameter Required? Description Type
ReferenceFeature Yes Reference of the Feature String
ReferenceCustomer Yes, unless IdSubscription is provided Reference of the Customer String
IdSubscription No, unless ReferenceCustomer is not provided Related subscription Integer
QuantityCurrent Yes New Current Quantity Usage to set to the Feature of the Customer Integer
DateStamp Yes Date Stamp of this modification DateTime

Returns

Update Usage OnOff feature

Definition
POST /v1/Usage

Example Request
POST https://api-2.proabono.com/v1/Usage
{
    "ReferenceFeature": "module-b",
    "ReferenceCustomer": "123456",
    "IsEnabled" : true,
    "DateStamp": "2016-03-29T18:33:50.67Z"
}

Example Response
{
    "IdSegment": 3,
    "IdFeature": 49,
    "IdCustomer": 77722,
    "IdSubscription": 10738,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceFeature": "module-b",
    "ReferenceCustomer": "123456",
    "TypeFeature": "OnOff",
    "IsIncluded": false,
    "IsEnabled": true,
    "DatePeriodStart": "2016-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}

Enable or Disable a Feature for a Customer Only valid for Feature with type OnOff.

Request Parameters

Parameter Required? Description Type
ReferenceFeature Yes Reference of the Feature String
ReferenceCustomer Yes, unless IdSubscription is provided Reference of the Customer String
IdSubscription No, unless ReferenceCustomer is not provided Related subscription Integer
IsEnabled Yes If Yes, the Feature will be enabled to the Customer Integer
DateStamp Yes Date Stamp of this modification DateTime

Returns

API - Offers

Offer describes what AND how you want to sell.

All your visible offers are displayed at :
https://{your-domain}.proabono.com/

(Note : You can modify the CSS Style Sheet from the ProAbono’s backoffice : Hosted Pages -> Design)

Offer Resource

Definition
{
  "Id": 35,
  "ReferenceOffer": "premium-offer",
  "IsVisible": true,
  "TitleLocalized": "Premium",
  "PricingLocalized": "190.00 Euro/mois ",
  "Currency": "EUR",
  "AmountRecurrence": 19000,
  "DurationRecurrence": 1,
  "UnitRecurrence": "Month",
  "Features": [...],
  "Links": [...]
}
Property Description Type
Id Id of the Offer Object Integer
Name Name of the Offer String
ReferenceOffer Identifier used within your own application for this offer. Unique for a given segment, meaning you can decline the same offer in multiple segments. String
IsVisible Visibility of the offer in the hosted pages Boolean
AmountUpFront Amount of the Upfront fee, Setup fee or Initial fee of your offer in cents Integer
AmountTrial Amount of the Trial period in cents Integer
DurationTrial Number of Trial Time Unit Integer
UnitTrial Time Unit of Trial TimeUnit
AmountRecurrence Amount of each recurrence in cents Integer
DurationRecurrence Number of Recurrence Time Unit Integer
UnitRecurrence Time Unit of Recurrence TimeUnit
CountRecurrences Number of Recurrences Integer
CountMinRecurrences Minimum recurrences the customer will be committed to pay Integer
AmountTermination Amount of the Termination Fee in cents Integer
StateLife State of the Offer StateLifeCycle
Features Collection of Features with Quantities and Properties Offer Nested Features (see below) OfferFeature
Links Useful links concerning the Offer See below.

Note : Amounts are set without currency because currency is set at the Segment Level.

Collection of Links

Rel Description
hosted-subscribe Link to the page where the Customer will be redirect.

OfferFeature Resource

1 - For OnOff Feature Type

Property Description Type
Id Id of the Feature included in the Offer Integer
ReferenceFeature Reference of the Feature included in the Offer String
IsIncluded If True, the Feature is included in the Offer. Integer
IsEnabled If True, the Feature will be enabled/available when the Customer will subscribe to the Offer. Integer

2 - For Limitation and Consumption Feature Type

Property Description Type
Id Id of the Feature included in the Offer Integer
ReferenceFeature Reference of the Feature included in the Offer String
QuantityIncluded Limitation/Quota/NumberOfUnit of the Feature included in the Offer.
If QuantityIncluded attribute is not provided, it means ‘unlimited’.		 Integer
QuantityCurrent Limitation/Quota/NumberOfUnit of the Feature, the Customer will start when subscribing to the Offer.
If QuantityCurrent attribute is not provided, it means 'unlimited’.		 Integer

Retrieve Offers

Definition
GET /v1/Offers

Example Request
GET https://api-2.proabono.com/v1/Offers?language=en

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2016-03-30T12:13:36.43Z",
  "Items": [
    {
      "Id": 35,
      "ReferenceOffer": "premium-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium",
      "PricingLocalized": "Euro 190.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 19000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
          "TitleLocalized": "Active Users",
          "PricingLocalized": "+Euro 7.00/extra unit",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 3,
          "QuantityCurrent": 3
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
          "TitleLocalized": "Module B",
          "PricingLocalized": "optional +Euro 10.00",
          "TypeFeature": "OnOff",
          "IsIncluded": false,
          "IsEnabled": false
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "PricingLocalized": "from Euro 0.20/extra unit",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 0,
          "QuantityCurrent": 0
        }
      ],
      "Links": [
        {
          "rel": "hosted-subscribe",
          "href": "https://sandbox-eur.proabono.com/subscribe?refo=premium-offer&refs=sandbox-eur"
        }
      ]
    },
    {
      "Id": 147,
      "ReferenceOffer": "premium-pro-plus-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium Pro+",
      "PricingLocalized": "Euro 250.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 25000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
          "TitleLocalized": "Active Users",
          "PricingLocalized": "from Euro 3.00/extra unit",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 10,
          "QuantityCurrent": 10
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "TitleLocalized": "Module B",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "PricingLocalized": "from Euro 0.01/extra unit",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 100,
          "QuantityCurrent": 0
        }
      ],
      "Links": [
        {
          "rel": "hosted-subscribe",
          "href": "https://sandbox-eur.proabono.com/subscribe?refo=premium-pro-plus-offer&refs=sandbox-eur"
        }
      ]
    }
  ]
}

It helps you to set up dynamically your pricing table or pricing page in every langages you want.

Optional Querystring Parameters

Parameter Description Type
ReferenceSegment Reference of the segment where your offers are declared. String
IsVisible Ignored by default. If true, only visible offers & features will be retrieved. If false, only not visible offers will be retrieved. Boolean
IgnoreFeatures False by default. If True, Features will NOT be provided in the response. Boolean
Language By default, ProAbono uses the language of your segment. Langage
Html True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
Links True by default. If false, Links will NOT be provided in the response. Boolean
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

You can combine these parameters to get exactly what you are looking for.

Example:

GET https://api-2.proabono.com/v1/Offers?SizePage=20&html=false&IgnoreFeatures=true&language=en

Returns

Retrieve Offers for a Customer

Definition
GET /v1/Offers?ReferenceCustomer={ReferenceCustomer}

Example Request
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2016-03-30T12:44:07.26Z",
  "Items": [
    {
      "Id": 35,
      "ReferenceOffer": "premium-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium",
      "PricingLocalized": "Euro 190.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 19000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
          "TitleLocalized": "Active Users",
          "PricingLocalized": "+Euro 7.00/extra unit",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 3,
          "QuantityCurrent": 3
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
          "TitleLocalized": "Module B",
          "PricingLocalized": "optional +Euro 10.00",
          "TypeFeature": "OnOff",
          "IsIncluded": false,
          "IsEnabled": false
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "PricingLocalized": "from Euro 0.20/extra unit",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 0,
          "QuantityCurrent": 0
        },
        {
          "Id": 243,
          "ReferenceFeature": "agent",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
          "TitleLocalized": "Agents",
          "PricingLocalized": "from Euro 6.00/extra unit",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 2,
          "QuantityCurrent": 2
        }
      ],
      "Links": [
        {
          "rel": "hosted-subscribe",
          "href": "https://sandbox-eur.proabono.com/subscribe-offer/{Unique-encrypted-url}"
        }
      ]
    },
    {
      "Id": 147,
      "ReferenceOffer": "premium-pro-plus-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium Pro+",
      "PricingLocalized": "Euro 250.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 25000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
          "TitleLocalized": "Active Users",
          "PricingLocalized": "from Euro 3.00/extra unit",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 10,
          "QuantityCurrent": 10
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "TitleLocalized": "Module B",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "PricingLocalized": "from Euro 0.01/extra unit",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 100,
          "QuantityCurrent": 0
        },
        {
          "Id": 243,
          "ReferenceFeature": "agent",
          "IsVisible": true,
          "TitleLocalized": "Agents",
          "TypeFeature": "Limitation"
        }
      ],
      "Links": [
        {
          "rel": "hosted-subscribe",
          "href": "https://sandbox-eur.proabono.com/subscribe-offer/{Another-Unique-encrypted-url}"
        }
      ]
    }
  ]
}

It helps you to set up dynamically the pricing table or pricing page for a Customer.

Retrieve a list of Offers and Features for a Customer by using your ReferenceCustomer that your site/service provided to ProAbono,

Mandatory Querystring Parameters

Parameter Description Type
ReferenceCustomer With the Reference of the customer, offers retrieved will be in language of the customer and links will be encrypted links dedicated to the customer. String

Optional Querystring Parameters

Parameter Description Type
Html True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
IsVisible Ignored by default. If true, only visible offers & features will be retrieved. If false, only not visible offers will be retrieved. Boolean
IgnoreFeatures False by default. If True, Features will NOT be provided in the response. Boolean
Links True by default. If false, Links will NOT be provided in the response. Boolean
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

You can combine these parameters to get exactly what you are looking for.

Example:

GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&SizePage=20&html=false&IgnoreFeatures=true

Returns

Retrieve Offers to upgrade a Customer

2 Definitions availables

Definition 1:
Ideal if you Customer has only one running subscription. ProAbono will be find the subscription and retrieve the offers with the upgrade links.

GET /v1/Offers?ReferenceCustomer={ReferenceCustomer}&Upgrade=true

Definition 2:
If your customer has more than 1 running subscription, ProAbono need the id of subscription to upgrade

GET /v1/Offers?IdSubscription={IdSubscription}

Example Request
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&Upgrade=true
GET https://api-2.proabono.com/v1/Offers?IdSubscription=10725

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2016-03-30T13:09:08.72Z",
  "Items": [
    {
      "Id": 147,
      "ReferenceOffer": "premium-pro-plus-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium Pro+",
      "PricingLocalized": "Euro 250.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 25000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Links": [
        {
          "rel": "hosted-upgrade",
          "href": "https://sandbox-eur.proabono.com/upgrade-to-offer/{An-Unique-encrypted-url}"
        }
      ]
    },
    {
      "Id": 35,
      "ReferenceOffer": "premium-offer",
      "IsVisible": true,
      "TitleLocalized": "Premium",
      "PricingLocalized": "Euro 190.00/month(s) ",
      "Currency": "EUR",
      "AmountRecurrence": 19000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Links": [
        {
          "rel": "hosted-related-subscription",
          "href": "https://sandbox-eur.proabono.com/overview-subscription/{Another-Unique-encrypted-url}"
        }
      ]
    }
  ]
}

It helps you to set up dynamically the pricing table or pricing page for a Customer who wants to upgrade.

Retrieve a list of Offers and Features for a Customer by using your ReferenceCustomer that your site/service provided to ProAbono,

Mandatory Querystring Parameters

Definition 1

Parameter Description Type
ReferenceCustomer With the Reference of the customer, offers retrieved will be in language of the customer and links will be encrypted links dedicated to the customer. String
Upgrade If true, the link with each offer will redirect the Customer the upgrade workflow. Boolean

Definition 2

Parameter Description Type
IdSubscription Id of the Subscription to upgrade Integer

Optional Querystring Parameters

Parameter Description Type
Html True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
IsVisible Ignored by default. If true, only visible offers will be retrieved. If false, only not visible offers will be retrieved. Boolean
IgnoreFeatures False by default. If True, Features will NOT be provided in the response. Boolean
Links True by default. If false, Links will NOT be provided in the response. Boolean
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

You can combine these parameters to get exactly what you are looking for.

Example:

GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&Upgrade=true&SizePage=20&IgnoreFeatures=true

Returns

Retrieve a Single Offer

Definition
GET /v1/Offer?ReferenceOffer={Ref}

Example Request
GET https://api-2.proabono.com/v1/Offer?ReferenceOffer=premium-offer&language=en&html=false

Example Response
{
  "Id": 35,
  "ReferenceOffer": "premium-offer",
  "IsVisible": true,
  "Name": "Premium",
  "TitleLocalized": "Premium",
  "PricingLocalized": "from Euro 210.00/month(s)",
  "Currency": "EUR",
  "Pricing": 21000,
  "AmountRecurrence": 21000,
  "DurationRecurrence": 1,
  "UnitRecurrence": "Month",
  "Features": [
    {
      "Id": 47,
      "ReferenceFeature": "module-a",
      "IsVisible": true,
      "TitleLocalized": "Module A",
      "TypeFeature": "OnOff",
      "IsIncluded": true,
      "IsEnabled": true
    },
    {
      "Id": 48,
      "ReferenceFeature": "users",
      "IsVisible": true,
      "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
      "TitleLocalized": "Active Users",
      "PricingLocalized": "+Euro 7.00/extra unit",
      "TypeFeature": "Limitation",
      "QuantityIncluded": 3,
      "QuantityCurrent": 3
    },
    {
      "Id": 49,
      "ReferenceFeature": "module-b",
      "IsVisible": true,
      "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
      "TitleLocalized": "Module B",
      "PricingLocalized": "optional +Euro 10.00",
      "TypeFeature": "OnOff",
      "IsIncluded": false,
      "IsEnabled": false
    },
    {
      "Id": 50,
      "ReferenceFeature": "text-messages",
      "IsVisible": true,
      "TitleLocalized": "Text Messages Sent",
      "PricingLocalized": "from Euro 0.20/extra unit",
      "TypeFeature": "Consumption",
      "QuantityIncluded": 0,
      "QuantityCurrent": 0
    },
    {
      "Id": 243,
      "ReferenceFeature": "agent",
      "IsVisible": true,
      "Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
      "TitleLocalized": "Agents",
      "PricingLocalized": "from Euro 6.00/extra unit",
      "TypeFeature": "Limitation",
      "QuantityIncluded": 2,
      "QuantityCurrent": 2
    }
  ],
  "Links": [
    {
      "rel": "hosted-subscribe",
      "href": "https://sandbox-eur.proabono.com/subscribe?refo=premium-offer&refs=sandbox-eur&lang=en"
    }
  ]
}

It helps you to retrieve 1 Single Offer.

Very useful to display dynamically the offer on your site pages in every langages you want.

Works like:

Only the endpoint is different /v1/Offer instead of /v1/Offers but same querystring parameters + the Reference of the Offer to retrieve.

Mandatory Querystring Parameters

Parameter Description Type
ReferenceOffer Reference of the offer to retrieve. String

Optional Querystring Parameters

Parameter Description Type
ReferenceSegment Reference of the segment where your offers are declared. String
ReferenceCustomer With the Reference of the customer, the offer retrieved will be in language of the customer and links will be encrypted links dedicated to the customer. See Retrieve Offers for a Customer String
Upgrade If true, the link with of the offer will redirect the Customer the upgrade workflow. Works with ReferenceCustomer. See Retrieve Offers to upgrade a Customer Boolean
IdSubscription Id of the Subscription to upgrade. IdSubscription is an alternative at ReferenceCustomer + Upgrade parameters. See Retrieve Offers to upgrade a Customer Integer
IsVisible Ignored by default. If true, only visible features will be retrieved. If false, only not visible features will be retrieved. Boolean
IgnoreFeatures False by default. If True, Features will NOT be provided in the response. Boolean
Language By default, ProAbono uses the language of your segment. Langage
Html True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
Links True by default. If false, Links will NOT be provided in the response. Boolean

You can combine these parameters to get exactly what you are looking for.

Examples:

Retrieve 1 Offer in english and without list of features
GET /v1/Offer?ReferenceOffer=basic&IgnoreFeatures=true&language=en

Retrieve 1 Offer for the Customer 123456
GET /v1/Offer?ReferenceOffer=ultimate&ReferenceCustomer=123456

Retrieve 1 Offer in order to get the upgrade link for the Customer 123456
GET /v1/Offer?ReferenceOffer=ultimate&ReferenceCustomer=123456&Upgrade=true

Retrieve 1 Offer in order to get the upgrade link for the Subscription 42
GET /v1/Offer?ReferenceOffer=ultimate&IdSubscription=42

Returns

API - Features

Context

A Customer has subscribed to one of your offers.
(Your Offers can contain several Features.)
And now, your site/service needs to know the details of its subscription, in other words :

Example of an Offer

Let’s say you have created an offer called “Premium Offer” for $39 per month.
This offer can have several features. Here are some examples of features of your offer :

Features are core for your business. Features describe what you sell.

Feature Resource

Property Description Type
Id Id of the Feature Object Integer
ReferenceFeature The unique identifier used within your own application for this Feature String
TitleLocalized Title of Feature String
DescriptionLocalized Description of the Feature String
IsVisible Visibility of the Feature in offers and hosted pages Boolean

Retrieve Features

Definition
GET /Features

Example Request
GET https://api-2.proabono.com/v1/Features?ReferenceSegment=sandbox-eur&Language=en&html=false

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 4,
  "TotalItems": 4,
  "DateGenerated": "2016-08-09T11:51:46.92Z",
  "Items": [
    {
      "Id": 47,
      "ReferenceFeature": "module-a",
      "IsVisible": true,
      "TitleLocalized": "Module A",
      "TypeFeature": "OnOff"
    },
    {
      "Id": 48,
      "ReferenceFeature": "users",
      "IsVisible": true,
      "TitleLocalized": "Active Users",
      "TypeFeature": "Limitation"
    },
    {
      "Id": 49,
      "ReferenceFeature": "module-b",
      "IsVisible": true,
      "TitleLocalized": "Module B",
      "TypeFeature": "OnOff"
    },
    {
      "Id": 50,
      "ReferenceFeature": "text-messages",
      "IsVisible": true,
      "TitleLocalized": "Text Messages Sent",
      "TypeFeature": "Consumption"
    }
  ]
}

Retrieve the Features in your site/service and declared in ProAbono.

Optional Querystring Parameters

Parameter Description Type
ReferenceSegment Feature Title and Description can be overriden and translated differently by segment. String
ReferenceCustomer Title and Description of the features available for a Customer will be in the language of the Customer. String
Html True by default. If false, TitleLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
Language By default, ProAbono uses the language of your segment. Langage
IsVisible Ignored by default. If true, only visible features will be retrieved. If false, only not visible features will be retrieved. Boolean
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

Returns

Retrieve a Single Feature

GET /Feature?ReferenceFeature={RefFeature}

Example Request
GET https://api-2.proabono.com/Feature?ReferenceFeature=users

Example Response
{
    "Id": 48,
    "ReferenceFeature": "users",
    "IsVisible": true,
    "TypeFeature": "Limitation",
    "TitleLocalized": "Active Users""
}

It helps you to retrieve 1 Single Feature.

Very useful to display dynamically the feature on your site pages in every langages you want.

Works like Retrieve Features,

Only the endpoint is different /v1/Feature instead of /v1/Features but same querystring parameters + the Reference of the Feature to retrieve.

Mandatory Querystring Parameters

Parameter Description Type
ReferenceFeature Reference of the feature to retrieve. String

Optional Querystring Parameters

Parameter Description Type
ReferenceSegment Feature Title and Description can be overriden and translated differently by segment. String
ReferenceCustomer Title and Description of the feature will be in the language of the Customer. String
Html True by default. If false, TitleLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. Boolean
Language By default, ProAbono uses the language of your segment. Langage

Returns

API - Subscriptions

Subscription Resource

Example Response
{
  "Id": 44082,
  "IdSegment": 3,
  "IdOffer": 1274,
  "IdCustomer": 102547,
  "IdCustomerBuyer": 102547,
  "ReferenceSegment": "sandbox-eur",
  "ReferenceOffer": "full-premium",
  "ReferenceCustomer": "123456",
  "ReferenceCustomerBuyer": "123456",
  "StateSubscription": "Running",
  "DateStart": "2016-08-09T12:38:55.00Z",
  "DatePeriodStart": "2016-08-09T12:38:55.00Z",
  "DatePeriodEnd": "2016-08-23T12:38:55.00Z",
  "DateTerm": "2016-08-23T12:38:55.00Z",
  "StateSubscriptionAfterTerm": "Running",
  "IsTrial": true,
  "CountDaysTrial": 13,
  "IsEngaged": true,
  "IsCustomerBillable": true,
  "IsPaymentCappingReached": false,
  "DateNextBilling": "2017-08-30T20:36:53.00Z",
  "TitleLocalized": "Full Premium",
  "AmountUpFront": 59900,
  "DurationTrial": 14,
  "UnitTrial": "Day",
  "AmountRecurrence": 9900,
  "DurationRecurrence": 1,
  "UnitRecurrence": "Month",
  "CountRecurrences": 12,
  "CountMinRecurrences": 3,
  "Features": [
    {
      "Id": 48,
      "ReferenceFeature": "users",
      "IsVisible": true,
      "TitleLocalized": "Active Users",
      "TypeFeature": "Limitation",
      "QuantityIncluded": 2,
      "QuantityCurrent": 2
    },
    {
      "Id": 49,
      "ReferenceFeature": "module-b",
      "IsVisible": true,
      "TitleLocalized": "Module B",
      "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
      "TypeFeature": "OnOff",
      "IsIncluded": true,
      "IsEnabled": true
    }
  ],
  "DateUpdate": "2016-08-09T12:38:53.76Z",
  "Links": [
    {
      "rel": "self",
      "href": "/v1/Subscription/44082"
    },
    {
      "rel": "hosted-related-subscription",
      "href": "https://sandbox-eur.proabono.com/overview-subscription/{an-unique-encrypted-url}"
    },
    {
      "rel": "hosted-upgrade",
      "href": "https://sandbox-eur.proabono.com/upgrades/{another-unique-encrypted-url}"
    }
  ]
}
Parameter Description Type
Id Id of your Subscription Integer
IdSegment of the Segment in which your customer has been created/added. Integer
IdOffer Id of the Offer subscribed Integer
IdCustomer Identifier of the Customer Integer
IdCustomerBuyer Identifier of the Customer who buys. Integer
ReferenceSegment Reference of the Segment in which your customer has been created/added. String
ReferenceOffer Reference of the Offer subscribed String
ReferenceCustomer The unique identifier used within your own application for this customer String
ReferenceCustomerBuyer Reference of the Customer who buys.
(Tips: Use your own id user)		 String
StateSubscription State of the Subscription StateSubscription
DateStart Start Date of the Subscription DateTime
DatePeriodStart Start Date of the billing period DateTime
DatePeriodEnd End Date of the billing period DateTime
DateTerm Term Date of the Subscription DateTime
StateSubscriptionAfterTerm Estimated State of the Subscription after the current period StateSubscription
IsTrial Indicates if the current period is a trial period or not Boolean
CountDaysTrial Number of days remaining in the trial period Integer
IsEngaged Indicates if the Customer is still in the minimum commitment period Boolean
IsCustomerBillable Indicates if the Customer is currently billable. Boolean
IsPaymentCappingReached Indicates if the Customer has exceeded the max duration limit of due payments and/or the max limit of accumulated amount of due payments. Boolean
DateNextBilling Date of the Customer Next Billing DateTime
TitleLocalized Title of the Subscription in the language of the Customer String
AmountUpFront Amount of the Upfront fee, Setup fee or Initial fee of your offer in cents Integer
AmountTrial Amount of the Trial period in cents Integer
DurationTrial Number of Trial Time Unit Integer
UnitTrial Time Unit of Trial TimeUnit
AmountRecurrence Amount of each recurrence in cents Integer
DurationRecurrence Number of Recurrence Time Unit Integer
UnitRecurrence Time Unit of Recurrence TimeUnit
CountRecurrences Number of Recurrences Integer
CountMinRecurrences Minimum recurrences the customer will be committed to pay Integer
AmountTermination Amount of the Termination Fee in cents Integer
Features Collection of Features + theirs usages (Can be empty if the Offer contained no feature when it was subscribed See below.
DateUpdate Date of the last update of the Subscription Integer
Metadata A set of key/value pairs that you can add to a subscription Metadata
Links Collection of Links. The Links in the collection depends on the Subscription State. See below.

Collection of links for a Subscription in InitiatedAgent State

Rel Description
hosted-related-subscription Unique encrypted link to the detailed page of the subscription for the concerned Customer.
hosted-subscribe Unique encrypted link to conclude and pay the Subscription for the concerned Customer.
hosted-register Unique encrypted link for the concerned Customer to directly type/update his/her payment information.

Collection of links for a Subscription in Running State

Rel Description
hosted-related-subscription Unique encrypted link to the detailed page of the subscription for the concerned Customer. From this page, the Customer can type/update his/her payment information.
hosted-upgrade Unique encrypted link to redirect the the Subscription for the concerned Customer.

SubscriptionFeature Resource

Property Description Type
Id Id of the Feature Integer
ReferenceFeature Reference of the Feature String
IsVisible Visibility of the Feature in hosted pages Boolean
TitleLocalized Title of the Feature in the language of the Customer String
DescriptionLocalized Description of the Feature in the language of the Customer String
TypeFeature Type of the Feature (OnOff, Limitation, Consumption) FeatureType
IsIncluded (Only for OnOff feature) It indicates if the feature is included in the subscription of the customer. False indicates that the feature can be enabled. Boolean
IsEnabled (Only for OnOff feature) It indicates if the feature is enabled in the subscription of the customer. Boolean
QuantityIncluded (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature available in the Subscription of the Customer. If not provided it means ‘unlimited’. Integer
QuantityCurrent (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature currently used in the Subscription of the Customer. If not provided it means ‘unlimited’. Integer

Create a Subscription

Definition
POST /v1/Subscription

Example Request
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "1234567890",
    "ReferenceOffer": "premium-pro-plus-offer",
    "Metadata":
        {
            "Site": "www.johndoe.com",
            "AccountingReference":"456-xyz",
            "IdPartner": 3
        }
}

Example Response
{
    "Id": 44088,
    "IdSegment": 3,
    "IdOffer": 147,
    "IdCustomer": 108052,
    "IdCustomerBuyer": 108052,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-pro-plus-offer",
    "ReferenceCustomer": "1234567890",
    "ReferenceCustomerBuyer": "1234567890",
    "StateSubscription": "InitiatedAgent",
    "IsCustomerBillable": false,
    "IsPaymentCappingReached": false,
    "TitleLocalized": "Premium Pro+",
    "DurationTrial": 0,
    "AmountRecurrence": 25000,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Metadata":
        {
            "Site": "www.johndoe.com",
            "AccountingReference":"456-xyz",
            "IdPartner": 3
        },
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "TitleLocalized": "Active Users",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 10,
            "QuantityCurrent": 10
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 50,
            "ReferenceFeature": "text-messages",
            "IsVisible": true,
            "TitleLocalized": "Text Messages Sent",
            "TypeFeature": "Consumption",
            "QuantityIncluded": 100,
            "QuantityCurrent": 0
        }
    ],
    "DateUpdate": "2016-08-09T13:17:39.88Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription/44088"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/subscription/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-subscribe",
            "href": "https://sandbox-eur.proabono.com/conclude/{Unique-Crypted-Url-2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/permission-update/{Unique-Crypted-Url-3}"
        }
    ]
}

Customers refer to your users in your Site/Service/Application.

Each customer shares a reference called ReferenceCustomer in order to be easily found in your database and ProAbono.

A customer can subscribe to offers.
Each subscription is a copy of the offer subscribed at the exact moment of the subscription.

Request Parameters

Parameter Required? Description Type
ReferenceOffer Yes Reference of the offer in which the customer will be created. String
ReferenceCustomer Yes The unique identifier used within your own application for this customer.
Must be previously declared/created in ProAbono. See Create a Customer		 String
ReferenceCustomerBuyer No Reference of the Customer who buys.
Must be previously declared/created in ProAbono. See Create a Customer		 String
Metadata No A set of key/value pairs that you can add to a subscription. Useful for storing additional information about the subscription in a structured format. Metadata

Note : Creating a Subscription based on an offer

QueryString Parameters

By default, ProAbono starts a subscription only if subscription is free (or has a free trial period) or if the customer has valid payment information.

Parameter Required? Description Type
EnsureBillable No ?ensureBillable=true forces the verification of the payment information, even if the Offer is free. If the customer has not registered any payment information, the 403 forbidden error is returned. Boolean
TryStart No ?tryStart=false prevents the immediate start of the subscription, for example if you want to customize this subscription before its start.
?tryStart=true tries to force the start of the subscription. If the Offer is paying Offer and the customer has no valid payment information, the 403 Forbidden error is returned		 Boolean
BillNow No If ?BillNow=true, the Start is billed immediately Boolean

Returns

Override a Subscription

Definition
POST /v1/Subscription

Example Request 1 (with the Trial overridden)
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-pro-plus-offer",
    "DurationTrial" : 21,
    "UnitTrial": "Day"
}

Example Request 2 (with Upfront amount overridden -> €100 Upfront fee)
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-pro-plus-offer",
    "AmountUpFront" : 10000
}

Example Request 3 (with Recurrence overridden -> €99 monthly to €199 quarterly)
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-pro-plus-offer",
    "DurationRecurrence" : 3,
    "UnitRecurrence" : "Month",
    "AmountRecurrence" : 19900
}

Each subscription is a copy of the offer subscribed at the exact moment of the subscription.
You can override lots of parameters of the Offer during the creation of the subscription.

It helps you to customize subscriptions for your Customers.

Request Parameters

Parameter Required? Description Type
ReferenceOffer Yes Reference of the offer in which the customer will be created. String
ReferenceCustomer Yes The unique identifier used within your own application for this customer.
Must be previously declared/created in ProAbono. See Create a Customer		 String
ReferenceCustomerBuyer No Reference of the Customer who buys.
Must be previously declared/created in ProAbono. See Create a Customer		 String
DateStart No Set the Date when the Subscription will start DateTime
TitleLocalized No Title of the Subscription in the language of the Customer (Plain text) String
DescriptionLocalized No Description of the Subscription in the language of the Customer (Plain text) String
AmountUpFront No Amount UpFront of the Offer Integer
AmountTrial No Amount of the Trial period in cents Integer
DurationTrial No Duration trial of the Offer Integer
UnitTrial No Override the Unit Time of Trial of the Offer String (Day, Week, Month, Year)
AmountRecurrence No Amount of each recurrence in cents Integer
DurationRecurrence No Number of Recurrence Time Unit Integer
UnitRecurrence No Time Unit of Recurrence TimeUnit
CountRecurrences No Number of Recurrences Integer
CountMinRecurrences No Minimum recurrences the customer committed to pay Integer
AmountTermination No Amount of the Termination Fee in cents Integer

Returns

Retrieve a Subscription

Definitions
GET /v1/Subscription/{IdSubscription}
GET /v1/Subscription/?ReferenceCustomer={Ref}

Example Request 
GET https://api-2.proabono.com/v1/Subscription/44088
GET https://api-2.proabono.com/v1/Subscription/?ReferenceCustomer=1234567890

Example Response
{
    "Id": 44088,
    "IdSegment": 3,
    "IdOffer": 147,
    "IdCustomer": 108052,
    "IdCustomerBuyer": 108052,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-pro-plus-offer",
    "ReferenceCustomer": "1234567890",
    "ReferenceCustomerBuyer": "1234567890",
    "StateSubscription": "InitiatedAgent",
    "IsCustomerBillable": false,
    "IsPaymentCappingReached": false,
    "TitleLocalized": "Premium Pro+",
    "DurationTrial": 0,
    "AmountRecurrence": 25000,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "TitleLocalized": "Active Users",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 10,
            "QuantityCurrent": 10
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 50,
            "ReferenceFeature": "text-messages",
            "IsVisible": true,
            "TitleLocalized": "Text Messages Sent",
            "TypeFeature": "Consumption",
            "QuantityIncluded": 100,
            "QuantityCurrent": 0
        }
    ],
    "DateUpdate": "2016-08-09T13:17:39.88Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription/44088"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/subscription/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-subscribe",
            "href": "https://sandbox-eur.proabono.com/conclude/{Unique-Crypted-Url-2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/permission-update/{Unique-Crypted-Url-3}"
        }
    ]
}

Retrieve a Subscription. 2 definitions are available : - Retrieve a Subcription by IdSubscription - Retrieve a Subscription with the ReferenceCustomer

Request Parameters for Definition 1 (By IdSubscription)

Parameter Required? Description Type
IdSubscription yes Id of the Subscription. Integer
Html no True by default. If false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. Boolean
IgnoreFeatures no False by default. If True, Features will NOT be provided in the response. Boolean

Returns

Request Parameters for Definition 2 (with the ReferenceCustomer)

This definition is very useful if your subscription model is “One Single Subscription per Customer”.

Parameter Required? Description Type
ReferenceCustomer yes Reference of the Customer. Integer
Html no True by default. If false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. Boolean
IgnoreFeatures no False by default. If True, Features will NOT be provided in the response. Boolean

Returns

Update Subscription Term Date

Definition
POST /v1/Subscription/{IdSubscription}/DateTerm

Example Request
POST https://api-2.proabono.com/v1/Subscription/{IdSubscription}/DateTerm
{
    "DateTerm":"2016-12-31T23:59:59.65Z"
}

Update the Term Date of the Subscription

Request Parameters

Parameter Required? Description Type
DateTerm Yes New Date of the term of the Subscription DateTime

Returns

Suspend a Subscription

Definition
POST /v1/Subscription/{IdSubscription}/Suspension

Example Requests
POST https://api-2.proabono.com/v1/Subscription/10811/Suspension

A Subscription can be suspended and later restarted.

Request Parameters

Parameter Required? Description Type
IdSubscription Yes Id of the Subscription. Integer

Returns

Start a Subscription

Definition
POST /v1/Subscription/{IdSubscription}/Start

Example Requests
POST https://api-2.proabono.com/v1/Subscription/10811/Start

POST https://api-2.proabono.com/v1/Subscription/10811/Start?EnsureBillable=true&Html=true

Start a subscription. Note : A Subscription with State “Terminated” or “History” can not be restarted.

Request Parameters

Parameter Required? Description Type
IdSubscription Yes Id of the Subscription. Integer

QueryString Parameters

Parameter Required? Description Type
EnsureBillable No ?ensureBillable=true forces the verification of the payment information, even if the Offer is free. If the customer has not registered any payment information, the 403 forbidden error is returned. Boolean
Html No If ?Html=false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. Boolean
BillNow No If ?BillNow=true, the Start is billed immediately Boolean

Returns

Upgrade a Subscription

Definition
POST /v1/Subscription/{IdSubscription}/Upgrade?ReferenceOffer={ReferenceOffer}

Example Requests
POST https://api-2.proabono.com/v1/Subscription/10811/Upgrade?ReferenceOffer=premium-pro-plus-offer

Upgrade a running subscription to a desired Offer.

Request Parameters

Parameter Required? Description Type
IdSubscription Yes Id of the Subscription. Integer
ReferenceOffer Yes The Reference Offer targeted to the upgrade String
BillNow No If ?BillNow=true, the Upgrade is billed immediately Boolean

Returns

Terminate a Subscription

Definition
POST /v1/Subscription/{IdSubscription}/Termination

Example Request
POST https://api-2.proabono.com/v1/Subscription/5486/Termination?Immediate=true

A Subscription can be terminated at the exact moment of the request with Immediate parameter at true. By default, the termination will be delayed to the end of current period (i.e. at the next renewal).

It is possible to override the Termination Date with DateTermination parameter.

Request Parameters

Parameter Required? Description Type
Id Yes Id of the Subscription. Integer
Immediate No False by default. If true, the Subscription will be terminated immediately, not at the next renewal. Boolean
DateTermination No Set a new termination date DateTime

Returns

List Subscriptions

Definition
GET /v1/Subscriptions

Example Request
GET https://api-2.proabono.com/v1/Subscriptions?IgnoreFeatures=true&

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2016-08-09T13:40:37.10Z",
  "Items": [
    {
      "Id": 44097,
      "IdSegment": 3,
      "IdOffer": 147,
      "IdCustomer": 108057,
      "IdCustomerBuyer": 108057,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceOffer": "premium-pro-plus-offer",
      "ReferenceCustomer": "0987654321",
      "ReferenceCustomerBuyer": "0987654321",
      "StateSubscription": "Running",
      "DateStart": "2016-08-09T13:40:10.00Z",
      "DatePeriodStart": "2016-08-09T13:40:10.00Z",
      "DatePeriodEnd": "2016-09-09T13:40:10.00Z",
      "DateTerm": "2016-09-09T13:40:10.00Z",
      "StateSubscriptionAfterTerm": "Running",
      "IsTrial": false,
      "IsEngaged": false,
      "IsCustomerBillable": true,
      "IsPaymentCappingReached": false,
      "DateNextBilling": "2016-09-09T19:40:10.00Z",
      "TitleLocalized": "Premium Pro+",
      "DurationTrial": 0,
      "AmountRecurrence": 25000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "TitleLocalized": "Active Users",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 10,
          "QuantityCurrent": 10
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "TitleLocalized": "Module B",
          "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 100,
          "QuantityCurrent": 120
        }
      ],
      "DateUpdate": "2016-08-09T13:40:10.88Z",
      "Links": [
        {
          "rel": "self",
          "href": "/v1/Subscription/44097"
        },
        {
          "rel": "hosted-related-subscription",
          "href": "https://sandbox-eur.proabono.com/overview-subscription/{Unique-Crypted-Url-1}"
        },
        {
          "rel": "hosted-upgrade",
          "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Crypted-Url-2}"
        }
      ]
    },
    {
      "Id": 44096,
      "IdSegment": 3,
      "IdOffer": 35,
      "IdCustomer": 108056,
      "IdCustomerBuyer": 108056,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceOffer": "premium-offer",
      "ReferenceCustomer": "abcdef",
      "ReferenceCustomerBuyer": "abcdef",
      "StateSubscription": "TerminatedAtRenewal",
      "DateStart": "2016-08-03T13:38:41.00Z",
      "DatePeriodStart": "2016-08-03T13:38:41.00Z",
      "DatePeriodEnd": "2016-09-03T13:38:41.00Z",
      "DateTerm": "2016-09-03T13:38:41.00Z",
      "StateSubscriptionAfterTerm": "Terminated",
      "IsTrial": false,
      "IsEngaged": false,
      "IsCustomerBillable": true,
      "IsPaymentCappingReached": false,
      "DateNextBilling": "2016-09-09T19:38:41.00Z",
      "TitleLocalized": "Premium",
      "DurationTrial": 0,
      "AmountRecurrence": 21000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "TitleLocalized": "Module A",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "TitleLocalized": "Active Users",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 3,
          "QuantityCurrent": 3
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "TitleLocalized": "Module B",
          "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
          "TypeFeature": "OnOff",
          "IsIncluded": false,
          "IsEnabled": true
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "TitleLocalized": "Text Messages Sent",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 0,
          "QuantityCurrent": 76
        }
      ],
      "DateUpdate": "2016-08-09T13:38:52.08Z",
      "Links": [
        {
          "rel": "self",
          "href": "/v1/Subscription/44096"
        },
        {
          "rel": "hosted-related-subscription",
          "href": "https://sandbox-eur.proabono.com/overview-subscription/{Unique-Crypted-Url-3}"
        }
      ]
    }
  ],
  "Links": [
    {
      "rel": "next",
      "href": "/v1/Subscriptions?Page=2"
    }
  ]
}

Retrieve all Subscriptions

Optional Querystring Parameters

Parameters Description Type
ReferenceSegment List all subscriptions created in a specific Segment String
ReferenceCustomer List all subscriptions of a specific Customer String
ReferenceCustomerBuyer List all subscriptions of a specific CustomerBuyer String
Html True by default. If false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. Boolean
IgnoreFeatures False by default. If True, Features will NOT be provided in the response. Boolean
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

You can combine these parameters to get exactly what you are looking for.

Example:

GET https://api-2.proabono.com/v1/Subscriptions?SizePage=20&ReferenceCustomerBuyer=1234567890

Returns

API - Compute Pricing

Pricing Computing is designed to compute the exact pricing, including taxes, when you want your customer to know exactly how much he or she will be charged.

It’s strongly recommended to avoid performing pricing calculations directly in yours application, as ProAbono is the referential for pricing and billing information.

Pricing for a Subscription Creation

Definition
POST /v1/Pricing/Subscription

Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription
{
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456"
}

Example Response
{
    "AmountTotalDue": 26775,
    "PricingLocalized": "€ 267.75",
    "DatePeriodStart": "2016-08-10T06:21:47.71Z",
    "DatePeriodTerm": "2016-09-10T06:21:47.71Z",
    "AmountSubtotal": 21000,
    "AmountTotal": 26775,
    "Details": [
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 26775,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2016-08-10T06:21:47.71Z",
            "DatePeriodTerm": "2016-09-10T06:21:47.71Z",
            "AmountSubtotal": 21000,
            "AmountTotal": 26775
        }
    ]
}

Compute the pricing of a Subcription creation.

Request Parameters

Same as Create a Subscription.

QueryString Parameters

Same as Create a Subscription.

Returns

Pricing for a Subscription Override

Definition
POST /v1/Pricing/Subscription

Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription
{
    "ReferenceOffer": "premium-offer",
    "AmountUpFront" : 19900,
    "ReferenceCustomer": "123456"
}

Example Response
{
    "AmountTotalDue": 52147,
    "PricingLocalized": "€ 521.47",
    "DatePeriodStart": "2016-08-10T06:56:24.42Z",
    "DatePeriodTerm": "2016-09-10T06:56:24.42Z",
    "AmountSubtotal": 40900,
    "AmountTotal": 52147,
    "Details": [
        {
            "LabelLocalized": "Up-front amount",
            "AmountTotalDue": 25372,
            "TypeMove": "SubscriptionUpFront",
            "DateMove": "2016-08-10T06:56:24.42Z",
            "AmountSubtotal": 19900,
            "AmountTotal": 25372
        },
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 26775,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2016-08-10T06:56:24.42Z",
            "DatePeriodTerm": "2016-09-10T06:56:24.42Z",
            "AmountSubtotal": 21000,
            "AmountTotal": 26775
        }
    ]
}

Compute the pricing of a overriden subcription creation.

Request Parameters

Same as Override a Subscription.

QueryString Parameters

Same as Override a Subscription.

Returns

Pricing for a Subscription Start

Definition
POST /v1/Pricing/Subscription/{IdSubscription}/Start

Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription/45678/Start?Html=false

Example Response
{
    "IdSubscription": 44179,
    "AmountTotalDue": 31875,
    "PricingLocalized": "€ 318.75",
    "DatePeriodStart": "2016-08-10T07:41:57.83Z",
    "DatePeriodTerm": "2016-09-10T07:41:57.83Z",
    "AmountSubtotal": 25000,
    "AmountTotal": 31875,
    "Details": [
        {
            "IdSubscription": 44179,
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 31875,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2016-08-10T07:41:57.83Z",
            "DatePeriodTerm": "2016-09-10T07:41:57.83Z",
            "AmountSubtotal": 25000,
            "AmountTotal": 31875
        }
    ],
    "NextTerm": {
        "IdSubscription": 44179,
        "AmountTotalDue": 31875,
        "PricingLocalized": "€ 318.75",
        "DatePeriodStart": "2016-09-10T07:41:57.83Z",
        "DatePeriodTerm": "2016-10-10T07:41:57.83Z",
        "AmountSubtotal": 25000,
        "AmountTotal": 31875,
        "Details": [
            {
                "IdSubscription": 44179,
                "LabelLocalized": "Subscription amount",
                "AmountTotalDue": 31875,
                "TypeMove": "SubscriptionRecurrence",
                "DatePeriodStart": "2016-09-10T07:41:57.83Z",
                "DatePeriodTerm": "2016-10-10T07:41:57.83Z",
                "AmountSubtotal": 25000,
                "AmountTotal": 31875
            }
        ]
    }
}

Compute the pricing for a (re)start of a subcription.

Request Parameters

Same as Start a Subscription.

QueryString Parameters

Same as Start a Subscription.

Returns

Pricing for a Subscription Upgrade

Definition
POST /v1/Pricing/Subscription/{IdSubscription}/Upgrade?ReferenceOffer={RefOffer}

Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription/45678/Upgrade?ReferenceOffer=premium-pro-plus-offer&html=false

Example Response
{
    "IdSubscription": 44081,
    "AmountTotalDue": 4971,
    "PricingLocalized": "49.71 €",
    "DatePeriodStart": "2016-08-10T07:32:13.76Z",
    "DatePeriodTerm": "2016-09-09T12:33:32.00Z",
    "AmountSubtotal": 3898,
    "AmountTotal": 4971,
    "Details": [
        {
            "IdSubscription": 44081,
            "LabelLocalized": "Subscription - refund on recurring flat fee",
            "AmountTotalDue": -26089,
            "TypeMove": "SubscriptionRecurrenceRefund",
            "DatePeriodStart": "2016-08-10T07:32:13.76Z",
            "DatePeriodTerm": "2016-09-09T12:33:30.48Z",
            "AmountSubtotal": -20463,
            "AmountTotal": -26089
        },
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 31060,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2016-08-10T07:32:13.76Z",
            "DatePeriodTerm": "2016-09-09T12:33:32.00Z",
            "AmountSubtotal": 24361,
            "AmountTotal": 31060
        }
    ],
    "NextTerm": {
        "AmountTotalDue": 31875,
        "PricingLocalized": "318.75 €",
        "DatePeriodStart": "2016-09-09T12:33:32.00Z",
        "DatePeriodTerm": "2016-10-09T12:33:32.00Z",
        "AmountSubtotal": 25000,
        "AmountTotal": 31875,
        "Details": [
            {
                "LabelLocalized": "Subscription amount",
                "AmountTotalDue": 31875,
                "TypeMove": "SubscriptionRecurrence",
                "DatePeriodStart": "2016-09-09T12:33:32.00Z",
                "DatePeriodTerm": "2016-10-09T12:33:32.00Z",
                "AmountSubtotal": 25000,
                "AmountTotal": 31875
            }
        ]
    }
}

Compute the pricing for an upgrade of a subcription.

Request Parameters

Same as Upgrade a Subscription.

QueryString Parameters

Same as Upgrade a Subscription.

Returns

Pricing for an Usage Update

Definition
POST /v1/Pricing/Usage

Example Request 1
POST https://api-2.proabono.com/v1/Pricing/Usage
{
    "ReferenceFeature": "module-b",
    "ReferenceCustomer": "123456",
    "IsEnabled":true,
    "DateStamp": "2016-08-09T12:13:50.65Z"
}

Example Request 2
POST https://api-2.proabono.com/v1/Pricing/Usage
{
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "QuantityCurrent":6,
    "DateStamp": "2016-08-09T12:13:50.65Z"
}


Example Request 3
POST https://api-2.proabono.com/v1/Pricing/Usage?html=false
{
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "Increment":4,
    "DateStamp": "2016-08-09T12:13:50.65Z"
}

Example Response 3
{
    "IdSubscription": 44082,
    "IdFeature": 48,
    "AmountTotalDue": 5038,
    "PricingLocalized": "€ 50.38",
    "DatePeriodStart": "2016-08-09T15:58:20.73Z",
    "DatePeriodTerm": "2016-08-23T12:38:55.00Z",
    "AmountSubtotal": 3952,
    "AmountTotal": 5038,
    "Details": [
        {
            "IdSubscription": 44082,
            "IdFeature": 48,
            "LabelLocalized": "Feature - prorated adjustment - Active Users",
            "AmountTotalDue": 5038,
            "TypeMove": "AutoFeatureProrata",
            "DatePeriodStart": "2016-08-09T15:58:20.73Z",
            "DatePeriodTerm": "2016-08-23T12:38:55.00Z",
            "QuantityReported": 6,
            "QuantityBilled": 4,
            "AmountSubtotal": 3952,
            "AmountTotal": 5038
        }
    ]
}

Example Request 4
POST https://api-2.proabono.com/v1/Pricing/Usage?NextTerm=true
{
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "Increment":4,
    "DateStamp": "2016-08-09T12:13:50.65Z"
}

Example Response 4
{
    "IdSubscription": 44082,
    "IdFeature": 48,
    "AmountTotalDue": 5038,
    "PricingLocalized": "€ 50.38",
    "DatePeriodStart": "2016-08-09T15:58:20.73Z",
    "DatePeriodTerm": "2016-08-23T12:38:55.00Z",
    "AmountSubtotal": 3952,
    "AmountTotal": 5038,
    "Details": [
        {
            "IdSubscription": 44082,
            "IdFeature": 48,
            "LabelLocalized": "Feature - prorated adjustment - Active Users",
            "AmountTotalDue": 5038,
            "TypeMove": "AutoFeatureProrata",
            "DatePeriodStart": "2016-08-09T15:58:20.73Z",
            "DatePeriodTerm": "2016-08-23T12:38:55.00Z",
            "QuantityReported": 6,
            "QuantityBilled": 4,
            "AmountSubtotal": 3952,
            "AmountTotal": 5038
        }
    ],
    "NextTerm": {
        "IdSubscription": 44082,
        "LabelLocalized": "Subscription cost after modification",       
        "PricingLocalized": "€ 191.22",
        "DatePeriodStart": "2016-08-23T12:38:55.00Z",   
        "DatePeriodTerm": "2016-09-23T12:38:55.00Z",
        "AmountSubtotal": 15000,
        "AmountTotal": 19122,
        "Details": [
            {
                "IdSubscription": 44082,
                "LabelLocalized": "Flat fee",
                "AmountTotalDue": 6374,
                "TypeMove": "AutoFSubscriptionRecurrence",
                "DatePeriodStart": "2016-08-23T12:38:55.00Z",
                "DatePeriodTerm": "2016-09-23T12:38:55.00Z",
                "AmountSubtotal": 5000,
                "AmountTotal": 6374
            },      
            {
                "IdSubscription": 44082,
                "IdFeature": 48,
                "LabelLocalized": "Feature - Active Users",
                "AmountTotalDue": 12748,
                "TypeMove": "AutoFeatureProratable",
                "DatePeriodStart": "2016-08-23T12:38:55.00Z",
                "DatePeriodTerm": "2016-09-23T12:38:55.00Z",
                "QuantityReported": 6,
                "QuantityBilled": 4,
                "AmountSubtotal": 10000,
                "AmountTotal": 12748
            }
        ]
    }   
}

Compute the pricing for an Usage Update by Increment, by QuantityCurrent and for OnOff feature.

Request Parameters for Usage Update for OnOff feature

Parameter Description Type
ReferenceFeature Reference of the Feature String
ReferenceCustomer Reference of the Customer String
IdSubscription Id of the Subscription to use if the Customer has multiple running subscriptions Integer
IsEnabled New State of the Feature for the Customer Boolean
DateStamp Date Stamp of this potential modification DateTime

Request Parameters for Usage Update by QuantityCurrent (For Features with Type Limitation Only)

Parameter Description Type
ReferenceFeature Reference of the Feature String
ReferenceCustomer Reference of the Customer String
IdSubscription Id of the Subscription to use if the Customer has multiple running subscriptions Integer
QuantityCurrent New Current Quantity of the Feature for the Customer Integer
DateStamp Date Stamp of this potential modification DateTime

Request Parameters for Usage Update by Increment (For Features with Type Consumption or Limitation)

Parameter Description Type
ReferenceFeature Reference of the Feature String
ReferenceCustomer Reference of the Customer String
IdSubscription Id of the Subscription to use if the Customer has multiple running subscriptions Integer
Increment New Increment of the Feature for the Customer Integer
DateStamp Date Stamp of this potential modification DateTime

Optional QueryString Parameters

Parameter Description Type
EnsureBillable ?ensureBillable=true forces the verification of the payment information, even if the Offer is free. If the customer has not registered any payment information, the 403 forbidden error is returned. Boolean
Html If ?Html=false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. Boolean
NextTerm ?NextTerm=true adds in the response the estimated cost of the next term. See Example 4 on the right Boolean

Returns

json