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.
- API
- Admin GraphQL API
- Operations
- deliveryCustomizationCreate, paymentCustomizationCreate, validationCreate
- Access scopes
- write_delivery_customizations, write_payment_customizations, write_validations
- API version
- 2026-10
- Last checked
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.
How to use it
- Deploy the app with the Function and note the handle from its shopify.extension.toml.
- Send EnableDeliveryCustomization with the handle, a title the merchant will see in Settings and enabled: true.
- Add the Function’s settings as a json metafield in the same input.
- 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.graphqlmutation EnableDeliveryCustomization($customization: DeliveryCustomizationInput!) {
deliveryCustomizationCreate(deliveryCustomization: $customization) {
deliveryCustomization {
id
title
enabled
functionId
}
userErrors {
code
field
message
}
}
}
delivery-customization-create.variables.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{
"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.graphqlmutation EnablePaymentCustomization($customization: PaymentCustomizationInput!) {
paymentCustomizationCreate(paymentCustomization: $customization) {
paymentCustomization {
id
title
enabled
}
userErrors {
code
field
message
}
}
}
payment-customization-create.variables.json{
"customization": {
"functionHandle": "hide-cod-above-total",
"title": "Hide cash on delivery above 500",
"enabled": true
}
}
payment-customization-create.response.json{
"data": {
"paymentCustomizationCreate": {
"paymentCustomization": {
"id": "gid://shopify/PaymentCustomization/1234567890",
"title": "Hide cash on delivery above 500",
"enabled": true
},
"userErrors": []
}
}
}
validation-create.graphqlmutation EnableValidation($validation: ValidationCreateInput!) {
validationCreate(validation: $validation) {
validation {
id
title
enabled
blockOnFailure
}
userErrors {
code
field
message
}
}
}
validation-create.variables.json{
"validation": {
"functionHandle": "block-po-box-addresses",
"title": "Block PO box addresses",
"enable": true,
"blockOnFailure": false
}
}
validation-create.response.json{
"data": {
"validationCreate": {
"validation": {
"id": "gid://shopify/Validation/1234567890",
"title": "Block PO box addresses",
"enabled": true,
"blockOnFailure": false
},
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
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
Related
- Hide Cash on Delivery above a cart total
- Hide express shipping for heavy carts
- Block PO box shipping addresses
- Delivery customization: hide, rename and sort shipping options
- Blocking a Shopify checkout that breaks your rules, with Cart and Checkout Validation
- Configuring Functions with metafields, so rules change without deploys
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
