Baskets with discounts, vouchers, and shipments

Overview

Compared to the details available a minimum basket a standard basket contains additional fields and is supporting discounts and vouchers. It supports all payment methods.

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

Supported Payment methods

This basket type supports all payment methods.

Create a 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/baskets

{
    "currencyCode": "EUR",
    "orderId": "{{randomOrderId}}",
    "totalValueGross": 200.00,
    "note": "basket note",
    "basketItems": [
        {
            "title": "Macbook pro",
            "subTitle": "basket item subtitle",
            "basketItemReferenceId": "item-1",
            "quantity": 1,
            "amountPerUnitGross": 200.00,
            "vat": 10,
            "type": "goods",
             "unit": "pc"
        }
    ]
}
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 and/or charging the transaction for this specific basket.
If not provided, the API sets the final orderID.
totalValueGross number Y The total amount for all the items in the basket.
note string N Additional details for the basket
basketItems
title (required) string N Title of the basket item
subTitle string N The subtitle for the basket item
basketItemReferenceId string N Unique basket item reference ID (within the basket). If not provided, the 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 VAT value for the basket item in percent
type (required) string N The type of item in the basket. The possible values are goods, discount.
unit number N The measuring unit for the basket item.

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

{
    "id": "s-bsk-db282c3a21d8"
}

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/baskets/{{basket_id}}

{
    "id": "s-bsk-db282c3a21d8",
    "totalValueGross": "200.0000",
    "currencyCode": "EUR",
    "orderId": "order-1611916622-716",
    "basketItems": [
        {
            "basketItemReferenceId": "item-1",
            "quantity": "1",
            "vat": "10.0000000",
            "amountDiscountPerUnitGross": "0.0000",
            "amountPerUnitGross": "200.0000",
            "title": "Macbook pro",
            "type": "goods",
            "unit": "pc",
            "subTitle": "basket item subtitle"
        }
    ]
}

Update a 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/baskets/s-bsk-db282c3a21d8

{
  "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": 10,
      "unit": "pc",
      "subTitle": "basket item 2"
    }
  ]
}
{
    "id": "s-bsk-db282c3a21d8"
}

You can review the updated details for the basket by sending a GET request to the basket resource specifying the basket ID that you want to update.

GET https://api.unzer.com/v2/baskets/s-bsk-db282c3a21d8

{
  "currencyCode": "EUR",
  "orderId": "order-1611916622-718",
  "totalValueGross":190.00,
  "note": "basket note",
  "basketItems": [
    {
      "title": "Macbook pro",
      "basketItemReferenceId": "item-1",
      "quantity": 1,
      "amountPerUnitGross": 200.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 10,
      "unit": "pc",
      "subTitle": "basket item 2"
    }
  ]
}

Use cases

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"
    },
    {
      "title": "Shipment costs",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 5.90,
      "vat": 1,
      "subTitle": "Insured standard shipment",
      "type": "shipments"
    }
  ]
}

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 example below.

{
  "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": 10,
      "unit": "pc",
      "subTitle": "basket item 2",
      "type": "goods"
    }
  ]
}

Provide vouchers

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

{
  "currencyCode": "EUR",
  "orderId": "{{randomOrderId}}",
  "totalValueGross":180.00,
  "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"
    },
    {
      "title": "10 EUR voucher newsletter registration",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 0.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 1,
      "type": "voucher"
    }
  ]
}

Combining all basket items types in one basket

Combining all use cases in one basket will look as shown in the following example:

{
  "currencyCode": "EUR",
  "orderId": "{{randomOrderId}}",
  "totalValueGross":185.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 1",
      "type": "goods"
    },
    {
      "title": "10 EUR voucher newsletter registration",
      "basketItemReferenceId": "item-2",
      "quantity": 1,
      "amountPerUnitGross": 0.00,
      "amountDiscountPerUnitGross": 10.00,
      "vat": 1,
      "type": "voucher"
    },
    {
      "title": "Shipment costs",
      "basketItemReferenceId": "item-3",
      "quantity": 1,
      "amountPerUnitGross": 5.90,
      "vat": 1,
      "subTitle": "Insured standard shipment",
      "type": "shipments"
    }
  ]
}

Basket validation

When creating or updating a standard 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

currencyCode

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

See also