# Create a quote

`POST /client_api/v2/quotes`

Describe the shipment, and we price it with each carrier that can take it. Each estimate in the answer can be booked with Create an order.

## Body

- `purpose_of_shipment_id` (integer, required): The incoterm the goods move under, which settles who pays duties and taxes. Take the id from List purposes of shipment. Ids differ between the sandbox and production.
- `reason_for_shipment_id` (integer): Why the goods are moving, for customs. Take the id from List reasons for shipment. Left out, we use documents for a document shipment and our default reason for anything else. Ids differ between the sandbox and production.
- `value_of_goods` (integer, required): What the goods are worth in total, at least 1. Customs duties and insurance are worked out from it.
- `value_of_goods_currency_id` (string): The currency of `value_of_goods` and of each item's value, as a three-letter code from List currencies.
- `description_of_contents` (string): What is in the shipment, in a few words a customs officer understands. At most 70 characters.
- `mass_unit` (enum, required): The unit every weight in this request is in. Possible enum values: `kg`, `lb`.
- `distance_unit` (enum, required): The unit every package size in this request is in. Possible enum values: `cm`, `inch`.
- `is_document` (boolean): `true` when the shipment holds only papers. Documents need no items declared.
- `is_stackable` (boolean): `true` when other freight may be stacked on top of the packages.
- `is_liftgate_required` (boolean): `true` when the vehicle needs a lift to load or unload, because there is no loading dock.
- `is_shipment_protection_required` (boolean): `true` to insure the goods for their declared value.
- `origin_address` (object): Where the carrier collects the goods. Needed to price the shipment.
  - `name` (string): The person to ask for. At most 35 characters.
  - `company` (string): The company at the address. At most 35 characters.
  - `address_1` (string): The street address. At most 34 characters.
  - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters.
  - `city` (string): The city or town. At most 20 characters.
  - `province` (string): The province, state or county.
  - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one.
  - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production.
  - `email` (string): An email address for the person at the address. Carriers use it for delivery notices.
  - `phone` (string): A phone number for the person at the address. At most 15 characters.
  - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`.
- `destination_address` (object): Where the goods are delivered. Needed to price the shipment.
  - `name` (string): The person to ask for. At most 35 characters.
  - `company` (string): The company at the address. At most 35 characters.
  - `address_1` (string): The street address. At most 34 characters.
  - `address_2` (string): A second address line, such as a floor or unit. At most 34 characters.
  - `city` (string): The city or town. At most 20 characters.
  - `province` (string): The province, state or county.
  - `postal_code` (string): The postal code. Some countries, such as Ireland, refuse an address without one.
  - `country_id` (integer, required): The country. Take the id from List countries. Ids differ between the sandbox and production.
  - `email` (string): An email address for the person at the address. Carriers use it for delivery notices.
  - `phone` (string): A phone number for the person at the address. At most 15 characters.
  - `classification` (enum): Whether the address is a business or a home. Carriers charge more to deliver to a home. Possible enum values: `business`, `residential`.
- `packages` (array of objects): Each box or pallet in the shipment. Needed to price the shipment.
  - `weight` (number, required): What the package weighs, in `mass_unit`.
  - `length` (integer, required): The package's length, in `distance_unit`.
  - `width` (integer, required): The package's width, in `distance_unit`.
  - `height` (integer, required): The package's height, in `distance_unit`.
- `hs_codes` (array of objects): Each kind of item in the shipment, as customs sees it. Leave out for a document shipment.
  - `code` (string, required): The item's tariff code (HS code), at least six digits.
  - `country_id` (integer, required): The country the item was made in. Take the id from List countries. Ids differ between the sandbox and production.
  - `description` (string, required): What the item is, in plain words. At most 250 characters.
  - `quantity` (integer): How many of this item are in the shipment.
  - `item_value` (number, required): What one item is worth, in `value_of_goods_currency_id`.
  - `item_mass` (number, required): What one item weighs, in `mass_unit`.

## Returns

Returns the quote.

- `quote` (object, required): The quote.
  - `id` (integer, required): The quote's id.
  - `dirty` (boolean, required): Always `false`. Nothing sets it.
  - `errors` (array of values, required): Why a carrier could not price the shipment, one message per carrier that refused. Empty when every carrier priced it.
  - `estimate_taxes_and_duties` (boolean, required): `true` when the estimates include the destination's duties and taxes.
  - `estimates` (array of objects, required): One estimate per carrier service that could take the shipment. Book one with Create an order.
    - `billable_weights` (object, required): The weights the carrier charges on, in metric and in imperial units.
      - `metric` (object, required): The weights in kilograms, the sizes in centimetres and the volume in cubic metres.
        - `packages` (integer, required): How many packages there are.
        - `mass_unit` (string, required): Always `kg`.
        - `distance_unit` (string, required): Always `cm`.
        - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size.
        - `weight` (number, required): What the packages weigh together.
        - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`.
        - `volume` (number, required): The packages' volume together.
      - `imperial` (object, required): The weights in pounds, the sizes in inches and the volume in cubic feet.
        - `packages` (integer, required): How many packages there are.
        - `mass_unit` (string, required): Always `lb`.
        - `distance_unit` (string, required): Always `inches`. A request spells the same unit `inch`.
        - `volumetric_weight` (number, required): The weight the carrier works out from the packages' size.
        - `weight` (number, required): What the packages weigh together.
        - `billable_weight` (number, required): The weight the carrier charges on, the larger of `weight` and `volumetric_weight`.
        - `volume` (number, required): The packages' volume together.
    - `estimate_id` (integer, required): The estimate's id. Book it by sending it as an order's `quote_estimate_id`.
    - `line_items` (array of objects, required): What the price is made of, one charge per line.
      - `cost` (number, required): What the charge costs, in `currency_id`.
      - `currency_id` (string, required): The currency the company is billed in.
      - `description` (string, required): The charge, such as freight or fuel surcharge.
    - `quote_expired` (boolean, required): `true` when this price no longer holds, because another estimate was booked or the shipment changed. Get a new quote.
    - `shipping_company` (string, required): The carrier.
    - `shipping_service` (string, required): The carrier's service, such as International Priority.
  - `hub_transit` (boolean, required): `true` when the shipment goes through one of our hubs on the way.

## Errors

- `400 Bad Request`: The request body isn't valid JSON, or something failed on our side.
- `401 Unauthorized`: The token is missing, expired or invalid. Sign in again.
- `422 Unprocessable Content`: The request was refused. `error` says why in one sentence, and `errors` lists each reason.
- `429 Too Many Requests`: Too many requests. Wait a little and try again.

## Example request (curl)

```bash
curl -X POST "https://sandbox-api.vatit-stream.com/client_api/v2/quotes" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose_of_shipment_id": 73,
    "reason_for_shipment_id": 45,
    "value_of_goods": 18500,
    "value_of_goods_currency_id": "ZAR",
    "description_of_contents": "Cotton shirts and denim trousers",
    "mass_unit": "kg",
    "distance_unit": "cm",
    "is_document": false,
    "is_stackable": true,
    "is_liftgate_required": false,
    "is_shipment_protection_required": false,
    "origin_address": {
      "name": "Thandi Mokoena",
      "company": "Global Trade Corp",
      "address_1": "14 Bree Street",
      "address_2": "Unit 3",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "8001",
      "country_id": 23,
      "email": "dispatch@globaltradecorp.example",
      "phone": "+27 21 555 0142",
      "classification": "business"
    },
    "destination_address": {
      "name": "Oliver Bennett",
      "company": "Bennett & Hale Ltd",
      "address_1": "221 Shoreditch High Street",
      "address_2": "Floor 2",
      "city": "London",
      "province": "Greater London",
      "postal_code": "E1 6PJ",
      "country_id": 24,
      "email": "goods-in@bennetthale.example",
      "phone": "+44 20 7946 0321",
      "classification": "business"
    },
    "packages": [
      {
        "weight": 12.5,
        "length": 60,
        "width": 40,
        "height": 35
      }
    ],
    "hs_codes": [
      {
        "code": "620342",
        "country_id": 23,
        "description": "Men'\''s cotton trousers",
        "quantity": 40,
        "item_value": 250,
        "item_mass": 0.2
      },
      {
        "code": "620520",
        "country_id": 23,
        "description": "Men'\''s cotton shirts",
        "quantity": 60,
        "item_value": 141.67,
        "item_mass": 0.075
      }
    ]
  }'
```

## Example response (201)

```json
{
  "quote": {
    "id": 39,
    "dirty": false,
    "errors": [],
    "estimate_taxes_and_duties": false,
    "estimates": [
      {
        "billable_weights": {
          "metric": {
            "packages": 1,
            "mass_unit": "kg",
            "distance_unit": "cm",
            "volumetric_weight": 16.8,
            "weight": 12.5,
            "billable_weight": 16.8,
            "volume": 0.084
          },
          "imperial": {
            "packages": 1,
            "mass_unit": "lb",
            "distance_unit": "inches",
            "volumetric_weight": 37.04,
            "weight": 27.56,
            "billable_weight": 37.04,
            "volume": 2.9664316254643865
          }
        },
        "estimate_id": 34,
        "line_items": [
          {
            "cost": 2184.5,
            "currency_id": "ZAR",
            "description": "Freight"
          },
          {
            "cost": 393.21,
            "currency_id": "ZAR",
            "description": "Fuel surcharge"
          },
          {
            "cost": 450,
            "currency_id": "ZAR",
            "description": "Customs clearance"
          }
        ],
        "quote_expired": false,
        "shipping_company": "FedEx",
        "shipping_service": "International Priority"
      }
    ],
    "hub_transit": false
  }
}
```