NAV Navbar
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
Content-Type: application/json
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": "2019-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": "2019-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

State Invoice

State Invoice Description
Draft Draft
PaymentExpected Payment expected
PaymentDue Payment due
PaymentDuePending Payment pending
PaymentAutoFailed Automated payment failed
Overdue Overdue
Disputed Disputed
Paid Paid
Refunded Refunded
Cancelled Cancelled
MarkedDeleted Deleted
Deleted Deleted (for good)

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.

Property Feature

Property Feature Description
UpdatableBeforeSubscription Allows the customer to choose the starting quantity in the hosted pages.
UpdatableAfterSubscription Allows the customer to update the quantity in the hosted pages.
FreeInTrial During the Trial Period, any update of the feature are free. Extra charges will start only after the trial period.
UpdateAtFullPrice When increasing the quantity, the extra fee is computed for the full period.
When decreasing the quantity, the fees already added for the period are not credited.
When this property is not set, the extra fees are prorated.
(read this article before enabling)

Type Payment

Type Payment Description
Free Subscription is free, no payment ever requested
ExternalCheck Payment with check
ExternalCash Payment with cash
ExternalBank Payment by wire transfer
ExternalOther Other payment type
Card Payment with payment card, automated renewal
DirectDebit Payment with bank account info, automated 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": "2019-12-03T17:07:35.04Z",
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        }
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/pricing/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{Unique-Encrypted-URL3}"
        }   
    ]
}
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-register Unique encrypted link to the page which contains payment method selection.
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/pricing/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{Unique-Encrypted-URL3}"
        }       
    ]
}

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": "2019-12-03T17:07:35.04Z",   
    "Metadata":
        {
            "Gender":"Male",
            "Incomes": 150000,
            "Kids": 3
        },
    "Links": [
        {
            "rel": "hosted-collection-offers",
            "href": "https://sandbox-eur.proabono.com/pricing/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{Unique-Encrypted-URL3}"
        },
        {
            "rel": "hosted-subscribe",
            "href": "https://sandbox-eur.proabono.com/subscribe-offer/{Unique-Encrypted-URL4}"
        }
    ]
}

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/pricing/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{Unique-Encrypted-URL3}"
        }
    ]
}

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": "2019-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": "2019-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": "2019-08-25T15:55:54.98Z",
            "DatePeriodEnd": "2019-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": "2019-08-20T07:28:53.95Z",
            "DatePeriodEnd": "2019-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": "2019-08-26T08:43:15.12Z",
            "DatePeriodEnd": "2019-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",
    "IsAutoBilling": true,
    "IsGreyListed": false,
    "DateNextBilling": "2019-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": "2019-08-30T20:36:53.00Z"
}

Example Response
{
    "TypePayment": "ExternalBank",,
    "IsAutoBilling": true,
    "IsGreyListed": false,
    "DateNextBilling": "2019-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
IsAutoBilling no Automatically set the next billing date. If disabled, the owed amounts will be stacked into the balance and you will you have to use the action 'Bill now' or set a next billing date Boolean
IsGreyListed no Prevent access to payment forms. Automatically set when suspicious activity is detected Boolean
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/pricing/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{Unique-Encrypted-URL3}"
        }
    ]
}

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/pricing/{New-Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-home",
            "href": "https://sandbox-eur.proabono.com/portal/{New-Unique-Encrypted-URL2}"
        },
        {
            "rel": "hosted-register",
            "href": "https://sandbox-eur.proabono.com/register/{New-Unique-Encrypted-URL3}"
        }
    ]
}

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

Invalidate Customer

Definitions
POST /v1/Customer/Invalidation?ReferenceCustomer={ref}
POST /v1/Customer/{idCustomer}/Invalidation

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

Example Request 2
POST https://api-2.proabono.com/v1/Customer/72461/Invalidation

Invalidate the customer so its ReferenceCustomer can be reused.

This operation will:

This operation will NOT:

Request Parameters
Parameter Required? Description Type
ReferenceCustomer Yes Reference of the Customer (ReferenceCustomer property) String
IdCustomer Yes Id of the Customer Integer
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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-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": "2019-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2019-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 No Reference of the Customer only usages from this customer String
IdCustomer No Id of the Customer to retrieve only usages from this customer Integer
IdSubscription No Id of the Subscription to retrieve only usages from this subscription Integer

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

Example:

GET https://api-2.proabono.com/v1/Usages?ReferenceCustomer=123456&IdSubscription=10738

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": "2019-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": "2019-03-29T21:35:32.00Z",
            "DatePeriodEnd": "2019-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": "2019-03-29T22:02:38.00Z",
            "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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": "2019-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": "2019-03-29T21:35:32.00Z",
    "DatePeriodEnd": "2019-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
Pricing Amount of the offer in cents Integer
PricingSubtotal Amount of the offer in cents without taxes Integer
PricingTotal Amount of the offer in cents with taxes Integer
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
<!-- IDK Properties -->
PricingLocalized Text of the price localized for the Customer 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": "2019-03-30T12:13:36.43Z",
  "Items": [
    {
      "Id": 35,
      "ReferenceOffer": "premium-offer",
      "IsVisible": true,
      "Name": "Premium",
      "TitleLocalized": "Premium",
      "PricingLocalized": "Euro 190.00/month(s) ",
      "Currency": "EUR",
      "Pricing": 19000,
      "PricingSubtotal": 19000,
      "PricingTotal": 22800,
      "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,
      "Name": "Premium Pro+",
      "TitleLocalized": "Premium Pro+",
      "PricingLocalized": "Euro 250.00/month(s) ",
      "Currency": "EUR",
      "Pricing": 25000,
      "PricingSubtotal": 25000,
      "PricingTotal": 30000,
      "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 containing your offers. If not specified, then the offers of the default segment are returned. 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": "2019-03-30T12:44:07.26Z",
  "Items": [
    {
      "Id": 35,
      "ReferenceOffer": "premium-offer",
      "IsVisible": true,
      "Name": "Premium",
      "TitleLocalized": "Premium",
      "PricingLocalized": "Euro 190.00/month(s) ",
      "Currency": "EUR",
      "Pricing": 19000,
      "PricingSubtotal": 19000,
      "PricingTotal": 22800,
      "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/{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": "2019-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/{Unique-encrypted-url1}"
        }
      ]
    },
    {
      "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/{Unique-encrypted-url2}"
        }
      ]
    }
  ]
}

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
Properties Properties of the Feature PropertyFeature String

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": "2019-08-09T11:51:46.92Z",
  "Items": [
    {
      "Id": 47,
      "ReferenceFeature": "module-a",
      "IsVisible": true,
      "Properties": "None",
      "TitleLocalized": "Module A",
      "TypeFeature": "OnOff"
    },
    {
      "Id": 48,
      "ReferenceFeature": "users",
      "IsVisible": true,
      "Properties": "None",
      "TitleLocalized": "Active Users",
      "TypeFeature": "Limitation"
    },
    {
      "Id": 49,
      "ReferenceFeature": "module-b",
      "IsVisible": true,
      "Properties": "None",
      "TitleLocalized": "Module B",
      "TypeFeature": "OnOff"
    },
    {
      "Id": 50,
      "ReferenceFeature": "text-messages",
      "IsVisible": true,
      "Properties": "None",
      "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,
    "Properties": "None",
    "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": "2019-08-09T12:38:55.00Z",
  "DatePeriodStart": "2019-08-09T12:38:55.00Z",
  "DatePeriodEnd": "2019-08-23T12:38:55.00Z",
  "DateTerm": "2019-08-23T12:38:55.00Z",
  "StateSubscriptionAfterTerm": "Running",
  "IsTrial": true,
  "CountDaysTrial": 13,
  "IsEngaged": true,
  "IsCustomerBillable": true,
  "IsPaymentCappingReached": false,
  "DateNextBilling": "2019-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": "2019-08-09T12:38:53.76Z",
  "Links": [
    {
      "rel": "self",
      "href": "/v1/Subscription/44082"
    },
    {
      "rel": "hosted-related-subscription",
      "href": "https://sandbox-eur.proabono.com/overview-subscription/{Unique-Encrypted-URL1}"
    },
    {
      "rel": "hosted-upgrade",
      "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Encrypted-URL2}"
    }
  ]
}
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
PricingSubtotal Amount of the offer in cents without taxes Integer
PricingTotal Amount of the offer in cents with taxes 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
DateResetConsumption Reset Date of the consumption 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
<!-- IDK Properties -->
TitleLocalized Title of the Feature in the language of the Customer String
PricingLocalized Text of the price localized for 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",$
    "PricingSubtotal": 25000,
    "PricingTotal": 25000,
    "StateSubscription": "InitiatedAgent",
    "DateStart": "2020-02-12T10:10:44.00Z",
    "DatePeriodStart": "2020-02-12T10:10:44.00Z",
    "DatePeriodEnd": "2020-03-12T10:10:44.00Z",
    "DateTerm": "2020-03-12T10:10:44.00Z",
    "DateResetConsumption": "2020-03-12T10:10:44.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": false,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-02-12T15:34:19.00Z",
    "TitleLocalized": "Premium Pro+",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "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,
            "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
            "TitleLocalized": "Module A",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
            "TitleLocalized": "Active Users",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 10,
            "QuantityCurrent": 10
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
            "TitleLocalized": "Module B",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 50,
            "ReferenceFeature": "text-messages",
            "IsVisible": true,
            "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
            "TitleLocalized": "Text Messages Sent",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Consumption",
            "QuantityIncluded": 100,
            "QuantityCurrent": 0
        }
    ],
    "DateUpdate": "2019-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/register/{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

Create a Subscription with custom free trial period

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

Example Response
{
    "Id": 430258,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 4900,
    "PricingTotal": 4900,
    "StateSubscription": "Running",
    "DateStart": "2020-03-25T17:45:43.00Z",
    "DatePeriodStart": "2020-03-25T17:45:43.00Z",
    "DatePeriodEnd": "2020-04-15T17:45:43.00Z",
    "DateTerm": "2020-04-15T17:45:43.00Z",
    "DateResetConsumption": "2020-04-15T17:45:43.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsTrial": true,
    "CountDaysTrial": 20,
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "AmountUpFront": 100000,
    "DurationTrial": 21,
    "UnitTrial": "Day",
    "AmountRecurrence": 4900,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-25T17:45:43.28Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=430258"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Encrypted-URL2}"
        }
    ]
}

ProAbono creates a subscription based on an Offer.

During the creation of the subscription,

Example : If, originally, the offer selected or desired by the customer has a 7 days free trial, you can create a subscription based on the desired offer and override the 7 days free trial by 21 days or the duration you want.

Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String
DurationTrial Duration trial of the Offer Integer
UnitTrial Unit Time of Trial of the Offer String (Day, Week, Month, Year)

See all request parameters you can use/combine at Override a Subscription.

Querystring Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Create a Subscription with custom upfront fee

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

Example Response
{
    "Id": 430272,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 4900,
    "PricingTotal": 4900,
    "StateSubscription": "Running",
    "DateStart": "2020-03-25T18:10:02.00Z",
    "DatePeriodStart": "2020-03-25T18:10:02.00Z",
    "DatePeriodEnd": "2020-04-25T18:10:02.00Z",
    "DateTerm": "2020-04-25T18:10:02.00Z",
    "DateResetConsumption": "2020-04-25T18:10:02.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "AmountUpFront": 10000,
    "AmountRecurrence": 4900,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-25T18:10:02.56Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=430272"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Encrypted-URL2}"
        }
    ]
}

ProAbono creates a subscription based on an Offer.

During the creation of the subscription,

Example : If, originally, the offer selected or desired by the customer has an Upfront fee of 50 €, you can create a subscription based on the desired offer and override the 50 € fees by 100 € or the amount you want.

Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String
AmountUpFront Amount UpFront of the Offer Integer

See all request parameters you can use/combine at Override a Subscription.

Querystring Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Create a Subscription with custom period & amount

Example Request
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-offer",
    "DurationRecurrence" : 3,
    "UnitRecurrence" : "Month",
    "AmountRecurrence" : 19900
}

Example Response
{
    "Id": 430271,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 19900,
    "PricingTotal": 19900,
    "StateSubscription": "Running",
    "DateStart": "2020-03-25T18:08:38.00Z",
    "DatePeriodStart": "2020-03-25T18:08:38.00Z",
    "DatePeriodEnd": "2020-06-25T18:08:38.00Z",
    "DateTerm": "2020-06-25T18:08:38.00Z",
    "DateResetConsumption": "2020-03-27T06:00:00.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span> <span class=\"frequency\">tous les 3 mois</span>",
    "AmountUpFront": 100000,
    "AmountRecurrence": 19900,
    "DurationRecurrence": 3,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-25T18:08:38.37Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=430271"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Encrypted-URL2}"
        }
    ]
}

ProAbono creates a subscription based on an Offer.

During the creation of the subscription, an other price and/or other periodicity can be set.

Example : If, originally, the offer selected or desired by the customer is 100 € monthly, you can create a subscription based on the desired offer and override the 100 € monthly by 199 € quarterly or what you want

Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String
AmountRecurrence Amount of each recurrence in cents Integer
DurationRecurrence Number of Recurrence Time Unit Integer
UnitRecurrence Time Unit of Recurrence TimeUnit

See all request parameters you can use/combine at Override a Subscription.

Querystring Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Create a Subscription with custom features

Example Request
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-offer",
    "AmountUpFront": 150000,
    "DurationRecurrence": 3,
    "UnitRecurrence": "Month",
    "AmountRecurrence": 19900,
    "Features": [
        {
            "ReferenceFeature": "module-a",
            "IsEnabled": true
        },      
        {
            "ReferenceFeature": "module-b",
            "IsIncluded": false,
            "IsEnabled": true,
            "Steps": [
                {
                    "AmountCeiling": "3500"
                }
            ]
        },
        {
            "ReferenceFeature": "module-c",
            "IsEnabled": true
        },          
        {
            "ReferenceFeature": "users",
            "QuantityIncluded": 3,
            "QuantityCurrent": 10
        },
        {
            "ReferenceFeature": "agents",
            "QuantityIncluded": 5,
            "QuantityCurrent": 20,
            "Steps": [
                {
                    "Increment": "1",
                    "AmountPerIncrement": "4000"
                }
            ]
        }
    ]
}

Example Response
{
    "Id": 430447,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 19900,
    "PricingTotal": 19900,
    "StateSubscription": "Running",
    "DateStart": "2020-03-26T10:19:36.00Z",
    "DatePeriodStart": "2020-03-26T10:19:36.00Z",
    "DatePeriodEnd": "2020-06-26T10:19:36.00Z",
    "DateTerm": "2020-06-26T10:19:36.00Z",
    "DateResetConsumption": "2020-03-27T06:00:00.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span> <span class=\"frequency\">tous les 3 mois</span>",
    "AmountUpFront": 150000,
    "AmountRecurrence": 19900,
    "DurationRecurrence": 3,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 3,
            "QuantityCurrent": 10
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">35.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": true
        },
        {
            "Id": 243,
            "ReferenceFeature": "agents",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">40.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 20
        },
        {
            "Id": 600,
            "ReferenceFeature": "module-c",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module C",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        }
    ],
    "DateUpdate": "2020-03-26T10:19:36.41Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=430447"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Encrypted-URL1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Encrypted-URL2}"
        }
    ]
}

ProAbono creates a subscription based on an Offer.

During the creation of the subscription :

Example : The offer selected or desired by the customer has somes features : Module A, Module B, Users, Agents (an other type of users). During you can (if needed),

Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String

See all request parameters you can use/combine at Override a Subscription.

Querystring Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Create & Start a Subscription in the future

Example Request
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-offer",
    "DateStart": "2098-02-14T23:59:59.65Z"
}

Example Response
{
    "Id": 423427,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 4900,
    "PricingTotal": 4900,
    "StateSubscription": "Delayed",
    "DateStart": "2098-02-14T23:59:59.65Z",
    "DateTerm": "2098-02-14T23:59:59.65Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "AmountUpFront": 0,
    "AmountRecurrence": 4900,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-12T13:47:33.40Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=423427"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Crypted-Url-2}"
        }
    ]
}
Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String
DateStart Start Date of the Subscription. Must be in the future. DateTime

See all request parameters you can use/combine at Override a Subscription.

QueryString Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Create & Start a Subscription in the past

Example Request
POST https://api-2.proabono.com/v1/Subscription
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-offer",
    "DateStart": "2020-02-14T08:00:00.00Z"
}

Example Response
{
    "Id": 423428,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 4900,
    "PricingTotal": 4900,
    "StateSubscription": "Running",
    "DateStart": "2020-02-14T08:00:00.00Z",
    "DatePeriodStart": "2020-02-14T08:00:00.00Z",
    "DatePeriodEnd": "2020-03-14T08:00:00.00Z",
    "DateTerm": "2020-03-14T08:00:00.00Z",
    "DateResetConsumption": "2020-03-14T08:00:00.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "AmountUpFront": 0,
    "AmountRecurrence": 4900,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-12T13:48:56.26Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=423428"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Crypted-Url-2}"
        }
    ]
}
Request Parameters
Parameters Description Type
ReferenceOffer Reference of the offer in which the customer will be created String
ReferenceCustomer List all subscriptions of a specific Customer String
DateStart Start Date of the Subscription. Must be in the past. DateTime

See all request parameters you can use/combine at Override a Subscription.

QueryString Parameters

See all querystring parameters you can use/combine at Create a Subscription.

Returns

Migrate a Subscription

Example Request
POST https://api-2.proabono.com/v1/Subscription?Migration=true
{
    "ReferenceCustomer": "123456",
    "ReferenceOffer": "premium-offer",
    "DateStart": "2020-02-14T08:00:00.00Z"
}

Example Response
{
    "Id": 423429,
    "IdSegment": 3,
    "IdOffer": 6994,
    "IdCustomer": 587475,
    "IdCustomerBuyer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceOffer": "premium-offer",
    "ReferenceCustomer": "123456",
    "ReferenceCustomerBuyer": "123456",
    "PricingSubtotal": 4900,
    "PricingTotal": 4900,
    "StateSubscription": "Running",
    "DateStart": "2020-02-14T08:00:00.00Z",
    "DatePeriodStart": "2020-02-14T08:00:00.00Z",
    "DatePeriodEnd": "2020-03-14T08:00:00.00Z",
    "DateTerm": "2020-03-14T08:00:00.00Z",
    "DateResetConsumption": "2020-03-14T08:00:00.00Z",
    "StateSubscriptionAfterTerm": "Running",
    "IsEngaged": false,
    "IsCustomerBillable": true,
    "IsPaymentCappingReached": false,
    "DateNextBilling": "2020-03-27T06:00:00.00Z",
    "TitleLocalized": "Premium",
    "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
    "AmountUpFront": 0,
    "AmountRecurrence": 4900,
    "DurationRecurrence": 1,
    "UnitRecurrence": "Month",
    "Features": [
        {
            "Id": 47,
            "ReferenceFeature": "module-a",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module A",
            "TypeFeature": "OnOff",
            "IsIncluded": true,
            "IsEnabled": true
        },
        {
            "Id": 48,
            "ReferenceFeature": "users",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Utilisateurs",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">12.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 2,
            "QuantityCurrent": 0
        },
        {
            "Id": 49,
            "ReferenceFeature": "module-b",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Module B",
            "DescriptionLocalized": "Ce module est simplement fabuleux. Il vous facilitera grandement la vie.",
            "PricingLocalized": "en&nbsp;option <span class=\"amount\">+<span class=\"amount-value\">25.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
            "TypeFeature": "OnOff",
            "IsIncluded": false,
            "IsEnabled": false
        },
        {
            "Id": 243,
            "ReferenceFeature": "agent",
            "IsVisible": true,
            "Properties": "None",
            "TitleLocalized": "Agents",
            "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">10.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
            "TypeFeature": "Limitation",
            "QuantityIncluded": 5,
            "QuantityCurrent": 5
        }
    ],
    "DateUpdate": "2020-03-12T13:49:06.62Z",
    "Links": [
        {
            "rel": "self",
            "href": "/v1/Subscription?idSubscription=423429"
        },
        {
            "rel": "hosted-related-subscription",
            "href": "https://sandbox-eur.proabono.com/portal-sub/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-upgrade",
            "href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Crypted-Url-2}"
        }
    ]
}

When a subscription must be migrated to ProAbono, it means that the current period has been already billed and must NOT be billed again. Therefore using ?Migration=true will start the subscription without billing the first period.

Request Parameters

See all request parameters you can use/combine at Override a Subscription.

Querystring Parameters
Parameters Description Type
Migration ?Migration=true starts the subscription without billing the first period. String

See all querystring parameters you can use/combine at Create a Subscription.

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": "2019-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/register/{Unique-Crypted-Url-3}"
        }
    ]
}

Retrieve a Subscription. 2 definitions are available :

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":"2019-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": "2019-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",
      "PricingSubtotal": 25000,
      "PricingTotal": 25000,
      "StateSubscription": "Running",
      "DateStart": "2019-08-09T13:40:10.00Z",
      "DatePeriodStart": "2019-08-09T13:40:10.00Z",
      "DatePeriodEnd": "2019-09-09T13:40:10.00Z",
      "DateTerm": "2019-09-09T13:40:10.00Z",
      "DateResetConsumption": "2019-09-09T13:40:10.00Z",
      "StateSubscriptionAfterTerm": "Running",
      "IsTrial": false,
      "IsEngaged": false,
      "IsCustomerBillable": true,
      "IsPaymentCappingReached": false,
      "DateNextBilling": "2019-09-09T19:40:10.00Z",
      "TitleLocalized": "Premium Pro+",
      "PricingLocalized": "<span class=\"best-price\">à partir de</span> <span class=\"amount\"><span class=\"amount-value\">0.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span><span class=\"frequency\">/mois</span>",
      "DurationTrial": 0,
      "AmountRecurrence": 25000,
      "DurationRecurrence": 1,
      "UnitRecurrence": "Month",
      "Features": [
        {
          "Id": 47,
          "ReferenceFeature": "module-a",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
          "TitleLocalized": "Module A",
          "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 48,
          "ReferenceFeature": "users",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
          "TitleLocalized": "Active Users",
          "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
          "TypeFeature": "Limitation",
          "QuantityIncluded": 10,
          "QuantityCurrent": 10
        },
        {
          "Id": 49,
          "ReferenceFeature": "module-b",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
          "TitleLocalized": "Module B",
          "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
          "DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
          "TypeFeature": "OnOff",
          "IsIncluded": true,
          "IsEnabled": true
        },
        {
          "Id": 50,
          "ReferenceFeature": "text-messages",
          "IsVisible": true,
          "Properties": "UpdatableBeforeSubscription, UpdateAtFullPrice",
          "TitleLocalized": "Text Messages Sent",
          "PricingLocalized": "<span class=\"amount\">+<span class=\"amount-value\">50.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>/unité&nbsp;supp.",
          "TypeFeature": "Consumption",
          "QuantityIncluded": 100,
          "QuantityCurrent": 120
        }
      ],
      "DateUpdate": "2019-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": "2019-08-03T13:38:41.00Z",
      "DatePeriodStart": "2019-08-03T13:38:41.00Z",
      "DatePeriodEnd": "2019-09-03T13:38:41.00Z",
      "DateTerm": "2019-09-03T13:38:41.00Z",
      "StateSubscriptionAfterTerm": "Terminated",
      "IsTrial": false,
      "IsEngaged": false,
      "IsCustomerBillable": true,
      "IsPaymentCappingReached": false,
      "DateNextBilling": "2019-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": "2019-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 - Quoting

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

Quote 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": "&euro; 267.75",
    "DatePeriodStart": "2019-08-10T06:21:47.71Z",
    "DatePeriodTerm": "2019-09-10T06:21:47.71Z",
    "AmountSubtotal": 21000,
    "AmountTotal": 26775,
    "Details": [
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 26775,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2019-08-10T06:21:47.71Z",
            "DatePeriodTerm": "2019-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

Quote 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": "&euro; 521.47",
    "DatePeriodStart": "2019-08-10T06:56:24.42Z",
    "DatePeriodTerm": "2019-09-10T06:56:24.42Z",
    "AmountSubtotal": 40900,
    "AmountTotal": 52147,
    "Details": [
        {
            "LabelLocalized": "Up-front amount",
            "AmountTotalDue": 25372,
            "TypeMove": "SubscriptionUpFront",
            "DateMove": "2019-08-10T06:56:24.42Z",
            "AmountSubtotal": 19900,
            "AmountTotal": 25372
        },
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 26775,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2019-08-10T06:56:24.42Z",
            "DatePeriodTerm": "2019-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

Quote 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": "&euro; 318.75",
    "DatePeriodStart": "2019-08-10T07:41:57.83Z",
    "DatePeriodTerm": "2019-09-10T07:41:57.83Z",
    "AmountSubtotal": 25000,
    "AmountTotal": 31875,
    "Details": [
        {
            "IdSubscription": 44179,
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 31875,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2019-08-10T07:41:57.83Z",
            "DatePeriodTerm": "2019-09-10T07:41:57.83Z",
            "AmountSubtotal": 25000,
            "AmountTotal": 31875
        }
    ],
    "NextTerm": {
        "IdSubscription": 44179,
        "AmountTotalDue": 31875,
        "PricingLocalized": "&euro; 318.75",
        "DatePeriodStart": "2019-09-10T07:41:57.83Z",
        "DatePeriodTerm": "2019-10-10T07:41:57.83Z",
        "AmountSubtotal": 25000,
        "AmountTotal": 31875,
        "Details": [
            {
                "IdSubscription": 44179,
                "LabelLocalized": "Subscription amount",
                "AmountTotalDue": 31875,
                "TypeMove": "SubscriptionRecurrence",
                "DatePeriodStart": "2019-09-10T07:41:57.83Z",
                "DatePeriodTerm": "2019-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

Quote 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 &euro;",
    "DatePeriodStart": "2019-08-10T07:32:13.76Z",
    "DatePeriodTerm": "2019-09-09T12:33:32.00Z",
    "AmountSubtotal": 3898,
    "AmountTotal": 4971,
    "Details": [
        {
            "IdSubscription": 44081,
            "LabelLocalized": "Subscription - refund on recurring flat fee",
            "AmountTotalDue": -26089,
            "TypeMove": "SubscriptionRecurrenceRefund",
            "DatePeriodStart": "2019-08-10T07:32:13.76Z",
            "DatePeriodTerm": "2019-09-09T12:33:30.48Z",
            "AmountSubtotal": -20463,
            "AmountTotal": -26089
        },
        {
            "LabelLocalized": "Subscription amount",
            "AmountTotalDue": 31060,
            "TypeMove": "SubscriptionRecurrence",
            "DatePeriodStart": "2019-08-10T07:32:13.76Z",
            "DatePeriodTerm": "2019-09-09T12:33:32.00Z",
            "AmountSubtotal": 24361,
            "AmountTotal": 31060
        }
    ],
    "NextTerm": {
        "AmountTotalDue": 31875,
        "PricingLocalized": "318.75 &euro;",
        "DatePeriodStart": "2019-09-09T12:33:32.00Z",
        "DatePeriodTerm": "2019-10-09T12:33:32.00Z",
        "AmountSubtotal": 25000,
        "AmountTotal": 31875,
        "Details": [
            {
                "LabelLocalized": "Subscription amount",
                "AmountTotalDue": 31875,
                "TypeMove": "SubscriptionRecurrence",
                "DatePeriodStart": "2019-09-09T12:33:32.00Z",
                "DatePeriodTerm": "2019-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

Quote 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": "2019-08-09T12:13:50.65Z"
}

Example Request 2
POST https://api-2.proabono.com/v1/Pricing/Usage
{
    "ReferenceFeature": "users",
    "ReferenceCustomer": "123456",
    "QuantityCurrent":6,
    "DateStamp": "2019-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": "2019-08-09T12:13:50.65Z"
}

Example Response 3
{
    "IdSubscription": 44082,
    "IdFeature": 48,
    "AmountTotalDue": 5038,
    "PricingLocalized": "&euro; 50.38",
    "DatePeriodStart": "2019-08-09T15:58:20.73Z",
    "DatePeriodTerm": "2019-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": "2019-08-09T15:58:20.73Z",
            "DatePeriodTerm": "2019-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": "2019-08-09T12:13:50.65Z"
}

Example Response 4
{
    "IdSubscription": 44082,
    "IdFeature": 48,
    "AmountTotalDue": 5038,
    "PricingLocalized": "&euro; 50.38",
    "DatePeriodStart": "2019-08-09T15:58:20.73Z",
    "DatePeriodTerm": "2019-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": "2019-08-09T15:58:20.73Z",
            "DatePeriodTerm": "2019-08-23T12:38:55.00Z",
            "QuantityReported": 6,
            "QuantityBilled": 4,
            "AmountSubtotal": 3952,
            "AmountTotal": 5038
        }
    ],
    "NextTerm": {
        "IdSubscription": 44082,
        "LabelLocalized": "Subscription cost after modification",       
        "PricingLocalized": "&euro; 191.22",
        "DatePeriodStart": "2019-08-23T12:38:55.00Z",   
        "DatePeriodTerm": "2019-09-23T12:38:55.00Z",
        "AmountSubtotal": 15000,
        "AmountTotal": 19122,
        "Details": [
            {
                "IdSubscription": 44082,
                "LabelLocalized": "Flat fee",
                "AmountTotalDue": 6374,
                "TypeMove": "AutoFSubscriptionRecurrence",
                "DatePeriodStart": "2019-08-23T12:38:55.00Z",
                "DatePeriodTerm": "2019-09-23T12:38:55.00Z",
                "AmountSubtotal": 5000,
                "AmountTotal": 6374
            },      
            {
                "IdSubscription": 44082,
                "IdFeature": 48,
                "LabelLocalized": "Feature - Active Users",
                "AmountTotalDue": 12748,
                "TypeMove": "AutoFeatureProratable",
                "DatePeriodStart": "2019-08-23T12:38:55.00Z",
                "DatePeriodTerm": "2019-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

Quote a BalanceLine Creation

Definition
POST /v1/Pricing/BalanceLine

Example Request
POST https://api-2.proabono.com/v1/Pricing/BalanceLine
{
    "ReferenceCustomer": "123456",
    "Label": "Consulting XYZ in hours",
    "Amount": 50000,
    "Quantity": 18

}

Example Response
{
    "IdSegment": 3,
    "IdCustomer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceCustomer": "123456",
    "LabelLocalized": "Consulting XYZ in hours",
    "PricingLocalized": "<span class=\"amount\"><span class=\"amount-value\">600.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
    "Currency": "EUR",
    "AmountSubtotal": 50000,
    "AmountTotal": 60000,
    "DateMove": "2020-02-19T16:15:56.38Z",
    "QuantityReported": 18,
    "QuantityBilled": 18
}

Compute the pricing of a BalanceLine creation.

Request Parameters

Same as Create a BalanceLine.

QueryString Parameters

Same as Create a BalanceLine.

Returns

API - Balances

Every customer has a Balance which lists all the debit and credit lines related to subscriptions, paid features, paid consumptions, refunds, ... Lines can be added also by API.

BalanceLine Resource

Example Response
{
    "IdSegment": 2,
    "IdCustomer": 72461,
    "IdSubscription": 456789,
    "ReferenceCustomer": "123456",
    "LabelLocalized": "Consulting XYZ in hours",
    "PricingLocalized": "<span class=\"amount\"><span class=\"amount-value\">600.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
    "Currency": "EUR",
    "AmountSubtotal": 50000,
    "AmountTotal": 60000,
    "DateMove": "2020-02-13T10:58:32.22Z",
    "QuantityReported": 18,
    "QuantityBilled": 18
}
Parameter Description Type
IdSegment Id of the Segment in which the Customer has been created. Integer
IdCustomer Id of the Customer related to this BalanceLine Integer
IdSubscription Id of the Subscription related to this BalanceLine Integer
ReferenceCustomer The unique identifier used within your own application for this customer String
LabelLocalized Text of the label localized for the BalanceLine String
PricingLocalized Text of the price localized for the BalanceLine String
Currency Currency of the BalanceLine String
AmountSubtotal Amount without taxes in cents Integer
AmountTotal Amount with taxes in cents Integer
DateMove Date of the BalanceLine DateTime
QuantityReported Quantity reported to the Customer Integer
QuantityBilled Quantity billed to the Customer and be displayed in a future invoice Integer

Create a BalanceLine

Definition
POST /v1/BalanceLine

Example Request 1
POST https://api-2.proabono.com/v1/BalanceLine
{
    "ReferenceCustomer": "123456",
    "Label": "Consulting XYZ in hours",
    "Amount": 50000,
    "Quantity": 18

}

Example Response 1
{
    "IdSegment": 3,
    "IdCustomer": 72461,
    "ReferenceCustomer": "123456",
    "LabelLocalized": "Consulting XYZ in hours",
    "PricingLocalized": "<span class=\"amount\"><span class=\"amount-value\">600.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
    "Currency": "EUR",
    "AmountSubtotal": 50000,
    "AmountTotal": 60000,
    "DateMove": "2020-02-13T10:58:32.22Z",
    "QuantityReported": 18,
    "QuantityBilled": 18
}
Request Parameters
Parameter Required? Description Type
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
IdCustomer Yes Id of the Customer related to this BalanceLine Integer
IdSubscription No Id of the Subscription related to this BalanceLine Integer
Label No Label of the BalanceLine will be displayed in the invoice String
Amount No Amount in cents calculated before taxes Integer
Quantity No Quantity est purely informative and will be displayed in the invoice but has no other impact. Integer
Returns

List BalanceLines

Definition
GET /v1/BalanceLines

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

Example Response 1
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2020-02-13T13:30:17.51Z",
  "Items": [
    {
      "IdSegment": 3,
      "IdCustomer": 587771,
      "IdSubscription": 417431,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceCustomer": "123456",
      "LabelLocalized": "Consulting XYZ in hours",
      "TypeMove": "None",
      "PricingLocalized": "<span class=\"amount\"><span class=\"amount-value\">600.00</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
      "Currency": "EUR",
      "AmountSubtotal": 50000,
      "AmountTotal": 60000,
      "DateMove": "2020-02-13T10:58:32.22Z",
      "QuantityReported": 18,
      "QuantityBilled": 18
    },
    {
      "IdSegment": 3,
      "IdCustomer": 587771,
      "IdSubscription": 417428,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceCustomer": "123456",
      "LabelLocalized": "Flat fee",
      "TypeMove": "AutoSubscriptionRecurrence",
      "PricingLocalized": "<span class=\"amount\"><span class=\"amount-value\">478.80</span>&nbsp;<span class=\"currency-value\">&euro;</span></span>",
      "Currency": "EUR",
      "AmountSubtotal": 39900,
      "AmountTotal": 47880,
      "DatePeriodStart": "2020-02-13T10:29:56.00Z",
      "DatePeriodTerm": "2020-03-13T10:21:17.00Z"
    },

  ],
    "Computations": {
    "AmountSubtotal": 89900,
    "AmountTotal": 1078800
  }
}

Example Request 2
GET https://api-2.proabono.com/v1/BalanceLines?ReferenceCustomer=123456&sizepage=0

Example Response 2
{
  "TotalItems": 2,
  "DateGenerated": "2020-02-13T13:30:17.51Z",
  "Computations": {
    "AmountSubtotal": 40943,
    "AmountTotal": 49131
  }
}

Retrieve all BalanceLines

Optional Querystring Parameters
Parameters Description Type
ReferenceSegment List all Balances lines of a specific Segment with its ReferenceSegment String
IdSegment List all Balances lines of a specific Segment with its IdSegment Integer
ReferenceFeature List all Balances lines of a specific Feature with its ReferenceFeature String
IdFeature List all Balances lines of a specific Feature with its IdFeature Integer
ReferenceCustomer List all Balances lines of a specific Customer with its ReferenceCustomer String
IdCustomer List all Balances lines of a specific Customer with its IdCustomer Integer
IdSubscription List all Balances lines of a specific Subscription Integer
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

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

Example:

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

Note

Returns

Bill a Customer

Definition
POST /v1/Billing/Customer

Example Request 1
POST https://api-2.proabono.com/v1/Billing/Customers?ReferenceCustomer=123456

Example Response 1
{
    "Id": 549013,
    "IdSegment": 3,
    "IdCustomer": 587475,
    "ReferenceSegment": "sandbox-eur",
    "ReferenceCustomer": "123456",
    "FullNumber": "S-3.00000033",
    "StateInvoice": "PaymentDue",
    "DateIssue": "2020-03-18T14:43:15.33Z",
    "DatePaymentLimit": "2020-04-17T00:00:00.00Z",
    "TypePayment": "ExternalBank",
    "AmountSubtotal": 109500,
    "AmountTotal": 131400,
    "Currency": "EUR",
    "DateUpdate": "2020-03-18T14:43:15.15Z",
    "Links": [
        {
            "rel": "hosted-related-invoice",
            "href": "https://sandbox-eur.proabono.com/portal-inv-pdf/{Unique-Crypted-Url-1}"
        },
        {
            "rel": "hosted-charge",
            "href": "https://sandbox-eur.proabono.com/inv-charge/{Unique-Crypted-Url-2}"
        },
        {
            "rel": "hosted-collection-invoice",
            "href": "https://sandbox-eur.proabono.com/portal-inv-list/{Unique-Crypted-Url-3}"
        }
    ]
}

To bill a customer

Request Parameters
Parameters Required? Description Type
ReferenceCustomer Yes The unique identifier used within your own application for this customer. String
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
Returns

API - Invoices

Invoice describes what you sold.

Invoice Resource

Example Response
{
  "Id": 499734,
  "IdSegment": 3,
  "IdCustomer": 587771,
  "ReferenceSegment": "sandbox-eur",
  "ReferenceCustomer": "123456",
  "FullNumber": "S-3.00000004",
  "StateInvoice": "PaymentDuePending",
  "DateIssue": "2020-02-13T10:31:15.97Z",
  "DatePayment": "2020-02-14T10:31:15.63Z",
  "DatePaymentProgrammed": "2020-02-13T10:31:15.66Z",
  "TypePayment": "DirectDebit",
  "AmountSubtotal": 29900,
  "AmountTotal": 35880,
  "Currency": "EUR",
  "DateUpdate": "2020-02-13T10:31:15.99Z",
  "Links": [
    {
      "rel": "hosted-related-invoice",
      "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL1}"
    },
    {
      "rel": "hosted-collection-invoice",
      "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
    }
  ]
}
Parameter Description Type
Id The identifier of the invoice Integer
IdSegment Id of the Segment in which the Customer has been created. Integer
IdCustomer Id of the Customer related to this CustomerMove Integer
ReferenceSegment Reference of the Segment in which your customer has been created/added. String
ReferenceCustomer The unique identifier used within your own application for this customer (ReferenceCustomer property) String
FullNumber FullNumber of the Invoice String
StateInvoice State of the Invoice StateInvoice
DateIssue Date when the Invoice has been issued DateTime
DatePayment Date of payment DateTime
DatePaymentProgrammed Programmed date of payment DateTime
DatePaymentLimit Limit of date of payment DateTime
TypePayment Type of payment TypePayment
AmountSubtotal Amount without taxes in cents Integer
AmountTotal Amount with taxes in cents Integer
Currency Currency of the Invoice String
DateUpdate Date of last update of the Invoice Datetime
Links Collection of Links -

Collection of links

Rel Description
hosted-related-invoice Unique encrypted link to the requested PDF invoice.
hosted-collection-invoice Unique encrypted link to the page which contains all invoices of a Customer or a Subscription.

Retrieve an Invoice

Definitions
GET /v1/Invoice?idInvoice={IdInvoice}
GET /v1/Invoice?FullNumber={FullNumber}


Example Request
GET https://api-2.proabono.com/v1/Invoice?IdInvoice=499734
GET https://api-2.proabono.com/v1/Invoice?FullNumber=S-1304.00000004

Example Response
{
  "Id": 499734,
  "IdSegment": 1304,
  "IdCustomer": 587771,
  "ReferenceSegment": "Demo1",
  "ReferenceCustomer": "123456",
  "FullNumber": "S-1304.00000004",
  "StateInvoice": "PaymentDuePending",
  "DateIssue": "2020-02-13T10:31:15.97Z",
  "DatePayment": "2020-02-14T10:31:15.63Z",
  "DatePaymentProgrammed": "2020-02-13T10:31:15.66Z",
  "TypePayment": "DirectDebit",
  "AmountSubtotal": 29900,
  "AmountTotal": 35880,
  "Currency": "EUR",
  "DateUpdate": "2020-02-13T10:31:15.99Z",
  "Links": [
    {
      "rel": "hosted-related-invoice",
      "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL1}"
    },
    {
      "rel": "hosted-collection-invoice",
      "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
    }
  ]
}

To retrieve a Invoice, use the IdInvoice or the FullNumber

Request Parameters
Parameter Required? Description Type
IdInvoice Yes Id of the Invoice related to this Payment Integer
FullNumber Yes FullNumber of the Invoice String
Returns

List Invoices

Definitions
GET /v1/Invoices?ReferenceCustomer={ReferenceCustomer}
GET /v1/Invoices?IdCustomer={IdCustomer}
Get /v1/Invoices?IdSubscription={IdSubscription}


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

Example Response
{
  "Page": 1,
  "SizePage": 10,
  "Count": 2,
  "TotalItems": 2,
  "DateGenerated": "2020-02-13T14:28:23.89Z",
  "Items": [
    {
      "Id": 499734,
      "IdSegment": 3,
      "IdCustomer": 587771,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceCustomer": "123456",
      "FullNumber": "S-3.00000004",
      "StateInvoice": "PaymentDuePending",
      "DateIssue": "2020-02-13T10:31:15.97Z",
      "DatePayment": "2020-02-14T10:31:15.63Z",
      "DatePaymentProgrammed": "2020-02-13T10:31:15.66Z",
      "TypePayment": "DirectDebit",
      "AmountSubtotal": 29900,
      "AmountTotal": 35880,
      "Currency": "EUR",
      "DateUpdate": "2020-02-13T10:31:15.99Z",
      "Links": [
        {
          "rel": "hosted-related-invoice",
          "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL1}"
        },
        {
          "rel": "hosted-collection-invoice",
          "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL2}"
        }
      ]
    },
    {
      "Id": 499729,
      "IdSegment": 3,
      "IdCustomer": 587771,
      "ReferenceSegment": "sandbox-eur",
      "ReferenceCustomer": "123456",
      "FullNumber": "S-3.00000001",
      "StateInvoice": "PaymentDuePending",
      "DateIssue": "2020-02-13T10:21:17.29Z",
      "DatePayment": "2020-02-14T10:21:16.65Z",
      "DatePaymentProgrammed": "2020-02-13T10:21:16.66Z",
      "TypePayment": "DirectDebit",
      "AmountSubtotal": 9900,
      "AmountTotal": 11880,
      "Currency": "EUR",
      "DateUpdate": "2020-02-13T10:21:17.29Z",
      "Links": [
        {
          "rel": "hosted-related-invoice",
          "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL3}"
        },
        {
          "rel": "hosted-collection-invoice",
          "href": "https://sandbox-eur.proabono.com/portal/{Unique-Encrypted-URL4}"
        }
      ]
    }
  ]
}

Retrieve all Invoices

Optional Querystring Parameters
Parameters Description Type
ReferenceCustomer List all Invoices of a specific Customer with its ReferenceCustomer String
IdCustomer List all Invoices of a specific Customer with its IdCustomer Integer
IdSubscription List all Invoices of a specific Subscription Integer
Page Indicate the page returned by ProAbono to a request See Pagination. Integer
SizePage Set the page size. See Pagination. Integer

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

Example:

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

Returns
json