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" } }
{ "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:
- POST /com/carrier_services.json Create a new CarrierService
- PUT /com/carrier_services/#{id}.json Modify an existing CarrierService
- GET /com/carrier_services.json Receive a list of all CarrierServices
- GET /com/carrier_services/#{id}.json Receive a single CarrierService
- DELETE /com/carrier_services/#{id}.json Remove a CarrierService from the database
CarrierService Properties
active |
States whether or not this carrier service is active. Valid values are "true" and "false". |
callback_url |
States the URL endpoint that haravan needs to retrieve shipping rates. This must be a public URL. |
carrier_service_type |
Distinguishes between api or legacy carrier services. |
name |
The name of the shipping service as seen by merchants and their customers. |
service_discovery |
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/com/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 /com/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/com/carrier_services/763770010.json
Update a carrier service
PUT /com/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/com/carrier_services.json
List carrier services
GET /com/carrier_services.json
View ResponseHTTP/1.1 200 OK { "carrier_services": [ { "active": true, "id": 763770008, "name": "Purolator", "service_discovery": true, "carrier_service_type": "api" } ] }
GET/com/carrier_services/763770009.json
Get a single carrier service by its ID
GET /com/carrier_services/#{id}.json
View ResponseHTTP/1.1 200 OK { "carrier_service": { "active": true, "id": 763770009, "name": "Purolator", "service_discovery": true, "carrier_service_type": "api" } }
DELETE/com/carrier_services/763770007.json