Collection time slots
=====================

When booking a collection with a carrier, some carriers offer an option to
retrieve specific time slots. This is useful if you want to ensure that the
carrier will come collect your shipments when you expect them to.

.. seealso::
    https://api-specification.myparcel.com/#tag/Carriers/paths/~1carriers~1%7Bcarrier_id%7D~1collection-time-slots/get

Collection time slots can be retrieved by using the following endpoint:

.. code-block:: http

    GET /carriers/{carrier_id}/collection-time-slots HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200

Request parameters
------------------
A few query parameters are available and mandatory in order to use this endpoint:

==============  ==================  ==========  ==================================================================================================
Parameter       Type                Required    Description
==============  ==================  ==========  ==================================================================================================
country_code    string              ✓           ISO 3166-1 alpha-2 country code of where to request collection times for.
postal_code     string              ✓           Postal code of where to request collection times for.
date_from       string or number    ✓           Date string in ISO 8601 format or unix timestamp of the day(s) to request time slots for.
date_to         string or number    ✓           Date string in ISO 8601 format or unix timestamp of the day(s) to request time slots for.
service_code    string                          Service codes of services to request collection times for. If not provided, all services are used.
==============  ==================  ==========  ==================================================================================================

Response
--------
This endpoint will return a set of :doc:`time slots </api/resources/common-objects/time-slots>` objects for the given parameters, if available.

.. code-block:: json

    {
      "data": [
        {
          "type": "collection-time-slots",
          "id": "be7f6752-34e0-49a1-a832-bcc209450ea9_1648110600_1648112399",
          "attributes": {
            "from": 1648110600,
            "to": 1648112399
          },
          "relationships": {
            "carrier": {
              "data": {
                "type": "carriers",
                "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
              }
            }
          }
        },
        {
          "type": "collection-time-slots",
          "id": "be7f6752-34e0-49a1-a832-bcc209450ea9_1648112400_1648114200",
          "attributes": {
            "from": 1648112400,
            "to": 1648114200
          },
          "relationships": {
            "carrier": {
              "data": {
                "type": "carriers",
                "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
              }
            }
          }
        }
      ],
      "meta": {
        "total_pages": 13,
        "total_records": 373
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200&page[number]=3&page[size]=30",
        "first": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200&page[number]=1&page[size]=30",
        "prev": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200&page[number]=2&page[size]=30",
        "next": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200&page[number]=4&page[size]=30",
        "last": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/collection-time-slots?country_code=GB&postal_code=NW1%206XE&date_from=1648110600&date_to=1648114200&page[number]=13&page[size]=30"
      }
    }