Add goodwill

An overview of the typical use case for the creation of a goodwill to trigger a refund to the customer.

In some cases, it might be necessary to grant a goodwill credit to your customer after the order has already been shipped. In these cases, you can define the values that will be paid out to the customer. Accounting as a Service will take care of the administration surrounding the goodwill credit, as well as taking over the payout to the customer.

How it works

When creating a goodwill for an order, the following process steps will take place:

1. (Prerequisite) Order has been placed using create webshop order.
2. (Prerequisite) Order has been invoiced using create invoice for webshop order.
3. Customer service grants a goodwill credit in CRM or OMS of the merchant.
4. Merchant calculates the values and passes on the information to Accounting as a Service.
5. Accounting as a Service takes over the booking of the revenue, taxes and discounts.
6. Accounting as a Service takes over the refund towards the customer.
7. Accounting as a Service triggers a notification of type accounting/refundCompleted once the initiated payment has been completed.
8. (Optional) Accounting as a Service informs the customer about the initiated payment via email.
9. (Optional) Merchant reviews the payment booking via the Accounting as a Service interface.

As an alternative to the process above using the related endpoint of the API, you can also make use of Accounting as a Service as the web UI of the accounting module to manually grant a goodwill credit.

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 goodwill for an order

To create a goodwill for an order, make a POST /accounting/{version}/businesses/{businessCode}/customers/{customerNumber}/orders/{orderReference}/goodwills request, where {businessCode} is the ID of the related business entity, {customerNumber} is the identifier of the affected customer and {orderReference} is the reference of the order that you would like to grant the goodwill credit to.

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

Sample request

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

{
    "creditDate": "2018-03-21",
    "goodwillDate": "2018-03-21",
    "goodwillReason": "CUSTOMER_COMPLAINT",
    "goodwillReference": "GDE12345678901",
    "invoiceReference": "IDE12345678901",
    "items": [{
        "grossUnitPrice": 11.9,
        "orderItemReference": 1,
        "quantity": 1,
        "vatAmount": 1.9,
        "vatPercent": 19,
        "vatType": "NORMAL"
    }]
}

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

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

Create goodwill for an order with payout to specific IBAN

In some cases, your customer may wish to receive the payment to a different bank account (IBAN) than to the one from which the origin payment came from. In such case, you can specify the IBAN, bank account owner and BIC (if the account is located outside the SEPA-area) that should be used instead. By default, all other goodwill payments will be made using the original payment method and account details.

If you need to make the goodwill payment to another account, the following fields are required:

• IBANcode
• bankAccountOwner
• BIC (this field is only mandatory if the account is located outside the SEPA-area)

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

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

{
    "creditDate": "2018-03-21",
    "goodwillDate": "2018-03-21",
    "goodwillReason": "CUSTOMER_COMPLAINT",
    "goodwillReference": "GDE12345678901",
    "invoiceReference": "IDE12345678901",
    "items": [{
        "grossUnitPrice": 11.9,
        "orderItemReference": 1,
        "quantity": 1,
        "vatAmount": 1.9,
        "vatPercent": 19,
        "vatType": "NORMAL"
    }],
  "IBANcode": "DE89370400440532013000",
  "bankAccountOwner": "Sammy Sample",
  "BIC": "INGDDEFFXXX"
}

Sample response

HTTP/1.1 200 OK
Content-Type: application/json

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

See also

• Create webshop order
• Create invoice for webshop order
• Refund
• Notification type accounting/refundCompleted