Service Rates

Service rates determine the price, dimensions and available options for a given service. A user has access to service rates that are related to the contracts they have access to.

Attributes

Attribute	Type	Required	Description
weight_min	integer	✓	The minimum weight in grams a shipment should have for this service rate to apply to it.
weight_max	integer	✓	The maximum weight in grams a shipment should have for this service rate to apply to it.
weight_bracket	object		If a weight bracket is present, the price depends on the actual weight of the parcel and should be calculated. See weight-bracket calculation.
length_max	integer		The maximum length of the shipment in mm.
width_max	integer		The maximum width of the shipment in mm.
height_max	integer		The maximum height of the shipment in mm.
volume_max	float		The maximum volume of the shipment in liters (dm3).
is_dynamic	boolean		When a service rate is dynamic, it’s price depends on complicated carrier logic. You can use the `/get-dynamic-service-rates` RPC endpoint to retrieve the current rates from the carrier.
price	price		The price of the service in cents.
fuel_surcharge	price		The additional fuel surcharge of the service in cents (not included in `price`).
oversize_surcharge	price		The oversize surcharge is an additional fee that is charged when the length of a shipment (longest dimension) exceeds the `length_max` field of the service rate (not included in `price`).
includes_vat	boolean	✓	Indicates whether VAT is included in the price returned by the API (default `false`).

Relationship	Type	Required	Description
contract	contracts	✓	The contract this rate belongs to.
service	services	✓	The service this rate belongs to.
service_options	service-options		The service service options that are available for this contract and service combination. The price and whether it is always included are available in the meta.

Endpoints

GET /service-rates

Retrieving a list of all the service rates available to the current user.

Scope Any of the following scopes:

organizations.manage
shipments.manage

Request parameters For more specific requests, the following parameters can be included as query parameters.

Parameter	Type	Description
filter[has_active_contract]	boolean	A `true` value will filter services-rates that have active contract associations. `false` will result in service-rates that do not have active contract associations. To retrieve all service-rates regardless of contract, omit this filter (not advised).
filter[weight]	integer	Weight in grams to filter on. This will only return service-rates for which the following is true `weight_min ≤ filter[weight] ≤ weight_max`. Service rates with a weight bracket will have their `bracket_price` calculated with this weight, you can find this in the `meta` of each rate.
filter[volume]	float	Volume in liters (dm3) to filter on. Use together with weight filter for the most accurate results. This is used to calculate the volumetric weight, using the `volumetric_weight_divisor` of the related service. (only applies to service-rates for services that use volumetric_weight).
filter[service]	string	Comma separated string of service ids to filter the service rates by.
filter[contract]	string	Comma separated string of contract ids to filter the service rates by.

Request

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

Response

{
  "data": [
    {
      "type": "service-rates",
      "id": "09a8f83a-bc8d-4598-81e6-ebf9d59a186a",
      "attributes": {
        "weight_min": 0,
        "weight_max": 2000,
        "length_max": 300,
        "width_max": 200,
        "height_max": 200,
        "volume_max": 12,
        "price": {
          "amount": 995,
          "currency": "EUR"
        }
      },
      "relationships": {
        "contract": {
          "data": {
            "type": "contracts",
            "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
          },
          "links": {
            "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        },
        "service": {
          "data": {
            "type": "services",
            "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
          },
          "links": {
            "related": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
          }
        },
        "service_options": {
          "data": [
            {
              "type": "service-options",
              "id": "4c675b1a-516c-4410-abff-d237fd45bcd0",
              "meta": {
                "price": {
                  "amount": 995,
                  "currency": "EUR"
                },
                "included": true
              }
            }
          ]
        }
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/service-rates/c9ce29a4-6325-11e7-907b-a6006ad3dba0"
      }
    }
  ],
  "meta": {
    "total_pages": 13,
    "total_records": 373
  },
  "links": {
    "self": "https://api.sandbox.myparcel.com/service-rates?page[number]=3&page[size]=30",
    "first": "https://api.sandbox.myparcel.com/service-rates?page[number]=1&page[size]=30",
    "prev": "https://api.sandbox.myparcel.com/service-rates?page[number]=2&page[size]=30",
    "next": "https://api.sandbox.myparcel.com/service-rates?page[number]=4&page[size]=30",
    "last": "https://api.sandbox.myparcel.com/service-rates?page[number]=13&page[size]=30"
  }
}

GET /service-rates/{service_rate_id}

Retrieve a specific service rate.

Scope

Any of the following scopes:

organizations.manage

Request

GET /shops/{service_rate_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/service-rates/09a8f83a-bc8d-4598-81e6-ebf9d59a186a

Response

{
  "data": {
    "type": "service-rates",
    "id": "09a8f83a-bc8d-4598-81e6-ebf9d59a186a",
    "attributes": {
      "weight_min": 0,
      "weight_max": 2000,
      "length_max": 300,
      "width_max": 200,
      "height_max": 200,
      "volume_max": 12,
      "price": {
        "amount": 995,
        "currency": "EUR"
      }
    },
    "relationships": {
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        },
        "links": {
          "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "175a235f-aff5-4e44-87b5-3657b75c1deb"
        },
        "links": {
          "related": "https://api.sandbox.myparcel.com/services/175a235f-aff5-4e44-87b5-3657b75c1deb"
        }
      },
      "service_options": {
        "data": [
          {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0",
            "meta": {
              "price": {
                "amount": 995,
                "currency": "EUR"
              },
              "included": true
            }
          }
        ]
      }
    },
    "links": {
      "self": "https://api.sandbox.myparcel.com/service-rates/c9ce29a4-6325-11e7-907b-a6006ad3dba0"
    }
  }
}