alt

Important information

There was an update of Unzer TLS/SSL certificates. Learn more

Unzer
search

    Marketplace basket

    Learn about marketplace baskets and adding product information with it.

    Overview

    The marketplace basket API specifies the details of the checkout information for a payment initialized via an marketplace operator. Some details include basket item descriptions, unit prices, discount information and risk scoring related data.

    Marketplace basket contains all the fields that are required for a creating a basket and additionally a marketplace participant ID.

    Once you have created a basket, it cannot be deleted. To learn more about basket API, go to API reference guide.

    Supported Payment methods

    The marketplace basket type supports all payment methods listed in Payment methods supported.

    Create a marketplace basket

    To create a basket, send a POST request to the basket API. Note that you cannot change or replace a basket once it is associated with a charge or authorization.

    POST https://api.unzer.com/v2/marketplace/baskets
{
  "totalValueGross": 110.00,
  "orderId": "{{randomOrderId}}",
  "currencyCode": "EUR",
  "basketItems": [
    {
      "type": "goods",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "unit": "pc.c",
      "amountPerUnitGross": 30,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 1 Macbook pro",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "type": "goods",
      "basketItemReferenceId": "item-4",
      "quantity": 3,
      "unit": "pc.c",
      "amountPerUnitGross": 10,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 1 Macbook pro",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "type": "goods",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "unit": "pc.c",
      "amountPerUnitGross": 20,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 2",
      "participantId": "31HA07BC814FC247577B309FF031D3F0"
    },
    {
      "type": "goods",
      "basketItemReferenceId": "item-3",
      "quantity": 2,
      "unit": "pc.c",
      "amountPerUnitGross": 15,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 3 Macbook pro",
      "participantId": "31HA07BC814FC247577B4BBF6E182F91"
    }
  ]
}
    Parameter Type Validation Description
    currencyCode (required) string N Currency code in ISO_4217 format
    orderId string N Specify the unique orderID. It is used for authorizing or charging the transaction for this specific basket.
    If no value is provided, an order ID is automatically generated by the Unzer system.
    totalValueGross number Y The total basket value (including VAT) of all basket items deducted after deducting all discounts.
    basketItems object
    title (required) string N Title of the basket item
    basketItemReferenceId string N Unique basket item reference ID (within the basket). If not provided, an ID is automatically generated by Unzer.
    quantity (required) number N Quantity of the basket item
    amountPerUnitGross (required) number N Amount per unit including VAT
    vat (required) number N The VAT value for the basket item in percentage
    subTitle string N The subtitle for the basket item
    type (required) string N The type of item in the basket. The valid values are goods, voucher, and shipment.
    unit string N The measuring unit for the basket item.
    participantId (required) string N The ID of the seller for your marketplace

    A basket is created with a unique ID. This ID is required for the payment workflow.

    {
   "id": "s-bsk-12a61c0e7c8e"
}

    Review basket details

    To review the details of a basket, send a GET request for the specific basket ID.

    GET https://api.unzer.com/v2/marketplace/baskets/{{basket_id}}

{
  "id": "s-bsk-12a61c0e7c8e",
  "totalValueGross": "110.0000",
  "currencyCode": "EUR",
  "orderId": "1651567316-138",
  "basketItems": [
      {
        "basketItemReferenceId": "item-1",
        "quantity": "1",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "30.0000",
        "title": "Participant 1 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B195E59A99FC6"
      },
      {
        "basketItemReferenceId": "item-4",
        "quantity": "3",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "10.0000",
        "title": "Participant 1 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B195E59A99FC6"
      },
      {
        "basketItemReferenceId": "item-2",
        "quantity": "1",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "20.0000",
        "title": "Participant 2",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B309FF031D3F0"
      },
      {
        "basketItemReferenceId": "item-3",
        "quantity": "2",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "15.0000",
        "title": "Participant 3 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B4BBF6E182F91"
      }
  ]
}

    Update a marketplace basket

    To update a basket, send a PUT request to the basket API. You cannot update the basket ID once it is created. You can only update the basket item details. For example, in our previous request, if we want to give a discount of 10 EUR, you can update the basket as shown in the following example.

    
PUT https://api.unzer.com/v2/marketplace/baskets/{{basket_id}}

{
  "id": "{{randomUUID}}",
  "orderId": "{{randomOrderId}}",
  "totalValueGross": "100.0000",
  "currencyCode": "EUR",
  "basketItems": [
      {
        "basketItemReferenceId": "item-1",
        "quantity": "1",
        "vat": "0",
        "amountDiscountPerUnitGross": "10.0000",
        "amountPerUnitGross": "30.0000",
        "title": "Participant 1 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B195E59A99FC6"
      },
      {
        "basketItemReferenceId": "item-4",
        "quantity": "3",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "10.0000",
        "title": "Participant 1 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B195E59A99FC6"
      },
      {
        "basketItemReferenceId": "item-2",
        "quantity": "1",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "20.0000",
        "title": "Participant 2",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B309FF031D3F0"
      },
      {
        "basketItemReferenceId": "item-3",
        "quantity": "2",
        "vat": "0",
        "amountDiscountPerUnitGross": "0.0000",
        "amountPerUnitGross": "15.0000",
        "title": "Participant 3 Macbook pro",
        "type": "goods",
        "unit": "pc.c",
        "subTitle": "Macbook pro 2021",
        "participantId": "31HA07BC814FC247577B4BBF6E182F91"
      }
  ]
}

    
{
  "id": "s-bsk-12a61c0e7c8e"
}

    Use cases

    The following use cases explain the various scenarios for using the marketplace API endpoint.

    Add shipping costs

    To provide shipment costs you can add a basket item with item.type shipments as shown in the following example.

    {
  "currencyCode": "EUR",
  "orderId": "{{randomOrderId}}",
  "totalValueGross":195.90,
  "note": "basket note",
  "basketItems": [
    {
      "title": "Macbook pro",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "amountPerUnitGross": 200.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 1,
      "unit": "pc",
      "subTitle": "basket item 2",
      "type": "goods",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "title": "Shipment costs",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 5.90,
      "vat": 1,
      "subTitle": "Insured standard shipment",
      "type": "shipments",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    }
  ]
}

    Provide basket items with discounts

    To provide discounted items you can add the parameter amountDiscountPerUnitGross and the absolute discount amount per unit to an basket item as shown in the following example.

    {
  "currencyCode": "EUR",
  "orderId": "{{randomOrderId}}",
  "totalValueGross":190.00,
  "note": "basket note",
  "basketItems": [
    {
      "title": "Macbook pro",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "amountPerUnitGross": 200.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 0,
      "unit": "pc",
      "subTitle": "basket item 2",
      "type": "goods",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    }
  ]
}

    Provide vouchers

    To add a voucher to your basket, you can add a basket item with item.type voucher as shown in the following example.

    Calculating voucher amount

    A basket item is considered as a voucher if item.type == voucher && item.amountPerUnitGross == 0 && item.amountDiscountPerUnitGross > 0

    {
  "currencyCode": "EUR",
  "orderId": "{{randomOrderId}}",
  "totalValueGross":190.00,
  "note": "basket note",
  "basketItems": [
    {
      "title": "Macbook pro",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "amountPerUnitGross": 200.00,
      "vat": 0,
      "unit": "pc",
      "subTitle": "basket item 2",
      "type": "goods",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "title": "10 EUR voucher newsletter registration",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 0.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 0,
      "type": "voucher",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    }
  ]
}

    Combining all basket items types in one basket

    Combining all use cases in one basket will look as shown in the example below.

    {
  "totalValueGross": 60.00,
  "orderId": "{{randomOrderId}}",
  "currencyCode": "EUR",
  "basketItems": [
    {
      "type": "goods",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "unit": "pc.c",
      "amountPerUnitGross": 30,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 1 Macbook pro",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "type": "voucher",
      "basketItemReferenceId": "item-4",
      "quantity": 1,
      "unit": "pc.c",
      "amountPerUnitGross": 0,
      "amountDiscountPerUnitGross": "10",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Voucher for newsletter subscription",
      "participantId": "31HA07BC814FC247577B195E59A99FC6"
    },
    {
      "type": "shipment",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "unit": "pc.c",
      "amountPerUnitGross": 10,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Shipment cost",
      "participantId": "31HA07BC814FC247577B4BBF6E182F91"
    },
    {
      "type": "goods",
      "basketItemReferenceId": "item-3",
      "quantity": 2,
      "unit": "pc.c",
      "amountPerUnitGross": 15,
      "amountDiscountPerUnitGross": "0",
      "subTitle": "Macbook pro 2021",
      "vat": "0",
      "title": "Participant 3 Macbook pro",
      "participantId": "31HA07BC814FC247577B4BBF6E182F91"
    }
  ]
}

    A basket ID is generated in the response.

    Validating a basket

    When creating or updating a basket there are several validations which have to be considered:

    totalValueGross

    • must be > 0.00
    • must be equal to the amount provided in the authorize and charges calls
    • is calculated as follows:
      • totalValueGross = basketItems.sum(( item.amountPerUnitGross - item.amountDiscountPerUnitGross)* item.quantity )

    amountDiscountPerUnitGross

    • must be > 0.00 (when provided)
    • can be maximum as high as the item.amountPerUnitGross of the respective basket item

    amountDiscountPerUnitGross when providing a voucher

    • must be > 0.00 (when provided)
    • can be maximum as high as basketItems.sum(( item.amountPerUnitGross - item.amountDiscountPerUnitGross)* item.quantity ) per participantId

    currencyCode

    • must be the same currency provided in authorize and charges calls

    See also