Ağır sepetlerde ekspres kargoyu gizleme
Bir gönderinin ağırlığı sınırı (varsayılan 30 kg) aştığında ekspres seçenekleri gizleyen Shopify teslimat özelleştirme Function’ı; test edilmiş JavaScript.
- Function API
- Delivery Customization
- Hedef (target)
- cart.delivery-options.transform.run
- Plan
- Herkese açık uygulamada her plan; özel uygulamada Shopify Plus
- Uygulama yetkisi
- write_delivery_customizations
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Bu teslimat özelleştirme Function’ı her gönderideki ürünlerin ağırlığını toplar ve sınırı (varsayılan 30 kg) aşınca ekspres seçenekleri gizler. Sınır ve seçenek adları bir JSON metafield’dan gelir. Delivery Customization API’nin cart.delivery-options.transform.run hedefini kullanır (sürüm 2026-10) ve herkese açık bir uygulamada her planda çalışır.
Nasıl kullanılır
- Shopify CLI ile bir uygulama oluşturun ve uzantıyı ekleyin: shopify app generate extension --template delivery_customization, dil olarak JavaScript.
- Oluşturulan shopify.extension.toml dosyasını ve src/ içindeki iki dosyayı aşağıdakilerle değiştirin.
- Testleri çalıştırın: shopify app function run --input tests/heavy-cart-in-pounds.input.json.
- shopify app deploy ile deploy edin ve özelleştirmeyi deliveryCustomizationCreate ile oluşturun.
- İsterseniz $app:function-configuration metafield’ını ayarlayın; örneğin {"maxWeightKg": 20, "optionTitles": ["Ekspres", "Aynı Gün"]}.
Kod
shopify.extension.tomlapi_version = "2026-10"
[[extensions]]
name = "Hide express shipping for heavy carts"
handle = "hide-express-heavy-carts"
type = "function"
[[extensions.targeting]]
target = "cart.delivery-options.transform.run"
input_query = "src/cart_delivery_options_transform_run.graphql"
export = "cart-delivery-options-transform-run"
[extensions.build]
command = ""
path = "dist/function.wasm"
src/cart_delivery_options_transform_run.graphqlquery CartDeliveryOptionsTransformRunInput {
cart {
deliveryGroups {
cartLines {
quantity
merchandise {
__typename
... on ProductVariant {
weight
weightUnit
}
}
}
deliveryOptions {
handle
title
}
}
}
deliveryCustomization {
metafield(namespace: "$app", key: "function-configuration") {
jsonValue
}
}
}
src/cart_delivery_options_transform_run.js// @ts-check
/**
* @typedef {import("../generated/api").CartDeliveryOptionsTransformRunInput} CartDeliveryOptionsTransformRunInput
* @typedef {import("../generated/api").CartDeliveryOptionsTransformRunResult} CartDeliveryOptionsTransformRunResult
*/
/** Settings stored as JSON in the customization's metafield. */
const DEFAULT_CONFIG = {
// Total product weight per shipment, in kilograms, above which the options are hidden.
maxWeightKg: 30,
// Matched case-insensitively anywhere in the delivery option title.
optionTitles: ["Express", "Ekspres"],
};
/** Kilograms per unit of Shopify's WeightUnit values. */
const KG_PER_UNIT = { GRAMS: 0.001, KILOGRAMS: 1, OUNCES: 0.028349523125, POUNDS: 0.45359237 };
/**
* Product weight of one delivery group. Variants without a weight count as 0,
* so missing data never hides an option by itself.
* @param {CartDeliveryOptionsTransformRunInput["cart"]["deliveryGroups"][number]} group
*/
function groupWeightKg(group) {
return group.cartLines.reduce((sum, line) => {
if (line.merchandise.__typename !== "ProductVariant") return sum;
const { weight, weightUnit } = line.merchandise;
return sum + (weight ?? 0) * (KG_PER_UNIT[weightUnit] ?? 0) * line.quantity;
}, 0);
}
/**
* @param {CartDeliveryOptionsTransformRunInput} input
* @returns {CartDeliveryOptionsTransformRunResult}
*/
export function cartDeliveryOptionsTransformRun(input) {
const config = { ...DEFAULT_CONFIG, ...input.deliveryCustomization?.metafield?.jsonValue };
const titles = config.optionTitles.map((title) => title.toLowerCase());
// Each delivery group is a separate shipment, so weigh them one by one.
const operations = input.cart.deliveryGroups
.filter((group) => groupWeightKg(group) > config.maxWeightKg)
.flatMap((group) => group.deliveryOptions)
.filter((option) => titles.some((title) => (option.title ?? "").toLowerCase().includes(title)))
.map((option) => ({ deliveryOptionHide: { deliveryOptionHandle: option.handle } }));
return { operations };
}
Test girdisi ve beklenen çıktı
tests/configured-limit.input.json{
"cart": {
"deliveryGroups": [
{
"cartLines": [
{ "quantity": 12, "merchandise": { "__typename": "ProductVariant", "weight": 900, "weightUnit": "GRAMS" } }
],
"deliveryOptions": [
{ "handle": "e5f6-standard", "title": "Standart Kargo" },
{ "handle": "e5f6-same-day", "title": "Aynı Gün Teslimat" }
]
}
]
},
"deliveryCustomization": {
"metafield": { "jsonValue": { "maxWeightKg": 10, "optionTitles": ["Aynı Gün"] } }
}
}
tests/configured-limit.output.json{ "operations": [ { "deliveryOptionHide": { "deliveryOptionHandle": "e5f6-same-day" } } ] }
tests/heavy-cart-in-pounds.input.json{
"cart": {
"deliveryGroups": [
{
"cartLines": [
{ "quantity": 3, "merchandise": { "__typename": "ProductVariant", "weight": 25, "weightUnit": "POUNDS" } },
{ "quantity": 1, "merchandise": { "__typename": "ProductVariant", "weight": null, "weightUnit": "KILOGRAMS" } }
],
"deliveryOptions": [
{ "handle": "a1b2c3d4-standard", "title": "Standard Shipping" },
{ "handle": "a1b2c3d4-express", "title": "Express Shipping" }
]
}
]
},
"deliveryCustomization": { "metafield": null }
}
tests/heavy-cart-in-pounds.output.json{ "operations": [ { "deliveryOptionHide": { "deliveryOptionHandle": "a1b2c3d4-express" } } ] }
tests/light-cart.input.json{
"cart": {
"deliveryGroups": [
{
"cartLines": [
{ "quantity": 2, "merchandise": { "__typename": "ProductVariant", "weight": 4.5, "weightUnit": "KILOGRAMS" } }
],
"deliveryOptions": [
{ "handle": "a1b2c3d4-standard", "title": "Standard Shipping" },
{ "handle": "a1b2c3d4-express", "title": "Express Shipping" }
]
}
]
},
"deliveryCustomization": { "metafield": null }
}
tests/light-cart.output.json{ "operations": [] }
Lintel tarafından yazıldı. MIT lisansı: kendi mağazanızda da müşteri işlerinizde de ücretsiz kullanabilirsiniz.
Sınırlar ve özel durumlar
- Ağırlık, yönetim panelindeki varyant ağırlığı çarpı adettir; ambalaj dahil değildir. Ağırlığı girilmemiş varyantlar sıfır sayılır.
- Gram, ons ve pound cinsinden ağırlıklar karşılaştırmadan önce kilograma çevrilir.
- Her teslimat grubu ayrı tartılır; bölünmüş sepette yalnızca ağır gönderi ekspres seçeneğini kaybeder.
- Kargo firmanız ağır paketleri zaten kabul etmiyorsa önce onun fiyatlarına bakın; Function yalnızca checkout’un sunduğu seçenekleri gizleyebilir.
Sık sorulan sorular
- Shopify ağırlığa göre bir kargo seçeneğini gizleyebilir mi?
- Evet, bir teslimat özelleştirme Function’ıyla. Function her varyantın ağırlığını ve adedini okur, gönderi başına toplar ve toplam sınırı aşarsa belirttiğiniz seçenekleri gizler.
- Function ambalajlı paket ağırlığını görür mü?
- Hayır. Her varyantın ağırlığını ve adedini görür. Ambalajınız ağırsa sınıra biraz pay bırakın.
- Ağırlık yerine büyük ebatlı ürünlerde ekspresi gizleyebilir miyim?
- Evet, ürün etiketiyle. Ürün etiketine göre kargo seçeneklerini gizleyen örneğe bakın; ikisi ayrı özelleştirmeler olarak birlikte çalışabilir.
Shopify belgeleri
İlgili içerikler
- Function API sürümü 2026-10 için yazıldı ve gösterilen tarihte Shopify’ın başvuru belgeleriyle karşılaştırıldı. Shopify her çeyrekte yeni bir sürüm yayımlar.
- Function içeren özel (custom) uygulamalar yalnızca Shopify Plus mağazalarında çalışır. Aynı Function herkese açık bir uygulamada, sayfada aksi yazmıyorsa her planda çalışır.
- Her örnek test verileriyle gelir ve yayımlamadan önce bu testleri çalıştırırız. Kodu değiştirdikten sonra testleri tekrar çalıştırın: shopify app function run.
- MIT lisansı. Kodu kendi mağazanızda da müşteri işlerinizde de kullanabilirsiniz.
Mağazanız için kurulmasını, test edilmesini ve bakımını isterseniz: Shopify Functions geliştirme.
