CarrierService

A Carrier Service (also known as a Carrier Calculated Service or Shipping Service) provides real-time shipping rates to Shopify. 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 Shopify 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 Shopify can retrieve applicable shipping rates. Your callback_url should be a public endpoint that expects these requests from Shopify.

Shopify 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 Shopify'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 Shopify 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"
             }
         ]
      }
                  

View an open sourced example Shipping and Fulfillment App that demonstrates how to use the Fulfillment and Carrier Service API.


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 Shopify 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 shopify 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 Shopify 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-Shopify-Access-Token:THE_TOKEN_GOES_HERE" https://AUTHORIZED_SHOP.myshopify.com/admin/carrier_services
        

Where THE_TOKEN_GOES_HERE is replaced by the oAuth token given to you by Shopify and https://AUTHORIZED_SHOP.myshopify.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": 734044710,
    "name": "Shipping Rate Provider",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
PUT/admin/carrier_services/734044714.json

Update a carrier service

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

{
  "carrier_service": {
    "active": false,
    "id": 734044714,
    "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": 734044712,
      "name": "Purolator",
      "service_discovery": true,
      "carrier_service_type": "api"
    }
  ]
}
GET/admin/carrier_services/734044713.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": 734044713,
    "name": "Purolator",
    "service_discovery": true,
    "carrier_service_type": "api"
  }
}
DELETE/admin/carrier_services/734044711.json

Destroy a carrier service

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

{}

Ready to put what you've learned into action?

Build an online store with Shopify Try it Free

Experience the future of retail now

Shopify Point of Sale Try it Free