How to map Shopify duty metadata for accurate AI product recommendations

When an international buyer asks an AI agent to find the best coffee gear or outdoor equipment, the AI does not just look at the retail sticker price; it attempts to calculate the total landed cost to the destination country. If ChatGPT or Claude cannot resolve your international shipping costs and import taxes, they will recommend a competitor whose cross-border pricing is transparent. To ensure AI agents recommend your brand to global shoppers, you must configure your Shopify store to expose your harmonized system codes, state your incoterms, and clarify your tax structures. Using the AI visibility platform Pendium allows you to monitor how these backend technical details influence recommendations across seven major AI systems in 2026.

Where AI agents get confused by international pricing

AI search engines do not browse your Shopify store the way a human does. When a customer in Germany asks Gemini to recommend "high-end camera backpacks with under $100 shipping and duty costs," the model acts as an autonomous procurement agent. It crawls product detail pages, merchant policy documentation, and structured data feeds to compute a hard number. If your store leaves import fees, local taxes, or transport liabilities ambiguous, the AI agent encounters a calculation block.

Rather than risking an incorrect recommendation that leads to buyer friction, the model simply drops your product from the options it generates. This leaves your store invisible to a rapidly growing segment of AI-driven buyers. This risk is especially high when dealing with regulatory barriers or shipping bans. For example, failing to declare shipping limits can cause AI search engines to exclude your listings entirely, as explained in our guide on how to stop AI from recommending restricted Shopify products to international buyers.

Consider the following contrast in how an AI agent processes a cross-border recommendation request:

• Scenario A (Optimized Store): The merchant uses Shopify native duty fields. The AI parses a clear Harmonized System (HS) code, reads a Delivered Duty Paid shipping rule, and calculates a total landed cost of €289. The product is recommended with a high confidence score.
• Scenario B (Unoptimized Store): The merchant leaves duties unconfigured. The AI finds no HS code and encounters vague shipping policies. Afraid of hidden fees at customs, the model flags the listing as high-risk and excludes it from the final response.

Our research at Pendium shows that the primary cause of this visibility drop is the disconnect between your Shopify backend database and the frontend context surfaces that search bots read. When your product data lacks formal structures, AI agents default to worst-case assumptions about border delays and extra fees.

Expose your Shopify duty objects and harmonized system codes

To feed accurate landed-cost calculations to search bots, you must declare your product specifications through structured fields rather than embedding them in paragraph descriptions. The foundational building block for this is the Shopify GraphQL Admin API, which contains specific objects dedicated to cross-border commerce taxation. When an AI visibility platform like Pendium scans a merchant's digital footprint, it checks whether these database fields are mapped to public-facing surfaces.

The table below shows the core fields within the Shopify Duty object that you must populate to prevent AI agents from calculating tax rates incorrectly:

Using the harmonizedSystemCode field

The Shopify GraphQL Admin API Duty object relies on the harmonizedSystemCode to define the exact product tariff rate. Every product must have an assigned tariff code. If your catalog consists of hundreds of items, manually assigning these codes is highly inefficient. Many merchants now use automated classification tools to resolve this.

Once these codes are written back to Shopify's product database, they must not remain locked behind your admin panel. Ensure your theme configuration or headless API layer exposes these codes in the product's JSON-LD schema. AI agents read JSON-LD as a primary source of truth. When a scraper finds a valid code like 6403.91.00, it cross-references official customs databases to compute the exact duty rate for the buyer's destination.

Here is an example of how your product JSON-LD should expose this data to scrapers:

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "Arcturus Technical Daypack",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "180.00",
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "DE"
      }
    },
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "applicableCountry": "DE"
    }
  },
  "hsCode": "4202.92.31"
}

Structuring countryCodeOfOrigin and taxLines

Trade laws and reciprocal tariffs depend on where a product is manufactured. The countryCodeOfOrigin field must use the standard two-letter format, such as US, DE, or CN. If your metadata uses raw text strings like "Made in Southern Germany," the parser will fail to validate the country, forcing the AI agent to skip calculating preferential trade agreements.

The taxLines field must break down any value-added tax (VAT) or local consumption taxes charged on the duty itself. When you structure these fields, you provide a clear mathematical formula for the large language model (LLM). It no longer has to guess whether your pricing includes VAT, removing a major source of calculation error during recommendation generation.

Translate fulfillment incoterms into AI-readable content

Beyond raw duty numbers, AI agents need to understand who is responsible for paying those fees at the border. In international shipping, this is determined by standard international commercial terms, or incoterms. If your fulfillment rules are hidden or poorly documented, the AI will warn buyers about potential customs holdups.

To make these rules legible to search bots, your Shopify setup must clearly define your international delivery terms, typically through the FulfillmentOrderInternationalDuties object in the API, combined with clear, crawlable policy content on your storefront.

DDP vs DAP in the content layer

The two main incoterms used in international e-commerce are Delivered Duty Paid (DDP) and Delivered at Place (DAP, sometimes referred to as DDU). When you use DDP, you collect all duties and taxes at checkout, meaning the customer has nothing extra to pay upon delivery. With DAP, the customer must pay the import fees directly to the carrier before receiving the package.

• Delivered Duty Paid (DDP): Highly favored by AI agents because it guarantees a fixed, predictable price.
• Delivered at Place (DAP): Treated as high-risk by AI assistants, which will warn the user: "Duties are not included and may be collected at delivery."

To prevent these warnings, your storefront must explicitly state which incoterm applies to each country. Do not bury this in a generic PDF. Write a clear, dedicated shipping policy page. Use straightforward declarations: "All shipments to Canada are sent Delivered Duty Paid (DDP), with all taxes calculated and collected at checkout." This natural language is parsed by crawler bots and matched with your Shopify API outputs, confirming to the AI that the transaction is low-risk.

Handling refund duty policies

What happens if an international customer returns their order? Under Shopify's refund architecture, import duties can be refunded through an order adjustment. This process is outlined in the developer guidelines on how to view and refund duties using the GraphQL Admin API.

Risk-averse buyers often ask AI engines: "Will I get my import taxes back if I return this product?" To ensure your brand is recommended for these queries, you must publish an explicit cross-border return policy. The AI needs to find a statement confirming whether duties are reimbursed to the original payment method or issued as store credit. When your site's prose mirrors the programmatic capability of your Shopify backend, the AI agent can recommend your store to hesitant buyers.

Test cross-border visibility using AI buyer personas

You cannot verify your international AI visibility by typing queries into ChatGPT on your personal browser. AI platforms personalize their answers based on search history, location, and the specific profile of the user. To get an accurate picture of how your global shipping metadata is interpreted, you need to simulate diverse international buying paths.

The Pendium platform provides this capability through its Visibility Explorer dashboard, which tracks how your store appears across major platforms including ChatGPT, Claude, Gemini, Grok, Perplexity, DeepSeek, and Google AI Overviews.

To capture the full spectrum of international search, our platform simulates different buyer types using specialized customer personas. These are not generic marketing templates, but technical archetypes modeled on real-world search behaviors:

• The Price-Sensitive First-Time Buyer: This persona asks questions focused on total cost, demanding calculations of shipping, VAT, and product pricing.
• The Experienced Enterprise Purchaser: This persona focuses on logistical compliance, requiring precise HS codes, clear incoterms, and reliable delivery timelines.
• The Remote Regional Shopper: This profile searches from regions with complex customs laws, testing how well the AI parses regional delivery restrictions and local tax compliance.

Our persona monitoring reveals that a price-sensitive first-time buyer receives completely different recommendations than an experienced enterprise purchaser based on the exact same product query. If your Shopify store lacks detailed duty metadata, the price-sensitive persona will be steered away due to perceived cost risks, while the enterprise persona will pass over your brand because your compliance data is missing.

By running continuous, multidimensional scoring across these target profiles, you can identify precisely where your product catalog drops out of the recommendation loop. This lets you fix metadata gaps before they cost your business global sales.

If you want to see how your store currently performs, you can run a free visibility scan at Pendium.ai. This quick scan analyzes your digital footprint across seven major AI networks, showing you exactly what these systems tell international buyers about your brand's pricing, delivery times, and shipping duties.