shopify-functions: Скилл для кастомизации Shopify

--- name: shopify-functions description: Build backend logic with Shopify Functions. Use this skill for creating custom discounts, delivery customization, payment customization, cart and checkout validation, and order routing. Functions run on Shopify's infrastructure using WebAssembly. Supports Rust and JavaScript. license: MIT compatibility: Requires Shopify CLI, Rust or JavaScript knowledge, and a Partner account metadata: author: shopify-agent-skills version: "1.0" shopify-api-version: "2025-01" --- # Shopify Functions ## When to use this skill Use this skill when: - Creating custom discount logic - Customizing delivery options - Implementing payment method rules - Validating cart or checkout - Building order routing logic - Extending Shopify's backend behavior ## What are Shopify Functions? Functions are serverless WebAssembly modules that extend Shopify's backend logic. They: - Run on Shopify's infrastructure - Execute in milliseconds - Scale automatically - Are upgrade-safe ### Function Types | API | Purpose | | ------------------------------ | -------------------------------------- | | **Discounts** | Product, order, and shipping discounts | | **Delivery Customization** | Rename, reorder, hide shipping options | | **Payment Customization** | Filter, reorder payment methods | | **Cart & Checkout Validation** | Block checkout with errors | | **Order Routing** | Control fulfillment locations | | **Cart Transform** | Modify cart contents | ## Getting Started ### 1. Create a Function ```bash # In an existing app shopify app generate extension # Select from function types: # - Delivery customization # - Product discount # - Order discount # - Cart & Checkout Validation # - etc. ``` ### 2. Choose a Language **Rust (Recommended)** - Best performance, handles large carts **JavaScript** - Easier to learn, good for simpler logic ### 3. Function Structure ``` extensions/ └── my-discount/ ├── src/ │ └── run.rs (or run.js) ├── input.graphql ├── shopify.extension.toml └── Cargo.toml (for Rust) ``` ## Function Anatomy ### Configuration (shopify.extension.toml) ```toml api_version = "2025-01" [[extensions]] name = "Volume Discount" handle = "volume-discount" type = "function" [[extensions.targeting]] target = "purchase.product-discount.run" input_query = "src/run.graphql" export = "run" [extensions.build] command = "cargo wasi build --release" path = "target/wasm32-wasi/release/volume-discount.wasm" ``` ### Input Query (input.graphql) ```graphql query RunInput { cart { lines { id quantity merchandise { ... on ProductVariant { id product { id title hasAnyTag(tags: ["discount-eligible"]) } } } cost { amountPerQuantity { amount currencyCode } } } } discountNode { metafield(namespace: "volume-discount", key: "config") { value } } } ``` ## Product Discount Function (Rust) ```rust // src/run.rs use shopify_function::prelude::*; use shopify_function::Result; #[shopify_function_target(query_path = "src/run.graphql", schema_path = "schema.graphql")] fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> { let mut discounts = vec![]; // Parse configuration from metafield let config: Config = input.discount_node.metafield .as_ref() .map(|m| serde_json::from_str(&m.value).unwrap()) .unwrap_or_default(); for line in input.cart.lines { let quantity = line.quantity; // Check if eligible for volume discount if quantity >= config.minimum_quantity { let merchandise = match &line.merchandise { input::InputCartLinesMerchandise::ProductVariant(variant) => variant, _ => continue, }; // Check for eligible tag if merchandise.product.has_any_tag { discounts.push(output::Discount { targets: vec![output::Target::ProductVariant( output::ProductVariantTarget { id: merchandise.id.clone(), quantity: None, }, )], value: output::Value::Percentage(output::Percentage { value: Decimal::from_str(&config.discount_percentage).unwrap(), }), message: Some(format!("{}% volume discount", config.discount_percentage)), }); } } } Ok(output::FunctionRunResult { discounts, discount_application_strategy: output::DiscountApplicationStrategy::FIRST, }) } #[derive(Default, serde::Deserialize)] struct Config { minimum_quantity: i64, discount_percentage: String, } ``` ## Product Discount Function (JavaScript) ```javascript // src/run.js // @ts-check import { DiscountApplicationStrategy } from "../generated/api"; /** * @param {RunInput} input * @returns {FunctionRunResult} */ export function run(input) { const config = JSON.parse( input.discountNode.metafield?.value ?? '{"minimumQuantity": 5, "percentage": "10"}', ); const discounts = []; for (const line of input.cart.lines) { const variant = line.merchandise; // Check quantity threshold if (line.quantity >= config.minimumQuantity) { // Check for eligible products if ( variant.__typename === "ProductVariant" && variant.product.hasAnyTag ) { discounts.push({ targets: [ { productVariant: { id: variant.id, }, }, ], value: { percentage: { value: config.percentage, }, }, message: `${config.percentage}% volume discount`, }); } } } return { discounts, discountApplicationStrategy: DiscountApplicationStrategy.First, }; } ``` ## Delivery Customization ```rust // Rename, hide, or reorder delivery options use shopify_function::prelude::*; use shopify_function::Result; #[shopify_function_target(query_path = "src/run.graphql", schema_path = "schema.graphql")] fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> { let mut operations = vec![]; for method in input.cart.delivery_groups[0].delivery_options.iter() { // Hide express shipping for heavy orders if method.title.contains("Express") && cart_weight_exceeds_limit(&input) { operations.push(output::Operation::Hide(output::HideOperation { delivery_option_handle: method.handle.clone(), })); } // Rename delivery option if method.title.contains("Standard") { operations.push(output::Operation::Rename(output::RenameOperation { delivery_option_handle: method.handle.clone(), title: Some("Economy Shipping (5-7 days)".to_string()), })); } } Ok(output::FunctionRunResult { operations }) } ``` ## Payment Customization ```javascript // src/run.js export function run(input) { const cart = input.cart; const operations = []; // Calculate cart total const total = cart.cost.totalAmount.amount; // Hide COD for orders over $500 if (parseFloat(total) > 500) { const codMethod = input.paymentMethods.find((method) => method.name.includes("Cash on Delivery"), ); if (codMethod) { operations.push({ hide: { paymentMethodId: codMethod.id, }, }); } } // Reorder payment methods operations.push({ move: { paymentMethodId: input.paymentMethods[0].id, index: 2, }, }); return { operations }; } ``` ## Cart & Checkout Validation ```rust use shopify_function::prelude::*; use shopify_function::Result; #[shopify_function_target(query_path = "src/run.graphql", schema_path = "schema.graphql")] fn run(input: input::ResponseData) -> Result<output::FunctionRunResult> { let mut errors = vec![]; // Check minimum order value let total: f64 = input.cart.cost.total_amount.amount.parse().unwrap(); if total < 25.0 { errors.push(output::FunctionError { localized_message: "Minimum order value is $25.00".to_string(), target: output::Target::Cart, }); } // Check product availability by region for line in &input.cart.lines { if let input::InputCartLinesMerchandise::ProductVariant(variant) = &line.merchandise { if is_restricted_product(&variant, &input.cart.buyer_identity) { errors.push(output::FunctionError { localized_message: format!( "{} is not available in your region", variant.product.title ), target: output::Target::CartLine(output::CartLineTarget { id: line.id.clone(), }), }); } } } Ok(output::FunctionRunResult { errors }) } ``` ## Cart Transform Modify cart contents dynamically: ```javascript // src/run.js export function run(input) { const operations = []; for (const line of input.cart.lines) { const variant = line.merchandise; // Add free gift for orders with specific products if (variant.product.hasAnyTag && line.quantity >= 3) { operations.push({ expand: { cartLineId: line.id, expandedCartItems: [ { merchandiseId: variant.id, quantity: line.quantity, }, { merchandiseId: "gid://shopify/ProductVariant/FREE_GIFT_ID", quantity: 1, }, ], }, }); } } return { operations }; } ``` ## Testing Functions ### Local Testing ```bash # Test with sample input shopify app function run --path extensions/my-function # Provide input via stdin cat input.json | shopify app function run --path extensions/my-function ``` ### Sample Input JSON ```json { "cart": { "lines": [ { "id": "gid://shopify/CartLine/1", "quantity": 5, "merchandise": { "__typename": "ProductVariant", "id": "gid://shopify/ProductVariant/123", "product": { "id": "gid://shopify/Product/456", "title": "Test Product", "hasAnyTag": true } }, "cost": { "amountPerQuantity": { "amount": "10.00", "currencyCode": "USD" } } } ] }, "discountNode": { "metafield": { "value": "{"minimumQuantity": 3, "discountPercentage": "15"}" } } } ``` ## Deployment ```bash # Deploy function with app shopify app deploy # Function will be available to configure in admin ``` ## Configuration UI Create an admin UI to configure function settings: ```jsx // app/routes/app.discount.jsx import { authenticate } from "../shopify.server"; import { Form, TextField, Button, Card } from "@shopify/polaris"; export async function action({ request }) { const { admin } = await authenticate.admin(request); const formData = await request.formData(); // Create discount with function await admin.graphql( ` mutation CreateDiscount($discount: DiscountAutomaticAppInput!) { discountAutomaticAppCreate(automaticAppDiscount: $discount) { automaticAppDiscount { discountId } userErrors { field message } } } `, { variables: { discount: { title: formData.get("title"), functionId: "YOUR_FUNCTION_ID", startsAt: new Date().toISOString(), metafields: [ { namespace: "volume-discount", key: "config", value: JSON.stringify({ minimumQuantity: parseInt(formData.get("minQty")), discountPercentage: formData.get("percentage"), }), type: "json", }, ], }, }, }, ); return redirect("/app/discounts"); } ``` ## Performance Best Practices 1. **Use Rust for large carts** - JavaScript can timeout 2. **Minimize input query** - Only request needed data 3. **Avoid complex loops** - Keep logic simple 4. **Cache configuration** - Parse metafields once 5. **Test with real data** - Test large cart scenarios ## CLI Commands Reference | Command | Description | | -------------------------------- | --------------- | | `shopify app generate extension` | Create function | | `shopify app function run` | Test locally | | `shopify app function typegen` | Generate types | | `shopify app deploy` | Deploy function | ## Resources - [Functions Overview](https://shopify.dev/docs/apps/build/functions) - [Functions API Reference](https://shopify.dev/docs/api/functions) - [Discount Functions](https://shopify.dev/docs/apps/build/discounts) - [Delivery Customization](https://shopify.dev/docs/apps/build/checkout/delivery-shipping) - [Payment Customization](https://shopify.dev/docs/apps/build/payments) - [JavaScript for Functions](https://shopify.dev/docs/apps/build/functions/programming-languages/javascript-for-functions) - [Rust for Functions](https://shopify.dev/docs/apps/build/functions/programming-languages/rust-for-functions) For checkout UI, see the [checkout-customization](../checkout-customization/SKILL.md) skill.