Shopify Scripts API 참조

이 페이지는 May 15, 2024에 인쇄되었습니다. 최신 버전은 https://help.shopify.com/ko/manual/checkout-settings/script-editor/shopify-scripts에서 확인하십시오.

스크립트는 상당한 제어와 유연성을 제공하는 Ruby API로 작성됩니다.

스크립트 유형은 매우 다양합니다. 스크립트 에디터 앱에서 스크립트를 생성할 때 어떤 스크립트 템플릿으로 시작할지 선택함에 따라 스크립트에 유형이 할당됩니다.

품목 스크립트

품목 스크립트는 카트의 품목에 영향을 미치며 가격을 변경하고 할인을 부여할 수 있습니다. 이 스크립트는 카트가 변경되면 실행됩니다.

구독을 할인하는 품목 스크립트는 첫 번째 구독 결제에만 적용됩니다. 이후 결제부터는 스크립트에 따라 할인되지 않습니다.

일부 메서드는 품목 스크립트에서만 사용할 수 있습니다.

배송 스크립트

배송 스크립트는 배송과 상호작용하며 배송 방법을 변경하고 배송료에 할인을 부여할 수 있습니다. 이 스크립트는 결제가 배송 옵션 페이지에 도달하면 실행됩니다.

구독 배송료를 할인하는 배송 스크립트는 첫 번째 구독 결제에만 적용됩니다. 이후 결제부터는 스크립트에 따라 할인되지 않습니다.

일부 메서드는 배송 스크립트에서만 사용할 수 있습니다.

결제 스크립트

결제 스크립트는 결제와 상호작용하여 전자결제 대행사를 숨기고 재정렬하거나 이름을 바꿀 수 있습니다. 참고로 결제 스크립트는 Apple Pay 등의 결제 화면 앞에 표시되는 전자결제 대행사와는 상호작용하지 않습니다. 이 스크립트는 결제가 결제 페이지에 도달하면 실행됩니다.

일부 메서드는 결제 스크립트에서만 사용할 수 있습니다.

이 페이지의 정보

일반 메서드

다음은 모든 유형의 스크립트에서 사용할 수 있는 메서드입니다.

입력

스크립트 입력 메서드
메서드 반품 유형 설명
.cart 카트 변경 가능한 카트 개체를 반환합니다.
.locale 문자열 고객의 로케일을 반환합니다. 예: en, fr, pt-BR

카트

카트 개체는 온라인 스토어에서만 사용할 수 있습니다. 일부 중단된 결제는 카트 개체에 액세스할 수 있습니다. 그러나 결제가 종료된 후 고객이 중단된 결제를 방문하면 자동 입력된 결제로 보내지며 해당 카트 개체는 더 이상 존재하지 않습니다. 이는 스토어 프론트가 중단된 결제 이메일을 통해 우회되었기 때문입니다.

Cart 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.customer 고객 카트 소유자가 있는 경우 이를 반환합니다.
.shipping_address ShippingAddress 카트 소유자의 배송 주소가 있는 경우 이를 반환합니다.
.discount_code 다양함 반품:

discount_code는 카트에 할인이 적용된 경우에 존재합니다. 할인 코드가 있다고 해서 카트의 가격이 반드시 변경되는 것은 아닙니다. 예를 들어, $50가 넘는 카트에 할인이 적용되고 스크립트에서 카트 가격을 $50 미만으로 내리면 discount_code는 여전히 존재하지만 카트의 가격은 변경되지 않습니다.

discount_code 예를 참조하십시오.
.line_items List<LineItem> 카트의 품목을 포함한 목록을 반환합니다.
.presentment_currency List<String> 고객의 현지(제시) 통화를 반환합니다(ISO 4217 형식). 예: USD
.subtotal_price 대금 품목 할인이 적용된 후 할인 코드가 적용되기 전의 카트의 소계 가격을 반환합니다.
.total_weight 그램 카트의 모든 품목의 총 중량을 반환합니다.

CartDiscount::FixedAmount

CartDiscount::FixedAmount 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.code 문자열 할인 적용에 사용된 할인 코드를 반환합니다.
.amount 대금 할인 금액을 반환합니다.
.reject({ message: String }) nil 카트에 적용된 할인 코드를 거부합니다. message가 필요합니다.
.rejected? 부울 할인 코드가 거부되었는지 여부를 반환합니다.

CartDiscount::Percentage

CartDiscount::Percentage 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.code 문자열 할인 적용에 사용된 할인 코드를 반환합니다.
.percentage 10 진수 할인의 백분율 금액을 반환합니다.
.reject({ message: String }) nil 카트에 적용된 할인 코드를 거부합니다. message가 필요합니다.
.rejected? 부울 할인 코드가 거부되었는지 여부를 반환합니다.

CartDiscount::Shipping

CartDiscount::Shipping 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.code 문자열 할인 적용에 사용된 할인 코드를 반환합니다.
.reject({ message: String }) nil 카트에 적용된 할인 코드를 거부합니다. message가 필요합니다.
.rejected? 부울 할인 코드가 거부되었는지 여부를 반환합니다.

고객

Customer 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.id 정수 고객의 ID 번호를 반환합니다.
.email 문자열 고객의 이메일 주소를 반환합니다.
.tags List<Tag> 고객에 설정된 태그를 나타내는 문자열 목록을 반환합니다.
.orders_count 정수 고객이 주문한 총 주문 수를 반환합니다.
.total_spent 대금 고객이 모든 주문에 소비한 총 금액을 반환합니다.
.accepts_marketing? 부울 고객이 마케팅을 수락하는지 여부를 반환합니다.

LineItem

<tdgrams
LineItem 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.grams 품목의 총 중량을 반환합니다.
.line_price 대금 품목의 가격
.discounted? 부울 품목 가격이 스크립트에 의해 할인되었는지 혹은 수동으로 할인이 적용되었는지 여부를 반환합니다. 할인 코드를 사용해도 반환 값에 영향을 주지 않습니다.
.properties hash 이 품목에 지정된 특성을 반환합니다.
.variant 이형 상품 품목별로 표시되는 특정 제품 이형 상품을 반환합니다.
.quantity 정수 이 품목의 수량을 반환합니다.
.selling_plan_id 정수 품목에 대한 판매 플랜의 ID를 반환합니다. 이 메서드는 스토어에서 구독을 판매하고 제품 이형이 구독으로 판매될 때 해당 스크립트로 감지하려는 경우에 유용합니다.

List

List 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.new List 목록을 나타내는 새 개체를 생성합니다.
.[] Element 또는 nil

지정된 지수에 해당하는 요소를 반환합니다.
.& List

두 목록에 공통적으로 적용되는 요소가 포함된 새 목록을 복제하지 않고 반환합니다.
.delete_if List 선택 사항인 코드 블록 옵션을 사용하여 구성 요소를 제거합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오.
.empty? 부울

목록에 요소가 포함되어 있지 않은 경우 true를 반환합니다.
.first Element 또는 nil

목록이 비어 있는 경우 첫 번째 요소 또는 nil을 반환합니다.
.index(*args, &block) int 또는 nil

목록의 첫 번째 요소의 지수를 반환합니다. 인수 대신 블록이 제공되는 경우에는 해당 블록이 참인 첫 번째 요소의 지수를 반환합니다.
.rindex(*args, &block) int 또는 nil

목록의 마지막 요소의 지수를 반환합니다. 인수 대신 블록이 제공되는 경우에는 해당 블록이 참인 첫 번째 요소의 지수를 반환합니다.
.last Element 또는 nil

목록이 비어 있는 경우 마지막 요소 또는 nil을 반환합니다.
.length int

목록에 있는 요소의 수를 반환합니다.
.size int

길이에 대한 별칭입니다.
.each(*args, &block) List

목록의 각 요소에 대한 블록을 한 번씩 호출하여 해당 요소를 매개 변수로서 블록에 전달합니다.

ShippingAddress

ShippingAddress 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.name 문자열 배송 주소와 연결된 사람의 이름을 반환합니다.
.address1 문자열 배송 주소의 거리 주소 부분을 반환합니다.
.address2 문자열 배송 주소의 거리 주소 부분에 대한 선택적인 추가 필드를 반환합니다.
.phone 문자열 배송 주소의 전화 번호를 반환합니다.
.city 문자열 배송 주소의 시를 반환합니다.
.zip 문자열 배송 주소의 우편 번호를 반환합니다.
.province 문자열 배송 주소의 주/도를 반환합니다.
.province_code 문자열 배송 주소의 주/도 약어 값을 반환합니다.
.country_code 문자열 배송 주소의 국가 약어 값을 반환합니다.

대금

Money 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.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 개체를 반환합니다.

이형 상품

Variant 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.id 정수 이형 상품의 ID 번호를 반환합니다.
.price 대금 이형 상품의 단가를 반환합니다.
.product 제품 이형 상품의 관련 제품을 반환합니다.
.skus List<String> 재고 추적에 자주 사용되는 이형 상품의 SKU(재고 관리 코드)를 반환합니다.
.title 문자열 이형 상품의 제목을 반환합니다.

제품

Product 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.id 정수 제품의 ID 번호를 반환합니다.
.gift_card? 부울 제품이 기프트 카드인지 여부를 반환합니다.
.tags List<Tag> 이 제품에 설정된 태그를 나타내는 문자열 목록을 반환합니다.
.product_type 문자열 제품 태그가 지정될 수 있는 카테고리로, 일반적으로 필터링 및 검색에 사용됩니다.
.vendor 문자열 이 제품의 공급업체를 반환합니다.

Kernel

Kernel은 모든 클래스에 포함된 Ruby 모듈입니다. 따라서 해당 메서드를 모든 개체에 사용할 수 있습니다. 이 메서드는 글로벌 함수가 다른 언어로 작동하는 방식과 동일하게 작동합니다.

Kernel 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.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

품목 메서드

다음은 품목 스크립트에서만 사용할 수 있는 메서드입니다.

카트

품목 스크립트에서 Cart 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.subtotal_price_was 대금 할인이 적용되기 전의 카트의 소계 가격을 반환합니다.
.subtotal_price_changed? 부울 소계 가격이 변경되었는지 여부를 반환합니다.

LineItem

품목 스크립트에서 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

이형 상품

품목 스크립트에서 Variant 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.compare_at_price 대금 이형 상품의 비교 가격을 반환합니다. 이형 상품에 비교 가격이 없는 경우 nil을 반환합니다.

배송 메서드

다음은 배송 스크립트에서 사용할 수 있는 메서드입니다.

입력

배송 스크립트에서 Input 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.shipping_rates ShippingRateList 모든 배송료의 목록을 반환합니다.

ShippingRateList

배송 스크립트에서 ShippingRateList 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.delete_if ShippingRateList 선택 사항인 코드 블록을 사용하여 배송료를 삭제합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오.
.sort! ShippingRateList 비교 연산자를 사용하거나 선택 사항인 코드 블록을 사용하여 배송료를 정렬합니다. Ruby의 sort! 메서드에 대한 문서를 참조하십시오.
.sort_by! ShippingRateList 선택 사항인 코드 블록을 사용하여 배송료를 정렬합니다. Ruby의 sort_by! 메서드에 대한 문서를 참조하십시오.

ShippingRate

배송 스크립트에서 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를 반환합니다.

결제 방법

다음은 결제 스크립트에서 사용할 수 있는 메서드입니다.

입력

결제 스크립트에서 Input 개체를 사용하는 스크립트 메서드
메서드 반품 유형 설명
.payment_gateways PaymentGatewaysList 스토어의 모든 전자결제 대행사 목록을 반환합니다.

PaymentGatewayList

결제 스크립트에서 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

자세히 알아보기

자세한 정보 알아보기:

Shopify와 함께 사업을 시작할 준비가 되셨습니까?

무료 체험