# Delivery Checkout API

# Overview

Note

All of the examples below are HTTP requests that can be roughly translated to the generated client method calls. The main goal of this section is to get the overall feeling of the API and the data flows.

Delivery Checkout is responsible for maintaining life cycle of a session that has all the data needed by the shipping selector widget. When a user visits checkout page, makes any changes to cart contents, selects shipping options and completes a purchase, all the relevant data are stored in the session.

Every session contains results field which provides information about currently selected delivery option for each child session created based on the received carts. Each result in results contains all important information like:

  • pricing,
  • category,
  • shipping method,
  • external_method_id,
  • details of pickup point if applicable.

Results field should be used in integration to get final result of session. The example result looks as follows:

{
    "session": {
        "checkout_session_id": "VM1-abfe8b49dc2848938361aa2fe9f71b63",
        "status": "ACTIVE",
        "results": [
            {
                "shipping": {
                    "shipping_method": "pnl-bua",
                    "delivery_type": "mailbox",
                    "delivery_time": {
                        "id": "vG5OJYuvleuJGg7eYtvy2w",
                        "expires": "2021-11-16T15:00:00+01:00",
                        "start": "2021-11-17T00:00:00+01:00",
                        "end": "2021-11-29T00:00:00+01:00"
                    },
                    "external_method_id": "PUA",
                    "warehouse": {
                        "address": {
                            "name": "iDeal of Sweden",
                            "address_lines": [
                                "Fanérgatan 14B"
                            ],
                            "city": "Habo",
                            "postal_code": "56633",
                            "country": "SE",
                            "coordinates": {
                                "lat": 57.90445,
                                "lng": 14.09945
                            }
                        }
                    }
                },
                "category": {
                    "id": "category-letter-se",
                    "name": "Brev AB 1"
                },
                "pricing": {
                    "currency": "SEK",
                    "price": 2900,
                    "price_components": [
                        {
                            "type": "PRICE_COMPONENT_TYPE_SHIPPING",
                            "value": 2900
                        }
                    ]
                },
                "selection": "PRESELECTED_CHOICE",
                "delivery_time": {
                    "pickup_from_merchant": {
                        "earliest": "2021-11-16T15:00:00+01:00",
                        "latest": "2021-11-16T15:00:00+01:00"
                    },
                    "customer_delivery_promise": {
                        "earliest": "2021-11-17T00:00:00+01:00",
                        "latest": "2021-11-29T00:00:00+01:00"
                    },
                    "carrier_delivery_promise": {
                        "earliest": "2021-11-17T00:00:00+01:00",
                        "latest": "2021-11-29T00:00:00+01:00"
                    }
                }
            }
        ],
        "updated_at": "2021-11-15T14:12:17Z"
    }
}

# Create Session

The session.create method is used to create a new session. It returns the newly created Session as well as a html_snippet that can be embedded in the checkout page. Session can be created with minimal set of properties - purchase_country, purchase_currency, locales and carts.

# Generic Flow

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when creating a new session and rendering shipping selector for that session onto the checkout page.

sequenceDiagram participant C as Customer participant M as Merchant participant A as Delivery Checkout API C->>M: Load checkout page M->>A: Create new session A->>M: Return shipping selector html snippet and session state M->>C: Render shipping selector html snippet on the page
  1. Customer loads the checkout page
  2. Merchant calls the session.create method
  3. Delivery Checkout API returns a new Session and the html_snippet needed to render the shipping selector.
  4. Merchant renders html_snippet on the page.

A minimal set of fields required to create a session is purchase_country, purchase_currency, locales and carts. A new session is returned along with an identifier and a token for authorization.

Note

We support Canada and United States regions, such as states and army regions that can be passed in the address (and on which the filtering of configured shipping methods can be done).

# Supported Languages

The following locales are supported:

  • cs-CZ - Czech
  • da-DK - Danish
  • de-AT - Austrian German
  • de-BE - Belgian German
  • de-CH - Swiss German
  • de-DE - German
  • de-LU - Luxembourgish German
  • el-GR - Greek
  • en-AU - Australian English
  • en-CA - Canadian English
  • en-GB - British English
  • en-IE - Irish English
  • en-US - American English
  • es-ES - Spanish
  • et-EE - Estonian
  • fi-FI - Finnish
  • fi-SE - Swedish Finnish
  • fr-BE - Belgian French
  • fr-CA - Canadian French
  • fr-CH - Swiss French
  • fr-FR - French
  • fr-LU - Luxembourgish French
  • hr-HR - Croatian
  • is-IS - Icelandic
  • it-CH - Swiss Italian
  • it-IT - Italian
  • ja-JP - Japanese
  • ko-KR - Korean
  • lt-LT - Lithuanian
  • lv-LV - Latvian
  • nb-NO - Norwegian Bokmål
  • nl-BE - Flemish
  • nl-NL - Dutch
  • nn-NO - Norwegian Nynorsk
  • no-NO - Norwegian
  • pl-PL - Polish
  • pt-PT - Portuguese
  • ru-RU - Russian
  • sk-SK - Slovak
  • sl-SI - Slovenian
  • sv-FI - Finland Swedish
  • sv-SE - Swedish
  • zh-CN - Simplified Chinese

# Example Calls

# Update Session

The session.update method can be used to update the Customer, Cart contents and to add or remove Carts of the session if needed. You can updated either Carts, Customer or both at the same time.

There are three flows that should be used when it comes to updating the session.

  1. When customer changes the shipping option
  2. When cart contents change
  3. When a new cart is created or some existing cart was dropped by the user

# Generic flow when customer changes shipping option

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when updating a session. In this scenario shipping selector is the master so there is no need to suspend it.

sequenceDiagram participant C as Customer participant SS as Shipping Selector participant CO as Checkout participant M as Merchant participant A as Delivery Checkout API C->>SS: Change the shipping option SS->>CO: Fire option changed JS event CO->>M: Do Ajax call to backend M->>A: Call /session.get A->>M: Return Session state M->>M: Update order with new shipping cost M->>CO: Return new shipping cost CO->>CO: Update total cost CO->>C: Show new total
  1. Customer changes shipping option
  2. Merchant is notified via JS event subscription
  3. Merchant makes the Ajax call to its backend
  4. Merchant fetches Ingrid Session using session.get and extracts the shipping cost
  5. Merchant updates its order data in the backend
  6. Merchant completes Ajax call and returns updated shipping cost
  7. Merchant updates total cart cost with newly updated shipping cost

# Generic flow when cart contents change

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when updating a session and checkout page is master.

sequenceDiagram participant C as Customer participant SS as Shipping Selector participant CO as Checkout participant M as Merchant participant A as Delivery Checkout API C->>CO: Update cart CO->>SS: Suspend CO->>M: Ajax call to backend M->>A: Call /session.update A->>M: Return updated session state M->>M: Update order with updated shipping cost M->>CO: Return Ajax call CO->>CO: Update cart and totals CO->>SS: Resume shipping selector SS->>M: Refresh state A->>SS: Return updated state SS->>C: Display fresh shipping options
  1. Put shipping selector in suspend mode using the Javascript API
  2. Call Merchant backend to make the change, for example remove item from the cart.
  3. Apply the update to the Session using the session.update call
  4. Updated session is returned
  5. Merchant update order with updated shipping cost
  6. Complete the Ajax call in the checkout
  7. Resume shipping selector using the Javascript API
  8. Shipping selector will then refresh its state

# Example Calls

Note

The difference between the search address and the customer address is that the first one simply points us to which area package should be delivered, but it doesn't need to be customer real address. The customer address must be provided by the merchant.

For example, if you want to have a package delivered close to your work, you can fill search address with your office address. The customer is a customer home address. It allows performing fraud detection if someone is ordering an expensive item and customer and search addresses are distant to each other. The merchant could compare both addresses and verify if the order is valid by contacting the customer before shipping goods.

# Complete Session

The session.complete method is used to mark a session as complete. At this point, if the customer haven't made a choice we'll generate one for the customer based on the information in the Customer property provided in the request.

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when completing a session when the customer checkout.

sequenceDiagram participant C as Customer participant M as Merchant participant A as Delivery Checkout API C->>M: Completes the order M->>A: Call /session.complete A->>M: Return completed session state M->>C: Redirects to confirmation page
  1. Customer completes the transaction
  2. Merchant completes the session using session.complete method
  3. Delivery Checkout API returns session in a completed state. The SelectedShippingOption and tos_id are also returned.
  4. Merchant redirects the customer to the confirmation page

TIP

On session complete call a tos_id will be returned. This id is important if you need to re-open a session as a completed session is "frozen" and cannot be modified. You can use tos_id to clone a completed session.

# Example Calls

# Get Session

The session.get method is used to fetch an active or completed session.

At any point of a session lifetime, session can be fetched using Get Session call. The only argument to this call is ID of the session.

The response contains the current state of a session and its format is the same as in examples above for creating and updating sessions. The session should never change during this call.

# Generic Flow

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when fetching a previously created session and rendering the shipping selector for that session in the checkout page.

sequenceDiagram participant C as Customer participant M as Merchant participant A as Delivery Checkout API C->>M: Load the checkout page M->>A: Call /session.get A->>M: Return shipping selector html snippet and session state M->>C: Render shipping selector html snippet on the page
  1. Customer loads the checkout page
  2. Merchant calls the session.get method
  3. Delivery Checkout API returns a new Session and the html_snippet to render shipping selector
  4. Merchant renders html_snippet in the checkout page

# Example Calls

# Pull Session

The session.pull method is used to fetch an existing session data.

At any point of a session lifetime, session can be fetched using Pull Session call. The only argument to this call is ID of the session.

The response contains the current state of a session and its format is the same as in examples above for creating and updating sessions. When some shipping options have expired or merchant configuration has changed, new shipping options might be fetched and new choices might be generated.

Call to this API endpoint can mutate session state. This is in contrary to session.get endpoint behaviour, that gets the last session state and does not refresh it.

# Generic Flow

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and Delivery Checkout API when fetching a previously created session and rendering the shipping selector for that session in the checkout page.

sequenceDiagram participant C as Customer participant M as Merchant participant A as Delivery Checkout API C->>M: Load the checkout page M->>A: Call /session.pull A->>M: Return shipping selector html snippet and session state M->>C: Render shipping selector html snippet on the page
  1. Customer loads the checkout page
  2. Merchant calls the session.pull method
  3. Delivery Checkout API returns a new Session and the html_snippet to render shipping selector
  4. Merchant renders html_snippet in the checkout page

# Example Calls

# Errors

# Concurrent updates

Session get, update and complete calls can fail when another concurrent call is made, that updates the session resource. In that case, the response to this call would be a message with HTTP 409 Conflict code, and the call would have to be made again.

Last Updated: 11/23/2021, 9:15:27 AM