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

Every session contains a result field which provides information about the currently selected delivery option. It contains all important bits such as:

  • Price
  • Category
  • Shipping method
  • External method ID
  • Details about the pickup point (if applicable)

Result field should be used in the integration to get the final result of the session. This is what the final result can look like.

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

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

# 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

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

# 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

Last Updated: 3/13/2020, 2:31:37 PM