Services
========
.. toctree::
:hidden:
services/address-rules
services/transit-time
Services are provided by :doc:`carriers ` and can be used to send :doc:`shipments `. Services are offered from a specific region to a specific region.
.. seealso::
https://api-specification.myparcel.com/#tag/Services
Attributes
----------
====================== ========================================================================================================== ===========
Attribute Type Description
====================== ========================================================================================================== ===========
name string Service name (eg. Next day), useful for displaying to users.
code string Service code (eg. carrier-parcel-next-day), often composed of the carrier name and the service name, lower cased.
package_type string enum: ``parcel`` ``letterbox`` ``letter`` ``unstamped`` Type of package (eg. letter).
handover_method string enum: ``collection`` ``drop-off`` Available methods to hand the shipment to the carrier. Value ``collection`` means the carrier will pick up the shipment at the shipment's sender address while drop-off means the sender has to drop the shipment at a pickup-dropoff-location.
delivery_method string enum: ``pick-up`` ``delivery`` Delivery method for the carrier. Services with value ``pick-up`` means the carrier delivers the shipment at a pickup-dropoff-location while ``delivery`` means they deliver at the shipment's recipient address).
uses_volumetric_weight boolean Whether the carrier also takes the shipment's :doc:`volumetric weight ` into account when determining the price of a shipment with the chosen service.
delivery_days array of string enum: ``Monday`` ``Tuesday`` ``Wednesday`` ``Thursday`` ``Friday`` ``Saturday`` ``Sunday`` Textual representation of days of the week this service delivers shipments.
transit_time :doc:`transit time ` The minimum and maximum time it takes to deliver the shipment.
regions_from array of :doc:`address rules ` Address rules for where this service can ship from.
regions_to array of :doc:`address rules ` Address rules for where this service can ship to.
====================== ========================================================================================================== ===========
============ ========================================= ===========
Relationship Type Description
============ ========================================= ===========
carrier :doc:`carriers ` Carrier offering the service.
============ ========================================= ===========
Endpoints
---------
.. raw:: html
GET /services
Retrieving a list of services.
**Scope**
No scopes are required to retrieve services.
**Request parameters**
For more specific requests, the following parameters can be included as query parameters.
================================== ======= ===========
Parameter Type Description
================================== ======= ===========
filter[package_type] string Comma separated string of package types to filter the services on (eg. ``letterbox``).
filter[carrier] string Comma separated string of ids of carrier to filter the services on
filter[address_from][country_code] string Retrieve services for which the given `2-letter ISO country code `_ corresponds to the origin region of the service.
filter[address_from][state_code] string Retrieve services for which the given `1 to 3 letter ISO subdivision code `_ corresponds to the origin region of the service.
filter[address_from][postal_code] string Retrieve services for which the given postal code corresponds to the origin region of the service (may result in multiple services if postal code exists in different regions).
filter[address_to][country_code] string Retrieve services for which the given `2-letter ISO country code `_ corresponds to the destination region of the service.
filter[address_to][state_code] string Retrieve services for which the given `1 to 3 letter ISO subdivision code `_ corresponds to the destination region of the service.
filter[address_to][postal_code] string Retrieve services for which the given postal code corresponds to the destination region of the service (may result in multiple services if postal code exists in different regions).
filter[has_active_contract] boolean A ``true`` value will filter services that have **active** :doc:`contract ` associations. ``false`` will result in services that do **not** have active contract associations. To retrieve **all** services regardless of contract, omit this filter.
filter[delivery_method] string Using filter value ``pick-up`` will result in services that deliver to a :doc:`pickup-dropoff-location `. Using ``delivery`` filters services for which the carrier delivers the shipment to the ``recipient_address``.
filter[code] string Retrieve services for which the given filter 'code' corresponds to the code of the service.
================================== ======= ===========
**Request**
.. code-block:: http
GET /services HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/services
**Response**
.. code-block:: json
{
"data": [
{
"type": "services",
"id": "175a235f-aff5-4e44-87b5-3657b75c1deb",
"attributes": {
"name": "Next day",
"code": "carrier-parcel-next-day",
"package_type": "parcel",
"delivery_days": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"transit_time": {
"min": 1,
"max": 1
},
"handover_method": "drop-off",
"delivery_method": "pick-up",
"uses_volumetric_weight": true,
"regions_from": [
{
"country_code": "GB"
}
],
"regions_to": [
{
"country_code": "GB"
}
]
},
"relationships": {
"carrier": {
"data": {
"type": "carriers",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
},
"links": {
"related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
}
},
"region_from": {
"data": {
"type": "regions",
"id": "0b6ecd39-6072-4529-a031-f21247a91296"
},
"links": {
"related": "https://api.sandbox.myparcel.com/regions/0b6ecd39-6072-4529-a031-f21247a91296"
}
},
"region_to": {
"data": {
"type": "regions",
"id": "0b6ecd39-6072-4529-a031-f21247a91296"
},
"links": {
"related": "https://api.sandbox.myparcel.com/regions/0b6ecd39-6072-4529-a031-f21247a91296"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
}
}
],
"meta": {
"total_pages": 1,
"total_records": 1
},
"links": {
"self": "https://api.sandbox.myparcel.com/services?page[number]=1&page[size]=30",
"first": "https://api.sandbox.myparcel.com/services?page[number]=1&page[size]=30",
"last": "https://api.sandbox.myparcel.com/services?page[number]=1&page[size]=30"
}
}
.. raw:: html
GET /services/{service_id}
Retrieve a specific service.
**Scope**
No scopes are required to retrieve services.
**Request**
.. code-block:: http
GET /services/{service_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/service/175a235f-aff5-4e44-87b5-3657b75c1deb
**Response**
.. code-block:: json
{
"data": {
"type": "services",
"id": "175a235f-aff5-4e44-87b5-3657b75c1deb",
"attributes": {
"name": "Next day",
"code": "carrier-parcel-next-day",
"package_type": "parcel",
"delivery_days": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"transit_time": {
"min": 1,
"max": 1
},
"handover_method": "drop-off",
"delivery_method": "pick-up",
"uses_volumetric_weight": true,
"regions_from": [
{
"country_code": "GB"
}
],
"regions_to": [
{
"country_code": "GB"
}
]
},
"relationships": {
"carrier": {
"data": {
"type": "carriers",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
},
"links": {
"related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
}
},
"region_from": {
"data": {
"type": "regions",
"id": "0b6ecd39-6072-4529-a031-f21247a91296"
},
"links": {
"related": "https://api.sandbox.myparcel.com/regions/0b6ecd39-6072-4529-a031-f21247a91296"
}
},
"region_to": {
"data": {
"type": "regions",
"id": "0b6ecd39-6072-4529-a031-f21247a91296"
},
"links": {
"related": "https://api.sandbox.myparcel.com/regions/0b6ecd39-6072-4529-a031-f21247a91296"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
}
}
}
.. raw:: html