Skip to main content

Place order

The place order call is executed when an OpenApp user confirms an order and payment has been initiated.

This is visible as step 9 in the sequence diagram:

Request​

In this case, OpenApp will execute a HTTP POST to the to the endpoint configured in the control panel, with order information in the request body. So if you configured the value https://shop.example.com/api/openapp/order, the request executed by OpenApp will be:

POST https://shop.example.com/api/openapp/order

In the POST body, OpenApp will add all data required to complete the order in the webshop. The actual data depends on the delivery method specified by the user.

The oaOrderId uniquely identifies an order. If an order is placed and OpenApp does not receive a response soon enough it may retry so it is important that the webshop implements the place order endpoint in an idempotent manner.

APM delivery​

In the example request below the user has selected a delivery into an APM locker. The required information for that is which locker location is selected as well as the information to contact the user for sending him a code to open the locker.

{
  "oaOrderId": "OA12345678901234",
  "basket": {
    "id": "basket-id",
    "price": {
      "currency": "PLN",
      "discounts": [
        {
          "code": "discount-code-text",
          "value": 1000
        }
      ],
      "basketValue": 11000,
      "deliveryCost": 100
    },
    "products": [
      {
        "ean": "12312",
        "id": "id123",
        "quantity": 2,
        "unitPrice": 6000,
        "linePrice": 12000
      }
    ],
    "loggedUser": "user-id-from-webshop"
  },
  "deliveryDetails": {
    "type": "PICKUP",
    "method": "INPOST_APM",
    "subType": "APM",
    "id": "WAW22A",
    "name": "WAW22A",
    "street": "Domaniewska",
    "streetNo": "12A",
    "postalCode": "02-654",
    "city": "Warszawa",
    "country": "PL",
    "email": "id@o-app.pl",
    "phoneNumber": "+48123123123"
  },
  "paymentDetails": {
    "currency": "PLN",
    "amount": 11000
  },
  "consents": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "version": 1
    },
    {
      "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "version": 2
    }
  ]
}

The user has not requested any invoice, so that information is missing from the data. The user is further using the anonimization features of OpenApp to hide his email address from the merchant. The merchant can still email the user since the email address provided by OpenApp will be forwarded, but the real identity of the user is not disclosed. As can be seen from the product list, the product had an original proce of PLN 70.00 and were discounted to PLN 60.00. Then a discount code with a value of PLM 10.00 was applied to the whole order, so the total price of the order is PLN 110.00.

Electronic delivery​

If the user has selected electronic delivery the required information is the email address:

{
  "oaOrderId": "OA12345678901234",
  "basket": {
    "id": "xxx",
    "price": {
      "currency": "PLN",
      "discounts": [],
      "basketValue": 6000,
      "deliveryCost": 100
    },
    "products": [
      {
        "ean": "12312",
        "id": "id123",
        "quantity": 1,
        "unitPrice": 6000,
        "linePrice": 6000
      }
    ]
  },
  "deliveryDetails": {
    "type": "ELECTRONIC",
    "method": "ELECTRONIC",
    "email": "userEmail@email.com"
  },
  "billingDetails": {
    "companyName": "Nice Company",
    "taxId": "111111111",
    "country": "PL",
    "city": "Warszawa",
    "postalCode": "02-654",
    "street": "Domaniewska",
    "streetNo": "12A",
    "notes": ""
  },
  "paymentDetails": {
    "currency": "PLN",
    "amount": 6000
  },
  "consents": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "version": 1
    },
    {
      "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "version": 2
    }
  ]
}

The user has ordered 1 item of PLN 60.00. Since there was no discount applied, the product list only has a unitPrice and a linePrice, and no previousUnitPrice or previousLinePrice. Of note is that the user has given consent to receive email marketing messages, but not to receive SMS marketing messages.

In store pickup​

If the user has selected in store pickup, delivery details will contain the delivery address enriched with pointId of pickup point seleted by user in app:

{
  "oaOrderId": "OA12345678901234",
  "basket": {
    "id": "basket-id",
    "price": {
      "currency": "PLN",
      "discounts": [
        {
          "code": "discount-code-text",
          "value": 1000
        }
      ],
      "basketValue": 11000,
      "deliveryCost": 100
    },
    "products": [
      {
        "ean": "12312",
        "id": "id123",
        "quantity": 2,
        "unitPrice": 6000,
        "linePrice": 12000
      }
    ],
    "loggedUser": "user-id-from-webshop"
  },
  "deliveryDetails": {
    "type": "PICKUP",
    "method": "INPOST_APM",
    "subType": "APM",
    "id": "WAW22A",
    "name": "WAW22A",
    "street": "Domaniewska",
    "streetNo": "12A",
    "postalCode": "02-654",
    "city": "Warszawa",
    "country": "PL",
    "email": "id@o-app.pl",
    "phoneNumber": "+48123123123"
  },
  "paymentDetails": {
    "currency": "PLN",
    "amount": 11000
  },
  "consents": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "version": 1
    },
    {
      "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "version": 2
    }
  ]
}

Courier delivery​

If the user has selected courier delivery the delivery details will contain the delivery address:

{
  "oaOrderId": "OA12345678901234",
  "basket": {
    "id": "basket-id",
    "price": {
      "currency": "PLN",
      "discounts": [],
      "basketValue": 12995,
      "deliveryCost": 100
    },
    "products": [
      {
        "ean": "12312",
        "id": "id123",
        "quantity": 2,
        "unitPrice": 6000,
        "linePrice": 12000
      }
    ],
    "loggedUser": "user-id-from-webshop"
  },
  "deliveryDetails": {
    "type": "COURIER",
    "method": "INPOST_COURIER",
    "firstName": "John",
    "lastName": "Doe",
    "country": "PL",
    "city": "Warszawa",
    "postalCode": "02-654",
    "street": "Domaniewska",
    "streetNo": "12",
    "apartmentNo": "17",
    "notes": "Please place the package on the porch behind the rose-bush if nobody opens the door.",
    "phoneNumber": "+48123456789",
    "email": "test@example.com",
    "companyName": "Nice Company"
  },
  "billingDetails": {
    "companyName": "Nice Company",
    "taxId": "111111111",
    "country": "PL",
    "city": "Warszawa",
    "postalCode": "02-654",
    "street": "Domaniewska",
    "streetNo": "12A",
    "notes": ""
  },
  "paymentDetails": {
    "currency": "PLN",
    "amount": 12995
  },
  "consents": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "version": 1
    },
    {
      "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "version": 2
    }
  ]
}

As courier delivery is not free, an additional fee of PLN 9.95 is added to the total price of the purchase.

Response​

In reponse, the website should send the order confirmation.

{
  "oaOrderId": "0123456789abcdef0123456789abcdef",
  "shopOrderId": "WS1213ASDZXC231A",
  "returnPolicy": {
    "maxReturnDays": 30
  }
}

The merchant website should answer within 8 seconds.

This example is an example of a simple basket. For a complete description of the basket response see the basket JSON schema.