# SIW 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 is to get the overall feeling of the API and the data flows.

SIW 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 result field which provides information about currently selected delivery option. It contains all important information like:

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

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

"session": {
    "result": {
        "shipping": {
            "shipping_method": "pnl-mpc",
            "delivery_type": "pickup",
            "carrier": "PostNord",
            "product": "MyPack Collect",
            "location": {
                "external_id": "586287",
                "name": "Direkten Sveavägen",
                "address": {
                    "name": "Direkten Sveavägen",
                    "address_lines": [
                        "Sveavägen 137"
                    ],
                    "city": "Stockholm",
                    "postal_code": "11346",
                    "country": "SE",
                    "coordinates": {
                        "lat": 59.34909509999998,
                        "lng": 18.050284299999994
                    }
                },
                "distance": {
                    "walking": {
                        "value": 450,
                        "duration": 5
                    },
                    "driving": {
                        "value": 771,
                        "duration": 1
                    }
                },
                "operational_hours": {
                    "mon": "08:00-20:00",
                    "tue": "08:00-20:00",
                    "wed": "08:00-20:00",
                    "thu": "08:00-20:00",
                    "fri": "08:00-20:00",
                    "sat": "09:00-17:00",
                    "sun": "10:00-16:00"
                }
            },
            "delivery_time": {
                "id": "VMzp-Ei2Lx7PAbmQMbnbFg",
                "expires": "2019-07-04T15:00:00+02:00",
                "start": "2019-07-05T00:00:00+02:00",
                "end": "2019-07-09T00:00:00+02:00"
            },
            "external_method_id": "pnl-mypack",
            "supports": {}
        },
        "category": {
            "id": "category-pickup",
            "name": "Category Pickup"
        },
        "pricing": {
            "currency": "SEK",
            "price": 1900
        }
    }
}

# 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, locale and cart.

SIW also supports embedding multiple widgets on a single page, see Multiple widgets.

# Generic Flow

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and SIW 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 SIW 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. SIW 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, locale and cart. 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 Cart or Customer of the session if needed. You can updated either Cart, Customer or both at the same time.

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

  1. When customer changes the shipping option
  2. When cart contents change

# Generic flow when customer changes shipping option

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and SIW 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 SIW 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 SIW 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 SIW 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.

TIP

Search address and customer address are two different entities, that serve separate purposes during session lifetime. Search address is provided by the customer and the customer address is always provided by merchant. Search address is used to generate the shipping options that will be presented to the customer. Customer address is the address where the parcel will be sent and should be provided sometime during session lifetime (at the latest during session.complete).

Shipping options may be regenerated under some conditions when the customer address is provided and it differs from the search address.

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

sequenceDiagram participant C as Customer participant M as Merchant participant A as SIW 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. SIW 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. There is one possibility that session gets changed during this call. When some shipping options have expired or merchant configuration has changed, new shipping options might be fetched and new choices might be generated.

# Generic Flow

The sequence diagram below describes the flow between the Customer, Merchant, Shipping Selector and SIW 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 SIW 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. SIW 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