Shopify Scripts API 참조

스크립트는 높은 수준의 제어 기능과 유연성을 제공하는 Ruby API로 작성됩니다.

다양한 스크립트 유형이 있습니다. 스크립트의 유형은 Script Editor 앱에서 스크립트를 생성할 때 시작하기 위해 선택하는 스크립트 템플릿에 따라 할당됩니다.

품목 스크립트

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

구독을 할인하는 품목 스크립트는 구독의 첫 결제에만 적용됩니다. 이후 결제는 스크립트로 할인되지 않습니다.

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

배송 스크립트

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

구독 배송료를 할인하는 배송 스크립트는 구독의 첫 결제에만 적용됩니다. 이후 결제는 스크립트로 할인되지 않습니다.

<p>Some methods <a href="#shipping-methods">can only be used in shipping scripts</a>.</p>

결제 스크립트

결제 스크립트는 결제와 상호 작용하며 전자결제 대행사의 이름을 바꾸고 숨기고 재정렬할 수 있습니다. 결제 스크립트는 Apple Pay와 같이 체크아웃 화면 이전에 표시되는 전자결제 대행사와는 상호 작용하지 않습니다. 이 스크립트는 체크아웃이 결제 페이지에 도달하면 실행됩니다.

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

이 페이지의 내용

일반 메소드

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

입력

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

Cart

카트 객체는 온라인 스토어에서만 사용할 수 있습니다. 일부 중단된 체크아웃에서는 카트 객체에 액세스할 수 있습니다. 그러나 체크아웃이 마감된 후 고객이 중단된 체크아웃을 방문하면 미리 채워진 체크아웃으로 이동되며 카트 객체는 더 이상 존재하지 않습니다. 중단된 체크아웃 이메일을 통해 스토어프론트를 우회했기 때문입니다.

메소드 반환 유형 설명

.customer Customer 카트의 소유자(있는 경우)를 반환합니다.

.shipping_address ShippingAddress 카트 소유자의 배송 주소(있는 경우)를 반환합니다.

.discount_code

다양함

Cart 객체를 사용하는 스크립트 메소드
메소드	반환 유형	설명
.customer	Customer	카트의 소유자(있는 경우)를 반환합니다.
.shipping_address	ShippingAddress	카트 소유자의 배송 주소(있는 경우)를 반환합니다.
.discount_code	다양함	반환값: 카트에 할인 코드가 없는 경우 `nil` 카트에 고정 금액 할인이 있는 경우 `CartDiscount::FixedAmount` 카트에 백분율 할인이 있는 경우 `CartDiscount::Percentage` 카트에 배송 할인이 있는 경우 `CartDiscount::Shipping` 단일 할인 코드를 반환합니다(제한 사항 참조). 카트에 할인이 적용된 경우 `discount_code`가 존재합니다. 이것이 반드시 카트 가격이 변경됨을 의미하는 것은 아닙니다. 예를 들어, 50달러를 초과하는 카트에 할인이 적용될 때 스크립트가 카트 가격을 50달러 미만으로 낮추더라도 `discount_code`는 계속 존재하며 카트 가격은 변경되지 않습니다. <p><a href="/manual/checkout-settings/script-editor/examples/vat-script">See an example of <code>discount_code</code></a>.</p> </td> </tr> <tr> <td scope="row">.line_items</td> <td><a href="#list">List</a><LineItem></td> <td>Returns a list containing the line items in the cart.</td> </tr> <tr> <td scope="row">.presentment_currency</td> <td><a href="#list">List</a><String></td> <td>Returns the customer's local (presentment) currency (in <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217</a> format). For example, USD. </td> </tr> <tr> <td scope="row">.subtotal_price</td> <td><a href="#money">Money</a></td> <td>Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.</td> </tr> <tr> <td scope="row">.total_weight</td> <td><a href="https://shopify.dev/api/liquid/objects/line_item#line_item-grams">grams</a></td> <td>Returns the total weight of all the line items in the cart.</td> </tr>

반환값:

카트에 할인 코드가 없는 경우 nil
카트에 고정 금액 할인이 있는 경우 CartDiscount::FixedAmount
카트에 백분율 할인이 있는 경우 CartDiscount::Percentage
카트에 배송 할인이 있는 경우 CartDiscount::Shipping
단일 할인 코드를 반환합니다(제한 사항 참조).

카트에 할인이 적용된 경우 discount_code가 존재합니다. 이것이 반드시 카트 가격이 변경됨을 의미하는 것은 아닙니다. 예를 들어, 50달러를 초과하는 카트에 할인이 적용될 때 스크립트가 카트 가격을 50달러 미만으로 낮추더라도 discount_code는 계속 존재하며 카트 가격은 변경되지 않습니다.

<p><a href="/manual/checkout-settings/script-editor/examples/vat-script">See an example of <code>discount_code</code></a>.</p>
  </td>
</tr>
<tr>
  <td scope="row">.line_items</td>
  <td><a href="#list">List</a>&lt;LineItem&gt;</td>
  <td>Returns a list containing the line items in the cart.</td>
</tr>
<tr>
  <td scope="row">.presentment_currency</td>
  <td><a href="#list">List</a>&lt;String&gt;</td>
  <td>Returns the customer's local (presentment) currency (in <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217</a> format). For example, USD. </td>
</tr>
<tr>
  <td scope="row">.subtotal_price</td>
  <td><a href="#money">Money</a></td>
  <td>Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.</td>
</tr>
<tr>
  <td scope="row">.total_weight</td>
  <td><a href="https://shopify.dev/api/liquid/objects/line_item#line_item-grams">grams</a></td>
  <td>Returns the total weight of all the line items in the cart.</td>
</tr>

CartDiscount::FixedAmount

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

CartDiscount::Percentage

CartDiscount::Percentage 객체를 사용하는 스크립트 메소드
메소드	반환 유형	설명
.code	문자열	할인을 적용하는 데 사용된 할인 코드를 반환합니다.
.percentage	데시멀	할인의 백분율 금액을 반환합니다.
.reject({ message: String })	nil	카트에 적용된 할인 코드를 거부합니다. `message`가 필요합니다.
.rejected?	불리언	할인 코드가 거부되었는지 여부를 반환합니다.

CartDiscount::Shipping

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

Customer

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

LineItem

LineItem 개체를 사용하는 스크립트 메서드
메소드	반환 유형	설명
.grams	grams	품목의 총 중량을 반환합니다.
.line_price	Money	품목의 가격입니다.
.discounted?	불리언	스크립트 또는 수동으로 적용된 할인에 의해 품목 가격이 할인되었는지 여부를 반환합니다. 할인 코드 사용은 반환 값에 영향을 주지 않습니다.
.properties	해시	이 품목에 지정된 속성을 반환합니다.
.variant	Variant	품목으로 표시되는 특정 제품 이형을 반환합니다.
.quantity	정수	이 품목의 수량을 반환합니다.
.selling_plan_id	정수	품목에 대한 판매 계획의 ID를 반환합니다. 이 메서드는 스토어에서 구독을 판매하고 스크립트에서 제품 이형이 구독으로 판매될 때를 감지하도록 하려는 경우에 유용합니다.

List

List 개체를 사용하는 스크립트 메서드
메소드	반환 유형	설명
.new	List	목록을 나타내는 새 개체를 생성합니다.
.[]	요소 또는 nil	지정된 인덱스의 요소를 반환합니다.
.&	List	두 목록에 공통된 요소를 포함하고 중복이 없는 새 목록을 반환합니다.
.delete_if	List	선택적 코드 블록을 사용하여 요소를 삭제합니다. Ruby의 `delete_if` 메서드에 대한 설명서를 참조하십시오.
.empty?	불리언	목록에 요소가 없는 경우 `true`를 반환합니다.
.first	요소 또는 nil	첫 번째 요소를 반환하거나 목록이 비어 있는 경우 `nil`을 반환합니다.
.index(*args, &block)	정수 또는 nil	목록의 첫 번째 요소의 인덱스를 반환합니다. 인수 대신 블록이 제공되는 경우, 블록이 true인 첫 번째 요소의 인덱스를 반환합니다.
.rindex(*args, &block)	정수 또는 nil	목록의 마지막 요소 인덱스를 반환합니다. 인수 대신 블록이 제공되는 경우, 블록이 true인 첫 번째 요소의 인덱스를 반환합니다.
.last	요소 또는 nil	마지막 요소를 반환하거나 목록이 비어 있는 경우 `nil`을 반환합니다.
.length	정수	목록에 있는 요소의 수를 반환합니다.
.size	정수	length의 별칭입니다.
.each(*args, &block)	List	목록의 각 요소에 대해 블록을 한 번 호출하며, 해당 요소를 블록에 매개 변수로 전달합니다.

ShippingAddress

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

Money

Money 개체를 사용하는 스크립트 메서드
메소드	반환 유형	설명
.derived_from_presentment(customer_cents:X)	Money	고객의 현지(표시) 통화의 금액(센트 단위)을 스토어 통화로 전환합니다. 이 메소드는 센트 단위의 숫자를 허용하는 `customer_cents` 매개변수를 허용합니다. 예를 들어 `Money.derived_from_presentment(customer_cents: 500)`입니다.
.new	Money	가격을 나타내는 새 객체를 생성합니다.
.zero	Money	가격이 0인 새 객체를 생성합니다.
+	Money	두 개의 `Money` 객체를 더합니다.
-	Money	한 `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	Money	이형 상품의 단가를 반환합니다.
.product	제품	이형 상품의 관련 제품을 반환합니다.
.skus	목록<문자열>	재고 추적에 자주 사용되는 이형 상품의 SKU(재고 관리 코드)를 반환합니다.
.title	문자열	이형 상품의 제목을 반환합니다.

제품

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

Kernel

Kernel은 모든 클래스에 포함된 Ruby 모듈입니다. 결과적으로 모든 객체에서 해당 메소드를 사용할 수 있습니다. 이러한 메소드는 다른 언어의 전역 함수와 동일한 방식으로 작동합니다.

Kernel 객체를 사용하는 스크립트 메소드
메소드	반환 유형	설명
.exit	없음	오류 없이 현재 스크립트의 실행을 종료합니다. `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

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

LineItem

품목 스크립트에서 LineItem 객체를 사용하는 스크립트 메소드
메소드	반환 유형	설명
.change_line_price(Money new_price, { message: 문자열 })	Money	품목의 가격을 지정된 금액으로 변경합니다. `message`가 필요합니다. `new_price`는 현재 가격보다 낮아야 합니다.
.original_line_price	Money	스크립트 및 할인이 적용되기 전의 원래 품목 가격을 반환합니다.
.line_price_was	Money	현재 스크립트에 의해 변경 사항이 적용되기 전의 품목 가격을 반환합니다.
.line_price_changed?	불리언	품목의 가격이 변경되었는지 여부를 반환합니다.
.change_properties(해시 new_properties, { message: 문자열 })	해시	품목의 새 속성을 설정합니다. 원래 속성 해시는 `properties_was`에 저장되고 메소드에 전달된 속성 해시가 품목의 새 속성이 됩니다.
.properties_was	해시	변경 사항이 적용되기 전 품목의 원래 속성 해시를 반환합니다.
.properties_changed?	불리언	품목의 속성이 변경되었는지 여부를 반환합니다.
.split({ take: 정수 })	품목	품목 하나를 두 개의 품목으로 분할합니다. `take`는 새 품목을 생성하기 위해 원래 품목에서 제거할 수량을 지정합니다.

.split 예시

이 예시 스크립트는 original_line_item이라는 품목을 두 개의 품목으로 분할합니다. 새 품목의 수량은 1입니다(take: 1로 지정). 그런 다음 스크립트는 “모자 3개째 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	Money	이형 상품의 비교 가격을 반환합니다. 이형 상품에 비교 가격이 없는 경우 `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	Money	해당하는 경우 배송료에 대한 마크업을 반환합니다.
.name	문자열	배송료의 이름을 반환합니다. `change_name` 메서드를 사용하여 수정할 수 있습니다.
.price	Money	배송료 가격을 반환합니다.
.source	문자열	해당하는 경우 배송료와 연결된 소스(배송업체)를 반환합니다. 수정할 수 없습니다.
.change_name(String new_name)	문자열	배송료 이름을 변경합니다(최대 255자). 소스를 변경, 삭제 또는 숨길 수 없습니다.
.apply_discount(Money discount, { message: String })	Money	지정된 고정 금액의 할인을 적용합니다. 가격은 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	목록<문자열>	전자결제 대행사에서 신용 카드를 지원하는 경우 스토어에서 허용하는 신용 카드 유형 목록을 반환합니다. 대행사에서 신용 카드를 지원하지 않는 경우 빈 목록을 반환합니다.
.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

자세히 알아보기

자세히 알아보기: