Service Options

Service options can be added to a shipment to add extra’s to the chosen service (if available). Options are a generic resource since many carriers offer the same options, like delivery in the weekend. The added price of the service option depends on the used contract and service and is described in the service rate that links the shipment’s service and contract together.

Service Option

Attribute	Type	Description	Required
name	string	Option name, useful for displaying to users.	✓
code	string	Option code, which will be used in the request to the carrier.	✓
category	string enum: `delivery-window` `handover-method` `proof-of-delivery`	The category in which a service option belongs. Note that only one service option per category can be set on a shipment.
values_format	object	The format of additional values required for this service option using JSON Schema e.g. price input for Cash on Delivery options.

Endpoints

GET /service-options

Retrieving a list of service options.

Scope No scopes are required to retrieve service options.

Request

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

Response

{
  "data": [
    {
      "type": "service-options",
      "id": "4c675b1a-516c-4410-abff-d237fd45bcd0",
      "attributes": {
        "name": "Collection",
        "category": "handover-method",
        "code": "handover-method:collection"
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/service-options/4c675b1a-516c-4410-abff-d237fd45bcd0"
      }
    },
    {
      "type": "service-options",
      "id": "c290cfb7-f0ad-4c51-bf2d-be8952ad3d2f",
      "attributes": {
        "name": "Sunday Delivery",
        "category": "delivery-window",
        "code": "delivery-window:saturday"
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/service-options/c290cfb7-f0ad-4c51-bf2d-be8952ad3d2f"
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_records": 2
  },
  "links": {
    "self": "https://api.sandbox.myparcel.com/service-options?page[number]=1&page[size]=30",
    "first": "https://api.sandbox.myparcel.com/service-options?page[number]=1&page[size]=30",
    "last": "https://api.sandbox.myparcel.com/service-options?page[number]=1&page[size]=30"
  }
}

GET /service-options/{service_option_id}

Retrieving a specific service option.

Scope No scopes are required to retrieve service options.

Request

GET /service-options/{service_option_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/service-options/c290cfb7-f0ad-4c51-bf2d-be8952ad3d2f

Response

{
  "data": {
    "type": "service-options",
    "id": "c290cfb7-f0ad-4c51-bf2d-be8952ad3d2f",
    "attributes": {
      "name": "Sunday Delivery",
      "category": "delivery-window",
      "code": "delivery-window:saturday"
    },
    "links": {
      "self": "https://api.sandbox.myparcel.com/service-options/c290cfb7-f0ad-4c51-bf2d-be8952ad3d2f"
    }
  }
}