Quick Menu

Direct Integration - Cancel Order

The Cancel Order interface allows clients to cancel full or partial orders in the event that products are not available in the warehouse or if a customer requests a cancellation before the order has been shipped or invoiced. Cancellations can only occur for full order items (positions) rather than partial items within a position. It is essential to ensure that any associated discounts or related items are also canceled.

Standard cancellation

The Cancel Order interface supports various business scenarios where order cancellations are necessary, including:

  • Out of Stock: When items are unavailable in the warehouse.
  • Customer Cancellation: When customers request to cancel their orders before shipment.
  • No Payment Received for Prepaid Orders: When payment has not been received within the specified period for orders requiring prepayment.
  • Customer Service Cancellation: Initiated by the customer service team for various reasons.

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

General Workflow

  1. Order Creation: Customer places an order.
  2. Order Submission: The client sends the order to Accounting as a Service using the Create Order request.
  3. Order Confirmation: The client receives a confirmation via the EDI Error Sent notification.
  4. Cancellation Trigger: The customer requests cancellation, or the client initiates cancellation due to stock unavailability.
  5. Order Management System Update: The client updates the order management system to reflect the cancellation of the full order or specific positions.
  6. Cancellation Request Submission: The client sends a cancellation request via the Cancel Order API to Accounting as a Service.
  7. Confirmation or Error Handling: The client receives a confirmation via the EDI Error Sent notification or an error message and corrects the request if necessary.
  8. In case the payment has already been captured, Accounting as a Service initiates a refund based on the received order cancellation request.
  9. (optional) Accounting as a Service triggers a notification of type accounting/refundCompleted once the initiated refund has been completed.

Request Submission

To create an order, make a POST request to:

/accounting/v1/businesses/{businessCode}/customers/{customerNumber}/orders/{orderReference}/cancellations
  • {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

Request Body Structure

Below is an example of a complete request body for cancelling an order:

{
    "cancellationDate": "2024-09-09",
    "cancellationReason": "OUT_OF_STOCK",
    "items": [
        {"orderItemReference": 1},
        {"orderItemReference": 2}
    ]
}

Response Handling

Make sure you received feedback to the request validation via EDI Error Sent notification. Errors related to validation or processing are returned with descriptive messages to facilitate troubleshooting.If the cancellation could be processed without errors, a confirmation will be sent. It is important that the referred order has been processed correctly, otherwise the cancellation cannot be processed. For more details: Error Handling section

Use Cases for the cancel order interface

type of cancellation

Description You can either cancel parts of an order or the full order. However, only full line items can be cancelled. Accounting as a Service does not allow partial cancellations of a line item.

  • partial cancllation: only full line items can be cancelled (e.g. in case of unavailability of the product in the warehouse).
  • full cancellation: for full cancellations, you have to provide all line items in the items section that have been provided in the create order request originally.

Implementation

Provide the position that has been used in the create order and provide this number in the orderItemReference.

Example for a partial cancellation

In this case only the line item 3 of the original order is cancelled:

{
    "cancellationDate": "2024-09-09",
    "cancellationReason": "OUT_OF_STOCK",
    "items": [
        {"orderItemReference": 3}
    ]
}

Cancel with / without refunds

Description

  • Cancellation with refund: If the customer already paid in the frontend (prepayment), the amount has to be refunded. This can either be initiated by Accounting as a Service or needs to be done by the client.
  • Cancel an order with alternative payment method: If the original payment method cannot be refunded or does not exist anymore, or Accounting as a Service has no access (Omnichannel payments), the client can provide an IBAN as an alternative payment method that will be used to refund the amount resulting from the cancellation.
  • Cancellation without refund: If the capture for the payment only takes place after the delivery, a refund is not necessary.

Implementation

You dont have to provide any additional information in case for the refunds. This will be configured in the onboarding process and depends on whether the payment has taken place before the shipment was done or after. In case of alternative payment methods, Accounting as a Service supports the refund via bank transfer. For this you have to provide the following information:

  • IBANcode
  • bankAccountOwner
  • BIC (only mandatory in case the account is located outside the SEPA-area)

Example for cancellation with alternative payment method

{
    "bankDetails": {
        "accountOwner": "John Doe",
        "bic": "GENODEM1MSC",
        "iban": "DE51100100501234567890"
    },
    "cancellationDate": "2018-03-21",
    "cancellationReason": "CUSTOMER_CANCELLATION",
    "invoiceReference": "IDE12345678903",
    "items": [{
        "orderItemReference": 4
    }]
}

Reason for cancellations

Description Accounting as a Service provides the option to differentiate the cancellation reasons for reporting purposes.

Reasons:

  • Out of Stock: When items are unavailable in the warehouse.
  • Customer Cancellation: When customers request to cancel their orders before shipment.
  • No Payment Received for Prepaid Orders: When payment has not been received within the specified period for orders requiring prepayment.
  • Customer Service Cancellation: Initiated by the customer service team for various reasons.

Implementation

The cancellation reason is provided in the cancellationReason. Use the values OUT_OF_STOCK, CUSTOMER_CANCELLATION, NO_PAYMENT, or CUSTOMER_SERVICE.

Example for No Payment

{
    "cancellationDate": "2024-09-09",
    "cancellationReason": "NO_PAYMENT",
    "items": [
        {"orderItemReference": 1},
        {"orderItemReference": 2},
        {"orderItemReference": 3},
        {"orderItemReference": 4}
    ]
}