Posta kutusu adreslerinde kurye seçeneklerini gizleme
Teslimat adresi posta kutusu (PO box) olduğunda UPS, FedEx gibi kurye seçeneklerini 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’ı, teslimat adresi posta kutusuysa (PO box) UPS, FedEx ve DHL gibi kurye seçeneklerini gizler, posta seçeneklerini açık bırakır. Kurye adları bir JSON metafield’dan gelir. Delivery Customization API’nin cart.delivery-options.transform.run hedefini kullanır, sürüm 2026-10. Shopify, kendi yerleşik kargo fiyatlarında adres bilgisinin gelmeyebileceğini belirtiyor.
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/po-box-address.input.json.
- shopify app deploy ile deploy edin ve özelleştirmeyi deliveryCustomizationCreate ile oluşturun.
- İsterseniz kuryelerinizi $app:function-configuration metafield’ına yazın; örneğin {"optionTitles": ["UPS", "FedEx"]}.
Kod
shopify.extension.tomlapi_version = "2026-10"
[[extensions]]
name = "Hide delivery options for PO boxes"
handle = "hide-delivery-po-boxes"
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 {
deliveryAddress {
address1
address2
}
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 = {
// Couriers that don't deliver to PO boxes, matched case-insensitively anywhere in the option title.
optionTitles: ["UPS", "FedEx", "DHL", "Express", "Courier"],
};
/**
* "PO box" spellings anywhere in the line, after a space or punctuation:
* "P.O. Box", "PO Box", "Post Office Box", "Postfach", Turkish "Posta Kutusu"
* and "PK" followed by a number ("Kadıköy PK 34"). The leading boundary keeps
* words such as "Spk" or "Park" from matching.
*/
const PO_BOX =
/(?:^|[^\p{L}\p{N}])(?:p\.?\s*o\.?\s*box|post\s*office\s*box|post\s*box|postfach|posta\s*kutusu|p\.?\s*k\.?\s*\d)/iu;
/** @param {string | null | undefined} line */
const isPoBox = (line) => PO_BOX.test(line ?? "");
/**
* @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());
const operations = input.cart.deliveryGroups
.filter((group) => isPoBox(group.deliveryAddress?.address1) || isPoBox(group.deliveryAddress?.address2))
.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-couriers.input.json{
"cart": {
"deliveryGroups": [
{
"deliveryAddress": { "address1": "Atatürk Cad. No: 5", "address2": "PK 112" },
"deliveryOptions": [
{ "handle": "77ff-ptt", "title": "PTT Kargo" },
{ "handle": "77ff-yurtici", "title": "Yurtiçi Kargo" }
]
}
]
},
"deliveryCustomization": { "metafield": { "jsonValue": { "optionTitles": ["Yurtiçi"] } } }
}
tests/configured-couriers.output.json{ "operations": [ { "deliveryOptionHide": { "deliveryOptionHandle": "77ff-yurtici" } } ] }
tests/po-box-address.input.json{
"cart": {
"deliveryGroups": [
{ "deliveryAddress": { "address1": "P.O. Box 4521", "address2": null }, "deliveryOptions": [
{ "handle": "c0de-usps", "title": "USPS Priority Mail" },
{ "handle": "c0de-ups", "title": "UPS Ground" },
{ "handle": "c0de-fedex", "title": "FedEx 2Day" }
] }
]
},
"deliveryCustomization": { "metafield": null }
}
tests/po-box-address.output.json{
"operations": [
{ "deliveryOptionHide": { "deliveryOptionHandle": "c0de-ups" } },
{ "deliveryOptionHide": { "deliveryOptionHandle": "c0de-fedex" } }
]
}
tests/po-box-after-name.input.json{
"cart": {
"deliveryGroups": [
{
"deliveryAddress": {
"address1": "John Smith PO Box 5",
"address2": null
},
"deliveryOptions": [
{
"handle": "c0de-usps",
"title": "USPS Priority Mail"
},
{
"handle": "c0de-ups",
"title": "UPS Ground"
},
{
"handle": "c0de-fedex",
"title": "FedEx 2Day"
}
]
}
]
},
"deliveryCustomization": {
"metafield": null
}
}tests/po-box-after-name.output.json{
"operations": [
{ "deliveryOptionHide": { "deliveryOptionHandle": "c0de-ups" } },
{ "deliveryOptionHide": { "deliveryOptionHandle": "c0de-fedex" } }
]
}
tests/street-address.input.json{
"cart": {
"deliveryGroups": [
{ "deliveryAddress": { "address1": "120 Boxwood Lane", "address2": "Apt 4" }, "deliveryOptions": [
{ "handle": "c0de-usps", "title": "USPS Priority Mail" },
{ "handle": "c0de-ups", "title": "UPS Ground" },
{ "handle": "c0de-fedex", "title": "FedEx 2Day" }
] }
]
},
"deliveryCustomization": { "metafield": null }
}
tests/street-address.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
- Shopify’ın referansına göre posta kutusu adreslerinde seçenek gizleme yalnızca kargo servislerinden (carrier service) ya da kargo uygulamalarından gelen fiyatlarda destekleniyor; yerleşik fiyatlarda adres bilgisi gelmeyebilir.
- Posta kutusu tespiti bir metin kontrolüdür (“PO Box”, “P.O. Box”, “Post Office Box”, “Postfach”, Türkçe “Posta Kutusu”/“PK”). Alışılmadık yazımlar eşleşmez.
- Posta kutusuna siparişi tamamen durdurmak için doğrulama (validation) örneğini kullanın; o örnek checkout’u bir mesajla engeller.
Sık sorulan sorular
- Posta kutusunu engellemek yerine neden seçenekleri gizleyelim?
- Birçok mağaza posta kutusuna posta servisiyle gönderebilir ama kuryeyle gönderemez. Yalnızca kurye seçeneklerini gizlemek bu siparişleri mümkün tutar.
- Shopify’ın kendi kargo fiyatlarıyla çalışır mı?
- Güvenilir şekilde çalışmaz. Shopify, yerleşik fiyatlarda posta kutusunu tespit etmek için gereken adres bilgisinin Function’a gelmeyebileceğini söylüyor. Kargo firması hesaplı ve uygulama fiyatlarında destekleniyor.
- Posta kutusunu başka dillerde de algılayabilir miyim?
- Evet. Koddaki PO_BOX desenine yerel yazımı ekleyin, örneğin İspanyolca adresler için “Apartado”, ve bunun için bir test dosyası yazın.
Shopify belgeleri
- 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.
