Skip to main content

Basket lock

Some purchase workflows require a (short term) lock on a shopping basket to make sure there are no modifications concurrent with the payment. For these scenarios it is possible to configure a lock request which will take place shortly before the actual purchase:

Request​

In this case OpenApp will execute a HTTP POST to the to the endpoint configured in the control panel for a recalculate, with an updated basket in the request body:

POST <recalculate-url>?lock=true

So if you configured the value https://shop.example.com/api/openapp/basket, the request executed by OpenApp will be:

POST https://shop.example.com/api/openapp/basket?lock=true

The request body contains the basket from the user. For example:

{
  "requestId": "request-id",
  "id": "basket-id",
  "price": {
    "currency": "PLN",
    "discounts": [
      {
        "code": "new-discount-code-text"
      }
    ]
  },
  "products": [
    {
      "ean": "12312",
      "id": "id123",
      "quantity": 3
    }
  ],
  "loggedUser": "user-id-from-webshop"
}

Response​

In response, the website should send the basket content and configured delivery options in the same format as for the retrieve basket response. The expiresAt property indicates until which time the basket is valid and locked. This is shown in the example below:

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

Of course it is possible that the website cannot accomodate the requested basket, for instance because not enough stock is available or prices changed. In that scenario the website should repond with the part of the basket that is available, plus an error code to indicate any errors in the basket. OpenApp will prompt the user to decide whether he wants to continue the purchase.

This example is an example of a simple basket. For a complete description of the basket response see the Schema tab above.