Services

Services are provided by carriers and can be used to send shipments. Services are offered from a specific region to a specific region.

See also

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.

information

array of objects with type and body

Additional information about the service.

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 volumetric weight into account when determining the price of a shipment with the chosen service.

volumetric_weight_divisor

integer

The volumetric weight divisor is used to calculate the volumetric weight of a shipment. Multiplying the length (mm) x width (mm) x height (mm) of a shipment and dividing it by this number will result in the volumetric weight (g).

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

transit time

The minimum and maximum time it takes to deliver the shipment.

regions_from

array of address rules

Address rules for where this service can ship from.

regions_to

array of address rules

Address rules for where this service can ship to.

Relationship

Type

Description

carrier

carriers

Carrier offering the service.

Endpoints

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

GET /services HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/services

Response

{
  "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"
  }
}
GET /services/{service_id}

Retrieve a specific service.

Scope

No scopes are required to retrieve services.

Request

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

{
  "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"
    }
  }
}