Shopify

info

The Shopify integration allows Karla to get all the order updates from your shop to display them on your customers tracking pages (e.g. purchased products, shipping address etc.) as well as to retrieve all tracking numbers to be able to provide corresponding tracking updates.

Steps

The process should not take longer than 5 minutes and it’s not complex at all.

1. Create a custom app and provide Karla with the API access token

Click on “Apps” and navigate to “Apps and sales channels settings” → “Develop apps” and click “Create an app”

• Name your app “GoKarla-Connector”
• Select yourself as the “App developer”
• Confirm with “Create app”

2. Click on “Configure Admin API scopes”

3: Select the following scopes

Required scopes

These scopes are required for essential Karla functionality

• read_fulfillments
• read_products
• read_orders
• read_order_edits
• write_orders - (only required for Shopify's native shipment updates)

warning

These scopes are very important, any missing permission might impact your Karla experience

Optional scopes (recommended)

These scopes are only required if you need advance Resolve capabilities.

• read_customers
• write_gift_cards
• read_gift_cards
• write_inventory
• read_inventory
• write_returns
• read_returns
• write_draft_orders
• read_draft_orders
• read_locations (to know warehouse locations for ETAs)

→ confirm with “Save”

4: Click on “Install App” and confirm on the popup with “Install”

5: Copy and safely store Shopify Admin Access Token

warning

You can only reveal this token once!

Send this Admin API access token to Karla

Perfect, you're done. This integration will give your customers an unparalleled tracking experience with Karla!

Campaign attribution for Shopify

To track which orders come from your Karla campaigns, you have two Shopify-specific methods available. For a complete overview of attribution methods across all platforms, see the Campaign Attribution Overview.

Method 1: Referral parameter (ref=karla)

Automatic setup

This method is enabled by default for all Shopify shops and requires no installation.

When customers click links from Karla tracking pages or campaigns, a ref=karla parameter is automatically added to the URL. Shopify captures this in the order's landing_site_ref field.

How it works:

1. Customer clicks link in tracking email/page with ref=karla parameter
2. Parameter is passed to cart/checkout
3. Shopify stores ref=karla in the order's landing_site_ref field
4. Karla retrieves orders via Shopify API filtering by landing_site_ref=karla

Shopify-specific limitations:

• Only works if the customer does not have a previous active session with your shop
• May not work if other Shopify plugins override the referral parameter
• The tracking page is embedded as an iframe, so it won't appear in Shopify's "Sessions by Landing Page" report (this is expected behavior)

Verifying orders in Shopify:

Navigate to Orders → Filter by Referral source = "karla", or search for orders with landing_site_ref: karla in the order details.

tip

This method works well for initial setup and basic tracking, but for more reliable attribution, consider Method 2 or using the Browser SDK attribution method.

Method 2: Discount codes

Easiest setup for discount campaigns

The simplest attribution method - works across all shop platforms, no technical setup required.

Simply add a discount code to your campaign in the Karla portal. Orders using this discount will be automatically attributed to the campaign.

Verifying orders in Shopify:

Navigate to Orders → Filter by Discount code to see all orders that used your campaign discount.

For complete details on discount code attribution, best practices, and limitations, see Discount Code Attribution in the Campaign Overview.

Advanced: Browser SDK for maximum accuracy

For the most accurate attribution tracking without requiring discount codes, you can install the Karla Browser SDK. This method provides detailed campaign data and works even when customers have existing shop sessions.

Setup instructions:

In the Shopify admin panel, navigate to Online Store > Themes:

Select your current theme and click on Edit theme:

Click on the three dots ... and select Edit code:

Go to the layout/theme.liquid file, just before the </head> tag, insert the Browser SDK JavaScript snippet, replacing gokarla-shopify with your shop slug:

Click on Save at the top. The script is now ready and will mark any orders that come from an interaction with Karla.

For complete details on Browser SDK attribution, see the Browser SDK Attribution section in the Campaign Overview.

Advanced: Custom Properties

Add custom properties to your Shopify orders to enhance your customers' delivery experience with Karla.

Understanding Scopes

Shopify supports two types of custom data, and we always prefix them with _karla_:

• Order attributes:
  • Apply to the entire order
  • Use Shopify attributes
• Line item properties:
  • Apply to individual products
  • Use Shopify properties

Order Attributes

These attributes will appear in the Additional details section of your order admin panel.

Marketplace Order Number

Use _karla_marketplace_order_number to track orders from external marketplaces (Amazon, eBay, etc.):

• Format: Any string (alphanumeric, dashes, and underscores supported)
• Scope: Entire order
• Use case: Reference external marketplace order IDs for cross-platform tracking

Order attribution variables

These parameters are automatically handled by our order attribution tracking script, but you can decide to manage them on your own if you want full control on Karla attribution logic.

These variables are:

• _karla_campaign: Campaign identifier
• _karla_captured_at: Timestamp when the attribution was first captured
• _karla_landing_path: Path on your shop where the customer landed
• _karla_landing_url: Full URL where the customer landed
• _karla_medium: Marketing medium (e.g., email, banner, push notification)
• _karla_referrer: HTTP referrer URL
• _karla_source: Traffic source identifier (e.g., trackpages, karla-lounge)

Line Item Properties

Line item properties apply to individual products and are added using the properties parameter.

Estimated Ship Date

Specify when a specific product will ship.

• Date formats accepted: any ISO 8601 date string (preferred), or common date strings like 23.10.2025 or 10/23/2025
• Scope: Individual line item

Complete Implementation Examples

Example 1: Adding Line Item Property (Product Page)

On your product page, add line item properties to the "Add to Cart" form:

<form action="/cart/add" method="post">
  <!-- Line item property: estimated ship date -->
  <input type="hidden" name="properties[_karla_estimated_ship_date]" value="2025-10-23">

  <input type="hidden" name="id" value="{{ product.variants.first.id }}">
  <button type="submit">Add to Cart</button>
</form>

Example 2: Adding Order Attribute (Cart Page)

There are two methods depending on your theme type:

Method A: Traditional Form (Older Themes)

If your theme uses traditional cart forms (typically older themes or custom implementations):

<form action="{{ routes.cart_url }}" method="post" ...>
  <!-- Your cart items display here -->

  <!-- Order attribute: marketplace order number, add before the </form> tag -->
  <input type="hidden" name="attributes[_karla_marketplace_order_number]" value="{{ your_marketplace_order_number }}">
</form>

Method B: AJAX Cart (Modern Themes)

Most modern Shopify themes (Dawn, Refresh, etc.) use AJAX for cart operations. For these themes, add this JavaScript to theme file (e.g., theme.liquid), before the closing </body> tag, for instance:

{% if customer.metafields.custom.marketplace_order_id %}
<script>
  fetch('/cart/update.js', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      attributes: { '_karla_marketplace_order_number': '{{ customer.metafields.custom.marketplace_order_id }}' }
    })
  });
</script>
{% endif %}

Replace your_marketplace_order_number with your actual Liquid variable containing the marketplace order ID.

Troubleshooting

Attributes/Properties not showing?

• Check spelling: must be exactly the documented key name (lowercase, double or single underscores respectively)
• Ensure properties/attributes are inside your <form> tag
• For order attributes, use attributes[...] not properties[...]
• For line item properties, use properties[...] not attributes[...]
• For modern themes: If hidden inputs don't work, use the AJAX method (Method B) instead

Order attributes still empty in cart.js?

• Your theme likely uses AJAX cart → Switch from Method A (hidden input) to Method B (JavaScript)
• Check browser console (F12) for errors
• Make sure the script runs after items are added to cart

Attributes/Properties visible to customers?

• Make sure property name starts with double/single underscore

Dates not working?

• Use format: YYYY-MM-DD (e.g., 2025-10-23)
• Or: DD.MM.YYYY (e.g., 23.10.2025)
• Or: MM/DD/YYYY (e.g., 10/23/2025)

The ideal format is an ISO 8601 date string, but we have extra parsing to accommodate to non-standard dates (best-effort).

Quick Reference

Order

Property	Type	Example
_karla_campaign	String	8c0b2fcf-c0a0-46f7-8383-1cac748f35c0
_karla_captured_at	String	AMZN-12345-67890
_karla_landing_path	String	/products/shoes
_karla_landing_url	String	https://shop.myshopify.com/products/test?karla_source=email
_karla_marketplace_order_number	String	AMZN-12345-67890
_karla_medium	String	social
_karla_referrer	String	https://google.com
_karla_source	String	trackpages

Order line item

Property	Type	Example
_karla_estimated_ship_date	Date	2025-10-23

Coming Soon

More custom properties are being added to support additional use cases. Stay tuned!