Quick Menu
Contract management
An overview of the typical use case handling for managing a contract in the context of a subscription-based order.
When working with subscription-based orders, the contract is the key element that serves to manage all relevant information for the billing and rating engine to process the billing and perform the calculation. Following the logical order, you will have to make sure that the associated customer is created and existing (see customer management) followed by the order (see order creation) that is supposed to be handled by the contract.
The creation of a contract is handled automatically when creating the related order in the subscription module. This page serves to demonstrate how to manage a contract.
How it works
While working with contracts, here is a list of the main activities that you will have to take care of.
Contract activation
Depending on your setup, you may have to explicitly activate a contract (e.g. in case of mobile phone contract which starts with the delivery of the phone). Given the setup of contract requiring explicit activation, the following process steps will take place when activating the contract:
- Merchant requests creation of new order in Accounting as a Service.
- Accounting as a Service creates new order and new contract that is associated with the order based on the information from request (new contract is in status
ORDERED). - (Optional) Merchant does what is necessary to be ready for the activation of the contract (e.g. shipping of the mobile phone).
- Merchants requests activation of the contract in Accounting as a Service.
- Accounting as a Service updates the status and starts processing the contract.
Contract cancellation/revocation/return
In case a contract cancellation/revocation/return is required, the following process steps will take place:
- Merchant requests creation of new order in Accounting as a Service
- Accounting as a Service creates new order and new contract that is associated with the order based on the information from request.
- Customer requests cancellation/revocation/return of his order
- Merchants passes request for cancellation/revocation/return to Accounting as a Service
- Accounting as a Service cancels the contract associated to the order.
- (OPTIONAL) Depending on the status of the order (e.g. if customer already paid for the product or not) Accounting as a Service will execute the refund process.
Contract termination
In case a contract termination is required, the following process steps will take place:
- Customer requests termination of his subscription (e.g. termination of a gym membership)
- Merchant passes request for termination to Accounting as a Service
- Accounting as a Service handles contract termination and sends back the date of termination to the merchant.
Adding more options to an existing contract
In some cases, there is a need to add one-time fees or additional recurring fees to a contract (e.g. a gym membership with additional work out training sessions that can be booked in addition). These fees can be added to regular subscription fees (such as monthly membership fees) and will be charged accordingly as part of upcoming bill runs.
- Customer requests additional options available as part of his subscriptions.
- Merchants requests adaptation of the contract in Accounting as a Service.
- Accounting as a Service updates the contract according to the information from the request.
- Upon next bill run, the billing and rating engine will take additional options into account when calculating the next invoice.
How to implement
Activate contract
To activate a contract, make a POST /subscriptions/{version}/customers/{customerNumber}/contracts/{contractId}/activate, where {contractId} is the ID of the contract and {customerNumber} is the identifier of the associated customer.
For more information, please refer to the related endpoint description within the API Explorer.
Sample request
POST /subscriptions/v1/customers/c1631704458/contracts/CON123/activate HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"requestedActivationDate": "2022-02-15"
}Sample response
HTTP/1.1 200 OK
Content-Type: application/json
{
"requestedActivationDate": "2022-02-15"
}Cancel/revoke/refund contract
To cancel/revoke/refund a contract, make a POST /subscriptions/v1/customers/{customerNumber}/orders/{orderReference}/returns, where {orderReference} is the ID of the order linked to the contract, and {customerNumber} is the identifier of the associated customer.
For more information, please refer to the related endpoint description within the API Explorer.
Sample request
POST /customers/c1631704458/orders/123/returns HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"returnDate": "2022-02-15",
"returnItems": [
{
"description": "Shirt red",
"grossUnitPrice": 19,
"netUnitPrice": 15.97,
"productID": "A0",
"quantity": 1,
"vatAmount": 3.03,
"vatPercent": 19
},
{
"description": "Shirt green",
"grossUnitPrice": 100,
"netUnitPrice": 84.03,
"productID": "B0",
"quantity": 1,
"vatAmount": 15.97,
"vatPercent": 19
}
],
"returnReason": "string",
"returnReference": "string"
}Sample response
HTTP/1.1 200 OK
Content-Type: application/json
{
"contracts": [],
"customerNumber": "700XXX651",
"externalCustomerReference": "c1631704458",
"signUpId": 700285700
}Terminate contract
To create a new order, make a POST /subscriptions/{version}/customers/{customerNumber}/contracts/{contractId}/terminate, where {contractId} is the ID of the contract and {customerNumber} is the identifier of the associated customer.
For more information, please refer to the related endpoint description within the API Explorer.
Sample request
POST /subscriptions/v1/customers/c1631704458/contracts/CON123/terminate HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"requestedTerminationDate": "2022-02-15",
"terminationReason": "02"
}Sample response
HTTP/1.1 200 OK
Content-Type: application/json
{
"terminationDate": "2022-02-15"
}Adding more options to an existing contract
To create a new order, make a POST /subscriptions/{version}/customers/{customerNumber}/contracts/{contractId}/options, where {contractId} is the ID of the contract and {customerNumber} is the identifier of the associated customer.
For more information, please refer to the related endpoint description within the API Explorer.
Sample request
POST /customers/c1631704458/contracts/CON123/options HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"options": [
{
"productID": "S1",
"charges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
}
]
}
]
}Sample response
HTTP/1.1 200 OK
Content-Type: application/json
{
"contracts": [],
"customerNumber": "700XXX651",
"externalCustomerReference": "c1631704458",
"signUpId": 700285700
}