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

Trang này được in vào Mar 31, 2023. Để lấy phiên bản hiện tại, vui lòng truy cập https://help.shopify.com/vi/manual/checkout-settings/script-editor/shopify-scripts.

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.

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ứcchỉ 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ớivận chuyểnvà 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ứcchỉ 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áckhoả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ứcchỉ 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ặcpt-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ề:

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_codevẫ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 Trả về danh sách có các mục hàng trong giỏ hàng.
.presentment_currency Danh sách Trả về đơn vị tiền tệ địa phương (hiển thị) của khách hàng (ở định dạngISO 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ộtthô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ộtthô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ộtthô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 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

grams Trả về tổng trọng lượng mục hàng.
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
.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ứcdelete_ifcủRuby.
.empty? Boolean

Trả vềtruenế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ặcnilnế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ủphần tử铜ố我cung阮富仲danh囊h. 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ặcnilnế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ượngMoney.
- Tiền Trừ một đối tượngMoneykhỏi một đối tượng khác.
* Tiền Nhân một đối tượngMoneyvới một con số.

Ví dụ về tiền

Money.new(cents:1000)

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

Money.new(cents:100)*50

Tạo một đối tượngMoneythể hiện 1 USD, sau đó nhân số tiền đó với 50. Trả về một đối tượngMoneythể 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 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 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

Kernellà 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 choOutput.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.customerifcustomer&&customer.email.end_with?("@mycompany.com")# Employees are not eligible for this promotion.exitend

Ph值ươngức mục挂

Các phương thức sau đây chỉ có thể dùng trongtậ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ềnnew_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_pricephả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 (hashnew_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ữ trongproperties_wasvà 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ênoriginal_line_itemthành hai mục hàng. Mục hàng mới có số lượng là 1 (dotake: 1chỉ đị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".

iforiginal_line_item.quantity>=3new_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_itemend

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ềnilnế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 trongtậ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ứcdelete_ifcủ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ứcsort!củ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ứcsort_by!củ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ứcchange_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ỗinew_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 美联社dụngưuđai giảm gia vớisố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ềtruenếu bắt buộc có số điện thoại để được hưởng phí vận chuyển này, hoặcfalsenế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 trongtậ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ứcdelete_ifcủ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ứcsort!củ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ứcsort_by!củ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

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ỗinew_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ề:

Bạn đã sẵn sàng bán hàng với Shopify?

Dùng thử miễn phí