Shopify Scripts API 참조
스크립트는 상당한 제어와 유연성을 제공하는 Ruby API로 작성됩니다.
스크립트 유형은 매우 다양합니다. 스크립트 에디터 앱에서 스크립트를 생성할 때 어떤 스크립트 템플릿으로 시작할지 선택함에 따라 스크립트에 유형이 할당됩니다.
품목 스크립트
품목 스크립트는 카트의 품목에 영향을 미치며 가격을 변경하고 할인을 부여할 수 있습니다. 이 스크립트는 카트가 변경되면 실행됩니다.
구독을 할인하는 품목 스크립트는 첫 번째 구독 결제에만 적용됩니다. 이후 결제부터는 스크립트에 따라 할인되지 않습니다.
일부 메서드는 품목 스크립트에서만 사용할 수 있습니다.
배송 스크립트
배송 스크립트는 배송과 상호작용하며 배송 방법을 변경하고 배송료에 할인을 부여할 수 있습니다. 이 스크립트는 결제가 배송 옵션 페이지에 도달하면 실행됩니다.
구독 배송료를 할인하는 배송 스크립트는 첫 번째 구독 결제에만 적용됩니다. 이후 결제부터는 스크립트에 따라 할인되지 않습니다.
일부 메서드는 배송 스크립트에서만 사용할 수 있습니다.
결제 스크립트
결제 스크립트는 결제와 상호작용하여 전자결제 대행사를 숨기고 재정렬하거나 이름을 바꿀 수 있습니다. 참고로 결제 스크립트는 Apple Pay 등의 결제 화면 앞에 표시되는 전자결제 대행사와는 상호작용하지 않습니다. 이 스크립트는 결제가 결제 페이지에 도달하면 실행됩니다.
일부 메서드는 결제 스크립트에서만 사용할 수 있습니다.
일반 메서드
다음은 모든 유형의 스크립트에서 사용할 수 있는 메서드입니다.
입력
메서드 | 반품 유형 | 설명 |
---|---|---|
.cart | 카트 | 변경 가능한 카트 개체를 반환합니다. |
.locale | 문자열 | 고객의 로케일을 반환합니다. 예: en , fr , pt-BR |
카트
카트 개체는 온라인 스토어에서만 사용할 수 있습니다. 일부 중단된 결제는 카트 개체에 액세스할 수 있습니다. 그러나 결제가 종료된 후 고객이 중단된 결제를 방문하면 자동 입력된 결제로 보내지며 해당 카트 개체는 더 이상 존재하지 않습니다. 이는 스토어 프론트가 중단된 결제 이메일을 통해 우회되었기 때문입니다.
메서드 | 반품 유형 | 설명 |
---|---|---|
.customer | 고객 | 카트 소유자가 있는 경우 이를 반환합니다. |
.shipping_address | ShippingAddress | 카트 소유자의 배송 주소가 있는 경우 이를 반환합니다. |
.discount_code | 다양함 |
반품:
|
.line_items | List<LineItem> | 카트의 품목을 포함한 목록을 반환합니다. |
.presentment_currency | List<String> | 고객의 현지(제시) 통화를 반환합니다(ISO 4217 형식). 예: USD |
.subtotal_price | 대금 | 품목 할인이 적용된 후 할인 코드가 적용되기 전의 카트의 소계 가격을 반환합니다. |
.total_weight | 그램 | 카트의 모든 품목의 총 중량을 반환합니다. |
CartDiscount::FixedAmount
메서드 | 반품 유형 | 설명 |
---|---|---|
.code | 문자열 | 할인 적용에 사용된 할인 코드를 반환합니다. |
.amount | 대금 | 할인 금액을 반환합니다. |
.reject({ message: String }) | nil | 카트에 적용된 할인 코드를 거부합니다. message 가 필요합니다. |
.rejected? | 부울 | 할인 코드가 거부되었는지 여부를 반환합니다. |
CartDiscount::Percentage
메서드 | 반품 유형 | 설명 |
---|---|---|
.code | 문자열 | 할인 적용에 사용된 할인 코드를 반환합니다. |
.percentage | 10 진수 | 할인의 백분율 금액을 반환합니다. |
.reject({ message: String }) | nil | 카트에 적용된 할인 코드를 거부합니다. message 가 필요합니다. |
.rejected? | 부울 | 할인 코드가 거부되었는지 여부를 반환합니다. |
CartDiscount::Shipping
메서드 | 반품 유형 | 설명 |
---|---|---|
.code | 문자열 | 할인 적용에 사용된 할인 코드를 반환합니다. |
.reject({ message: String }) | nil | 카트에 적용된 할인 코드를 거부합니다. message 가 필요합니다. |
.rejected? | 부울 | 할인 코드가 거부되었는지 여부를 반환합니다. |
고객
메서드 | 반품 유형 | 설명 |
---|---|---|
.id | 정수 | 고객의 ID 번호를 반환합니다. |
문자열 | 고객의 이메일 주소를 반환합니다. | |
.tags | List<Tag> | 고객에 설정된 태그를 나타내는 문자열 목록을 반환합니다. |
.orders_count | 정수 | 고객이 주문한 총 주문 수를 반환합니다. |
.total_spent | 대금 | 고객이 모든 주문에 소비한 총 금액을 반환합니다. |
.accepts_marketing? | 부울 | 고객이 마케팅을 수락하는지 여부를 반환합니다. |
LineItem
메서드 | 반품 유형 | 설명 |
---|---|---|
.grams | <tdgrams품목의 총 중량을 반환합니다. | |
.line_price | 대금 | 품목의 가격 |
.discounted? | 부울 | 품목 가격이 스크립트에 의해 할인되었는지 혹은 수동으로 할인이 적용되었는지 여부를 반환합니다. 할인 코드를 사용해도 반환 값에 영향을 주지 않습니다. |
.properties | hash | 이 품목에 지정된 특성을 반환합니다. |
.variant | 이형 상품 | 품목별로 표시되는 특정 제품 이형 상품을 반환합니다. |
.quantity | 정수 | 이 품목의 수량을 반환합니다. |
.selling_plan_id | 정수 | 품목에 대한 판매 플랜의 ID를 반환합니다. 이 메서드는 스토어에서 구독을 판매하고 제품 이형이 구독으로 판매될 때 해당 스크립트로 감지하려는 경우에 유용합니다. |
List
메서드 | 반품 유형 | 설명 |
---|---|---|
.new | List | 목록을 나타내는 새 개체를 생성합니다. |
.[] | Element 또는 nil |
지정된 지수에 해당하는 요소를 반환합니다. |
.& | List |
두 목록에 공통적으로 적용되는 요소가 포함된 새 목록을 복제하지 않고 반환합니다. |
.delete_if | List | 선택 사항인 코드 블록 옵션을 사용하여 구성 요소를 제거합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오. |
.empty? | 부울 |
목록에 요소가 포함되어 있지 않은 경우 |
.first | Element 또는 nil |
목록이 비어 있는 경우 첫 번째 요소 또는 |
.index(*args, &block) | int 또는 nil |
목록의 첫 번째 요소의 지수를 반환합니다. 인수 대신 블록이 제공되는 경우에는 해당 블록이 참인 첫 번째 요소의 지수를 반환합니다. |
.rindex(*args, &block) | int 또는 nil |
목록의 마지막 요소의 지수를 반환합니다. 인수 대신 블록이 제공되는 경우에는 해당 블록이 참인 첫 번째 요소의 지수를 반환합니다. |
.last | Element 또는 nil |
목록이 비어 있는 경우 마지막 요소 또는 |
.length | int |
목록에 있는 요소의 수를 반환합니다. |
.size | int |
길이에 대한 별칭입니다. |
.each(*args, &block) | List |
목록의 각 요소에 대한 블록을 한 번씩 호출하여 해당 요소를 매개 변수로서 블록에 전달합니다. |
ShippingAddress
메서드 | 반품 유형 | 설명 |
---|---|---|
.name | 문자열 | 배송 주소와 연결된 사람의 이름을 반환합니다. |
.address1 | 문자열 | 배송 주소의 거리 주소 부분을 반환합니다. |
.address2 | 문자열 | 배송 주소의 거리 주소 부분에 대한 선택적인 추가 필드를 반환합니다. |
.phone | 문자열 | 배송 주소의 전화 번호를 반환합니다. |
.city | 문자열 | 배송 주소의 시를 반환합니다. |
.zip | 문자열 | 배송 주소의 우편 번호를 반환합니다. |
.province | 문자열 | 배송 주소의 주/도를 반환합니다. |
.province_code | 문자열 | 배송 주소의 주/도 약어 값을 반환합니다. |
.country_code | 문자열 | 배송 주소의 국가 약어 값을 반환합니다. |
대금
메서드 | 반품 유형 | 설명 |
---|---|---|
.derived_from_presentment(customer_cents:X) | 대금 | 고객의 현지(제시) 통화에서 스토어 통화로 금액(센트)을 전환합니다. 이 메서드는 customer_cents 매개 변수를 허용하며, 이는 숫자를 센트로 허용합니다. 예: Money.derived_from_presentment(customer_cents: 500)
|
.new | 대금 | 가격을 나타내는 새 개체를 생성합니다. |
.zero | 대금 |
가격이 0인 새 개체를 생성합니다. |
+ | 대금 |
Money 개체 두 개를 더합니다. |
- | 대금 |
Money 개체 하나를 뺍니다. |
* | 대금 |
Money 개체에 수를 곱합니다. |
Money 예
Money.new(cents: 1000)
1000 센트 또는 $10를 나타내는 Money
개체를 생성합니다.
Money.new(cents: 100) * 50
$1를 나타내는 Money
개체를 생성하고 해당 금액에 50을 곱합니다. $50를 나타내는 Money
개체를 반환합니다.
이형 상품
메서드 | 반품 유형 | 설명 |
---|---|---|
.id | 정수 | 이형 상품의 ID 번호를 반환합니다. |
.price | 대금 | 이형 상품의 단가를 반환합니다. |
.product | 제품 | 이형 상품의 관련 제품을 반환합니다. |
.skus | List<String> | 재고 추적에 자주 사용되는 이형 상품의 SKU(재고 관리 코드)를 반환합니다. |
.title | 문자열 | 이형 상품의 제목을 반환합니다. |
제품
메서드 | 반품 유형 | 설명 |
---|---|---|
.id | 정수 | 제품의 ID 번호를 반환합니다. |
.gift_card? | 부울 | 제품이 기프트 카드인지 여부를 반환합니다. |
.tags | List<Tag> | 이 제품에 설정된 태그를 나타내는 문자열 목록을 반환합니다. |
.product_type | 문자열 | 제품 태그가 지정될 수 있는 카테고리로, 일반적으로 필터링 및 검색에 사용됩니다. |
.vendor | 문자열 | 이 제품의 공급업체를 반환합니다. |
Kernel
Kernel은 모든 클래스에 포함된 Ruby 모듈입니다. 따라서 해당 메서드를 모든 개체에 사용할 수 있습니다. 이 메서드는 글로벌 함수가 다른 언어로 작동하는 방식과 동일하게 작동합니다.
메서드 | 반품 유형 | 설명 |
---|---|---|
.exit | none | 오류 없이 현재 스크립트의 실행을 종료합니다. 이 작업을 Output.cart 에 할당하기 전에 실행하면 해당 스크립트는 아무런 영향을 주지 않습니다. 고객이 스크립트를 실행할 수 없는 경우에 스크립트를 종료하는 유용한 방법입니다. |
Kernel 예
customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
# Employees are not eligible for this promotion.
exit
end
품목 메서드
다음은 품목 스크립트에서만 사용할 수 있는 메서드입니다.
카트
메서드 | 반품 유형 | 설명 |
---|---|---|
.subtotal_price_was | 대금 | 할인이 적용되기 전의 카트의 소계 가격을 반환합니다. |
.subtotal_price_changed? | 부울 | 소계 가격이 변경되었는지 여부를 반환합니다. |
LineItem
메서드 | 반품 유형 | 설명 |
---|---|---|
.change_line_price(Money new_price, { message: String }) | 대금 | 품목 가격을 지정된 금액으로 변경합니다. message 가 필요합니다. new_price 는 현재 가격보다 낮아야 합니다. |
.original_line_price | 대금 | 스크립트 및 할인이 적용되기 전의 품목의 원래 가격을 반환합니다. |
.line_price_was | 대금 | 현재 스크립트에서 변경 사항이 적용되기 전의 품목의 가격을 반환합니다. |
.line_price_changed? | 부울 | 품목 가격이 변경되었는지 여부를 반환합니다. |
.change_properties(hash new_properties, { message: String }) | hash | 품목에 대한 새 특성을 설정합니다. 원래 특성 해시가 properties_was 에 저장되며 메서드에 전달된 특성 해시가 해당 품목의 새 특성이 됩니다. |
.properties_was | hash | 변경 사항이 적용되기 전의 품목의 원래 특성 해시를 반환합니다. |
.properties_changed? | 부울 | 품목에 대한 특성이 변경되었는지 여부를 반환합니다. |
.split({ take: Integer }) | LineItem | 하나의 품목을 두 개의 품목으로 분할합니다. take 는 원래 품목에서 제거할 수량을 지정하여 새 품목을 생성합니다. |
.split 예
이 예시 스크립트에서는 original_line_item
으로 불리는 하나의 품목을 두 개의 품목으로 분할합니다. 새 품목의 수량은 1입니다(take: 1
로 지정). 그러면 스크립트에서 "세 번째 모자 5달러"라는 메시지와 함께 새 품목에 할인된 가격을 적용합니다.
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
이형 상품
메서드 | 반품 유형 | 설명 |
---|---|---|
.compare_at_price | 대금 | 이형 상품의 비교 가격을 반환합니다. 이형 상품에 비교 가격이 없는 경우 nil 을 반환합니다. |
배송 메서드
다음은 배송 스크립트에서 사용할 수 있는 메서드입니다.
입력
메서드 | 반품 유형 | 설명 |
---|---|---|
.shipping_rates | ShippingRateList | 모든 배송료의 목록을 반환합니다. |
ShippingRateList
메서드 | 반품 유형 | 설명 |
---|---|---|
.delete_if | ShippingRateList | 선택 사항인 코드 블록을 사용하여 배송료를 삭제합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오. |
.sort! | ShippingRateList | 비교 연산자를 사용하거나 선택 사항인 코드 블록을 사용하여 배송료를 정렬합니다. Ruby의 sort! 메서드에 대한 문서를 참조하십시오. |
.sort_by! | ShippingRateList | 선택 사항인 코드 블록을 사용하여 배송료를 정렬합니다. Ruby의 sort_by! 메서드에 대한 문서를 참조하십시오. |
ShippingRate
메서드 | 반품 유형 | 설명 |
---|---|---|
.code | 문자열 | 배송료의 코드를 반환합니다. |
.markup | 대금 | 해당하는 경우 배송료에 대한 마크업을 반환합니다. |
.name | 문자열 | 배송료의 이름을 반환합니다. change_name 방법을 사용하여 수정할 수 있습니다. |
.price | 대금 | 배송료의 가격을 반환합니다. |
.source | 문자열 | 관련이 있는 경우 배송료와 관련된 소스(배송업체)를 반환합니다. 수정할 수 없습니다. |
.change_name(String new_name) | 문자열 | 배송료의 이름(최대 255자)을 변경합니다. 소스를 변경, 삭제 또는 숨길 수 없습니다. |
.apply_discount(Money discount, { message: String }) | 대금 | 지정된 고정 금액의 할인을 적용합니다. 가격은 0 미만으로 내릴 수 없습니다. 메시지가 필요합니다. |
.phone_required? | 부울 | 배송료를 받기 위해 전화 번호를 입력해야 하는 경우에는 true 를 반환하며, 전화 번호가 필요하지 않은 경우에는 false 를 반환합니다. |
결제 방법
다음은 결제 스크립트에서 사용할 수 있는 메서드입니다.
입력
메서드 | 반품 유형 | 설명 |
---|---|---|
.payment_gateways | PaymentGatewaysList | 스토어의 모든 전자결제 대행사 목록을 반환합니다. |
PaymentGatewayList
메서드 | 반품 유형 | 설명 |
---|---|---|
.delete_if | PaymentGatewayList | 선택 사항인 코드 블록 옵션을 사용하여 전자결제 대행사를 삭제합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오. |
.sort! | PaymentGatewayList | 비교 연산자를 사용하거나 선택 사항인 코드 블록을 사용하여 전자결제 대행사를 정렬합니다. Ruby의 sort! 메서드에 대한 문서를 참조하십시오. |
.sort_by! | PaymentGatewayList | 선택 사항인 코드 블록을 사용하여 전자결제 대행사를 정렬합니다. Ruby의 sort_by! 메서드에 대한 문서를 참조하십시오. |
PaymentGateway
메서드 | 반품 유형 | 설명 |
---|---|---|
.name | 문자열 | 전자결제 대행사의 이름을 반환합니다. |
.enabled_card_brands | List<String> |
전자결제 대행사에서 신용 카드를 지원하는 경우에는 스토어에서 허용하는 신용 카드 유형 목록을 반환합니다. 대행사에서 신용 카드를 지원하지 않는 경우에는 빈 목록을 반환합니다. |
.change_name(String new_name) | 문자열 | 전자결제 대행사 이름을 변경합니다. 로고가 있는 전자결제 대행사의 이름은 변경할 수 없습니다. |
예제
다음 품목 스크립트 예시에서는 고객이 기프트 카드가 아닌 제품을 주문하면 제품 가격이 $9로 인하됩니다. 또한 고객이 스토어에 방문한 동안 소비한 총 금액이 표시됩니다.
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
자세히 알아보기
자세한 정보 알아보기: