Quick Menu

Create webshop order

An overview of the typical use case handling the creation of a webshop order as the initial action along the accounting process in Accounting as a Service.

The creation of a webshop order is the first step in the accounting process of Accounting as a Service. It is the prerequisite for creating and sending invoices, booking revenue, capturing a payment and booking incoming payments.

This use case is supposed to be applied in combination with a typical checkout procedure from a webshop, which is executed once the user has passed the payment part and finally confirmed the order. The use case serves to hand in the basic data of a webshop order to be used by the accounting module for further processing.

If you are using Accounting as a Service Subscription, please note that calling the create order endpoint from the subscription module automatically results in the creation of an order in the accounting module.

IMPORTANT NOTE In case you make use of the subscription module to create your order, you should NOT create a webshop order for the in addition.

How it works

When creating a webshop order, the following process steps will take place:

  1. Customer places an order in the webshop of the merchant following a typical checkout scenario. (Alternative trigger: In case of subscription based business but without using Accounting as a Service Subscription, a subscription bill run takes place).
  2. Merchant requests the creation of a new order in Accounting as a Service.
  3. Accounting as a Service creates new order based on the information from the request.
  4. In case a down payment needs to be executed, Accounting as a Service books a down payment request.
  5. In case the down payment hits your bank account or occurs in a settlement file, Accounting as a Service books it including VAT and sends a notification of type accounting/paymentReceived.
High-level process description
An overview using BPMN to describe the process flow
Checkout the BPMN illustration to get an overview of the process, including the various activities and participating main actors.
Open in new tab

How to implement

Create a webshop order with physical products

To create a webshop order, make a POST /accounting/{version}/businesses/{businessCode}/customers/{customerNumber}/orders request, where {businessCode} is the 4-digit company code number of the related business code and {customerNumber} is the identifier of the associated customer.

Depending on the payment method that is linked to the order, you will have to provide payment specific information as part of the paymentReference. For more information about the possible values available for the field paymentMethodName, please check out the unique identifiers of the payment method overview.

In case your order includes physical products, you will have to set orderType = PHYSICAL_GOODS. Also, the product(s) to be shipped should have positionType = SALES_ARTICLE.

For more information, please refer to the related endpoint description within the API Explorer.

Sample request
POST /accounting/v1/businesses/1000/customers/TFI2021072801/orders HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
    "billToAddress": {
        "careOf": "Jane c/o John",
        "countryCode": "DE",
        "firstName": "Max",
        "language": "de",
        "lastName": "Mustermann",
        "postalCode": "48213",
        "postalPlace": "Muenster",
        "salutation": "MRS",
        "street": "Beispielstr.",
        "streetNumber": "13A",
        "title": "DR",
        "birthDate": "1983-09-15",
        "nationality": "DE",
        "email": "max.mustermann@outlook.com",
        "phone": "+491345789555",
        "customerGroup": "Gold Clients",
        "taxIdentificationNumber": "DE999999999"
    },
    "currency": "EUR",
    "orderType": "PHYSICAL_GOODS",
    "orderDate": "2015-12-10T00:00:00.0000000",
    "items": [
        {
            "grossUnitPrice": 119.00,
            "orderItemReference": 1,
            "quantity": 1,
            "vatAmount": 19,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "BEF12346512A/1",
            "description": "Blumentopf XL (GRAU)",
            "positionType": "SALES_ARTICLE"
        }
    ],
    "orderReference": "ODE12345678901",
    "paymentReference": {
        "paymentMethodName": "VISA",
        "paymentDetails": {
            "authorizationDate": "2018-11-05T16:15:03.0000000+00:00",
            "authorizedAmount": 119.00,
            "cardHolder": "Max Mustermann",
            "cardType": "VI",
            "expirationDate": {
                "month": 12,
                "year": 2018
            },
            "merchantAccountId": "ECOM_WP",
            "settlementReference": "ODE12340849323",
            "transactionToken": "8acda4a36b26b30a016b64b7bcd0225c"
        }
    },
    "processAfterDunning": "HAND_OVER_FOR_DEBT_COLLECTION",
    "orderChannel": "ECOM",
    "shipToAddress": {
        "careOf": "Jane c/o John",
        "countryCode": "DE",
        "firstName": "Max",
        "language": "de",
        "lastName": "Mustermann",
        "postalCode": "48213",
        "postalPlace": "Muenster",
        "salutation": "MRS",
        "street": "Beispielstr.",
        "streetNumber": "13A",
        "title": "DR",
        "state": "AL"
    },
    "supplyingCountry": "DE",
    "vatDeclarationCountry": "DE"
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "internalRequestId": "23c9579b-baaf-468f-a529-f876226e183c"
}

Create a webshop order with digital products only

In case of the order only consisting of digital products, you will not need to provide a shipping address. Please note that if you have a mixed shopping cart (i.e. digital + physical products), you will have to provide the shipping address information.

In case of the order only consisting of digital products orderType needs to be set to the value DIGITAL_GOODS.

Sample request
POST /accounting/v1/businesses/1000/customers/TFI2021072801/orders HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
    "billToAddress": {
        ...
    },
    "currency": "EUR",
    "orderType": "DIGITAL_GOODS",
    "orderDate": "2015-12-10T00:00:00.0000000",
    "items": [
        {
            "grossUnitPrice": 11.9,
            "orderItemReference": 1,
            "quantity": 1,
            "vatAmount": 1.9,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "WKD12346512A/1",
            "description": "Best wishes (Digital card)",
            "positionType": "SALES_ARTICLE"
        }
    ],
    "orderReference": "ODE12345678901",
    "paymentReference": {
        ...
    },
    "processAfterDunning": "HAND_OVER_FOR_DEBT_COLLECTION",
    "orderChannel": "ECOM",
    "supplyingCountry": "DE",
    "vatDeclarationCountry": "DE"
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "internalRequestId": "23c9579b-baaf-468f-a529-f876226e183d"
}

Create webshop order for subscription

If you use your own or a 3rd party subscription management module, you need to provide additional contract details when creating an order that refers to a subscription.

When dealing with subscriptions, Accounting as a Service expects you to have contracts with your customers building the basis for regular orders and invoices (e.g. mobile phone contracts). For this reason, you will be expected to provide additional information on the contract in form of the contract object.

In addition, subscription related order items need to have positionType = SUBSCRIPTION_ORDER in which case the property subscription needs to be provided.

Sample request
POST /accounting/v1/businesses/1000/customers/TFI2021072801/orders HTTP/1.1
Host: api-uat.accounting.riverty.io
X-Subscription-Key: YOUR_API_SUBSCRIPTION_TOKEN
Content-Type: application/json

{
    "billToAddress": {
        ...
    },
    "contract": {
        "basicCharge": 12,
        "contractID": "A545axe58",
        "customerContractEndDate": "2016-01-09T00:00:00.0000000",
        "customerContractStartDate": "2015-12-10T00:00:00.0000000",
        "description": "10 month contract",
        "endDate": "2019-03-15T00:00:00.0000000",
        "minimumTerm": 3,
        "startDate": "2018-12-05T00:00:00.0000000"
    },
    "currency": "EUR",
    "orderType": "DIGITAL_GOODS",
    "orderDate": "2015-12-10T00:00:00.0000000",
    "items": [
        {
            "grossUnitPrice": 119.00,
            "orderItemReference": 1,
            "quantity": 1,
            "vatAmount": 19,
            "vatPercent": 19,
            "vatType": "NORMAL",
            "productId": "BEF12346512AAA",
            "description": "Monthly download volume (Package M)",
            "positionType": "SUBSCRIPTION_ORDER",
            "subscription": {
                "endDate": "2019-03-15T00:00:00.0000000",
                "startDate": "2018-12-05T00:00:00.0000000"
            }
        }
    ],
    "orderReference": "ODE12345678901",
    "paymentReference": {
        ...
    },
    "processAfterDunning": "HAND_OVER_FOR_DEBT_COLLECTION",
    "orderChannel": "ECOM",
    "supplyingCountry": "DE",
    "vatDeclarationCountry": "DE"
}
Sample response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "internalRequestId": "23c9579b-baaf-468f-a529-f876226e183d"
}

Special handlings

Here is a list of special cases that might be helpful for you to know.

Provide order with discounts

You can provide orders including discounts. As it does not make any difference for the booking whether the discounts are position or order related, you have to provide a single order position for each discount.

When creating order positions for discounts, please set positionType = DISCOUNT.

As you will have to provide the information about which positions to be invoiced or returned as part of the call Create invoice for webshop order or Return webshop order, you should create a separate order position for every value that should/could be invoiced/returned separately.

Provide order with gift cards (partial payment)

If you sell Giftcards that can be used to pay parts of the order value, you have to differentiate between the main payment method (paying the rest of the order value) and the Giftcard (reducing the order value to be paid).

For partial payments via Giftcards, you have to provide the Giftcard using the positionType = GIFT_CARD_VOUCHER_PAYMENT. In addition, you can provide a Giftcard ID as value for the field giftCardVoucherId of reportingPositionData, which can be used for reporting / reconciliation purposes.

Provide generic position information per order

Accounting as a Service allows up to 5 additional fields that can be added for each order and in addition for each order item. This information can be used for reporting purposes on your side. Please use the fields genericField... to be found under reportingPositionData.

"reportingPositionData": {
        "genericField1": "Some value A",
        "genericField2": "Some value B",
        "genericField3": "Some value C",
        "genericField4": "Some value D",
        "genericField5": "Some value E",
}

See also