POST

Upsell validation

https://api.kustom.co/merchant_urls.upsell_validation

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

Request body169 fields

order_idstringoptional
Unique order ID that will be used for the entire lifecycle of the order. (max 255 characters)
purchase_countrystringrequired
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_currencystringrequired
The purchase currency of the merchant’s store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.
localestringrequired
Used to define the language and region of the customer. RFC 1766 customer’s locale.
statusstringoptional
The current status of the order.
billing_addressobjectoptional
16 fields in billing_address
- given_namestringoptional
  Given name.
- family_namestringoptional
  Family name.
- organization_namestringoptional
  Organization name. Only applicable for orders with customer.type=“organization”.
- emailstringoptional
  E-mail address.
- titlestringoptional
  Title.
  Valid values for UK:
  - Mr
  - Ms
  - Mrs
  - Miss
  Valid values for DACH:
  - Herr
  - Frau
  Valid values for NL:
  - Dhr.
  - Mevr.
- street_addressstringoptional
  Street address, first line. (Street name and number)
- street_address2stringoptional
  Street address, second line. (Apartment number, suite, etc.)
- street_namestringoptional
  Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
- street_numberstringoptional
  Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
- house_extensionstringoptional
  House extension. Only applicable in NL
- postal_codestringoptional
  Postal/post code.
- citystringoptional
  City.
- regionstringoptional
  State or Region.
- phonestringoptional
  Phone number.
- countrystringoptional
  ISO 3166 alpha-2. Country.
- care_ofstringoptional
  Care of.
shipping_addressobjectoptional
Same shape as billing_address — 16 fields, identical. Anchors under this path still resolve.
16 fields in shipping_address
- given_namestringoptional
  Given name.
- family_namestringoptional
  Family name.
- organization_namestringoptional
  Organization name. Only applicable for orders with customer.type=“organization”.
- emailstringoptional
  E-mail address.
- titlestringoptional
  Title.
  Valid values for UK:
  - Mr
  - Ms
  - Mrs
  - Miss
  Valid values for DACH:
  - Herr
  - Frau
  Valid values for NL:
  - Dhr.
  - Mevr.
- street_addressstringoptional
  Street address, first line. (Street name and number)
- street_address2stringoptional
  Street address, second line. (Apartment number, suite, etc.)
- street_namestringoptional
  Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
- street_numberstringoptional
  Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
- house_extensionstringoptional
  House extension. Only applicable in NL
- postal_codestringoptional
  Postal/post code.
- citystringoptional
  City.
- regionstringoptional
  State or Region.
- phonestringoptional
  Phone number.
- countrystringoptional
  ISO 3166 alpha-2. Country.
- care_ofstringoptional
  Care of.
order_amountinteger · int64required
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_amountinteger · int64required
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.
32 fields in order_lines
- typestringoptional
  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)
- referencestringoptional
  Article number, SKU or similar. (max 255 characters)
- namestringrequired
  Descriptive name of the order line item (max 255 characters)
- quantityinteger · int64required
  Non-negative number. Quantity of the order line item.
- subscriptionobjectoptional
  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)
  3 fields in subscription
  - namestringoptional
    The name of the subscription product.
    
    Example: “Premium Account”
  - intervalstringrequired
    The cadence unit for this.
    
    Example: “DAY”
    DAY
    WEEK
    MONTH
    YEAR
  - interval_countinteger · int32required
    The number of intervals.
    
    Example: 30
- quantity_unitstringoptional
  Unit used to describe the quantity, e.g. kg, pcs… If defined has to be 1-8 characters
- unit_priceinteger · int64required
  Minor units. Includes tax, excludes discount. (max value: 100000000).
  
  Example: 100 Euros should be 10000.
- tax_rateinteger · int64required
  Non-negative value. The percentage value is represented with two implicit decimals. (max 10000)
  
  Example: 25% should be 2500.
- total_amountinteger · int64required
  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_amountinteger · int64optional
  Non-negative minor units. Includes tax.
  
  Example: 25 euros should be 2500
- total_tax_amountinteger · int64required
  Must be within ±1 of total_amount - total_amount * 10000 / (10000 + tax_rate). Negative when type is discount.
- merchant_datastringoptional
  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_urlstringoptional
  URL to the product page that can be later embedded in communications between Kustom and the customer. (max 1024 characters)
- image_urlstringoptional
  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_identifiersobjectoptional
  6 fields in product_identifiers
  - brandstringoptional
    The product’s brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
  - colorstringoptional
    Color to be shown to the end customer (max 64 characters).
  - category_pathstringoptional
    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_numberstringoptional
    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_numberstringoptional
    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
  - sizestringoptional
    Size to be shown to the end customer (max 64 characters).
- shipping_attributesobjectoptional
  7 fields in shipping_attributes
  - weightinteger · int64optional
    The product’s weight as used in the merchant’s webshop. Non-negative. Measured in grams.
  - dimensionsobjectoptional
    3 fields in dimensions
    heightinteger · int64optional
    The product’s height as used in the merchant’s webshop. Non-negative. Measured in millimeters.
    widthinteger · int64optional
    The product’s width as used in the merchant’s webshop. Non-negative. Measured in millimeters.
    lengthinteger · int64optional
    The product’s length as used in the merchant’s webshop. Non-negative. Measured in millimeters.
  - tags[]array<string>optional
    The product’s extra features, example [“dangerous_goods”, “bulky”]
  - delivery_idstringoptional
    The ID of the delivery this item belongs to. The delivery ID must be defined in the deliveries array of the order.
customerobjectoptional
5 fields in customer
- typestringoptional
  The default supported value is ‘person’. If B2B is enabled for the merchant, the value may be “organization”.
- genderstringoptional
  Customer’s gender - ‘male’ or ‘female’.
- date_of_birthstringoptional
  Customer’s date of birth. The format is ‘yyyy-mm-dd’. ISO 8601 date.
- organization_registration_idstringoptional
  “The organization’s official registration id (organization number).
  
  Note: Applicable only for B2B orders.”
- vat_idstringoptional
  Organization VAT ID. Only applies for b2b orders.
merchant_reference1stringoptional
Used for storing merchant’s internal order number or other reference. (max 255 characters).
merchant_reference2stringoptional
Used for storing merchant’s internal order number or other reference. (max 255 characters).
merchant_datastringoptional
Pass through field to send any information about the order (max 6000 characters).
selected_shipping_optionobjectoptional
52 fields in selected_shipping_option
- idstringrequired
  id
- namestringrequired
  Name.
- descriptionstringoptional
  Description.
- promostringoptional
  Promotion name. To be used if this shipping option is promotional.
- priceinteger · int64required
  Price including tax.
- preselectedbooleanoptional
  If true, this option will be preselected when checkout loads. Default: false
- tax_amountinteger · int64required
  Tax amount.
- tax_rateinteger · int64required
  Non-negative. In percent, two implicit decimals. I.e 2500 = 25%.
- shipping_methodstringoptional
  Shipping method. Possible values:
  - PickUpStore
  - Home
  - BoxReg
  - BoxUnreg
  - PickUpPoint
  - Own
  - Postal
  - DHLPackstation
  - Digital
  If DHLPackstation is selected the correct form will be displayed.
- delivery_detailsobjectoptional
  33 fields in delivery_details
  - carrierstringoptional
    Carrier product name
  - classstringoptional
    Type of shipping class
  - productobjectoptional
    6 fields in product
    namestringoptional
    Carrier product name
    identifierstringoptional
    Carrier product identifier
    external_idstringoptional
    The external identifier of the carrier
    product_namestringoptional
    The product or service level name provided by the carrier
    metaobjectoptional
    Carrier-specific metadata
    1 field in meta
    keystringoptional
    Any additional property. The key is free-form; the value has this shape.
  - timeslotobjectoptional
    3 fields in timeslot
    idstringoptional
    Id
    startstringoptional
    Start time
    endstringoptional
    End time
  - pickup_locationobjectoptional
    19 fields in pickup_location
    idstringoptional
    Id
    namestringoptional
    Name of the location
    addressobjectoptional
    16 fields in address
    given_namestringoptional
    Given name.
    family_namestringoptional
    Family name.
    organization_namestringoptional
    Organization name. Only applicable for orders with customer.type=“organization”.
    emailstringoptional
    E-mail address.
    titlestringoptional
    Title.
    Valid values for UK:
    Mr
    Ms
    Mrs
    Miss
    Valid values for DACH:
    Herr
    Frau
    Valid values for NL:
    Dhr.
    Mevr.
    street_addressstringoptional
    Street address, first line. (Street name and number)
    street_address2stringoptional
    Street address, second line. (Apartment number, suite, etc.)
    street_namestringoptional
    Street name. Only applicable in DE/AT/NL. Do not combine with street_address. See streetNumber.
    street_numberstringoptional
    Street number. Only applicable in DE/AT/NL. Do not combine with street_address. See streetName.
    house_extensionstringoptional
    House extension. Only applicable in NL
    postal_codestringoptional
    Postal/post code.
    citystringoptional
    City.
    regionstringoptional
    State or Region.
    phonestringoptional
    Phone number.
    countrystringoptional
    ISO 3166 alpha-2. Country.
    care_ofstringoptional
    Care of.
- tms_referencestringoptional
  TMS reference. Required to map completed orders to shipments reserved in TMS.
- tos_idstringoptional
  TOS ID. Required to map completed orders to shipments reserved via Ingrid.
- selected_addons[]array<object>optional
  5 fields in selected_addons
  - typestringoptional
  - priceinteger · int64optional
  - external_idstringoptional
  - user_inputstringoptional
  - display_namestringoptional
- external_method_idstringoptional
  The external identifier defined on the TMS (Only applicable for Ingrid-Headless)
upsell_order_lines[]array<object>optional
The list of upsell order lines requested to be added to the order.
Same shape as order_lines — 32 fields, identical. Anchors under this path still resolve.
32 fields in upsell_order_lines
- typestringoptional
  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)
- referencestringoptional
  Article number, SKU or similar. (max 255 characters)
- namestringrequired
  Descriptive name of the order line item (max 255 characters)
- quantityinteger · int64required
  Non-negative number. Quantity of the order line item.
- subscriptionobjectoptional
  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)
  3 fields in subscription
  - namestringoptional
    The name of the subscription product.
    
    Example: “Premium Account”
  - intervalstringrequired
    The cadence unit for this.
    
    Example: “DAY”
    DAY
    WEEK
    MONTH
    YEAR
  - interval_countinteger · int32required
    The number of intervals.
    
    Example: 30
- quantity_unitstringoptional
  Unit used to describe the quantity, e.g. kg, pcs… If defined has to be 1-8 characters
- unit_priceinteger · int64required
  Minor units. Includes tax, excludes discount. (max value: 100000000).
  
  Example: 100 Euros should be 10000.
- tax_rateinteger · int64required
  Non-negative value. The percentage value is represented with two implicit decimals. (max 10000)
  
  Example: 25% should be 2500.
- total_amountinteger · int64required
  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_amountinteger · int64optional
  Non-negative minor units. Includes tax.
  
  Example: 25 euros should be 2500
- total_tax_amountinteger · int64required
  Must be within ±1 of total_amount - total_amount * 10000 / (10000 + tax_rate). Negative when type is discount.
- merchant_datastringoptional
  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_urlstringoptional
  URL to the product page that can be later embedded in communications between Kustom and the customer. (max 1024 characters)
- image_urlstringoptional
  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_identifiersobjectoptional
  6 fields in product_identifiers
  - brandstringoptional
    The product’s brand name as generally recognized by consumers. If no brand is available for a product, do not supply any value.
  - colorstringoptional
    Color to be shown to the end customer (max 64 characters).
  - category_pathstringoptional
    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_numberstringoptional
    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_numberstringoptional
    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
  - sizestringoptional
    Size to be shown to the end customer (max 64 characters).
- shipping_attributesobjectoptional
  7 fields in shipping_attributes
  - weightinteger · int64optional
    The product’s weight as used in the merchant’s webshop. Non-negative. Measured in grams.
  - dimensionsobjectoptional
    3 fields in dimensions
    heightinteger · int64optional
    The product’s height as used in the merchant’s webshop. Non-negative. Measured in millimeters.
    widthinteger · int64optional
    The product’s width as used in the merchant’s webshop. Non-negative. Measured in millimeters.
    lengthinteger · int64optional
    The product’s length as used in the merchant’s webshop. Non-negative. Measured in millimeters.
  - tags[]array<string>optional
    The product’s extra features, example [“dangerous_goods”, “bulky”]
  - delivery_idstringoptional
    The ID of the delivery this item belongs to. The delivery ID must be defined in the deliveries array of the order.

200

Response0 fields

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

No response body — this status returns headers only.

400

Response0 fields

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

No response body — this status returns headers only.

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

Request body· application/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>"
      }
    }
  ]
}

202 lines

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.