Document Properties
Kbid
260Q29
Last Modified
13-Oct-2021
Added to KB
13-Nov-2014
Public Access
Everyone
Status
Online
Doc Type
Guidelines
Product
  • ICM 7.10
  • ICM 11
Guide - Checkout Implementation Based on RESTful API

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
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.