Introduction
The pages help you quickly get familuar with the Upodi as a programmer.
Developer - Welcome!
We love the subscription business and thank you for taking the time to review our development hub. Please do not be shy - contact us immediately if you find questions not answered - you can always have a direct chat with us using Intercom below.
Getting started quickly (cheating)
If you are impatient and want to learn by doing - follow this cheat sheet guide:
1) Create an API key
2) Configure your desired client and set the authorization header = 'bearer base64(key)'
3) Create your first customer
4) Make your first API Call :)
5) Extend the functionality using our API.
Postman Collection
You can download our postman collection for sampling here.
In need of assistance?
Upodi support can be reached 09:00 to 16:00 GMT+1, Monday - Friday. Refer to your contract for on-call support during non-working hours.
- Github is the central for code and developers.
- StackOverflow offer community support.
- Upodi TrustCenter offers direct insight to our uptime, service maintenance and issues.
Stay up to date
Using our DeveloperNews mailing list, we inform you when news have been published. From developers, for developers. Subscribe here.
TLS 1.2 requirement
To comply with PCI DSS requirements by June 30th 2018, Upodi have moved API to strictly enforce TLS 1.2 from SSL/TLS. You will have to configure your integration with support of TLS 1.2.
All services consumed by Upodi have been verified for TLS 1.2.
What happens on 30 June 2018?
30th June 2018 was the deadline for disabling SSL/early TLS when working with PCI compliant data. As such, implementing a more secure encryption protocol – TLS 1.1 or higher (TLS v1.2 is strongly encouraged) in order to meet the PCI Data Security Standard (PCI DSS) for safeguarding payment data.
Getting started
Upodi is a customer & subscription management platform that supports 1.000+ business' and over 100.000 subscriptions' in 10 countries around the world. Many of these businesses use the Upodi API to automate and integrate their existing line of business (LOB) solutions.
The API
This is the documentation for the Upodi v2 API. Read the contents of this page carefully.
Upodi API is using HTTP methods and a RESTful endpoint structure, and uses HTTP response codes to indicate API errors. Format requests in JSON and the APIs return JSON-formatted responses. Upodi API do not support XML content negotiation.
A resource can support the following basic REST API actions (that are actually HTTP methods):
- GET for retrieving the resource
- POST for creating the resource
- PUT for modifying the resource
- DELETE for removing the resource
Upon updating data, the full object must be retrieved and returned. Our API does not provide property-by-property update. Issue a GET, provide changes then a PUT.
- PATCH is not supported (property update)
We make changes to the APIs from time to time. For more information, see API Changes.
Latest Upodi API endpoint:
Requests
To perform an API action you need to make an API request. For HTTP POST and PUT method, the Upodi API accepts application/json media type.
To ensure requests are threated as JSON, please add the ACCEPT header:
Accept: application/json; charset=utf-8
In addition, you must set the CONTENT-TYPE header for every request:
Content-type: application/json; charset=utf-8
Response
An API request, that has been sent to the API service, returns an API response. All responses from the Upodi API will be in JSON. All responses will contain a unique request identifier in the HTTP headers with name Request-Id. The format is a GUID.
Versioning
To ensure compatibility this section highlights how we version the API.
We might change the API time over time. This is to make sure we enable as much functionality as possible for our customers.
To support continuity and stability our efforts reason to allow a version of
Current version - 2
As an example, if the new release is version 7, we will support the API version 5. The version is applied on the URL in the format v{version number} of the API endpoint, as follows:
Version of API is embedded into the URL
Authentication
Upodi use a token API key to allow access to the API. You will need to create this API key in Upodi. To retrieve an API key, follow these steps:
1) Sign in with an administrative account.
2) Go to Setup > Developer > API Keys.
3) Generate a new API token. API keys are generated under two scopes - READ or WRITE or both.
4) Keep the API token safe and use it only on non-customer facing code (not in Javascript or HTML).
Be careful
As you setup an API key, be sure to select either read or write access permissions. Setting Upodi.js privileges will not enable the REST API to work. See the upodi.js section below.
Once created, add the key token encoded with Base64 as an authorization header, of the HTTP request to the API. The scheme is bearer.
Authorization: bearer {base64 encoding of the API key}
All API requests must be made over HTTPS (TLS/SSL). Calls made over plain HTTP will be rejected by our security protocol and fail. Most requests require authentication.
Information
The API header must be a base64 encoding of your API token, iso-8859-1 encoding. Keep your keys secure and do not expose them. Use www.base64encode.org to test.
Our API and webhooks are currently secured using TLS 1.0. We have a [planned transition to TLS 1.2].(http://trust.upodi.com/)
Data types
Data is formatted consuming and producing application/json media types.
The Upodi API use several different data types to extend and express data value(s). Data types will follow these policies.
Data type policies
| Data type | Description | Example |
|---|---|---|
| currencies | All currencies are handled as floats. They are formatted by US numeric standard, with two digits. | 490.281,90 |
| date & time | Date & time is always formatted to UTC timezone ("yyyy-MM-ddTHH:mm:ssZ"). | 2015-06-15T13:45:30 |
| numbers | All numbers (integers, doubles, and floats) are formatted by US numeric standard. | 3.390.281,90 |
| guid | All IDs are guid (UUID) formatted using 128 bit. Use online tool | 0f9aeed3-7c54-4cae-976a-dc35ed4f09ce |
Handling errors
Errors
Upodi use conventional HTTP response codes to indicate success or failure of an API request.
Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g. a card is declined), we return a 402 error code.
Attributes
200 - OK
Everything worked as expected.
201 - Created
Object created. ID of object can be found in body.
204 - No content
The resource have been executed.
206 - Created
The resource have been created. You may find data in the response of the newly created entity.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided and/or conducting a request with a wrong scope of the provided API key.
402 - Request Failed
The parameters were valid but the request failed.
403 - Forbidden
The current API key does not provide proper access scope (READ or WRITE).
404 - Not Found
The requested resource doesn't exist.
409 - Conflict
The request conflicts with another request (perhaps due to using the same idempotent key).
422 - Unprocessable entity
Entity is likely a duplicate or already exists. Please check body for error code. Usually a response of customer if accountnumber is duplicated.
500 - 506 (server errors)
Something went wrong on our end. (These are rare but recorded and will issue a system alert to operations ).
Throtteling
The API is limited to return 1.000 record at a time when providing list of records. To page the results, please use the following parameters.
$top
Returns only the first n the results.
$skip
Skips the first n results.
$select
Selects which properties to include in the response.
$orderby
Sorts the results.
$expand
Expands related entities inline. These are arrays of objects and object properties.
$filter
Filters the output.
Read more here. Examples here.
To page a result set, use the parameters. The following example will skip the first 10 results, and take a list of 50.
GET /customers/?$skip=10&top=50 HTTP/1.1Only list methods support paging
Example /customers/ will support paging, where-as single results like /customers/{id}/ will not.
https://api.upodi.io/v2/customers/?$select=ID,Subscriptions/ID&$expand=Subscriptions
Webhooks
Webhooks are a quick way to keep track of event.
Webhooks are used as a messaging channel, to keep line of business systems synchronized with events inside Upodi. A webhook cannot be used as a reliable state of an object or action. The webhook should be used for event notification in conjunction with the API.
Upodi sends webhooks to any public available webserver as HTTP POST. You can specify multiple endpoints in the Upodi application.
Upon an event, Upodi will trigger a webhook and try to send this notification to the endpoint(s). Timeout is set to 5 seconds. The webhook response is not captured by Upodi. It is a simple fire and forget event.
Summarized:
- Enable a public available web endpoint using HTTP (port 80) or HTTPS (port 443).
- Your endpoint must be live and capture the event within 5 seconds.
- Upodi do not catch any response code.
- Method is POST.
- "Signature" will correspond to the authenticity token, and can be used to verify the source.
Webhook body
A webhook holds various information and details. Please make a sample to monitor the response formats.
This is an example of a webhook body (customer, create event):
{
"ID" : "f07b8521-4421-4de6-96a5-178cf498cfef",
"Time" : 131516890300860922,
"Signature" : YTYxNWEzMdItZTBgg5i00YWE4LTk5tu6rh2JiZmEyODk5OGMz,
"Action" :"create",
"Issuer" : {
"Url" : "/Customer/create/0ea627de-158e-48b1-bcbb-7fe6058d191c",
"Identifier":"0ea627de-158e-48b1-bcbb-7fe6058d191c"
},
"Data" : null,
"Type" :
"Customer"
}Need to test a webhook?
Services like Webhook Site enable quick test of the webhook calls from Upodi. Setup a Webhook.site endpoint and add the URL to the Upodi webhook.
Events
The followings events are sent from Upodi, to endpoint configured under webhooks.
Customer
create
Occurs when a customer is created. Payload is id of the newly created customer.
update
Occurs when a customer is updated. Payload is id of the updated customer.
delete
Occurs when a customer is deleted. Payload is the id of the deleted customer.
Subscription
create
Occurs when a subscription is created. Payload is id of the newly created subscription.
update
Occurs when a subscription is updated. Payload is id of the updated subscription.
delete
Occurs when a subscription is deleted. Payload is the id of the deleted subscription.
cancel
Occurs when a subscription is cancelled.
activated
Occurs when a subscription is activated.
renewing
Occurs when a subscription is set to renewing state (not subject for evergreen).
renewed
Occurs when a subscription has completed a renewal event (not subject for evergreen).
ended
Occurs when a subscription has ended.
hold
Occurs when a subscription is put on hold.
expire
Occurs when a subscription has expired.
Invoice
create
Occurs when an invoice is created. Payload is id of the newly created invoice.
update
Occurs when an invoice is updated. Payload is id of the updated invoice.
delete
Occurs when an invoice is deleted. Payload is the id of the deleted invoice.
paid
Occurs when an invoice is paid.
Transaction
create
Occurs when a transaction is created. Occurs for each transaction also during dunning, each transaction may be declined, completed etc.
Tokenized cards
The payment industry is going into what is called tokenization.
Tokenization is a secure approch to solve both a) high PCI standards required to operate raw credit card data. Tokenization is a way to create a reference to a credit card provided by a payment gateway provider. Tokenization, when applied to data security, is the process of substituting a sensitive data element with a non-sensitive equivalent, referred to as a token, that has no extrinsic or exploitable meaning or value for the reader.
To determine which gateway is the best, please read the following section.
Upodi support tokenization of provides as follows
Stripe
Yes
No
QuickPay
Yes
No
ePay
Yes
No
AltaPay
No
No
PayLike.io
Yes
No
PayPal
No
No
To activate your preferred payment provider, please contact Upodi helpdesk.
AltaPay
We currently do not support tokenization via AltaPay. Stay tuned. We will update shortly. Contact us via intercom to get the private guide.
ePay
To use Upodi with ePay tokens, you must create a subscription via the ePay gateway provider, by following the various integration options.
As ePay token, we use subscription token in this example of ID 49820479.
Read how to create subscription in ePay here.
Upodi Payment
To create a payment method for Stripe token, make a POST request to /paymentmethods/:customerid/ with a body using the createpaymentmethod request object:
{
"type" : 64 /* PureTokenBased = 64 */,
"makedefault" : "true", /* will make the payment method default */
"puretoken" : {
"token" : " 49820479", /* ePay subscription ID */
"paymentgateway" : "epay"
}
}PayLike.IO
In order to setup PayLike.IO with Upodi you have to:
- Retrieve an APPKEY from the PayLike.IO account you want to use.
- Run a test payment on the same PayLike.IO account. We suggest you use the test card number 4100 0000 0000 and a valid expiration date.
- Click the successful test payment to retrieve the merchant ID from here.
- Navigate to Upodi and select Setup > Payment Providers > PayLike.IO. Provide the MerchantID and APPKEY from above to setup the payment provider.
Now the Payment Provider has been set up and you can start using Upodi with Paylike.io card tokens using the PayLike.IO SDK or API.
Read how to create a card token using PayLike.IO. See code sample here.
var paylike = Paylike('{your public key}', { style: false });
var $form = document.querySelector('form#checkout');
$form.addEventListener('submit', function( e ){
e.preventDefault();
paylike.tokenize($form, { },
function( err, r ){
if (err) {
console.log(err);
} else {
var tokenizedCard = r.card.id;
// example: 5ad5beb225735a2a38d6170e
// call upodi API with tokenizedCard...
}
});
});Upodi Payment
To create a payment method for PayLike.IO token, make a POST request to /paymentmethods/:customerid/ with a body using the createpaymentmethod request object:
{
"type" : 64 /* PureTokenBased = 64 */,
"makedefault" : "true", /* will make the payment method default */
"puretoken" : {
"token" : "5ad5beb225735a2a38d6170e", /* Paylike.IO card token */
"paymentgateway" : "paylike"
}
}Stripe
To use Stripe tokens in Upodi, you must follow the implementation guidance from Stripe to create a customer with a default payment method (credit card) attached. You can use various methods from Stripe to integrate your token method with Upodi. Please see Stripe documentation here or our GitHub sample here.
Upodi then uses the customer id by Stripe. Example using the customer ID cus_C9VhJ6qk0qkKqI. In most cases, you should create tokens client-side using Checkout, Elements, or Stripe mobile libraries, instead of using the Stripe API.
Using Stripe to get a customer token
Stripe requires that you save the card token to a customer in order to use it for a recurring charge in the future.
Once you retrieve the card token (example: tok_60OX9jRXUI6WzLI0V2SFxUjr), do not charge the token. Instead save it to a customer object:
# Create a Customer:
curl https://api.stripe.com/v1/customers \
-u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
-d email="paying.user@example.com" \
-d source=tok_60OX9jRXUI6WzLI0V2SFxUjr// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
// Token is created using Checkout or Elements!
// Get the payment token ID submitted by the form:
$token = $_POST['stripeToken'];
// Create a Customer:
$customer = \Stripe\Customer::create(array(
"email" => "paying.user@example.com",
"source" => $token,
));// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
// Token is created using Checkout or Elements!
// Get the payment token submitted by the form:
var token = model.Token; // Using ASP.NET MVC
var customers = new StripeCustomerService();
var charges = new StripeChargeService();
var customer = customers.Create(new StripeCustomerCreateOptions {
Email = "paying.user@example.com",
SourceToken = token
});Once you have created the customer, you can retrieve the customer id and send this to Upodi using our API. Further documentation is available on Stripes website.
You can see a sample page how to bulid a form for Upodi using Stripe elements here.
Provide the token to Upodi Payment
To create a payment method for Stripe token, make a POST request to /paymentmethods/:customerid/ with a body using the createpaymentmethod request object:
{
"type" : 64 /* PureTokenBased = 64 */,
"makedefault" : "true", /* will make the payment method default on the customer */
"puretoken" : {
"token" : "cus_C9VhJ6qk0qkKqI", /* Stripe customer ID */
"paymentgateway" : "stripe"
}
}QuickPay
To use Upodi with QuickPay tokens, you must create a subscription in the QuickPay gateway provider, by following the various integration options.
As QuickPay token, we use subscription token in this example of ID 101239321.
QuickPay only support one currency per token
It is important that you match currency in Upodi with a subscription currency in QuickPay, if currency is setup incorrectly QuickPay subscription will be charged in currency that is set in Upodi.
Upodi Payment
To create a payment method for QuickPay token, make a POST request to /paymentmethods/:customerid/ with a body using the createpaymentmethod request object:
{
"type" : 64 /* PureTokenBased = 64 */,
"makedefault" : "true", /* will make the payment method default */
"puretoken" : {
"token" : " 101239321", /* QuickPay subscription ID */
"paymentgateway" : "quickpay"
}
}customer object
Properties of the customer object.
|
id
guid
required
|
id of object, set by Upodi |
| parentid guid | object id if the customer has a parent customer |
| billtoparent boolean | if true, the parent customer will be the billing entity |
| collectivebilling boolean | if true, billing is conducted as collective billing. read more here |
| accountnumber string | Can be provided, otherwise will revert to a random of syntax "CU-xxxx". |
| companyname string | Company name. |
| companyvat string | VAT number of the customer. Syntax XX01234567, example DK39483902. |
|
fullname
string
required
|
Full name of the customer. |
| refkey string | Custom key, example a remote id. |
| primaryemail string | Primary email of customer. |
| currencycode string | Default currency code of customer. Must be enabled in Settings. Syntax XXX, example USD. |
| autobill boolean | When true, billing will be handled automatically. |
| paymentmethod guid | Id of default payment method. If null, the customer is set to manual. |
| homephone string | A provided phone number. |
| businessphone string | A provided phone number. |
| mobilephone string | A provided phone number. |
| addressline1 string | Address line 1. |
| addressline2 guid | Address line 1. |
| city guid | Name of the account city. |
| postalcode string | Postal- or zip code. |
| country string | Country of account. |
| county string | County of account. |
| state string | Address state, for example WA. |
| note string | Text field for custom notes. |
| defaultpaymentmethod paymentmethod | Default payment method object if expanded. |
| paymentterm int | Supported days of payment term. values:
|
| createddate datetime | Date of when the object was created. |
| modifieddate datetime | Date of when the object was last modified. |
| createdby guid | Id of the creator. |
| modifiedby guid | Id of the modified. |
| subscriptions subscription array | Read-only array of subscriptions. May be included otherwise use query options. |
| invoices invoice array | Read-only array of invoices. May be included otherwise use query options. |
| paymentmethods paymentmethod array | Read-only array of payment methods. May be included otherwise use query options. |
| subscriptioncharges subscriptioncharge array | Read-only array of charges. May be included otherwise use query options. |
| transactions transaction array | Read-only array of transactions. May be included otherwise use query options. |
{
/* id of object, set by Upodi */
"id": "guid",
/* object id if the customer has a parent customer */
"parentid" : "guid",
/* if true, the parent customer will be the billing entity */
"billtoparent" : "boolean",
/* required, can be customized */
"accountnumber": "string",
"companyname": "string",
"companyvat": "string",
/* required */
"fullname": "string",
/* custom key, example a remote id */
"refkey": "string",
"primaryemail": "string",
/* required */
"currencycode": "string",
/* required */
"autobill": "boolean",
/* id of default payment method - can be extracted via $expand=DefaultPaymentMethod */
"paymentmethod": "guid",
"homephone": "string",
"businessphone": "string",
"mobilephone": "string",
"addressline1": "string",
"addressline2": "string",
/* text field */
"note": "string",
/* address city */
"city": "string",
"postalcode": "string",
/* address country */
"country": "string",
/* address county */
"county": "string",
/* address state */
"state": "string",
/* default payment method object if expanded */
"defaultpaymentmethod": "paymentmethod object",
"currency": "currency",
/* supported days of payment term. values:
-1=notset, 0=onreciept, 8=net8 days, 14=net14, 21=net21, 30=net30, 45=net45, 60=net60, 90=net90 */
"paymentterm" : "int",
/* array of subscription */
"subscriptions": "subscription[]",
/* array of invoices */
"invoices": "invoice[] array",
"paymentmethods": "paymentmethod[] array",
"subscriptioncharges": "subscriptioncharge[] array",
"transactions": "transaction[] array",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile object",
"modifiedbyuser": "userprofile object",
"createddate": "datetime",
"modifieddate": "datetime"
}contact object
Properties of the contact object. Contacts are always childs of existing customers.
{
/* id of object, set by Upodi */
"id": "guid",
/* required. id of the parent customer */
"customerid": "guid",
/* required. defines the type of contact. 8=invoice is sent to contact, 16= Delivery adress is used from contact, 32= EAN contact. Uses combined value of flags (fx 24=invoice is sent to contant and delivery to) */
"contacttype": "int",
/* required */
"fullname": "string",
/* custom key, example a remote id */
"refkey": "string",
"primaryemail": "string",
"homephone": "string",
"businessphone": "string",
"mobilephone": "string",
"addressline1": "string",
"addressline2": "string",
/* text field */
"note": "string",
/* address city */
"city": "string",
"postalcode": "string",
/* address country */
"country": "string",
/* address county */
"county": "string",
/* address state */
"state": "string",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile object",
"modifiedbyuser": "userprofile object",
"createddate": "datetime",
"modifieddate": "datetime"
}createpaymentmethod object
Used for the /paymentmethods/:customerid/ POST request.
See /paymentmethods/:customerid/ request. The given payment method need to be configured with a matching payment gateway before the payment method is accepted and processed.
{
"type" : int /* PureTokenBased = 64, FI = 128, LS = 256, Upodi card token = 8 */,
"makedefault" : "boolean", /* will make the payment method default on the customer */
"puretoken" : { /* Optional. Only define properties if type=64 (token) is defined. */
"token" : "string",
"paymentgateway" : "string" /* Optional. Only define properties if type=64 (token) is defined. Example stripe, epay, quickpay etc. */
},
"fi" : { /* Optional. Only define properties if type=128 (FI) is defined. */
"ficustomernumber" : "string"
},
"creditcard" : { /* Optional. Only define properties if type=8 (Upodi.js token) is defined. */
"cardtoken" : "string"
},
"ls" : { /* Optional. Leverandør Service. Only define properties if type=256 (FI) is defined. */
"bankregnumber" : "integer", /* 4 numbers long, example 9890 */
"bankaccountnumber" : "integer", /* 10 numbers long */
"cvrnumber" : "integer" /*8 numbers long */
}
}Example
The following outlines an example where the POST /paymentmethods/:customerid/ will create a default payment method on a customer, as a Stripe token.
{
"type" : 64,
"makedefault" : "true",
"puretoken" : {
"token" : "card_2445249082",
"paymentgateway" : "stripe"
}
}discount object
Properties of the discount object.
{
/* id of object, set by Upodi */
"id": "guid",
"fullname" : "string",
/* procentage = 0 */
"discounttypeenum" : "integer",
/* procentage amount */
"amount" : "decimal",
"InvoiceText" : "string",
/* 100=days,200=weeks,300=months,400=years. Defines expiry period */
"expiryperiod": "integer",
/* number of days, weeks, months, years */
"expiryperiodinterval": "integer",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile object",
"modifiedbyuser": "userprofile object",
"createddate": "datetime",
"modifieddate": "datetime"
}discountcode object
Properties of the discountcode object.
Full discount code for application is formatted as {codeprefix}-{code}. You can apply this to a customer, a subscription or a subscription charge.
{
/* id of object, set by Upodi */
"id": "guid",
/* required */
"codeprefix" : "string",
/* required. a code */
"code" : "string",
/* active=0, expired=1, consumed=2 */
"state" : "integer",
/* allows null, or the end date of the valid use. */
"expiredate": "guid",
/* readonly. number of times the code is consumed */
"usecount" : "integer",
"discountid" : "guid",
/* 0 for endless, a positive number for the times a code can be used */
"redemption" : "int",
"discount" : "discount object"
}
discountconsumer object
Properties of the discountconsumer object.
{
/* id of object, set by Upodi */
"id": "guid",
/* id of discount object */
"discountid" : "guid",
/* id of consuming object - customer, subscripion or subscriptioncharge */
"consumerid" : "guid",
"discount" : "discount object",
/* customer=0, subscription=1, subscriptioncharge=2 */
"consumertype" : "int",
"expirydate": "datetime",
"modifiedby": "guid",
"createdbyuser": "userprofile object",
"modifiedbyuser": "userprofile object",
"createddate": "datetime",
"modifieddate": "datetime"
}
subscription object
Properties of the subscription object
{
/* id of object, set by upodi */
"id": "guid",
"customerid": "guid",
/* Required. */
"productplanid": "guid",
/* Required. number of the subscription, can be custom */
"subscriptionnumber": "string",
/* allow null, if set switches to plan on renewal */
"switchtoplanid" : "guid",
/* if true, the subscription auto renews */
"autorenew": "boolean",
/* set by upodi. 0=active, 1=renewing, 2=grace, 3=expired, 4=cancelled, 5=draft, 6=pendingending, 7=ended, 8=hold */
"statecode": "integer",
/* set by upodi. 1024=deleted, 7=inactive, 1=active, 0=draft */
"status": "integer",
"startdate": "datetime",
"enddate": "datetime",
/* read-only. tell the life time of the subscription */
"lifetime": "integer",
/* internal of the term set by the initialtermperiod, example 1 for "one month" */
"initialterminterval": "integer",
/* days=100, months=300, quarters=400, years=500 */
"initialtermperiod": "integer",
/* read-only. initial period in string. */
"initialterm": "string",
/* internal of the term set by the renewaltermperiod, example 6 for "6 months" */
"renewalterminterval": "integer",
/* days=100, months=300, quarters=400, years=500 */
"renewaltermperiod": "integer",
/* read-only. renewal period in string. */
"renewalterm": "string",
/* custom key, example a remote id */
"refkey": "string",
/* set by upodi */
"lastrenewaldate": "datetime",
/* set by upodi */
"cancellationdate": "datetime",
/* set by upodi */
"activationdate": "datetime",
"customer": "customer object",
"productplan": "productplan object",
"subscriptioncharges": "subscriptioncharge[] array",
/* set by upodi */
"createdby": "guid",
/* set by upodi */
"modifiedby": "guid",
/* set by upodi */
"createdbyuser": "userprofile object",
/* set by upodi */
"modifiedbyuser": "userprofile object",
/* set by upodi */
"createddate": "datetime",
/* set by upodi */
"modifieddate": "datetime"
}
subscriptioncharge object
Properties of the subscription charge object
A subscription charge will be created for each billing cycle. The state of the previous subscription charge object will be transferred to the a new "pending" subscription charge. This enables a history of each charge back in time. New IDs are set for each new charge.
{
/* id of object, set by upodi */
"id": "guid",
"amount": "float",
"nextchargedate": "datetime",
"previouschargedate": "datetime",
"subscription": "subscription",
"productplancharge": "productplancharge",
"customer": "customer",
"subscriptionid": "guid",
/* set by upodi */
"toggled" : "boolean",
"productplanchargeid" : "guid",
"customerid" : "guid",
"unitprice" : "float",
"currencycode" : "string",
"description" : "string",
"invoiceid" : "guid",
"invoice" : "invoice",
"statecode" : "integer",
"createdby" : "guid",
"modifiedby" : "guid",
/* draft=0,active=1,hold=2 */
"statecode" : "integer",
/* draft=0,active=1,inactive=7,deleted=1024 */
"status" : "integer",
/* set by upodi */
"createdbyuser": "userprofile",
/* set by upodi */
"modifiedbyuser": "userprofile",
/* set by upodi */
"createddate": "datetime",
"modifieddate": "datetime"
}
invoice object
Properties of the invoice object
{
"id": "guid",
"customerid": "guid",
"subscriptionid": "guid",
"currencycode": "string",
"totalamount": "float",
"total": "float",
"totalvat": "float",
"invoicedate": "datetime",
"duedate": "datetime",
"paymentdate": "datetime",
/*
1024=failed,80=declined,70=pendingresponse,60=pendingprocessing,
50=cancelled,40=overdue,30=overpaid, 20=paid, 10=booked, 0=draft
*/
"paymentstatus": "integer",
/* text representation of the payment method */
"paymentdescriptor" : "string",
/* text representation of the invoice (example INV-0002130) */
"invoicenumber": "string",
/* numeric of the invoice number (example 2130) */
"invoicenumeric" : "integer",
"subscription": "subscription",
"customer": "customer",
"invoicelines": "invoicelines[]",
"dunningschemeid": "guid",
"dunningscheme": "dunningscheme",
"dunningstep": "integer",
/* set by Upodi - external ERP id */
"externalfinance" : "string",
/* normal=0, draft=1, booked=2, failedbook=1024 */
"externalstatecode" : "integer",
/* used for integration, cam be set to a custom value */
"refkey" : "string",
"nextretry": "datetime",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile",
"modifiedbyuser": "userprofile",
"createddate": "datetime",
"modifieddate": "datetime"
}
invoiceline object
Properties of the invoiceline object
{
"id": "guid",
"description": "string",
/* required */
"invoiceid": "guid",
"subscriptionchargeid": "guid",
"productplanchargeid": "guid",
"linenumber": "integer",
"quantity": "float",
"totalvat": "float",
"unitprice": "float",
"totalprice": "float",
"invoice": "invoice",
/* set by upodi */
"periodstart" : "date",
/* set by upodi */
"periodend" : "date",
"discount" : "float",
"discountamount" : "float",
"subscriptioncharge": "subscriptioncharge",
"productplancharge": "productplancharge",
"uomid": "guid",
"unit": "string",
"totalpriceexchangerate" : "float",
"totalpricebasecurrency" : "float",
"createddate": "datetime",
"modifieddate": "datetime"
}paymentmethod object
Properties of a paymentmethod object.
{
"customer": "object",
"id" : "guid",
"fullname" : "string",
"issuer" : "string",
"customerid" : "string",
"expirydate" : "datetime",
/* PureTokenBased=64, Creditcard=8, ManualInvoice=0, FI=128 */
"paymentmethodtype" : int,
"createddate" : "datetime",
"modifieddate" : "datetime",
"paymentdata" : "string"
}productplan object
Properties of the productplan object
{
"id": "guid",
"productfamilyid": "guid",
"sku": "string",
"fullname": "string",
"currencycode": "string",
/* "DKK, EUR" */
"activecurrencies": "string",
"currencies": "string[]",
"description": "string",
/* 1024=deleted, 7=inactive, 1=active, 0=draft */
"status": "integer",
/* 0=none, 1=prorate upgrades */
"changehandle": "integer",
"productplancharges": "productplancharge[]",
"subscriptions": "subscription[]",
"productfamily": "productfamily",
"productplanpricings": "productplanpricing[]",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile",
"modifiedbyuser": "userprofile",
"createddate": "datetime",
"modifieddate": "datetime"
}
productplancharge object
Properties of the productplancharge object
{
/* contains aligned productplancharge objects */
"addonproductcharge": "productplancharge",
"id": "guid",
"productplanid": "guid",
"fullname": "string",
"invoicetext": "string",
/* 8=flatfee,16=perunit,tieredpricing=32,volumepricing=64,procentage=1024,custom=12 */
"pricingmodel": "integer",
/* 8=onetime,16=recurring,32=usage */
"chargetype": "integer",
/* 100=daily,200=weekly,300=monthly,
400=quarterly,500=annually,1000=dayofweek,
1100=dayofmonth,1200=lastdayofmonth */
"billingperiod": "integer",
"billingperiodinterval": "integer",
/* 8=subscriptionstartdate,16=subscriptionenddate,
32=subscriptioncancellationdate,64=subscriptionactivationdate,
128=subscriptioncreationdate */
"billingperiodalignment": "integer",
"billingday": "integer",
"defaultamount": "float",
/* a string used to identify products for balancing purposes usually in erp-systems */
"sku": "string",
/* a string used to connect products for switch plan */
"anchorcode": "string",
"taxable": "boolean",
/* 0=charge, 10=dependency; - dependency to a parent productplancharge */
"productchargetype": "integer",
"productplan": "productplan",
"productplanchargepricings": "productplanchargepricing[]",
"subscriptioncharges": "subscriptioncharge[]",
"uom": "uom",
"uomid": "guid",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile",
"modifiedbyuser": "userprofile",
"createddate": "datetime",
"modifieddate": "datetime"
}productfamily object
Properties of the productfamily object
{
"id": "string",
"fullname": "string",
"productplans": "productplan[]",
"dunningschemeid": "guid",
"dunningscheme": "dunningscheme",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile",
"modifiedbyuser": "userprofile",
"createddate": "datetime",
"modifieddate": "datetime"
}
productplanchargepricing object
Properties of the productplanchargepricing object
{
"id": "guid",
"productplanchargeid": "guid",
"productplanid": "guid",
"segment": "integer",
"currencycode": "string",
"price": "float",
"tierfrom": "integer",
"tierto": "integer",
/* perunit=1,flatfee=0 */
"tierpriceformat": "integer",
"productplancharge": "productplancharge",
"productplan": "productplan",
"createddate": "datetime",
"modifieddate": "datetime"
}transaction object
Properties of the transaction object
{
"id": "guid",
"customerid": "guid",
"invoiceid": "guid",
/* unknown=0, decline=8,failure=16, success=1 */
"statecode": "integer",
/* inactive=7, active=1, draft=0, deleted=1024 */
"status": "integer",
/* void=2, verification=4, payment=8, refund=16, decline=32, chargeback=64 */
"type": "integer",
"totalamount": "float",
"currencycode": "string",
"paymentmethodid": "guid",
"paymentproviderid": "guid",
"customer": "customer",
"paymentmethod": "paymentmethod",
"paymentprovider": "paymentprovider",
"invoice": "invoice",
/* none=0,generic=101010, cardexpired=30000, invalidcardnumber=40100, invalidcardexpiry=40200, invalidcardcvc=40300, carddecline=101011, carddeclinefraud=101020, cardholder=101021 */
"errorcode": "integer",
"gatewayreference": "string",
"gatewayresponse": "string",
"gatewayerrorcode": "string",
"createdby": "guid",
"modifiedby": "guid",
"createdbyuser": "userprofile",
"modifiedbyuser": "userprofile",
"createddate": "datetime",
"modifieddate": "datetime"
}
currency object
Properties of the currency object
{
"id": "integer",
"currencyname": "string",
"exchangerate": "float",
"currencyid": "string",
"isactive": "boolean"
}
uom object
Properties of the uom object
{
"id": "string",
"fullname": "string",
"pluralname": "string",
"status": "integer",
"createddate": "datetime",
"modifieddate": "datetime",
}
/customers/:id/invoices
Return a list of invoice ids as a string array. Requires API scope 'read'.
/customers/:id/paymentmethods
Return a list of payment method ids. Requires API scope 'read'.
customers/:paymentMethodId/validatepaymentmethod/
Validates an associated payment method of a customer.
/customers/:id/assigncardtoken
Assigns a card to a customer and maps it as a payment method. Requires API scope 'write'.
Body is a string of the card token recieved from upodi.js.
{
"token" : "card_322jkl24j4lk2j", /* required */
"makedefault" : "true" /* optional parameter */
}/customers/:id/setdefaultpaymentmethod
Assigns a default payment method. Requires API scope 'write'.
Body is a string of the payment method id, i.e. "0e13a91b-90dc-4d5e-a24d-ed7c359672a5".
"0e13a91b-90dc-4d5e-a24d-ed7c359672a5"/paymentmethods/:customerid/bycustomer
Returns a paymenthod by customer id. Requires API scope 'read'.
/paymentmethods/:customerid/
Created a new payment method on a customer. Requires API scope 'write'.
See createpaymentmethod object here.
/discounts/
Creates a discount. Requires API scope 'write'. The type has to be 0, as for now we don’t have other discount type but 0 is meant as default percentage type discount.
/discounts/:id/applydiscountcodecustomer
Applies a discount to a customer. Requires API scope 'write'.
/discounts/:id/applydiscountcodesubscription
Applies a discount to a subscription. Requires API scope 'write'.
/discounts/:id/applydiscountcodesubscriptioncharge
Applies a discount to a subscription charge. Requires API scope 'write'.
Body must be a string of a valid discount-code, i.e. "discount-24mjui42j". Syntax is "{prefix}-{code}".
/discounts/:id/cleardiscountcodecustomer
Clear a discount from a customer. Requires API scope 'write'.
/discounts/:id/cleardiscountcodesubscription
Clear a discount from a subscription. Requires API scope 'write'.
/discounts/discountcode/
Deletes a discount code if not in use or already consumed.
BODY must be a string with " provided, no json formatting.
"discount-24M24klm2kl"/subscriptions/
Creates a new subscription. Subscriptions need to be activated before being active. Requires API scope 'write'.
/subscriptions/:id/setamount/
Sets quantity on all subscription charges or the one with specific productplanchargeid.
/subscriptions/:id/switchplan
Switch a subscription plan from one to another.
Body must contain the id of the new product plan. Be sure to include the " to keep json formatting.
"0a8eff02-a470-4a77-b37b-cbba97840e50""0a8eff02-a470-4a77-b37b-cbba97840e50"PUT https://api.upodi.io/v2/subscriptions/33bae0dd-f348-46e4-b865-2aeada684128/switchplan/?prorate=true HTTP/1.1
Content-type: application/json
Content-length: 5
Authorization: Bearer ...
"0a8eff02-a470-4a77-b37b-cbba97840e50"curl -X PUT
-d '"0a8eff02-a470-4a77-b37b-cbba97840e50", "prorate": "true"'
-H 'Content-type: application/json'
-H 'Authorization: Bearer...'
https://api.upodi.io/v2/subscriptions/33bae0dd-f348-46e4-b865-2aeada684128/switchplan/?prorate=true/subscriptions/:id/setpaymentmethod
Body must contain the Id of the Payment Method. The payment method has to exist on the Subscription Customer.
"8d5e55bf-a1d1-48cf-bf47-82e8330551b9"/subscriptioncharges/
Returns a list of subscription charges. Requires API scope 'read'.
/subscriptioncharges/:id
Get a subscriptioncharge based on the id. Requires API scope 'read'.
/subscriptioncharges/:id/setamount/
Set the amount of a subscription charge. Requires API scope 'write'.
Body must be a decimal of the new amount. Please format numbers by US numeric standard. Be sure to include the " to keep json formatting.
"3.2""3.2", "prorate": "true"PUT https://api.upodi.io/v2/subscriptionCharges/33bae0dd-f348-46e4-b865-2aeada684128/setamount/ HTTP/1.1
Content-type: application/json
Content-length: 5
Authorization: Bearer ...
"3.2", "prorate": "true"
curl -X PUT
-d '"3.2", "prorate": "true"'
-H 'Content-type: application/json'
-H 'Authorization: Bearer...'
https://api.upodi.io/v2/subscriptionCharges/33bae0dd-f348-46e4-b865-2aeada684128/setamount//subscriptioncharges/:id/togglecharge/
Toggles the subscriptioncharge on/off. Requires API scope 'write'.
/invoices/:id
Get a invoice based on the id. Requires API scope 'read'.