Collect on Delivery

Table of Contents

Overview
Configuration
Usage

Overview

Collect on Delivery (COD) support was added in Broadleaf 1.7.5 and 1.8.0. COD is a form of payment where all or part of the cart total will be received when the goods are delivered in person rather than during checkout, electronically.

Configuration

COD can be enabled like any other payment method. This includes setting extra fees and some restrictions on when the method is available such as for cart min and max totals.

Sample configuration for Collect on Delivery:

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-payment-method-options:
          - payment-method-type: CREDIT_CARD
            payment-method-gateway-type: PASSTHROUGH
         # set up COD
         - payment-method-type: COD
           payment-method-gateway-type: COD
           cart-max-total-restriction:
             USD: 500.00
           cart-min-total-restriction:
             USD: 100.00
           fulfillment-inclusions:
             fulfillmentOption.name: ['FIXED_STANDARD']
           fulfillment-exclusions:
             address.postalCode: ['10100']
           fees:
             - name: Fee 1
               amount: 1.00
               currency: USD
               taxable: false
               discountable: false
               refundable: false

Usage

Selecting COD

Like other Payment Methods, COD will be filtered out of the list of payment methods returned to the frontend from the CheckokutCartEndpoint#getCheckoutPaymentMethodOptions request if the current cart does not meet the restrictions.

To select, a payment should be created with type COD and the amount desired via the Payment Transaction Service. Then, a request should be sent to set the COD_STATUS attribute on the FulfillmentGroup. This can be done via the CheckoutCartEndpoint#updateFulfillmentGroupInCart, PATCH /api/cart-operation/checkout/:cartId/fulfillment-groups/:reference-number. The selection will be validated against the restrictions before the update is persisted.

Example request payload

{
    "attributes": {
      "COD_STATUS": "SELECTED"
    }
}

If not available at time of selection, an HTTP 400 COD_NOT_AVAILABLE error will be returned.
If there are fees associated with the method, then those will be added a separate Cart Items with type EXTRA_FEE.
- If tax is applied, the TaxInfo will be added to the CartItem’s internalAttributes as TAX_INFO
- The value of the Fee.isRefundable flag will be added to internalAttributes.IS_FEE_REFUNDABLE

Important

These items are not added to any FulfillmentGroup to avoid changes to fulfillment pricing.

Tip	Attribute name `COD_STATUS` Constant for reference: `FulfillmentGroup.COD_STATUS_ATTR` Attribute values for reference: `FulfillmentGroup.DefaultCollectOnDeliveryStatus`

Subsequent Updates before Checkout Completion

On every subsequent update to the cart if COD is selected, validation will be performed to ensure that the update to the cart will not invalidate COD. If an update such as changing the fulfillment option invalidates COD, an HTTP 400 COD_NOT_AVAILABLE error will be returned to allow the user to cancel or confirm the update. If the update is confirmed, the #updateFulfillmentGroupInCart should first be used to de-select COD. This will remove the fee CartItems and archive the related payment in Payment Transaction Service.

Example request payload

{
    "attributes": {
      "COD_STATUS": "NOT_SELECTED"
    }
}

Then the original request can be retried.

Checkout Completion

Once a checkout request is submitted, COD will again be validated to ensure it is applicable. Additionally, the sum of the payments including COD must equal the cart total including fees. If it has been deselected previously but the related payment method has not been archived, it will now be archived.

Important

COD payments will not have any transactions against them.

Post Checkout

After checkout, the Order Operations Service will create OrderItems for any fee CartItems and update the related OrderFulfillment so that #requiresCollectOnDelivery is set to true. No additional logic is currently provided to handle COD payment collection—collection should be handled offline. However, if other payment options were added, they may still be captured for the remainder of the order amount not covered by COD.