New contract via order creation

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.

How it works

Create "one-stop" order

When creating a new order via the "one-stop" order process, the following process steps will take place:

  • Customer browses products of the merchant. Hint: In case the product catalogue of Accounting as a Service is supposed to be the main source, all product information will be taken from Accounting as a Service when displaying products.
  • Customer places an order in the webshop.
  • Merchant checks for the customer to exist in Accounting as a Service and to have valid data.
  • (Optional) In case the customer does not yet exist in Accounting as a Service, customer creation handling needs to take place (see customer management).
  • (Optional) In case the customer data needs to be updated, the data needs to be adapted (see customer management).
  • Merchant requests creation of the order in Accounting as a Service.
  • Accounting as a Service creates new order based on the information from request.
  • In case the order needs activation first (e.g.: mobile phone contract which starts with delivery of phone), processing of the order will start with contract activation. Otherwise, the order will be processed immediately by Accounting as a Service.
High-level process description
A process overview using BPMN
Checkout the BPMN illustration to get an overview of the process, including the various activities and participating main actors.

Create order using basket functionality

When creating a new order using the basket functionality, the following process steps will take place:

  • Customer browses products of the merchant. Hint: In case the product catalogue of Accounting as a Service is supposed to be the main source, all product information will be taken from Accounting as a Service when displaying products.
  • Customer requests adding a product to his basket.
  • Merchant requests creation of new basket in Accounting as a Service.
  • Accounting as a Service creates a new basket.
  • Merchant requests adding the selected product to the basket.
  • Accounting as a Service adds the indicated product to the basket.
  • Customer checks out from the webshop with his basket.
  • Merchant requests creation order based on previous basket.
  • Accounting as a Service creates new order based on the information from the basket.
  • In case the order needs activation first (e.g.: mobile phone contract which starts with delivery of phone), processing of the order will start with contract activation. Otherwise, the order will be processed immediately by Accounting as a Service.
High-level process description
A process overview using BPMN
Checkout the BPMN illustration to get an overview of the process, including the various activities and participating main actors.

How to implement

Get products

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.

Sample request
GET /subscriptions/v1/products HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
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
      }
    ]
  }
]

Create order

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.

Sample request
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
    }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "contracts": [],
    "customerNumber": "700XXX651",
    "externalCustomerReference": "c1631704458",
    "signUpId": 700285700
}

Create basket

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.

Sample request
POST /subscriptions/v1/baskets HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
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"
}

Get basket

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.

Sample request
GET /subscriptions/v1/baskets/1800003245 HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Sample response
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"
}

Add product to basket

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.

Sample request
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,
}
Sample response
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"
}

Order basket

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.

Sample request
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
    }
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "contracts": [],
    "customerNumber": "700XXX651",
    "externalCustomerReference": "c1631704458",
    "signUpId": 700285700
}

See also