# Upsell validation

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

Will be called before updating the purchase with upsell order lines to validate the upsell.

## Request body

`application/json`

- `order_id` (string) — Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
- `purchase_country` (string, required) — The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc.
- `purchase_currency` (string, required) — The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.
- `locale` (string, required) — Used to define the language and region of the customer. RFC 1766 customer's locale.
- `status` (string) — The current status of the order.
- `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`.
- `order_amount` (integer, required) — Total amount of the order including tax and any available discounts. The value should be in non-negative minor units.

  Example: 25 Euros should be 2500.
- `order_tax_amount` (integer, required) — Total tax amount of the order. The value should be in non-negative minor units.

  Example: 25 Euros should be 2500.
- `order_lines[]` (array<object>, required) — An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.
  - `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.
- `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.
- `merchant_reference1` (string) — Used for storing merchant's internal order number or other reference. (max 255 characters).
- `merchant_reference2` (string) — Used for storing merchant's internal order number or other reference. (max 255 characters).
- `merchant_data` (string) — Pass through field to send any information about the order (max 6000 characters).
- `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)
- `upsell_order_lines[]` (array<object>) — The list of upsell order lines requested to be added to the order. Same shape as `order_lines`.

### Example request

```json
{
  "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  "purchase_country": "US",
  "purchase_currency": "USD",
  "locale": "en-US",
  "status": "CHECKOUT_COMPLETE",
  "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"
  },
  "order_amount": 50000,
  "order_tax_amount": 4545,
  "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>"
      }
    }
  ],
  "customer": {
    "type": "person",
    "gender": "male",
    "date_of_birth": "1995-10-20",
    "organization_registration_id": "556737-0431",
    "vat_id": "<string>"
  },
  "merchant_reference1": "45aa52f387871e3a210645d4",
  "merchant_reference2": "45aa52f387871e3a210645d4",
  "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "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"
  },
  "upsell_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>"
      }
    }
  ]
}
```

## Responses

### 200

Upsell is approved. The order will be updated with upsell order lines.

### 400

Upsell is declined. The order will not be updated with upsell order lines.