Metafield'lar
Uygulamanız ürüne, siparişe, üyeye, kategoriye, içerik sayfasına ve blog yazısına kendi verisini metafield olarak yazabilir. Mağazaya özgü ayarlarınızı da kurulum metafield'ı olarak saklayabilirsiniz. Eşlemeyi kendi veritabanınızda tutmanız gerekmez; veri mağazada, ilgili kaydın yanında durur.
Bir kayda bağlı olmayan kendi verinizi (SSS, beden tablosu, mağaza listesi gibi) metaobject olarak tutarsınız: alanlarını siz tanımlarsınız, kayıtlarını oluşturur, okur, günceller ve silersiniz.
Metafield ve metaobject uç noktaları ayrı bir kapsam istemez; uygulamanın kurulu olması yeterlidir. Uygulamanız yalnız kendi tanımlarını ve değerlerini görür; mağazanın ve başka uygulamaların metafield ve metaobject'lerini hiçbir uç noktadan okuyamaz.
Kavramlar
- Tanım (
metafield-definitions): hangi kayıt türüne, hangi anahtarla, hangi tipte değer yazılacağı. Tanımı oluşturan uygulama tanımın sahibidir; tanımı yalnız o değiştirir ve siler. - Değer (
metafields): bir tanımın tek bir kayıttaki karşılığı (ör. 42 numaralı ürününgaranti_suresideğeri). - Metaobject tanımı (
metaobject-definitions): kendi nesne türünüz ve alanları (ör.sss:soru,yanit). - Metaobject (
metaobjects): bir metaobject tanımının tek bir kaydı (ör. bir SSS maddesi).
Sahip kaynak (ownerResource) | Gereken kapsam |
|---|---|
product | read_products |
category | read_products |
order | read_orders |
customer | read_customers |
content | read_content |
blog | read_content |
installation | — |
Metafield için ayrı bir okuma ya da yazma kapsamı yoktur; tanım oluşturmak da kapsam istemez. Bir kayda değer yazmak ya da kaydın değerini okumak için o kaydı görebilmeniz yeterlidir: ürün değeri için read_products, sipariş için read_orders. Değer yazmak kaydın kendisini değiştirmediği için write_ kapsamı gerekmez. Kaydı görme kapsamınız yoksa 403 alırsınız.
Sınırlar
| Sınır | Değer |
|---|---|
| Tanım sayısı | Uygulama başına, sahip kaynak başına 10 (ör. üründe 10, siparişte 10) |
| Metaobject tanımı sayısı | Uygulama başına 10 |
| Metaobject alan sayısı | Tanım başına 20 |
| Değer boyutu | 16 KB (metafield değeri ve metaobject alan değeri) |
| Anahtar | Küçük harfle başlar; a-z, 0-9, _; en fazla 64 karakter |
| Anahtar tekilliği | Metafield anahtarı aynı sahip kaynakta, metaobject tanımı anahtarı mağazanın bütün nesnelerinde tekildir; mağaza ya da başka bir uygulama aynı anahtarı kullanıyorsa 422 döner, farklı bir anahtar seçin. installation tanımlarında anahtar yalnız sizin tanımlarınız arasında tekildir. |
Daha büyük veri için kendi veritabanınızı kullanın ve metafield'a yalnız kimliğini yazın.
Tanımlar
| Uç nokta | Metot | Kapsam |
|---|---|---|
/config/metafield-definitions | GET, POST | — |
/config/metafield-definitions/{id} | GET, PATCH, DELETE | — |
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafield-definitions \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "metafield-definitions",
"attributes": {
"ownerResource": "product",
"key": "garanti_suresi",
"name": "Garanti süresi (ay)",
"fieldType": "number",
"adminAccess": "read",
"retention": "delete"
}
}
}'
| Alan | Açıklama |
|---|---|
ownerResource | product, category, order, customer, content, blog, installation. Oluşturduktan sonra değişmez. |
key | Anahtar. Oluşturduktan sonra değişmez. |
name | Panelde görünen ad. |
fieldType | Değer tipi (aşağıdaki tablo). Oluşturduktan sonra değişmez. |
settings | Tipe özgü ayarlar; seçim tiplerinde seçenekler (options). |
hasLocale | Değer dile göre ayrı tutulsun mu. |
adminAccess | Mağaza panelinde görünürlük: hidden (görünmez), read (salt-okur, varsayılan), write (mağaza düzenleyebilir). |
retention | Uygulama kaldırılınca: delete (tanım ve tüm değerleri silinir, varsayılan) ya da keep (tanım ve değerler 90 gün saklanır; uygulama geri kurulursa size döner, kurulmazsa mağazaya devredilir). |
storefrontAccess | none (varsayılan) ya da read. Vitrin ve tema okuması henüz açık değildir; değer saklanır. |
appPrefix | Salt-okur; tanımın sahibi olan uygulama. |
Filtreler: id, ownerResource, key. Silinen tanımın bütün değerleri de silinir.
Değerler
| Uç nokta | Metot | Kapsam |
|---|---|---|
/config/metafields | GET, POST | Sahip kaydın okuma kapsamı |
/config/metafields/{id} | GET, PATCH, DELETE | Sahip kaydın okuma kapsamı |
POST upsert'tür: aynı kayıt, tanım ve dil için değer varsa güncellenir, yoksa oluşturulur. İki durumda da 201 ve güncel kayıt döner.
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafields \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "metafields",
"attributes": {
"ownerResource": "product",
"ownerId": 42,
"definitionId": 318,
"value": 24
}
}
}'
| Alan | Açıklama |
|---|---|
ownerResource, ownerId | Değerin yazıldığı kayıt. |
definitionId | Tanımın kimliği. |
value | Değer; metin, sayı ya da mantıksal. multiselect ve checkbox liste alır. Her zaman metin olarak döner (liste JSON metni olarak). |
langCode | İsteğe bağlı dil; verilmezse mağazanın varsayılan dili. |
key, fieldType, appPrefix | Salt-okur; tanımdan gelir. |
Bir kaydın bütün değerleri:
curl 'https://<domain>/api/v3/admin/2026-01/config/metafields?filter[ownerResource]=product&filter[ownerId]=42' \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json'
Filtreler: id, ownerResource, ownerId (virgülle birden çok), definitionId (virgülle birden çok), key, langCode.
Değer tipleri
fieldType | Kabul edilen değer |
|---|---|
text, textarea, editor, hidden, tel | Metin |
number, range | Sayı |
email | E-posta adresi |
url | URL |
date | YYYY-AA-GG |
time, datetime-local | Metin |
color | Onaltılık renk (#1a2b3c) |
checkbox, radio, select | Tek değer; checkbox liste de alır |
multiselect | Liste |
Tipe uymayan değer 422 döner.
Kurulum metafield'ları
Kurulum metafield'ı bir kayda değil, uygulamanızın bu mağazadaki kurulumuna aittir. Mağazaya özgü ayarları, eşitleme durumunu ya da dış sistemdeki hesap kimliğini burada saklayın.
- Tanımı
ownerResource: "installation"ile oluşturun.adminAccessher zamanhidden,storefrontAccessher zamannoneolur; başka değer422döner. - Değer yazarken
ownerIdgöndermeyin; gönderirseniz422döner. Değer, isteği yapan uygulamanın kurulumuna yazılır ve yanıttaownerIdher zaman0'dır. - Değerleri yalnız siz görürsünüz. Mağaza panelinde, mağazanın kendi istemcisinde ve vitrinde görünmez; başka uygulamalar okuyamaz.
- Kapsam gerekmez. Tanım sayısı (10) ve değer boyutu (16 KB) sınırları burada da geçerlidir.
curl -X POST https://<domain>/api/v3/admin/2026-01/config/metafields \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "metafields",
"attributes": {
"ownerResource": "installation",
"definitionId": 325,
"value": "{\"syncEnabled\":true,\"warehouseId\":3}"
}
}
}'
Kurulumunuzun bütün değerleri:
curl 'https://<domain>/api/v3/admin/2026-01/config/metafields?filter[ownerResource]=installation' \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json'
Metaobject tanımları
| Uç nokta | Metot | Kapsam |
|---|---|---|
/config/metaobject-definitions | GET, POST | — |
/config/metaobject-definitions/{id} | GET, PATCH, DELETE | — |
Tanımı alanlarıyla birlikte tek istekte oluşturun:
curl -X POST 'https://<domain>/api/v3/admin/2026-01/config/metaobject-definitions' \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "metaobject-definitions",
"attributes": {
"key": "sss",
"name": "Sıkça sorulan sorular",
"fields": [
{ "key": "soru", "name": "Soru", "fieldType": "text" },
{ "key": "yanit", "name": "Yanıt", "fieldType": "textarea" },
{ "key": "sira", "name": "Sıra", "fieldType": "number" }
],
"adminAccess": "read",
"retention": "delete"
}
}
}'
201 ile tanım döner:
{
"data": {
"type": "metaobject-definitions",
"id": "57",
"attributes": {
"key": "sss",
"name": "Sıkça sorulan sorular",
"fields": [
{ "key": "soru", "name": "Soru", "fieldType": "text" },
{ "key": "yanit", "name": "Yanıt", "fieldType": "textarea" },
{ "key": "sira", "name": "Sıra", "fieldType": "number" }
],
"appPrefix": "app.ornek-sss",
"retention": "delete",
"adminAccess": "read",
"storefrontAccess": "none",
"releasedAt": null,
"createdAt": "2026-11-12T09:30:00.000000Z",
"updatedAt": "2026-11-12T09:30:00.000000Z"
}
}
}
| Alan | Tip | Açıklama |
|---|---|---|
key | string | Zorunlu. Tanımın anahtarı; küçük harfle başlar, a-z, 0-9, _, en fazla 64 karakter. Oluşturduktan sonra değişmez. |
name | string | Zorunlu. Panelde görünen ad. En fazla 255 karakter. |
fields | array | Zorunlu. Alanlar; en az 1, en fazla 20. Her eleman key (anahtar kuralıyla, tanımda tekil), name ve fieldType taşır. fieldType değerleri değer tipleri tablosundakilerdir. Liste sırası alan sırasıdır. |
adminAccess | string | hidden, read (varsayılan) ya da write. Metafield'daki anlamıyla; write ise mağaza kayıtları panelden düzenleyebilir. |
retention | string | delete (varsayılan) ya da keep; Uygulama kaldırılınca bölümündeki gibi. |
storefrontAccess | string | none (varsayılan) ya da read. Vitrin ve tema okuması henüz açık değildir; değer saklanır. |
appPrefix | string | Salt okunur; tanımın sahibi olan uygulama. |
releasedAt | datetime | Salt okunur; uygulama kaldırılıp tanım beklemedeyse kaldırma zamanı, değilse null. |
PATCH ile name, adminAccess, retention, storefrontAccess ve fields güncellenir. fields gönderirseniz liste alanların tam halidir: yeni anahtarlar eklenir, var olanların adı ve sırası güncellenir, listede olmayan alanlar kayıtlardaki değerleriyle birlikte silinir. Var olan alanın fieldType'ı değişmez; değiştirmek için alanı yeni anahtarla ekleyin.
Silinen tanımın bütün kayıtları ve değerleri de silinir. Filtreler: id, key.
fields listesini eksik gönderirseniz listede olmayan alanların değerleri geri alınamaz şekilde silinir. Alan eklerken önce tanımı GET ile okuyun, yeni alanı listenin sonuna ekleyip gönderin.Metaobject kayıtları
| Uç nokta | Metot | Kapsam |
|---|---|---|
/config/metaobjects | GET, POST | — |
/config/metaobjects/{id} | GET, PATCH, DELETE | — |
curl -X POST 'https://<domain>/api/v3/admin/2026-01/config/metaobjects' \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "metaobjects",
"attributes": {
"definitionId": 57,
"name": "Kargo süresi",
"fields": {
"soru": "Siparişim ne zaman kargoya verilir?",
"yanit": "Hafta içi 14.00'e kadar verilen siparişler aynı gün kargoya verilir.",
"sira": 1
}
}
}
}'
201 ile kayıt döner:
{
"data": {
"type": "metaobjects",
"id": "903",
"attributes": {
"definitionId": 57,
"name": "Kargo süresi",
"fields": {
"soru": "Siparişim ne zaman kargoya verilir?",
"yanit": "Hafta içi 14.00'e kadar verilen siparişler aynı gün kargoya verilir.",
"sira": "1"
},
"createdAt": "2026-11-12T09:31:00.000000Z",
"updatedAt": "2026-11-12T09:31:00.000000Z"
}
}
}
| Alan | Tip | Açıklama |
|---|---|---|
definitionId | integer | Zorunlu. Metaobject tanımının kimliği. Oluşturduktan sonra değişmez. |
name | string | Kaydın adı. null olabilir. En fazla 255 karakter. |
fields | object | Alan anahtarı → değer. Değer değer tipleri tablosuna göre doğrulanır ve en fazla 16 KB'tır; değerler metin olarak döner (liste tiplerinde liste). Değeri olmayan alan nesnede yer almaz. |
PATCH ile name ve fields güncellenir. fields kısmidir: yalnız gönderdiğiniz alanlar değişir, değeri null gönderilen alan silinir.
Bir tanımın bütün kayıtları:
curl 'https://<domain>/api/v3/admin/2026-01/config/metaobjects?filter[definitionId]=57' \
-H 'Authorization: Bearer <access_token>' \
-H 'Accept: application/vnd.api+json'
Filtreler: id (virgülle birden çok), definitionId.
| Durum kodu | Sebep |
|---|---|
422 | definitionId sizin bir tanımınız değil; fields içinde tanımda olmayan anahtar; değer tipe uymuyor ya da 16 KB'ı aşıyor |
Mağaza panelinde
Metafield tanımınız adminAccess değerine göre ürün, sipariş ve üye ekranlarında, metaobject tanımınız mağazanın özel nesneleri arasında görünür:
hidden: mağaza görmez; yalnız uygulamanızın iç verisi.read: mağaza görür, değiştiremez. Panelden gelen değişiklik yok sayılır.write: mağaza değeri ve metaobject kayıtlarını düzenleyebilir. Tanımı (ad, tip, alanlar, ayarlar) yine yalnız siz değiştirirsiniz.
Uygulama kaldırılınca
Bu bölüm metafield ve metaobject tanımları için aynıdır. retention: delete tanımlar bütün değerleri ve kayıtlarıyla hemen silinir. Yeniden kurduğunuzda tanımları baştan oluşturursunuz; eski değerler gelmez.
retention: keep tanımlar ve değerleri 90 gün saklanır:
- Bu sürede tanım sizin kalır. Mağaza değerleri panelde görür ama değiştiremez; tanımı silemez. Başka uygulamalar yine göremez.
- Uygulamanız bu sürede aynı mağazaya yeniden kurulursa tanımlar ve değerler olduğu gibi size döner; yeniden oluşturmanız gerekmez, aynı anahtarlarla çalışmaya devam edersiniz.
metafield-definitionsvemetaobject-definitionslistelerinde hazır bulursunuz. - 90 gün içinde kurulmazsa tanımlar mağazaya devredilir: mağazanın kendi tanımı olur, uygulamanız artık göremez ve geri alamaz.
installationtanımları devredilmez; değerleriyle birlikte silinir.
Tanımın kaldırılıp beklemede olduğu, mağazanın kendi istemcisine releasedAt alanında görünür.
Değişiklik olayı
Değer değiştiğinde metafield.updated olayı gelir. Belge, bu uçta GET ile alacağınız metafields kaydıdır; yalnız kendi tanımlarınızın değerleri için gönderilir. Değer aynı kalan yazımlar olay üretmez. installation değerlerini yalnız uygulamanız yazabildiği için bu değerler olay üretmez.
Mağaza metafield'ları
Uygulamalar mağazanın kendi metafield ve metaobject'lerini ve platformun meta verisini okuyamaz. Meta verisi taşıyan şu yollar uygulama token'ına açık değildir:
customer/customer-meta-fields(üye alanı tanımları):403customer/customers?filter[meta]=…:400(read_customersyoksa üye listesinin kendisi403döner)order/orders/-actions/meta-fields:403config/meta-object-entriesvePOST config/object-fields(mağazanın özel nesneleri):403config/objects/{id}(mağazanın özel nesnesi):403. Bu yolun liste ucu yoktur; mağazada olmayan bir kimlik yetki denetiminden önce404döner.cms/contentsvecatalog/combinesyanıtlarındakimetaFieldsalanı yer almaz