Shopify Function Examples

This function demonstrates how to generate pickup point delivery options by fetching data from an external API via an HTTP request. The implementation is split into two distinct targets:

1. Fetch target: Responsible for generating the HTTP request. It takes input (like delivery address country and coordinates) and outputs a FunctionFetchResult containing the request details (method, URL, headers, etc.).
2. Run target: Responsible for processing the API response. It takes the fetchResult (status and body) and produces the final pickup point data in the format specified by FunctionRunResult.

This two-step process allows the function to bridge external data sources with Shopify's delivery option generation logic.

// The function uses two targets:
// 1. Fetch target (src/fetch.rs) -> generates HTTP request
// 2. Run target (src/run.rs) -> parses response and produces pickup points

To enable the Expand bundle operation, the bundle's parent product_variant must have two specific metafields:

1. component_reference

   • Namespace: custom
   • Key: component_reference
   • Content Type: variants
   • Value: An array of product_variant GIDs.

2. component_quantities

   • Namespace: custom
   • Key: component_quantities
   • Content Type: integer
   • Value: An array of integers corresponding to the quantities of the variants in component_reference.

Example Configuration: For a bundle containing two shirts (ID 3) and one pair of pants (ID 4):

• component_reference: ["gid://shopify/ProductVariant/3", "gid://shopify/ProductVariant/4"]
• component_quantities: [2, 1]

// component_reference
[
  "gid://shopify/ProductVariant/3",
  "gid://shopify/ProductVariant/4"
]

// component_quantities
[2, 1]

To enable the Merge bundle operation, each child component belonging to a bundle must have a metafield with the following properties:

• Namespace: custom
• Key: component_parents
• Content Type: JSON

The value of this metafield must be an array of objects. Each object defines a bundle rule that links the child to a parent variant.

Bundle Rule Schema:

{
  "id": <Bundle parent ProductVariant ID>,
  "component_reference": {
    "value": <Array of Bundle children ProductVariant IDs>
  },
  "component_quantities": {
    "value": <Array of quantities for children ProductVariant IDs>
  }
}

Important Requirements:

1. ID Format: All IDs must be Shopify product_variant GIDs (e.g., gid://shopify/ProductVariant/6).
2. Ordering: The order of IDs in component_reference must match the order of quantities in component_quantities.
3. Completeness: The merge operation only triggers if the extension detects all components of a given bundle in the cart at checkout.

[
  {
    "id": "gid://shopify/ProductVariant/6",
    "component_reference": {
      "value": [
        "gid://shopify/ProductVariant/3",
        "gid://shopify/ProductVariant/4"
      ]
    },
    "component_quantities": {
      "value": [2, 1]
    }
  }
]

This template uses SQLite by default. If you switch to MongoDB, you must adjust your Prisma schema and configuration because MongoDB does not support prisma migrate.

Mapping the ID field

Prisma expects the ID field to be the ID of the session, not the MongoDB _id field. You must map the _id field to a new session_id field in your schema:

model Session {
  session_id  String    @id @default(auto()) @map("_id") @db.ObjectId
  id          String    @unique
  ...
}

Using db push instead of migrate

Since MongoDB doesn't support prisma migrate, use prisma db push. Update your shopify.web.toml file to include these commands:

[commands]
predev = "npx prisma generate && npx prisma db push"
dev = "npx prisma migrate deploy && npm exec react-router dev"

Requirement: Replica Set

To perform transactions, your MongoDB server must be running as a replica set.

To implement bundling using the cart_transform function in this sample app, you must configure specific metafields on product variants to define the relationship between a 'parent' bundle variant and its 'child' component variants.

1. Configure Variant Metafield Definitions

Create the following three metafield definitions under Settings > Custom data > Variants:

JSON Schema for custom.component_parents:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Bundle component parents",
  "description": "A definition of the bundle a child belongs to",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "ID of bundle parent product variant: gid://shopify/ProductVariant/<id number>",
        "type": "string"
      },
      "component_reference": {
        "type": "object",
        "properties": {
          "value": {
            "description": "Array of product variant IDs: [gid://shopify/ProductVariant/<id number>]",
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
          }
        },
        "required": ["value"]
      },
      "component_quantities": {
        "type": "object",
        "properties": {
          "value": {
            "description": "Array of quantities of product variants defined in component_reference: [1]",
            "type": "array",
            "items": {
              "type": "integer"
            },
            "minItems": 1
          }
        },
        "required": ["value"]
      },
      "price_adjustment": {
        "type": "object",
        "properties": {
          "value": {
            "description": "Array of quantities of product variants defined in component_reference: [1]",
            "type": "array",
            "items": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "required": ["value"]
      }
    },
    "required": ["id", "component_reference", "component_quantities"]
  }
}

2. Define the Bundle Parent

1. Create a product to act as the bundle. It must have at least one variant in inventory, a price > 0, and at least one option.
2. On the Parent Product Variant page, locate the Metafields section.
3. Set custom.component_reference by selecting the product variants that will be included in the bundle.
4. Set custom.component_quantities by entering quantities that correspond to the order of variants in component_reference.
5. Note the Parent Variant ID from the browser URL (e.g., gid://shopify/ProductVariant/<id>).

3. Define the Bundle on Child Variants

For each child variant included in the bundle, you must update its custom.component_parents metafield with a JSON array matching the parent's configuration:

[
  {
    "id": "gid://shopify/ProductVariant/<ID of parent product variant>",
    "component_reference": {
      "value": [
        "gid://shopify/ProductVariant/<ID of first child product variant>",
        "gid://shopify/ProductVariant/<ID of second child product variant>"
      ]
    },
    "component_quantities": {
      "value": [
        <quantity of first product variant in bundle>,
        <quantity of second product variant in bundle>
      ]
    }
  }
]