# COS API

COS 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 informations 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
        }
    }
}

# General Flow

The root object is a Session that is created using CreateSessionRequest when the shipping selector is loaded for the first time. It is identified by id on the Session object and can be accessed from the shipping selector using token.

Session can be created with minimal set of properties: purchase_country, purchase_currency, locale and cart.

Whatever change occurs in the shipping selector or in the checkout page (cart contents, customer address, delivery option selection) the session is updated using UpdateSessionRequest.

When order is finalized, the session is closed with CompleteSessionRequest and cannot be changed anymore. You can use tos_id to re-open the session. In that case the old session is cloned with the new one.

The session can be fetched at any time with GetSessionRequest, so that if the user reloads a checkout page, the shipping selector will fetch last saved state of a COS session.

# Create Session

This call creates a new session with CreateSessionRequest. A minimal set of fields required to create a session is purchase_country, purchase_currency, locale and cart. A new session has an identifier and a Token for authorization.

In examples below, we will show how different combinations of request parameters affect resulting session. Let's start with the simplest, minimal session without the search_address:

In above case, choices were generated based on shipping categories as no search address was provided. The preselected choice is calculated based on category preselected flag. Shipping options are empty because we are not able to fetch any real shipping options from any carriers without search address.

Next example shows creating a session with minimal search address (postal code and country).

As a result, a new session will be returned (shipping categories were redacted for brevity, those are exactly the same as in the previous example).

This time we received shipping_options filled with real shipping options that were returned by two carriers: DBSchenker and PostNord. Both options have delivery type pickup and both contain a list of available pickup points and their addresses. Choices are generated based on shipping options and sorted according to custom business rules. Choices are used by the widget to display shipping option in the correct order.

Let's see one more example with full search address (including street):

This time shipping options' locations contains additional distance property:

{
    "walking": {
        "value": 714,
        "duration": 9
    },
    "driving": {
        "value": 1403,
        "duration": 5
    }
}

Distance is measured between search address and pickup point address and has two values: distance in meters and duration in minutes. Two variants are returned, walking and driving. Distance data is used for sorting choices in order to show most convenient shipping option at the top.

# Update Session

By updating session we can set user_choice, change cart contents, search_address or set / update customer data. The difference between search address and the customer 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. 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.

Example update session call changing search address:

POST /v1/cos/session.update HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Authorization: Bearer base64-encoded-api-token
Content-Type: application/json

{
	"id": "899d72b4-8f3b-48ba-a971-fad4d0fbfd2c",
	"search_address": {
		"country": "SE",
		"postal_code": "11733",
		"address_lines": ["Mälarvarvsbacken 10"]
	}
}

The response contains updated session (with new search address and fresh shipping options and choices). Response format is the same as in examples above for creating sessions.

Example update session call with user choice:

User choice now points to one of the available choices and represents what customer selected in the widget. User choice must be among choices list, otherwise, validation error will be returned.

# Complete Session

Complete session is called when the order is finalized. Customer field is mandatory. No more changes can be made to the session after it is completed.

The response contains completed session (with new customer data). The response format is the same as in examples above for creating and updating sessions. The only difference is that session status is COMPLETE.

# Complete and Promote

# Create from Order

# Complete and Update Order

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

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