CarrierService

A Carrier Service (also known as a Carrier Calculated Service or Shipping Service) provides real-time shipping rates to haravan. Some common carrier services include: FedEx, USPS and UPS.

Reminder

Access to the Carrier Services API requires the store be on the Unlimited Plan or higher. The term "carrier" is often used interchangeably with "shipping".

Using the Carrier Services API, you can register a new carrier service and provide endpoints to haravan with a list of applicable shipping rates. With the Carrier Services API you can even use the cart data to adjust shipping rates and offer shipping discounts based on what is in the customer's cart.

When registering a new carrier service, your will need to provide a POST endpoint rooted in the callback_url where haravan can retrieve applicable shipping rates. Your callback_url should be a public endpoint that expects these requests from haravan.

haravan provides server-side caching to reduce the number of external requests. Any shipping rate estimate request that identically matches the following fields will be retrieved from haravan's cache of the initial response:

  • variant ids
  • variant quantities
  • carrier service id
  • origin address
  • destination address
  • item weights & signatures

If any of these fields differ, shipping rates will be requested from the external provider. Each cache key expires 24 hours after being initialized.

A sample haravan request for shipping rates:

POST Your callback URL

Get a list of applicable shipping rates for the following...

Example Shipping Rate Request sent to a Carrier Service

        {
           "rate": {
               "origin": {
                   "country": "CA",
                   "postal_code": "K1S4J3",
                   "province": "ON",
                   "city": "Ottawa",
                   "name": null,
                   "address1": "520 Cambridge Street South",
                   "address2": null,
                   "address3": null,
                   "phone": null,
                   "fax": null,
                   "address_type": null,
                   "company_name": null
               },
               "destination": {
                   "country": "CA",
                   "postal_code": "K1S 3T7",
                   "province": "ON",
                   "city": "Ottawa",
                   "name": "Jason Normore",
                   "address1": "520 Cambridge Street South Apt. 5",
                   "address2": null,
                   "address3": null,
                   "phone": "7097433959",
                   "fax": null,
                   "address_type": null,
                   "company_name": null
               },
               "items": [
                   {
                       "name": "My Product 3",
                       "sku": null,
                       "quantity": 1,
                       "grams": 1000,
                       "price": 2000,
                       "vendor": "TestVendor",
                       "requires_shipping": true,
                       "taxable": true,
                       "fulfillment_service": "manual"
                   }
               ],
               "currency": "CAD"
           }
        }
View Response
        {
           "rates": [
               {
                   "service_name": "canadapost-overnight",
                   "service_code": "ON",
                   "total_price": "1295",
                   "currency": "CAD",
                   "min_delivery_date": "2013-04-12 14:48:45 -0400",
                   "max_delivery_date": "2013-04-12 14:48:45 -0400"
               },
               {
                   "service_name": "fedex-2dayground",
                   "service_code": "1D",
                   "total_price": "2934",
                   "currency": "USD",
                   "min_delivery_date": "2013-04-12 14:48:45 -0400",
                   "max_delivery_date": "2013-04-12 14:48:45 -0400"
               },
               {
                   "service_name": "fedex-2dayground",
                   "service_code": "1D",
                   "total_price": "2934",
                   "currency": "USD",
                   "min_delivery_date": "2013-04-12 14:48:45 -0400",
                   "max_delivery_date": "2013-04-12 14:48:45 -0400"
               }
           ]
        }

Note that the address3, fax, address_type, and company_name fields are returned by specific ActiveShipping providers. For API-created Carrier Services, you can faithfully stick to shipping address fields only, i.e. address1, address2, city, zip, province, and country. Other values are not sent to the callback URL; they remain null.

Setting carrier service permissions

Add the write_shipping permission to your requested scopes.

What can you do with CarrierService?

The haravan API lets you do the following with the CarrierService resource. More detailed versions of these general actions may be available:

CarrierService Properties

active
{ "active" : "true" }

States whether or not this carrier service is active. Valid values are "true" and "false".

callback_url
{ "callback_url" : "http://myapp.com" }

States the URL endpoint that haravan needs to retrieve shipping rates. This must be a public URL.

carrier_service_type
{ "carrier_service_type" : "api" }

Distinguishes between api or legacy carrier services.

name
{ "name" : "My Carrier Service" }

The name of the shipping service as seen by merchants and their customers.

service_discovery
{ "service_discovery" : "true" }

States if merchants are able to send dummy data to your service through the haravan admin to see shipping rate examples. Valid values are "true" and "false"

Endpoints

POST/admin/carrier_services.json


To create a carrier service, you can also use a cURL request that uses that carrier_service.json payload:

  curl -X POST -d @fulfillment_service.json -H"Accept:application/json" -H"Content-Type:application/json" -H"X-haravan-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myharavan.com/admin/carrier_services

Where THE_TOKEN_GOES_HERE is replaced by the oAuth token given to you by haravan and https://AUTHORIZED_SHOP.myharavan.com/admin/carrier_services is replaced by the authorized shop's URL.


Create a carrier service

POST /admin/carrier_services.json
{
  "carrier_service": {
    "name": "Shipping Rate Provider",
    "callback_url": "http:\/\/shippingrateprovider.com",
    "format": "json",
    "service_discovery": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "carrier_service": {
    "active": true,
    "id": 763770006,
    "name": "Shipping Rate Provider",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
PUT/admin/carrier_services/763770010.json

Update a carrier service

PUT /admin/carrier_services/#{id}.json
{
  "carrier_service": {
    "active": false,
    "id": 763770010,
    "name": "Some new name",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
View Response
HTTP/1.1 200 OK
{
  "carrier_service": {
    "active": false,
    "id": 763770010,
    "name": "Some new name",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
GET/admin/carrier_services.json

List carrier services

GET /admin/carrier_services.json
View Response
HTTP/1.1 200 OK
{
  "carrier_services": [
    {
      "active": true,
      "id": 763770008,
      "name": "Purolator",
      "service_discovery": true,
      "carrier_service_type": "api"
    }
  ]
}
GET/admin/carrier_services/763770009.json

Get a single carrier service by its ID

GET /admin/carrier_services/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "carrier_service": {
    "active": true,
    "id": 763770009,
    "name": "Purolator",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
DELETE/admin/carrier_services/763770007.json

Destroy a carrier service

DELETE /admin/carrier_services/#{id}.json
View Response
HTTP/1.1 200 OK
{}