Contracts
=========

Contracts define the service, service options, and prices available for a carrier. A contract might be available because it is shared with you or because you added your own contract (including API credentials for that carrier).

.. seealso::
    https://api-specification.myparcel.com/#tag/Contracts

Attributes
----------

================================  ==================================================================================  ==========  ===========
Attribute                         Type                                                                                Required    Description
================================  ==================================================================================  ==========  ===========
name                              string                                                                              ✓           A name for users to recognize the contract by.
currency                          string enum: ``EUR`` ``GBP``                                                        ✓           Currency code in `ISO 4217 <https://en.wikipedia.org/wiki/ISO_4217>`_ format.
credentials                       See ``credentials_format`` for :doc:`carriers resource </api/resources/carriers/>`  write-only  The carriers resource has a ``credentials_format`` describing how the credentials for that specific carrier should be provided. Credentials will not be returned for a get request and are stored encrypted.
status                            string enum: ``pending`` ``active`` ``inactive`` ``invalid``                        read-only   Newly created contracts are pending until verified. The user can manually switch between active and inactive once verified. After updating credentials, the contract goes back to pending. If verification fails, the contract will become invalid.
volumetric_weight_divisor_factor  integer                                                                             ✓           If your contractual agreements with the carrier contain a :doc:`volumetric weight </api/resources/shipments/physical-properties/volumetric-weight>` formula that uses a different divisor than the ``volumetric_weight_divisor``` on our Service resource, you can use this factor to increase or decrease the divisor. For example a factor of 1.25 would change a divisor of 4000 to 5000.
================================  ==================================================================================  ==========  ===========

===================  ==============================================================================================  ========  ===========
Relationship         Type                                                                                            Required  Description
===================  ==============================================================================================  ========  ===========
carrier              :doc:`carriers </api/resources/carriers>`                                                       ✓         The carrier the contract is used for.
owner                :doc:`brokers </api/resources/brokers>` OR :doc:`organizations </api/resources/organizations>`  ✓         The owner of the contract.
liability_coverages  array of :doc:`liability coverages </api/resources/liability-coverages>`                                  The available liability coverages for this contract.
===================  ==============================================================================================  ========  ===========

Endpoints
---------

.. raw:: html

    <details>
        <summary><a>GET /contracts</a></summary>

Retrieving a list of contracts.

**Scope**

Any of the following scopes:

- ``shipments.manage``
- ``organizations.manage``

**Request**

.. code-block:: http

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

**Response**

.. code-block:: json

    {
      "data": [
        {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
          "attributes": {
            "name": "My Custom 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": "organizations",
                "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
              }
            },
            "liability_coverages": {
              "data": [
                {
                  "type": "liability-coverages",
                  "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
                }
              ]
            }
          }
        }
      ],
      "meta": {
        "total_pages": 13,
        "total_records": 373
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/contracts?page[number]=3&page[size]=30",
        "first": "https://api.sandbox.myparcel.com/contracts?page[number]=1&page[size]=30",
        "prev": "https://api.sandbox.myparcel.com/contracts?page[number]=2&page[size]=30",
        "next": "https://api.sandbox.myparcel.com/contracts?page[number]=4&page[size]=30",
        "last": "https://api.sandbox.myparcel.com/contracts?page[number]=13&page[size]=30"
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>GET /contracts/{contract_id}</a></summary>

Retrieving a specific contract.

**Scope**

Any of the following scopes:

- ``shipments.manage``
- ``organizations.manage``

**Request**

.. code-block:: http

    GET /contracts/{contract_id} HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff

**Response**

.. code-block:: json

    {
      "data": {
        "type": "contracts",
        "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
        "attributes": {
          "name": "My Custom 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": "organizations",
              "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
            }
          },
          "liability_coverages": {
            "data": [
              {
                "type": "liability-coverages",
                "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
              }
            ]
          }
        }
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>GET /carriers/{carrier_id}/contracts</a></summary>

Get all contracts for a specific carrier.

**Scope**

Any of the following scopes:

- ``shipments.manage``
- ``organizations.manage``

**Request parameters**

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

=========  ======  ===========
Parameter  Type    Description
=========  ======  ===========
include    string  Comma separated string of the relationship names you want to include the data of. The relationships that can be included are: ``carrier`` and ``owner``.
=========  ======  ===========

**Request**

.. code-block:: http

    GET /carriers/{carrier_id}/contracts HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts

**Response**

.. code-block:: json

    {
      "data": [
        {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
          "attributes": {
            "currency": "EUR",
            "name": "My Custom Contract",
            "status": "active",
            "created_at": 1504801719
          },
          "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": "organizations",
                "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
              },
              "links": {
                "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
              }
            },
            "liability_coverages": {
              "data": [
                {
                  "type": "liability-coverages",
                  "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4"
                }
              ]
           }
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff"
          }
        }
      ],
      "meta": {
        "total_pages": 13,
        "total_records": 373
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts?page[number]=3&page[size]=30",
        "first": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts?page[number]=1&page[size]=30",
        "prev": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts?page[number]=2&page[size]=30",
        "next": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts?page[number]=4&page[size]=30",
        "last": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9/contracts?page[number]=13&page[size]=30"
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>POST /contracts</a></summary>

Create a contract.

**Scope**

Any of the following scopes:

- ``organizations.manage``

**Request**

.. code-block:: http

    POST /contracts HTTP/1.1
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/contracts

    {
      "data": {
        "type": "contracts",
        "attributes": {
          "name": "My Custom Contract",
          "currency": "EUR",
          "credentials": {
            "api_username": "your_api_username",
            "api_password": "your_api_password"
          }
        },
        "relationships": {
          "carrier": {
            "data": {
              "type": "carriers",
              "id": "be7f6752-34e0-49a1-a832-bcc209450ea9"
            }
          },
          "owner": {
            "data": {
              "type": "organizations",
              "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
            }
          }
        }
      }
    }

**Response**

.. code-block:: json

    {
      "data": {
        "type": "contracts",
        "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
        "attributes": {
          "name": "My Custom 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": "organizations",
              "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
            }
          }
        }
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>PATCH /contracts/{contract_id}</a></summary>

Update an existing contract.

**Scope**

Any of the following scopes:

- ``organizations.manage``

**Request**

In this example we're changing the status of the contract to "inactive"

.. code-block:: http

    PATCH /contracts/{contract_id} HTTP/1.1
    Accept: application/vnd.api+json
    Content-Type: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff

    {
      "data": {
        "type": "contracts",
        "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
        "attributes": {
          "status": "inactive"
        }
      }
    }

**Response**

.. code-block:: json

    {
      "data": {
        "type": "contracts",
        "id": "2cb32706-5762-4b96-9212-327e6afaeeff",
        "attributes": {
          "name": "My Custom Contract",
          "currency": "EUR",
          "status": "inactive"
        },
        "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": "organizations",
              "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
            },
            "links": {
              "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
            }
          }
        }
      }
    }

.. raw:: html

    </details>