Business Guide - WebShop REST API - Basket and Checkout (valid to 7.7)

1 Introduction

This document describes the procedure of creating a basket, preparing the checkout and creating an order by using the IS7 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?

2 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.

3 RESTful API Basket and Checkout Flow

Like in the beginning mentioned, 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

rest_checkout_1

3.1 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

REST_simple_checkout_sequence

3.2 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

4 Checkout Request Overview

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

business_outline_REST_cc_advanced


Process Step:

4.1 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:
  • Basket is created which can be enriched with further details (add items, addresses, shipping and payment options) but which cannot transformed into an order (because of the missing information)
  • return of the basket ID and the URI of the basket
REST Call:REST API - Create a new basket


 



 

Process Step:

4.2 Add Line Item(s) to Basket

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

 


 


 

Process Step:

4.3 Get Basket Line Item Options

URI:/baskets/<basket-id>/items/<item-id>
http Method:OPTIONS
Property:optional
Precondition:
  • Basket must already be available (existing and valid Basket ID)
  • at least one item must be already added to the basket
Description:
  • the client is requesting 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:

4.4 Edit Line Item Data

URI:/baskets/<basket-id>/items/<item-id>
http Method:PUT
Property:optional
Precondition:
  • Basket must already be available (existing and valid Basket ID)
  • at least one item must be already added to the basket
Description:
  • the client has edit the 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:

4.5 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:
  • Basket must already be 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 is adding 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:

4.6 Get Basket (Shipping) Options

URI:/baskets/<basket-id>
http Method:OPTIONS
Property:optional
Precondition:
  • Basket must already be 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 is requesting 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:

4.7 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:
  • Basket must already be 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:

4.8 Get Payment Options

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

optional

Precondition:
  • Basket must already be 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:

4.9 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:
  • 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:

4.10 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:
  • Basket must already be 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:
    • 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:

4.11 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:
  • Basket must already be 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 the 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:
  • shop system gets all necessary information to communicate with the payment provider after order confirmation to finalize and to confirm the payment transaction
  • 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:

4.12 Submit Order (create order)

URI:/orders/
http Method:POST
Property:

mandatory

Precondition:
  • Basket must already be 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
  • 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.

Customer Support
Knowledge Base
Product Resources
Support Tickets