Class: Etsy::Listing

Inherits:
Object
  • Object
show all
Includes:
Model
Defined in:
lib/etsy/listing.rb

Overview

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)

Constant Summary collapse

STATES = 
%w(active removed sold_out expired alchemy)
VALID_STATES = 
[:active, :expired, :inactive, :sold, :featured, :draft, :sold_out]

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Model

included, #initialize, #result, #secret, #token

Class Method Details

.create(options = {}) ⇒ Object 



63
64
65
66
 
# File 'lib/etsy/listing.rb', line 63

def self.create(options = {})
  options.merge!(:require_secure => true)
  post("/listings", options)
end

.destroy(listing, options = {}) ⇒ Object 



73
74
75
76
 
# 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) ⇒ Object

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])



86
87
88
 
# 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 = {}) ⇒ Object

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)



130
131
132
133
 
# 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 = {}) ⇒ Object

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)

Raises:

  • (ArgumentError) 


106
107
108
109
110
111
112
113
114
115
116
 
# 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 = {}) ⇒ Object 



68
69
70
71
 
# File 'lib/etsy/listing.rb', line 68

def self.update(listing, options = {})
  options.merge!(:require_secure => true)
  put("/listings/#{listing.id}", options)
end

Instance Method Details

#add_variations(options) ⇒ Object

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")
)



197
198
199
200
201
 
# 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 = {}) ⇒ Object

Return a list of users who have favorited this listing



244
245
246
247
248
249
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


209
210
211
 
# File 'lib/etsy/listing.rb', line 209

def black_and_white?
  is_black_and_white
end

#category ⇒ Object

Listing category name



149
150
151
152
 
# File 'lib/etsy/listing.rb', line 149

def category
  path = category_path.join('/')
  @category ||= Category.find(path)
end

#created_at ⇒ Object

Time that this listing was created



221
222
223
 
# File 'lib/etsy/listing.rb', line 221

def created_at
  Time.at(created)
end

#ending_at ⇒ Object

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



238
239
240
 
# File 'lib/etsy/listing.rb', line 238

def ending_at
  Time.at(ending)
end

#image ⇒ Object

The primary image for this listing.



143
144
145
 
# File 'lib/etsy/listing.rb', line 143

def image
  images.first
end

#images ⇒ Object

The collection of images associated with this listing.



137
138
139
 
# File 'lib/etsy/listing.rb', line 137

def images
  @images ||= listing_images
end

#is_supply ⇒ Object 



251
252
253
 
# File 'lib/etsy/listing.rb', line 251

def is_supply
  !!@result.fetch("is_supply")
end

#modified_at ⇒ Object

Time that this listing was last modified



232
233
234
 
# File 'lib/etsy/listing.rb', line 232

def modified_at
  Time.at(modified)
end

#original_created_at ⇒ Object

Time that this listing was originally created



226
227
228
 
# File 'lib/etsy/listing.rb', line 226

def original_created_at
  Time.at(original_created)
end

#receipts ⇒ Object 



59
60
61
 
# File 'lib/etsy/listing.rb', line 59

def receipts
  transactions.map{|t|t.receipt}
end

#taxonomy_attributes(options = {}) ⇒ Object

Returns the taxonomy defined attributes for the listing



156
157
158
159
 
# 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 ⇒ Object 



55
56
57
 
# File 'lib/etsy/listing.rb', line 55

def transactions
  @transactions ||= Transaction.find_all_by_listing_id(id, oauth)
end

#update_variations(options) ⇒ Object 



203
204
205
206
207
 
# 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 = {}) ⇒ Object 



161
162
163
164
 
# 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