Updates a shop. Assumes that all string parameters are provided in the shop''s primary language. Please note that the policy_additional field should only be set for shops located in the EU. Passing a value for this field for shops outside of the EU, will result in an error.'
tags:
- Shop
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
title:
type: string
description: A brief heading string for the shop's main page.
announcement:
type: string
description: An announcement string to buyers that displays on the shop's homepage.
sale_message:
type: string
description: A message string sent to users who complete a purchase from this shop.
digital_sale_message:
type: string
description: A message string sent to users who purchase a digital item from this shop.
policy_additional:
type: string
description: The shop's additional policies string (may be blank).
examples:
UpdateShopRequestExample:
summary: Default updateShop request
x-microcks-default: true
value:
title: example string
announcement: example string
sale_message: example string
digital_sale_message: example string
policy_additional: example string
responses:
'200':
description: A single Shop.
content:
application/json:
schema:
$ref: '#/components/schemas/Shop'
examples:
UpdateShop200Example:
summary: Default updateShop 200 response
x-microcks-default: true
value:
shop_id: 123456
user_id: 456789
shop_name: HandmadeCrafts
create_date: 1
created_timestamp: 1758153645
title: Handmade Ceramic Mug — Stoneware
announcement: example string
currency_code: USD
is_vacation: true
vacation_message: Thanks for your order! Shipping out tomorrow.
sale_message: Thanks for your order! Shipping out tomorrow.
digital_sale_message: Thanks for your order! Shipping out tomorrow.
update_date: 1
updated_timestamp: 1758153645
listing_active_count: 1
digital_listing_count: 1
login_name: handmade_seller
accepts_custom_requests: true
policy_welcome: example string
policy_payment: example string
policy_shipping: example string
policy_refunds: example string
policy_additional: example string
policy_seller_info: example string
policy_update_date: 1
policy_has_private_receipt_info: true
has_unstructured_policies: true
policy_privacy: example string
vacation_autoreply: example string
url: https://www.etsy.com/listing/123456789
image_url_760x100: https://www.etsy.com/listing/123456789
num_favorers: 1
languages:
- example string
icon_url_fullxfull: https://www.etsy.com/listing/123456789
is_using_structured_policies: true
has_onboarded_structured_policies: true
include_dispute_form_link: true
is_direct_checkout_onboarded: true
is_etsy_payments_onboarded: true
is_calculated_eligible: true
is_opted_in_to_buyer_promise: true
is_shop_us_based: true
transaction_sold_count: 1
shipping_from_country_iso: US
shop_location_country_iso: US
review_count: 1
review_average: 1.0
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShop400Example:
summary: Default updateShop 400 response
x-microcks-default: true
value:
error: example string
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShop403Example:
summary: Default updateShop 403 response
x-microcks-default: true
value:
error: example string
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShop404Example:
summary: Default updateShop 404 response
x-microcks-default: true
value:
error: example string
'401':
description: The request lacks valid authentication credentials. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShop401Example:
summary: Default updateShop 401 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShop500Example:
summary: Default updateShop 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- shops_r
- shops_w
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Update Shop
/v3/application/users/{user_id}/shops:
get:
operationId: getShopByOwnerUserId
description: '
Retrieves the shop identified by the shop owner''s user ID.'
tags:
- Shop
parameters:
- name: user_id
in: path
description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
required: true
schema:
type: integer
description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
format: int64
minimum: 1
example: 456789
responses:
'200':
description: A single Shop
content:
application/json:
schema:
$ref: '#/components/schemas/Shop'
examples:
GetShopByOwnerUserId200Example:
summary: Default getShopByOwnerUserId 200 response
x-microcks-default: true
value:
shop_id: 123456
user_id: 456789
shop_name: HandmadeCrafts
create_date: 1
created_timestamp: 1758153645
title: Handmade Ceramic Mug — Stoneware
announcement: example string
currency_code: USD
is_vacation: true
vacation_message: Thanks for your order! Shipping out tomorrow.
sale_message: Thanks for your order! Shipping out tomorrow.
digital_sale_message: Thanks for your order! Shipping out tomorrow.
update_date: 1
updated_timestamp: 1758153645
listing_active_count: 1
digital_listing_count: 1
login_name: handmade_seller
accepts_custom_requests: true
policy_welcome: example string
policy_payment: example string
policy_shipping: example string
policy_refunds: example string
policy_additional: example string
policy_seller_info: example string
policy_update_date: 1
policy_has_private_receipt_info: true
has_unstructured_policies: true
policy_privacy: example string
vacation_autoreply: example string
url: https://www.etsy.com/listing/123456789
image_url_760x100: https://www.etsy.com/listing/123456789
num_favorers: 1
languages:
- example string
icon_url_fullxfull: https://www.etsy.com/listing/123456789
is_using_structured_policies: true
has_onboarded_structured_policies: true
include_dispute_form_link: true
is_direct_checkout_onboarded: true
is_etsy_payments_onboarded: true
is_calculated_eligible: true
is_opted_in_to_buyer_promise: true
is_shop_us_based: true
transaction_sold_count: 1
shipping_from_country_iso: US
shop_location_country_iso: US
review_count: 1
review_average: 1.0
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopByOwnerUserId404Example:
summary: Default getShopByOwnerUserId 404 response
x-microcks-default: true
value:
error: example string
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopByOwnerUserId400Example:
summary: Default getShopByOwnerUserId 400 response
x-microcks-default: true
value:
error: example string
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopByOwnerUserId403Example:
summary: Default getShopByOwnerUserId 403 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopByOwnerUserId500Example:
summary: Default getShopByOwnerUserId 500 response
x-microcks-default: true
value:
error: example string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Shop by Owner User Id
/v3/application/shops:
get:
operationId: findShops
description: '
Open API V3 endpoint for searching shops by name. Note: We make every effort to ensure that frozen or removed shops are not included in the search results. However, rarely, due to timing issues, they may appear.'
tags:
- Shop
parameters:
- name: shop_name
in: query
description: The shop's name string.
required: true
schema:
type: string
description: The shop's name string.
example: HandmadeCrafts
- name: limit
in: query
description: The maximum number of results to return.
required: false
schema:
type: integer
description: The maximum number of results to return.
minimum: 1
maximum: 100
default: 25
example: 25
- name: offset
in: query
description: The number of records to skip before selecting the first result.
required: false
schema:
type: integer
description: The number of records to skip before selecting the first result.
minimum: 0
default: 0
example: 0
responses:
'200':
description: A list of Shops
content:
application/json:
schema:
$ref: '#/components/schemas/Shops'
examples:
FindShops200Example:
summary: Default findShops 200 response
x-microcks-default: true
value:
count: 1
results:
- null
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
FindShops500Example:
summary: Default findShops 500 response
x-microcks-default: true
value:
error: example string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Find Shops
components:
schemas:
ErrorSchema:
type: object
x-resource-id: ErrorSchema
required:
- error
properties:
error:
type: string
example: example string
Shop:
type: object
x-resource-id: Shop
description: A shop created by an Etsy user.
properties:
shop_id:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
user_id:
type: integer
description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
format: int64
minimum: 1
example: 456789
shop_name:
type: string
description: The shop's name string.
example: HandmadeCrafts
create_date:
type: integer
description: The date and time this shop was created, in epoch seconds.
minimum: 0
example: 1
created_timestamp:
type: integer
description: The date and time this shop was created, in epoch seconds.
minimum: 0
example: 1758153645
title:
type: string
description: A brief heading string for the shop's main page.
nullable: true
example: Handmade Ceramic Mug — Stoneware
announcement:
type: string
description: An announcement string to buyers that displays on the shop's homepage.
nullable: true
example: example string
currency_code:
type: string
description: The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.
example: USD
is_vacation:
type: boolean
description: When true, this shop is not accepting purchases.
example: true
vacation_message:
type: string
description: The shop's message string displayed when `is_vacation` is true.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
sale_message:
type: string
description: A message string sent to users who complete a purchase from this shop.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
digital_sale_message:
type: string
description: A message string sent to users who purchase a digital item from this shop.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
update_date:
type: integer
description: The date and time of the last update to the shop, in epoch seconds.
minimum: 0
example: 1
updated_timestamp:
type: integer
description: The date and time of the last update to the shop, in epoch seconds.
minimum: 0
example: 1758153645
listing_active_count:
type: integer
description: The number of active listings in the shop.
minimum: 0
example: 1
digital_listing_count:
type: integer
description: The number of digital listings in the shop.
minimum: 0
example: 1
login_name:
type: string
description: The shop owner's login name string.
example: handmade_seller
accepts_custom_requests:
type: boolean
description: When true, the shop accepts customization requests.
example: true
policy_welcome:
type: string
description: The shop's policy welcome string (may be blank).
nullable: true
example: example string
policy_payment:
type: string
description: The shop's payment policy string (may be blank).
nullable: true
example: example string
policy_shipping:
type: string
description: The shop's shipping policy string (may be blank).
nullable: true
example: example string
policy_refunds:
type: string
description: The shop's refund policy string (may be blank).
nullable: true
example: example string
policy_additional:
type: string
description: The shop's additional policies string (may be blank).
nullable: true
example: example string
policy_seller_info:
type: string
description: The shop's seller information string (may be blank).
nullable: true
example: example string
policy_update_date:
type: integer
description: The date and time of the last update to the shop's policies, in epoch seconds.
minimum: 0
example: 1
policy_has_private_receipt_info:
type: boolean
description: When true, EU receipts display private info.
example: true
has_unstructured_policies:
type: boolean
description: When true, the shop displays additional unstructured policy fields.
example: true
policy_privacy:
type: string
description: The shop's privacy policy string (may be blank).
nullable: true
example: example string
vacation_autoreply:
type: string
description: The shop's automatic reply string displayed in new conversations when `is_vacation` is true.
nullable: true
example: example string
url:
type: string
description: The URL string for this shop.
example: https://www.etsy.com/listing/123456789
image_url_760x100:
type: string
description: The URL string for this shop's banner image.
nullable: true
example: https://www.etsy.com/listing/123456789
num_favorers:
type: integer
description: The number of users who marked this shop a favorite.
minimum: 0
example: 1
languages:
type: array
description: A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.
items:
type: string
icon_url_fullxfull:
type: string
description: The URL string for this shop's icon image.
nullable: true
example: https://www.etsy.com/listing/123456789
is_using_structured_policies:
type: boolean
description: When true, the shop accepted using structured policies.
example: true
has_onboarded_structured_policies:
type: boolean
description: When true, the shop accepted OR declined after viewing structured policies onboarding.
example: true
include_dispute_form_link:
type: boolean
description: When true, this shop's policies include a link to an EU online dispute form.
example: true
is_direct_checkout_onboarded:
type: boolean
description: '(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.'
example: true
is_etsy_payments_onboarded:
type: boolean
description: When true, the shop has onboarded onto Etsy Payments.
example: true
is_calculated_eligible:
type: boolean
description: When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)
example: true
is_opted_in_to_buyer_promise:
type: boolean
description: When true, the shop opted in to buyer promise.
example: true
is_shop_us_based:
type: boolean
description: When true, the shop is based in the US.
example: true
transaction_sold_count:
type: integer
description: The total number of sales ([transactions](/documentation/reference#tag/Shop-Receipt-Transactions)) for this shop.
minimum: 0
example: 1
shipping_from_country_iso:
type: string
description: The country ISO the shop is shipping from.
format: ISO 3166-1 alpha-2
nullable: true
example: US
shop_location_country_iso:
type: string
description: The country ISO where the shop is located.
format: ISO 3166-1 alpha-2
nullable: true
example: US
review_count:
type: integer
description: Number of reviews of shop listings in the past year.
nullable: true
example: 1
review_average:
type: number
description: Average rating based on reviews of shop listings in the past year.
format: float
nullable: true
example: 1.0
Shops:
type: object
x-resource-id: Shops
description: A set of Shop records.
properties:
count:
type: integer
description: The total number of Shops
minimum: 0
example: 1
results:
type: array
description: The Shop resources.
items:
description: The Shop resources.
oneOf:
- $ref: '#/components/schemas/Shop'
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
description: Every request to a v3 API endpoint must include this data in the format `keystring:shared_secret`. Your keystring and shared secret are available on the [Your Apps](https://www.etsy.com/developers/your-apps) page.
oauth2:
type: oauth2
description: Open API v3 supports authenticating via OAuth 2.0. More information about Etsy's specific implementation of OAuth2 can be found [here](/documentation/essentials/oauth2).
flows:
authorizationCode:
authorizationUrl: https://www.etsy.com/oauth/connect
tokenUrl: https://openapi.etsy.com/v3/public/oauth/token
scopes:
address_r: see billing and shipping addresses
address_w: update billing and shipping addresses
billing_r: see all billing statement data
cart_r: read shopping carts
cart_w: add/remove from shopping carts
email_r: read a user profile
favorites_r: see private favorites
favorites_w: add/remove favorites
feedback_r: see purchase info in feedback
listings_d: delete listings
listings_r: see all listings (including expired etc)
listings_w: create/edit listings
profile_r: see all profile data
profile_w: update user profile, avatar, etc
recommend_r: see recommended listings
recommend_w: accept/reject recommended listings
shops_r: see private shop info
shops_w: update shop
transactions_r: see all checkout/payment data
transactions_w: update receipts
x-tagGroups:
- name: Listing Management
tags:
- BuyerTaxonomy
- SellerTaxonomy
- ShopListing
- ShopListing File
- ShopListing Image
- ShopListing Inventory
- ShopListing Offering
- ShopListing Personalization
- ShopListing Product
- ShopListing Translation
- ShopListing VariationImage
- ShopListing Video
- name: Other
tags:
- Other
- name: Payment Management
tags:
- Ledger Entry
- Payment
- name: Receipt Management
tags:
- Shop Receipt
- Shop Receipt Transactions
- name: Review Management
tags:
- Review
- name: Shipping Management
tags:
- Shop HolidayPreferences
- Shop ProcessingProfiles
- Shop ShippingProfile
- name: Shop Management
tags:
- Shop
- Shop ProductionPartner
- Shop Section
- name: Shop Policy Management
tags:
- Shop Return Policy
- name: User Management
tags:
- User
- UserAddress