# 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:

```json
{
  "customer": {
    "email": "customer@example.com",
    "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"):

```liquid
{% 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