كائن السلة

شكل كائن واحد يسري عبر SDK بأكمله. فهو ما يعيده getCart()، وما يمرره cart_loaded وcart_updated إلى معالجك، وما يستقبله بلوك Custom code.

كل المبالغ بالوحدة الصغرى للعملة (السنتات للدولار الأمريكي)، وليست أبدًا سلسلة منسّقة. 5779 تعني $57.79. استخدم formatMoney لعرضها.

السلة

الحقل	النوع	الوصف
`token`	`string`	رمز سلة Shopify.
`items`	`AftersellCartLine[]`	بنود السلة. انظر بنود السلة.
`itemCount`	`number`	إجمالي كمية العناصر، كما يراها المتسوق.
`hasSubscriptionItems`	`boolean`	تكون `true` عندما يحمل بند واحد على الأقل في `items` خطة بيع، بما في ذلك بنود الإضافات التي يستبعدها `itemCount`. وتكون `false` في السلة الفارغة.
`totalPrice`	`number`	الإجمالي الحالي، بالسنتات.
`originalTotalPrice`	`number`	الإجمالي قبل الخصومات، بالسنتات.
`totalDiscount`	`number`	إجمالي الخصم، بالسنتات.
`compareAtTotalPrice`	`number \| null`	مجموع سعر المقارنة (MSRP) لكل بند × الكمية، بالسنتات. تكون `null` عند عدم توفرها، فارجع حينها إلى `originalTotalPrice`.
`currency`	`string`	رمز العملة.
`discountCodes`	`string[]`	أكواد الخصم المقبولة على السلة، مرتَّبة. تكون `[]` عند عدم وجودها.
`attributes`	`Record<string, string>`	سمات السلة. للقراءة فقط من SDK.

itemCount ليس دائمًا مجموع items. يعكس items سلة Shopify الحقيقية، بما في ذلك بنود الإضافات التي يخفيها الدرج، مثل حماية الشحن. أما itemCount فهو الرقم الموجَّه للمتسوق الذي يطابق شارة السلة. لمعرفة “كم عنصرًا اختار المتسوق”، استخدم itemCount؛ وللمرور على البنود التي تعرضها السلة، استخدم items.هناك أمران غائبان تمامًا عن items: البنود المخفية عبر setHidden، وأبناء الحزم الذين ينتقلون إلى بندهم الرئيسي. كلاهما يظل محسوبًا في إجماليات السلة، التي تأتي مباشرةً من Shopify.

window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log(state.itemCount, 'items');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
  console.log('Saved:', window.aftersell.cart.actions.formatMoney(state.totalDiscount));
  console.log('Codes:', state.discountCodes.join(', ') || 'none');
});

بنود السلة

كل عنصر في items، وكذلك item في item_added وitem_removed:

الحقل	النوع	الوصف
`key`	`string`	مفتاح البند في Shopify. مرره إلى إجراءات البنود.
`productId`	`number`	معرّف المنتج في Shopify.
`variantId`	`number`	معرّف المتغير في Shopify.
`handle`	`string`	معرّف المنتج النصي (handle).
`title`	`string`	عنوان العرض.
`productTitle`	`string`	عنوان المنتج بدون المتغير.
`variantTitle`	`string \| null`	تسمية المتغير، أو `null`.
`variantOptions`	`Array<{ name, value }>`	الخيارات المحددة، مثل `[{ name: 'Size', value: 'Medium' }]`. يُصدر Shopify القيمة `Title: Default Title` للمنتج ذي المتغير الواحد.
`quantity`	`number`	كمية هذا البند.
`linePrice`	`number`	سعر البند، بالسنتات.
`finalLinePrice`	`number`	سعر البند بعد الخصومات، بالسنتات.
`originalLinePrice`	`number`	سعر البند قبل الخصومات، بالسنتات.
`compareAtPrice`	`number \| null`	سعر المقارنة (MSRP) للمتغير لكل وحدة، بالسنتات. يكون `null` عند عدم وجوده.
`properties`	`Record<string, string> \| null`	خصائص بند السلة.
`internalProperties`	`Record<string, string>`	طبقة عرض فقط من `registerLineTransform`. لا تُحفظ أبدًا في Shopify. تكون `{}` عند عدم وجودها.
`discountAllocations`	`Array<{ title, amount }>`	الخصومات المطبَّقة على هذا البند. تكون `amount` بالسنتات. وتكون `[]` عند عدم وجودها.
`isGiftCard`	`boolean`	ما إذا كان البند بطاقة هدية.
`sellingPlan`	`{ id, name } \| null`	خطة الاشتراك النشطة، أو `null` للشراء لمرة واحدة.
`bundle`	`AftersellCartBundle \| null`	نموذج عرض الحزمة على البند الرئيسي؛ ويكون `null` على البنود غير المرتبطة بحزمة وعلى الأبناء.
`metadata`	`Record<string, unknown>`	بيانات الإثراء مفهرسة بمعرّف المُثري `id`. تكون `{}` حتى يملأها مُثرٍ.

يمكن أن تحمل properties مدخلات من المتسوق، مثل حقل نص مخصص في نموذج المنتج. اعرضها كنص، وليس أبدًا كـ HTML خام.

تحديد بند

استخدم key لأي شيء يتصرف على بند، وvariantId أو productId لأي شيء يحدد منتجًا:

// ✅ Acting on a line: use key.
window.aftersell.cart.actions.removeItem(line.key);

// ✅ Recognising a product: use variantId.
const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);

يمكن أن يظهر المتغير نفسه في عدة بنود عندما تختلف الخصائص. كوبان منقوشان بنصين مختلفين هما بندان يتشاركان variantId واحدًا. لهذا تأخذ الإجراءات key.

أسعار البند

ثلاثة أسعار يسهل الخلط بينها:

ما تريده	ما تستخدمه
ما يدفعه المتسوق مقابل هذا البند	`finalLinePrice`
ما كان يكلفه قبل خصومات السلة	`originalLinePrice`
السعر المشطوب (MSRP)، لكل وحدة	`compareAtPrice` × `quantity`

// Is this line discounted?
const isDiscounted = line.finalLinePrice < line.originalLinePrice;

// Is it free? (A common way to detect a gift line.)
const isFree = line.finalLinePrice === 0;

الحزم

عندما تُجمَّع البنود في حزمة، يحمل البند الرئيسي كائن bundle. تُطوى البنود الأبناء داخله ولا تظهر في items بمفردها بعد ذلك. راجع جمع بنود حزمة من تطبيق آخر لمعرفة كيفية إعداد التجميع.

الحقل	النوع	الوصف
`id`	`string`	معرّف الحزمة.
`source`	`'native' \| 'grouped'`	حزمة Shopify أصلية، أو بنود جمّعها Aftersell.
`memberKeys`	`string[]`	مفتاح `key` لكل بند في الحزمة.
`children`	`AftersellBundleChild[]`	محتويات الحزمة.
`displayPrice`	`number`	السعر المعروض للحزمة، بالسنتات.

يحمل كل ابن key (يكون null للمكوّن الأصلي)، وtitle، وvariantTitle، وquantity، وperAnchorQty، وimageUrl، وfinalLinePrice، وoriginalLinePrice، وcompareAtPrice.

// Skip bundle children when totalling your own line list.
const topLevel = state.items.filter((line) => !isBundleChild(line, state));

خطط الاشتراك

الخطة النشطة للبند هي sellingPlan، أو null للشراء لمرة واحدة. للحصول على إجابة على مستوى السلة كلها، اقرأ hasSubscriptionItems بدلًا من فحص البنود بنفسك، لأنه يحسب أيضًا بنود الإضافات التي يعرضها items لكن يتخطاها itemCount:

if (state.hasSubscriptionItems) {
  // The cart contains at least one subscription line.
}

const subscriptions = state.items.filter((line) => line.sellingPlan);
console.log(subscriptions.length, 'subscription lines');

الخطط المتاحة على البند، أي الموجودة في المنتقي، ليست على كائن السلة. شكّلها باستخدام registerSubscriptionOptionsTransform وregisterDefaultSubscriptionOptionSelector.

إلى أين تذهب بعد ذلك

الإجراءات: اقرأ السلة وغيّرها.
الأحداث: من أين يأتي هذا الكائن.
الخطافات: أضِف بياناتك الخاصة إلى بند عبر مُثرٍ.
حالات الاستخدام: حلول كاملة تقرأ هذه الحقول.

البدء

الصفحة الرئيسية

أفضل الممارسات

عروض البيع الإضافي بعد الشراء

عربة التسوق

عروض البيع الإضافي في صفحة الدفع (Shopify Plus)

صفحة الشكر

عروض البيع الإضافي في صفحة المنتج

Rokt Thanks

الاستراتيجيات

التحليلات والتتبع

التكاملات

Aftersell MCP

الفوترة والحساب

استكشاف الأخطاء وإصلاحها

السلة

بنود السلة

تحديد بند

أسعار البند

الحزم

خطط الاشتراك

إلى أين تذهب بعد ذلك

​السلة

​بنود السلة

​تحديد بند

​أسعار البند

​الحزم

​خطط الاشتراك

​إلى أين تذهب بعد ذلك

السلة

بنود السلة

تحديد بند

أسعار البند

الحزم

خطط الاشتراك

إلى أين تذهب بعد ذلك