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
# File lib/etsy/listing.rb, line 59 def self.create(options = {}) options.merge!(:require_secure => true) post("/listings", options) end
# File lib/etsy/listing.rb, line 69 def self.destroy(listing, options = {}) options.merge!(:require_secure => true) delete("/listings/#{listing.id}", options) end
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 82 def self.find(*identifiers_and_options) find_one_or_more('listings', identifiers_and_options) end
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 126 def self.find_all_active_by_category(category, options = {}) options[:category] = category get_all("/listings/active", options) end
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 102 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
# File lib/etsy/listing.rb, line 64 def self.update(listing, options = {}) options.merge!(:require_secure => true) put("/listings/#{listing.id}", options) end
Private Class Methods
Find all listings that have been bought by a user
# File lib/etsy/listing.rb, line 281 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 listings favored by a user
# File lib/etsy/listing.rb, line 273 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
# File lib/etsy/listing.rb, line 257 def self.invalid_state_message(state) "The state '#{state}' is invalid. Must be one of #{VALID_STATES.join(', ')}" end
# File lib/etsy/listing.rb, line 261 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
# File lib/etsy/listing.rb, line 253 def self.valid?(state) VALID_STATES.include?(state) end
Public Instance Methods
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 193 def add_variations(options) options[:variations] = JSON.dump(options.delete(:variations)) options[:require_secure] = true self.class.post("/listings/#{id}/variations", options) end
Return a list of users who have favorited this listing
# File lib/etsy/listing.rb, line 240 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
# File lib/etsy/listing.rb, line 205 def black_and_white? is_black_and_white end
Listing
category name
# File lib/etsy/listing.rb, line 145 def category path = category_path.join('/') @category ||= Category.find(path) end
Time that this listing was created
# File lib/etsy/listing.rb, line 217 def created_at Time.at(created) end
Time that this listing is ending (will be removed from store)
# File lib/etsy/listing.rb, line 234 def ending_at Time.at(ending) end
The primary image for this listing.
# File lib/etsy/listing.rb, line 139 def image images.first end
The collection of images associated with this listing.
# File lib/etsy/listing.rb, line 133 def images @images ||= listing_images end
# File lib/etsy/listing.rb, line 247 def is_supply !!@result.fetch("is_supply") end
Time that this listing was last modified
# File lib/etsy/listing.rb, line 228 def modified_at Time.at(modified) end
Time that this listing was originally created
# File lib/etsy/listing.rb, line 222 def original_created_at Time.at(original_created) end
Returns the taxonomy defined attributes for the listing
# File lib/etsy/listing.rb, line 152 def taxonomy_attributes(options={}) options.merge!(:require_secure => true) self.class.get_all("/listings/#{id}/attributes", oauth.merge(options)) end
# File lib/etsy/listing.rb, line 55 def transactions @transactions ||= Transaction.find_all_by_listing_id(id, oauth) end
# File lib/etsy/listing.rb, line 199 def update_variations(options) options[:variations] = JSON.dump(options.delete(:variations)) options[:require_secure] = true self.class.put("/listings/#{id}/variations", options) end
# File lib/etsy/listing.rb, line 157 def variations(options={}) options.merge!(:require_secure => true) self.class.get_all("/listings/#{id}/variations", oauth.merge(options)) end
Private Instance Methods
# File lib/etsy/listing.rb, line 297 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
# File lib/etsy/listing.rb, line 293 def oauth oauth = (token && secret) ? {:access_token => token, :access_secret => secret} : {} end