Basket change

It is possible to change a basket that has already been sent to OpenApp but has not been converted. This can be useful when a user modifies their basket in the webshop without after the basket has already been retrieved by OpenApp. To do so, a basket change callback can be executed, as shown in step 7 of the sequence diagram:

Request

A basket change request is executed by a POST to the following endpoint:

POST {{OpenAppUrl}}/merchant/v1/basket/change

The request body contains information about the order that is being cancelled:

Request

{
  "id": "basket-id",
  "expiresAt": "2022-03-23T21:00:00Z",
  "price": {
    "currency": "PLN",
    "discounts": [
      {
        "code": "discount-code-text",
        "value": 1000
      }
    ],
    "basketValue": 13000
  },
  "deliveryOptions": [
    {
      "key": "INPOST_APM",
      "cost": 0
    },
    {
      "key": "DPD_COURIER",
      "cost": 1000,
      "timing": "next business day"
    }
  ],
  "products": [
    {
      "ean": "12312",
      "id": "id123",
      "name": "Superb product",
      "images": [
        "http://cdn.merchant.com/static/products/id123/1",
        "http://cdn.merchant.com/static/products/id123/2"
      ],
      "quantity": 2,
      "unitPrice": 7000,
      "linePrice": 14000,
      "originalUnitPrice": 7000,
      "originalLinePrice": 14000,
      "policies": [
        {
          "type": "AGE",
          "criteria": {
            "minAge": 18
          }
        }
      ]
    }
  ],
  "loggedUser": "user-id-from-webshop"
}

Schema

idstringRequired

The unique ID of the basket.

maxLength: 36

requestIdstringOptional

The ID of the basket request as generated by OpenApp. Mandatory in case of an asynchronous connection through a queue in order to correlate the placed order with the response.

maxLength: 36

expiresAtstringRequired

The moment until which the basket is valid. This can be used to indicate a basket needs to be ordered before a specific time in order to guarantee availability.

format: date-time

oaOrderIdstringOptional

The OpenApp order ID (if known).

priceobjectRequired

Show child parametersHide child parameters3

currencystringRequired

basketValueintegerRequired

The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.

minimum: 0

discountsarray of BasketPriceDiscountRequired

Applied discounts

Show child parametersHide child parameters3

codestringRequired

The discount code.

maxLength: 36

valueintegerRequired

The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.

minimum: 0

errorenumOptional

The error code of the discount

Possible values: EXPIREDINVALIDNOT_APPLICABLEUSED

deliveryOptionsarray of BasketDeliveryOptionRequired

Show child parametersHide child parameters3

keyenumRequired

Possible values: DHL_COURIERDHL_PICKUPDPD_COURIERDPD_PICKUPELECTRONICFEDEX_COURIERGEIS_COURIERGLS_COURIERINPOST_APMINPOST_COURIERINSTORE_PICKUPORLEN_APMPOCZTA_POLSKA_APMPOCZTEX_COURIERUPS_COURIER

costintegerRequired

The price of the delivery. Price is expressed as the number (integer) of 1/100s of the price.

timingstringOptional

The estimation of the delivery time, i.e. 'next business day' or 'July 18th'.

maxLength: 40

productsarray of BasketProductRequired

Show child parametersHide child parameters10

namestringRequired

The product name.

imagesarray of stringRequired

The URLs of the product image

originalUnitPriceintegerRequired

The original (before discount) price of a single product. Price is expressed as the number (integer) of 1/100s of the price.

originalLinePriceintegerRequired

The original (before discount) price of the products. Price is expressed as the number (integer) of 1/100s of the price.

errorenumOptional

Error code when the product request can not be accomodated in a recalculate request.

Possible values: OUT_OF_STOCKQUANTITY_TOO_BIG

eanstringOptional

The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.

maxLength: 36

idstringRequired

The unique ID of the product.

maxLength: 36

quantityintegerRequired

The number of items in the purchase.

minimum: 0

unitPriceintegerRequired

The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.

linePriceintegerRequired

The price of the products. Price is expressed as the number (integer) of 1/100s of the price.

invoiceAddressMandatorybooleanOptional

Whether an invoice address is mandatory

loggedUserstringOptional

The unique ID of the user.

maxLength: 255

Raw JSON Schema

{
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique ID of the basket.",
      "maxLength": 36,
      "type": "string",
      "title": "id"
    },
    "requestId": {
      "description": "The ID of the basket request as generated by OpenApp. Mandatory in case of an asynchronous connection through a queue in order to correlate the placed order with the response.",
      "maxLength": 36,
      "type": "string",
      "title": "requestId"
    },
    "expiresAt": {
      "description": "The moment until which the basket is valid. This can be used to indicate a basket needs to be ordered before a specific time in order to guarantee availability.",
      "format": "date-time",
      "type": "string",
      "title": "expiresAt"
    },
    "oaOrderId": {
      "description": "The OpenApp order ID (if known).",
      "type": "string",
      "title": "oaOrderId"
    },
    "price": {
      "$ref": "#/definitions/BasketPrice",
      "title": "price"
    },
    "deliveryOptions": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/BasketDeliveryOption"
      },
      "title": "deliveryOptions"
    },
    "products": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/BasketProduct"
      },
      "title": "products"
    },
    "invoiceAddressMandatory": {
      "description": "Whether an invoice address is mandatory",
      "type": "boolean",
      "title": "invoiceAddressMandatory"
    },
    "loggedUser": {
      "description": "The unique ID of the user.",
      "maxLength": 255,
      "type": "string",
      "title": "loggedUser"
    }
  },
  "required": [
    "deliveryOptions",
    "expiresAt",
    "id",
    "price",
    "products"
  ],
  "definitions": {
    "BasketPrice": {
      "title": "BasketPrice",
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "title": "currency"
        },
        "basketValue": {
          "description": "The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.",
          "minimum": 0,
          "type": "integer",
          "title": "basketValue"
        },
        "discounts": {
          "description": "Applied discounts",
          "type": "array",
          "items": {
            "$ref": "#/definitions/BasketPriceDiscount"
          },
          "title": "discounts"
        }
      },
      "required": [
        "basketValue",
        "currency",
        "discounts"
      ]
    },
    "BasketPriceDiscount": {
      "title": "BasketPriceDiscount",
      "type": "object",
      "properties": {
        "code": {
          "description": "The discount code.",
          "maxLength": 36,
          "type": "string",
          "title": "code"
        },
        "value": {
          "description": "The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.",
          "minimum": 0,
          "type": "integer",
          "title": "value"
        },
        "error": {
          "description": "The error code of the discount",
          "enum": [
            "EXPIRED",
            "INVALID",
            "NOT_APPLICABLE",
            "USED"
          ],
          "type": "string",
          "title": "error"
        }
      },
      "required": [
        "code",
        "value"
      ]
    },
    "BasketDeliveryOption": {
      "title": "BasketDeliveryOption",
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/definitions/MerchantDeliveryOptions",
          "title": "key"
        },
        "cost": {
          "description": "The price of the delivery. Price is expressed as the number (integer) of 1/100s of the price.",
          "type": "integer",
          "title": "cost"
        },
        "timing": {
          "description": "The estimation of the delivery time, i.e. 'next business day' or 'July 18th'.",
          "maxLength": 40,
          "type": "string",
          "title": "timing"
        }
      },
      "required": [
        "cost",
        "key"
      ]
    },
    "MerchantDeliveryOptions": {
      "title": "MerchantDeliveryOptions",
      "enum": [
        "DHL_COURIER",
        "DHL_PICKUP",
        "DPD_COURIER",
        "DPD_PICKUP",
        "ELECTRONIC",
        "FEDEX_COURIER",
        "GEIS_COURIER",
        "GLS_COURIER",
        "INPOST_APM",
        "INPOST_COURIER",
        "INSTORE_PICKUP",
        "ORLEN_APM",
        "POCZTA_POLSKA_APM",
        "POCZTEX_COURIER",
        "UPS_COURIER"
      ],
      "type": "string"
    },
    "BasketProduct": {
      "title": "BasketProduct",
      "type": "object",
      "properties": {
        "name": {
          "description": "The product name.",
          "type": "string",
          "title": "name"
        },
        "images": {
          "description": "The URLs of the product image",
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "images"
        },
        "originalUnitPrice": {
          "description": "The original (before discount) price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
          "type": "integer",
          "title": "originalUnitPrice"
        },
        "originalLinePrice": {
          "description": "The original (before discount) price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
          "type": "integer",
          "title": "originalLinePrice"
        },
        "error": {
          "description": "Error code when the product request can not be accomodated in a recalculate request.",
          "enum": [
            "OUT_OF_STOCK",
            "QUANTITY_TOO_BIG"
          ],
          "type": "string",
          "title": "error"
        },
        "ean": {
          "description": "The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.",
          "maxLength": 36,
          "type": "string",
          "title": "ean"
        },
        "id": {
          "description": "The unique ID of the product.",
          "maxLength": 36,
          "type": "string",
          "title": "id"
        },
        "quantity": {
          "description": "The number of items in the purchase.",
          "minimum": 0,
          "type": "integer",
          "title": "quantity"
        },
        "unitPrice": {
          "description": "The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
          "type": "integer",
          "title": "unitPrice"
        },
        "linePrice": {
          "description": "The price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
          "type": "integer",
          "title": "linePrice"
        }
      },
      "required": [
        "id",
        "images",
        "linePrice",
        "name",
        "originalLinePrice",
        "originalUnitPrice",
        "quantity",
        "unitPrice"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Response

In response, OpenApp will confirm the order is cancelled.

warning

Sending a basket change will reload the basket for the user if the user had not yet initiated the payment. If the user had initiated the payment, the payment will complete and the order will be placed according to the original basket. The shop must be able to handle this scenario.

Errors

Error name	Code
InvalidBasketException	400
MissingDeliveryOptionsException	400
BasketExpiredException	400