Adding liability coverage

Liability coverage can be added to a shipment to cover damage or loss of valuable goods when sending them through the MyParcel.com API. It is important to cover the contents of a package to their actual value. Because of this, whenever liability coverage is available for a contract, it will often be available for different “value groups”, covering a higher value for a higher price. This concerns broker-offered liability coverage. Carrier liability coverage might be available as a service option.

When is liability coverage available?

At this moment, liability coverage is only available for contracts provided by MyParcel.com and not custom contracts. To find out if liability coverage is available for a shipment and up to how much value can be covered, a call to the GET /contracts/{contract_id} endpoint should be made to retrieve the contract you intend to use with your shipment. The API will respond with the contracts resource and if the contract has liability coverage available, it will be listed in the relationships of the retrieved response.

{
  "data": {
    "type": "contracts",
    "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
    "attributes": {
      "name": "MyParcel.com contract",
      "currency": "EUR",
      "status": "active"
    },
    "relationships": {
      "carrier": {
        "data": {
          "type": "carriers",
          "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
        },
        "links": {
          "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
        }
      },
      "owner": {
        "data": {
          "type": "brokers",
          "id": "a294ee55-bc94-4890-b734-afd56c158f95"
        },
        "links": {
          "related": "https://api.sandbox.myparcel.com/brokers/a294ee55-bc94-4890-b734-afd56c158f95"
        }
      },
      "liability_coverages": {
        "data": [
          {
            "type": "liability-coverages",
            "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
          }
        ]
      }
    }
  }
}

Attaching liability coverage to a shipment

Attaching liability coverage to a shipment is quite easy. The same way that a contract, service, shop and service options are attached to a shipment, liability coverage can be passed as a relationship on a shipment. Note that only one liability coverage resource can be attached to a shipment at a time. It is therefore important to choose the correct liability coverage for the value of your shipment.

Warning

When attaching liability coverage to a shipment, make sure the contract relationship on the liability coverage corresponds to the contract relationship on the to-be-created shipment.

{
  "data": {
    "type": "shipments",
    "attributes": {
      "...": "..."
    },
    "relationships": {
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      },
      "service": {
        "data": {
          "type": "services",
          "id": "af5e65b6-a709-4f61-a565-7c12a752482f"
        }
      },
      "contract": {
        "data": {
          "type": "contracts",
          "id": "448e55b3-0829-4783-a9ca-1078697cdb46"
        }
      },
      "liability_coverage": {
        "data": {
          "type": "liability-coverages",
          "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
        }
      }
    }
  }
}

Carrier liability coverage

To add the carrier-offered liability coverage, include the liability coverage service option ID when creating a shipment in the MyParcel API. You can find the service option ID by calling GET /service-options (see service options documentation for more information). Additionally, you are required to set liability coverage amount and currency.

Here’s a sample JSON snippet for adding the “liability coverage” service option to your shipment:

"service_options": {
    "data": [
        {
            "type": "service-options",
            "id": "4c675b1a-516c-4410-abff-d237fd45bcd0",
            "meta": {
                "values": {
                    "amount": 1200,
                    "currency": "EUR"
                }
            }
        }
    ]
},