# Upsell recommendations

> `POST https://api.kustom.co/merchant_urls.upsell`

Will be called when upsell recommendations are to be fetched on the confirmation page, to present upsell options for the consumer.

## Request body

`application/json`

- `upsell_possible` (boolean, required) — Specifies if upselling is possible for this order.
- `max_upsell_amount` (integer, required) — Non-negative, the maximum amount that can be upsold.
- `billing_address` (object)
  - `given_name` (string) — Given name.
  - `family_name` (string) — Family name.
  - `organization_name` (string) — Organization name. Only applicable for orders with customer.type="organization".
  - `email` (string) — E-mail address.
  - `title` (string) — Title.
    Valid values for UK:

    - *Mr*
    - *Ms*
    - *Mrs*
    - *Miss*

    Valid values for DACH:

    - *Herr*
    - *Frau*

    Valid values for NL:

    - *Dhr.*
    - *Mevr.*
  - `street_address` (string) — Street address, first line. (Street name and number)
  - `street_address2` (string) — Street address, second line. (Apartment number, suite, etc.)
  - `street_name` (string) — Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See **streetNumber**.
  - `street_number` (string) — Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See **streetName**.
  - `house_extension` (string) — House extension. Only applicable in NL
  - `postal_code` (string) — Postal/post code.
  - `city` (string) — City.
  - `region` (string) — State or Region.
  - `phone` (string) — Phone number.
  - `country` (string) — ISO 3166 alpha-2. Country.
  - `care_of` (string) — Care of.
- `shipping_address` (object) Same shape as `billing_address`.
- `customer` (object)
  - `type` (string) — The default supported value is 'person'. If B2B is enabled for the merchant, the value may be "organization".
  - `gender` (string) — Customer’s gender - ‘male’ or ‘female’.
  - `date_of_birth` (string) — Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
  - `organization_registration_id` (string) — "The organization's official registration id (organization number).

    Note: Applicable only for B2B orders."
  - `vat_id` (string) — Organization VAT ID. Only applies for b2b orders.
- `order_lines[]` (array<object>)
  - `type` (string) — Type of the order line item. The possible values are:

    - *physical (physical good)*
    - *discount*
    - *shipping_fee*
    - *sales_tax (depends on the country/city, usually called VAT)*
    - *digital (digital good)*
    - *gift_card*
    - *store_credit (credit from the merchant)*
    - *surcharge (extra charge)*
  - `reference` (string) — Article number, SKU or similar. (max 255 characters)
  - `name` (string, required) — Descriptive name of the order line item (max 255 characters)
  - `quantity` (integer, required) — Non-negative number. Quantity of the order line item.
  - `subscription` (object) — Describes the subscription.
    Including subscription details will also change the buy button to inform the user that they will be subscribing.
    (Only applicable for recurring orders)
    - `name` (string) — The name of the subscription product.

      Example: "Premium Account"
    - `interval` (string, required) — The cadence unit for this.

      Example: "DAY"
      Enum: `DAY`, `WEEK`, `MONTH`, `YEAR`.
    - `interval_count` (integer, required) — The number of intervals.

      Example: 30
  - `quantity_unit` (string) — Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
  - `unit_price` (integer, required) — Minor units. Includes tax, excludes discount. (max value: 100000000).

    Example: 100 Euros should be 10000.
  - `tax_rate` (integer, required) — Non-negative value. The percentage value is represented with two implicit decimals. (max 10000)

    Example: 25% should be 2500.
  - `total_amount` (integer, required) — Minor units. Includes tax and discount.

    Example: 25 euros should be 2500
    Value = (quantity x unit_price) - total_discount_amount.
    (max value: 100000000)
  - `total_discount_amount` (integer) — Non-negative minor units. Includes tax.

    Example: 25 euros should be 2500
  - `total_tax_amount` (integer, required) — Must be within ±1 of total_amount - total_amount \* 10000 / (10000 + tax_rate). Negative when type is discount.
  - `merchant_data` (string) — Property used to store additional metadata per item that will be returned whenever an order is read from Kustom. Pass through field. (max 1024 characters).
  - `product_url` (string) — URL to the product page that can be later embedded in communications between Kustom and the customer. (max 1024 characters)
  - `image_url` (string) — URL to an image that can be later embedded in communications between Kustom and the customer. (max 1024 characters)

    Improves post-purchase customer experiences.
  - `product_identifiers` (object)
    - `brand` (string) — The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
    - `color` (string) — Color to be shown to the end customer (max 64 characters).
    - `category_path` (string) — The product's category path as used in the merchant's webshop. Include the full and most detailed category and separate the segments with ' > '. (max 750 characters)

      Example: "Electronics Store > Computers & Tablets > Desktops"
    - `global_trade_item_number` (string) — The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
    - `manufacturer_part_number` (string) — The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
    - `size` (string) — Size to be shown to the end customer (max 64 characters).
  - `shipping_attributes` (object)
    - `weight` (integer) — The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
    - `dimensions` (object)
      - `height` (integer) — The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
      - `width` (integer) — The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
      - `length` (integer) — The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
    - `tags[]` (array<string>) — The product's extra features, example ["dangerous_goods", "bulky"]
    - `delivery_id` (string) — The ID of the delivery this item belongs to. The delivery ID must be defined in the `deliveries` array of the order.
- `selected_shipping_option` (object)
  - `id` (string, required) — id
  - `name` (string, required) — Name.
  - `description` (string) — Description.
  - `promo` (string) — Promotion name. To be used if this shipping option is promotional.
  - `price` (integer, required) — Price including tax.
  - `preselected` (boolean) — If true, this option will be preselected when checkout loads. Default: false
  - `tax_amount` (integer, required) — Tax amount.
  - `tax_rate` (integer, required) — Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
  - `shipping_method` (string) — Shipping method. Possible values:

    - PickUpStore
    - Home
    - BoxReg
    - BoxUnreg
    - PickUpPoint
    - Own
    - Postal
    - DHLPackstation
    - Digital
     If DHLPackstation is selected the correct form will be displayed.
  - `delivery_details` (object)
    - `carrier` (string) — Carrier product name
    - `class` (string) — Type of shipping class
    - `product` (object)
      - `name` (string) — Carrier product name
      - `identifier` (string) — Carrier product identifier
      - `external_id` (string) — The external identifier of the carrier
      - `product_name` (string) — The product or service level name provided by the carrier
      - `meta` (object) — Carrier-specific metadata
        - `key` (string) — Any additional property. The key is free-form; the value has this shape.
    - `timeslot` (object)
      - `id` (string) — Id
      - `start` (string) — Start time
      - `end` (string) — End time
    - `pickup_location` (object)
      - `id` (string) — Id
      - `name` (string) — Name of the location
      - `address` (object)
        - `given_name` (string) — Given name.
        - `family_name` (string) — Family name.
        - `organization_name` (string) — Organization name. Only applicable for orders with customer.type="organization".
        - `email` (string) — E-mail address.
        - `title` (string) — Title.
          Valid values for UK:

          - *Mr*
          - *Ms*
          - *Mrs*
          - *Miss*

          Valid values for DACH:

          - *Herr*
          - *Frau*

          Valid values for NL:

          - *Dhr.*
          - *Mevr.*
        - `street_address` (string) — Street address, first line. (Street name and number)
        - `street_address2` (string) — Street address, second line. (Apartment number, suite, etc.)
        - `street_name` (string) — Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See **streetNumber**.
        - `street_number` (string) — Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See **streetName**.
        - `house_extension` (string) — House extension. Only applicable in NL
        - `postal_code` (string) — Postal/post code.
        - `city` (string) — City.
        - `region` (string) — State or Region.
        - `phone` (string) — Phone number.
        - `country` (string) — ISO 3166 alpha-2. Country.
        - `care_of` (string) — Care of.
  - `tms_reference` (string) — TMS reference. Required to map completed orders to shipments reserved in TMS.
  - `tos_id` (string) — TOS ID. Required to map completed orders to shipments reserved via Ingrid.
  - `selected_addons[]` (array<object>)
    - `type` (string)
    - `price` (integer)
    - `external_id` (string)
    - `user_input` (string)
    - `display_name` (string)
  - `external_method_id` (string) — The external identifier defined on the TMS (Only applicable for Ingrid-Headless)
- `purchase_currency` (string) — ISO 4217 purchase currency.
- `locale` (string) — RFC 1766 customer's locale.
- `merchant_id` (string)
- `session_id` (string)
- `merchant_reference1` (string)
- `selected_shipping_options[]` (array<object>) Same shape as `selected_shipping_option`.

### Example request

```json
{
  "upsell_possible": false,
  "max_upsell_amount": 0,
  "billing_address": {
    "given_name": "John",
    "family_name": "Doe",
    "organization_name": "Acme Corporation",
    "email": "john@doe.com",
    "title": "Mr",
    "street_address": "Lombard St 10",
    "street_address2": "Apt 214",
    "street_name": "Lombard St",
    "street_number": "10",
    "house_extension": "B",
    "postal_code": "90210",
    "city": "Beverly Hills",
    "region": "CA",
    "phone": "333444555",
    "country": "US",
    "care_of": "C/O"
  },
  "shipping_address": {
    "given_name": "John",
    "family_name": "Doe",
    "organization_name": "Acme Corporation",
    "email": "john@doe.com",
    "title": "Mr",
    "street_address": "Lombard St 10",
    "street_address2": "Apt 214",
    "street_name": "Lombard St",
    "street_number": "10",
    "house_extension": "B",
    "postal_code": "90210",
    "city": "Beverly Hills",
    "region": "CA",
    "phone": "333444555",
    "country": "US",
    "care_of": "C/O"
  },
  "customer": {
    "type": "person",
    "gender": "male",
    "date_of_birth": "1995-10-20",
    "organization_registration_id": "556737-0431",
    "vat_id": "<string>"
  },
  "order_lines": [
    {
      "type": "physical",
      "reference": "19-402-USA",
      "name": "Red T-Shirt",
      "quantity": 5,
      "subscription": {
        "name": "<string>",
        "interval": "DAY",
        "interval_count": 0
      },
      "quantity_unit": "pcs",
      "unit_price": 10000,
      "tax_rate": 1000,
      "total_amount": 50000,
      "total_discount_amount": 0,
      "total_tax_amount": 4545,
      "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
      "product_url": "https://www.example.com/products/f2a8d7e34",
      "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
      "product_identifiers": {
        "brand": "Intel",
        "color": "Blue",
        "category_path": "Electronics Store > Computers & Tablets > Desktops",
        "global_trade_item_number": "735858293167",
        "manufacturer_part_number": "BOXNUC5CPYH",
        "size": "Medium"
      },
      "shipping_attributes": {
        "weight": 1000,
        "dimensions": {
          "height": 100,
          "width": 100,
          "length": 100
        },
        "tags": [
          "<string>"
        ],
        "delivery_id": "<string>"
      }
    }
  ],
  "selected_shipping_option": {
    "id": "express_priority",
    "name": "EXPRESS 1-2 Days",
    "description": "Delivery by 4:30 pm",
    "promo": "Christmas Promotion",
    "price": 0,
    "preselected": false,
    "tax_amount": 0,
    "tax_rate": 0,
    "shipping_method": "PickUpStore",
    "delivery_details": {
      "carrier": "<string>",
      "class": "<string>",
      "product": {
        "name": "<string>",
        "identifier": "<string>",
        "external_id": "<string>",
        "product_name": "Parcel",
        "meta": {
          "key": "<string>"
        }
      },
      "timeslot": {
        "id": "<string>",
        "start": "<string>",
        "end": "<string>"
      },
      "pickup_location": {
        "id": "<string>",
        "name": "<string>",
        "address": {
          "given_name": "John",
          "family_name": "Doe",
          "organization_name": "Acme Corporation",
          "email": "john@doe.com",
          "title": "Mr",
          "street_address": "Lombard St 10",
          "street_address2": "Apt 214",
          "street_name": "Lombard St",
          "street_number": "10",
          "house_extension": "B",
          "postal_code": "90210",
          "city": "Beverly Hills",
          "region": "CA",
          "phone": "333444555",
          "country": "US",
          "care_of": "C/O"
        }
      }
    },
    "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
    "tos_id": "01K7HJZHY22AAX6PNV5DPXNZQF",
    "selected_addons": [
      {
        "type": "<string>",
        "price": 0,
        "external_id": "<string>",
        "user_input": "<string>",
        "display_name": "<string>"
      }
    ],
    "external_method_id": "dhl-parcelconnect-fr"
  },
  "purchase_currency": "USD",
  "locale": "en-US",
  "merchant_id": "<string>",
  "session_id": "<string>",
  "merchant_reference1": "<string>",
  "selected_shipping_options": [
    {
      "id": "express_priority",
      "name": "EXPRESS 1-2 Days",
      "description": "Delivery by 4:30 pm",
      "promo": "Christmas Promotion",
      "price": 0,
      "preselected": false,
      "tax_amount": 0,
      "tax_rate": 0,
      "shipping_method": "PickUpStore",
      "delivery_details": {
        "carrier": "<string>",
        "class": "<string>",
        "product": {
          "name": "<string>",
          "identifier": "<string>",
          "external_id": "<string>",
          "product_name": "Parcel",
          "meta": {
            "key": "<string>"
          }
        },
        "timeslot": {
          "id": "<string>",
          "start": "<string>",
          "end": "<string>"
        },
        "pickup_location": {
          "id": "<string>",
          "name": "<string>",
          "address": {
            "given_name": "John",
            "family_name": "Doe",
            "organization_name": "Acme Corporation",
            "email": "john@doe.com",
            "title": "Mr",
            "street_address": "Lombard St 10",
            "street_address2": "Apt 214",
            "street_name": "Lombard St",
            "street_number": "10",
            "house_extension": "B",
            "postal_code": "90210",
            "city": "Beverly Hills",
            "region": "CA",
            "phone": "333444555",
            "country": "US",
            "care_of": "C/O"
          }
        }
      },
      "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
      "tos_id": "01K7HJZHY22AAX6PNV5DPXNZQF",
      "selected_addons": [
        {
          "type": "<string>",
          "price": 0,
          "external_id": "<string>",
          "user_input": "<string>",
          "display_name": "<string>"
        }
      ],
      "external_method_id": "dhl-parcelconnect-fr"
    }
  ]
}
```

## Responses

### 200

Upsell recommendations returned successfully.

`application/json`

- `last_upsell_time` (string) — ISO 8601 datetime. When the upsell window expires. The format will be as follows:
  "yyyy-mm-ddThh:mm:ssZ"
- `upsell_lines[]` (array<object>, required) — List of upsell lines that will be displayed.
  - `type` (string) — Type of the order line item. The possible values are:

    - *physical (physical good)*
    - *discount*
    - *shipping_fee*
    - *sales_tax (depends on the country/city, usually called VAT)*
    - *digital (digital good)*
    - *gift_card*
    - *store_credit (credit from the merchant)*
    - *surcharge (extra charge)*
  - `reference` (string) — Article number, SKU or similar. (max 255 characters)
  - `name` (string, required) — Descriptive name of the order line item (max 255 characters)
  - `quantity` (integer, required) — Non-negative number. Default offered quantity of the upsell line item.
  - `description` (string) — Description for the upsell item. (max 1024 characters)
  - `quantity_unit` (string) — Unit used to describe the quantity, e.g. kg, pcs... If defined has to be 1-8 characters
  - `unit_price` (integer, required) — Minor units. Includes tax, excludes discount. (max value: 100000000).

    Example: 100 Euros should be 10000.
  - `tax_rate` (integer, required) — Non-negative value. The percentage value is represented with two implicit decimals. (max 10000)

    Example: 25% should be 2500.
  - `total_amount` (integer, required) — Minor units. Includes tax and discount.

    Example: 25 euros should be 2500
    Value = (quantity x unit_price) - total_discount_amount.
    (max value: 100000000)
  - `total_discount_amount` (integer) — Non-negative minor units. Includes tax.

    Example: 25 euros should be 2500
  - `total_tax_amount` (integer, required) — Must be within ±1 of total_amount - total_amount \* 10000 / (10000 + tax_rate). Negative when type is discount.
  - `merchant_data` (string) — Property used to store additional metadata per item that will be returned whenever an order is read from Kustom. Pass through field. (max 1024 characters).
  - `product_url` (string) — URL to the product page that can be later embedded in communications between Kustom and the customer. (max 1024 characters)
  - `image_url` (string) — URL to an image that can be later embedded in communications between Kustom and the customer. (max 1024 characters)

    Improves post-purchase customer experiences.
  - `product_identifiers` (object)
    - `brand` (string) — The product's brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
    - `color` (string) — Color to be shown to the end customer (max 64 characters).
    - `category_path` (string) — The product's category path as used in the merchant's webshop. Include the full and most detailed category and separate the segments with ' > '. (max 750 characters)

      Example: "Electronics Store > Computers & Tablets > Desktops"
    - `global_trade_item_number` (string) — The product's Global Trade Item Number (GTIN). Common types of GTIN are EAN, ISBN or UPC. Exclude dashes and spaces, where possible
    - `manufacturer_part_number` (string) — The product's Manufacturer Part Number (MPN), which - together with the brand - uniquely identifies a product. Only submit MPNs assigned by a manufacturer and use the most specific MPN possible
    - `size` (string) — Size to be shown to the end customer (max 64 characters).
  - `shipping_attributes` (object)
    - `weight` (integer) — The product's weight as used in the merchant's webshop. Non-negative. Measured in grams.
    - `dimensions` (object)
      - `height` (integer) — The product's height as used in the merchant's webshop. Non-negative. Measured in millimeters.
      - `width` (integer) — The product's width as used in the merchant's webshop. Non-negative. Measured in millimeters.
      - `length` (integer) — The product's length as used in the merchant's webshop. Non-negative. Measured in millimeters.
    - `tags[]` (array<string>) — The product's extra features, example ["dangerous_goods", "bulky"]
    - `delivery_id` (string) — The ID of the delivery this item belongs to. The delivery ID must be defined in the `deliveries` array of the order.
  - `max_allowed_quantity` (integer, required) — Non-negative number. Maximum allowed quantity of the upsell line items.
  - `feedback_url` (string) — URL for the upsell feedback for the item. (max 1024 characters)
  - `variants[]` (array<object>) — List of product variants available for this upsell item.
    - `attributes` (object, required) — Key-value pairs describing variant attributes, e.g. {"color": "red", "size": "M"}.
      - `key` (string) — Any additional property. The key is free-form; the value has this shape.
    - `brand` (string) — Brand name of the variant.
    - `category` (string) — Category of the variant.
    - `image_url` (string) — URL of the variant product image.
    - `name` (string) — Display name of the variant.
    - `product_url` (string) — URL of the variant product page.
    - `sale_price` (integer) — Total price of the variant including tax in minor units.
    - `sku` (string, required) — Stock keeping unit identifier for this variant.
    - `total_discount_amount` (integer) — Total discount amount of the variant in minor units.
    - `unit_price` (integer) — Unit price of the variant in minor units.
  - `subscription` (object) — Describes the subscription.
    Including subscription details will also change the buy button to inform the user that they will be subscribing.
    (Only applicable for recurring orders)
    - `name` (string) — The name of the subscription product.

      Example: "Premium Account"
    - `interval` (string, required) — The cadence unit for this.

      Example: "DAY"
      Enum: `DAY`, `WEEK`, `MONTH`, `YEAR`.
    - `interval_count` (integer, required) — The number of intervals.

      Example: 30
- `notification_uri` (string) — URL for notifications on pending orders. (max 2000 characters)
  Example: "https://merchant.com/notification/{checkout.order.id}"
- `empty` (boolean) — Signal no upsell without returning lines.

```json
{
  "last_upsell_time": "<date-time>",
  "upsell_lines": [
    {
      "type": "physical",
      "reference": "19-402-USA",
      "name": "Red T-Shirt",
      "quantity": 1,
      "description": "<string>",
      "quantity_unit": "pcs",
      "unit_price": 10000,
      "tax_rate": 1000,
      "total_amount": 10000,
      "total_discount_amount": 0,
      "total_tax_amount": 4545,
      "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
      "product_url": "https://www.example.com/products/f2a8d7e34",
      "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
      "product_identifiers": {
        "brand": "Intel",
        "color": "Blue",
        "category_path": "Electronics Store > Computers & Tablets > Desktops",
        "global_trade_item_number": "735858293167",
        "manufacturer_part_number": "BOXNUC5CPYH",
        "size": "Medium"
      },
      "shipping_attributes": {
        "weight": 1000,
        "dimensions": {
          "height": 100,
          "width": 100,
          "length": 100
        },
        "tags": [
          "<string>"
        ],
        "delivery_id": "<string>"
      },
      "max_allowed_quantity": 5,
      "feedback_url": "https://www.example.com/api/upsell/KDL-32BX330",
      "variants": [
        {
          "attributes": {
            "key": "<string>"
          },
          "brand": "<string>",
          "category": "<string>",
          "image_url": "<string>",
          "name": "<string>",
          "product_url": "<string>",
          "sale_price": 0,
          "sku": "<string>",
          "total_discount_amount": 0,
          "unit_price": 0
        }
      ],
      "subscription": {
        "name": "<string>",
        "interval": "DAY",
        "interval_count": 0
      }
    }
  ],
  "notification_uri": "https://www.example.com/api/notification/{checkout.order.id}",
  "empty": false
}
```