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?

Difference Between Web Shop 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 PrimeTechSpecials 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

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

Example for a Simple Checkout

Customer is logged in
No line item edit
No Basket edit
- Use of saved default address for invoicing and shipping
- Use of 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

This section lists a series of REST API calls arranged by a common checkout flow (like in the web shop).

Click the link in the headline of an API call to go to the calls documentation. There you can find additional information like the cartridge which holds the according definition, the applications the call is available for and additional data formats (JSON, XML).

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

Process Step:	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)

Process Step:	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

Process Step:	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

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

Process Step:	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

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

Process Step:	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

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:	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)

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

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:	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)

Process Step:	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

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.