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 `_ format. credentials See ``credentials_format`` for :doc:`carriers resource ` 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 ` 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 ` ✓ The carrier the contract is used for. owner :doc:`brokers ` OR :doc:`organizations ` ✓ The owner of the contract. liability_coverages array of :doc:`liability coverages ` The available liability coverages for this contract. =================== ============================================================================================== ======== =========== Endpoints --------- .. raw:: html
GET /contracts 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
GET /contracts/{contract_id} 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
GET /carriers/{carrier_id}/contracts 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
POST /contracts 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
PATCH /contracts/{contract_id} 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