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
- Sign up.
- Get your API Keys and Endpoints from “My Profile” / Integration.
- Try it out! Create your first customer.
Your First Requests
POST /v1/Customer
Accept: application/json
Accept-Encoding: gzip, deflate, compress
{
Email: 'john@doe.com',
Name: 'Mr Doe'
}
...
GET https://api-2.proabono.com/v1/Customer?ReferenceCustomer=123456
The API works with JSON.
To ensure maximal compatibility, use the Accept in all requests :
Accept: application/json
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.
- Username :
Agent key
- Password :
API key
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'
}
Concatenate agent_key and api_key separated with ’:’ -> agent_key:api_key
c7fa57b8-4861-4857:f6797af1-791b-40b1
Base-64 encode the string
YzdmYTU3YjgtNDg2MS00ODU3OmY2Nzk3YWYxLTc5MWItNDBiMQ==
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,
- codes in the 2xx range indicate success,
- codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.),
- and codes in the 5xx range indicate an error with ProAbono’s servers.
The table below describes the response codes that will be issued and gives potential reasons as to why they may have been sent back.
Successful Response Codes | |
---|---|
200 OK: | Successful request |
201 Created: | Successfully created the resource. |
204 No Content: | Successfully processed the request, but no content was sent back |
Unsuccessful Response Codes | |
---|---|
400 Bad Request: | Invalid or missing request parameters Inspect the request parameters and ensure that all required parameters are supplied. Check the response body : ProAbono may supply a hint on how to fix the problem. |
401 Unauthorized: | Invalid or no credentials passed in the request Inspect the authorisation header and ensure that a valid authentication has been provided. |
403 Forbidden: | The operation cannot be processed. The response contains a JSON error object with more information |
404 Not Found: | The requested Resource was not found Check your URL syntax or parameters. |
405 Method not allowed: | The requested resource does not support the supplied HTTP method Check the API documentation, you are doing something unhealthy. |
406 Not Acceptable: | Provided Content-Type or Accept header is not supported. You should probably use application/json. |
422 Unprocessable Entity: | Request syntax is correct, but its content is not. The response body will contains a list of errors that will tell you exactly where the problems are. See Errors section. |
500 Internal Server Error: | An internal error occurred when processing the request. Attempt the request again and if the HTTP 500 error re-occurs contact support@proabono.com |
501 Method Not Implemented: | The requested resource is not implemented yet. Found any ? You probably are a very advanced user. Contact tech support to know more about the release date. |
Errors
Example of an error
{
"Target": "AmountRecurrence",
"Code": "Error.Property.ConvertValue.Exception",
"Message": "Exception while converting given value for the property",
"Exception": "Input string was not in a correct format"
}
If your request results in a 4xx or 5xx HTTP code, the response body does contain an error.
Property | Description | Always returned? |
---|---|---|
Target | The related property | No |
Code | The error code | Yes |
Message | A message localized in your language | Yes |
Exception | More about the error | No |
Example of a list of errors
[
{
"Target": "AmountRecurrence",
"Code": "Error.Property.ValueRequired",
"Message": "A value is required for the property"
},
{
"Target": "Ammount",
"Code": "Error.Property.UnexpectedProperty",
"Message": "Unexpected property"
}
]
List of Errors
Errors list is just a JSON array of errors.
Pagination
{
"Page": 2,
"SizePage": 3,
"Count": 3,
"TotalItems": 40,
"DateGenerated": "2014-12-11T12:45:05.1234714Z",
"Items": [
{
"item":"1"
},
{
"item":"2"
},
{
"item":"3"
}
],
"Links": [
{
"rel": "prev",
"href": "/Subscriptions?page=1&SizePage=3"
},
{
"rel": "next",
"href": "/Subscriptions?page=3&SizePage=3"
}
]
}
Requests that contain multiple items will be paginated by default.
Page
: Page number your are on.SizePage
: Maximum number of items per pageCount
: Number of items on the current pageTotalItems
: Number of items in this collectionLinks
: Most resources will provide these links at the end of the response object in alink
array that supplies links withrel=next
andrel=prev
attributes.
Filters
GET https://api-2.proabono.com/Subscriptions?ReferenceSegment=Sandbox-eur&Page=3&SizePage=20
Every objects collection has multiple available filters that can be passed in the URL.
Available filters are detailled for each object collection below.
Data Formats
Dates
Example
{
"DateStart": "2017-08-09T12:38:55.00Z"
}
Dates are in universal time : UTC.
They are sent and received in ISO 8601 format : YYYY-MM-DDTHH:MM:SSZ
Time Unit
Unit | Description |
---|---|
Day | |
Week | |
Month | |
Year |
Languages
ProAbono supports all languages.
Proabono supports language in ISO 639-1 format.
However you are responsible for the translation.
Common language code are :
Code | Language |
---|---|
de | German |
en | English |
es | Spanish |
fr | French |
nl | Dutch |
pt | Portuguese |
it | Italian |
Countries
Proabono supports country codes in ISO_3166-1 alpha2 format.
Common Country Codes are :
Code | Country |
---|---|
AU | Australia |
BR | Brazil |
CA | Canada |
DE | Germany |
ES | Spain |
FR | France |
GB | United Kingdom of Great Britain |
IT | Italy |
NL | Netherlands |
US | United States of America |
Region/Province/State
Proabono supports Region/Province/State codes in ISO_3166-2 format
Common Region/Province/State Codes are :
Country Code | Region/Province/State code list Url | Country |
---|---|---|
AU | ISO_3166-2:AU | Australia |
BR | ISO_3166-2:BR | Brazil |
CA | ISO_3166-2:CA | Canada |
DE | ISO_3166-2:DE | Germany |
ES | ISO_3166-2:ES | Spain |
FR | ISO_3166-2:FR | France |
GB | ISO_3166-2:GB | United Kingdom of Great Britain |
IT | ISO_3166-2:IT | Italy |
NL | ISO_3166-2:NL | Netherlands |
US | ISO_3166-2:US | United States of America |
State Subscription
State Subscription | Description |
---|---|
InitiatedCustomer | Subscription has been initiated from hosted pages |
InitiatedAgent | Subscription has been initiated by an Agent |
Delayed | Subscription has been validated by the Customer AND the status will turn into Running at DateStart . See Subscription Object. |
Running | Subscription is running |
SuspendedCustomer | Subscription has been suspended by the Customer |
SuspendedPaymentInfoMissing | Subscription has been suspended because a payment is missing |
SuspendedPaymentDue | Subscription has been suspended because of payment due |
SuspendedAgent | Subscription has been suspended by an Agent |
SuspendedSystem | Subscription has been suspended by the system (technical problem) |
TerminatedAtRenewal | Subscription will be terminated at the next renewal (i.e. at the end of the current period) |
History | Subscription is over |
Terminated | Subscription has been terminated |
Deleted | Subscription has been deleted |
State Life
State Life | Description |
---|---|
Ok | Enabled |
ToModerate | To validate |
DisabledUser | Disabled |
DisabledModeration | Rejected (moderation) |
DisabledSystem | Locked |
Deleted | Deleted |
Type Feature
Type Feature | Description |
---|---|
OnOff | For features like Module, Content Access, … |
Limitation | Type for Feature which must be counted BUT its quantity will NOT be reset at each subscription renewal. |
Consumption | Type for Feature which must be counted AND its quantity will be reset at each subscription renewal. |
Address Resource
Example
{
"Company": "John Doe LLC",
"FirstName": "John",
"LastName": "Doe",
"AddressLine1": "123 avenue des Champs Elysées",
"AddressLine2": "1st Floor",
"ZipCode": "75008",
"City": "Paris",
"Country": "FR",
"Region": "FR-75",
"Phone": "+33102030405",
"TaxInformation":"FR1234567890"
}
Property | Description | Type |
---|---|---|
Id | Id of the Address Object | Integer |
Company | Name of the Company | String |
FirstName | - | String |
LastName | - | String |
AddressLine1 | Line 1 of the Address | String |
AddressLine2 | Line 2 of the Address | String |
ZipCode | ZipCode of the Address | String |
City | Name of the City | String |
Country | Code of Country of the Address | CountryCode |
Region | Region stands for Subdivision, Department, Region, Province, State of the Country | RegionCode |
TaxInformation | Tax Information (VAT id, Num TVA Intra, GST…) | String |
Phone | Phone Number | String |
Metadata
Example Request "Create a Customer"
POST https://api-2.proabono.com/v1/Customer
{
"ReferenceCustomer": "123456",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"ReferenceOffer": "premium-pro-plus",
"Metadata":
{
"Gender":"Male",
"Incomes": 150000,
"Kids": 3
}
}
A set of key/value pairs that you can add to an object (Customer, Subscription, …). It can be useful for storing additional information about the object in a structured format. You can unset individual keys if you POST an empty value for that key. You can clear all keys if you POST an empty value for metadata.
At most 5 key/value pairs per object.
Max length of a value is 450 characters.
API - Customers
Customers are the users of your online service.
Each customer contains a ReferenceCustomer. It’s a free field used to uniquely identify a customer.
GET or POST on a customer returns customer-specific links you can use to have the customer access the customer portal, or embed in a iframe. See ’Customer Portal - how it works’
Customer Resource
Example Response
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"ReferenceAffiliation": "janesmith",
"DateAffiliation": "2016-12-03T17:07:35.04Z",
"Metadata":
{
"Gender":"Male",
"Incomes": 150000,
"Kids": 3
}
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
}
]
}
Parameter | Description | Type |
---|---|---|
Id | Id of your customer | Integer |
IdSegment | Id of the Segment in which your Customer has been created | Integer |
ReferenceCustomer | The unique identifier used within your own application for this customer | String |
ReferenceSegment | Reference of the Segment in which your customer has been created/added. | String |
Email of your customer | String | |
Name | Fullname of your customer | String |
Language | Language of your customer | Langage |
ReferenceAffiliation | Reference of the affiliate who brought the customer | String |
Metadata | A set of key/value pairs that you can add to a customer | Metadata |
Links | Collection of Links | - |
Collection of links
Rel | Description |
---|---|
hosted-collection-offers | Unique encrypted link to the page which contains all visible offers available for the concerned Customer. |
hosted-home | Unique encrypted link to the page which contains all subscriptions of the concerned Customer |
hosted-subscribe | Unique encrypted link to redirect the concerned Customer to the subscription page of the offer related to the mentioned ReferenceOffer. Only available when ReferenceOffer has been mentioned in the request. |
hosted-collection-upgrade | Unique encrypted link to the page which contains all visible offers available for upgrade for the concerned Customer. Only available when a customer has already a Running Subscription. |
Create a Customer
Definition
POST /v1/Customer
Example Request 1
POST https://api-2.proabono.com/v1/Customer
{
"ReferenceCustomer": "123456",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en"
}
Example Response 1
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
}
]
}
Example Request 2
POST https://api-2.proabono.com/v1/Customer
{
"ReferenceCustomer": "123456",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"ReferenceOffer": "premium-pro-plus",
"ReferenceAffiliation": "janesmith",
"Metadata":
{
"Gender":"Male",
"Incomes": 150000,
"Kids": 3
}
}
Example Response 2
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"ReferenceAffiliation": "janesmith",
"DateAffiliation": "2016-12-03T17:07:35.04Z",
"Metadata":
{
"Gender":"Male",
"Incomes": 150000,
"Kids": 3
},
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL1}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/subscriptions/{Unique-Encrypted-URL2}"
},
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/subscribe-offer/{Unique-Encrypted-URL3}"
}
]
}
Customers are the users of your online service.
Each customer contains a ReferenceCustomer. It’s a free field used to uniquely identify a customer.
Creating a customer returns customer-specific links you can use to have the customer access the customer portal, or embed in a iframe. See ’Customer Portal - how it works’.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
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
- HTTP 201 in case of a success. Response body contains the created resource.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Retrieve a Customer
GET /v1/Customer?ReferenceCustomer={ref}
Example Request
GET https://api-2.proabono.com/v1/Customer?ReferenceCustomer=123456
Example Response
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"Metadata":
{
"Gender":"Male",
"Incomes": 150000,
"Kids": 3
},
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/offers/{Another-Unique-Encrypted-URL}"
}
]
}
To retrieve a Customer, use the ReferenceCustomer you provided when creating the Customer.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | yes | Reference of the Customer (ReferenceCustomer property) | String |
ReferenceOffer | No | Reference of the offer your customer wants to subscribe. If creation succeed, the responses will contain a direct subscription URL you can redirect the customer to. | String |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
Update a Customer
Creating or updating a customer is the same operation in the ProAbono API. If a customer with the same ReferenceCustomer is posted, then it’s just updated. See Create a customer.
List Customers
Definition
GET /v1/Customers
Example Request
GET https://api-2.proabono.com/v1/Customers
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 3,
"TotalItems": 3,
"DateGenerated": "2015-05-10T18:33:16.28Z",
"Items": [
{
"Id": 342883,
"IdSegment": 3,
"ReferenceCustomer": "user-0d85bd4c",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en"
},
{
"Id": 342856,
"IdSegment": 3,
"ReferenceCustomer": "user-0cb58042",
"ReferenceSegment": "sandbox-eur",
"Name": "Erika Mustermann",
"Email": "erika@mustermann.de",
"Language": "de"
},
{
"Id": 342855,
"IdSegment": 3,
"ReferenceCustomer": "user-f90f9f12",
"ReferenceSegment": "sandbox-eur",
"Name": "Paul Martin",
"Email": "paul@martin.fr",
"Language": "fr"
}
]
}
Retrieve all Customers
Optional Querystring Parameters
Parameters | Description | Type |
---|---|---|
ReferenceSegment | List all Customers created in a specific Segment | String |
ReferenceFeature | List all Customers with an active subscription containing a specific Feature. See List Customers by Feature. | String |
Page | Indicate the page returned by ProAbono to a request. See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
You can combine these parameters to get exactly what you are looking for.
Example:
GET https://api-2.proabono.com/v1/Customers?SizePage=20
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
List Customers by Feature
Definition
GET /v1/Customers?ReferenceFeature={Ref}
Example Request
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=users
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 3,
"TotalItems": 3,
"DateGenerated": "2015-05-10T18:33:16.28Z",
"Items": [
{
"Id": 342883,
"IdSegment": 3,
"ReferenceCustomer": "user-0d85bd4c",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"QuantityIncluded": 3,
"QuantityCurrent": 3,
"DatePeriodStart": "2015-08-25T15:55:54.98Z",
"DatePeriodEnd": "2015-09-03T15:55:54.98Z"
},
{
"Id": 342856,
"IdSegment": 3,
"ReferenceCustomer": "user-0cb58042",
"ReferenceSegment": "sandbox-eur",
"Name": "Erika Mustermann",
"Email": "erika@mustermann.de",
"Language": "de",
"QuantityIncluded": 10,
"QuantityCurrent": 15,
"DatePeriodStart": "2015-08-20T07:28:53.95Z",
"DatePeriodEnd": "2015-09-20T07:28:53.95Z"
},
{
"Id": 342855,
"ReferenceCustomer": "user-f90f9f12",
"ReferenceSegment": "sandbox-eur",
"Name": "Paul Martin",
"Email": "paul@martin.fr",
"Language": "fr",
"QuantityIncluded": 1,
"QuantityCurrent": 1,
"DatePeriodStart": "2015-08-26T08:43:15.12Z",
"DatePeriodEnd": "2015-09-26T08:43:15.12Z"
}
]
}
Retrieve all Customers with an active subscription containing a specific Feature AND describe the relation between each Customer and the specific Feature.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceFeature | yes | Reference of the Feature (ReferenceFeature property) | String |
Examples:
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=module-a
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=users
GET https://api-2.proabono.com/v1/Customers?ReferenceFeature=text-messages
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources with additionnal data.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Retrieve Payment Settings
GET /v1/CustomerSettingsPayment?ReferenceCustomer={ref}
Example Request
GET https://api-2.proabono.com/v1/CustomerSettingsPayment?ReferenceCustomer=123456
Example Response
{
"TypePayment": "Card",
"DateNextBilling": "2016-08-29T20:36:53.00Z"
}
To retrieve a Customer Payment Settings, use the ReferenceCustomer you provided when creating the Customer.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | yes | Reference of the Customer (ReferenceCustomer property) | String |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
Update Payment Settings
POST /v1/CustomerSettingsPayment?ReferenceCustomer={ref}
Example Request
POST https://api-2.proabono.com/v1/CustomerSettingsPayment?ReferenceCustomer=123456
{
"TypePayment": "ExternalBank",
"DateNextBilling": "2017-08-30T20:36:53.00Z"
}
Example Response
{
"TypePayment": "ExternalBank",
"DateNextBilling": "2017-08-30T20:36:53.00Z"
}
To update/set a Customer Payment Settings, use the ReferenceCustomer you provided when creating the Customer.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | yes | Reference of the Customer (ReferenceCustomer property) | String |
DateNextBilling | no | Date of the next billing | DateTime |
TypePayment | no | Set a manual payment method here. Automated payment methods are handled automatically in the Customer Portal. | Possible values: ExternalBank, ExternalCash, ExternalCheck, ExternalOther. |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Anonymize Customer
POST /v1/Customer/Anonymization?ReferenceCustomer={ref}
Example Request
POST https://api-2.proabono.com/v1/Customer/Anonymization?ReferenceCustomer=123456
Example Response
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Language": "en",
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{Unique-Encrypted-URL}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/subscriptions/{Another-Unique-Encrypted-URL}"
}
]
}
To anonymize a Customer, use the ReferenceCustomer you provided when creating the Customer.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | yes | Reference of the Customer (ReferenceCustomer property) | String |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
Revoke Crypted Links
POST /v1/Customer/LinksRevokation?ReferenceCustomer={ref}
Example Request
POST https://api-2.proabono.com/v1/Customer/LinksRevokation?ReferenceCustomer=123456
Example Response
{
"Id": 72461,
"IdSegment": 3,
"ReferenceCustomer": "123456",
"ReferenceSegment": "sandbox-eur",
"Name": "John Doe",
"Email": "john@doe.com",
"Language": "en",
"Links": [
{
"rel": "hosted-collection-offers",
"href": "https://sandbox-eur.proabono.com/offers/{New-Unique-Encrypted-URL}"
},
{
"rel": "hosted-home",
"href": "https://sandbox-eur.proabono.com/subscriptions/{Another-New-Unique-Encrypted-URL}"
}
]
}
To revoke all crypted URLs of the Customer Portal, use the ReferenceCustomer you provided when creating the Customer. More about Crypted URLs.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | yes | Reference of the Customer (ReferenceCustomer property) | String |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Customer is not found or unaccessible. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
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 :
- know the details of its subscription, in other words, what your customers can access, use/do in your site/service, what your customers purchased in details.
- update usages of these features your Customer uses/needs
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 :
- Module A
- Module B
- Number of Users
- Text Messages Sent
- …
Features & Usages are core for your business. Usages describe what you sell and how you sell.
Usage Resource
Example Usage for OnOff Feature
{
"IdSegment": 3,
"IdFeature": 47,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "module-a",
"ReferenceCustomer": "123456",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Example Usage for Limitation and Consumption Feature
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 4,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Property | Description | Type |
---|---|---|
IdSegment | Id of the Segment in which the Customer has been created. | Integer |
IdFeature | Id of the Feature related to this Usage | Integer |
IdCustomer | Id of the Customer related to this Usage | Integer |
IdSubscription | Id of the Subscription related to this Usage. If not returned, it means multiple subscriptions matches that usage. | Integer |
ReferenceSegment | Reference of the segment in which the customer has been created. | String |
ReferenceFeature | Reference of the Feature shared with your site/service and ProAbono. | String |
ReferenceCustomer | The unique identifier used within your own application for this customer | String |
TypeFeature | Type of the Feature (OnOff, Limitation, Consumption) | FeatureType |
IsIncluded | (Only for OnOff feature) It indicates if the feature is included in the subscription of the customer. False indicates that the feature can be enabled. | Boolean |
IsEnabled | (Only for OnOff feature) It indicates if the feature is enabled in the subscription of the customer. | Boolean |
QuantityIncluded | (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature available in the Subscription of the Customer. If not provided it means ‘unlimited’. | Integer |
QuantityCurrent | (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature currently used in the Subscription of the Customer. If not provided it means ‘unlimited’. | Integer |
DatePeriodStart | This is the start of the considered billing period. Used to enforce quota (like 10 emails per months). | DateTime |
DatePeriodEnd | This is the end of the considered billing period. Used to enforce quota | DateTime |
Retrieve Usages for a Customer
Definition
GET /v1/Usages?ReferenceCustomer={ReferenceCustomer}
Example Request
GET https://api-2.proabono.com/v1/Usages?ReferenceCustomer=123456
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 4,
"TotalItems": 4,
"DateGenerated": "2016-03-29T21:54:19.51Z",
"Items": [
{
"IdSegment": 3,
"IdFeature": 47,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "module-a",
"ReferenceCustomer": "123456",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 4,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
"IdSegment": 3,
"IdFeature": 49,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "module-b",
"ReferenceCustomer": "123456",
"TypeFeature": "OnOff",
"IsIncluded": false,
"IsEnabled": false,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
"IdSegment": 3,
"IdFeature": 50,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "text-messages",
"ReferenceCustomer": "123456",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 57,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
]
}
Retrieve Usages of all Features available for a Customer using your own ReferenceCustomer that you or site/service provided to ProAbono.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | Yes | Reference of the Customer (ReferenceCustomer property) | String |
IdSubscription | No | Id of the Subscription to retrieve only usages from this subscription | String |
Returns
- HTTP 200 and Response body contains a list of features available for the desired Customer with theirs usages (quantities). See Usages
- HTTP 204 No Content which means that no Feature is used in your application.
- In any other cases, response body contains a single error describing the problem.
Example
Let’s say your application is a CRM platform (Customer RelationShip Management).
The Customer 123456 subscribed to an Offer which contains 4 Features :
- “Active Users” (ReferenceFeature: users)
- “Module A” (ReferenceFeature: module-a)
- “Module B” (ReferenceFeature: module-b)
- “Text Messages Sent” (ReferenceFeature: text-messages)
According the Response, your Customer 123456 subscribed to an Offer at 39 $ per month which:
- can access to Module A ,
- can NOT currently access to Module B,
- allows 4 active users to connect to your site/service/application
(but 3 are included in the subscription, the 4th is extra-paid), - already consumes 57 of “Text Messages” resource
Retrieve Usages for a Feature
Definition
GET /v1/Usages?ReferenceFeature={ReferenceFeature}
Example Request
GET https://api-2.proabono.com/v1/Usages?ReferenceFeature=users
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 2,
"TotalItems": 2,
"DateGenerated": "2016-03-29T22:02:45.63Z",
"Items": [
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 17,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77723,
"IdSubscription": 10739,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "abcdef",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10,
"DatePeriodStart": "2016-03-29T22:02:38.00Z",
"DatePeriodEnd": "2016-04-29T22:02:38.00Z"
}
]
}
Retrieve all Usages related to a specific Feature.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceFeature | Yes | Reference of the Feature (ReferenceFeature property) | String |
Returns
- HTTP 200 and Response body contains a list of Usages for the desired Feature. See Usages
- HTTP 204 No Content which means that the Feature is not used for the moment in your application.
- In any other cases, response body contains a single error describing the problem.
Retrieve a Single Usage
Definition
GET /v1/Usage?ReferenceFeature={ReferenceFeature}&ReferenceCustomer={ReferenceCustomer}
Example Request 1
GET https://api-2.proabono.com/v1/Usage?ReferenceFeature=users&ReferenceCustomer=123456
Example Response 1
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 17,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Example Request 2
GET https://api-2.proabono.com/v1/Usage?ReferenceFeature=module-a&ReferenceCustomer=123456
Example Response 2
{
"IdSegment": 3,
"IdFeature": 47,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "module-a",
"ReferenceCustomer": "123456",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Retrieve the Usage of 1 specific Feature for a Customer using your own ReferenceFeature AND your ReferenceCustomer that your site/service provided to ProAbono.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceCustomer | Yes | Reference of the Customer (ReferenceCustomer property) | String |
IdSubscription | No | Id of the Subscription to retrieve the usage of the feature of this subscription | Integer |
ReferenceFeature | Yes | Reference of the Feature (ReferenceFeature property) | String |
Returns
- HTTP 200 and Response body contains a compiled usage of a specific Feature for the desired Feature. See Usages
- HTTP 204 No Content which means that the feature is available for the Customer.
- In any other cases, response body contains a single error describing the problem.
Update Usage by Increment
Definition
POST /v1/Usage
Example Request
POST https://api-2.proabono.com/v1/Usage
{
"ReferenceFeature": "text-messages",
"ReferenceCustomer": "123456",
"Increment":57,
"DateStamp": "2016-03-29T19:33:50.65Z"
}
Example Response
{
"IdSegment": 3,
"IdFeature": 50,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "text-messages",
"ReferenceCustomer": "123456",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 57,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Increment the usage of a Feature. Only valid for Feature with types Limitation or Consumption.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceFeature | Yes | Reference of the Feature | String |
ReferenceCustomer | Yes, unless IdSubscription is provided | Reference of the Customer | String |
IdSubscription | No, unless ReferenceCustomer is not provided | Related subscription | Integer |
Increment | Yes | Usage Increment to apply to the Feature of the Customer | Integer |
DateStamp | Yes | Date Stamp of this modification | DateTime |
Returns
- HTTP 200 in case of a success. Response body contains the Usage resource with the modification.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Note : A feature of type consumption sees its QuantityCurrent attribute reset at each subscription renewal.
Update Usage by Current Quantity
Definition
POST /v1/Usage
Example Request
POST https://api-2.proabono.com/v1/Usage
{
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"QuantityCurrent":17,
"DateStamp": "2016-03-29T19:35:51.65Z"
}
Example Response
{
"IdSegment": 3,
"IdFeature": 48,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 17,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Set the new current quantity of a Feature. Only valid for Feature with type Limitation.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceFeature | Yes | Reference of the Feature | String |
ReferenceCustomer | Yes, unless IdSubscription is provided | Reference of the Customer | String |
IdSubscription | No, unless ReferenceCustomer is not provided | Related subscription | Integer |
QuantityCurrent | Yes | New Current Quantity Usage to set to the Feature of the Customer | Integer |
DateStamp | Yes | Date Stamp of this modification | DateTime |
Returns
- HTTP 200 in case of a success. Response body contains the Usage resource with the modification.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Update Usage OnOff feature
Definition
POST /v1/Usage
Example Request
POST https://api-2.proabono.com/v1/Usage
{
"ReferenceFeature": "module-b",
"ReferenceCustomer": "123456",
"IsEnabled" : true,
"DateStamp": "2016-03-29T18:33:50.67Z"
}
Example Response
{
"IdSegment": 3,
"IdFeature": 49,
"IdCustomer": 77722,
"IdSubscription": 10738,
"ReferenceSegment": "sandbox-eur",
"ReferenceFeature": "module-b",
"ReferenceCustomer": "123456",
"TypeFeature": "OnOff",
"IsIncluded": false,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Enable or Disable a Feature for a Customer Only valid for Feature with type OnOff.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceFeature | Yes | Reference of the Feature | String |
ReferenceCustomer | Yes, unless IdSubscription is provided | Reference of the Customer | String |
IdSubscription | No, unless ReferenceCustomer is not provided | Related subscription | Integer |
IsEnabled | Yes | If Yes, the Feature will be enabled to the Customer | Integer |
DateStamp | Yes | Date Stamp of this modification | DateTime |
Returns
- HTTP 200 in case of a success. Response body contains the Usage resource with the modification.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
API - Offers
Offer describes what AND how you want to sell.
All your visible offers are displayed at :
https://{your-domain}.proabono.com/
(Note : You can modify the CSS Style Sheet from the ProAbono’s backoffice : Hosted Pages -> Design)
Offer Resource
Definition
{
"Id": 35,
"ReferenceOffer": "premium-offer",
"IsVisible": true,
"TitleLocalized": "Premium",
"PricingLocalized": "190.00 Euro/mois ",
"Currency": "EUR",
"AmountRecurrence": 19000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [...],
"Links": [...]
}
Property | Description | Type |
---|---|---|
Id | Id of the Offer Object | Integer |
Name | Name of the Offer | String |
ReferenceOffer | Identifier used within your own application for this offer. Unique for a given segment, meaning you can decline the same offer in multiple segments. | String |
IsVisible | Visibility of the offer in the hosted pages | Boolean |
AmountUpFront | Amount of the Upfront fee, Setup fee or Initial fee of your offer in cents | Integer |
AmountTrial | Amount of the Trial period in cents | Integer |
DurationTrial | Number of Trial Time Unit | Integer |
UnitTrial | Time Unit of Trial | TimeUnit |
AmountRecurrence | Amount of each recurrence in cents | Integer |
DurationRecurrence | Number of Recurrence Time Unit | Integer |
UnitRecurrence | Time Unit of Recurrence | TimeUnit |
CountRecurrences | Number of Recurrences | Integer |
CountMinRecurrences | Minimum recurrences the customer will be committed to pay | Integer |
AmountTermination | Amount of the Termination Fee in cents | Integer |
StateLife | State of the Offer | StateLifeCycle |
Features | Collection of Features with Quantities and Properties | Offer Nested Features (see below) OfferFeature |
Links | Useful links concerning the Offer | See below. |
Note : Amounts are set without currency because currency is set at the Segment Level.
Collection of Links
Rel | Description |
---|---|
hosted-subscribe | Link to the page where the Customer will be redirect. |
OfferFeature Resource
1 - For OnOff Feature Type
Property | Description | Type |
---|---|---|
Id | Id of the Feature included in the Offer | Integer |
ReferenceFeature | Reference of the Feature included in the Offer | String |
IsIncluded | If True, the Feature is included in the Offer. | Integer |
IsEnabled | If True, the Feature will be enabled/available when the Customer will subscribe to the Offer. | Integer |
2 - For Limitation and Consumption Feature Type
Property | Description | Type |
---|---|---|
Id | Id of the Feature included in the Offer | Integer |
ReferenceFeature | Reference of the Feature included in the Offer | String |
QuantityIncluded | Limitation/Quota/NumberOfUnit of the Feature included in the Offer. If QuantityIncluded attribute is not provided, it means ‘unlimited’. |
Integer |
QuantityCurrent | Limitation/Quota/NumberOfUnit of the Feature, the Customer will start when subscribing to the Offer. If QuantityCurrent attribute is not provided, it means 'unlimited’. |
Integer |
Retrieve Offers
Definition
GET /v1/Offers
Example Request
GET https://api-2.proabono.com/v1/Offers?language=en
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 2,
"TotalItems": 2,
"DateGenerated": "2016-03-30T12:13:36.43Z",
"Items": [
{
"Id": 35,
"ReferenceOffer": "premium-offer",
"IsVisible": true,
"TitleLocalized": "Premium",
"PricingLocalized": "Euro 190.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 19000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
"TitleLocalized": "Active Users",
"PricingLocalized": "+Euro 7.00/extra unit",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 3
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
"TitleLocalized": "Module B",
"PricingLocalized": "optional +Euro 10.00",
"TypeFeature": "OnOff",
"IsIncluded": false,
"IsEnabled": false
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"PricingLocalized": "from Euro 0.20/extra unit",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 0
}
],
"Links": [
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/subscribe?refo=premium-offer&refs=sandbox-eur"
}
]
},
{
"Id": 147,
"ReferenceOffer": "premium-pro-plus-offer",
"IsVisible": true,
"TitleLocalized": "Premium Pro+",
"PricingLocalized": "Euro 250.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
"TitleLocalized": "Active Users",
"PricingLocalized": "from Euro 3.00/extra unit",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"PricingLocalized": "from Euro 0.01/extra unit",
"TypeFeature": "Consumption",
"QuantityIncluded": 100,
"QuantityCurrent": 0
}
],
"Links": [
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/subscribe?refo=premium-pro-plus-offer&refs=sandbox-eur"
}
]
}
]
}
It helps you to set up dynamically your pricing table or pricing page in every langages you want.
Optional Querystring Parameters
Parameter | Description | Type |
---|---|---|
ReferenceSegment | Reference of the segment where your offers are declared. | String |
IsVisible | Ignored by default. If true, only visible offers & features will be retrieved. If false, only not visible offers will be retrieved. | Boolean |
IgnoreFeatures | False by default. If True, Features will NOT be provided in the response. | Boolean |
Language | By default, ProAbono uses the language of your segment. | Langage |
Html | True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. | Boolean |
Links | True by default. If false, Links will NOT be provided in the response. | Boolean |
Page | Indicate the page returned by ProAbono to a request See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
You can combine these parameters to get exactly what you are looking for.
Example:
GET https://api-2.proabono.com/v1/Offers?SizePage=20&html=false&IgnoreFeatures=true&language=en
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
Retrieve Offers for a Customer
Definition
GET /v1/Offers?ReferenceCustomer={ReferenceCustomer}
Example Request
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 2,
"TotalItems": 2,
"DateGenerated": "2016-03-30T12:44:07.26Z",
"Items": [
{
"Id": 35,
"ReferenceOffer": "premium-offer",
"IsVisible": true,
"TitleLocalized": "Premium",
"PricingLocalized": "Euro 190.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 19000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
"TitleLocalized": "Active Users",
"PricingLocalized": "+Euro 7.00/extra unit",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 3
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
"TitleLocalized": "Module B",
"PricingLocalized": "optional +Euro 10.00",
"TypeFeature": "OnOff",
"IsIncluded": false,
"IsEnabled": false
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"PricingLocalized": "from Euro 0.20/extra unit",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 0
},
{
"Id": 243,
"ReferenceFeature": "agent",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription",
"TitleLocalized": "Agents",
"PricingLocalized": "from Euro 6.00/extra unit",
"TypeFeature": "Limitation",
"QuantityIncluded": 2,
"QuantityCurrent": 2
}
],
"Links": [
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/subscribe-offer/{Unique-encrypted-url}"
}
]
},
{
"Id": 147,
"ReferenceOffer": "premium-pro-plus-offer",
"IsVisible": true,
"TitleLocalized": "Premium Pro+",
"PricingLocalized": "Euro 250.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"Properties": "UpdatableBeforeSubscription, UpdatableAfterSubscription, FreeInTrial",
"TitleLocalized": "Active Users",
"PricingLocalized": "from Euro 3.00/extra unit",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"PricingLocalized": "from Euro 0.01/extra unit",
"TypeFeature": "Consumption",
"QuantityIncluded": 100,
"QuantityCurrent": 0
},
{
"Id": 243,
"ReferenceFeature": "agent",
"IsVisible": true,
"TitleLocalized": "Agents",
"TypeFeature": "Limitation"
}
],
"Links": [
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/subscribe-offer/{Another-Unique-encrypted-url}"
}
]
}
]
}
It helps you to set up dynamically the pricing table or pricing page for a Customer.
Retrieve a list of Offers and Features for a Customer by using your ReferenceCustomer that your site/service provided to ProAbono,
Mandatory Querystring Parameters
Parameter | Description | Type |
---|---|---|
ReferenceCustomer | With the Reference of the customer, offers retrieved will be in language of the customer and links will be encrypted links dedicated to the customer. | String |
Optional Querystring Parameters
Parameter | Description | Type |
---|---|---|
Html | True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. | Boolean |
IsVisible | Ignored by default. If true, only visible offers & features will be retrieved. If false, only not visible offers will be retrieved. | Boolean |
IgnoreFeatures | False by default. If True, Features will NOT be provided in the response. | Boolean |
Links | True by default. If false, Links will NOT be provided in the response. | Boolean |
Page | Indicate the page returned by ProAbono to a request See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
You can combine these parameters to get exactly what you are looking for.
Example:
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&SizePage=20&html=false&IgnoreFeatures=true
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
Retrieve Offers to upgrade a Customer
2 Definitions availables
Definition 1:
Ideal if you Customer has only one running subscription. ProAbono will be find the subscription and retrieve the offers with the upgrade links.
GET /v1/Offers?ReferenceCustomer={ReferenceCustomer}&Upgrade=true
Definition 2:
If your customer has more than 1 running subscription, ProAbono need the id of subscription to upgrade
GET /v1/Offers?IdSubscription={IdSubscription}
Example Request
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&Upgrade=true
GET https://api-2.proabono.com/v1/Offers?IdSubscription=10725
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 2,
"TotalItems": 2,
"DateGenerated": "2016-03-30T13:09:08.72Z",
"Items": [
{
"Id": 147,
"ReferenceOffer": "premium-pro-plus-offer",
"IsVisible": true,
"TitleLocalized": "Premium Pro+",
"PricingLocalized": "Euro 250.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Links": [
{
"rel": "hosted-upgrade",
"href": "https://sandbox-eur.proabono.com/upgrade-to-offer/{An-Unique-encrypted-url}"
}
]
},
{
"Id": 35,
"ReferenceOffer": "premium-offer",
"IsVisible": true,
"TitleLocalized": "Premium",
"PricingLocalized": "Euro 190.00/month(s) ",
"Currency": "EUR",
"AmountRecurrence": 19000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Links": [
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/overview-subscription/{Another-Unique-encrypted-url}"
}
]
}
]
}
It helps you to set up dynamically the pricing table or pricing page for a Customer who wants to upgrade.
Retrieve a list of Offers and Features for a Customer by using your ReferenceCustomer that your site/service provided to ProAbono,
Mandatory Querystring Parameters
Definition 1
Parameter | Description | Type |
---|---|---|
ReferenceCustomer | With the Reference of the customer, offers retrieved will be in language of the customer and links will be encrypted links dedicated to the customer. | String |
Upgrade | If true, the link with each offer will redirect the Customer the upgrade workflow. | Boolean |
Definition 2
Parameter | Description | Type |
---|---|---|
IdSubscription | Id of the Subscription to upgrade | Integer |
Optional Querystring Parameters
Parameter | Description | Type |
---|---|---|
Html | True by default. If false, TitleLocalized and PricingLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. | Boolean |
IsVisible | Ignored by default. If true, only visible offers will be retrieved. If false, only not visible offers will be retrieved. | Boolean |
IgnoreFeatures | False by default. If True, Features will NOT be provided in the response. | Boolean |
Links | True by default. If false, Links will NOT be provided in the response. | Boolean |
Page | Indicate the page returned by ProAbono to a request See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
You can combine these parameters to get exactly what you are looking for.
Example:
GET https://api-2.proabono.com/v1/Offers?ReferenceCustomer=123456&Upgrade=true&SizePage=20&IgnoreFeatures=true
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of success. Response body contains the requested resource.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
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 :
- what your customers can access, use/do in your site/service,
- what your customers purchased in details.
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 :
- Module A
- Module B
- Number of Users
- Text Messages Sent
- …
Features are core for your business. Features describe what you sell.
Feature Resource
Property | Description | Type |
---|---|---|
Id | Id of the Feature Object | Integer |
ReferenceFeature | The unique identifier used within your own application for this Feature | String |
TitleLocalized | Title of Feature | String |
DescriptionLocalized | Description of the Feature | String |
IsVisible | Visibility of the Feature in offers and hosted pages | Boolean |
Retrieve Features
Definition
GET /Features
Example Request
GET https://api-2.proabono.com/v1/Features?ReferenceSegment=sandbox-eur&Language=en&html=false
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 4,
"TotalItems": 4,
"DateGenerated": "2016-08-09T11:51:46.92Z",
"Items": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff"
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation"
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"TypeFeature": "OnOff"
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"TypeFeature": "Consumption"
}
]
}
Retrieve the Features in your site/service and declared in ProAbono.
Optional Querystring Parameters
Parameter | Description | Type |
---|---|---|
ReferenceSegment | Feature Title and Description can be overriden and translated differently by segment. | String |
ReferenceCustomer | Title and Description of the features available for a Customer will be in the language of the Customer. | String |
Html | True by default. If false, TitleLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. | Boolean |
Language | By default, ProAbono uses the language of your segment. | Langage |
IsVisible | Ignored by default. If true, only visible features will be retrieved. If false, only not visible features will be retrieved. | Boolean |
Page | Indicate the page returned by ProAbono to a request See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
Returns
- HTTP 200 and Response body contains a list of features available.
- HTTP 204 No Content which means that no Feature is available.
- In any other cases, response body contains a single error describing the problem.
Retrieve a Single Feature
GET /Feature?ReferenceFeature={RefFeature}
Example Request
GET https://api-2.proabono.com/Feature?ReferenceFeature=users
Example Response
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TypeFeature": "Limitation",
"TitleLocalized": "Active Users""
}
It helps you to retrieve 1 Single Feature.
Very useful to display dynamically the feature on your site pages in every langages you want.
Works like Retrieve Features,
Only the endpoint is different /v1/Feature instead of /v1/Features but same querystring parameters + the Reference of the Feature to retrieve.
Mandatory Querystring Parameters
Parameter | Description | Type |
---|---|---|
ReferenceFeature | Reference of the feature to retrieve. | String |
Optional Querystring Parameters
Parameter | Description | Type |
---|---|---|
ReferenceSegment | Feature Title and Description can be overriden and translated differently by segment. | String |
ReferenceCustomer | Title and Description of the feature will be in the language of the Customer. | String |
Html | True by default. If false, TitleLocalized will be in plain text, not html. DescriptionLocalized will NOT be provided in the response. | Boolean |
Language | By default, ProAbono uses the language of your segment. | Langage |
Returns
- HTTP 200 and Response body contains a feature.
- HTTP 204 No Content which means that no Feature is available.
- In any other cases, response body contains a single error describing the problem.
API - Subscriptions
Subscription Resource
Example Response
{
"Id": 44082,
"IdSegment": 3,
"IdOffer": 1274,
"IdCustomer": 102547,
"IdCustomerBuyer": 102547,
"ReferenceSegment": "sandbox-eur",
"ReferenceOffer": "full-premium",
"ReferenceCustomer": "123456",
"ReferenceCustomerBuyer": "123456",
"StateSubscription": "Running",
"DateStart": "2016-08-09T12:38:55.00Z",
"DatePeriodStart": "2016-08-09T12:38:55.00Z",
"DatePeriodEnd": "2016-08-23T12:38:55.00Z",
"DateTerm": "2016-08-23T12:38:55.00Z",
"StateSubscriptionAfterTerm": "Running",
"IsTrial": true,
"CountDaysTrial": 13,
"IsEngaged": true,
"IsCustomerBillable": true,
"IsPaymentCappingReached": false,
"DateNextBilling": "2017-08-30T20:36:53.00Z",
"TitleLocalized": "Full Premium",
"AmountUpFront": 59900,
"DurationTrial": 14,
"UnitTrial": "Day",
"AmountRecurrence": 9900,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"CountRecurrences": 12,
"CountMinRecurrences": 3,
"Features": [
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation",
"QuantityIncluded": 2,
"QuantityCurrent": 2
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
}
],
"DateUpdate": "2016-08-09T12:38:53.76Z",
"Links": [
{
"rel": "self",
"href": "/v1/Subscription/44082"
},
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/overview-subscription/{an-unique-encrypted-url}"
},
{
"rel": "hosted-upgrade",
"href": "https://sandbox-eur.proabono.com/upgrades/{another-unique-encrypted-url}"
}
]
}
Parameter | Description | Type |
---|---|---|
Id | Id of your Subscription | Integer |
IdSegment | of the Segment in which your customer has been created/added. | Integer |
IdOffer | Id of the Offer subscribed | Integer |
IdCustomer | Identifier of the Customer | Integer |
IdCustomerBuyer | Identifier of the Customer who buys. | Integer |
ReferenceSegment | Reference of the Segment in which your customer has been created/added. | String |
ReferenceOffer | Reference of the Offer subscribed | String |
ReferenceCustomer | The unique identifier used within your own application for this customer | String |
ReferenceCustomerBuyer | Reference of the Customer who buys. (Tips: Use your own id user) |
String |
StateSubscription | State of the Subscription | StateSubscription |
DateStart | Start Date of the Subscription | DateTime |
DatePeriodStart | Start Date of the billing period | DateTime |
DatePeriodEnd | End Date of the billing period | DateTime |
DateTerm | Term Date of the Subscription | DateTime |
StateSubscriptionAfterTerm | Estimated State of the Subscription after the current period | StateSubscription |
IsTrial | Indicates if the current period is a trial period or not | Boolean |
CountDaysTrial | Number of days remaining in the trial period | Integer |
IsEngaged | Indicates if the Customer is still in the minimum commitment period | Boolean |
IsCustomerBillable | Indicates if the Customer is currently billable. | Boolean |
IsPaymentCappingReached | Indicates if the Customer has exceeded the max duration limit of due payments and/or the max limit of accumulated amount of due payments. | Boolean |
DateNextBilling | Date of the Customer Next Billing | DateTime |
TitleLocalized | Title of the Subscription in the language of the Customer | String |
AmountUpFront | Amount of the Upfront fee, Setup fee or Initial fee of your offer in cents | Integer |
AmountTrial | Amount of the Trial period in cents | Integer |
DurationTrial | Number of Trial Time Unit | Integer |
UnitTrial | Time Unit of Trial | TimeUnit |
AmountRecurrence | Amount of each recurrence in cents | Integer |
DurationRecurrence | Number of Recurrence Time Unit | Integer |
UnitRecurrence | Time Unit of Recurrence | TimeUnit |
CountRecurrences | Number of Recurrences | Integer |
CountMinRecurrences | Minimum recurrences the customer will be committed to pay | Integer |
AmountTermination | Amount of the Termination Fee in cents | Integer |
Features | Collection of Features + theirs usages (Can be empty if the Offer contained no feature when it was subscribed | See below. |
DateUpdate | Date of the last update of the Subscription | Integer |
Metadata | A set of key/value pairs that you can add to a subscription | Metadata |
Links | Collection of Links. The Links in the collection depends on the Subscription State. | See below. |
Collection of links for a Subscription in InitiatedAgent State
Rel | Description |
---|---|
hosted-related-subscription | Unique encrypted link to the detailed page of the subscription for the concerned Customer. |
hosted-subscribe | Unique encrypted link to conclude and pay the Subscription for the concerned Customer. |
hosted-register | Unique encrypted link for the concerned Customer to directly type/update his/her payment information. |
Collection of links for a Subscription in Running State
Rel | Description |
---|---|
hosted-related-subscription | Unique encrypted link to the detailed page of the subscription for the concerned Customer. From this page, the Customer can type/update his/her payment information. |
hosted-upgrade | Unique encrypted link to redirect the the Subscription for the concerned Customer. |
SubscriptionFeature Resource
Property | Description | Type |
---|---|---|
Id | Id of the Feature | Integer |
ReferenceFeature | Reference of the Feature | String |
IsVisible | Visibility of the Feature in hosted pages | Boolean |
TitleLocalized | Title of the Feature in the language of the Customer | String |
DescriptionLocalized | Description of the Feature in the language of the Customer | String |
TypeFeature | Type of the Feature (OnOff, Limitation, Consumption) | FeatureType |
IsIncluded | (Only for OnOff feature) It indicates if the feature is included in the subscription of the customer. False indicates that the feature can be enabled. | Boolean |
IsEnabled | (Only for OnOff feature) It indicates if the feature is enabled in the subscription of the customer. | Boolean |
QuantityIncluded | (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature available in the Subscription of the Customer. If not provided it means ‘unlimited’. | Integer |
QuantityCurrent | (Only for Limitation or Consumption feature) Limitation, quota or volume of the Feature currently used in the Subscription of the Customer. If not provided it means ‘unlimited’. | Integer |
Create a Subscription
Definition
POST /v1/Subscription
Example Request
POST https://api-2.proabono.com/v1/Subscription
{
"ReferenceCustomer": "1234567890",
"ReferenceOffer": "premium-pro-plus-offer",
"Metadata":
{
"Site": "www.johndoe.com",
"AccountingReference":"456-xyz",
"IdPartner": 3
}
}
Example Response
{
"Id": 44088,
"IdSegment": 3,
"IdOffer": 147,
"IdCustomer": 108052,
"IdCustomerBuyer": 108052,
"ReferenceSegment": "sandbox-eur",
"ReferenceOffer": "premium-pro-plus-offer",
"ReferenceCustomer": "1234567890",
"ReferenceCustomerBuyer": "1234567890",
"StateSubscription": "InitiatedAgent",
"IsCustomerBillable": false,
"IsPaymentCappingReached": false,
"TitleLocalized": "Premium Pro+",
"DurationTrial": 0,
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Metadata":
{
"Site": "www.johndoe.com",
"AccountingReference":"456-xyz",
"IdPartner": 3
},
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"TypeFeature": "Consumption",
"QuantityIncluded": 100,
"QuantityCurrent": 0
}
],
"DateUpdate": "2016-08-09T13:17:39.88Z",
"Links": [
{
"rel": "self",
"href": "/v1/Subscription/44088"
},
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/subscription/{Unique-Crypted-Url-1}"
},
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/conclude/{Unique-Crypted-Url-2}"
},
{
"rel": "hosted-register",
"href": "https://sandbox-eur.proabono.com/permission-update/{Unique-Crypted-Url-3}"
}
]
}
Customers refer to your users in your Site/Service/Application.
Each customer shares a reference called ReferenceCustomer
in order to be easily found in your database and ProAbono.
A customer can subscribe to offers.
Each subscription is a copy of the offer subscribed at the exact moment of the subscription.
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
ReferenceOffer | Yes | Reference of the offer in which the customer will be created. | String |
ReferenceCustomer | Yes | The unique identifier used within your own application for this customer. Must be previously declared/created in ProAbono. See Create a Customer |
String |
ReferenceCustomerBuyer | No | Reference of the Customer who buys. Must be previously declared/created in ProAbono. See Create a Customer |
String |
Metadata | No | A set of key/value pairs that you can add to a subscription. Useful for storing additional information about the subscription in a structured format. | Metadata |
Note : Creating a Subscription based on an offer
- without any Trial Period, ProAbono will set the StateSubscription at
InitiatedAgent
. The Customer must provide its payment info to see its Subscription running. - with a Trial Period, ProAbono will set the StateSubscription at
Running
. The Customer must type its payment info to still see its Subscription running after the end of the Trial Period.
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
- HTTP 201 in case of a success. Response body contains the created resource.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 201 in case of a success. Response body contains the created resource.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Retrieve a Subscription
Definitions
GET /v1/Subscription/{IdSubscription}
GET /v1/Subscription/?ReferenceCustomer={Ref}
Example Request
GET https://api-2.proabono.com/v1/Subscription/44088
GET https://api-2.proabono.com/v1/Subscription/?ReferenceCustomer=1234567890
Example Response
{
"Id": 44088,
"IdSegment": 3,
"IdOffer": 147,
"IdCustomer": 108052,
"IdCustomerBuyer": 108052,
"ReferenceSegment": "sandbox-eur",
"ReferenceOffer": "premium-pro-plus-offer",
"ReferenceCustomer": "1234567890",
"ReferenceCustomerBuyer": "1234567890",
"StateSubscription": "InitiatedAgent",
"IsCustomerBillable": false,
"IsPaymentCappingReached": false,
"TitleLocalized": "Premium Pro+",
"DurationTrial": 0,
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"TypeFeature": "Consumption",
"QuantityIncluded": 100,
"QuantityCurrent": 0
}
],
"DateUpdate": "2016-08-09T13:17:39.88Z",
"Links": [
{
"rel": "self",
"href": "/v1/Subscription/44088"
},
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/subscription/{Unique-Crypted-Url-1}"
},
{
"rel": "hosted-subscribe",
"href": "https://sandbox-eur.proabono.com/conclude/{Unique-Crypted-Url-2}"
},
{
"rel": "hosted-register",
"href": "https://sandbox-eur.proabono.com/permission-update/{Unique-Crypted-Url-3}"
}
]
}
Retrieve a Subscription. 2 definitions are available : - Retrieve a Subcription by IdSubscription - Retrieve a Subscription with the ReferenceCustomer
Request Parameters for Definition 1 (By IdSubscription)
Parameter | Required? | Description | Type |
---|---|---|---|
IdSubscription | yes | Id of the Subscription. | Integer |
Html | no | True by default. If false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. | Boolean |
IgnoreFeatures | no | False by default. If True, Features will NOT be provided in the response. | Boolean |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 404 if the resource is not found. Response body may contain more information.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 404 if the resource is not found. Response body may contain more information.
- HTTP 409 if the customer has more than one running subscription. If in this case, definition 1 must be used.
- In any other cases, response body contains a single error describing the problem.
Update Subscription Term Date
Definition
POST /v1/Subscription/{IdSubscription}/DateTerm
Example Request
POST https://api-2.proabono.com/v1/Subscription/{IdSubscription}/DateTerm
{
"DateTerm":"2016-12-31T23:59:59.65Z"
}
Update the Term Date of the Subscription
Request Parameters
Parameter | Required? | Description | Type |
---|---|---|---|
DateTerm | Yes | New Date of the term of the Subscription | DateTime |
Returns
- HTTP 200 in case of a success. Response body contains the desired resource.
- HTTP 403 if the Subscription is not found or unaccessible. Response body may contain more information.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
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
- HTTP 200 in case of a success.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
List Subscriptions
Definition
GET /v1/Subscriptions
Example Request
GET https://api-2.proabono.com/v1/Subscriptions?IgnoreFeatures=true&
Example Response
{
"Page": 1,
"SizePage": 10,
"Count": 2,
"TotalItems": 2,
"DateGenerated": "2016-08-09T13:40:37.10Z",
"Items": [
{
"Id": 44097,
"IdSegment": 3,
"IdOffer": 147,
"IdCustomer": 108057,
"IdCustomerBuyer": 108057,
"ReferenceSegment": "sandbox-eur",
"ReferenceOffer": "premium-pro-plus-offer",
"ReferenceCustomer": "0987654321",
"ReferenceCustomerBuyer": "0987654321",
"StateSubscription": "Running",
"DateStart": "2016-08-09T13:40:10.00Z",
"DatePeriodStart": "2016-08-09T13:40:10.00Z",
"DatePeriodEnd": "2016-09-09T13:40:10.00Z",
"DateTerm": "2016-09-09T13:40:10.00Z",
"StateSubscriptionAfterTerm": "Running",
"IsTrial": false,
"IsEngaged": false,
"IsCustomerBillable": true,
"IsPaymentCappingReached": false,
"DateNextBilling": "2016-09-09T19:40:10.00Z",
"TitleLocalized": "Premium Pro+",
"DurationTrial": 0,
"AmountRecurrence": 25000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation",
"QuantityIncluded": 10,
"QuantityCurrent": 10
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"TypeFeature": "Consumption",
"QuantityIncluded": 100,
"QuantityCurrent": 120
}
],
"DateUpdate": "2016-08-09T13:40:10.88Z",
"Links": [
{
"rel": "self",
"href": "/v1/Subscription/44097"
},
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/overview-subscription/{Unique-Crypted-Url-1}"
},
{
"rel": "hosted-upgrade",
"href": "https://sandbox-eur.proabono.com/upgrades/{Unique-Crypted-Url-2}"
}
]
},
{
"Id": 44096,
"IdSegment": 3,
"IdOffer": 35,
"IdCustomer": 108056,
"IdCustomerBuyer": 108056,
"ReferenceSegment": "sandbox-eur",
"ReferenceOffer": "premium-offer",
"ReferenceCustomer": "abcdef",
"ReferenceCustomerBuyer": "abcdef",
"StateSubscription": "TerminatedAtRenewal",
"DateStart": "2016-08-03T13:38:41.00Z",
"DatePeriodStart": "2016-08-03T13:38:41.00Z",
"DatePeriodEnd": "2016-09-03T13:38:41.00Z",
"DateTerm": "2016-09-03T13:38:41.00Z",
"StateSubscriptionAfterTerm": "Terminated",
"IsTrial": false,
"IsEngaged": false,
"IsCustomerBillable": true,
"IsPaymentCappingReached": false,
"DateNextBilling": "2016-09-09T19:38:41.00Z",
"TitleLocalized": "Premium",
"DurationTrial": 0,
"AmountRecurrence": 21000,
"DurationRecurrence": 1,
"UnitRecurrence": "Month",
"Features": [
{
"Id": 47,
"ReferenceFeature": "module-a",
"IsVisible": true,
"TitleLocalized": "Module A",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true
},
{
"Id": 48,
"ReferenceFeature": "users",
"IsVisible": true,
"TitleLocalized": "Active Users",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 3
},
{
"Id": 49,
"ReferenceFeature": "module-b",
"IsVisible": true,
"TitleLocalized": "Module B",
"DescriptionLocalized": "This module is awesome. It revolutionizes your life.",
"TypeFeature": "OnOff",
"IsIncluded": false,
"IsEnabled": true
},
{
"Id": 50,
"ReferenceFeature": "text-messages",
"IsVisible": true,
"TitleLocalized": "Text Messages Sent",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 76
}
],
"DateUpdate": "2016-08-09T13:38:52.08Z",
"Links": [
{
"rel": "self",
"href": "/v1/Subscription/44096"
},
{
"rel": "hosted-related-subscription",
"href": "https://sandbox-eur.proabono.com/overview-subscription/{Unique-Crypted-Url-3}"
}
]
}
],
"Links": [
{
"rel": "next",
"href": "/v1/Subscriptions?Page=2"
}
]
}
Retrieve all Subscriptions
Optional Querystring Parameters
Parameters | Description | Type |
---|---|---|
ReferenceSegment | List all subscriptions created in a specific Segment | String |
ReferenceCustomer | List all subscriptions of a specific Customer | String |
ReferenceCustomerBuyer | List all subscriptions of a specific CustomerBuyer | String |
Html | True by default. If false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. | Boolean |
IgnoreFeatures | False by default. If True, Features will NOT be provided in the response. | Boolean |
Page | Indicate the page returned by ProAbono to a request See Pagination. | Integer |
SizePage | Set the page size. See Pagination. | Integer |
You can combine these parameters to get exactly what you are looking for.
Example:
GET https://api-2.proabono.com/v1/Subscriptions?SizePage=20&ReferenceCustomerBuyer=1234567890
Returns
- HTTP 200 in case of success. Response body contains a Paginated list of requested resources.
- HTTP 204 if there is no result. Response body is Empty.
- In any other cases, response body contains a single error describing the problem.
API - Compute Pricing
Pricing Computing is designed to compute the exact pricing, including taxes, when you want your customer to know exactly how much he or she will be charged.
It’s strongly recommended to avoid performing pricing calculations directly in yours application, as ProAbono is the referential for pricing and billing information.
Pricing for a Subscription Creation
Definition
POST /v1/Pricing/Subscription
Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription
{
"ReferenceOffer": "premium-offer",
"ReferenceCustomer": "123456"
}
Example Response
{
"AmountTotalDue": 26775,
"PricingLocalized": "€ 267.75",
"DatePeriodStart": "2016-08-10T06:21:47.71Z",
"DatePeriodTerm": "2016-09-10T06:21:47.71Z",
"AmountSubtotal": 21000,
"AmountTotal": 26775,
"Details": [
{
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 26775,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-08-10T06:21:47.71Z",
"DatePeriodTerm": "2016-09-10T06:21:47.71Z",
"AmountSubtotal": 21000,
"AmountTotal": 26775
}
]
}
Compute the pricing of a Subcription creation.
Request Parameters
Same as Create a Subscription.
QueryString Parameters
Same as Create a Subscription.
Returns
- HTTP 200 in case of a success. Response body contains the details of the computed pricing.
- HTTP 403 with message “Error.Customer.PaymentSettings.Missing” if the Customer has no valid payment information.
- HTTP 403 with message “Error.Customer.Billing.CappingReached” if the Customer has reached the billing limits.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Pricing for a Subscription Override
Definition
POST /v1/Pricing/Subscription
Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription
{
"ReferenceOffer": "premium-offer",
"AmountUpFront" : 19900,
"ReferenceCustomer": "123456"
}
Example Response
{
"AmountTotalDue": 52147,
"PricingLocalized": "€ 521.47",
"DatePeriodStart": "2016-08-10T06:56:24.42Z",
"DatePeriodTerm": "2016-09-10T06:56:24.42Z",
"AmountSubtotal": 40900,
"AmountTotal": 52147,
"Details": [
{
"LabelLocalized": "Up-front amount",
"AmountTotalDue": 25372,
"TypeMove": "SubscriptionUpFront",
"DateMove": "2016-08-10T06:56:24.42Z",
"AmountSubtotal": 19900,
"AmountTotal": 25372
},
{
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 26775,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-08-10T06:56:24.42Z",
"DatePeriodTerm": "2016-09-10T06:56:24.42Z",
"AmountSubtotal": 21000,
"AmountTotal": 26775
}
]
}
Compute the pricing of a overriden subcription creation.
Request Parameters
Same as Override a Subscription.
QueryString Parameters
Same as Override a Subscription.
Returns
- HTTP 200 in case of a success. Response body contains the details of the computed pricing.
- HTTP 403 with message “Error.Customer.PaymentSettings.Missing” if the Customer has no valid payment information.
- HTTP 403 with message “Error.Customer.Billing.CappingReached” if the Customer has reached the billing limits.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Pricing for a Subscription Start
Definition
POST /v1/Pricing/Subscription/{IdSubscription}/Start
Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription/45678/Start?Html=false
Example Response
{
"IdSubscription": 44179,
"AmountTotalDue": 31875,
"PricingLocalized": "€ 318.75",
"DatePeriodStart": "2016-08-10T07:41:57.83Z",
"DatePeriodTerm": "2016-09-10T07:41:57.83Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875,
"Details": [
{
"IdSubscription": 44179,
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 31875,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-08-10T07:41:57.83Z",
"DatePeriodTerm": "2016-09-10T07:41:57.83Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875
}
],
"NextTerm": {
"IdSubscription": 44179,
"AmountTotalDue": 31875,
"PricingLocalized": "€ 318.75",
"DatePeriodStart": "2016-09-10T07:41:57.83Z",
"DatePeriodTerm": "2016-10-10T07:41:57.83Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875,
"Details": [
{
"IdSubscription": 44179,
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 31875,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-09-10T07:41:57.83Z",
"DatePeriodTerm": "2016-10-10T07:41:57.83Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875
}
]
}
}
Compute the pricing for a (re)start of a subcription.
Request Parameters
Same as Start a Subscription.
QueryString Parameters
Same as Start a Subscription.
Returns
- HTTP 200 in case of a success. Response body contains the details of the computed pricing.
- HTTP 403 with message “Error.Customer.PaymentSettings.Missing” if the Customer has no valid payment information.
- HTTP 403 with message “Error.Customer.Billing.CappingReached” if the Customer has reached the billing limits.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Pricing for a Subscription Upgrade
Definition
POST /v1/Pricing/Subscription/{IdSubscription}/Upgrade?ReferenceOffer={RefOffer}
Example Request
POST https://api-2.proabono.com/v1/Pricing/Subscription/45678/Upgrade?ReferenceOffer=premium-pro-plus-offer&html=false
Example Response
{
"IdSubscription": 44081,
"AmountTotalDue": 4971,
"PricingLocalized": "49.71 €",
"DatePeriodStart": "2016-08-10T07:32:13.76Z",
"DatePeriodTerm": "2016-09-09T12:33:32.00Z",
"AmountSubtotal": 3898,
"AmountTotal": 4971,
"Details": [
{
"IdSubscription": 44081,
"LabelLocalized": "Subscription - refund on recurring flat fee",
"AmountTotalDue": -26089,
"TypeMove": "SubscriptionRecurrenceRefund",
"DatePeriodStart": "2016-08-10T07:32:13.76Z",
"DatePeriodTerm": "2016-09-09T12:33:30.48Z",
"AmountSubtotal": -20463,
"AmountTotal": -26089
},
{
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 31060,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-08-10T07:32:13.76Z",
"DatePeriodTerm": "2016-09-09T12:33:32.00Z",
"AmountSubtotal": 24361,
"AmountTotal": 31060
}
],
"NextTerm": {
"AmountTotalDue": 31875,
"PricingLocalized": "318.75 €",
"DatePeriodStart": "2016-09-09T12:33:32.00Z",
"DatePeriodTerm": "2016-10-09T12:33:32.00Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875,
"Details": [
{
"LabelLocalized": "Subscription amount",
"AmountTotalDue": 31875,
"TypeMove": "SubscriptionRecurrence",
"DatePeriodStart": "2016-09-09T12:33:32.00Z",
"DatePeriodTerm": "2016-10-09T12:33:32.00Z",
"AmountSubtotal": 25000,
"AmountTotal": 31875
}
]
}
}
Compute the pricing for an upgrade of a subcription.
Request Parameters
Same as Upgrade a Subscription.
QueryString Parameters
Same as Upgrade a Subscription.
Returns
- HTTP 200 in case of a success. Response body contains the details of the computed pricing.
- HTTP 403 with message “Error.Customer.PaymentSettings.Missing” if the Customer has no valid payment information.
- HTTP 403 with message “Error.Customer.Billing.CappingReached” if the Customer has reached the billing limits.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.
Pricing for an Usage Update
Definition
POST /v1/Pricing/Usage
Example Request 1
POST https://api-2.proabono.com/v1/Pricing/Usage
{
"ReferenceFeature": "module-b",
"ReferenceCustomer": "123456",
"IsEnabled":true,
"DateStamp": "2016-08-09T12:13:50.65Z"
}
Example Request 2
POST https://api-2.proabono.com/v1/Pricing/Usage
{
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"QuantityCurrent":6,
"DateStamp": "2016-08-09T12:13:50.65Z"
}
Example Request 3
POST https://api-2.proabono.com/v1/Pricing/Usage?html=false
{
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"Increment":4,
"DateStamp": "2016-08-09T12:13:50.65Z"
}
Example Response 3
{
"IdSubscription": 44082,
"IdFeature": 48,
"AmountTotalDue": 5038,
"PricingLocalized": "€ 50.38",
"DatePeriodStart": "2016-08-09T15:58:20.73Z",
"DatePeriodTerm": "2016-08-23T12:38:55.00Z",
"AmountSubtotal": 3952,
"AmountTotal": 5038,
"Details": [
{
"IdSubscription": 44082,
"IdFeature": 48,
"LabelLocalized": "Feature - prorated adjustment - Active Users",
"AmountTotalDue": 5038,
"TypeMove": "AutoFeatureProrata",
"DatePeriodStart": "2016-08-09T15:58:20.73Z",
"DatePeriodTerm": "2016-08-23T12:38:55.00Z",
"QuantityReported": 6,
"QuantityBilled": 4,
"AmountSubtotal": 3952,
"AmountTotal": 5038
}
]
}
Example Request 4
POST https://api-2.proabono.com/v1/Pricing/Usage?NextTerm=true
{
"ReferenceFeature": "users",
"ReferenceCustomer": "123456",
"Increment":4,
"DateStamp": "2016-08-09T12:13:50.65Z"
}
Example Response 4
{
"IdSubscription": 44082,
"IdFeature": 48,
"AmountTotalDue": 5038,
"PricingLocalized": "€ 50.38",
"DatePeriodStart": "2016-08-09T15:58:20.73Z",
"DatePeriodTerm": "2016-08-23T12:38:55.00Z",
"AmountSubtotal": 3952,
"AmountTotal": 5038,
"Details": [
{
"IdSubscription": 44082,
"IdFeature": 48,
"LabelLocalized": "Feature - prorated adjustment - Active Users",
"AmountTotalDue": 5038,
"TypeMove": "AutoFeatureProrata",
"DatePeriodStart": "2016-08-09T15:58:20.73Z",
"DatePeriodTerm": "2016-08-23T12:38:55.00Z",
"QuantityReported": 6,
"QuantityBilled": 4,
"AmountSubtotal": 3952,
"AmountTotal": 5038
}
],
"NextTerm": {
"IdSubscription": 44082,
"LabelLocalized": "Subscription cost after modification",
"PricingLocalized": "€ 191.22",
"DatePeriodStart": "2016-08-23T12:38:55.00Z",
"DatePeriodTerm": "2016-09-23T12:38:55.00Z",
"AmountSubtotal": 15000,
"AmountTotal": 19122,
"Details": [
{
"IdSubscription": 44082,
"LabelLocalized": "Flat fee",
"AmountTotalDue": 6374,
"TypeMove": "AutoFSubscriptionRecurrence",
"DatePeriodStart": "2016-08-23T12:38:55.00Z",
"DatePeriodTerm": "2016-09-23T12:38:55.00Z",
"AmountSubtotal": 5000,
"AmountTotal": 6374
},
{
"IdSubscription": 44082,
"IdFeature": 48,
"LabelLocalized": "Feature - Active Users",
"AmountTotalDue": 12748,
"TypeMove": "AutoFeatureProratable",
"DatePeriodStart": "2016-08-23T12:38:55.00Z",
"DatePeriodTerm": "2016-09-23T12:38:55.00Z",
"QuantityReported": 6,
"QuantityBilled": 4,
"AmountSubtotal": 10000,
"AmountTotal": 12748
}
]
}
}
Compute the pricing for an Usage Update by Increment, by QuantityCurrent and for OnOff feature.
Request Parameters for Usage Update for OnOff feature
Parameter | Description | Type |
---|---|---|
ReferenceFeature | Reference of the Feature | String |
ReferenceCustomer | Reference of the Customer | String |
IdSubscription | Id of the Subscription to use if the Customer has multiple running subscriptions | Integer |
IsEnabled | New State of the Feature for the Customer | Boolean |
DateStamp | Date Stamp of this potential modification | DateTime |
Request Parameters for Usage Update by QuantityCurrent (For Features with Type Limitation Only)
Parameter | Description | Type |
---|---|---|
ReferenceFeature | Reference of the Feature | String |
ReferenceCustomer | Reference of the Customer | String |
IdSubscription | Id of the Subscription to use if the Customer has multiple running subscriptions | Integer |
QuantityCurrent | New Current Quantity of the Feature for the Customer | Integer |
DateStamp | Date Stamp of this potential modification | DateTime |
Request Parameters for Usage Update by Increment (For Features with Type Consumption or Limitation)
Parameter | Description | Type |
---|---|---|
ReferenceFeature | Reference of the Feature | String |
ReferenceCustomer | Reference of the Customer | String |
IdSubscription | Id of the Subscription to use if the Customer has multiple running subscriptions | Integer |
Increment | New Increment of the Feature for the Customer | Integer |
DateStamp | Date Stamp of this potential modification | DateTime |
Optional QueryString Parameters
Parameter | Description | Type |
---|---|---|
EnsureBillable | ?ensureBillable=true forces the verification of the payment information, even if the Offer is free. If the customer has not registered any payment information, the 403 forbidden error is returned. | Boolean |
Html | If ?Html=false, TitleLocalized of the features will be in plain text, not html. DescriptionLocalized of the Features will NOT be provided in the response. | Boolean |
NextTerm | ?NextTerm=true adds in the response the estimated cost of the next term. See Example 4 on the right | Boolean |
Returns
- HTTP 200 in case of a success. Response body contains the details of the computed pricing.
- HTTP 403 with message “Error.Customer.PaymentSettings.Missing” if the Customer has no valid payment information.
- HTTP 403 with message “Error.Customer.Billing.CappingReached” if the Customer has reached the billing limits.
- HTTP 422 in case of validation errors. Response body contains a list of errors.
- In any other cases, response body contains a single error describing the problem.