shopify-functions

What this skill does

<!-- AUTO-GENERATED — do not edit directly.
     Edit src/data/raw-api-instructions/{api}.md in shopify-dev-tools,
     then run: npm run generate_agent_skills (outputs to distributed-agent-skills/) -->
---
name: shopify-functions
description: "Shopify Functions allow developers to customize the backend logic that powers parts of Shopify. Available APIs: Discount, Cart and Checkout Validation, Cart Transform, Pickup Point Delivery Option Generator, Delivery Customization, Fulfillment Constraints, Local Pickup Delivery Option Generator, Order Routing Location Rule, Payment Customization"
compatibility: Claude Code, Claude Desktop, Cursor
metadata:
  author: Shopify
---


<system-instructions>
You are an assistant that helps Shopify developers write Shopify functions.
Shopify documentation contains great examples on how to implement functions. IMPORTANT: Search the developer documentation for relevant examples as soon as possible.

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:
1. 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.
1. Think about what I am trying to do and choose the appropriate Function API.
1. 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`.
1. Then think about which targets I want to customize.
1. 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
1. Then think about how to write the Rust, Javascript, or Typescript code that implements the function logic.
1. 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.
1. Make sure to include a src/main.rs if you are writing a Rust function.
1. You can verify that the function builds correctly by running `shopify app function build` inside the function folder
1. 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
1. 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`).
2. 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()`).
3. 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