Sayudha

16 Objects Cart, Checkout, Order, dan Customer

Properties2
descriptionObject transaksi, cart dan line_item buat keranjang, customer beserta alamat dan ordernya, order dengan fulfillment dan transaction, diskon, gift card, dan B2B
tagsshopify, liquid, dasar

12 menit baca

Di 14 Objects Produk dan Koleksi dan 15 Objects Konten kita bahas apa yang ditampilin. Sekarang object yang muncul waktu uang beneran mulai jalan: keranjang, pelanggan, dan pesanan.

Urutan alurnya di toko: pengunjung masukin produk ke cart (isinya line_item), lanjut ke checkout, jadi order yang punya transaction dan fulfillment, dan semuanya nempel ke customer. Bab ini ngikutin urutan itu.

Ingat aturan dari 14 Objects Produk dan Koleksi > Soal Harga Subunit: semua harga di sini dalam subunit dan mata uang lokal pelanggan, selalu tampilin lewat filter money.

cart

Keranjang belanja. Global, bisa diakses dari mana aja, karena ikon keranjang di header butuh tau jumlah item di semua halaman.

1. Isi Keranjang

  1. items, array line_item. Ini isinya.
  2. item_count, jumlah total item (jumlah kuantitas, bukan jumlah baris). Dua kaos dan satu topi = 3.
  3. empty?, true kalau kosong. Lebih jelas daripada item_count == 0.
  4. currency, mata uang keranjang, object currency.
  5. requires_shipping, true kalau ada produk yang butuh dikirim.
  6. total_weight, berat total dalam gram.

2. Harga

Urutan dari kotor ke bersih:

  1. original_total_price, total sebelum diskon apapun.
  2. items_subtotal_price, total item setelah diskon per baris, tapi sebelum diskon level keranjang, pajak (kecuali pajak termasuk harga), dan ongkir.
  3. total_discount, total semua diskon (jumlah yang dihemat).
  4. total_price, total setelah semua diskon.
  5. checkout_charge_amount, jumlah yang bakal ditagih saat checkout. Beda sama total_price kalau ada selling plan yang bayarnya belakangan (pre-order, try before you buy).
  6. taxes_included, true kalau pajak udah termasuk di harga.
  7. duties_included, true kalau bea masuk udah termasuk.

Pola ringkasan keranjang:

<p>Subtotal: {{ cart.items_subtotal_price | money }}</p>
{% if cart.total_discount > 0 %}
  <p>Hemat: {{ cart.total_discount | money }}</p>
{% endif %}
<p>Total: {{ cart.total_price | money }}</p>

3. Diskon

  1. discount_applications, array discount_application semua diskon di keranjang.
  2. cart_level_discount_applications, cuma yang level keranjang (bukan per baris).
  3. discounts, deprecated karena gak semua jenis diskon tercakup. Pakai discount_applications.

4. Catatan dan Atribut

Merchant sering butuh info tambahan dari pembeli: “mau dibungkus kado?”, “tulisan ukiran apa?”. Dua mekanismenya:

note, satu teks bebas. Ditangkap pakai input bernama note di dalam form keranjang:

<label>Gift note:</label>
<textarea name="note"></textarea>

Cuma boleh ada satu {{ cart.note }} di halaman keranjang. Kalau ada dua, yang dikirim cuma yang paling bawah di DOM.

attributes, pasangan nama-nilai bebas. Ditangkap pakai input bernama attributes[nama]:

<label>What do you want engraved on your cauldron?</label>
<input type="text" name="attributes[cauldron-engraving]" value="{{ cart.attributes.cauldron-engraving }}" />

Trik: awali nama atribut pakai __ (dua garis bawah) biar jadi privat. Atribut privat gak bisa dibaca dari Liquid atau Ajax API, cocok buat data yang gak ngaruh ke tampilan (misalnya ID pelacakan), dan bikin cache halaman lebih efektif karena Shopify tau data itu gak ngubah render.

Bahasan form keranjang lengkap di 24 Template per Halaman.

line_item

Satu baris di keranjang atau order. Satu baris = satu varian dengan kuantitas tertentu.

1. Identitas

  1. id dan key, ID dan kunci unik baris. key yang dipakai Ajax API buat ngubah baris tertentu.
  2. title, gabungan product.title dan variant.title dipisah tanda hubung, misalnya Health potion - S / Low.
  3. product, object product-nya (bisa juga remote_product).
  4. product_id.
  5. variant, object variant-nya.
  6. variant_id.
  7. sku dan vendor.
  8. image, gambar varian, atau gambar unggulan produk kalau varian gak punya gambar.
  9. url, URL variannya.
  10. url_to_remove, URL buat ngehapus baris ini dari keranjang. Cara paling sederhana bikin tombol hapus tanpa JavaScript.
  11. options_with_values, array option_with_value buat nampilin “Size: S, Strength: Low”.
  12. quantity, jumlah.
  13. gift_card, true kalau produknya gift card.
  14. requires_shipping, taxable, grams (berat dalam satuan default toko).

2. Harga

Ada dua sumbu: per unit vs per baris, dan sebelum vs sesudah diskon:

  1. original_price, harga satu unit sebelum diskon.
  2. final_price, harga satu unit sesudah diskon per baris.
  3. original_line_price, harga seluruh baris (unit × kuantitas) sebelum diskon.
  4. final_line_price, harga seluruh baris sesudah diskon per baris.
  5. line_level_total_discount, total diskon yang kena baris ini.
  6. unit_price dan unit_price_measurement, buat unit pricing.

Yang deprecated: price, line_price, total_discount, dan discounts. Pakai versi original_* / final_*.

❌ deprecated

{{ item.line_price | money }}

✅ benar, dan jelas mana yang sebelum dan sesudah diskon

{% if item.original_line_price != item.final_line_price %}
  <s>{{ item.original_line_price | money }}</s>
{% endif %}
{{ item.final_line_price | money }}

3. Diskon

  1. discount_allocations, array discount_allocation semua diskon yang kena baris ini.
  2. line_level_discount_allocations, cuma yang langsung ke baris ini (bukan bagian dari diskon keranjang).
  3. message, info soal diskon yang mempengaruhi baris ini.

4. Properti Baris (Line Item Properties)

Ini cara ngasih info kustom per item, beda sama cart.attributes yang per keranjang. Contoh: teks ukiran buat item tertentu. Ditangkap di form produk pakai input bernama properties[nama]:

{% form 'product', product %}
  ...
  <label for="engravingText">Engraving</label>
  <input type="text" id="engravingText" name="properties[Engraving]">
  ...
{% endform %}

Di keranjang, dibaca lewat properties yang bisa di-loop:

{% for property in item.properties %}
  {{ property.first }}: {{ property.last }}
{% endfor %}

Sama kaya atribut keranjang, nama properti berawalan _ (satu garis bawah) disembunyiin dari checkout dan email, tapi tetap kebaca di Liquid. Buat data teknis yang gak perlu dilihat pembeli.

5. Selling Plan dan Bundle

  1. selling_plan_allocation, alokasi selling plan baris ini (buat langganan). nil kalau gak ada.
  2. item_components, array line_item komponen kalau baris ini bundle. Cuma di keranjang.
  3. parent_relationship, punya parent yang ngasih baris induk kalau baris ini komponen bundle. Cuma di keranjang.
  4. instructions, aturan buat baris bersarang: can_remove dan can_update_quantity. Komponen bundle biasanya gak boleh dihapus sendiri-sendiri.

6. Di Order

Properti yang cuma bermakna di order.line_items:

  1. fulfillment, object fulfillment baris ini.
  2. fulfillment_service, layanan pemenuhannya, manual kalau gak ada.
  3. successfully_fulfilled_quantity, berapa yang udah dikirim.
  4. tax_lines, array tax_line.

7. Error

error_message, pesan error soal status baris dalam bahasa pembeli, misalnya “Stok cuma tersisa 2”. Cuma tersedia di keranjang buat toko yang pakai Checkout Extensibility.

customer

Pelanggan toko. Global kalau pelanggan lagi login, dan juga tersedia di template customers/account, customers/addresses, customers/order, serta lewat checkout.customer, gift_card.customer, dan order.customer. Di luar itu, kalau gak login, nil.

Ini yang bikin pola “kalau login tampilin nama, kalau nggak tampilin tombol login” jadi gampang:

{% if customer %}
  Halo, {{ customer.first_name }}!
  <a href="{{ routes.account_logout_url }}">Keluar</a>
{% else %}
  <a href="{{ routes.account_login_url }}">Masuk</a>
{% endif %}

1. Identitas

  1. id, email, phone.
  2. first_name, last_name, name (lengkap).
  3. has_account, true kalau emailnya terhubung ke akun. Di checkout, ini bisa true walaupun pelanggan belum login, cukup masukin email yang terdaftar.
  4. has_avatar?, true kalau punya avatar.
  5. accepts_marketing, true kalau setuju nerima marketing.
  6. tags, array tag pelanggan (merchant sering pakai ini buat “VIP”, “wholesale”, dan sebagainya).
  7. tax_exempt, true kalau bebas pajak.
  8. metafields.

2. Alamat

  1. addresses, array address. Bisa di-paginate.
  2. addresses_count.
  3. default_address, alamat utama.

3. Order

  1. orders, array order. Bisa di-paginate.
  2. orders_count, jumlah order.
  3. last_order, order terakhir, gak termasuk order tes.
  4. total_spent, total belanja sepanjang masa dalam subunit.

4. Pembayaran dan Kredit

  1. payment_methods, array customer_payment_method (metode pembayaran tersimpan) dengan payment_instrument_type (misalnya credit_card) dan token.
  2. store_credit_account, object dengan balance (object money) buat saldo kredit toko.

5. B2B

Buat pelanggan bisnis:

  1. b2b?, true kalau pelanggan B2B.
  2. current_company, object company yang lagi dibelanjain.
  3. current_location, object company_location yang lagi dipilih.
  4. company_available_locations, array lokasi perusahaan yang bisa diakses pelanggan.
  5. company_available_locations_count.

Bahasannya di 42 Harga Diskon, Currency, Unit Pricing, Installments, B2B.

Object B2B

1. company

Perusahaan pelanggan B2B: id, name, external_id, metafields, available_locations (array company_location), dan available_locations_count.

2. company_location

Satu lokasi perusahaan:

  1. id, name, external_id, metafields.
  2. company, perusahaan induknya.
  3. current?, true kalau lokasi ini yang lagi dipilih.
  4. url_to_set_as_current, URL buat ngeset lokasi ini jadi aktif. Ini yang dipakai buat pemilih lokasi di header.
  5. shipping_address, object company_address.
  6. tax_registration_id, NPWP-nya.
  7. store_credit_account.

3. company_address

Mirip address biasa, tapi punya attention (baris “u.p.” / perhatian) dan gak punya phone, company, name, summary, url.

order

Satu pesanan yang udah jadi. Tersedia di template customers/order dan lewat customer.orders, customer.last_order, checkout.order.

1. Identitas

  1. id.
  2. name, nama order kaya #1001.
  3. order_number, versi angkanya, 1001.
  4. confirmation_number, kode acak kaya XPAV284CT yang boleh ditampilin ke pelanggan sebagai ganti nomor urut. Nomor urut itu bocorin volume penjualan toko ke pesaing, kode acak nggak.
  5. email, phone.
  6. customer, object customer.
  7. created_at, cancelled_at.
  8. note, attributes, tags, metafields.
  9. order_status_url, URL halaman status order.
  10. customer_url, URL buat pelanggan lihat order di akunnya.
  11. customer_order_url, URL halaman detail order di customer accounts baru.

2. Status

  1. financial_status, status pembayaran: authorized, expired, paid, partially_paid, partially_refunded, pending, refunded, unpaid, voided.
  2. financial_status_label, versi terjemahannya buat ditampilin.
  3. fulfillment_status, status pengiriman: complete, fulfilled, partial, restocked, unfulfilled.
  4. fulfillment_status_label, versi terjemahannya.
  5. cancelled, true kalau dibatalkan.
  6. cancel_reason dan cancel_reason_label.
  7. pickup_in_store?, true kalau order ambil di toko.

Selalu tampilin versi _label, bukan nilai mentahnya, biar otomatis sesuai bahasa pelanggan.

❌ salah, nampilin partially_paid ke pelanggan

{{ order.financial_status }}

✅ benar, udah diterjemahin

{{ order.financial_status_label }}

3. Item dan Alamat

  1. line_items, array line_item.
  2. subtotal_line_items, baris tanpa tip, dipakai buat ngitung subtotal.
  3. item_count.
  4. shipping_address dan billing_address, object address.
  5. shipping_methods, array shipping_method.

4. Harga

  1. line_items_subtotal_price, total baris setelah diskon per baris.
  2. subtotal_price, subtotal setelah diskon baris dan keranjang.
  3. shipping_price, ongkir.
  4. tax_price, total pajak.
  5. total_duties, total bea masuk.
  6. total_discounts, total diskon.
  7. total_price, total order, dihitung sebelum refund.
  8. total_refunded_amount, yang udah dikembalikan.
  9. total_net_amount, total dikurangi refund. Pakai ini kalau mau nampilin “yang benar-benar dibayar”.
  10. tax_lines, array tax_line.
  11. discount_applications dan cart_level_discount_applications. discounts deprecated.
  12. transactions, array transaction.

Object Pendukung Order

1. fulfillment

Satu pengiriman (satu order bisa dikirim beberapa kali):

  1. created_at.
  2. fulfillment_line_items, baris yang ada di pengiriman ini.
  3. item_count.
  4. tracking_company, nama kurir.
  5. tracking_number dan tracking_numbers (kalau lebih dari satu resi).
  6. tracking_url, link lacak.

2. shipping_method

Metode pengiriman:

  1. id, title, handle (handle-nya ditambahin harganya di belakang).
  2. original_price, ongkir sebelum diskon.
  3. price_with_discounts, ongkir setelah diskon termasuk diskon level order. price deprecated karena gak termasuk diskon order.
  4. discount_allocations dan tax_lines.

3. tax_line

Satu baris pajak: title, price (jumlah pajak), rate (desimal, misalnya 0.11), dan rate_percentage (11).

4. transaction

Satu transaksi pembayaran:

  1. id, name, amount, created_at.
  2. kind, jenisnya (authorization, capture, sale, void, refund).
  3. status dan status_label (terjemahannya).
  4. gateway, nama provider dalam bentuk handle.
  5. gateway_display_name, nama provider buat ditampilin.
  6. receipt, info struk dari provider.
  7. payment_details, object transaction_payment_details dengan credit_card_company, credit_card_last_four_digits, credit_card_number (udah disamarkan), dan gift_card.
  8. show_buyer_pending_payment_instructions?, true kalau transaksinya tertunda dan pembeli harus nyelesaiin pembayaran di luar (transfer bank, gerai).
  9. buyer_pending_payment_notice, pesan instruksinya.
  10. buyer_pending_payment_instructions, array pending_payment_instruction_input berisi pasangan header dan value (misalnya “Entity” dan “Reference” buat Multibanco).

Pola nampilin instruksi bayar:

{% for transaction in order.transactions %}
  {% if transaction.show_buyer_pending_payment_instructions? %}
    <p>{{ transaction.buyer_pending_payment_notice }}</p>
    {% for instruction in transaction.buyer_pending_payment_instructions %}
      <p>{{ instruction.header }}: {{ instruction.value }}</p>
    {% endfor %}
  {% endif %}
{% endfor %}

Object Diskon

Ada tiga object diskon, dan yang penting dipahami: discount_application itu diskonnya, discount_allocation itu penerapannya ke item tertentu. Satu diskon “10% semua produk” (application) bisa nempel ke lima baris berbeda (lima allocation).

1. discount_application

  1. title, nama diskon yang dilihat pelanggan (kode kupon atau nama diskon otomatis).
  2. type, asalnya: automatic, discount_code, manual, atau script.
  3. value dan value_type, nilai dan jenisnya (persen atau nominal).
  4. target_type, kena ke apa: baris item atau ongkir.
  5. target_selection, cara milih targetnya (semua, eksplisit, atau berhak).
  6. total_allocated_amount, total nominal diskon ini.

Pola nampilin diskon di keranjang:

{% for discount_application in cart.cart_level_discount_applications %}
  <p>{{ discount_application.title }}: -{{ discount_application.total_allocated_amount | money }}</p>
{% endfor %}

2. discount_allocation

  1. amount, nominal potongan di item ini.
  2. discount_application, diskon yang menyebabkannya.

3. discount (Deprecated)

Object lama dengan title / code (sama), amount / total_amount (sama), savings / total_savings (nilai negatif), dan type. Deprecated karena gak nyakup semua jenis diskon. Pakai discount_application.

Bahasan cara nampilin diskon lengkap di 42 Harga Diskon, Currency, Unit Pricing, Installments, B2B.

gift_card

Gift card. Tersedia di template gift_card.liquid dan lewat transaction_payment_details.gift_card:

  1. code, kode penukaran. Hati-hati nampilin ini, cuma di halaman gift card milik pembelinya.
  2. last_four_characters, 4 karakter terakhir kode, aman ditampilin.
  3. balance, sisa saldo.
  4. initial_value, nilai awal.
  5. currency, kode ISO mata uang.
  6. enabled, expired, expires_on.
  7. customer, product, variant, properties.
  8. recipient, object dengan name, email, nickname kalau gift card dikirim ke orang lain.
  9. message, pesan personal buat penerima.
  10. send_on, tanggal terjadwal pengiriman.
  11. url, URL buat lihat gift card (di domain checkout.shopify.com).
  12. pass_url, URL download sebagai Apple Wallet Pass.
  13. qr_identifier, string buat bikin QR code.
  14. template_suffix.

Bahasannya di 24 Template per Halaman dan 41 Produk Recommendations, Gift Card, dan Bundles.

checkout

Object checkout itu warisan dari checkout.liquid yang udah dihentikan. Sejak 13 Agustus 2024, halaman Information, Shipping, dan Payment gak bisa lagi dikustomisasi lewat Liquid, harus pakai Checkout Extensibility. Object ini masih ada buat halaman Thank you dan Order status di toko yang belum migrasi.

Propertinya mirip gabungan cart dan order: line_items, total_price, shipping_address, billing_address, shipping_method, tax_lines, transactions, discount_applications, applied_gift_cards, gift_cards_amount, buyer_accepts_marketing, customer, order, order_id, order_name, order_number, dan sebagainya. Banyak propertinya udah deprecated.

Catatan: order gak tersedia di halaman Thank you (karena ordernya baru dibikin), makanya di sana pakai checkout.order_name.

Detail checkout.liquid ada di 34 checkout.liquid (deprecated). Buat theme baru, kamu gak bakal nyentuh object ini.

Ringkasan

  1. cart global, punya items (array line_item), item_count (jumlah kuantitas), dan empty?.
  2. Harga keranjang berurutan: original_total_price → items_subtotal_price → total_price, dengan total_discount sebagai selisihnya, dan checkout_charge_amount buat yang bayarnya sebagian.
  3. cart.note cuma boleh satu di halaman, dan atribut berawalan __ jadi privat dan gak kebaca Liquid.
  4. line_item punya empat harga: original_price / final_price (per unit) dan original_line_price / final_line_price (per baris). price, line_price, total_discount deprecated.
  5. Properti baris ditangkap pakai properties[nama] di form produk, dan nama berawalan _ disembunyiin dari checkout.
  6. url_to_remove bikin tombol hapus tanpa JavaScript.
  7. customer global cuma kalau login, kalau nggak nil. has_account bisa true tanpa login di checkout.
  8. customer.orders dan addresses bisa di-paginate, last_order gak termasuk order tes.
  9. B2B: customer.b2b?, current_company, current_location, dan company_location.url_to_set_as_current buat ganti lokasi.
  10. order.confirmation_number boleh ditampilin sebagai ganti nomor urut biar volume penjualan gak bocor.
  11. Selalu tampilin financial_status_label dan fulfillment_status_label, bukan nilai mentahnya.
  12. total_price dihitung sebelum refund, total_net_amount sesudahnya.
  13. discount_application itu diskonnya, discount_allocation itu penerapannya ke item. Object discount deprecated.
  14. transaction.show_buyer_pending_payment_instructions? buat nampilin instruksi bayar offline.
  15. gift_card.code sensitif, tampilin last_four_characters kecuali di halaman gift card pemiliknya.
  16. checkout itu warisan checkout.liquid yang udah dihentikan, jangan dipakai di theme baru.

Bab selanjutnya kita tutup bahasan object dengan sisanya: section, block, dan app buat arsitektur theme, form dan form_errors buat form, paginate, filter buat storefront filtering, search dan predictive_search, plus object-object robots.txt.

Tampilan Grafik

Tautan Balik