COS

Choice Of Shipment is the main API that the widget talks to

COS is responsible for maintaining life cycle of a session that has all the data needed by the checkout 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.

General Flow

The root object is a Session that is created using CreateSessionRequest when the widget is loaded for the first time. It is identified by id on the Session object and can be accessed from the widget using token. Session can be created with minimal set of fields: purchase_country, purchase_currency, locale and cart.

Whatever change occurs in the widget or on 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.

The session can be fetched at any time with GetSessionRequest, so that if the user reloads a checkout page, the widget can 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 search_address:

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

{
    "locale": "en-US",
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "cart": {
        "currency": "SEK",
        "items": [{"sku": "1234"}]
    }
}

As a result, a new session will be returned:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "session": {
        "id": "46015b2d-42a3-474b-9b05-c13e585f7072",
        "token": "Y2xpZW50OmE1YjkxNTE1MjU1NjRkMTU5YTJhMGIzMDFjZmE1YzQz",
        "status": "ACTIVE",
        "cart": {
            "currency": "SEK",
            "items": [
                {
                    "sku": "1234",
                }
            ],
        },
        "preselected_choice": {
            "shipping_method": "dbs-pos",
            "location_ref": "",
            "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
            "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
        },
        "shipping_categories": [
            {
                "id": "ea9b519d-a1c3-4a15-aab1-68f7791d803f",
                "name": "Frakt",
                "price": 1400,
                "sort_order": 3,
                "shipping_methods": [
                    "dbs-pos"
                ],
                "preselected": false,
                "requirements": {
                    "address": false,
                    "hide_shipping_options": true,
                    "use_price_from": false
                },
                "delivery_type": "pickup",
                "time_slot": {
                    "id": "z7fapfDsNZfVNHxScRCkuA",
                    "expires": "2018-05-11T15:00:00+02:00",
                    "start": "2018-05-15T00:00:00+02:00",
                    "end": "2018-05-16T00:00:00+02:00"
                },
                "prices": {
                    "dbs-pos": 1400
                },
            },
            {
                "id": "11405d2f-0548-4fed-be10-c4cd3fa9a82e",
                "name": "Snabbfrakt",
                "price": 2500,
                "sort_order": 1,
                "shipping_methods": [
                    "dbs-pos",
                    "pnl-mpc"
                ],
                "preselected": true,
                "requirements": {
                    "address": false,
                    "hide_shipping_options": false,
                    "use_price_from": false
                },
                "delivery_type": "pickup",
                "time_slot": {
                    "id": "eqOd7n6l0Jk-a9p6MRwDqw",
                    "expires": "2018-05-11T15:00:00+02:00",
                    "start": "2018-05-14T00:00:00+02:00",
                    "end": "2018-05-14T00:00:00+02:00"
                },
                "prices": {
                    "dbs-pos": 2500,
                    "pnl-mpc": 2500
                },
            },
            {
                "id": "964ab8cd-8881-4add-bf3b-31769006e42b",
                "name": "Hemleverans",
                "price": 2500,
                "sort_order": 4,
                "shipping_methods": [
                    "bst-std",
                    "dbs-par"
                ],
                "preselected": false,
                "requirements": {
                    "address": true,
                    "hide_shipping_options": false,
                    "use_price_from": false
                },
                "delivery_type": "delivery",
                "time_slot": {
                    "id": "QtSY2-2tQSPzP7WgeHRmng",
                    "expires": "2018-05-11T11:00:00+02:00",
                    "start": "2018-05-11T00:00:00+02:00",
                    "end": "2018-05-11T00:00:00+02:00"
                },
                "prices": {
                    "bst-std": 6900,
                    "dbs-par": 1234
                },
            }
        ],
        "shipping_options": [],
        "purchase_country": "SE",
        "purchase_currency": "SEK",
        "locale": "en-US",
        "choices": [
            {
                "shipping_method": "bst-std",
                "location_ref": "",
                "time_slot_ref": "QtSY2-2tQSPzP7WgeHRmng",
                "shipping_category_ref": "964ab8cd-8881-4add-bf3b-31769006e42b"
            },
            {
                "shipping_method": "dbs-par",
                "location_ref": "",
                "time_slot_ref": "QtSY2-2tQSPzP7WgeHRmng",
                "shipping_category_ref": "964ab8cd-8881-4add-bf3b-31769006e42b"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "",
                "time_slot_ref": "z7fapfDsNZfVNHxScRCkuA",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            }
        ]
    }
}

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

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

{
    "locale": "en-US",
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "cart": {
        "currency": "SEK",
        "items": [{"sku": "1234"}]
    },
    "search_address": {
        "country": "SE",
        "postal_code": "12333"
    }
}

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):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "session": {
        "id": "8090018c-a1fb-484b-bbda-8b71554602d4",
        "token": "Y2xpZW50OjU3NGYzM2MyYWM3MjQ3ODJiZWI3ZjM1M2QyZjc4ZDFk",
        "status": "ACTIVE",
        "cart": {
            "currency": "SEK",
            "items": [
                {
                    "sku": "1234",
                }
            ],
        },
        "preselected_choice": {
            "shipping_method": "pnl-mpc",
            "location_ref": "525172",
            "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
            "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
        },
        "shipping_categories": [...],
        "shipping_options": [
            {
                "shipping_method": "pnl-mpc",
                "delivery_type": "pickup",
                "carrier": "PostNord",
                "product": "MyPack Collect",
                "price": 2500,
                "currency": "SEK",
                "locations": [
                    {
                        "external_id": "525172",
                        "name": "Hemköp Stockholm Farsta C",
                        "address": {
                            "name": "Hemköp Stockholm Farsta C",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Farstaplan "
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12347",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.24321759999999,
                                "lng": 18.0909712
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "09:00-20:00",
                            "tue": "09:00-20:00",
                            "wed": "09:00-20:00",
                            "thu": "09:00-20:00",
                            "fri": "09:00-20:00",
                            "sat": "10:00-18:00",
                            "sun": "10:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "525185",
                        "name": "Direkten Farsta Speltjänst",
                        "address": {
                            "name": "Direkten Farsta Speltjänst",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Storforsplan 46"
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12347",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.2420304,
                                "lng": 18.0935293
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "10:00-21:00",
                            "tue": "10:00-21:00",
                            "wed": "10:00-21:00",
                            "thu": "10:00-21:00",
                            "fri": "10:00-21:00",
                            "sat": "10:00-18:00",
                            "sun": "11:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "525175",
                        "name": "Coop Konsum Farstastrand",
                        "address": {
                            "name": "Coop Konsum Farstastrand",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Farsta Strandplan 15"
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12371",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.2350721,
                                "lng": 18.1020795
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "07:00-20:00",
                            "tue": "07:00-20:00",
                            "wed": "07:00-20:00",
                            "thu": "07:00-20:00",
                            "fri": "07:00-20:00",
                            "sat": "08:00-18:00",
                            "sun": "08:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "525182",
                        "name": "ICA Nära Bomben",
                        "address": {
                            "name": "ICA Nära Bomben",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Tobaksvägen 4"
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12357",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.2552057,
                                "lng": 18.0785398
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "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": "08:00-20:00",
                            "sun": "08:00-20:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "546472",
                        "name": "Direkten Gubbängen",
                        "address": {
                            "name": "Direkten Gubbängen",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Gubbängstorget 114"
                            ],
                            "city": "Enskede",
                            "region": "",
                            "postal_code": "12245",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.26206550000001,
                                "lng": 18.0830049
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "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": "10:00-18:00",
                            "sun": "11:00-17:00",
                            "free_text": []
                        },
                        "meta": {}
                    }
                ],
                "time_slots": [
                    {
                        "id": "CBfJwq1wc6AlHVFwcOtFyA",
                        "expires": "2018-05-11T15:00:00+02:00",
                        "start": "2018-05-12T00:00:00+02:00",
                        "end": "2018-05-12T00:00:00+02:00"
                    }
                ],
                "external_method_id": "",
                "default_addons": [],
                "supports": {
                    "search": false,
                    "door_code": false,
                    "courier_instructions": false
                },
                "meta": {}
            },
            {
                "shipping_method": "dbs-pos",
                "delivery_type": "pickup",
                "carrier": "DB Schenker",
                "product": "Ombud Standard",
                "price": 2500,
                "currency": "SEK",
                "locations": [
                    {
                        "external_id": "0101",
                        "name": "Gubbängens Tobak & Spel",
                        "address": {
                            "name": "Gubbängens Tobak & Spel",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Gubbängstorget 114"
                            ],
                            "city": "Enskede",
                            "region": "",
                            "postal_code": "12245",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.26206550000001,
                                "lng": 18.0830049
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "",
                            "tue": "",
                            "wed": "",
                            "thu": "",
                            "fri": "",
                            "sat": "",
                            "sun": "",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "0013",
                        "name": "Stockholm Stop",
                        "address": {
                            "name": "Stockholm Stop",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Pepparvägen 38-40"
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12356",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.2534502,
                                "lng": 18.0825441
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "08:30-20:00",
                            "tue": "08:30-20:00",
                            "wed": "08:30-20:00",
                            "thu": "08:30-20:00",
                            "fri": "08:30-20:00",
                            "sat": "10:00-18:00",
                            "sun": "10:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "0251",
                        "name": "Farsta Direkten",
                        "address": {
                            "name": "Farsta Direkten",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Storforsplan 46"
                            ],
                            "city": "Farsta",
                            "region": "",
                            "postal_code": "12347",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.2420304,
                                "lng": 18.0935293
                            },
                            "door_code": ""
                        },
                        "distance": null,
                        "operational_hours": {
                            "mon": "10:00-20:00",
                            "tue": "10:00-20:00",
                            "wed": "10:00-20:00",
                            "thu": "10:00-20:00",
                            "fri": "10:00-20:00",
                            "sat": "10:00-18:00",
                            "sun": "11:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    }
                ],
                "time_slots": [
                    {
                        "id": "eqOd7n6l0Jk-a9p6MRwDqw",
                        "expires": "2018-05-11T15:00:00+02:00",
                        "start": "2018-05-14T00:00:00+02:00",
                        "end": "2018-05-14T00:00:00+02:00"
                    }
                ],
                "external_method_id": "",
                "default_addons": [],
                "supports": {
                    "search": false,
                    "door_code": false,
                    "courier_instructions": false
                },
                "meta": {}
            }
        ],
        "purchase_country": "SE",
        "purchase_currency": "SEK",
        "locale": "en-US",
        "choices": [
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "525172",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "525185",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "525175",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "525182",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "546472",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0101",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0013",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0251",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0101",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0013",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0251",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            }
        ],
        "expires_at": "2018-05-11T15:00:00+02:00",
        "search_address": {
            "postal_code": "12333",
            "country": "SE",
        }
    }
}

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):

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

{
    "locale": "en-US",
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "cart": {
        "currency": "SEK",
        "items": [{"sku": "1234"}]
    },
    "search_address": {
        "country": "SE",
        "postal_code": "11733",
        "address_lines": ["Mälarvarvsbacken 8"]
    }
}

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "session": {
        "id": "899d72b4-8f3b-48ba-a971-fad4d0fbfd2c",
        "token": "Y2xpZW50OjBlZjgzY2ZkYTdmMjQxYzJhNzYxYTI0ZDQ3NDZhOTg0",
        "status": "ACTIVE",
        "cart": {
            "currency": "SEK",
            "items": [
                {
                    "sku": "1234",
                }
            ],
        },
        "preselected_choice": {
            "shipping_method": "pnl-mpc",
            "location_ref": "588298",
            "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
            "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
        },
        "shipping_categories": [...],
        "shipping_options": [
            {
                "shipping_method": "pnl-mpc",
                "delivery_type": "pickup",
                "carrier": "PostNord",
                "product": "MyPack Collect",
                "price": 2500,
                "currency": "SEK",
                "locations": [
                    {
                        "external_id": "588298",
                        "name": "Nära Dej Jarans Livs",
                        "address": {
                            "name": "Nära Dej Jarans Livs",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Pålsundsgatan 4"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11731",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.31869159999999,
                                "lng": 18.0351015
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 315,
                                "duration": 5
                            },
                            "driving": {
                                "value": 2101,
                                "duration": 6
                            }
                        },
                        "operational_hours": {
                            "mon": "08:00-21:00",
                            "tue": "08:00-21:00",
                            "wed": "08:00-21:00",
                            "thu": "08:00-21:00",
                            "fri": "08:00-21:00",
                            "sat": "08:00-21:00",
                            "sun": "08:00-21:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "588288",
                        "name": "Hemköp Hornstull",
                        "address": {
                            "name": "Hemköp Hornstull",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Långholmsgatan 25"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11733",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.3160846,
                                "lng": 18.0340672
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 714,
                                "duration": 9
                            },
                            "driving": {
                                "value": 1403,
                                "duration": 5
                            }
                        },
                        "operational_hours": {
                            "mon": "08:00-22:00",
                            "tue": "08:00-22:00",
                            "wed": "08:00-22:00",
                            "thu": "08:00-22:00",
                            "fri": "08:00-22:00",
                            "sat": "09:00-22:00",
                            "sun": "09:00-22:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "588171",
                        "name": "ICA Nära Hornstull",
                        "address": {
                            "name": "ICA Nära Hornstull",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Bergsunds Strand 42"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11738",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.3156919,
                                "lng": 18.0325305
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 767,
                                "duration": 10
                            },
                            "driving": {
                                "value": 1138,
                                "duration": 3
                            }
                        },
                        "operational_hours": {
                            "mon": "08:00-22:00",
                            "tue": "08:00-22:00",
                            "wed": "08:00-22:00",
                            "thu": "08:00-22:00",
                            "fri": "08:00-22:00",
                            "sat": "09:00-22:00",
                            "sun": "09:00-22:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "592370",
                        "name": "Time Kungsholmen",
                        "address": {
                            "name": "Time Kungsholmen",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Hantverkargatan 40"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11221",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.329539,
                                "lng": 18.0398035
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 2388,
                                "duration": 31
                            },
                            "driving": {
                                "value": 3173,
                                "duration": 7
                            }
                        },
                        "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-18:00",
                            "sun": "09:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "592978",
                        "name": "Office Depot",
                        "address": {
                            "name": "Office Depot",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "S:t Eriksgatan 37"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11234",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.333445,
                                "lng": 18.0319098
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 2142,
                                "duration": 28
                            },
                            "driving": {
                                "value": 2523,
                                "duration": 6
                            }
                        },
                        "operational_hours": {
                            "mon": "09:00-19:00",
                            "tue": "09:00-19:00",
                            "wed": "09:00-19:00",
                            "thu": "09:00-19:00",
                            "fri": "09:00-19:00",
                            "sat": "11:00-16:00",
                            "sun": "",
                            "free_text": []
                        },
                        "meta": {}
                    }
                ],
                "time_slots": [
                    {
                        "id": "CBfJwq1wc6AlHVFwcOtFyA",
                        "expires": "2018-05-11T15:00:00+02:00",
                        "start": "2018-05-12T00:00:00+02:00",
                        "end": "2018-05-12T00:00:00+02:00"
                    }
                ],
                "external_method_id": "",
                "default_addons": [],
                "supports": {
                    "search": false,
                    "door_code": false,
                    "courier_instructions": false
                },
                "meta": {}
            },
            {
                "shipping_method": "dbs-pos",
                "delivery_type": "pickup",
                "carrier": "DB Schenker",
                "product": "Ombud Standard",
                "price": 2500,
                "currency": "SEK",
                "locations": [
                    {
                        "external_id": "0298",
                        "name": "Nära Dej Jarans Livs",
                        "address": {
                            "name": "Nära Dej Jarans Livs",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Pålsundsgatan 4"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11731",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.31869159999999,
                                "lng": 18.0351015
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 315,
                                "duration": 5
                            },
                            "driving": {
                                "value": 2101,
                                "duration": 6
                            }
                        },
                        "operational_hours": {
                            "mon": "08:00-21:00",
                            "tue": "08:00-21:00",
                            "wed": "08:00-21:00",
                            "thu": "08:00-21:00",
                            "fri": "08:00-21:00",
                            "sat": "09:00-21:00",
                            "sun": "09:00-21:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "0214",
                        "name": "Handlarn Bergsundsstrand",
                        "address": {
                            "name": "Handlarn Bergsundsstrand",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Slipgatan 11"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11739",
                            "country": "SE",
                            "coordinates": {
                                "lat": 59.3170181,
                                "lng": 18.0279062
                            },
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 784,
                                "duration": 10
                            },
                            "driving": {
                                "value": 784,
                                "duration": 2
                            }
                        },
                        "operational_hours": {
                            "mon": "09:00-21:00",
                            "tue": "09:00-21:00",
                            "wed": "09:00-21:00",
                            "thu": "09:00-21:00",
                            "fri": "09:00-21:00",
                            "sat": "10:00-21:00",
                            "sun": "10:00-21:00",
                            "free_text": []
                        },
                        "meta": {}
                    },
                    {
                        "external_id": "0032",
                        "name": "Liljeholms Spel",
                        "address": {
                            "name": "Liljeholms Spel",
                            "care_of": "",
                            "attn": "",
                            "address_lines": [
                                "Liljeholmstorget 30"
                            ],
                            "city": "Stockholm",
                            "region": "",
                            "postal_code": "11761",
                            "country": "SE",
                            "coordinates": null,
                            "door_code": ""
                        },
                        "distance": {
                            "walking": {
                                "value": 1760,
                                "duration": 23
                            },
                            "driving": {
                                "value": 2107,
                                "duration": 5
                            }
                        },
                        "operational_hours": {
                            "mon": "10:00-20:00",
                            "tue": "10:00-20:00",
                            "wed": "10:00-20:00",
                            "thu": "10:00-20:00",
                            "fri": "10:00-20:00",
                            "sat": "10:00-18:00",
                            "sun": "10:00-18:00",
                            "free_text": []
                        },
                        "meta": {}
                    }
                ],
                "time_slots": [
                    {
                        "id": "eqOd7n6l0Jk-a9p6MRwDqw",
                        "expires": "2018-05-11T15:00:00+02:00",
                        "start": "2018-05-14T00:00:00+02:00",
                        "end": "2018-05-14T00:00:00+02:00"
                    }
                ],
                "external_method_id": "",
                "default_addons": [],
                "supports": {
                    "search": false,
                    "door_code": false,
                    "courier_instructions": false
                },
                "meta": {}
            }
        ],
        "purchase_country": "SE",
        "purchase_currency": "SEK",
        "locale": "en-US",
        "external_id": "",
        "choices": [...],
        "expires_at": "2018-05-11T15:00:00+02:00",
        "search_address": {
            "address_lines": [
                "Mälarvarvsbacken 8"
            ],
            "postal_code": "11733",
            "country": "SE",
            "coordinates": {
                "lat": 59.32071,
                "lng": 18.0356114
            },
        }
    }
}

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:

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",
    "user_choice": {
        "shipping_method": "dbs-pos",
        "location_ref": "0032",
        "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
        "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
    }
}

The response contains updated session with user_choice field set (shipping options and categories were redacted for brevity):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "session": {
        "id": "899d72b4-8f3b-48ba-a971-fad4d0fbfd2c",
        "token": "Y2xpZW50OjBlZjgzY2ZkYTdmMjQxYzJhNzYxYTI0ZDQ3NDZhOTg0",
        "status": "ACTIVE",
        "cart": {
            "currency": "SEK",
            "items": [
                {
                    "sku": "1234",
                }
            ],
        },
        "user_choice": {
            "shipping_method": "dbs-pos",
            "location_ref": "0032",
            "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
            "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
        },
        "preselected_choice": {
            "shipping_method": "pnl-mpc",
            "location_ref": "588298",
            "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
            "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
        },
        "shipping_categories": [...],
        "shipping_options": [...],
        "purchase_country": "SE",
        "purchase_currency": "SEK",
        "choices": [
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "588298",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "588288",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "588171",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "592978",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "pnl-mpc",
                "location_ref": "592370",
                "time_slot_ref": "CBfJwq1wc6AlHVFwcOtFyA",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0298",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0298",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0214",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0214",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0032",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "ea9b519d-a1c3-4a15-aab1-68f7791d803f"
            },
            {
                "shipping_method": "dbs-pos",
                "location_ref": "0032",
                "time_slot_ref": "eqOd7n6l0Jk-a9p6MRwDqw",
                "shipping_category_ref": "11405d2f-0548-4fed-be10-c4cd3fa9a82e"
            }
        ],
        "expires_at": "2018-05-11T15:00:00+02:00",
        "search_address": {
            "address_lines": [
                "Mälarvarvsbacken 10"
            ],
            "postal_code": "11733",
            "country": "SE",
            "coordinates": {
                "lat": 59.32084,
                "lng": 18.036114
            },
        }
    }
}

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 session after it is completed.

Example complete session call with customer:

POST /v1/cos/session.complete 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",
    "customer": {
        "address": {
            "country": "SE",
            "city": "Stockholm",
            "postal_code": "11733",
            "address_lines": ["Mälarvarvsbacken 10"]
        }
    }
}

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.

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:

GET /v1/cos/session.get?899d72b4-8f3b-48ba-a971-fad4d0fbfd2c HTTP/1.1
Host: api.ingrid.com
Accept: application/json
Authorization: Bearer base64-encoded-api-token
Content-Type: application/json

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.

Object Definitions

AddLocationToSessionRequest

id
string
shipping_method
string
location_ref
string

AddLocationToSessionResponse

session

AdditionalInfo

courier_instructions
string
door_code
string

Address

Generic address entity

name
string
Customer name
care_of
string optional
Care of part of address
attn
string optional
Attention field
address_lines
string[]
List of address lines part of address
city
string
Name of the city
region
string optional
Region can be a state or a province
postal_code
string
Postal code (or zipcode in US)
country
string
Country should be specified as two uppercase letters (ISO Alpha-2). Example SE
coordinates
Coordinates readonly
Geolocation coordinates of the address
door_code
string optional
The door code to the main entrance

CarrierAddon

name
string
code
string
Identifier of the addon in carrier's system.
description
string

Cart

total_value
integer
currency
string
shipping_date
items
total_discount
integer
pre_order
boolean
voucher
string
cart_id
string
attributes
string[]

CartItem

sku
string
name
string
attributes
string[]
out_of_stock
boolean
dimensions
dimensionsDimensions
Dimensions of this cart item.
quantity
integer
Quantity of this item.
weight
integer
Weight of the object in gramms.

Choice

shipping_method
string
location_ref
string
time_slot_ref
string
shipping_category_ref
string

CompleteSessionAndPromoteToOrderRequest

CompleteSessionAndPromoteToOrderRequest is send as a final request. Either customer or customer_info needs to be present and have all customer data.

id
string
customer_info
CustomerInfo deprecated
CustomerInfo
warehouse_id
string
WarehouseID specifies from which warehouse order will be sent. If it is not supplied and site has only one warehouse, this warehouse will be used as sender. Otherwise order will have no sender.
customer
external_id
string

CompleteSessionAndPromoteToOrderResponse

session
tos_id
string

CompleteSessionAndUpdateOrderRequest

CompleteSessionAndUpdateOrderRequest is send as a final request. Either customer or customer_info needs to be present and have all customer data.

id
string
tos_id
string
customer_info
CustomerInfo deprecated
CustomerInfo
warehouse_id
string
WarehouseID specifies from which warehouse order will be sent. If it is not supplied and site has only one warehouse, this warehouse will be used as sender. Otherwise order will have no sender.
customer
external_id
string

CompleteSessionAndUpdateOrderResponse

session

CompleteSessionRequest

CompleteSessionRequest is send as a final request. Either customer or customer_info needs to be present and have all customer data.

id
string
customer_info
CustomerInfo deprecated
CustomerInfo
tos_id
string optional
TosID is id of an order, which was created from this session.
customer
external_id
string

CompleteSessionResponse

session

Coordinates

Geolocation coordinates

lat
number
Latitude
lng
number
Longitude

CreateSessionFromOrderRequest

CreateSessionFromOrderRequest provides session data needed to create a new session.

locale
string
Locale defined as lc-CC, see ISO 3166-1
external_id
string
tos_id
string
TosId specifies order, which will be used to create session

CreateSessionFromOrderResponse

session

CreateSessionRequest

CreateSessionRequest provides session data needed to create a new session.

purchase_country
string
purchase_currency
string
locale
string
Locale defined as lc-CC, see ISO 3166-1
customer_info
CustomerInfo deprecated
CustomerInfo
cart
external_id
string
tos_id
string optional
TosId specifies that this session is connected to an existing order
customer
search_address

CreateSessionResponse

session

CustomShippingLocation

shipping_method
string
location_ref
string
added_at
string

CustomerInfo

address
phone
string
email
string

DateTimeRange

start
string
Start DateTime in RFC3339.
end
string
End DateTime in RFC3339.

Distance

walking
driving

DistanceSpec

value
integer
duration
integer

GetSessionResponse

session

LegLocation

LegLocation represents a location that takes part in a delivery.

address
Address
Address of a location. This is optional when LocationType is WAREHOUSE or HOME, since these values can be obtained from the session.
location_type
external_id
string

LocationSearchResponse

locations

OperationalHours

mon
string
tue
string
wed
string
thu
string
fri
string
sat
string
sun
string
free_text
string[]

PickupLocation

external_id
string
name
string
address
distance
operational_hours
meta
object
location_type

Route

Route represents a list of delivery steps.

id
string
shipping_legs
ShippingLeg[]
ShippingLegs represent a list of delivery steps. For a non-chained delivery this will contain only one element.

SearchLocation

external_id
string
name
string
address
operational_hours
shipping_method
string

Session

A root object of COS system that holds data required by the widget. Whenever user selects a shipping option using the widget or anything is changed in a cart, session is updated and stored.

id
string
UUIDv4 identifier of the session. Generated when session is created. Used for updating, fetching and completing the session.
token
string
Authorization token used by the widget to fetch, update or complete sessions. Generated when the session is created.
status
string
customer_info
CustomerInfo deprecated
Customer Info is only supported for backwards compatibility, use Customer and Search Address instead.
cart
Cart
Cart details as items, their weight, dimentions, quantities as well as shipping date, cart total value and currency.
user_choice
Choice
User selection of shipping option. Everytime user selects different shipping option, this field is updated.
preselected_choice
Choice
Shipping option pre-selected by COS for the user. Matches shipping category with preselected flag set to true and reflects the best possible shipping option (based on sorting rules).
shipping_categories
ShippingCategory[]
Pre-configured shipping categories. All shipping options fall into one of category. If no shipping options are available (no search address provided), possible user choices are made based on categories instead.
shipping_options
ShippingOption[]
Real shipping options (as fetched from carrier integrations). Contain pickup locations with opening hours and time slots (possible delivery times).
purchase_country
string
Customer country.
purchase_currency
string
Customer currency.
locale
string
Customer locale.
external_id
string
Optional external ID to connect the session with an order on merchant side.
choices
Choice[]
List of possible choices generated based on shipping options or categories (if options are missing).
additional_information
AdditionalInfo
Additional information needed for delivery.
expires_at
string
Time of expiration of the first time slot (possible delivery time) for any shipping option.
tos_id
string
Transport order system ID. If the session was created from order, it is id of this order. Once the session is completed and promoted to order, tos_id stores id of this order. See TOS documentation for details.
custom_shipping_locations
customer
CustomerInfo
Customer's real home address.
search_address
Address
Lookup address for delivery. May be an office address if customer wants to pick up a package close to his/her work place.

ShippingCategory

id
string
name
string
price
integer deprecated
Use prices.
sort_order
integer
region_ids
string[]
shipping_methods
string[]
custom_text
string
custom_info_text
string
preselected
boolean
requirements
delivery_type
string
time_slot
external_id
string
currency
string
prices
object
group_id
string
custom_unavailable_text
string

ShippingCategoryRequirements

address
boolean
hide_shipping_options
boolean
use_price_from
boolean

ShippingLeg

ShippingLeg represents a single step of package delivery.

shipping_method
string
delivery_type
string
from
to

ShippingOption

shipping_method
string
delivery_type
string
carrier
string
product
string
price
integer deprecated
Use Prices on ShippingCategory.
currency
string deprecated
Use Currency on ShippingCategory.
locations
time_slots
external_method_id
string
default_addons
CarrierAddon[]
DefaultAddons are addons that are enabled by default.
supports
meta
object
routes
Route[]
Routes represent all possible combinations for delivery steps.

Supports

search
boolean
door_code
boolean
courier_instructions
boolean

TimeSlot

id
string
expires
string
start
string
end
string

UpdateSessionRequest

id
string
user_choice
customer_info
CustomerInfo deprecated
CustomerInfo
cart
additional_info
customer
search_address
external_id
string

UpdateSessionResponse

session

dimensionsDimensions

Dimensions of an object in millimeters.

height
integer
Height of the object in millimeters.
length
integer
Length of the object in millimeters.
width
integer
Width of the object in millimeters.