Shipping Rate Context

Shipping Rate Context

The Shipping Rate Context feature enables you to access logged-in customer information within your Carrier Calculated Shipping Rate scripts. This allows you to create personalized shipping options based on customer data, such as offering free shipping to VIP customers or applying custom rates based on customer tags.

Requirements

  • Shopify Plus plan (Checkout UI Extensions are only available on Shopify Plus)

  • Shipping Rate script configured in your store

How It Works

The Shipping Rate Context feature consists of two parts:

  1. Checkout UI Extension - A hidden block that runs during checkout and attaches customer metadata to cart line items

  2. Shipping Rate Script - Your custom Liquid script that reads the customer metadata and applies shipping logic

Data Flow

Customer enters checkout
        ↓
Shipping Rate Context extension runs
        ↓
Customer data (email, ID) is attached to line items as `_datajet` property
        ↓
Carrier Calculated Shipping request is made
        ↓
Your shipping rate script reads `_datajet` property
        ↓
Script queries customer data (e.g., tags) via GraphQL
        ↓
Custom shipping rates are returned based on customer data

Setup Instructions

Step 1: Add the Shipping Rate Context Block to Checkout

  1. Navigate to Settings > Checkout in your Shopify admin

  2. Click Customize to open the checkout editor

  3. In the checkout editor, add a new block

  4. Search for and select Shipping Rate Context from the DataJet app

  5. The block is invisible to customers and can be placed anywhere in the checkout

  6. Save your changes

Step 2: Create Your Shipping Rate Script

In your Carrier Calculated Shipping rate script, you can now access customer data through the _datajet property on line items.

Customer Data Available

The _datajet property contains a JSON object with the following structure:

{
  "customer": {
    "email": "[email protected]",
    "id": "1234567890"
  }
}
Field
Description

customer.email

The logged-in customer's email address

customer.id

The Shopify customer ID (numeric, without the gid:// prefix)

Note: If the customer is not logged in, the customer field will be null.

Example: Free Shipping for Tagged Customers

The following example demonstrates how to offer free shipping to customers with a specific tag (e.g., "FREE-SHIPPING"):

{% capture customer_query %}
  query($id: ID!) {
    customer(id: $id) {
      id
      displayName
      email
      tags
    }
  }
{% endcapture %}

{% assign free_shipping = false %}
{% assign required_customer_tag = "FREE-SHIPPING" %}

{% comment %}
  _datajet property only exists on line item if Shipping Rate Context
  Checkout UI block has been added to store's Checkout
{% endcomment %}
{% assign metadata = request.body.rate.items | map: "properties._datajet" | compact | first %}

{% if metadata %}
  {% assign parsed_metadata = metadata | parse %}
  {% assign logged_in_customer = parsed_metadata.customer %}
{% endif %}

{% if logged_in_customer != blank %}

  {% json customer_variables %}
    {
      "id": "gid://shopify/Customer/{{logged_in_customer.id}}"
    }
  {% endjson %}

  {% graphql query: customer_query, variables: customer_variables as result %}
  {% assign customer_tags = result.customer.tags %}

  {% if customer_tags contains required_customer_tag %}
    {% assign free_shipping = true %}
  {% endif %}
{% endif %}

{% comment %} Returning response {% endcomment %}
{% json response %}
  {
    "body": {
      "rates": [
        {% if free_shipping %}
          {
            "service_name": "Free Shipping",
            "service_code": "FS",
            "total_price": "0",
            "currency": "USD"
          }
        {% endif %}
      ]
    }
  }
{% endjson %}

{% return response %}

Use Cases

Here are some common scenarios where Shipping Rate Context is useful:

VIP Customer Shipping

Offer free or discounted shipping to loyalty program members or VIP customers identified by tags.

B2B Shipping Rates

Apply different shipping rates for wholesale/B2B customers vs. retail customers.

Regional Shipping Rules

Combine customer data with address information to create sophisticated regional shipping rules.

Subscription Customer Benefits

Provide special shipping options for customers subscribed to your membership program.

Troubleshooting

Customer data is not available

  1. Verify the extension is installed: Go to Settings > Checkout > Customize and confirm the "Shipping Rate Context" block is added

  2. Check customer login status: The _datajet property only contains customer data when the customer is logged in during checkout

  3. Confirm Shopify Plus: This feature requires a Shopify Plus plan

The _datajet property is missing

  • Ensure the Shipping Rate Context checkout block is properly configured and saved

  • The block must be active in the live checkout (not just in draft/preview mode)

GraphQL query returns null

  • Verify the customer ID format includes the full GID prefix: gid://shopify/Customer/{id}

  • Check that your app has the required permissions to query customer data

PreviousShipping RateNextEmail

Last updated