Quick Menu

Direct Integration - Return Order

The "Return Order" interface in Accounting as a Service is designed to handle the return of goods or licenses by customers. It allows clients to submit return data for processed orders, ensuring accurate booking of returned items, taxes, and discounts, as well as initiating refunds where applicable. This interface supports both standard returns initiated by customers and carrier returns where parcels were undeliverable. The process is integrated with existing order and invoice data, allowing seamless management of returns and associated refunds.

Standard return

The "Return Order" interface allows clients to process returns when customers send back goods or when parcels are returned by carriers as undeliverable. There are two primary reasons for returns:

  • CARRIER_RETURN: Used when the carrier returns the goods because the parcel was undeliverable (e.g., the end-customer was not home, did not pick up the parcel, or rejected it at the door).
  • CUSTOMER_RETURN: Used when the customer returns the goods for various reasons, such as not liking the product or it not fitting.

In both 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.
  • Partial Returns: The system supports partial returns (e.g., returning part of a line item). You are responsible for adjusting discounts and shipment fees that may no longer apply due to the return.
  • Multiple Return Requests: You can send multiple return requests for a single order, even for individual pieces of a line item. However, the order's value cannot increase due to the return process.
  • Refund Processing: If an open position is found on the end-customer account, it will be settled first before any refund is issued to the customer.

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. Return Initiation: The customer or carrier returns goods or licenses, and you posts a return order request to Accounting as a Service.
  4. Validation and Confirmation: Accounting as a Service validates the return request and provides feedback (confirmation or error) via via EDI Error Sent notification. notification.
  5. Booking and Refund: Accounting as a Service books the returned revenue, taxes, and discounts of the returned line items and processes the refund (if configured).
  6. 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}/returns
  • {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 returning an order (or parts of an order):

{
    "invoiceReference": "ORDNL-9100250113",
    "returnDate": "2024-08-28",
    "returnReason": "CUSTOMER_RETURN",
    "returnReference": "RETNL-440025011",
    "items": [
        {
            "grossUnitPrice": 5.00,
            "orderItemReference": 2,
            "quantity": 1.0,
            "vatAmount": 0.87,
            "vatPercent": 21,
            "vatType": "NORMAL"
        },
        {
            "grossUnitPrice": 74.80,
            "orderItemReference": 1,
            "quantity": 1.0,
            "vatAmount": 12.98,
            "vatPercent": 21,
            "vatType": "NORMAL"
        }
    ]
}
  • invoiceReference: Reference to the original invoice.
  • returnDate: Date when the return was processed.
  • returnReason: Reason for the return (e.g., CARRIER_RETURN, CUSTOMER_RETURN).
  • returnReference: Unique reference for the return transaction.
  • 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

Return 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 return order request.

Implementation

When processing a return 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 return order 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

{
    "invoiceReference": "ORDNL-9100250113",
    "returnDate": "2024-08-28",
    "returnReason": "CUSTOMER_RETURN",
    "returnReference": "RETNL-440025011",
    "items": [
        {
            "grossUnitPrice": 5.00,
            "orderItemReference": 2,
            "quantity": 1.0,
            "vatAmount": 0.87,
            "vatPercent": 21,
            "vatType": "NORMAL"
        }
    ],
    "bankDetails": {
        "accountOwner": "John Doe",
        "iban": "DE436345345344742",
        "bic": "BOFIIE2DXXX"
    }
}

Returns of Goods with Bundle Discounts

Description

When customers purchase items as part of a bundle that includes a discount (e.g., "Buy 3, get 10% off"), returning a portion of the bundle can affect the eligibility for the discount. In such cases, you are responsible for recalculating the applicable discounts and including the relevant line items in the return order request.

Implementation

Include both the returned items and the discount that cannot be considered anymore in the return order request.

Example

{
    "invoiceReference": "ORDNL-9100250113",
    "returnDate": "2024-08-28",
    "returnReason": "CUSTOMER_RETURN",
    "returnReference": "RETNL-440025011",
    "items": [
        {
            "grossUnitPrice": 5.00,
            "orderItemReference": 2,
            "quantity": 1.0,
            "vatAmount": 0.87,
            "vatPercent": 21,
            "vatType": "NORMAL"
        },
        {
            "grossUnitPrice": -2.00,  // Adjusted discount for the remaining items
            "orderItemReference": 3,  // Reference to the discount line item
            "quantity": 1.0,
            "vatAmount": -0.42,
            "vatPercent": 21,
            "vatType": "NORMAL"
        }
    ]
}