An overview of the typical use case handling for creating a new subscription order in Accounting as a Service.
Creating an order is the prerequisite to move on with the related contract management. Before the order creation, you will have to make sure that the customer associated with the order is existing in the subscription module. For managing the customer, please refer to the customer management.
This page serves to demonstrate how to create an order in the subscription module. There are two ways to create an order, which will be described below.
When creating a new order via the "one-stop" order process, the following process steps will take place:
When creating a new order using the basket functionality, the following process steps will take place:
To get the list of existing products as managed in the product catalogue of the subscription module, make a GET /subscriptions/{version}/products
.
For more information, please refer to the related endpoint description within the API Explorer.
GET /subscriptions/v1/products HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"productID": 25,
"externalProductId": "ID025",
"description": "Product X4R",
"displayValue": "Product X4R",
"displayValueForBill": "Product X4R",
"minContractDuration": 0,
"charges": [
{
"netAmount": 10.0,
"grossAmount": 11.9,
"amountGrossDiscounts": 0.0,
"amountNetDiscounts": 0.0,
"chargeType": "Initial Charge",
"chargeMode": "ONE_OFF",
"vatPercent": 19.0
}
]
}
]
To create a new order, make a POST /subscriptions/{version}/customers/{customerNumber}/orders
, where {customerNumber}
is the reference of the customer associated with the new order.
For more information, please refer to the related endpoint description within the API Explorer.
POST /subscriptions/v1/customers/c1631704458/orders HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"businessEntity": "string",
"guestCustomer": false,
"order": {
"campaigns": [
"STRING",
"STRING"
],
"currency": "EUR",
"deliveryType": "EXPRESS",
"items": [
{
"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
}
],
"orderChannel": "ECOM",
"orderDate": "2019-12-30T00:00:00Z",
"orderReference": "C01285859",
"shipToAddress": {
"addressType": "string",
"careOf": "",
"countryCode": "DE",
"postalCode": "33333",
"postalPlace": "Guetersloh",
"street": "An der Autobahn",
"streetNumber": "200",
"streetNumberAdditional": ""
},
"totalGrossAmount": 119,
"totalNetAmount": 100
},
"paymentTransaction": {
"links": {
"href": "https://my.cancel.server/v7.1.53/api/transactions/cancel",
"type": "CANCEL"
},
"miscPspSpecificDetails": {
"latestPspTransactionId": "string",
"pspOrderId": "string"
},
"status": "string",
"token": "string",
"totalCapturedAmount": 1,
"totalRefundedAmount": 0
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"contracts": [],
"customerNumber": "700XXX651",
"externalCustomerReference": "c1631704458",
"signUpId": 700285700
}
To create a new basket, make a POST /subscriptions/{version}/baskets
.
For more information, please refer to the related endpoint description within the API Explorer.
POST /subscriptions/v1/baskets HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "2021-02-15T00:00:00Z",
"currency": "EUR",
"externalCustomerId": "12345",
"id": "1800003245",
"items": [
{
"contractEndDate": "2022-02-15T00:00:00Z",
"customData": [
{
"customDataType": "Car",
"details": {
"VIN": "1234ABC"
}
}
],
"oneTimeCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
}
],
"productID": "S1",
"quantity": 1,
"recurringCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
}
],
"startDateRequested": "2021-02-15T00:00:00Z"
}
],
"totalOnetimeCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
},
"totalRecurringCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
},
"updated": "2021-02-20T00:00:00Z"
}
To get detailed information for an existing basket, make a GET /subscriptions/{version}/baskets/{basketId}
, where {basketId}
is the ID of the basket as it is returned when creating a new basket.
For more information, please refer to the related endpoint description within the API Explorer.
GET /subscriptions/v1/baskets/1800003245 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "2021-02-15T00:00:00Z",
"currency": "EUR",
"externalCustomerId": "12345",
"id": "1800003245",
"items": [
{
"contractEndDate": "2022-02-15T00:00:00Z",
"customData": [
{
"customDataType": "Car",
"details": {
"VIN": "1234ABC"
}
}
],
"oneTimeCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
}
],
"productID": "S1",
"quantity": 1,
"recurringCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
}
],
"startDateRequested": "2021-02-15T00:00:00Z"
}
],
"totalOnetimeCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
},
"totalRecurringCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
},
"updated": "2021-02-20T00:00:00Z"
}
To add a product to a basket , make a PUT /subscriptions/{version}/baskets/{basketId}
, where {basketId}
is the ID of the basket as it is returned when creating a new basket.
For more information, please refer to the related endpoint description within the API Explorer.
PUT /subscriptions/v1/baskets/1800003245 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"productID": "25",
"quantity": 1,
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": "2021-02-15T00:00:00Z",
"currency": "EUR",
"externalCustomerId": "12345",
"id": "1800003245",
"items": [
{
"contractEndDate": "2022-02-15T00:00:00Z",
"customData": [
{
"customDataType": "Car",
"details": {
"VIN": "1234ABC"
}
}
],
"oneTimeCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
}
],
"productID": "S1",
"quantity": 1,
"recurringCharges": [
{
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
}
],
"startDateRequested": "2021-02-15T00:00:00Z"
}
],
"totalOnetimeCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 0,
"netAmount": 0,
"unitAmountGross": 0,
"unitAmountNet": 0,
"vatAmount": 0,
"vatPercent": 0
},
"totalRecurringCharge": {
"amountGrossDiscounts": 0,
"amountNetDiscounts": 0,
"grossAmount": 17.99,
"netAmount": 15.12,
"unitAmountGross": 17.99,
"unitAmountNet": 15.12,
"vatAmount": 2.87,
"vatPercent": 0.19
},
"updated": "2021-02-20T00:00:00Z"
}
To create a new order based on an existing basket, the request is similar to the order creation without using a basket. Make a POST /subscriptions/{version}/customers/{customerNumber}/orders
, where {customerNumber}
is the identifier of the customer associated with the new order.
For more information, please refer to the related endpoint description within the API Explorer.
POST /subscriptions/v1/customers/c1631704458/orders HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json
{
"businessEntity": "string",
"guestCustomer": false,
"order": {
"baskedId": 1800003245
},
"paymentTransaction": {
"links": {
"href": "https://my.cancel.server/v7.1.53/api/transactions/cancel",
"type": "CANCEL"
},
"miscPspSpecificDetails": {
"latestPspTransactionId": "string",
"pspOrderId": "string"
},
"status": "string",
"token": "string",
"totalCapturedAmount": 1,
"totalRefundedAmount": 0
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"contracts": [],
"customerNumber": "700XXX651",
"externalCustomerReference": "c1631704458",
"signUpId": 700285700
}