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 Canada Post, FedEx, UPS, and USPS. The term carrier is often used interchangeably with the terms shipping company and rate provider.

Using the CarrierService resource, you can add a carrier service to a shop and then provide a list of applicable shipping rates at checkout. You can even use the cart data to adjust shipping rates and offer shipping discounts based on what is in the customer's cart.

Requirements for accessing the CarrierService resource

To access the CarrierService resource, add the write_shipping permission to your app's requested scopes. For more information, see API access scopes.

The store installing your carrier service must also meet one of the following requirements:

  • It is on the Advanced Shopify plan or higher.
  • Its Shopify plan is paid annually.
  • It is a development store.

Providing shipping rates to Shopify

When adding a carrier service to a store, you need to provide a POST endpoint rooted in the callback_url property where Shopify can retrieve applicable shipping rates. The callback URL should be a public endpoint that expects these requests from Shopify.

A sample Shopify request for shipping rates:

POSTYour callback URL

Retrieves a list of applicable shipping rates

Example shipping rate request sent to a carrier service

{
  "rate": {
    "origin": {
      "country": "CA",
      "postal_code": "K2P1L4",
      "province": "ON",
      "city": "Ottawa",
      "name": null,
      "address1": "150 Elgin St.",
      "address2": "",
      "address3": null,
      "phone": "16135551212",
      "fax": null,
      "email": null,
      "address_type": null,
      "company_name": "Jamie D's Emporium"
    },
    "destination": {
      "country": "CA",
      "postal_code": "K1M1M4",
      "province": "ON",
      "city": "Ottawa",
      "name": "Bob Norman",
      "address1": "24 Sussex Dr.",
      "address2": "",
      "address3": null,
      "phone": null,
      "fax": null,
      "email": null,
      "address_type": null,
      "company_name": null
    },
    "items": [{
      "name": "Short Sleeve T-Shirt",
      "sku": "",
      "quantity": 1,
      "grams": 1000,
      "price": 1999,
      "vendor": "Jamie D's Emporium",
      "requires_shipping": true,
      "taxable": true,
      "fulfillment_service": "manual",
      "properties": null,
      "product_id": 48447225880,
      "variant_id": 258644705304
    }],
    "currency": "USD",
    "locale": "en"
  }
}
                    
{
   "rates": [
       {
           "service_name": "canadapost-overnight",
           "service_code": "ON",
           "total_price": "1295",
           "description": "This is the fastest option by far",
           "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": "2D",
           "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-priorityovernight",
           "service_code": "1D",
           "total_price": "3587",
           "currency": "USD",
           "min_delivery_date": "2013-04-12 14:48:45 -0400",
           "max_delivery_date": "2013-04-12 14:48:45 -0400"
       }
   ]
}
                    

The address3, fax, address_type, and company_name fields are returned by specific ActiveShipping providers. For API-created carrier services, you should use only the following shipping address fields:

  • address1
  • address2
  • city
  • zip
  • province
  • country

Other values remain as null and are not sent to the callback URL.

Response fields

When Shopify requests shipping rates using your callback URL, the response object rates must be a JSON array of objects with the following fields. Required fields must be included in the response for the carrier service integration to work properly.

Field Description
service_name
required
The name of the rate, which customers see at checkout. For example: Expedited Mail.
description
required
A description of the rate, which customers see at checkout. For example: Includes tracking and insurance.
service_code
required
A unique code associated with the rate. For example: expedited_mail.
currency
required
The currency of the shipping rate.
total_price
required
The total price based on the shipping rate currency.
phone_required Whether the customer must provide a phone number at checkout.
min_delivery_date The earliest delivery date for the displayed rate.
max_delivery_date The latest delivery date for the displayed rate to still be valid.

Server-side caching of requests

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

  • variant IDs
  • default shipping box weight and dimensions
  • variant quantities
  • carrier service ID
  • origin address
  • destination address
  • item weights and signatures

If any of these fields differ, or if the cache has expired since the original request, then new shipping rates are requested.

What you can 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

Whether this carrier service is active.

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

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.

id
"id": 14079244

The ID of the carrier service.

format
"format": "json"

The format of the data returned by the URL endpoint. Valid values: json and xml. Default value: json.

name
"name": "My Carrier Service"

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

service_discovery
"service_discovery": true

Whether merchants are able to send dummy data to your service through the Shopify admin to see shipping rate examples.

Endpoints

POST /admin/carrier_services.json
Creates a carrier service

Create a carrier service

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

Updates a carrier service. Only the app that creates a carrier service can update it.

Update a carrier service

PUT /admin/carrier_services/#{carrier_service_id}.json
{
  "carrier_service": {
    "id": 1036894979,
    "name": "Some new name",
    "active": false
  }
}
View Response
HTTP/1.1 200 OK
{
  "carrier_service": {
    "id": 1036894979,
    "name": "Some new name",
    "active": false,
    "service_discovery": true,
    "carrier_service_type": "api",
    "format": "json",
    "callback_url": "http://example.com/"
  }
}
GET /admin/carrier_services.json
Retrieves a list of carrier services

Retrieve a list of carrier services

GET /admin/carrier_services.json
View Response
HTTP/1.1 200 OK
{
  "carrier_services": [
    {
      "id": 1036894980,
      "name": "Purolator",
      "active": true,
      "service_discovery": true,
      "carrier_service_type": "api",
      "format": "json",
      "callback_url": "http://example.com/"
    },
    {
      "id": 615128020,
      "name": "ups",
      "active": true,
      "service_discovery": true,
      "carrier_service_type": "legacy"
    }
  ]
}
GET /admin/carrier_services/1036894981.json

Retrieves a single carrier service by its ID

Retrieve a single carrier service

GET /admin/carrier_services/#{carrier_service_id}.json
View Response
HTTP/1.1 200 OK
{
  "carrier_service": {
    "id": 1036894981,
    "name": "Purolator",
    "active": true,
    "service_discovery": true,
    "carrier_service_type": "api",
    "format": "json",
    "callback_url": "http://example.com/"
  }
}
DELETE /admin/carrier_services/1036894982.json

Deletes a carrier service

Delete a carrier service

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

Sign up for a Partner account to get started.

Sign up