Our new data requirements in Open API v2 are here! For more information about the required fulfillment data, check out the Estimated Delivery Dates page.

API Documentation

Shop

Overview

Represents a shop with listings for sale.  Each shop is owned by one user.

Fields

Field Visibility Level Permission Scope Type Description
shop_id public none int The shop's numeric ID.
shop_name public none string The shop's name.
first_line private shops_rw string The first line of the shops address.
Deprecated: use UserAddress.first_line instead.
second_line private shops_rw string The second line of the shops address.
Deprecated: use UserAddress.second_line instead.
city private shops_rw string The city the shop is in.
Deprecated: use UserAddress.city instead.
state private shops_rw string The state the shop is in.
Deprecated: use UserAddress.state instead.
zip private shops_rw string The zip code the shop is in.
Deprecated: use UserAddress.zip instead.
country_id private shops_rw int The numeric ID of the country the shop is in.
Deprecated: use UserAddress.country_id instead.
user_id public none int The numeric ID of the user that owns this shop.
creation_tsz public none float The date and time the shop was created, in epoch seconds.
title public none string A brief heading for the shop's main page.
announcement public none string An announcement to buyers that displays on the shop's homepage.
currency_code public none string The ISO code (alphabetic) for the seller's native currency.
is_vacation public none boolean If the seller is not currently accepting purchases, 1, blank otherwise.
vacation_message public none string If is_vacation=1, a message to buyers.
sale_message public none string A message that is sent to users who buy from this shop.
digital_sale_message public none string A message that is sent to users who buy a digital item from this shop.
last_updated_tsz public none float The date and time the shop was last updated, in epoch seconds.
listing_active_count public none int The number of active listings in the shop.
digital_listing_count public none int Number of digital listings the shop has.
login_name public none string The user's login name.
lat private shops_rw float The latitude of the shop.
lon private shops_rw float The longitude of the shop.
accepts_custom_requests public none boolean True if the shop accepts requests for custom items.
policy_welcome public none string The introductory text from the top of the seller's policies page (may be blank).
policy_payment public none string The seller's policy on payment (may be blank).
policy_shipping public none string The seller's policy on shipping (may be blank).
policy_refunds public none string The seller's policy on refunds (may be blank).
policy_additional public none string Any additional policy information the seller provides (may be blank).
policy_seller_info public none string The shop's seller information (may be blank).
policy_updated_tsz public none float The date and time the shop was last updated, in epoch seconds.
policy_has_private_receipt_info public none boolean True if seller has private info to show in EU receipts
vacation_autoreply public none string If is_vacation=1, a message to buyers in response to new convos.
ga_code private shops_rw string The shop's Google Analytics code.
name private shops_rw string The shop owner's real name.
Deprecated: use UserAddress.name instead.
url public none string The URL of the shop
image_url_760x100 public none string The URL to the shop's banner image.
num_favorers public none int The number of members who've marked this Shop as a favorite
languages public none array(string) The languages that this Shop is enrolled in.
upcoming_local_event_id public none int the id of the next upcoming event this hops is attending, that is near the user.
icon_url_fullxfull public none string The url of the shop full-sized shop icon.
is_using_structured_policies public none boolean True if shop has accepted using structured policies.
has_onboarded_structured_policies public none boolean True if shop has viewed structured policies onboarding and accepted OR declined.
has_unstructured_policies public none boolean True if shop has any unstructured policy fields filled out.
policy_privacy public none string Privacy policy information the seller provides (may be blank).
use_new_inventory_endpoints private none boolean Should this user's listings be created or edited using the new Inventory endpoints?

Associations

Association Visibility Level Permission Scope Type Description
User public none User The user who owns this shop.
About public none ShopAbout Detailed data about this shop.
Sections public none array(ShopSection) An array of sections within the shop.  Each section holds listings.
Listings public none array(Listing) An array of listings within the shop.  (Must be used with scope "active", e.g.: Listings:active).

(NOTE: If calling on behalf of a shop owner in the context of listing management, you may include the parameter include_private=true to return private listings. This is an experimental feature and may change.)
Receipts private shops_rw array(Receipt) An array of receipts (one per buyer) for this shop.
Transactions private shops_rw array(Transaction) An array of transactions (sold items) for this shop.
Translations public none array(ShopTranslation) An array of translations for this Shop.
StructuredPolicies public none StructuredPolicies Association for structured policies.
SellerDetails public none SellerDetails Association for seller personal details.
FAQ public none array(FrequentlyAskedQuestion) Mocked association for frequently asked questions

Methods

findAllShops

Method Name findAllShops
Synopsis Finds all Shops. If there is a keywords parameter, finds shops with shop_name starting with keywords.
HTTP Method GET
URI /shops
Parameters
Name Required Default Type
shop_name N   string
limit N 25 int
offset N 0 int
page N   int
lat N   latitude
lon N   longitude
distance_max N 35 float
Requires OAuth N
Permission Scope none

getShop

Method Name getShop
Synopsis Retrieves a Shop by id.
HTTP Method GET
URI /shops/:shop_id
Parameters
Name Required Default Type
shop_id Y   array(shop_id_or_name)
Requires OAuth N
Permission Scope none

updateShop

Method Name updateShop
Synopsis Updates a Shop
HTTP Method PUT
URI /shops/:shop_id
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
title N   string
announcement N   text
sale_message N   text
policy_welcome N   text
policy_payment N   text
policy_shipping N   text
policy_refunds N   text
policy_additional N   text
policy_privacy N   text
policy_seller_info N   text
digital_sale_message N   text
Requires OAuth Y
Permission Scope shops_rw

uploadShopBanner

Method Name uploadShopBanner
Synopsis Upload a new shop banner image
HTTP Method POST
URI /shops/:shop_id/appearance/banner
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
image Y   imagefile
Requires OAuth Y
Permission Scope shops_rw

deleteShopBanner

Method Name deleteShopBanner
Synopsis Deletes a shop banner image
HTTP Method DELETE
URI /shops/:shop_id/appearance/banner
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
Requires OAuth Y
Permission Scope shops_rw

getListingShop

Method Name getListingShop
Synopsis Retrieves a shop by a listing id.
HTTP Method GET
URI /shops/listing/:listing_id
Parameters
Name Required Default Type
listing_id Y   int
Requires OAuth N
Permission Scope none

findAllUserShops

Method Name findAllUserShops
Synopsis Retrieves a set of Shop objects associated to a User.
HTTP Method GET
URI /users/:user_id/shops
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth N
Permission Scope none

Open API v3New

Your developer account