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).

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 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 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	carriers	✓	The carrier the contract is used for.
owner	brokers OR organizations	✓	The owner of the contract.
liability_coverages	array of liability coverages		The available liability coverages for this contract.

Endpoints

GET /contracts

Retrieving a list of contracts.

Scope

Any of the following scopes:

shipments.manage
organizations.manage

Request

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

Response

{
  "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"
  }
}

GET /contracts/{contract_id}

Retrieving a specific contract.

Scope

Any of the following scopes:

shipments.manage
organizations.manage

Request

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

{
  "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"
          }
        ]
      }
    }
  }
}

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

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

{
  "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"
  }
}

POST /contracts

Create a contract.

Scope

Any of the following scopes:

organizations.manage

Request

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

{
  "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"
        }
      }
    }
  }
}

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”

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

{
  "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"
        }
      }
    }
  }
}