External Discounts

You can integrate discounts from an external system directly into the cart and order processes instead of using discounts from the Kibo catalog. This is done by installing an adapter configured with the endpoint of your external discount system, which Kibo will then call to retrieve discount details. 

This feature supports order and item level discounts for product, shipping, and handling. You can use external discounts alongside external pricing if desired.

External Request and Response

Before configuring the adapter, you should be familiar with the request that Kibo will send to your external endpoint and the response you are expected to provide.

Request from Kibo

Kibo will make the following request to your system when determining pricing. Any changes that require a pricing refresh such as adding an item, adding a payment, or updating the quantity will trigger this call to update discounts.

{
    "orderNumber": "System.Int32",
    "orderId": "System.String",
    "currencyCode": "System.String",
    "items": [
        {
            "id": "System.String",
            "lineId": "System.Int32",
            "product": {
                "id": "System.String",
                "productCode": "System.String",
                "baseProductCode": "System.String",
                "price": "System.Decimal",
                "salePrice": "System.Decimal",
                "overridePrice": "System.Decimal",
                "productProperties": [
                    {
                        "attributeFQN": "System.String",
                        "values": [
                            {
                                "value": "System.Object",
                                "stringValue": "System.String"
                            }
                        ],
                        "attributeDetail": {
                            "inputType": "System.String",
                            "valueType": "System.String",
                            "dataType": "System.String",
                            "name": "System.String",
                            "description": "System.String"
                        },
                        "isHidden": "System.Boolean",
                        "isMultiValue": "System.Boolean"
                    }
                ]
            },
            "quantity": "System.Int32",
            "shippingPricePerRate": [
                {
                    "shippingMethodCode": "System.String",
                    "amount": "System.Decimal",
                    "zone": "System.String"
                }
            ],
            "appliedProductDiscountIds": [
                {}
            ],
            "appliedShippingDiscountIds": [
                {}
            ],
            "rejectedDiscounts": [
                {}
            ],
            "fulfillmentLocationCode": "System.String",
            "fulfillmentMethod": "System.String",
            "data":{
            }
        }
    ],
    "payments": [
        {
            "paymentType": "System.String",
            "paymentWorkflow": "System.String",
            "amount": "System.Decimal"
        }
    ],
    "couponCodes": [
        {}
    ],
    "rejectedCouponCodes": [
        {}
    ],
    "orderSubmittedDate": "/Date(-62135575200000-0600)/",
    "appliedOrderDiscountIds": [
        {}
    ],
    "rejectedDiscounts": [
        {}
    ],
    "useOverridePriceToCalculateDiscounts": "System.Boolean",(Is this required?)
    "customerId": "System.Int32",
    "data":{
    },
    "shipToGroupings": [
        {
            "id": "System.String",
            "lineItemIds": [
                {}
            ],
            "appliedShippingDiscountIds": [
                {}
            ],
            "appliedHandlingDiscountIds": [
                {}
            ],
            "shippingMethodCode": "",
            "flatRateShippingAmount": "System.Decimal",
            "orderHandling": "System.Decimal",
            "orderShippingAdjustment": "System.Decimal",
            "fulfillmentMethod": "System.String"
        }
    ],
    "orderAdjustment": "System.Decimal"
}

Expected Response

The response from your external system should provide the Discount ID, Name, Scope, Target (except in cases of free items), and Impact Amount. You are responsible for calculating the impact, which tells Kibo exactly how much to discount from the order or line item. This means that the impact must be an exact value, not a percentage. Kibo will then calculate all of the tax and item totals.

Use this template to configure your responses:

[
  {
    "discountId": "System.Int32",
    "name": "System.String",
    "impactAmount": "System.Decimal",
    "target": {
      "type": "Product/Shipping/Handling",
      "lineIds": [
        1,
        2
      ],
      "groupingId": "System.String"
    },
    "scope": "LineItem/Order",
    "couponCode": "",
    "freeItem": {
       "productCode": "",
       "variationProductCode"
    },
    "rejected":
    {
       "reason": ""
    },
    "data":{
    }    
  }
]

If Kibo does not receive this response within five seconds of the request being made, then an error will occur stating that the response was not received.

Response Examples

The examples below show how the response might look for different scenarios.

{
    "discountId": "1",
    "name": "10OffOnSp_01",
    "impactAmount": "10",
    "target": {
      "type": "Product",
      "lineIds": [
        1
      ]
    },
    "scope": "LineItem",
    "couponCode": "10OFF"
  }

{
    "discountId": "2",
    "name": "5OffonSP_02",
    "impactAmount": "5",
    "target": {
      "type": "Shipping",
      "lineIds": [
        2
      ]
    },
    "scope": "LineItem",
    "couponCode": "5OFF"
  }

{
    "discountId": "3",
    "name": "50Offon200",
    "impactAmount": "50",
    "target": {
      "lineIds": [
        1,2,3
      ]
    },
    "scope": "Order"
  }

{
    "discountId": "4",
    "name": "FreeShipping",
    "impactAmount": "5",(or whatever the shipping amount is)
    "target": {
      "type": "Shipping"
    },
    "scope": "Order",
    "couponCode": "FREESHIP",
}

{
    "discountId": "5",
    "name": "7OffOnHandling",
    "impactAmount": "7",
    "target": {
      "type": "Handling"
    },
    "scope": "Order"
  }

{
    "discountId": "6",
    "name": "BSP_01GSP_2",
    "impactAmount": "10",
    "scope": "LineItem",
    "freeItem": {
       productCode: sp_02
    }
}

{
    "discountId": "7",
    "name": "10OffOnBp_01",
    "impactAmount": "10",
    "target": {
      "type": "Product",
      "lineIds":[1]
    },
    "scope": "LineItem",
    "couponCode": "10OFF",
    "data":{
      "bundle": [
        "productCode":"bp_01",
        "itemCodes":[
        "item_01"
        ]
      ]
    }
  }

{
    "discountId": "8",
    "name": "10OffOnBp_01",
    "impactAmount": "10",
    "target": {
      "type": "Product",
       "lineIds":[1]
    },
    "scope": "LineItem",
    "couponCode": "10OFF",
    "reject":{
      "reason": "This discount is not applicable"
    }
  }

Discount Requirements

Order discounts can target product, shipping, or handling while line item discounts can target product or shipping. Order handling discounts are only applied to the order handling fee, not line items. This means that if there is no order handling fee, handling discounts will not be applied.

If a line item discount does not include a free item, then the impact amount and target are required.

• If the target is product, then line item IDs should also be provided. The discount will only be applied to those items. 
• If the target is shipping, then line item IDs should also be provided. The discount will only be applied to those items.

If a line item discount includes a freeItem value, then the target is not required.

• The discount will be added to the suggestedDiscounts array of the order or cart. You must configure your logic to look at those suggestedDiscounts on the Order API or Cart API and then add the free product to the cart or order. This is the only way to add a free item while using external discounts. 

For order discounts, the impact amount is always required. 

• If the target is product, then line item IDs are optional. If they are provided, the discount will be distributed to only those items. If any line item ID is not present on the order, then the discount will not be applied. 
• If the target is shipping or handling, then line item IDs will be ignored if provided. The discount will be distributed across all Ship to Home items. 
• If you are using multiship, then a target.groupingId value is required. Each grouping in an order, quote, or checkout must have a shipping method code in order for any shipping discounts to apply. If no method is present, then shipping discounts will not be applied even if they are provided in your response. 

Discount Stacking

Product discounts may be stacked, which means that multiple discounts can be applied at the order or line item level. Kibo will recalculate their impacts based on the available order total and apply any discounts with an impact greater than $0. 

For example, if an item total is $20 and three order discounts are suggested with impact amounts of $15, $7, and $5:

• The impact of the first discount remains $15 because it can be subtracted in full from the order total, leaving a remaining total of $5.
• The impact of the second discount is recalculated from $7 to $5, because that is the maximum remaining total.
• The impact of the third discount is recalculated to $0 and will not be applied to the order.

Configure the Discount Adapter

It is recommended to contact your Kibo enablement team before creating the discount adapter, as Kibo Support may assist you with creating and installing the application. 

Create an Application

To begin creating a custom shipping integration, you will need to create an application. For more details and context, see the application documentation. 

1. In the Kibo Dev Center, under the Developer Accounts list, select your developer account.
2. Go to Develop > Applications.
3. Enter your application's name in the search bar.
4. Under the Actions column for your app, select the settings icon.
5. Select Edit.
6. On the left hand side, select Packages > Capabilities.
7. Select Add Capability.
8. Select Discount Adapter from the dropdown menu.
9. Click Ok. This displays the Configure Discount Adapter screen.
10. Enter the endpoint of your external system that Kibo should send the discount request to.
11. Click Save.

Submit Your App for Certification

If you are deploying this app to a production tenant, it must be certified to ensure that it is secure. Once you have tested the adapter, provide Kibo with the Application ID and Development account of the application. Kibo Engineering will review the adapter and perform an audit. This process usually takes about four weeks. 

Install Your App

When certified, the application can be installed on a tenant:

1. In the Dev Center, go to Develop > Applications.
2. Double click the app or click Edit from the settings icon on the far right. 
3. Click Install.
4. Select a tenant to install your application to and click OK.

Enable in Your Tenant

Finally, you must enable the application in your tenant:

1. In Admin, go to System > Customization > Applications.
2. Select the application.
3. Toggle on Enable Application.