Tham chiếu API Đoạn mã Shopify

Các tập lệnh được viết bằng một API của Ruby, mang đến cho bạn khả năng kiểm soát và tính linh hoạt tuyệt vời.

Shopify Plus

Đoạn mã Shopify và ứng Script Editor chỉ khả dụng cho thương nhân Shopify Plus. Ứng dụng Script Editor không còn khả dụng để tải xuống từ Shopify App Store.

Vào ngày 28 tháng 8 năm 2025, Đoạn mã Shopify sẽ bị xóa và không còn hoạt động. Hãy di chuyển Đoạn mã hiện có của bạn sang Shopify Functions trước ngày này.

Có nhiều loại tập lệnh khác nhau. Tập lệnh được chỉ định loại khi bạn tạo tập lệnh trong ứng dụng Script Editor, dựa trên mẫu tập lệnh mà bạn chọn để bắt đầu:

Tập lệnh mục hàng

Tập lệnh mục hàng ảnh hưởng đến mục hàng trong giỏ hàng, có thể thay đổi giá cũng cấp ưu đãi giảm giá. Những tập lệnh này chạy khi giỏ hàng có thay đổi.

Tập lệnh mục hàng giảm giá gói đăng ký chỉ áp dụng cho lần thanh toán gói đăng ký đầu tiên. Các lần thanh toán sau sẽ không được giảm giá bằng tập lệnh.

Một số phương thức chỉ có thể áp dụng trong tập lệnh mục hàng.

Tập lệnh vận chuyển

Các tập lệnh vận chuyển tương tác với vận chuyển và có thể thay đổi phương thức vận chuyển cấp ưu đãi giảm giá phí vận chuyển. Các tập lệnh này sẽ chạy khi quá trình thanh toán đến trang tùy chọn vận chuyển.

Đoạn mã vận chuyển giảm phí vận chuyển của gói đăng ký chỉ áp dụng cho kỳ thanh toán đầu tiên của gói và không áp dụng cho các kỳ thanh toán sau đó.

Một số phương thức chỉ có thể sử dụng trong tập lệnh vận chuyển.

Tập lệnh thanh toán

Tập lệnh thanh toán tương tác với các khoản thanh toántoán và có thể đổi tên, ẩn cũng như sắp xếp lại thứ tự cổng thanh toán. Lưu ý rằng tập lệnh thanh toán không tương tác với cổng thanh toán nào hiển thị trước màn hình thanh toán, ví dụ như Apple Pay. Các tập lệnh này sẽ chạy khi thanh toán đến trang thanh toán.

Một số phương thức chỉ dùng được trong tập lệnh thanh toán.

Phương thức chung

Các phương thức sau đây có thể sử dụng trong mọi loại tập lệnh:

Nhập vào

Phương thức nhập tập lệnh

Phương thức	Loại trả lại	Mô tả
.cart	Giỏ hàng	Trả về một đối tượng giỏ hàng có thể thay đổi.
.locale	chuỗi	Trả về vùng miền của khách hàng. Ví dụ, en , fr , hoặc pt-BR.

Giỏ hàng

Đối tượng giỏ hàng chỉ có trên cửa hàng trực tuyến. Một số giao dịch thanh toán bỏ dở có quyền truy cập vào đối tượng giỏ hàng. Tuy nhiên, nếu thanh toán đã đóng lại và sau đó một khách hàng truy cập vào giao dịch thanh toán bỏ dở đó, họ sẽ được đưa đến thanh toán đã điền trước và đối tượng giỏ hàng đó không còn tồn tại. Nguyên nhân là email về giao dịch thanh toán bỏ dở đã bỏ qua cửa hàng.

Phương thức tập lệnh sử dụng đối tượng Cart

Phương thức	Loại trả lại	Mô tả
.customer	Khách hàng	Trả về chủ sở hữu giỏ hàng (nếu có).
.shipping_address	ShippingAddress	Trả lại địa chỉ giao hàng của chủ sở hữu giỏ hàng (nếu có).
.discount_code	không cố định	Trả về: nil nếu giỏ hàng không có mã giảm giá CartDiscount::FixedAmount nếu giỏ hàng có số tiền giảm giá cố định CartDiscount::Percentage nếu giỏ hàng có ưu đãi giảm giá theo tỷ lệ phần trăm CartDiscount::Shipping nếu giỏ hàng có ưu đãi giảm giá cho vận chuyển Trả về một mã giảm giá duy nhất (xem Hạn chế) discount_codesẽ xuất hiện nếu áp dụng ưu đãi giảm giá cho giỏ hàng. Điều đó không nhất thiết có nghĩa là giá của giỏ hàng thay đổi. Ví dụ: Nếu áp dụng ưu đãi giảm giá cho giỏ hàng trên 50 USD và tập lệnh giảm giá cho giỏ hàng dưới 50 USD, discount_code vẫn sẽ hiện diện nhưng giá của giỏ hàng không thay đổi. Xem ví dụ về discount_code.
.line_items	Danh sách<LineItem>	Trả về danh sách có các mục hàng trong giỏ hàng.
.presentment_currency	Danh sách<String>	Trả về đơn vị tiền tệ địa phương (hiển thị) của khách hàng (ở định dạng ISO 4217). Ví dụ: USD.
.subtotal_price	Tiền	Trả về giá tổng phụ của giỏ hàng sau khi áp dụng ưu đãi giảm giá theo mục hàng nhưng trước khi áp dụng mã giảm giá.
.total_weight	gam	Trả về tổng trọng lượng của tất cả các mục hàng trong giỏ hàng.

CartDiscount::FixedAmount

Phương thức tập lệnh sử dụng đối tượng CartDiscount::FixedAmount

Phương thức	Loại trả lại	Mô tả
.mã	Chuỗi	Trả về mã giảm giá dùng để áp dụng ưu đãi giảm giá.
.amount	Tiền	Trả về số tiền giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có một thông báo.
.rejected?	Boolean	Trả lại xem mã giảm giá có bị từ chối hay không.

CartDiscount::Percentage

Phương thức tập lệnh sử dụng đối tượng CartDiscount::Percentage

Phương thức	Loại trả lại	Mô tả
.mã	Chuỗi	Trả về mã giảm giá dùng để áp dụng ưu đãi giảm giá.
.percentage	Dấu thập phân	Trả về số tỷ lệ phần trăm của ưu đãi giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có một thông báo.
.rejected?	Boolean	Trả lại xem mã giảm giá có bị từ chối hay không.

CartDiscount::Shipping

Phương thức tập lệnh sử dụng đối tượng CartDiscount::Shipping

Phương thức	Loại trả lại	Mô tả
.mã	Chuỗi	Trả về mã giảm giá dùng để áp dụng ưu đãi giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có một thông báo.
.rejected?	Boolean	Trả lại xem mã giảm giá có bị từ chối hay không.

Khách hàng

Phương thức tập lệnh dùng đối tượng Customer

Phương thức	Loại trả lại	Mô tả
.id	Số nguyên	Trả về số ID của khách hàng.
.email	Chuỗi	Trả về địa chỉ email của khách hàng.
.tags	Danh sách<Thẻ>	Trả về danh sách các chuỗi thể hiện các thẻ đã đặt cho khách hàng.
.orders_count	Số nguyên	Trả về tổng số đơn hàng mà khách hàng đã đặt.
.total_spent	Tiền	Trả về tổng số tiền mà khách hàng đã chi tiêu cho tất cả đơn hàng.
.accepts_marketing?	Boolean	Trả lại xem khách hàng có chấp nhận tiếp thị hay không.

LineItem

<tdgrams

Phương thức tập lệnh dùng đối tượng LineItem

Phương thức	Loại trả lại	Mô tả
.grams	Trả về tổng trọng lượng mục hàng.
.line_price	Tiền	Giá mục hàng.
.discounted?	Boolean	Trả về xem giá của mục hàng đã được chiết khấu qua đoạn mã hay ưu đãi giảm giá áp dụng thủ công chưa. Việc sử dụng mã giảm giá không ảnh hưởng đến giá trị trả về.
.properties	hash	Trả về thuộc tính được chỉ định cho mục hàng này.
.variant	Mẫu mã	Trả về mẫu mã sản phẩm cụ thể mà mục hàng thể hiện.
.quantity	Số nguyên	Trả về số lượng mục hàng này.
.selling_plan_id	Số nguyên	Trả về ID của gói bán hàng cho mục hàng. Phương thức này hữu ích khi cửa hàng bán gói đăng ký và bạn muốn đoạn mã phát hiện thời điểm mẫu mã sản phẩm được bán dưới dạng gói đăng ký.

Danh sách

Phương thức tập lệnh dùng đối tượng List

Phương thức	Loại trả lại	Mô tả
.new	Danh sách	Tạo một đối tượng mới đại diện cho danh sách.
.[]	Phần tử hoặc nil	Trả về phần tử tại chỉ mục được chỉ định.
.&	Danh sách	Trả về danh sách mới chứa các phần tử chung cho hai danh sách, không trùng lặp.
.delete_if	Danh sách	Xóa phần tử sử dụng khối mã tùy chọn. Xem tài liệu về phương thức delete_if của Ruby.
.empty?	Boolean	Trả về true nếu danh sách không có phần tử nào.
.first	Phần tử hoặc nil	Trả về phần tử đầu tiên hoặc nil nếu danh sách trống.
.index(*args, &block)	int hoặc nil	Trả về chỉ số của phần tử đầu tiên trong danh sách. Nếu có khối lệnh thay vì đối số, trả về chỉ số của phần tử đầu tiên đúng với khối lệnh.
.rindex(*args, &block)	int hoặc nil	Trả về chỉ số của phần tử cuối cùng trong danh sách. Nếu tìm thấy khối lệnh thay vì đối số, trả về chỉ số của phần tử đầu tiên đúng với khối lệnh.
.last	Phần tử hoặc nil	Trả về phần tử cuối cùng hoặc nil nếu danh sách trống.
.length	int	Trả về số lượng các phần tử trong danh sách.
.size	int	Bí danh cho length.
.each(*args, &block)	Danh sách	Gọi khối một lần cho từng phần tử trong danh sách, chuyển phần tử này làm tham số cho khối.

ShippingAddress

Phương thức tập lệnh sử dụng đối tượng ShippingAddress

Phương thức	Loại trả lại	Mô tả
.name	string	Trả lại tên của người gắn liền với địa chỉ giao hàng.
.address1	string	Trả về phần địa chỉ đường phố trong địa chỉ giao hàng.
.address2	string	Trả về trường bổ sung tùy chọn của phần địa chỉ đường phố trong địa chỉ giao hàng.
.phone	string	Trả về số điện thoại theo địa chỉ giao hàng.
.city	string	Trả về thành phố theo địa chỉ giao hàng.
.zip	string	Trả về mã ZIP theo địa chỉ gửi hàng.
.province	string	Trả về tỉnh/tiểu bang theo địa chỉ gửi hàng.
.province_code	string	Trả về giá trị viết tắt của tỉnh/tiểu bang theo địa chỉ gửi hàng.
. country_code	string	Trả về giá trị viết tắt của quốc gia trong địa chỉ vận chuyển.

Tiền

Phương thức tập lệnh dùng đối tượng Money

Phương thức	Loại trả lại	Mô tả
.derived_from_presentment (customer_cents:X)	Tiền	Chuyển đổi một số tiền (bằng đơn vị tiền tệ nhỏ nhất) từ đơn vị tiền tệ địa phương (hiển thị) của khách hàng thành đơn vị tiền tệ của cửa hàng. Phương thức này chấp nhận tham số customer_cents, là tham số chấp nhận một con số bằng cent. Ví dụ, Money.derived_from_presentment(customer_cents: 500) .
.new	Tiền	Tạo đối tượng mới để thể hiện giá.
.zero	Tiền	Tạo một đối tượng mới có giá là 0.
+	Tiền	Thêm hai đối tượng Money.
-	Tiền	Trừ một đối tượng Money khỏi một đối tượng khác.
*	Tiền	Nhân một đối tượng Money với một con số.

Ví dụ về tiền

Money.new(cents: 1000)

Tạo một đối tượng Money thể hiện 1000 cent hoặc 10 USD.

Money.new(cents: 100) * 50

Tạo một đối tượng Money thể hiện 1 USD, sau đó nhân số tiền đó với 50. Trả về một đối tượng Money thể hiện 50 USD.

Mẫu mã

Phương thức tập lệnh dùng đối tượng Variant

Phương thức	Loại trả lại	Mô tả
.id	Số nguyên	Trả về số ID của mẫu mã.
.price	Tiền	Trả về đơn giá của mẫu mã.
.product	Sản phẩm	Trả về sản phẩm tương ứng của mẫu mã.
.sku	Danh sách<String>	Trả về đơn vị lưu kho (SKU) của mẫu mã, thường được dùng để theo dõi hàng trong kho.
.title	Chuỗi	Trả về tiêu đề của mẫu mã.

Sản phẩm

Phương thức tập lệnh dùng đối tượng Product

Phương thức	Loại trả lại	Mô tả
.id	Số nguyên	Trả về số ID của sản phẩm.
.gift_card?	Boolean	Trả lại xem sản phẩm có phải thẻ quà tặng hay không.
.tags	Danh sách<Thẻ>	Trả về danh sách chuỗi thể hiện các thẻ được đặt cho sản phẩm này.
.product_type	Chuỗi	Việc phân loại giúp gắn thẻ sản phẩm, thường được dùng cho lọc và tìm kiếm.
.vendor	Chuỗi	Trả về nhà cung cấp sản phẩm này.

Kernel

Kernel là một môđun Ruby có trong mọi loại. Do đó, phương thức của nó có thể dùng cho mọi đối tượng. Những phương thức này hoạt động theo cách giống như các chức năng toàn cầu hoạt động trong các ngôn ngữ khác.

Phương thức tập lệnh dùng đối tượng Kernel

Phương thức	Loại trả lại	Mô tả
.exit	không	Chấm dứt việc thực hiện tập lệnh hiện tại mà không có lỗi nào. Nếu khởi chạy trước khi có bất kỳ chỉ định nào cho Output.cart, tập lệnh sẽ không có hiệu lực. Đây là cách hữu hiệu để thoát tập lệnh, ví dụ, nếu khách hàng không đủ điều kiện chạy tập lệnh.

Ví dụ về Kernel

customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

Phương thức mục hàng

Các phương thức sau đây chỉ có thể dùng trong tập lệnh mục hàng:

Giỏ hàng

Phương thức tập lệnh sử dụng đối tượng Cart trong tập lệnh mục hàng

Phương thức	Loại trả lại	Mô tả
.subtotal_price_was	Tiền	Trả về giá tổng phụ của giỏ hàng trước khi áp dụng bất kỳ ưu đãi giảm giá nào.
.subtotal_price_changed?	Boolean	Trả về để xem giá tổng phụ có thay đổi hay không.

LineItem

Phương thức tập lệnh dùng đối tượng LineItem trong tập lệnh mục hàng

Phương thức	Loại trả lại	Mô tả
.change_line_price (tiền new_price, {message: string })	Tiền	Thay đổi giá của mục hàng thành số tiền được chỉ định. Bắt buộc phải có message. new_price phải thấp hơn giá hiện tại.
.original_line_price	Tiền	Trả về giá gốc của mục hàng trước khi áp dụng tập lệnh và ưu đãi giảm giá.
.line_price_was	Tiền	Trả về giá của mục hàng trước khi áp dụng thay đổi do tập lệnh hiện tại.
.line_price_changed?	Boolean	Trả lại xem giá của mặt hàng có thay đổi hay không.
.change_properties (hash new_properties, { message: String })	hash	Đặt các thuộc tính mới cho mục hàng. Hàm băm thuộc tính ban đầu được giữ trong properties_was và hàm băm thuộc tính được chuyển cho phương thức sẽ trở thành hàm băm thuộc tính mới của mục hàng.
.properties_was	hash	Trả về hàm băm thuộc tính ban đầu của mục hàng trước khi áp dụng bất kỳ thay đổi nào.
.properties_changed?	Boolean	Trả lại xem thuộc tính của mục hàng có bị thay đổi hay không.
.split ({take: Integer })	LineItem	Tách một mục hàng thành hai mục hàng. takechỉ định số lượng sẽ lấy đi trong mục hàng ban đầu để tạo mục hàng mới.

Ví dụ về .split

Tập lệnh ví dụ này chia tách một mục hàng có tên original_line_item thành hai mục hàng. Mục hàng mới có số lượng là 1 (do take: 1 chỉ định). Sau đó, tập lệnh áp dụng giá đã chiết khấu cho mục hàng mới với thông báo "Mũ thứ ba có giá 5 đô la".

if original_line_item.quantity >= 3
  new_line_item = original_line_item.split(take: 1)
  new_line_item.change_line_price(Money.new(cents: 500), message: "Third hat for 5 dollars")
  cart.line_items << new_line_item
end

Mẫu mã

Phương thức tập lệnh dùng đối tượng Variant trong tập lệnh mục hàng

Phương thức	Loại trả lại	Mô tả
.compare_at_price	Tiền	Trả về giá gốc của mẫu mã. Trả về nil nếu mẫu mã không có giá gốc.

Phương thức vận chuyển

Các phương thức sau đây có thể dùng trong tập lệnh vận chuyển:

Nhập vào

Phương thức tập lệnh dùng đối tượng Input trong tập lệnh vận chuyển

Phương thức	Loại trả lại	Mô tả
.shipping_rates	ShippingRateList	Trả về danh sách có toàn bộ phí vận chuyển.

ShippingRateList

Phương thức tập lệnh sử dụng đối tượng ShippingRateList trong tập lệnh vận chuyển

Phương thức	Loại trả lại	Mô tả
.delete_if	ShippingRateList	Xóa phí vận chuyển bằng khối mã tùy chọn. Xem tài liệu về phương thức delete_if của Ruby.
.sort!	ShippingRateList	Sắp xếp phí vận chuyển bằng toán tử so sánh hoặc khối mã tùy chọn. Xem tài liệu về phương thức sort! của Ruby.
.sort_by!	ShippingRateList	Sắp xếp phí vận chuyển bằng khối mã tùy chọn. Xem tài liệu về phương thức sort_by! của Ruby.

ShippingRate

Phương thức tập lệnh dùng đối tượng ShippingRate trong tập lệnh vận chuyển

Phương thức	Loại trả lại	Mô tả
.mã	Chuỗi	Trả về mã phí vận chuyển.
.markup	Tiền	Trả về mức tăng giá đối với phí vận chuyển, nếu có.
.name	Chuỗi	Trả về tên phí vận chuyển. Có thể sửa đổi bằng phương thức change_name.
.price	Tiền	Trả về mức phí vận chuyển.
.source	Chuỗi	Trả về nguồn (hãng vận chuyển) gắn với mức phí vận chuyển này, nếu có. Không thể sửa đổi.
.change_name (Chuỗi new_name)	Chuỗi	Thay đổi tên (tối đa 255 ký tự) của mức phí vận chuyển. Không thể thay đổi, xóa hoặc ẩn nguồn.
.apply_discount (ưu đãi giảm giá Money, {message: String})	Tiền	Áp dụng ưu đãi giảm giá với số tiền cố định đã chỉ định. Không thể giảm giá xuống dưới 0. Bắt buộc phải có thông báo.
.phone_required?	Boolean	Trả về true nếu bắt buộc có số điện thoại để được hưởng phí vận chuyển này, hoặc false nếu không bắt buộc có số điện thoại.

Phương thức thanh toán

Các phương thức sau đều dùng được trong tập lệnh thanh toán:

Nhập vào

Phương thức tập lệnh dùng đối tượng Input trong tập lệnh thanh toán

Phương thức	Loại trả lại	Mô tả
.payment_gateways	PaymentGatewaysList	Trả về danh sách tất cả các cổng thanh toán của cửa hàng.

PaymentGatewayList

Phương thức tập lệnh sử dụng đối tượng PaymentGatewayList trong tập lệnh thanh toán

Phương thức	Loại trả lại	Mô tả
.delete_if	PaymentGatewayList	Xóa cổng thanh toán bằng khối mã tùy chọn. Xem tài liệu về phương thức delete_if của Ruby.
.sort!	PaymentGatewayList	Sắp xếp cổng thanh toán bằng toán tử so sánh hoặc khối mã tùy chọn. Xem tài liệu về phương thức sort! của Ruby.
.sort_by!	PaymentGatewayList	Sắp xếp cổng thanh toán bằng khối mã tùy chọn. Xem tài liệu về phương thức sort_by! của Ruby.

PaymentGateway

Phương thức	Loại trả lại	Mô tả
.name	Chuỗi	Trả về tên của cổng thanh toán.
.enabled_card_brands	Danh sách<String>	Nếu cổng thanh toán hỗ trợ thẻ tín dụng, trả về danh sách các loại thẻ tín dụng mà cửa hàng chấp nhận. Nếu cổng không hỗ trợ thẻ tín dụng, trả về danh sách trống.
.change_name (Chuỗi new_name)	Chuỗi	Đổi tên cổng thanh toán. Không thể đổi tên cổng thanh toán có logo.

Ví dụ

Trong ví dụ về tập lệnh mục hàng sau, khi khách đặt hàng sản phẩm không phải thẻ quà tặng, giá sản phẩm giảm đi 9 USD. Ngoài ra, tổng số tiền khách hàng đã chi trong tất cả các lần truy cập vào cửa hàng sẽ hiển thị:

customer = Input.cart.customer Input.cart.line_items.each do |line_item| product = line_item.variant.product next if product.gift_card? line_item.change_line_price(line_item.line_price - Money.new(cents: 900), message: customer.total_spent) end Output.cart = Input.cart

Tìm hiểu thêm

Tìm hiểu thêm về:

• Các khái niệm cơ bản về Ruby
• Tạo tập lệnh
• Kiểm tra và gỡ lỗi tập lệnh
• Cập nhật mẫu Liquid cho tập lệnh
• Shopify Scripts