Direct Integration - Add Goodwill

The "Add Goodwill" interface allows you to process goodwill adjustments when customers experience issues such as complaints, delivery delays, missing items, or other scenarios that warrant compensation without returning the goods. Goodwill adjustments can also be used in cases where the client chooses to compensate the customer for lost items, defective products that don’t need to be returned, or specific corrections like voucher usage or price discrepancies.

Standard Goodwill

The "Add Goodwill" interface allows clients to process goodwills for orders with a complaint of the customer but without a return of goods. There are three main categories for such a goodwill:

  • Customer Service Goodwill: For customer complaints, delayed delivery, or defective items that do not need to be returned.
  • Goodwill for Lost Packages: When a package is lost by the carrier, and you need to compensate the customer without a return.
  • Adjustments for Pricing Errors: Correcting an order when the price charged does not match the advertised price.

In each case, you must provide the goodwillReason field with the appropriate reason from the predefined list (e.g., CUSTOMER_COMPLAINT, DELIVERY_DELAYED).

In all cases, a refund will be triggered if the end-customer has already paid for the goods and there is no outstanding amount on the end-customer’s account.

Key Points:

  • Prerequisites:
    • The order must have been created using the create order request and confirmed by Accounting as a Service via an EDI Error Sent notification.
    • The line item must have been shipped and invoiced; the create invoice request must have been sent to Accounting as a Service and confirmed via EDI Error Sent notification.
  • You have to ensure that the goodwill is always applied to specific line items within the order. If the goodwill applies to the entire order, you must split the goodwill value among all relevant line items.
  • The goodwill amount should be calculated and provided by you; Accounting as a Service will use the values exactly as provided.

General Workflow:

  1. Order Creation: Order is placed using create order and confirmed by Accounting as a Service via EDI Error Sent notification.
  2. Invoice and Shipment: Line items are shipped and invoiced; the create invoice request is confirmed by Accounting as a Service via EDI Error Sent notification.
  3. Grant Goodwill: You have to identify the need for a goodwill adjustment in your system (e.g., CRM/OMS) due to customer service decisions, complaints, or issues.
  4. Submit Goodwill Request: You have to calculate the goodwill values for the affected line items and submit them via the add goodwill request to Accounting as a Service.
  5. Validation and Confirmation: Accounting as a Service validates the goodwill request and provides feedback (confirmation or error) via via EDI Error Sent notification. notification.
  6. Booking and Refund: Accounting as a Service books the goodwill-revenue, taxes, and discounts of the returned line items and processes the refund (if configured).
  7. Notifications:
    • Optionally, Accounting as a Service triggers a notification of type accounting/refundCompleted once the payment has been processed.
    • Optionally, the end-customer is informed about the initiated refund via email.

Request Submission

To create an invoice, make a POST request to:

POST /accounting/v1/businesses/{businessCode}/customers/{customerNumber}/orders/{orderReference}/goodwills
  • {businessCode}: Represents the legal entity (e.g., use "1000" in sandbox).
  • {customerNumber}: The end-customer’s unique identifier used in the create order
  • {orderReference}: The orderReference provided for the original order in the create order

Key Points: Ensure all mandatory fields are completed as per the API-Explorer.

Request Body Structure

Below is an example of a complete request body for adding a goodwill to an order (or parts of an order):

{
    "goodwillDate": "2024-09-13",
    "goodwillReason": "CUSTOMER_COMPLAINT",
    "invoiceReference": "INV-1234322",
    "goodwillReference": "01J7NPK9R5Y0KV1GHA34JZ7YP2",
    "items": [
        {
            "grossUnitPrice": 20.00,
            "orderItemReference": 1,
            "quantity": 1.0,
            "vatAmount": 3.47,
            "vatPercent": 21,
            "vatType": "NORMAL"
        }
    ]
}
  • invoiceReference: Reference to the original invoice.
  • goodwillReference: Your ID for the communication of the goodwill.
  • goodwillDate: Date when the goodwill was processed.
  • goodwillReason: Reason for the return
    • CUSTOMER_COMPLAINT: When a customer complains about product functionality, quality, service, or process.
    • DELIVERY_DELAYED: Compensation for delayed delivery.
    • ARTICLE_PARCEL_MISSING: Compensation when an article or entire parcel is missing.
    • ARTICLE_DEFECTIVE: Article is defective but doesn’t need to be returned.
    • CORRECTION_PRICE: When the price was not as advertised.
    • LOSS_OF_DELIVERY: When the delivery is lost by the carrier.
    • CORRECTION_VOUCHER: When a customer wanted to use a voucher but was unable to do so; this corrects the original order.
    • LOSS_OF_RETURN_POST: When the customer returns goods, but the return is lost during transit.
    • LOSS_OF_RETURN_WAREHOUSE: When the customer returns goods, the carrier delivers the parcel, but it is not booked in by the logistics center.
    • CONTRADICTION_OF_SIGNATURE: When there is a contradiction of signature.
    • ISSUE_IN_STORE: When there was an issue with an order in the physical store.
    • REFUND_EXPRESS_COSTS: When the express delivery costs need to be refunded without any return.
    • FRAUD: When the end-customer can proove that they were victims of fraud.
    • OTHER: For other unspecified reasons.
  • items: Details of the returned items, including line item reference, quantity, and applicable tax information.

You are responsible to provide the correct items that need to be considered (e.g. Discounts, Shipment-Discounts) and the correct values (considering previously granted goodwills). Accounting as a Service takes the values as given.

Use Cases

Goodwill with Alternative Refund Payment Method (Bank Transfer)

Description

In some scenarios, such as when the original payment method does not involve a PSP or bank account (e.g., Cash on Delivery or Omnichannel payments), Accounting as a Service may not have the necessary details to process a refund. In such cases, the client must provide alternative refund payment details in the add goodwill request.

Implementation

When processing a goodwill that requires an alternative refund method, you have to request the details from the end-customer and include the customer's bank details within the add goodwill request. This additional information allows Accounting as a Service to perform the refund via bank transfer, even when the original payment method does not directly support refunds. The bank details should include the account accountOwner, IBAN, and BIC (for non-SEPA countries).

Example

{
    "goodwillDate": "2018-03-21",
    "goodwillReason": "CUSTOMER_COMPLAINT",
    "goodwillReference": "GDE12345678901",
    "invoiceReference": "IDE12345678901",
    "items": [
        {
            "grossUnitPrice": 5.00,
            "orderItemReference": 2,
            "quantity": 1.0,
            "vatAmount": 0.87,
            "vatPercent": 21,
            "vatType": "NORMAL"
        }
    ],
    "bankDetails": {
        "accountOwner": "John Doe",
        "iban": "DE436345345344742",
        "bic": "BOFIIE2DXXX"
    }
}