shopify-functions

shopify-functions

Required Tool Calls (do not skip)

You have a bash tool. Every response must use it — in this order:

• Call bash with node scripts/search_docs.mjs "<function type or operation>" — search before writing code

• Write the code using the search results

• Call bash with node scripts/validate.mjs --code '...' --model YOUR_MODEL_NAME --client-name YOUR_CLIENT_NAME --client-version YOUR_CLIENT_VERSION --artifact-id YOUR_ARTIFACT_ID --revision REVISION_NUMBER — validate before returning (Always include these flags. Use your actual model name for YOUR_MODEL_NAME; use claude-code/cursor/etc. for YOUR_CLIENT_NAME. For YOUR_ARTIFACT_ID, generate a stable random ID per code block and reuse it across validation retries. For REVISION_NUMBER, start at 1 and increment on each retry of the same artifact.)

• If validation fails: search for the error type, fix, re-validate (max 3 retries)

• Return code only after validation passes

You must run both search_docs.mjs and validate.mjs in every response. Do not return code to the user without completing step 3.

Shopify functions allow developers to customize the backend logic that powers parts of Shopify.

• Functions are pure: They cannot access the network, filesystem, random number generators, or the current date/time.

• All necessary data must be provided via the input query. Input queries must follow camelCase. If selecting a field that is a UNION type you must request __typename

Here are all the available Shopify functions APIs. Ensure to pick one of these, and avoid using deprecated ones unless explicitly asked for.

• Discount: Create a discount that applies to merchandise, product, product variants and/or shipping rates at checkout. Use this for ANY discount related task.

• Order Discount (deprecated): Create a new type of discount that's applied to all merchandise in the cart. IMPORTANT: don't choose this API unless the user asks to use the order discount API

• Product Discount (deprecated): Create a new type of discount that's applied to a particular product or product variant in the cart. IMPORTANT: don't choose this API unless the user asks to use the product discount API

• Shipping Discount (deprecated): Create a new type of discount that's applied to one or more shipping rates at checkout. IMPORTANT: don't choose this API unless the user asks to use the shipping discount API

• Delivery Customization: Rename, reorder, and sort the delivery options available to buyers during checkout

• Payment Customization: Rename, reorder, and sort payment methods and set payment terms for buyers during checkout

• Cart Transform: Expand cart line items and update the presentation of cart line items

• Cart and Checkout Validation: Provide your own validation of a cart and checkout

• Fulfillment Constraints: Provide your own logic for how Shopify should fulfill and allocate an order

• Local Pickup Delivery Option Generator: Generate custom local pickup options available to buyers during checkout

• Pickup Point Delivery Option Generator: Generate custom pickup point options available to buyers during checkout

A Shopify function can have multiple targets. Each target is a specific part of Shopify that the function can customize. For example, in the case of the Discount API you have four possible targets:

• cart.lines.discounts.generate.run: discount logic to apply discounts to cart lines and order subtotal

• cart.lines.discounts.generate.fetch: (optional, requires network access) retrieves data needed for cart discounts, including validation of discount codes

• cart.delivery-options.discounts.generate.run: discount logic to apply discounts to shipping and delivery options

• cart.delivery-options.discounts.generate.fetch: (optional, requires network access) retrieves data needed for delivery discounts, including validation of discount codes

Each function target is composed of:

• A GraphQL query that fetches the input used by the logic. This information is present in the "Input" object in the GraphQL schema definition.

• A Rust, Javascript, or Typescript implementation of the function logic. This logic has to return a JSON object that adheres to the shape of the "FunctionResult" object in the GraphQL schema definition. Some examples:

for a "run" target, the return object is "FunctionRunResult"

• for a "fetch" target, the return object is "FunctionFetchResult"

• for a "cart.lines.discounts.generate.run" target, the return object is "CartLinesDiscountsGenerateRunResult"

IMPORTANT: If the user doesn't specify a programming language, use Rust as the default.

Think about all the steps required to generate a Shopify function:

• Search the developer documentation for relevant examples, making sure to include the programming language the user has chosen. Pay extreme attention to these examples when writing your solution. THIS IS VERY IMPORTANT.

• Think about what I am trying to do and choose the appropriate Function API.

• If the user wants to create a new function make sure to run the Shopify CLI command shopify app generate extension --template <api_lowercase_and_underscore> --flavor <rust|vanilla-js|typescript> --name=<function_name>. Assume that the Shopify CLI is installed globally as shopify.

• Then think about which targets I want to customize.

• For each target, think about which fields I need to fetch from the GraphQL input object. You can:

Look at the GraphQL schema definition (schema.graphql) inside the function folder if it exists

• Explore available fields and types in the function's GraphQL schema to understand what data is accessible

• Then think about how to write the Rust, Javascript, or Typescript code that implements the function logic.

• Pay particular attention to the return value of the function logic. It has to match the shape of the "FunctionResult" object in the GraphQL schema definition.

• Make sure to include a src/main.rs if you are writing a Rust function.

• You can verify that the function builds correctly by running shopify app function build inside the function folder

• You can test that the function runs with a specific input JSON by running shopify app function run --input=input.json --export=<export_name> inside the function folder. You can find the correct export name by looking at the export field of the target inside the shopify.extension.toml

IMPORTANT: DO NOT DEPLOY the function for the user. Never ever ever run shopify app deploy.

Naming Conventions

• Identify the Target and Output Type: Look at the expected output type for the function target (e.g., FunctionRunResult, CartLinesDiscountsGenerateRunResult). The "target" is usually the last part (e.g., Run, GenerateRun).

• Determine the Function Name:

• Simple Output Types: If the output type follows the pattern Function<Target>Result (like FunctionRunResult), the function name is the lowercase target (e.g., run()).

• Complex Output Types: If the output type has a more descriptive prefix (like CartLinesDiscountsGenerateRunResult), the function name is the snake_case version of the prefix and target combined (e.g., cart_lines_discounts_generate_run()).

• Determine File Names:

• Rust/JavaScript File: Name the source code file based on the function name: src/<function_name>.rs or src/<function_name>.js.

• GraphQL Query File: Name the input query file similarly: src/<function_name>.graphql. e.g. src/fetch.graphql or src/run.graphql IMPORTANT: DO NOT name the file src/input.graphql.

• For Rust, you must ALWAYS generate a src/main.rs file that imports these targets.

Examples:

• Output: FunctionFetchResult -> Target: Fetch -> Function: fetch() -> Files: src/fetch.rs, src/fetch.graphql

• Output: FunctionRunResult -> Target: Run -> Function: run() -> Files: src/run.rs, src/run.graphql

• Output: CartLinesDiscountsGenerateRunResult -> Target: CartLinesDiscountsGenerateRun -> Function: cart_lines_discounts_generate_run() -> Files: src/cart_lines_discounts_generate_run.rs, src/cart_lines_discounts_generate_run.graphql IMPORTANT: You MUST look at the OutputType when determining the name otherwise the function will not compile

Some function type supports multiple "targets" or entry points within the same schema. For these you MUST generate the input query, function code, and sample outputs for EACH target. For example:

• fetch and run for delivery customizations

• fetch and run for pickup point customizations

• cart and delivery for discounts

Best practices for writing GraphQL operations

• Pay careful attention to the examples when choosing the name of the GraphQL query or mutation. For Rust examples, it MUST be Input.

• When choosing an enum value:

Only use values defined in the schema definition. DO NOT MAKE UP VALUES.

• Use the pure enum value unchanged, without namespace or quote wrapping, for example for the CountryCode enum just use US instead of "US" or CountryCode.US.

• When choosing a scalar value:

Float does not need to be wrapped in double quotes.

• UnsignedInt64 needs to be wrapped in double quotes.

• When reading GraphQL if a field is BuyerIdentity! (it means it's required) if it's BuyerIdentity (no !) then it is NOT required.

• If a field is OPTIONAL (It does not have a ! at the end such as BuyerIdentity) in the input data, then it MUST be unwrapped to handle the optional case when using Rust.

• If a field is OPTIONAL in the output data, then you must wrap that output in Some() when using Rust.

• You cannot write the same field twice. Use different aliases if you need to fetch the same field twice, i.e. when you need to pass different args.

• Only use properties that are defined in the schema definition. DO NOT MAKE UP PROPERTIES UNDER ANY CIRCUMSTANCES.

• GraphQL requires you to select specific fields within objects; never request an object without field selections (e.g., validation { } is invalid, you must specify which fields to retrieve).

• Only select the fields required to fulfill the business logic of your function

How to help with Shopify functions

If a user wants to know how to build a Shopify function make sure to follow this structure:

• example of the shopify cli command shopify app generate extension --template <api_lowercase_and_underscore> --flavor <rust|vanilla-js|typescript>

• example of function logic in Rust, Javascript, or Typescript. This logic has to use the input data fetched by the GraphQL query. Include tests. This is a MUST. Include file names. If the function type supports multiple targets, provide code and tests for each target.

• example of GraphQL query to fetch input data. The query name must follow the naming convention of the target RunInput as an example for JavaScript implementations and must be Input for Rust implementations. Include file names. If the function type supports multiple targets, provide a query for each target (e.g., src/fetch.graphql, src/run.graphql). DO NOT NAME IT input.graphql

• example of JSON input returned by the GraphQL query. Make sure that every field mentioned by the GraphQL query has a matching value in the JSON input. When you make a fragment selection ... on ProductVariant you MUST include __typename on Merchandise, or Region. THIS IS IMPORTANT. If the function type supports multiple targets, provide sample input JSON for each target.

• example of a JSON return object. Make sure this is the output JSON that would be generated by the JSON input above. If the function type supports multiple targets, provide sample output JSON for each target.

If a function cannot be accomplished with any of the Function APIs simply return a message that it can't be completed, and give the user a reason why. Example reasons why it can't:

• You cannot remove an item from cart

• You cannot access the current date or time

• You cannot generate a random value

Important notes for Input Queries

It's not possible to fetch tags directly, you must use either hasAnyTag(list_of_tags), which return a boolean, or hasTags(list_of_tags), which return a list of { hasTag: boolean, tag: String } objects. When using any graphql field that tags arguments YOU MUST pass in those arguments into your input query ONLY, you may set defaults in the query. DO NOT USE THESE ARGUMENTS IN THE RUST CODE. When you make a fragment selection ... on ProductVariant you MUST include __typename on the parent field otherwise the program will not compile. e.g. regions { __typename ... on Country { isoCode }}

query Input(\$excludedCollectionIds: [ID!], \$vipCollectionIds: [ID!]) {
  cart {
    lines {
      id
      merchandise {
        __typename
        ... on ProductVariant {
          id
          product {
            inExcludedCollection: inAnyCollection(ids: \$excludedCollectionIds)
            inVIPCollection: inAnyCollection(ids: \$vipCollectionIds)
          }
        }
      }
    }
  }
}

Important notes for Javascript function logic

• the module needs to export a function which is the camel cased version of the name as the target, i.e. 'export function fetch' or 'export function run' or 'export function cartLinesDiscountsGenerateRun'

• the function must return a JSON object that adheres to the shape of the "FunctionResult" object in the GraphQL schema definition.

Important notes for Rust function logic

• Don't import external crates (like rust_decimal or chrono or serde), the only ones allowed are shopify_function. i.e. use shopify_function::; is ok, but use chrono::; and serde::Deserialize is not.

• Decimal::from(100.0) is valid, while Decimal::from(100) is not. It can only convert from floats, not integers or strings otherwise the program will not compile.

• make sure to unwrap Options when the field is marked as optional in the GraphQL schema definition. The rust code will generate types based on the GraphQL schema definition and will fail if you get this wrong. THIS IS IMPORTANT.

• make sure to be careful when to use float (10.0), int (0), or decimals ("29.99")

• If a field is OPTIONAL (It does not have a ! at the end) in the input data, then it MUST be unwrapped to handle the optional case. For example, access buyer_identity like this: if let Some(identity) = input.cart().buyer_identity() { /* use identity */ } or using methods like as_ref(), and_then(), etc. Do NOT assume an optional field is present.

• If a field is OPTIONAL in the output data, then you must wrap that output in Some().

• If doing a comparison against an OPTIONAL field you must also wrap that value. For example, comparing an optional product_type: Option field with the string literal "gift card" should be done like this: product_type() == Some("gift card".to_string())

• If a value has an ENUM then you must use the Title Case name of that enum, like PaymentCustomizationPaymentMethodPlacement::PaymentMethod

• D

...