Product Catalogue

This document describes how to supply item-level order information in REST API requests that contain order.basket.

Basket items supplement the transaction amount. They do not replace the request's mandatory transactionAmount.total and transactionAmount.currency fields.

Basket information is supplied below order:

order
└── basket
    ├── productStock
    └── items[]
        ├── id
        ├── description
        ├── quantity
        ├── unitPrice
        ├── subTotal
        ├── valueAddedTax
        ├── localTax
        ├── deliveryAmount
        ├── chargeTotal
        ├── currency
        ├── unit
        ├── category
        ├── detailedCategory
        └── options[]
            ├── name
            └── choice

Presence: m = mandatory, c = conditional, o = optional, - = exposed in the schema but not used as an item-level override.

Basket fields

Basket item fields

All amount fields describe the current item entry, including all units represented by that entry unless stated otherwise.

Item option fields

Amount calculation rules

For each basket item, calculate the amounts as follows:

subTotal = quantity * unitPrice

chargeTotal = subTotal
            + valueAddedTax
            + localTax
            + deliveryAmount

Treat an omitted optional amount component as zero for the calculation. Do not omit chargeTotal; the Gateway does not derive a missing item total.

The following rules apply:

1. unitPrice is the price for one unit.
2. subTotal is the extended subtotal for all units in the item entry. It is not another unit-price field.
3. valueAddedTax, localTax, and deliveryAmount are totals for the item entry, not per-unit values.
4. chargeTotal must equal the sum of the supplied item components.
5. Item amount components use transactionAmount.currency and must fit that currency's supported fraction digits.
6. transactionAmount.total remains mandatory. For a transaction containing only the documented basket amounts, it normally equals the sum of all item chargeTotal values.

Example

The following request fragment contains one item with seven units. Payment-method and authentication fields are omitted so the example can focus on the basket.

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": 365.00,
    "currency": "EUR"
  },
  "order": {
    "orderId": "ORDER-10001",
    "basket": {
      "items": [
        {
          "id": "ITEM-01",
          "description": "Example product",
          "quantity": 7,
          "unitPrice": 50.00,
          "subTotal": 350.00,
          "valueAddedTax": 10.00,
          "localTax": 2.00,
          "deliveryAmount": 3.00,
          "chargeTotal": 365.00,
          "unit": "piece",
          "category": "books",
          "detailedCategory": "technical-books",
          "options": [
            {
              "name": "format",
              "choice": "hardcover"
            }
          ]
        }
      ]
    }
  }
}

Calculation:

subTotal = 7 * 50.00 = 350.00
chargeTotal = 350.00 + 10.00 + 2.00 + 3.00 = 365.00

Example without tax or delivery

Tax and delivery fields may be omitted when they do not apply, but chargeTotal must still be supplied.

{
  "id": "ITEM-02",
  "quantity": 2,
  "unitPrice": 12.50,
  "subTotal": 25.00,
  "chargeTotal": 25.00
}

Multiple items

Validate every item independently. The transaction total is separate from the per-item totals.

item 1 chargeTotal = 25.00
item 2 chargeTotal = 40.00
transactionAmount.total = 65.00

If the transaction also contains an amount that is not allocated to a basket item, include that amount when calculating transactionAmount.total according to the applicable payment scenario.

Product stock checking

Set order.basket.productStock to check only when product-inventory validation is enabled for the store.

When stock checking is requested:

• supply an id that identifies a configured catalogue product;
• supply the requested quantity;
• supply option name and choice values when inventory depends on a product variant;
• expect the request to fail if the product or selected option is unknown, the requested stock is unavailable, or inventory checking is not enabled for the store.

Omit productStock when the basket is supplied only for order detail, reporting, or payment-method processing.

Validation errors

Operational rules