Provide rates

POST https://your-endpoint.com/rates

Fulfil requests rates in two situations

Case 1: For a customer shipment

This is the most common case where the rates are requested for a package. If the rates are requested after the items are packaged, then the rate request will include precise packaging information. When rates are requested before packing, Fulfil makes an estimate on the weight and the packages that will be used.

Case 2: For a sales order

Many merchants also use Fulfil to enter orders (usually wholesale). At the time of processing the sales order, an user may want to provide the customer with an estimate of their shipping (or charge shipping on the order). The rate request sent in this situation also has packaging information, but is only likely to contain 1 package.

If the weight of the package exceeds per package limits, we recommend splitting packages on your end and sending a rate that assumes multiple packages being used. This is only an estimate and most merchants will include a markup on rates to protect margins.

Example Request

POST <YOUR CALLBACK URL>/rates

JSON

{
  "account_id": "123456789",
  "origin": {
    "name": "Joe Santiego",
    "street1": "444 Castro St",
    "street2": "Suite 1200",
    "city": "Mountain view",
    "zip": "94041",
    "country": "US",
    "state": "CA",
    "email": "[email protected]",
    "phone": "[phone]",
    "company": "Fulfil.IO Inc.",
    "validation_status": null,
    "address_type": null,
    "tax_identification": null
  },
  "destination": {
    "name": "Joe Santiego",
    "street1": "444 Castro St",
    "street2": "Suite 1200",
    "city": "Mountain view",
    "zip": "94041",
    "country": "US",
    "state": "CA",
    "email": "[email protected]",
    "phone": "[phone]",
    "company": "Fulfil.IO Inc.",
    "validation_status": null,
    "address_type": null,
    "tax_identification": null
  },
  "packages": [
    {
      "length": 4,
      "width": 4,
      "height": 5,
      "dimension_unit": "in",
      "weight": 7,
      "weight_unit": "lb",
      "carrier_code": null,
      "machinable": false,
      "dhl_ecommerce_dangerous_goods_category": null,
      "easyship_category": null,
      "description": "Merchandise",
      "quantity": null,
      "amount": null,
      "reference": null
    }
  ],
// The "customs" property will only be populated if the origin and destination 
// country are different (international shipment)
  "customs": {
    "customs_certify": true,
    "contents_type": "other",
    "customs_signer": null,
    "contents_explanation": "Electronic Items",
    "non_delivery_option": "return",
    "items": [
      {
        "description": "iPhone 7",
        "quantity": 1,
        "value": 99,
        "currency": "USD",
        "weight": 1,
        "weight_unit": "lb",
        "hs_code": null,
        "sku": null,
        "country_of_origin": "US",
        "_options": {}
      },
      {
        "description": "MacBook Pro",
        "quantity": 2,
        "value": 40,
        "currency": "USD",
        "weight": 6,
        "weight_unit": "lb",
        "hs_code": null,
        "sku": null,
        "country_of_origin": "US",
        "_options": {}
      }
    ],
    "incoterm": null,
    "invoice_number": null,
    "eel": null,
    "pfc": null,
    "exporter_tax_id_type": null,
    "exporter_tax_id": null,
    "exporter_eori_number": null,
    "importer": null
  }
}

Expected Response

The response must include at least the following 3 fields:

• service_code
• service_name
• rate

JSON

[
    {
        "service_code": "SD",
        "service_name": "Same day delivery",
        "rate": "18.50",
    },
    {
        "service_code": "EXP",
        "service_name": "Two day delivery",
        "rate": "13.95",
    },
    {
        "service_code": "STD",
        "service_name": "Upto 4 day delivery",
        "rate": "8.95",
    }
]

A fully detailed response could include the following attributes

JSON

[
    { 
       "service_code": "SD",
        "service_name": "Same day delivery",
        "rate": "18.50",
        "currency": "USD",
        "list_rate": "20",
         "trackable" : true,
         "guaranteed": true,
         "delivery_days": 1,
         "delivery_date": "2021-01-01",
         "insurance_fee": "1.00",
         "insured": true
    },
    {
        "service_code": "EXP",
        "service_name": "Two day delivery",
        "rate": "13.95",
        "currency": "USD",
        "list_rate": "18.95",
         "trackable" : true,
         "guaranteed": true,
         "delivery_days": 2,
         "delivery_date": "2021-01-02",
         "insurance_fee": "1.00",
         "insured": true
    },
    {
        "service_code": "STD",
        "service_name": "Upto 4 day delivery",
        "rate": "8.95",
        "currency": "USD",
        "list_rate": "12.99",
         "trackable" : true,
         "guaranteed": true,
         "delivery_days": null,
         "delivery_date": null,
         "insurance_fee": null,
         "insured": false
    }
]