Storefront API ile sepet oluşturma ve ürün ekleme
Headless bir sepet kurun: satırlar ve alıcı ülkesiyle cartCreate, yeni ürünler için cartLinesAdd ve alıcıyı ödemeye yönlendirmek için checkoutUrl.
- API
- Storefront API
- İşlemler
- cartCreate, cartLinesAdd
- Erişim yetkisi
- unauthenticated_write_checkouts
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Headless bir mağazada sepeti Storefront API’nin cartCreate mutation’ıyla oluşturun; ilk satırları (merchandiseId varyantın GID’sidir) ve yerel fiyatlar için buyerIdentity.countryCode’u verin. Dönen sepet ID’sini bir cookie’de saklayın ve ürünleri cartLinesAdd ile, istek başına en fazla 250 satır olacak şekilde ekleyin. Ödeme için alıcıyı cart.checkoutUrl’ye yönlendirin; gerisini Shopify checkout halleder.
Nasıl kullanılır
- CreateCart’ı ilk satır ve alıcının ülkesiyle gönderin. cart.id’yi örneğin bir cookie’de saklayın.
- AddToCart’ı sepet ID’si ve yeni satırlarla gönderin. Satır attribute’ları hediye notu gibi bilgileri siparişe taşır.
- Her çağrıdan sonra userErrors ve warnings’i kontrol edin; warnings, değişikliği durdurmayan sorunları bildirir.
- Ödeme butonunu cart.checkoutUrl’ye bağlayın.
Kod
cart-create.graphqlmutation CreateCart($input: CartInput!) {
cartCreate(input: $input) {
cart {
id
checkoutUrl
totalQuantity
cost {
subtotalAmount {
amount
currencyCode
}
}
}
userErrors {
code
field
message
}
warnings {
code
message
target
}
}
}
cart-create.variables.json{
"input": {
"lines": [
{"merchandiseId": "gid://shopify/ProductVariant/1111111111", "quantity": 1}
],
"buyerIdentity": {
"countryCode": "DE"
}
}
}
cart-create.response.json{
"data": {
"cartCreate": {
"cart": {
"id": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"checkoutUrl": "https://your-store.myshopify.com/cart/c/c1-0000000000000000000000000000000?key=0000000000000000",
"totalQuantity": 1,
"cost": {
"subtotalAmount": {
"amount": "49.0",
"currencyCode": "EUR"
}
}
},
"userErrors": [],
"warnings": []
}
}
}
cart-lines-add.graphqlmutation AddToCart($cartId: ID!, $lines: [CartLineInput!]!) {
cartLinesAdd(cartId: $cartId, lines: $lines) {
cart {
id
totalQuantity
lines(first: 20) {
nodes {
id
quantity
merchandise {
... on ProductVariant {
id
title
}
}
}
}
cost {
totalAmount {
amount
currencyCode
}
}
}
userErrors {
code
field
message
}
warnings {
code
message
target
}
}
}
cart-lines-add.variables.json{
"cartId": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"lines": [
{
"merchandiseId": "gid://shopify/ProductVariant/2222222222",
"quantity": 2,
"attributes": [{"key": "Gift note", "value": "Happy birthday!"}]
}
]
}
cart-lines-add.response.json{
"data": {
"cartLinesAdd": {
"cart": {
"id": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"totalQuantity": 3,
"lines": {
"nodes": [
{"id": "gid://shopify/CartLine/00000000-0000-0000-0000-000000000001?cart=c1-0000000000000000000000000000000", "quantity": 1, "merchandise": {"id": "gid://shopify/ProductVariant/1111111111", "title": "M"}},
{"id": "gid://shopify/CartLine/00000000-0000-0000-0000-000000000002?cart=c1-0000000000000000000000000000000", "quantity": 2, "merchandise": {"id": "gid://shopify/ProductVariant/2222222222", "title": "Default Title"}}
]
},
"cost": {
"totalAmount": {
"amount": "119.0",
"currencyCode": "EUR"
}
}
},
"userErrors": [],
"warnings": []
}
}
}
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
- Tarayıcıda public, sunucuda private bir Storefront erişim token’ı kullanın; asla Admin API token’ı kullanmayın.
- Sepetteki buyerIdentity ülke bağlamını belirler; fiyatlar ve stok durumu o pazara göre gelir.
- Adetleri değiştirmek için cartLinesUpdate’i, satır çıkarmak için cartLinesRemove’u kullanın.
- Storefront API’de Money tutarları "49.0" gibi Decimal metinlerdir.
Sık sorulan sorular
- Shopify Storefront API ile sepet nasıl oluşturulur?
- cartCreate’i merchandiseId (varyant ID’si) ve quantity içeren satırlarla çağırın. Yanıtta sepet ID’si ve checkoutUrl bulunur.
- Mevcut bir sepete ürün nasıl eklenir?
- cartLinesAdd’i sepet ID’si ve eklenecek satırlarla, istek başına en fazla 250 satır olacak şekilde çağırın. Yanıt güncel sepeti döndürür.
- Sepette fiyatları alıcının para biriminde nasıl gösteririm?
- Sepeti oluştururken ya da sonradan cartBuyerIdentityUpdate ile buyerIdentity.countryCode’u ayarlayın. Fiyatlar o ülkenin pazarına göre gelir.
Shopify belgeleri
- Gösterilen tarihte, 2026-10 sürümünün Admin veya Storefront API şemasıyla doğrulandı. İstek adresinizdeki sürümü kontrol edin.
- Örneklerdeki ID’ler ve mağaza adresleri yer tutucudur. Kendi değerlerinizle değiştirin.
- Admin API çağrıları uygulamanızdan bir erişim anahtarı (access token) ister. Admin API anahtarını asla vitrine ya da temaya koymayın.
- 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: API entegrasyonları.
