Document Tree
Document Properties
Kbid
2873B2
Last Modified
15-Feb-2023
Added to KB
17-Sep-2018
Public Access
Everyone
Status
Online
Doc Type
Guidelines
Product
  • ICM 7.10
  • ICM 11
Home ⋮ Knowledge Base
Business Guide - WebShop REST API - Basket and Checkout
Share this document

Table of Contents


Introduction

This document describes the procedure of creating a basket, preparing the checkout and creating an order by using the Intershop 7 RESTful API. Therefore the following questions should be answered:

  • How do I add an item to the cart and how do I manipulate (edit and delete) it?
  • How does an anonymous basket gets assigned to a registered/logged-in customer? (merge baskets)
  • How are the dependencies of each single checkout step?
  • How do I change shipping methods and how do I add further payment options?
  • How are the different payment process types working and are there differences between the single payment methods
  • How can I create an order?

Difference Between WebShop Implementation and RESTful API

The difference of the web shop implementation and the RESTful API implementation is that the checkout does not have such a strict and dependent process sequence at the RESTful API implementation. This is due to the objective of each implementation technology. The web shop implementation of inSPIRED is focused on a UI application while the RESTful API is focused on a data application which is a base for a UI application (for instance a mobile web app). So, the basket and checkout process and handling of the RESTful API allows a higher flexibility of the process sequence and the order of each single process step and block.

For instance: At the web shop implementation, the completed shipping step is a mandatory precondition before the payment step can be started. In contrast to this, the payment step can be executed before the shipping information are added to the basket or before any line item is added to the basket. But there are also some dependencies within the process steps of the RESTful API basket and checkout process. For instance, editing the shipping options is only possible if there have been added already some items to the basket.

RESTful API Basket and Checkout Flow

The process steps of the RESTful API are more or less independently of each other. But there are some restriction which are also valid for a checkout via the RESTful API:

  • Creating a basket is always the first action before the checkout flow can begin => the first request is POST /basket/
  • Creating the order is always the last step of the checkout => the last request is POST /orders/
  • To get and to set shipping options via the RESTful API, the basket must contain at least one item


Example for a Simple Checkout

  • Customer is logged in
  • No line item edit
  • No basket edit
    • Default address for invoicing and shipping
    • Use pre-selected shipping method
  • Simple payment method without a redirection

Example for an Advanced Checkout

  • Customer logs in during checkout process (basket is already created as anonymous customer)
  • Line item edit
  • Add a warranty
  • Basket edit:
    • Add a new address
    • Add a promotion
    • Select another shipping method

  • Advanced payment method with a redirection flow

Checkout Request Overview

Arranged by a common checkout flow (like in the web shop)

Process Step:

Create Basket (always the first step) 

URI:/baskets/
http Method:POST
Property:mandatory (at first!)
Precondition:none
Description:
  • It is the basic request before running any basket or checkout operation.
  • This request is the precondition for adding items to the basket.
  • It is always the first request for triggering a transaction operation.
Result:
  • The basket is created and can be enriched with further details (add items, addresses, shipping and payment options).
  • It cannot be transformed into an order (because of the missing information).
  • The basket ID and the URI of the basket are returned.
REST Call:REST API - Create a new basket


Process Step:

Add Line Item(s) to Basket

URI:/baskets/<basket-id>/items
http Method:POST
Property:mandatory
Precondition:
  • The basket must be already available (existing and valid Basket ID).
Description:
  • This request adds a list of items to an existing basket.
  • This request is the precondition for editing the shipping options (e.g., selecting another shipping method).
Result:
  • The items are added to the active basket.
  • The whole basket including the URI of the respective item(s) is returned.
REST Call:REST API - Adds line items to basket / add quote items to basket


Process Step:

Get Basket Line Item Options

URI:/baskets/<basket-id>/items/<item-id>
http Method:OPTIONS
Property:optional
Precondition:
  • The basket must already be available (existing and valid Basket ID).
  • At least one item must be already added to the basket.
Description:
  • The client requests the options of a respective line item:
    • Shipping options and methods
    • Service line item options (e.g. whether a warranty is available or not)
    • Other item variations
Result:
  • Returns:
    • The valid shipping options and methods of the item
    • Available service line items
    • Other item variations
REST Call:REST API - Return basket line item options


Process Step:

Edit Line Item Data

URI:/baskets/<basket-id>/items/<item-id>
http Method:PUT
Property:optional
Precondition:
  • The basket must already be available (existing and valid Basket ID).
  • At least one item must be already added to the basket.
Description:
  • The client can set the following line item options:
    • Shipping options and method
      (multiple shipping enabled = multiple shipping buckets)
    • Item quantity
    • Item variation
    • Change shipping address of item
      (only if multiple shipping is supported)
Result:
  • Returns the URI of the respective line item
REST Call:REST API - Set basket line item related data


Process Step:

Add SubLineItem

URI:

/baskets/<basket-id>/items/<item-id>/sublineitems/warranty (for warranties)

/baskets/<basket-id>/items/<item-id>/sublineitems/giftwrap (for gift wraps)

/baskets/<basket-id>/items/<item-id>/sublineitems/giftmessage (for gift messages)

http Method:PUT
Property:optional
Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the cart which is supporting the respective SubLineItem-type and has assigned a SubLineItem.
Description:
  • The client adds a SubLineItem (warranty, gift wrap or gift message) to a LineItem at the shopping cart
Result:
  • Returns the URI of the added SubLineItem

Note

The GET and DELETE requests are working equal to the LineItemRequests. The OPTIONS request is currently not available.
REST Call:REST API - Modify basket sub line item
Process Step:

Get Basket (Shipping) Options

URI:/baskets/<basket-id>
http Method:OPTIONS
Property:optional
Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Items should be added to the cart (not relevant for every option but especially for shipping options).
Description:
  • The client requests the shipping options and methods which are valid for the current basket so that he can select one in a downstreamed step.
Result:
  • Returns the shipping options and methods which are valid for the current basket
REST Call:REST API - Return basket options


Process Step:

Edit Basket Data

  • Add/Edit Invoice and Shipping Address(es)
  • Edit Shipping Options and Methods (disables multiple shipping)
  • Add/Edit B2B customer information (e.g. taxation ID)
  • Add/Edit Promotion Code
  • Transform basket of anonymous customer into basket of registered customer
URI:/baskets/<basket-id>
http Method:PUT
Property:
  • Mandatory (in case of anonymous user or logged in user with missing addresses or saved payment information)
  • Optional (in case of a logged in user who has saved at least one address and payment information at his account and when accelerated checkout is enabled)
Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the basket.
Description:
  • The client will update or add mandatory basket information:
    • Add/Edit Invoice and Shipping Address(es)
    • Edit Shipping Options and Methods (disables multiple shipping)
  • The client will add additional B2B information to the cart.
  • The client will add a promotion code to the cart.
  • The client has created the basket as anonymous user and is logging in so that the basket will transformed (change authentication of the basket).
Result:
  • Returns the updated or enriched basket
REST Call:REST API - Set basket related information


Process Step:

Get Payment Options

URI:/baskets/<basket-id>/payments/
http Method:OPTIONS
Property:

optional

Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the basket.
Description:
  • The client will request the available and valid payment methods for the current basket.
Result:
  • Returns all available and valid payment methods for the current basket with its specific options and attributes
REST Call:REST API - Return payment options for basket (internal)



Process Step:

Add Payment Method to Basket

URI:/baskets/<basket-id>/payments/
http Method:POST
Property:
  • mandatory (in case of anonymous user or logged in user with missing saved payment information)
  • optional (in case of a logged in user who has saved at least one address and payment information at his account and when accelerated checkout is enabled)
Precondition:
  • The basket must already be available (existing and valid Basket ID)
  • Item(s) must be added to the basket
Description:
  • The client set/select a payment method for his basket and will save the necessary payment information (e.g., the credit card data).
Result:
  • Returns the URI of the PaymentInstrumentInfo (selected payment method and the necessary payment information)
REST Call:REST API - Add payment to basket


Process Step:

Get Return URL`s for Payment-Provider-Redirect from the REST client

URI:/baskets/<basket-id>/payments/<payment-id>/redirect/
http Method:PUT
Property:

mandatory if a redirect payment method is selected

Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the basket.
  • A redirect payment method must be selected.
Description:
  • The client transfers the return URL´s to the shop system which are for the return back to the REST client after the redirect to the Payment Provider page
    • SuccessURL
    • FailURL
    • CancelURL
Result:
    • The shop system generates the redirect URL for the Payment Provider Redirect and transfers this URL to the REST client by the response.
REST Call:REST API - Get return-URLs from REST client for payment provider redirect (redirect before checkout)


Process Step:

Get Payment Transaction information from REST client after Payment-Provider-Redirect

URI:/baskets/<basket-id>/payments/<payment-id>/redirect/
http Method:POST
Property:

mandatory if a redirect payment method is selected

Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the basket.
  • A redirect payment method must be selected.
  • REST client must have transferred return URL`s to the shop system and must have received the redirect URL from the shop system.
Description:
  • By return to the REST client after the payment transaction initialization at the payment provider page, the REST client transfers the relevant information back to the shop system
    • Inter alia, the token
Result:
  • The shop system gets all necessary information to communicate with the payment provider after order confirmation to finalize and to confirm the payment transaction.
  • The system returns full PaymentInstrumentInfo (PII) with all data (including data from the payment provider).
REST Call:REST API - Get transaction details after redirect before checkout


Process Step:

Get Basket

URI:/baskets/<basket-id>/
http Method:GET
Property:

mandatory

Precondition:
  • The basket must be already available (existing and valid Basket ID).
Description:
  • The client get the calculated basket.
Result:
  • Returns the basket's summary.
REST Call:REST API - Get Basket by ID


Process Step:

Submit Order (create order)

URI:/orders/
http Method:POST
Property:

mandatory

Precondition:
  • The basket must be already available (existing and valid Basket ID).
  • Item(s) must be added to the basket.
  • Invoice address must be added to the basket.
  • Shipping address/es must be added to basket/buckets.
  • The payment method must be selected and if necessary the Payment Information must be added.
Description:
  • The client accepts the terms and conditions and submits the order.
Result:
  • Returns the URI of the order
REST Call:REST API - Create new order
Disclaimer
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.