Shopify Scripts API 참조

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

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

품목 스크립트

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

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

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

배송 스크립트

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

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

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

결제 스크립트

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

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

일반 메서드

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

입력

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

카트

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

Cart 개체를 사용하는 스크립트 메서드
메서드반품 유형설명
.customer고객카트 소유자가 있는 경우 이를 반환합니다.
.shipping_addressShippingAddress카트 소유자의 배송 주소가 있는 경우 이를 반환합니다.
.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문자열할인 적용에 사용된 할인 코드를 반환합니다.
.percentage10 진수할인의 백분율 금액을 반환합니다.
.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?부울품목 가격이 스크립트에 의해 할인되었는지 혹은 수동으로 할인이 적용되었는지 여부를 반환합니다. 할인 코드를 사용해도 반환 값에 영향을 주지 않습니다.
.propertieshash이 품목에 지정된 특성을 반환합니다.
.variant이형 상품품목별로 표시되는 특정 제품 이형 상품을 반환합니다.
.quantity정수이 품목의 수량을 반환합니다.
.selling_plan_id정수품목에 대한 판매 플랜의 ID를 반환합니다. 이 메서드는 스토어에서 구독을 판매하고 제품 이형이 구독으로 판매될 때 해당 스크립트로 감지하려는 경우에 유용합니다.

List

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

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

.&List

두 목록에 공통적으로 적용되는 요소가 포함된 새 목록을 복제하지 않고 반환합니다.

.delete_ifList선택 사항인 코드 블록 옵션을 사용하여 구성 요소를 제거합니다. Ruby의 delete_if 메서드에 대한 문서를 참조하십시오.
.empty?부울

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

.firstElement 또는 nil

목록이 비어 있는 경우 첫 번째 요소 또는 nil을 반환합니다.

.index(*args, &block)int 또는 nil

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

.rindex(*args, &block)int 또는 nil

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

.lastElement 또는 nil

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

.lengthint

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

.sizeint

길이에 대한 별칭입니다.

.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 개체를 사용하는 스크립트 메서드
메서드반품 유형설명
.exitnone오류 없이 현재 스크립트의 실행을 종료합니다. 이 작업을 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_washash변경 사항이 적용되기 전의 품목의 원래 특성 해시를 반환합니다.
.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_ratesShippingRateList모든 배송료의 목록을 반환합니다.

ShippingRateList

배송 스크립트에서 ShippingRateList 개체를 사용하는 스크립트 메서드
메서드반품 유형설명
.delete_ifShippingRateList선택 사항인 코드 블록을 사용하여 배송료를 삭제합니다. 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_gatewaysPaymentGatewaysList스토어의 모든 전자결제 대행사 목록을 반환합니다.

PaymentGatewayList

결제 스크립트에서 PaymentGatewayList 개체를 사용하는 스크립트 메서드
메서드반품 유형설명
.delete_ifPaymentGatewayList선택 사항인 코드 블록 옵션을 사용하여 전자결제 대행사를 삭제합니다. 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

자세히 알아보기

자세한 정보 알아보기:

적절한 답변을 찾을 수 없습니까? 언제든지 도와드리겠습니다.