class Etsy::Listing

Listing

Represents a single Etsy listing. Has the following attributes:

id

The unique identifier for this listing

title

The title of this listing

description

This listing's full description

view_count

The number of times this listing has been viewed

url

The full URL to this listing's detail page

price

The price of this listing item

currency

The currency that the seller is using for this listing item

quantity

The number of items available for sale

tags

An array of tags that the seller has used for this listing

materials

Any array of materials that was used in the production of this item

state

The current state of the item

hue

The hue of the listing's primary image (HSV color).

saturation

The saturation of the listing's primary image (HSV color).

brightness

The value of the listing's primary image (HSV color).

black_and_white?

True if the listing's primary image is in black & white.

Additionally, the following queries on this item are available:

active?

Is this listing active?

removed?

Has this listing been removed?

sold_out?

Is this listing sold out?

expired?

Has this listing expired?

alchemy?

Is this listing an Alchemy item? (i.e. requested by an Etsy user)

Constants

STATES
VALID_STATES

Public Class Methods

create(options = {}) click to toggle source
# File lib/etsy/listing.rb, line 63
def self.create(options = {})
  options.merge!(:require_secure => true)
  post("/listings", options)
end
destroy(listing, options = {}) click to toggle source
# File lib/etsy/listing.rb, line 73
def self.destroy(listing, options = {})
  options.merge!(:require_secure => true)
  delete("/listings/#{listing.id}", options)
end
find(*identifiers_and_options) click to toggle source

Retrieve one or more listings by ID:

Etsy::Listing.find(123)

You can find multiple listings by passing an array of identifiers:

Etsy::Listing.find([123, 456])
# File lib/etsy/listing.rb, line 86
def self.find(*identifiers_and_options)
  find_one_or_more('listings', identifiers_and_options)
end
find_all_active_by_category(category, options = {}) click to toggle source

Retrieve active listings for a given category. By default, pulls back the first 25 active listings. Defaults can be overridden using :limit, :offset, and :state

options = {

:limit => 25,
:offset => 100,
:token => 'toke',
:secret => 'secret'

} Etsy::Listing.find_all_active_by_category(“accessories”, options)

# File lib/etsy/listing.rb, line 130
def self.find_all_active_by_category(category, options = {})
  options[:category] = category
  get_all("/listings/active", options)
end
find_all_by_shop_id(shop_id, options = {}) click to toggle source

Retrieve listings for a given shop. By default, pulls back the first 25 active listings. Defaults can be overridden using :limit, :offset, and :state

Available states are :active, :expired, :inactive, :sold, and :featured, :draft, :sold_out where :featured is a subset of the others.

options = {

:state => :expired,
:limit => 100,
:offset => 100,
:token => 'toke',
:secret => 'secret'

} Etsy::Listing.find_all_by_shop_id(123, options)

# File lib/etsy/listing.rb, line 106
def self.find_all_by_shop_id(shop_id, options = {})
  state = options.delete(:state) || :active

  raise(ArgumentError, self.invalid_state_message(state)) unless valid?(state)

  if state == :sold
    sold_listings(shop_id, options)
  else
    get_all("/shops/#{shop_id}/listings/#{state}", options)
  end
end
update(listing, options = {}) click to toggle source
# File lib/etsy/listing.rb, line 68
def self.update(listing, options = {})
  options.merge!(:require_secure => true)
  put("/listings/#{listing.id}", options)
end

Private Class Methods

bought_listings(user_id, options = {}) click to toggle source

Find all listings that have been bought by a user

# File lib/etsy/listing.rb, line 285
def self.bought_listings(user_id, options = {})
  includes = options.delete(:includes)

  transactions = Transaction.find_all_by_buyer_id(user_id, options)
  listing_ids  = transactions.map {|t| t.listing_id }.uniq

  options = options.merge(:includes => includes) if includes
  (listing_ids.size > 0) ? Array(find(listing_ids, options)) : []
end
find_all_user_favorite_listings(user_id, options = {}) click to toggle source

Find all listings favored by a user

# File lib/etsy/listing.rb, line 277
def self.find_all_user_favorite_listings(user_id, options = {})
  favorite_listings = FavoriteListing.find_all_user_favorite_listings(user_id, options)
  listing_ids  = favorite_listings.map {|f| f.listing_id }.uniq
  (listing_ids.size > 0) ? Array(find(listing_ids, options)) : []
end
invalid_state_message(state) click to toggle source
# File lib/etsy/listing.rb, line 261
def self.invalid_state_message(state)
  "The state '#{state}' is invalid. Must be one of #{VALID_STATES.join(', ')}"
end
sold_listings(shop_id, options = {}) click to toggle source
# File lib/etsy/listing.rb, line 265
def self.sold_listings(shop_id, options = {})
  includes = options.delete(:includes)

  transactions = Transaction.find_all_by_shop_id(shop_id, options)
  listing_ids  = transactions.map {|t| t.listing_id }.uniq

  options = options.merge(:includes => includes) if includes
  (listing_ids.size > 0) ? Array(find(listing_ids, options)) : []
end
valid?(state) click to toggle source
# File lib/etsy/listing.rb, line 257
def self.valid?(state)
  VALID_STATES.include?(state)
end

Public Instance Methods

add_variations(options) click to toggle source

property_id = Etsy::Variation::PropertySet.find_property_by_name(“Dimensions”).fetch(“property_id”) scale = Etsy::Variation::PropertySet.qualifying_properties_for_property(“Dimensions”).detect {|qp| qp.fetch(“description”) == “Sizing Scale”} my_listing.add_variations(

:variations => [
  {"property_id" => property_id, "value" => "1 x 2", "is_available" => true, "price" => 1.23},
  {"property_id" => property_id, "value" => "2 x 4", "is_available" => true, "price" => 2.34}
],
scale.fetch("param") => scale.fetch("options").fetch("Inches")

)

# File lib/etsy/listing.rb, line 197
def add_variations(options)
  options[:variations] = JSON.dump(options.delete(:variations))
  options[:require_secure] = true
  self.class.post("/listings/#{id}/variations", options)
end
admirers(options = {}) click to toggle source

Return a list of users who have favorited this listing

# File lib/etsy/listing.rb, line 244
def admirers(options = {})
  options = options.merge(:access_token => token, :access_secret => secret) if (token && secret)
  favorite_listings = FavoriteListing.find_all_listings_favored_by(id, options)
  user_ids  = favorite_listings.map {|f| f.user_id }.uniq
  (user_ids.size > 0) ? Array(Etsy::User.find(user_ids, options)) : []
end
black_and_white?() click to toggle source
# File lib/etsy/listing.rb, line 209
def black_and_white?
  is_black_and_white
end
category() click to toggle source

Listing category name

# File lib/etsy/listing.rb, line 149
def category
  path = category_path.join('/')
  @category ||= Category.find(path)
end
created_at() click to toggle source

Time that this listing was created

# File lib/etsy/listing.rb, line 221
def created_at
  Time.at(created)
end
ending_at() click to toggle source

Time that this listing is ending (will be removed from store)

# File lib/etsy/listing.rb, line 238
def ending_at
  Time.at(ending)
end
image() click to toggle source

The primary image for this listing.

# File lib/etsy/listing.rb, line 143
def image
  images.first
end
images() click to toggle source

The collection of images associated with this listing.

# File lib/etsy/listing.rb, line 137
def images
  @images ||= listing_images
end
is_supply() click to toggle source
# File lib/etsy/listing.rb, line 251
def is_supply
  !!@result.fetch("is_supply")
end
modified_at() click to toggle source

Time that this listing was last modified

# File lib/etsy/listing.rb, line 232
def modified_at
  Time.at(modified)
end
original_created_at() click to toggle source

Time that this listing was originally created

# File lib/etsy/listing.rb, line 226
def original_created_at
  Time.at(original_created)
end
receipts() click to toggle source
# File lib/etsy/listing.rb, line 59
def receipts
  transactions.map{|t|t.receipt}
end
taxonomy_attributes(options={}) click to toggle source

Returns the taxonomy defined attributes for the listing

# File lib/etsy/listing.rb, line 156
def taxonomy_attributes(options={})
  options.merge!(:require_secure => true)
  self.class.get_all("/listings/#{id}/attributes", oauth.merge(options))
end
transactions() click to toggle source
# File lib/etsy/listing.rb, line 55
def transactions
  @transactions ||= Transaction.find_all_by_listing_id(id, oauth)
end
update_variations(options) click to toggle source
# File lib/etsy/listing.rb, line 203
def update_variations(options)
  options[:variations] = JSON.dump(options.delete(:variations))
  options[:require_secure] = true
  self.class.put("/listings/#{id}/variations", options)
end
variations(options={}) click to toggle source
# File lib/etsy/listing.rb, line 161
def variations(options={})
  options.merge!(:require_secure => true)
  self.class.get_all("/listings/#{id}/variations", oauth.merge(options))
end

Private Instance Methods

listing_images() click to toggle source
# File lib/etsy/listing.rb, line 301
def listing_images
  if result && result["Images"]
    result["Images"].map { |hash| Image.new(hash) }
  else
    Image.find_all_by_listing_id(id, oauth)
  end
end
oauth() click to toggle source
# File lib/etsy/listing.rb, line 297
def oauth
  oauth = (token && secret) ? {:access_token => token, :access_secret => secret} : {}
end