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.

Your app's request to create a carrier service will fail unless the store installing your carrier service meets one of the following requirements:

• It's on the Advanced Shopify plan or higher.
• It's on the Shopify plan with yearly billing, or the carrier service feature has been added to the store for a monthly fee. For more information, contact Shopify Support.
• It's 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:

POST

{
  "rate": {
    "origin": {
      "country": "CA",
      "postal_code": "K2P1L4",
      "province": "ON",
      "city": "Ottawa",
      "name": null,
      "address1": "150 Elgin St.",
      "address2": "",
      "address3": null,
      "phone": null,
      "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.

Special conditions

• To indicate that this carrier service cannot handle this shipping request, return an empty array and any successful (20x) HTTP code.
• To force backup rates instead, return a 40x or 50x HTTP code with any content. A good choice is the regular 404 Not Found code.
• Redirects (30x codes) will only be followed for the same domain as the original callback URL. Attempting to redirect to a different domain will trigger backup rates.
• There is no retry mechanism. The response must be successful on the first try, within the time budget listed below. Timeouts or errors will trigger backup rates.

Response Timeouts

The read timeout for rate requests are dynamic, based on the number of requests per minute (RPM). These limits are applied to each shop-app pair. The timeout values are as follows.

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. The cache expires 15 minutes after rates are successfully returned. If an error occurs, then the cache expires after 30 seconds.