# Activate a delivery, payment or validation Function

> Turn on a deployed Function in a store with deliveryCustomizationCreate, paymentCustomizationCreate or validationCreate, with its settings as a metafield.

Page: https://lintelagency.com/resources/graphql/register-function-customization

## In short

A delivery, payment or validation Function runs only after you activate it on the store. Call deliveryCustomizationCreate with the Function’s functionHandle, a title and enabled: true; use paymentCustomizationCreate for payment Functions and validationCreate for cart and checkout validation. Pass settings as a JSON metafield in the same call, and read it in the Function’s input query.

## Facts

- **API:** Admin GraphQL API
- **Operations:** deliveryCustomizationCreate, paymentCustomizationCreate, validationCreate
- **Access scopes:** write_delivery_customizations, write_payment_customizations, write_validations
- **API version:** 2026-10
- **Last checked:** 2 November 2026

## How to use it

1. Deploy the app with the Function and note the handle from its shopify.extension.toml.
2. Send EnableDeliveryCustomization with the handle, a title the merchant will see in Settings and enabled: true.
3. Add the Function’s settings as a json metafield in the same input.
4. For a payment Function, send the same input to paymentCustomizationCreate; for a validation, use validationCreate, where the switch is called enable.

## Code

### delivery-customization-create.graphql

```graphql
mutation EnableDeliveryCustomization($customization: DeliveryCustomizationInput!) {
  deliveryCustomizationCreate(deliveryCustomization: $customization) {
    deliveryCustomization {
      id
      title
      enabled
      functionId
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### delivery-customization-create.variables.json

```json
{
  "customization": {
    "functionHandle": "hide-express-heavy-carts",
    "title": "Hide express shipping over 20 kg",
    "enabled": true,
    "metafields": [
      {
        "namespace": "$app",
        "key": "function-configuration",
        "type": "json",
        "value": "{\"maxWeightKg\":20,\"rateTitleContains\":\"Express\"}"
      }
    ]
  }
}
```

### delivery-customization-create.response.json

```json
{
  "data": {
    "deliveryCustomizationCreate": {
      "deliveryCustomization": {
        "id": "gid://shopify/DeliveryCustomization/1234567890",
        "title": "Hide express shipping over 20 kg",
        "enabled": true,
        "functionId": "00000000-0000-0000-0000-000000000000"
      },
      "userErrors": []
    }
  }
}
```

### payment-customization-create.graphql

```graphql
mutation EnablePaymentCustomization($customization: PaymentCustomizationInput!) {
  paymentCustomizationCreate(paymentCustomization: $customization) {
    paymentCustomization {
      id
      title
      enabled
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### payment-customization-create.variables.json

```json
{
  "customization": {
    "functionHandle": "hide-cod-above-total",
    "title": "Hide cash on delivery above 500",
    "enabled": true
  }
}
```

### payment-customization-create.response.json

```json
{
  "data": {
    "paymentCustomizationCreate": {
      "paymentCustomization": {
        "id": "gid://shopify/PaymentCustomization/1234567890",
        "title": "Hide cash on delivery above 500",
        "enabled": true
      },
      "userErrors": []
    }
  }
}
```

### validation-create.graphql

```graphql
mutation EnableValidation($validation: ValidationCreateInput!) {
  validationCreate(validation: $validation) {
    validation {
      id
      title
      enabled
      blockOnFailure
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### validation-create.variables.json

```json
{
  "validation": {
    "functionHandle": "block-po-box-addresses",
    "title": "Block PO box addresses",
    "enable": true,
    "blockOnFailure": false
  }
}
```

### validation-create.response.json

```json
{
  "data": {
    "validationCreate": {
      "validation": {
        "id": "gid://shopify/Validation/1234567890",
        "title": "Block PO box addresses",
        "enabled": true,
        "blockOnFailure": false
      },
      "userErrors": []
    }
  }
}
```

## Limits and edge cases

- functionHandle is scoped to your app: it only finds Functions your app deployed.
- validationCreate also takes blockOnFailure: when true, a Function error such as a timeout blocks checkout too; validation errors always block.
- Each call creates a new customization. To change one, use the matching …Update mutation with its ID instead of creating a second one.
- To switch a customization off without deleting it, set enabled: false with deliveryCustomizationUpdate or paymentCustomizationUpdate.

## Questions

### Why isn’t my delivery customization Function running?

Deploying it isn’t enough. A delivery customization that uses it must exist on the store, created with deliveryCustomizationCreate and enabled: true.

### What is the difference between a payment customization and a validation?

A payment customization hides, renames or reorders payment methods. A validation blocks checkout with an error message when the cart breaks a rule.

### How do I pass settings to a checkout Function?

Save them as a metafield on the customization or validation, in the create call or later with metafieldsSet, and read the metafield in the Function’s input query.

## Shopify documentation

- [deliveryCustomizationCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryCustomizationCreate)
- [paymentCustomizationCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/paymentCustomizationCreate)
- [validationCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/validationCreate)

## Related

- [Hide Cash on Delivery above a cart total](https://lintelagency.com/resources/shopify-functions/hide-cash-on-delivery-above-cart-total)
- [Hide express shipping for heavy carts](https://lintelagency.com/resources/shopify-functions/hide-express-shipping-for-heavy-carts)
- [Block PO box shipping addresses](https://lintelagency.com/resources/shopify-functions/block-po-box-addresses)
- [Delivery customization: hide, rename and sort shipping options](https://lintelagency.com/journal/shopify-delivery-customization-function)
- [Blocking a Shopify checkout that breaks your rules, with Cart and Checkout Validation](https://lintelagency.com/journal/shopify-checkout-validation)
- [Configuring Functions with metafields, so rules change without deploys](https://lintelagency.com/journal/configuring-functions-with-metafields)

License: MIT. Free to use in your own store and in client work.