Service Rates ============= .. toctree:: :hidden: service-rates/weight-bracket 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. .. seealso:: https://api-specification.myparcel.com/#tag/ServiceRates Attributes ---------- .. list-table:: :header-rows: 1 :width: 100% :widths: 20 10 10 60 * - 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 - :doc:`object ` - - If a weight bracket is present, the price depends on the actual weight of the parcel and should be calculated. See :doc:`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 - :doc:`price ` - - The price of the service in cents. * - fuel_surcharge - :doc:`price ` - - The additional fuel surcharge of the service in cents (not included in ``price``). * - oversize_surcharge - :doc:`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``). .. list-table:: :header-rows: 1 :width: 100% :widths: 20 10 10 60 * - Relationship - Type - Required - Description * - contract - :doc:`contracts ` - ✓ - The contract this rate belongs to. * - service - :doc:`services ` - ✓ - The service this rate belongs to. * - service_options - :doc:`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 --------- .. raw:: html
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. .. list-table:: :header-rows: 1 :width: 100% :widths: 20 10 70 * - Parameter - Type - Description * - filter[has_active_contract] - boolean - A ``true`` value will filter services-rates that have **active** :doc:`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 :doc:`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** .. code-block:: http GET /service-rates HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/service-rates **Response** .. code-block:: json { "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" } } .. raw:: html
GET /service-rates/{service_rate_id} Retrieve a specific service rate. **Scope** Any of the following scopes: - ``organizations.manage`` **Request** .. code-block:: http 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** .. code-block:: json { "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" } } } .. raw:: html