Create a basket

Submit product information such as items, discounts, vouchers, and shipment cost within your payment.

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	A basket or shop reference ID sent from the shop’s back end. If not 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 after deducting all discounts.
`note`	string	N	Additional details for the basket
`basketItems`	object
`title` (required)	string	N	The title of the basket item
`subTitle`	string	N	The subtitle for the basket item
`basketItemReferenceId` (required)	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
`type` (required)	string	N	The type of item in the basket. The valid values are `goods`, `digital`, `shipment`, and `voucher`.
`unit`	string	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",
            "amountDiscountPerUnitGross": "0.0000",
            "amountPerUnitGross": "200.0000",
            "title": "Macbook pro",
            "type": "goods",
            "unit": "pc",
            "subTitle": "basket item subtitle"
        }
    ]
}

Add shipping costs

To provide shipment costs you can add a basket item with item.type shipment 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": "shipment"
    }
  ]
}

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, such as coupons, gift cards, or promotional codes to your basket, you can add a basket item with item.type voucher as shown in the following example.

{
  "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"
    }
  ]
}

Adding all basket item 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": "shipment"
    }
  ]
}

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

Important information