{ "openapi": "3.0.2", "info": { "title": "Etsy Open API v3", "description": "

Etsy's Open API provides a simple RESTful interface for various Etsy.com features.

If you'd like to report an issue or provide feedback on the API design, please add an issue in Github.

© 2021-2025 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's API Developer Terms of Use.", "termsOfService": "https://www.etsy.com/legal/api", "contact": { "email": "developers@etsy.com" }, "version": "3.0.0" }, "servers": [ { "url": "https://openapi.etsy.com", "description": "Base URL for all Open API endpoints." } ], "security": [ { "api_key": [] } ], "tags": [ { "name": "User" }, { "name": "UserAddress" }, { "name": "Shop Receipt Transactions" }, { "name": "Other" }, { "name": "Shop" }, { "name": "Shop ShippingProfile" }, { "name": "Shop Section" }, { "name": "ShopListing" }, { "name": "Shop ProcessingProfiles" }, { "name": "Shop ProductionPartner" }, { "name": "Shop Return Policy" }, { "name": "Shop HolidayPreferences" }, { "name": "SellerTaxonomy" }, { "name": "Review" }, { "name": "Shop Receipt" }, { "name": "Payment" }, { "name": "Ledger Entry" }, { "name": "ShopListing Video" }, { "name": "ShopListing VariationImage" }, { "name": "ShopListing Translation" }, { "name": "ShopListing Inventory" }, { "name": "ShopListing Offering" }, { "name": "ShopListing Product" }, { "name": "ShopListing Image" }, { "name": "ShopListing File" }, { "name": "BuyerTaxonomy" } ], "x-tagGroups": [ { "name": "Listing Management", "tags": [ "BuyerTaxonomy", "SellerTaxonomy", "ShopListing", "ShopListing File", "ShopListing Image", "ShopListing Inventory", "ShopListing Offering", "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"] } ], "paths": { "/v3/application/buyer-taxonomy/nodes": { "get": { "operationId": "getBuyerTaxonomyNodes", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the full hierarchy tree of buyer taxonomy nodes.", "tags": ["BuyerTaxonomy"], "parameters": [], "responses": { "200": { "description": "List the full hierarchy tree of buyer taxonomy nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerTaxonomyNodes" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/buyer-taxonomy/nodes/{taxonomy_id}/properties": { "get": { "operationId": "getPropertiesByBuyerTaxonomyId", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of product properties, with applicable scales and values, supported for a specific buyer taxonomy ID.", "tags": ["BuyerTaxonomy"], "parameters": [ { "name": "taxonomy_id", "in": "path", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "required": true, "schema": { "type": "integer", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A list of product properties, with applicable scales and values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerTaxonomyNodeProperties" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings": { "post": { "operationId": "createDraftListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a physical draft [listing](/documentation/reference#tag/ShopListing) product in a shop on the Etsy channel.", "tags": ["ShopListing"], "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "quantity", "title", "description", "price", "who_made", "when_made", "taxonomy_id" ], "properties": { "quantity": { "type": "integer", "description": "The positive non-zero number of products available for purchase in the listing. Note: The listing quantity is the sum of available offering quantities. You can request the quantities for individual offerings from the ListingInventory resource using the [getListingInventory](/documentation/reference#operation/getListingInventory) endpoint." }, "title": { "type": "string", "description": "The listing's title string. When creating or updating a listing, valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{P}\\p{Sm}\\p{Zs}\u2122\u00a9\u00ae]/u) You can only use the %, :, & and + characters once each." }, "description": { "type": "string", "description": "A description string of the product for sale in the listing." }, "price": { "type": "number", "description": "The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The [`getListingInventory`](/documentation/reference/#operation/getListingInventory) method requests exact prices for available offerings.", "format": "float" }, "who_made": { "type": "string", "description": "An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.", "enum": [ "i_did", "someone_else", "collective" ] }, "when_made": { "type": "string", "description": "An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.", "enum": [ "made_to_order", "2020_2025", "2010_2019", "2006_2009", "before_2006", "2000_2005", "1990s", "1980s", "1970s", "1960s", "1950s", "1940s", "1930s", "1920s", "1910s", "1900s", "1800s", "1700s", "before_1700" ] }, "taxonomy_id": { "type": "integer", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "format": "int64", "minimum": 1 }, "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "nullable": true, "minimum": 1 }, "return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "nullable": true, "minimum": 1 }, "materials": { "type": "array", "description": "A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "nullable": true, "items": { "type": "string" } }, "shop_section_id": { "type": "integer", "description": "The numeric ID of the [shop section](/documentation/reference#tag/Shop-Section) for this listing. Default value is null.", "format": "int64", "nullable": true, "minimum": 1 }, "processing_min": { "type": "integer", "description": "The minimum number of days required to process this listing. Default value is null.", "nullable": true }, "processing_max": { "type": "integer", "description": "The maximum number of days required to process this listing. Default value is null.", "nullable": true }, "readiness_state_id": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "nullable": true, "minimum": 1 }, "tags": { "type": "array", "description": "A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}\\-'\u2122\u00a9\u00ae]/u) Default value is null.", "nullable": true, "items": { "type": "string" } }, "styles": { "type": "array", "description": "An array of style strings for this listing, each of which is free-form text string such as \"Formal\", or \"Steampunk\". When creating or updating a listing, the listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "nullable": true, "items": { "type": "string" } }, "item_weight": { "type": "number", "description": "The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_length": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_width": { "type": "number", "description": "The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_height": { "type": "number", "description": "The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_weight_unit": { "type": "string", "description": "A string defining the units used to measure the weight of the product. Default value is null.", "nullable": true, "enum": ["oz", "lb", "g", "kg"] }, "item_dimensions_unit": { "type": "string", "description": "A string defining the units used to measure the dimensions of the product. Default value is null.", "nullable": true, "enum": [ "in", "ft", "mm", "cm", "m", "yd", "inches" ] }, "is_personalizable": { "type": "boolean", "description": "When true, this listing is personalizable. The default value is null." }, "personalization_is_required": { "type": "boolean", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'." }, "personalization_char_count_max": { "type": "integer", "description": "This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'." }, "personalization_instructions": { "type": "string", "description": "A string representing instructions for the buyer to enter the personalization. Will only change if is_personalizable is 'true'." }, "production_partner_ids": { "type": "array", "description": "An array of unique IDs of production partner ids.", "nullable": true, "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "image_ids": { "type": "array", "description": "An array of numeric image IDs of the images in a listing, which can include up to 20 images.", "nullable": true, "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "is_supply": { "type": "boolean", "description": "When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'." }, "is_customizable": { "type": "boolean", "description": "When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders." }, "should_auto_renew": { "type": "boolean", "description": "When true, renews a listing for four months upon expiration." }, "is_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout." }, "type": { "type": "string", "description": "An enumerated type string that indicates whether the listing is physical or a digital download.", "enum": ["physical", "download", "both"] } } } } } }, "responses": { "201": { "description": "A single ShopListing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListing" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] }, "get": { "operationId": "getListingsByShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nEndpoint to list Listings that belong to a Shop. Listings can be filtered using the 'state' param.", "tags": ["ShopListing"], "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 } }, { "name": "state", "in": "query", "description": "When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.", "required": false, "schema": { "type": "string", "description": "When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.", "enum": [ "active", "inactive", "sold_out", "draft", "expired" ], "default": "active" } }, { "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 } }, { "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 } }, { "name": "sort_on", "in": "query", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "required": false, "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "enum": ["created", "price", "updated", "score"], "default": "created" } }, { "name": "sort_order", "in": "query", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "required": false, "schema": { "type": "string", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "enum": [ "asc", "ascending", "desc", "descending", "up", "down" ], "default": "desc" } }, { "name": "includes", "in": "query", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "required": false, "schema": { "type": "array", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "items": { "type": "string", "enum": [ "Shipping", "Images", "Shop", "User", "Translations", "Inventory", "Videos" ] }, "default": null } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of Listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingsWithAssociations" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] } }, "/v3/application/listings/{listing_id}": { "delete": { "operationId": "deleteListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to delete a ShopListing. A ShopListing can be deleted only if the state is one of the following: SOLD_OUT, DRAFT, EXPIRED, INACTIVE, ACTIVE and is_available or ACTIVE and has seller flags: SUPRESSED (frozen), VACATION, CUSTOM_SHOPS (pattern), SELL_ON_FACEBOOK", "tags": ["ShopListing"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "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" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "204": { "description": "The Listing resource was correctly deleted" }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_d"] } ] }, "get": { "operationId": "getListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a listing record by listing ID.", "tags": ["ShopListing"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "includes", "in": "query", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "required": false, "schema": { "type": "array", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "items": { "type": "string", "enum": [ "Shipping", "Images", "Shop", "User", "Translations", "Inventory", "Videos" ] }, "default": null } }, { "name": "language", "in": "query", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.", "required": false, "schema": { "type": "string", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.", "default": null } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } }, { "name": "allow_suggested_title", "in": "query", "description": "This parameter will include in the response a suggested title for the listing, if one is available. Since suggestions are only available to the listing's owner, client must submit an oauth_access_token scoped to the owner of the listing.", "required": false, "schema": { "type": "boolean", "description": "This parameter will include in the response a suggested title for the listing, if one is available. Since suggestions are only available to the listing's owner, client must submit an oauth_access_token scoped to the owner of the listing." } } ], "responses": { "200": { "description": "A single Listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingWithAssociations" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/files/{listing_file_id}": { "delete": { "operationId": "deleteListingFile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a file from a specific listing. When you delete the final file for a digital listing, the listing converts into a physical listing. The response to a delete request returns a list of the remaining file records associated with the given listing.", "tags": ["ShopListing File"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "listing_file_id", "in": "path", "description": "The unique numeric ID of a file associated with a digital listing.", "required": true, "schema": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "format": "int64", "minimum": 1 } } ], "responses": { "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "204": { "description": "The ShopListingFile resource was correctly deleted" }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] }, "get": { "operationId": "getListingFile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a single file associated with the given digital listing. Requesting a file from a physical listing returns an empty result.", "tags": ["ShopListing File"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "listing_file_id", "in": "path", "description": "The unique numeric ID of a file associated with a digital listing.", "required": true, "schema": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "The metatdata for a file associated with a digital listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingFile" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/files": { "get": { "operationId": "getAllListingFiles", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves all the files associated with the given digital listing. Requesting files from a physical listing returns an empty result.", "tags": ["ShopListing File"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "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 } } ], "responses": { "200": { "description": "A list of metadata objects for the file resources associated with a listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingFiles" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] }, "post": { "operationId": "uploadListingFile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUploads a new file for a digital listing, or associates an existing file with a specific listing. You must either provide the `listing_file_id` of an existing file, or the name and binary file data for a file to upload. Associating an existing file to a physical listing converts the physical listing into a digital listing, which removes all shipping costs and any product and inventory variations.", "tags": ["ShopListing File"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "listing_file_id": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "format": "int64", "minimum": 1 }, "file": { "type": "string", "description": "A binary file to upload.", "format": "binary", "nullable": true }, "name": { "type": "string", "description": "The file name string of a file to upload" }, "rank": { "type": "integer", "description": "The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.", "format": "int64", "minimum": 1, "default": 1 } } } } } }, "responses": { "201": { "description": "The metadata for a file associated with a digital listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingFile" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/active": { "get": { "operationId": "findAllListingsActive", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nA list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.", "tags": ["ShopListing"], "parameters": [ { "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 } }, { "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 } }, { "name": "keywords", "in": "query", "description": "Search term or phrase that must appear in all results.", "required": false, "schema": { "type": "string", "description": "Search term or phrase that must appear in all results.", "default": null } }, { "name": "sort_on", "in": "query", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "required": false, "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "enum": ["created", "price", "updated", "score"], "default": "created" } }, { "name": "sort_order", "in": "query", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "required": false, "schema": { "type": "string", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "enum": [ "asc", "ascending", "desc", "descending", "up", "down" ], "default": "desc" } }, { "name": "min_price", "in": "query", "description": "The minimum price of listings to be returned by a search result.", "required": false, "schema": { "type": "number", "description": "The minimum price of listings to be returned by a search result.", "format": "float", "default": null } }, { "name": "max_price", "in": "query", "description": "The maximum price of listings to be returned by a search result.", "required": false, "schema": { "type": "number", "description": "The maximum price of listings to be returned by a search result.", "format": "float", "default": null } }, { "name": "taxonomy_id", "in": "query", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "required": false, "schema": { "type": "integer", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "format": "int64", "minimum": 1, "default": null } }, { "name": "shop_location", "in": "query", "description": "Filters by shop location. If location cannot be parsed, Etsy responds with an error.", "required": false, "schema": { "type": "string", "description": "Filters by shop location. If location cannot be parsed, Etsy responds with an error.", "default": null } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/active": { "get": { "operationId": "findAllActiveListingsByShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.", "tags": ["ShopListing"], "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 } }, { "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 } }, { "name": "sort_on", "in": "query", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "required": false, "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "enum": ["created", "price", "updated", "score"], "default": "created" } }, { "name": "sort_order", "in": "query", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "required": false, "schema": { "type": "string", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "enum": [ "asc", "ascending", "desc", "descending", "up", "down" ], "default": "desc" } }, { "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 } }, { "name": "keywords", "in": "query", "description": "Search term or phrase that must appear in all results.", "required": false, "schema": { "type": "string", "description": "Search term or phrase that must appear in all results.", "default": null } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/images/{listing_image_id}": { "delete": { "operationId": "deleteListingImage", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to delete a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image; see uploadListingImage.", "tags": ["ShopListing Image"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "listing_image_id", "in": "path", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "204": { "description": "The ListingImage resource was correctly deleted" }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/{listing_id}/images/{listing_image_id}": { "get": { "operationId": "getListingImage", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the references and metadata for a listing image with a specific image ID.", "tags": ["ShopListing Image"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "listing_image_id", "in": "path", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single ListingImage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingImage" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/listings/{listing_id}/images": { "get": { "operationId": "getListingImages", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves all listing image resources for a listing with a specific listing ID.", "tags": ["ShopListing Image"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "An array of ListingImage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingImages" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/images": { "post": { "operationId": "uploadListingImage", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the `image` parameter. You can assign a previously deleted image to a listing using the deleted image's image ID in the `listing_image_id` parameter. When a request contains both `image` and `listing_image_id` parameter values, the endpoint uploads the image in the `image` parameter only. Note: When uploading a new image, data such as colors and size may return as null values due to asynchronous processing of the image. Use getListingImage endpoint to fetch these values.", "tags": ["ShopListing Image"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "The file name string of a file to upload", "format": "binary", "nullable": true }, "listing_image_id": { "type": "integer", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "format": "int64", "minimum": 1 }, "rank": { "type": "integer", "description": "The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.", "minimum": 0, "default": 1 }, "overwrite": { "type": "boolean", "description": "When true, this request replaces the existing image at a given rank.", "default": false }, "is_watermarked": { "type": "boolean", "description": "When true, indicates that the uploaded image has a watermark.", "default": false }, "alt_text": { "type": "string", "description": "Alt text for the listing image. Max length 500 characters.", "default": "" } } } } } }, "responses": { "201": { "description": "A single ListingImage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingImage" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/{listing_id}/inventory": { "get": { "operationId": "getListingInventory", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the inventory record for a listing. Listings you did not edit using the Etsy.com inventory tools have no inventory records. This endpoint returns SKU data if you are the owner of the inventory records being fetched.", "tags": ["ShopListing Inventory"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "show_deleted", "in": "query", "description": "A boolean value for inventory whether to include deleted products and their offerings. Default value is false.", "required": false, "schema": { "type": "boolean", "description": "A boolean value for inventory whether to include deleted products and their offerings. Default value is false." } }, { "name": "includes", "in": "query", "description": "An enumerated string that attaches a valid association. Default value is null.", "required": false, "schema": { "type": "string", "description": "An enumerated string that attaches a valid association. Default value is null.", "enum": ["Listing"] } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A single listing inventory record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingInventoryWithAssociations" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "422": { "description": "There was a problem processing your request. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] }, "put": { "operationId": "updateListingInventory", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product sku, offering quantity, and/or price are incompatible with values in `*_on_property_*` fields. When setting a price, assign a float equal to amount divided by divisor as specified in the Money resource.", "tags": ["ShopListing Inventory"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["products"], "properties": { "products": { "type": "array", "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.", "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "The SKU string for the product", "nullable": true }, "property_values": { "type": "array", "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "items": { "type": "object", "properties": { "property_id": { "type": "integer", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "format": "int64", "minimum": 1 }, "value_ids": { "type": "array", "description": "An array of unique IDs of multiple Etsy [listing property](/documentation/reference#operation/getListingProperties) values. For example, if your listing offers different sizes of a product, then the value ID list contains value IDs for each size.", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "scale_id": { "type": "integer", "description": "The numeric ID of a single Etsy.com measurement scale. For example, for shoe size, there are three `scale_id`s available - `UK`, `US/Canada`, and `EU`, where `US/Canada` has `scale_id` 19.", "format": "int64", "nullable": true, "minimum": 1 }, "property_name": { "type": "string", "description": "The name of the property, in the requested locale language." }, "values": { "type": "array", "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "items": { "type": "string" } } }, "required": [ "property_id", "value_ids", "values" ] } }, "offerings": { "type": "array", "description": "A list of product offering entries for this product.", "items": { "type": "object", "properties": { "price": { "type": "number", "description": "The price of the product.", "format": "float" }, "quantity": { "type": "integer", "description": "How many of this product are available?" }, "is_enabled": { "type": "boolean", "description": "True if the offering is shown to buyers" }, "readiness_state_id": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "nullable": true, "minimum": 1 } }, "required": [ "price", "quantity", "is_enabled", "readiness_state_id" ] } } }, "required": ["offerings"] } }, "price_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.", "items": { "type": "integer" } }, "quantity_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "sku_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "readiness_state_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.", "nullable": true, "items": { "type": "integer", "format": "int64", "minimum": 1 } } } } } } }, "responses": { "200": { "description": "A single listing's inventory record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingInventory" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/{listing_id}/inventory/products/{product_id}": { "get": { "operationId": "getListingProduct", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to retrieve a ListingProduct by ID.", "tags": ["ShopListing Product"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The listing to return a ListingProduct for.", "required": true, "schema": { "type": "integer", "description": "The listing to return a ListingProduct for.", "format": "int64", "minimum": 1 } }, { "name": "product_id", "in": "path", "description": "The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A single ListingInventoryProduct", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingInventoryProduct" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] } }, "/v3/application/listings/{listing_id}/products/{product_id}/offerings/{product_offering_id}": { "get": { "operationId": "getListingOffering", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet an Offering for a Listing", "tags": ["ShopListing Offering"], "parameters": [ { "name": "listing_id", "in": "path", "description": "", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "product_id", "in": "path", "description": "", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "product_offering_id", "in": "path", "description": "", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A single ListingInventoryProductOffering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingInventoryProductOffering" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/listings/batch": { "get": { "operationId": "getListingsByListingIds", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nAllows to query multiple listing ids at once. Limit 100 ids maximum per query.", "tags": ["ShopListing"], "parameters": [ { "name": "listing_ids", "in": "query", "description": "The list of numeric IDS for the listings in a specific Etsy shop.", "required": true, "schema": { "type": "array", "description": "The list of numeric IDS for the listings in a specific Etsy shop.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } }, { "name": "includes", "in": "query", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "required": false, "schema": { "type": "array", "description": "An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations' and 'Inventory'.", "items": { "type": "string", "enum": [ "Shipping", "Images", "Shop", "User", "Translations", "Inventory", "Videos" ] }, "default": null } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of Listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListingsWithAssociations" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/featured": { "get": { "operationId": "getFeaturedListingsByShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves Listings associated to a Shop that are featured.", "tags": ["ShopListing"], "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 } }, { "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 } }, { "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of Listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/properties/{property_id}": { "delete": { "operationId": "deleteListingProperty", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a property for a Listing.", "tags": ["ShopListing"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "property_id", "in": "path", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "required": true, "schema": { "type": "integer", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "The ListingProperty resource was correctly deleted" }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] }, "put": { "operationId": "updateListingProperty", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates or populates the properties list defining product offerings for a listing. Each offering requires both a `value` and a `value_id` that are valid for a `scale_id` assigned to the listing or that you assign to the listing with this request.", "tags": ["ShopListing"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "property_id", "in": "path", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "required": true, "schema": { "type": "integer", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["value_ids", "values"], "properties": { "value_ids": { "type": "array", "description": "An array of unique IDs of multiple Etsy [listing property](/documentation/reference#operation/getListingProperties) values. For example, if your listing offers different sizes of a product, then the value ID list contains value IDs for each size.", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "values": { "type": "array", "description": "An array of value strings for multiple Etsy [listing property](/documentation/reference#operation/getListingProperties) values. For example, if your listing offers different colored products, then the values array contains the color strings for each color. Note: parenthesis characters (`(` and `)`) are not allowed.", "items": { "type": "string" } }, "scale_id": { "type": "integer", "description": "The numeric ID of a single Etsy.com measurement scale. For example, for shoe size, there are three `scale_id`s available - `UK`, `US/Canada`, and `EU`, where `US/Canada` has `scale_id` 19.", "format": "int64", "minimum": 1 } } } } } }, "responses": { "200": { "description": "A single listing property.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingPropertyValue" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/{listing_id}/properties/{property_id}": { "get": { "operationId": "getListingProperty", "description": "
Feedback only Give feedback

Development for this endpoint is in progress. It will only return a 501 response.

\n\nRetrieves a listing's property", "tags": ["ShopListing"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "property_id", "in": "path", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "required": true, "schema": { "type": "integer", "description": "The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single ListingProperty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingPropertyValue" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "501": { "description": "This endpoint is not functional at this time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/properties": { "get": { "operationId": "getListingProperties", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet a listing's properties", "tags": ["ShopListing"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A Listing's Properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingPropertyValues" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/transactions": { "get": { "operationId": "getShopReceiptTransactionsByListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the list of transactions associated with a listing.", "tags": ["Shop Receipt Transactions"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "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 } }, { "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceiptTransactions" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language}": { "post": { "operationId": "createListingTranslation", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a ListingTranslation by listing_id and language", "tags": ["ShopListing Translation"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "language", "in": "path", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.", "required": true, "schema": { "type": "string", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["title", "description"], "properties": { "title": { "type": "string", "description": "The title of the Listing of this Translation." }, "description": { "type": "string", "description": "The description of the Listing of this Translation." }, "tags": { "type": "array", "description": "The tags of the Listing of this Translation.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "A single ListingTranslation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingTranslation" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] }, "get": { "operationId": "getListingTranslation", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet a Translation for a Listing in the given language", "tags": ["ShopListing Translation"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "language", "in": "path", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.", "required": true, "schema": { "type": "string", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`." } } ], "responses": { "200": { "description": "A single ListingTranslation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingTranslation" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } }, "put": { "operationId": "updateListingTranslation", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates a ListingTranslation by listing_id and language", "tags": ["ShopListing Translation"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "language", "in": "path", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.", "required": true, "schema": { "type": "string", "description": "The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["title", "description"], "properties": { "title": { "type": "string", "description": "The title of the Listing of this Translation." }, "description": { "type": "string", "description": "The description of the Listing of this Translation." }, "tags": { "type": "array", "description": "The tags of the Listing of this Translation.", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "A single ListingTranslation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingTranslation" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/shops/{shop_id}/listings/{listing_id}": { "patch": { "operationId": "updateListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates a listing, identified by a listing ID, for a specific shop identified by a shop ID. Note that this is a PATCH method type. When activating, or manually renewing a physical listing, the shipping profile referenced by the `shipping_profile_id`, and all of its fields, along with its entries and upgrades must be complete and valid. If the shipping profile is not complete and valid, we will throw an exception with an error message that guides the request sender to update whatever data is bad. Draft digital listings that are not made to order must have a file upload associated with it to be activated. If the listing is made to order, the file upload is not required.", "tags": ["ShopListing"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "image_ids": { "type": "array", "description": "An array of numeric image IDs of the images in a listing, which can include up to 20 images.", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "title": { "type": "string", "description": "The listing's title string. When creating or updating a listing, valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{P}\\p{Sm}\\p{Zs}\u2122\u00a9\u00ae]/u) You can only use the %, :, & and + characters once each." }, "description": { "type": "string", "description": "A description string of the product for sale in the listing." }, "materials": { "type": "array", "description": "A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "nullable": true, "items": { "type": "string" } }, "should_auto_renew": { "type": "boolean", "description": "When true, renews a listing for four months upon expiration." }, "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "nullable": true, "minimum": 1 }, "return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies). Required for active physical listings. This requirement does not apply to listings of EU-based shops.", "format": "int64", "nullable": true, "minimum": 1 }, "shop_section_id": { "type": "integer", "description": "The numeric ID of the [shop section](/documentation/reference#tag/Shop-Section) for this listing. Default value is null.", "nullable": true }, "item_weight": { "type": "number", "description": "The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_length": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_width": { "type": "number", "description": "The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_height": { "type": "number", "description": "The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true, "minimum": 0, "maximum": 1.79769313486e308 }, "item_weight_unit": { "type": "string", "description": "A string defining the units used to measure the weight of the product. Default value is null.", "nullable": true, "enum": ["", "oz", "lb", "g", "kg"] }, "item_dimensions_unit": { "type": "string", "description": "A string defining the units used to measure the dimensions of the product. Default value is null.", "nullable": true, "enum": [ "", "in", "ft", "mm", "cm", "m", "yd", "inches" ] }, "is_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout." }, "taxonomy_id": { "type": "integer", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "format": "int64", "minimum": 1 }, "tags": { "type": "array", "description": "A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}\\-'\u2122\u00a9\u00ae]/u) Default value is null.", "nullable": true, "items": { "type": "string" } }, "who_made": { "type": "string", "description": "An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.", "enum": [ "i_did", "someone_else", "collective" ] }, "when_made": { "type": "string", "description": "An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.", "enum": [ "made_to_order", "2020_2025", "2010_2019", "2006_2009", "before_2006", "2000_2005", "1990s", "1980s", "1970s", "1960s", "1950s", "1940s", "1930s", "1920s", "1910s", "1900s", "1800s", "1700s", "before_1700" ] }, "featured_rank": { "type": "integer", "description": "The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.", "nullable": true }, "is_personalizable": { "type": "boolean", "description": "When true, this listing is personalizable. The default value is null." }, "personalization_is_required": { "type": "boolean", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'." }, "personalization_char_count_max": { "type": "integer", "description": "This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'." }, "personalization_instructions": { "type": "string", "description": "A string representing instructions for the buyer to enter the personalization. Will only change if is_personalizable is 'true'." }, "state": { "type": "string", "description": "When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.", "enum": ["active", "inactive"] }, "is_supply": { "type": "boolean", "description": "When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'." }, "production_partner_ids": { "type": "array", "description": "An array of unique IDs of production partner ids.", "nullable": true, "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "type": { "type": "string", "description": "An enumerated type string that indicates whether the listing is physical or a digital download.", "nullable": true, "enum": ["physical", "download", "both"] } } } } } }, "responses": { "200": { "description": "A single ShopListing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListing" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/variation-images": { "get": { "operationId": "getListingVariationImages", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGets all variation images on a listing.", "tags": ["ShopListing VariationImage"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A list of ListingVariationImages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingVariationImages" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } }, "post": { "operationId": "updateVariationImages", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates variation images on a listing. `variation_images` is an array with inputs for the `property_id`, `value_id`, and `image_id` fields. `image_ids` are associated with a `ListingImage` on the listing associated with the provided `listing_id`. `property_id` and `value_id` pairs are associated with a `ListingProduct` on the listing associated with the provided `listing_id`. `variation_images` should not contain any duplicates. `variation_images` does not contain more than one `property_id` as variation images can only be associated on one property. The update overwrites all existing variation images on a listing, so if your request is successful, the variation images on the listing will be exactly those you specify. ", "tags": ["ShopListing VariationImage"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["variation_images"], "properties": { "variation_images": { "type": "array", "description": "A list of variation image data.", "items": { "type": "object", "properties": { "property_id": { "type": "integer", "format": "int64", "minimum": 1 }, "value_id": { "type": "integer", "format": "int64", "minimum": 1 }, "image_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "property_id", "value_id", "image_id" ] } } } } } } }, "responses": { "200": { "description": "A single ListingVariationImage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingVariationImages" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/videos/{video_id}": { "delete": { "operationId": "deleteListingVideo", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to delete a listing video. A copy of the video remains on our servers, and so a deleted video may be re-associated with the listing without re-uploading the original video; see uploadListingVideo.", "tags": ["ShopListing Video"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "video_id", "in": "path", "description": "The unique ID of a video associated with a listing.", "required": true, "schema": { "type": "integer", "description": "The unique ID of a video associated with a listing.", "format": "int64", "minimum": 1 } } ], "responses": { "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "204": { "description": "The ListingVideo resource was correctly deleted" }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/listings/{listing_id}/videos/{video_id}": { "get": { "operationId": "getListingVideo", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a single video associated with the given listing. Requesting a video from a listing returns an empty result.", "tags": ["ShopListing Video"], "parameters": [ { "name": "video_id", "in": "path", "description": "The unique ID of a video associated with a listing.", "required": true, "schema": { "type": "integer", "description": "The unique ID of a video associated with a listing.", "format": "int64", "minimum": 1 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "The metatdata for a video associated with a listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingVideo" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/listings/{listing_id}/videos": { "get": { "operationId": "getListingVideos", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves all listing video resources for a listing with a specific listing ID.", "tags": ["ShopListing Video"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A list of videos for a listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingVideos" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/listings/{listing_id}/videos": { "post": { "operationId": "uploadListingVideo", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUploads a new video for a listing, or associates an existing video with a specific listing. You must either provide the `video_id` of an existing video, or the name and binary file data for a video to upload.", "tags": ["ShopListing Video"], "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 } }, { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "video_id": { "type": "integer", "description": "The unique ID of a video associated with a listing.", "format": "int64", "minimum": 1 }, "video": { "type": "string", "description": "A video file to upload.", "format": "binary", "nullable": true }, "name": { "type": "string", "description": "The file name string for the video to upload." } } } } } }, "responses": { "201": { "description": "The metadata for a file associated with a digital listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingVideo" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_w"] } ] } }, "/v3/application/shops/{shop_id}/payment-account/ledger-entries/{ledger_entry_id}": { "get": { "operationId": "getShopPaymentAccountLedgerEntry", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet a single Shop Payment Account Ledger's Entry", "tags": ["Ledger Entry"], "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 } }, { "name": "ledger_entry_id", "in": "path", "description": "The unique ID of the shop owner ledger entry.", "required": true, "schema": { "type": "integer", "description": "The unique ID of the shop owner ledger entry.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single of PaymentAccountLedgerEntry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccountLedgerEntry" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/payment-account/ledger-entries": { "get": { "operationId": "getShopPaymentAccountLedgerEntries", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet a Shop Payment Account Ledger's Entries", "tags": ["Ledger Entry"], "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 } }, { "name": "min_created", "in": "query", "description": "The earliest unix timestamp for when a record was created.", "required": true, "schema": { "type": "integer", "description": "The earliest unix timestamp for when a record was created.", "minimum": 946684800 } }, { "name": "max_created", "in": "query", "description": "The latest unix timestamp for when a record was created.", "required": true, "schema": { "type": "integer", "description": "The latest unix timestamp for when a record was created.", "minimum": 946684800 } }, { "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 } }, { "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 } } ], "responses": { "200": { "description": "A list of PaymentAccountLedgerEntries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAccountLedgerEntries" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/payment-account/ledger-entries/payments": { "get": { "operationId": "getPaymentAccountLedgerEntryPayments", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGet a Payment from a PaymentAccount Ledger Entry ID, if applicable", "tags": ["Payment"], "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 } }, { "name": "ledger_entry_ids", "in": "query", "description": "", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 1 } } } ], "responses": { "200": { "description": "A list of Payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payments" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/receipts/{receipt_id}/payments": { "get": { "operationId": "getShopPaymentByReceiptId", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a payment from a specific receipt, identified by `receipt_id`, from a specific shop, identified by `shop_id`", "tags": ["Payment"], "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 } }, { "name": "receipt_id", "in": "path", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payments" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/payments": { "get": { "operationId": "getPayments", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of payments from a shop identified by `shop_id`. You can also filter results using a list of payment IDs.", "tags": ["Payment"], "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 } }, { "name": "payment_ids", "in": "query", "description": "A comma-separated array of Payment IDs numbers.", "required": true, "schema": { "type": "array", "description": "A comma-separated array of Payment IDs numbers.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } } ], "responses": { "200": { "description": "A list of payments from a specific shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payments" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/openapi-ping": { "get": { "operationId": "ping", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCheck to confirm connectivity to the Etsy API with an application", "tags": ["Other"], "parameters": [], "responses": { "200": { "description": "A confirmation that the current application has access to the Open API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pong" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "App does not have the proper permissions to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/receipts/{receipt_id}": { "get": { "operationId": "getShopReceipt", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy", "tags": ["Shop Receipt"], "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 } }, { "name": "receipt_id", "in": "path", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A single Shop Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceipt" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] }, "put": { "operationId": "updateShopReceipt", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates the status of a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy", "tags": ["Shop Receipt"], "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 } }, { "name": "receipt_id", "in": "path", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "was_shipped": { "type": "boolean", "description": "When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.", "nullable": true }, "was_paid": { "type": "boolean", "description": "When `true`, returns receipts where the seller has recieved payment for the receipt. When `false`, returns receipts where payment has not been received.", "nullable": true } } } } } }, "responses": { "200": { "description": "Update A Shop Receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceipt" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_w"] } ] } }, "/v3/application/shops/{shop_id}/receipts": { "get": { "operationId": "getShopReceipts", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRequests the Shop Receipts from a specific Shop, unfiltered or filtered by receipt id range or offset, date, paid, and/or shipped purchases. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy", "tags": ["Shop Receipt"], "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 } }, { "name": "min_created", "in": "query", "description": "The earliest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The earliest unix timestamp for when a record was created.", "minimum": 946684800, "default": null } }, { "name": "max_created", "in": "query", "description": "The latest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The latest unix timestamp for when a record was created.", "minimum": 946684800, "default": null } }, { "name": "min_last_modified", "in": "query", "description": "The earliest unix timestamp for when a record last changed.", "required": false, "schema": { "type": "integer", "description": "The earliest unix timestamp for when a record last changed.", "minimum": 946684800, "default": null } }, { "name": "max_last_modified", "in": "query", "description": "The latest unix timestamp for when a record last changed.", "required": false, "schema": { "type": "integer", "description": "The latest unix timestamp for when a record last changed.", "minimum": 946684800, "default": null } }, { "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 } }, { "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 } }, { "name": "sort_on", "in": "query", "description": "The value to sort a search result of listings on.", "required": false, "schema": { "type": "string", "description": "The value to sort a search result of listings on.", "enum": ["created", "updated", "receipt_id"], "default": "created" } }, { "name": "sort_order", "in": "query", "description": "The ascending(up) or descending(down) order to sort receipts by.", "required": false, "schema": { "type": "string", "description": "The ascending(up) or descending(down) order to sort receipts by.", "enum": [ "asc", "ascending", "desc", "descending", "up", "down" ], "default": "desc" } }, { "name": "was_paid", "in": "query", "description": "When `true`, returns receipts where the seller has recieved payment for the receipt. When `false`, returns receipts where payment has not been received.", "required": false, "schema": { "type": "boolean", "description": "When `true`, returns receipts where the seller has recieved payment for the receipt. When `false`, returns receipts where payment has not been received.", "nullable": true } }, { "name": "was_shipped", "in": "query", "description": "When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.", "required": false, "schema": { "type": "boolean", "description": "When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.", "nullable": true } }, { "name": "was_delivered", "in": "query", "description": "When `true`, returns receipts that have been marked as delivered. When `false`, returns receipts where shipment has not been marked as delivered.", "required": false, "schema": { "type": "boolean", "description": "When `true`, returns receipts that have been marked as delivered. When `false`, returns receipts where shipment has not been marked as delivered.", "nullable": true } }, { "name": "was_canceled", "in": "query", "description": "When `true`, the endpoint will only return the canceled receipts. When `false`, the endpoint will only return non-canceled receipts.", "required": false, "schema": { "type": "boolean", "description": "When `true`, the endpoint will only return the canceled receipts. When `false`, the endpoint will only return non-canceled receipts.", "nullable": true } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of Shop Receipts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceipts" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/receipts/{receipt_id}/listings": { "get": { "operationId": "getListingsByShopReceipt", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGets all listings associated with a receipt.", "tags": ["ShopListing"], "parameters": [ { "name": "receipt_id", "in": "path", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "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 } }, { "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 } }, { "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A set of ShopListing resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking": { "post": { "operationId": "createReceiptShipment", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nSubmits tracking information for a Shop Receipt, which creates a Shop Receipt Shipment entry for the given receipt_id. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send_bcc is true, Etsy sends shipping notifications to the seller as well. When tracking_code and carrier_name aren't sent, the receipt is marked as shipped only. If the carrier is not supported, you may use `other` as the carrier name so you can provide the tracking code. **NOTES** When shipping within the United States AND the order is over $10 _or_ when shipping to India, tracking code and carrier name ARE required. Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy", "tags": ["Shop Receipt"], "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 } }, { "name": "receipt_id", "in": "path", "description": "The receipt to submit tracking for.", "required": true, "schema": { "type": "integer", "description": "The receipt to submit tracking for.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "tracking_code": { "type": "string", "description": "The tracking code for this receipt." }, "carrier_name": { "type": "string", "description": "The carrier name for this receipt." }, "send_bcc": { "type": "boolean", "description": "If true, the shipping notification will be sent to the seller as well" }, "note_to_buyer": { "type": "string", "description": "Message to include in notification to the buyer." } } } } } }, "responses": { "200": { "description": "A single ShopReceipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceipt" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_w"] } ] } }, "/v3/application/shops/{shop_id}/receipts/{receipt_id}/transactions": { "get": { "operationId": "getShopReceiptTransactionsByReceipt", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the list of transactions associated with a specific receipt.", "tags": ["Shop Receipt Transactions"], "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 } }, { "name": "receipt_id", "in": "path", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceiptTransactions" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/listings/{listing_id}/reviews": { "get": { "operationId": "getReviewsByListing", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 to retrieve the reviews for a listing given its ID.", "tags": ["Review"], "parameters": [ { "name": "listing_id", "in": "path", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "required": true, "schema": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 } }, { "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 } }, { "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 } }, { "name": "min_created", "in": "query", "description": "The earliest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The earliest unix timestamp for when a record was created.", "nullable": true, "minimum": 946684800 } }, { "name": "max_created", "in": "query", "description": "The latest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The latest unix timestamp for when a record was created.", "nullable": true, "minimum": 946684800 } } ], "responses": { "200": { "description": "A set of Transaction Reviews by Listing ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingReviews" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/reviews": { "get": { "operationId": "getReviewsByShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 to retrieve the reviews from a shop given its ID.", "tags": ["Review"], "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 } }, { "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 } }, { "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 } }, { "name": "min_created", "in": "query", "description": "The earliest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The earliest unix timestamp for when a record was created.", "nullable": true, "minimum": 946684800 } }, { "name": "max_created", "in": "query", "description": "The latest unix timestamp for when a record was created.", "required": false, "schema": { "type": "integer", "description": "The latest unix timestamp for when a record was created.", "nullable": true, "minimum": 946684800 } } ], "responses": { "200": { "description": "A set of Transaction Reviews By Shop ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionReviews" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/seller-taxonomy/nodes": { "get": { "operationId": "getSellerTaxonomyNodes", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the full hierarchy tree of seller taxonomy nodes.", "tags": ["SellerTaxonomy"], "parameters": [], "responses": { "200": { "description": "List the full hierarchy tree of seller taxonomy nodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerTaxonomyNodes" } } } }, "503": { "description": "The service is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/seller-taxonomy/nodes/{taxonomy_id}/properties": { "get": { "operationId": "getPropertiesByTaxonomyId", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of product properties, with applicable scales and values, supported for a specific seller taxonomy ID.", "tags": ["SellerTaxonomy"], "parameters": [ { "name": "taxonomy_id", "in": "path", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "required": true, "schema": { "type": "integer", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A list of product properties, with applicable scales and values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyNodeProperties" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shipping-carriers": { "get": { "operationId": "getShippingCarriers", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of available shipping carriers and the mail classes associated with them for a given country", "tags": ["Shop ShippingProfile"], "parameters": [ { "name": "origin_country_iso", "in": "query", "description": "The ISO code of the country from which the listing ships.", "required": true, "schema": { "type": "string", "description": "The ISO code of the country from which the listing ships.", "format": "ISO 3166-1 alpha-2" } } ], "responses": { "200": { "description": "A set of ShippingCarriers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingCarriers" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}": { "get": { "operationId": "getShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the shop identified by a specific shop ID.", "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 } } ], "responses": { "200": { "description": "A single Shop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } }, "put": { "operationId": "updateShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates 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 } } ], "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)." } } } } } }, "responses": { "200": { "description": "A single Shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r", "shops_w"] } ] } }, "/v3/application/users/{user_id}/shops": { "get": { "operationId": "getShopByOwnerUserId", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves 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 } } ], "responses": { "200": { "description": "A single Shop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shop" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/holiday-preferences": { "get": { "operationId": "getHolidayPreferences", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of holidays that are available to a shop to set a preference for. Currently only supported in the US and CA", "tags": ["Shop HolidayPreferences"], "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 } } ], "responses": { "200": { "description": "A list of holiday preferences", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShopHolidayPreference" } } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/holiday-preferences/{holiday_id}": { "put": { "operationId": "updateHolidayPreferences", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates the preference for whether the seller will process orders or not on the holiday. Currently only supported in the US and CA", "tags": ["Shop HolidayPreferences"], "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 } }, { "name": "holiday_id", "in": "path", "description": "The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info", "required": true, "schema": { "type": "integer", "description": "The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105 ] } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["is_working"], "properties": { "is_working": { "type": "boolean", "description": "A boolean value for whether the shop will process orders on a particular holiday." } } } } } }, "responses": { "200": { "description": "The updated holiday preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopHolidayPreference" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops": { "get": { "operationId": "findShops", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen 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." } }, { "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 } }, { "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 } } ], "responses": { "200": { "description": "A list of Shops", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shops" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/policies/return/consolidate": { "post": { "operationId": "consolidateShopReturnPolicies", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nConsolidates Return Policies by moving all listings from a source return policy to a destination return policy, and deleting the source return policy. This is commonly used in the event that a user attempts to update a Return Policy such that its data is a duplicate of some other Return Policy, which is prevented.", "tags": ["Shop Return Policy"], "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 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "source_return_policy_id", "destination_return_policy_id" ], "properties": { "source_return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 }, "destination_return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 } } } } } }, "responses": { "200": { "description": "The updated target Return Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReturnPolicy" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/policies/return": { "post": { "operationId": "createShopReturnPolicy", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new Return Policy. Note: if either accepts_returns or accepts_exchanges is true, then a return_deadline is required.", "tags": ["Shop Return Policy"], "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 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "accepts_returns", "accepts_exchanges" ], "properties": { "accepts_returns": { "type": "boolean" }, "accepts_exchanges": { "type": "boolean" }, "return_deadline": { "type": "integer", "description": "The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].", "nullable": true } } } } } }, "responses": { "200": { "description": "A single Return Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReturnPolicy" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopReturnPolicies", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nReturns a shop's list of existing Return Policies", "tags": ["Shop Return Policy"], "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 } } ], "responses": { "200": { "description": "List of shop's Return Policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReturnPolicies" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/policies/return/{return_policy_id}": { "delete": { "operationId": "deleteShopReturnPolicy", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes an existing Return Policy. Deletion is only allowed for policies which have no associated listings \u2013 move them to another policy before attempting deletion.", "tags": ["Shop Return Policy"], "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 } }, { "name": "return_policy_id", "in": "path", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "The Return Policy was successfully deleted." }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopReturnPolicy", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves an existing Return Policy.", "tags": ["Shop Return Policy"], "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 } }, { "name": "return_policy_id", "in": "path", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single Return Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReturnPolicy" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] }, "put": { "operationId": "updateShopReturnPolicy", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates an existing Return Policy. Note: if either accepts_returns or accepts_exchanges is true, then a return_deadline is required.", "tags": ["Shop Return Policy"], "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 } }, { "name": "return_policy_id", "in": "path", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "accepts_returns", "accepts_exchanges" ], "properties": { "accepts_returns": { "type": "boolean" }, "accepts_exchanges": { "type": "boolean" }, "return_deadline": { "type": "integer", "description": "The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].", "nullable": true } } } } } }, "responses": { "200": { "description": "An updated Return Policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReturnPolicy" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/policies/return/{return_policy_id}/listings": { "get": { "operationId": "getListingsByShopReturnPolicy", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nGets all listings associated with a Return Policy.", "tags": ["ShopListing"], "parameters": [ { "name": "return_policy_id", "in": "path", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 } }, { "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A set of ShopListing resources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["listings_r"] } ] } }, "/v3/application/shops/{shop_id}/production-partners": { "get": { "operationId": "getShopProductionPartners", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of production partners available in the specific Etsy shop identified by its shop ID.", "tags": ["Shop ProductionPartner"], "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 } } ], "responses": { "200": { "description": "A list of shop production partners", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopProductionPartners" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/readiness-state-definitions": { "post": { "operationId": "createShopReadinessStateDefinition", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new ReadinessStateDefinition. If an existing definition matches the input values, this endpoint will throw a Conflict error, please refer to the Content-Location header to obtain the get endpoint url for the values of the existing definition. Does not affect the product offering-readiness states definition relationship.", "tags": ["Shop ProcessingProfiles"], "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 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "readiness_state", "min_processing_time", "max_processing_time" ], "properties": { "readiness_state": { "type": "string", "description": "The readiness state of a product: \\\"1\\\" means \\\"ready_to_ship\\\", and \\\"2\\\" means \\\"made_to_order\\\"", "enum": ["ready_to_ship", "made_to_order"] }, "min_processing_time": { "type": "integer", "description": "The minimum number of days or weeks for processing a specific product.", "minimum": 1, "maximum": 10 }, "max_processing_time": { "type": "integer", "description": "The maximum number of days or weeks for processing a specific product.", "minimum": 1, "maximum": 10 }, "processing_time_unit": { "type": "string", "description": "The unit used to represent how long a processing time is. A week is equivalent to how many days the seller works per week as stated in their processing schedule. If none is provided, the unit is set to \\\"days\\\".", "enum": ["days", "weeks"], "default": "days" } } } } } }, "responses": { "201": { "description": "A single ReadinessStateDefinition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopProcessingProfile" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopReadinessStateDefinitions", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of ProcessingProfiles available in the specific Etsy shop identified by its shop ID.", "tags": ["Shop ProcessingProfiles"], "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 } }, { "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 } }, { "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 } } ], "responses": { "200": { "description": "A list of ProcessingProfiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopProcessingProfiles" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/readiness-state-definitions/{readiness_state_definition_id}": { "delete": { "operationId": "deleteShopReadinessStateDefinition", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a ReadinessStateDefinition by given readiness state definition ID. If there any active offerings linked to the definition, this endpoint will throw a Bad Request error. If you want to delete a ReadinessStateDefinition that is linked to active offerings, you must link the offerings to a different readiness state definition.", "tags": ["Shop ProcessingProfiles"], "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 } }, { "name": "readiness_state_definition_id", "in": "path", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "minimum": 1 } } ], "responses": { "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "204": { "description": "The ReadinessStateDefinition was successfully deleted" }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopReadinessStateDefinition", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a ProcessingProfile referenced by readiness state definition ID.", "tags": ["Shop ProcessingProfiles"], "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 } }, { "name": "readiness_state_definition_id", "in": "path", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single ProcessingProfile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopProcessingProfile" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] }, "put": { "operationId": "updateShopReadinessStateDefinition", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates an existing ReadinessStateDefinition. If an existing definition matches the input values, this endpoint will throw a Conflict error, please refer to the Content-Location header to obtain the get endpoint url for the values of the existing definition. Does not affect the product offering-readiness states definition relationship.", "tags": ["Shop ProcessingProfiles"], "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 } }, { "name": "readiness_state_definition_id", "in": "path", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "readiness_state": { "type": "string", "description": "The readiness state of a product: \\\"1\\\" means \\\"ready_to_ship\\\", and \\\"2\\\" means \\\"made_to_order\\\"", "enum": ["ready_to_ship", "made_to_order"] }, "min_processing_time": { "type": "integer", "description": "The minimum number of days or weeks for processing a specific product.", "minimum": 1, "maximum": 10 }, "max_processing_time": { "type": "integer", "description": "The maximum number of days or weeks for processing a specific product.", "minimum": 1, "maximum": 10 }, "processing_time_unit": { "type": "string", "description": "The unit used to represent how long a processing time is. A week is equivalent to how many days the seller works per week as stated in their processing schedule. If none is provided, the unit is set to \\\"days\\\".", "enum": ["days", "weeks"], "default": "days" } } } } } }, "responses": { "200": { "description": "The updated ReadinessStateDefinition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopProcessingProfile" } } } }, "409": { "description": "There was a request conflict with the current state of the target resource. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/sections": { "post": { "operationId": "createShopSection", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new section in a specific shop.", "tags": ["Shop Section"], "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 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "description": "The title string for a shop section." } } } } } }, "responses": { "200": { "description": "A Shop Section resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopSection" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopSections", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the list of shop sections in a specific shop identified by shop ID.", "tags": ["Shop Section"], "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 } } ], "responses": { "200": { "description": "A list of shop sections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopSections" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/sections/{shop_section_id}": { "delete": { "operationId": "deleteShopSection", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a section in a specific shop given a valid shop_section_id.", "tags": ["Shop Section"], "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 } }, { "name": "shop_section_id", "in": "path", "description": "The numeric ID of a section in a specific Etsy shop.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "The shop section resource was correctly deleted" }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopSection", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a shop section, referenced by section ID and shop ID.", "tags": ["Shop Section"], "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 } }, { "name": "shop_section_id", "in": "path", "description": "The numeric ID of a section in a specific Etsy shop.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A shop section resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopSection" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } }, "put": { "operationId": "updateShopSection", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates a section in a specific shop given a valid shop_section_id.", "tags": ["Shop Section"], "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 } }, { "name": "shop_section_id", "in": "path", "description": "The numeric ID of a section in a specific Etsy shop.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "description": "The title string for a shop section." } } } } } }, "responses": { "200": { "description": "A Shop Section resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopSection" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/shop-sections/listings": { "get": { "operationId": "getListingsByShopSectionId", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves all the listings from the section of a specific shop.", "tags": ["ShopListing"], "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 } }, { "name": "shop_section_ids", "in": "query", "description": "A list of numeric IDS for all sections in a specific Etsy shop.", "required": true, "schema": { "type": "array", "description": "A list of numeric IDS for all sections in a specific Etsy shop.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } }, { "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 } }, { "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 } }, { "name": "sort_on", "in": "query", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "required": false, "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.", "enum": ["created", "price", "updated", "score"], "default": "created" } }, { "name": "sort_order", "in": "query", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "required": false, "schema": { "type": "string", "description": "The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).", "enum": [ "asc", "ascending", "desc", "descending", "up", "down" ], "default": "desc" } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of listings from a shop section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopListings" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/shipping-profiles": { "post": { "operationId": "createShopShippingProfile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new ShippingProfile. You can pass a country iso code or a region when creating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.", "tags": ["Shop ShippingProfile"], "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 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "title", "origin_country_iso", "primary_cost", "secondary_cost" ], "properties": { "title": { "type": "string", "description": "The name string of this shipping profile." }, "origin_country_iso": { "type": "string", "description": "The ISO code of the country from which the listing ships.", "format": "ISO 3166-1 alpha-2" }, "primary_cost": { "type": "number", "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float", "minimum": 0 }, "secondary_cost": { "type": "number", "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float", "minimum": 0 }, "min_processing_time": { "type": "integer", "description": "The minimum time required to process to ship listings with this shipping profile.", "minimum": 1, "maximum": 10 }, "max_processing_time": { "type": "integer", "description": "The maximum processing time the listing needs to ship.", "minimum": 1, "maximum": 10 }, "processing_time_unit": { "type": "string", "description": "The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to \"business_days\".", "enum": ["business_days", "weeks"], "default": "business_days" }, "destination_country_iso": { "type": "string", "description": "The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.", "format": "ISO 3166-1 alpha-2", "default": null }, "destination_region": { "type": "string", "description": "The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If `none`, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.", "enum": ["eu", "non_eu", "none"], "default": "none" }, "origin_postal_code": { "type": "string", "description": "The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info", "default": "" }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "minimum": 0, "default": 0 }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "default": null }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null } } } } } }, "responses": { "200": { "description": "A single ShippingProfile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfile" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopShippingProfiles", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.", "tags": ["Shop ShippingProfile"], "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 } } ], "responses": { "200": { "description": "A list of shipping profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfiles" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}": { "delete": { "operationId": "deleteShopShippingProfile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a ShippingProfile by given id.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "responses": { "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "204": { "description": "The ShopShippingProfile resource was correctly deleted" }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopShippingProfile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a Shipping Profile referenced by shipping profile ID.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single ShippingProfile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfile" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] }, "put": { "operationId": "updateShopShippingProfile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nChanges the settings in a shipping profile. You can pass a country iso code or a region when updating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The name string of this shipping profile." }, "origin_country_iso": { "type": "string", "description": "The ISO code of the country from which the listing ships.", "format": "ISO 3166-1 alpha-2" }, "min_processing_time": { "type": "integer", "description": "The minimum time required to process to ship listings with this shipping profile.", "minimum": 1, "maximum": 10 }, "max_processing_time": { "type": "integer", "description": "The maximum processing time the listing needs to ship.", "minimum": 1, "maximum": 10 }, "processing_time_unit": { "type": "string", "description": "The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to \"business_days\".", "enum": ["business_days", "weeks"], "default": "business_days" }, "origin_postal_code": { "type": "string", "description": "The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info", "default": null } } } } } }, "responses": { "200": { "description": "The updated shipping profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfile" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}/destinations": { "post": { "operationId": "createShopShippingProfileDestination", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new shipping destination, which sets the shipping cost, carrier, and class for a destination in a [shipping profile](/documentation/reference/#tag/Shop-ShippingProfile). createShopShippingProfileDestination assigns costs using the currency of the associated shop. Set the destination using either `destination_country_iso` or `destination_region`; `destination_country_iso` and `destination_region` are mutually exclusive \u2014 set one or the other. Setting both triggers error 400. If the request sets neither `destination_country_iso` nor `destination_region`, the default destination is \"everywhere\". You must also either assign both a `shipping_carrier_id` AND `mail_class` or both `min_delivery_days` AND `max_delivery_days`.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["primary_cost", "secondary_cost"], "properties": { "primary_cost": { "type": "number", "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float", "minimum": 0 }, "secondary_cost": { "type": "number", "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float", "minimum": 0 }, "destination_country_iso": { "type": "string", "description": "The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.", "format": "ISO 3166-1 alpha-2", "default": null }, "destination_region": { "type": "string", "description": "The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If `none`, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.", "enum": ["eu", "non_eu", "none"], "default": "none" }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "minimum": 0, "default": 0 }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "default": null }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null } } } } } }, "responses": { "201": { "description": "A single shipping destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileDestination" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopShippingProfileDestinationsByShippingProfile", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a list of shipping destination objects associated with a shipping profile.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } }, { "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 } }, { "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 } } ], "responses": { "200": { "description": "A list of shipping destination objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileDestinations" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}/destinations/{shipping_profile_destination_id}": { "delete": { "operationId": "deleteShopShippingProfileDestination", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a shipping destination and removes the destination option from every listing that uses the associated shipping profile. A shipping profile requires at least one shipping destination, so this endpoint cannot delete the final shipping destination for any shipping profile. To delete the final shipping destination from a shipping profile, you must [delete the entire shipping profile](/documentation/reference/#operation/deleteShopShippingProfile).", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } }, { "name": "shipping_profile_destination_id", "in": "path", "description": "The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "Etsy deleted the shipping profile destination." }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "put": { "operationId": "updateShopShippingProfileDestination", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates an existing shipping destination, which can set or reassign the shipping cost, carrier, and class for a destination.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } }, { "name": "shipping_profile_destination_id", "in": "path", "description": "The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "primary_cost": { "type": "number", "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float", "minimum": 0, "default": null }, "secondary_cost": { "type": "number", "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float", "minimum": 0, "default": null }, "destination_country_iso": { "type": "string", "description": "The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.", "format": "ISO 3166-1 alpha-2", "default": null }, "destination_region": { "type": "string", "description": "The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If `none`, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.", "enum": ["eu", "non_eu", "none"], "default": "none" }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "minimum": 0, "default": null }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "default": null }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null } } } } } }, "responses": { "200": { "description": "A single shipping destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileDestination" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}/upgrades": { "post": { "operationId": "createShopShippingProfileUpgrade", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCreates a new shipping profile upgrade, which can establish a price for a shipping option, such as an alternate carrier or faster delivery.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "type", "upgrade_name", "price", "secondary_price" ], "properties": { "type": { "type": "integer", "description": "The type of the shipping upgrade. Domestic (0) or international (1).", "enum": [0, 1] }, "upgrade_name": { "type": "string", "description": "Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority." }, "price": { "type": "number", "description": "Additional cost of adding the shipping upgrade.", "format": "float", "minimum": 0 }, "secondary_price": { "type": "number", "description": "Additional cost of adding the shipping upgrade for each additional item.", "format": "float", "minimum": 0 }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "minimum": 0, "default": 0 }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "default": null }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null } } } } } }, "responses": { "200": { "description": "A single shipping profile upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileUpgrade" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "get": { "operationId": "getShopShippingProfileUpgrades", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the list of shipping profile upgrades assigned to a specific shipping profile.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A list of shipping profile upgrades.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileUpgrades" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } }, "/v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}/upgrades/{upgrade_id}": { "delete": { "operationId": "deleteShopShippingProfileUpgrade", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nDeletes a shipping profile upgrade and removes the upgrade option from every listing that uses the associated shipping profile.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the shipping profile.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the shipping profile.", "format": "int64", "minimum": 1 } }, { "name": "upgrade_id", "in": "path", "description": "The numeric ID that is associated with a shipping upgrade", "required": true, "schema": { "type": "integer", "description": "The numeric ID that is associated with a shipping upgrade", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "Etsy deleted the shipping profile upgrade." }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] }, "put": { "operationId": "updateShopShippingProfileUpgrade", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nUpdates a shipping profile upgrade and updates any listings that use the shipping profile.", "tags": ["Shop ShippingProfile"], "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 } }, { "name": "shipping_profile_id", "in": "path", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "minimum": 1 } }, { "name": "upgrade_id", "in": "path", "description": "The numeric ID that is associated with a shipping upgrade", "required": true, "schema": { "type": "integer", "description": "The numeric ID that is associated with a shipping upgrade", "format": "int64", "minimum": 1 } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "upgrade_name": { "type": "string", "description": "Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.", "default": null }, "type": { "type": "integer", "description": "The type of the shipping upgrade. Domestic (0) or international (1).", "enum": [0, 1] }, "price": { "type": "number", "description": "Additional cost of adding the shipping upgrade.", "format": "float", "minimum": 0, "default": null }, "secondary_price": { "type": "number", "description": "Additional cost of adding the shipping upgrade for each additional item.", "format": "float", "minimum": 0, "default": null }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "minimum": 0, "default": null }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "default": null }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "minimum": 1, "maximum": 45, "default": null } } } } } }, "responses": { "200": { "description": "A single shipping profile upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopShippingProfileUpgrade" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "503": { "description": "This function is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_w"] } ] } }, "/v3/application/scopes": { "post": { "operationId": "tokenScopes", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nCheck the scopes of the provided token", "tags": ["Other"], "parameters": [], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "A confirmation that the current application has access to the Open API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scopes" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } } } }, "/v3/application/shops/{shop_id}/transactions/{transaction_id}": { "get": { "operationId": "getShopReceiptTransaction", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a transaction by transaction ID.", "tags": ["Shop Receipt Transactions"], "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 } }, { "name": "transaction_id", "in": "path", "description": "The unique numeric ID for a transaction.", "required": true, "schema": { "type": "integer", "description": "The unique numeric ID for a transaction.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceiptTransaction" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "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" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/shops/{shop_id}/transactions": { "get": { "operationId": "getShopReceiptTransactionsByShop", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves the list of transactions associated with a shop.", "tags": ["Shop Receipt Transactions"], "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 } }, { "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 } }, { "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 } }, { "name": "legacy", "in": "query", "description": "This parameter needed to enable new parameters and response values related to processing profiles.", "required": false, "schema": { "type": "boolean", "description": "This parameter needed to enable new parameters and response values related to processing profiles." } } ], "responses": { "200": { "description": "A list of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopReceiptTransactions" } } } }, "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" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["transactions_r"] } ] } }, "/v3/application/user/addresses/{user_address_id}": { "delete": { "operationId": "deleteUserAddress", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to delete a UserAddress for a User.", "tags": ["UserAddress"], "parameters": [ { "name": "user_address_id", "in": "path", "description": "The numeric ID of the user's address.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the user's address.", "format": "int64", "minimum": 1 } } ], "responses": { "204": { "description": "The User Address resource was correctly deleted" }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["address_r"] } ] }, "get": { "operationId": "getUserAddress", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to retrieve a UserAddress for a User.", "tags": ["UserAddress"], "parameters": [ { "name": "user_address_id", "in": "path", "description": "The numeric ID of the user's address.", "required": true, "schema": { "type": "integer", "description": "The numeric ID of the user's address.", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single UserAddress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAddress" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["address_r"] } ] } }, "/v3/application/user/addresses": { "get": { "operationId": "getUserAddresses", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nOpen API V3 endpoint to retrieve UserAddresses for a User.", "tags": ["UserAddress"], "parameters": [ { "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 } }, { "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 } } ], "responses": { "200": { "description": "A list of UserAddress records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAddresses" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["address_r"] } ] } }, "/v3/application/users/{user_id}": { "get": { "operationId": "getUser", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nRetrieves a user profile based on a unique user ID. Access is limited to profiles of the authenticated user or linked buyers. For the primary_email field, specific app-based permissions are required and granted case-by-case.", "tags": ["User"], "parameters": [ { "name": "user_id", "in": "path", "description": "", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "responses": { "200": { "description": "A single User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["email_r"] } ] } }, "/v3/application/users/me": { "get": { "operationId": "getMe", "description": "
General ReleaseReport bug

This endpoint is ready for production use.

\n\nReturns basic info for the user making the request.", "tags": ["User"], "parameters": [], "responses": { "200": { "description": "Fetches basic info about the requesting user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Self" } } } }, "404": { "description": "A resource could not be found. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "400": { "description": "There was a problem with the request data. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "401": { "description": "The request lacks valid authentication credentials. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorSchema" } } } } }, "security": [ { "api_key": [], "oauth2": ["shops_r"] } ] } } }, "components": { "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "Every request to a v3 API endpoint must include this data, with your application's API key as the value." }, "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" } } } } }, "schemas": { "TypeDiscriminator": { "type": "object", "required": ["__type"], "properties": { "__type": { "type": "string", "description": "field used to determine the type of the object when deserializing union type responses" } } }, "BuyerTaxonomyNodes": { "type": "object", "x-resource-id": "BuyerTaxonomyNodes", "description": "A list of taxonomy nodes from the buyer taxonomy tree.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyNode" } ] } } } }, "BuyerTaxonomyNode": { "type": "object", "x-resource-id": "BuyerTaxonomyNode", "description": "A taxonomy node in the buyer taxonomy tree.", "properties": { "id": { "type": "integer", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "format": "int64", "minimum": 1 }, "level": { "type": "integer", "description": "The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.", "minimum": 0 }, "name": { "type": "string", "description": "The name string for this taxonomy node." }, "parent_id": { "type": "integer", "description": "The numeric taxonomy ID of the parent of this node.", "format": "int64", "nullable": true, "minimum": 1, "default": null }, "children": { "type": "array", "description": "An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.", "items": { "description": "An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyNode" } ] } }, "full_path_taxonomy_ids": { "type": "array", "description": "An array of `taxonomy_id`s including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } } }, "ErrorSchema": { "type": "object", "x-resource-id": "ErrorSchema", "required": ["error"], "properties": { "error": { "type": "string" } } }, "BuyerTaxonomyNodeProperties": { "type": "object", "x-resource-id": "BuyerTaxonomyNodeProperties", "description": "A list of product property definitions.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyNodeProperty" } ] } } } }, "BuyerTaxonomyNodeProperty": { "type": "object", "x-resource-id": "BuyerTaxonomyNodeProperty", "description": "A product property definition.", "properties": { "property_id": { "type": "integer", "description": "The unique numeric ID of this product property.", "format": "int64", "minimum": 1 }, "name": { "type": "string", "description": "The name string for this taxonomy node." }, "display_name": { "type": "string", "description": "The human-readable product property name string." }, "scales": { "type": "array", "description": "A list of available scales.", "items": { "description": "A list of available scales.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyPropertyScale" } ] } }, "is_required": { "type": "boolean", "description": "When true, listings assigned eligible taxonomy IDs require this property." }, "supports_attributes": { "type": "boolean", "description": "When true, you can use this property in listing attributes." }, "supports_variations": { "type": "boolean", "description": "When true, you can use this property in listing variations." }, "is_multivalued": { "type": "boolean", "description": "When true, you can assign multiple property values to this property" }, "max_values_allowed": { "type": "integer", "description": "When true, you can assign multiple property values to this property", "nullable": true }, "possible_values": { "type": "array", "description": "A list of supported property value strings for this property.", "items": { "description": "A list of supported property value strings for this property.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyPropertyValue" } ] } }, "selected_values": { "type": "array", "description": "A list of property value strings automatically and always selected for the given property.", "items": { "description": "A list of property value strings automatically and always selected for the given property.", "allOf": [ { "$ref": "#/components/schemas/BuyerTaxonomyPropertyValue" } ] } } } }, "BuyerTaxonomyPropertyScale": { "type": "object", "x-resource-id": "BuyerTaxonomyPropertyScale", "description": "A scale defnining the assignable increments for the property values available to specific product properties.", "properties": { "scale_id": { "type": "integer", "description": "The unique numeric ID of a scale.", "format": "int64", "minimum": 1 }, "display_name": { "type": "string", "description": "The name string for a scale." }, "description": { "type": "string", "description": "The description string for a scale." } } }, "BuyerTaxonomyPropertyValue": { "type": "object", "x-resource-id": "BuyerTaxonomyPropertyValue", "description": "A property value for a specific product property, which may also employ a specific scale.", "properties": { "value_id": { "type": "integer", "description": "The numeric ID of this property value.", "format": "int64", "nullable": true, "minimum": 1 }, "name": { "type": "string", "description": "The name string of this property value." }, "scale_id": { "type": "integer", "description": "The numeric scale ID of the scale to which this property value belongs.", "format": "int64", "nullable": true, "minimum": 1 }, "equal_to": { "type": "array", "description": "A list of numeric property value IDs this property value is equal to (if any).", "items": { "type": "integer", "minimum": 0 } } } }, "ShopListing": { "type": "object", "x-resource-id": "ShopListing", "description": "A listing from a shop, which contains a product quantity, title, description, price, etc.", "properties": { "listing_id": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 }, "user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) posting the listing.", "format": "int64", "minimum": 1 }, "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "title": { "type": "string", "description": "The listing's title string. When creating or updating a listing, valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{P}\\p{Sm}\\p{Zs}\u2122\u00a9\u00ae]/u) You can only use the %, :, & and + characters once each." }, "description": { "type": "string", "description": "A description string of the product for sale in the listing." }, "state": { "type": "string", "description": "When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.", "enum": [ "active", "inactive", "sold_out", "draft", "expired" ] }, "creation_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "ending_timestamp": { "type": "integer", "description": "The listing's expiration time, in epoch seconds.", "minimum": 946684800 }, "original_creation_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "last_modified_timestamp": { "type": "integer", "description": "The time of the last update to the listing, in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The time of the last update to the listing, in epoch seconds.", "minimum": 946684800 }, "state_timestamp": { "type": "integer", "description": "The date and time of the last state change of this listing.", "nullable": true, "minimum": 946684800 }, "quantity": { "type": "integer", "description": "The positive non-zero number of products available for purchase in the listing. Note: The listing quantity is the sum of available offering quantities. You can request the quantities for individual offerings from the ListingInventory resource using the [getListingInventory](/documentation/reference#operation/getListingInventory) endpoint.", "minimum": 0 }, "shop_section_id": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "nullable": true, "minimum": 1 }, "featured_rank": { "type": "integer", "description": "The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page." }, "url": { "type": "string", "description": "The full URL to the listing's page on Etsy." }, "num_favorers": { "type": "integer", "description": "The number of users who marked this Listing a favorite.", "minimum": 0 }, "non_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates do not apply to this listing at checkout." }, "is_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout." }, "is_customizable": { "type": "boolean", "description": "When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders." }, "is_personalizable": { "type": "boolean", "description": "When true, this listing is personalizable. The default value is null." }, "personalization_is_required": { "type": "boolean", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'." }, "personalization_char_count_max": { "type": "integer", "description": "This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'.", "nullable": true }, "personalization_instructions": { "type": "string", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'.", "nullable": true }, "listing_type": { "type": "string", "description": "An enumerated type string that indicates whether the listing is physical or a digital download.", "enum": ["physical", "download", "both"] }, "tags": { "type": "array", "description": "A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}\\-'\u2122\u00a9\u00ae]/u) Default value is null.", "items": { "type": "string" } }, "materials": { "type": "array", "description": "A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "items": { "type": "string" } }, "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "nullable": true, "minimum": 1 }, "return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "nullable": true, "minimum": 1 }, "processing_min": { "type": "integer", "description": "The minimum number of days required to process this listing. Default value is null.", "nullable": true, "minimum": 0 }, "processing_max": { "type": "integer", "description": "The maximum number of days required to process this listing. Default value is null.", "nullable": true, "minimum": 0 }, "who_made": { "type": "string", "description": "An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.", "nullable": true, "enum": ["i_did", "someone_else", "collective"] }, "when_made": { "type": "string", "description": "An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.", "nullable": true, "enum": [ "made_to_order", "2020_2025", "2010_2019", "2006_2009", "before_2006", "2000_2005", "1990s", "1980s", "1970s", "1960s", "1950s", "1940s", "1930s", "1920s", "1910s", "1900s", "1800s", "1700s", "before_1700" ] }, "is_supply": { "type": "boolean", "description": "When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.", "nullable": true }, "item_weight": { "type": "number", "description": "The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_weight_unit": { "type": "string", "description": "A string defining the units used to measure the weight of the product. Default value is null.", "nullable": true, "enum": ["oz", "lb", "g", "kg"] }, "item_length": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_width": { "type": "number", "description": "The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_height": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_dimensions_unit": { "type": "string", "description": "A string defining the units used to measure the dimensions of the product. Default value is null.", "nullable": true, "enum": ["in", "ft", "mm", "cm", "m", "yd", "inches"] }, "is_private": { "type": "boolean", "description": "When true, this is a private listing intended for a specific buyer and hidden from shop view." }, "style": { "type": "array", "description": "An array of style strings for this listing, each of which is free-form text string such as \"Formal\", or \"Steampunk\". When creating or updating a listing, the listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "items": { "type": "string" } }, "file_data": { "type": "string", "description": "A string describing the files attached to a digital listing." }, "has_variations": { "type": "boolean", "description": "When true, the listing has variations." }, "should_auto_renew": { "type": "boolean", "description": "When true, renews a listing for four months upon expiration." }, "language": { "type": "string", "description": "The IETF language tag for the default language of the listing. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ru`.", "nullable": true }, "price": { "description": "The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The [`getListingInventory`](/documentation/reference/#operation/getListingInventory) method requests exact prices for available offerings.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "taxonomy_id": { "type": "integer", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "nullable": true }, "readiness_state_id": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "nullable": true, "minimum": 1 }, "suggested_title": { "type": "string", "description": "A title string suggested by Etsy. Only available for a user's own listings, when allow_suggested_title param is present, and when a shop's language setting is English. Not all listings will have suggestions.", "nullable": true } } }, "Money": { "type": "object", "x-resource-id": "Money", "description": "A representation of an amount of money.", "properties": { "amount": { "type": "integer", "description": "The amount of represented by this data." }, "divisor": { "type": "integer", "description": "The divisor to render the amount.", "minimum": 0 }, "currency_code": { "type": "string", "description": "The ISO currency code for this data." } } }, "ShopListingFile": { "type": "object", "x-resource-id": "ShopListingFile", "description": "A file associated with a digital listing.", "properties": { "listing_file_id": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "format": "int64", "minimum": 1 }, "listing_id": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 }, "rank": { "type": "integer", "description": "The numeric index of the display order position of this file in the listing, starting at 1.", "minimum": 0 }, "filename": { "type": "string", "description": "The file name string for a file associated with a digital listing." }, "filesize": { "type": "string", "description": "A human-readable format size string for the size of a file." }, "size_bytes": { "type": "integer", "description": "A number indicating the size of a file, measured in bytes.", "minimum": 0 }, "filetype": { "type": "string", "description": "A type string indicating a file's MIME type." }, "create_timestamp": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The unique numeric ID of a file associated with a digital listing.", "minimum": 946684800 } } }, "ShopListingFiles": { "type": "object", "x-resource-id": "ShopListingFiles", "description": "Represents several ShopListingFiles.", "properties": { "count": { "type": "integer", "description": "The number of ShopListingFiles being returned..", "minimum": 0 }, "results": { "type": "array", "description": "An array of ShopListingFile resources.", "items": { "description": "An array of ShopListingFile resources.", "allOf": [ { "$ref": "#/components/schemas/ShopListingFile" } ] } } } }, "ShopListings": { "type": "object", "x-resource-id": "ShopListings", "description": "A set of ShopListing resources.", "properties": { "count": { "type": "integer", "description": "The number of ShopListing resources found.", "minimum": 0 }, "results": { "type": "array", "description": "The ShopListing resources found.", "items": { "description": "The ShopListing resources found.", "allOf": [ { "$ref": "#/components/schemas/ShopListing" } ] } } } }, "ShopListingWithAssociations": { "type": "object", "x-resource-id": "ShopListingWithAssociations", "description": "A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.", "properties": { "listing_id": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 }, "user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) posting the listing.", "format": "int64", "minimum": 1 }, "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "title": { "type": "string", "description": "The listing's title string. When creating or updating a listing, valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{P}\\p{Sm}\\p{Zs}\u2122\u00a9\u00ae]/u) You can only use the %, :, & and + characters once each." }, "description": { "type": "string", "description": "A description string of the product for sale in the listing." }, "state": { "type": "string", "description": "When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.", "enum": [ "active", "inactive", "sold_out", "draft", "expired" ] }, "creation_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "ending_timestamp": { "type": "integer", "description": "The listing's expiration time, in epoch seconds.", "minimum": 946684800 }, "original_creation_timestamp": { "type": "integer", "description": "The listing's creation time, in epoch seconds.", "minimum": 946684800 }, "last_modified_timestamp": { "type": "integer", "description": "The time of the last update to the listing, in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The time of the last update to the listing, in epoch seconds.", "minimum": 946684800 }, "state_timestamp": { "type": "integer", "description": "The date and time of the last state change of this listing.", "nullable": true, "minimum": 946684800 }, "quantity": { "type": "integer", "description": "The positive non-zero number of products available for purchase in the listing. Note: The listing quantity is the sum of available offering quantities. You can request the quantities for individual offerings from the ListingInventory resource using the [getListingInventory](/documentation/reference#operation/getListingInventory) endpoint.", "minimum": 0 }, "shop_section_id": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "nullable": true, "minimum": 1 }, "featured_rank": { "type": "integer", "description": "The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page." }, "url": { "type": "string", "description": "The full URL to the listing's page on Etsy." }, "num_favorers": { "type": "integer", "description": "The number of users who marked this Listing a favorite.", "minimum": 0 }, "non_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates do not apply to this listing at checkout." }, "is_taxable": { "type": "boolean", "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout." }, "is_customizable": { "type": "boolean", "description": "When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders." }, "is_personalizable": { "type": "boolean", "description": "When true, this listing is personalizable. The default value is null." }, "personalization_is_required": { "type": "boolean", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'." }, "personalization_char_count_max": { "type": "integer", "description": "This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'.", "nullable": true }, "personalization_instructions": { "type": "string", "description": "When true, this listing requires personalization. The default value is null. Will only change if is_personalizable is 'true'.", "nullable": true }, "listing_type": { "type": "string", "description": "An enumerated type string that indicates whether the listing is physical or a digital download.", "enum": ["physical", "download", "both"] }, "tags": { "type": "array", "description": "A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', \u2122, \u00a9, and \u00ae. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}\\-'\u2122\u00a9\u00ae]/u) Default value is null.", "items": { "type": "string" } }, "materials": { "type": "array", "description": "A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "items": { "type": "string" } }, "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.", "format": "int64", "nullable": true, "minimum": 1 }, "return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "nullable": true, "minimum": 1 }, "processing_min": { "type": "integer", "description": "The minimum number of days required to process this listing. Default value is null.", "nullable": true, "minimum": 0 }, "processing_max": { "type": "integer", "description": "The maximum number of days required to process this listing. Default value is null.", "nullable": true, "minimum": 0 }, "who_made": { "type": "string", "description": "An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.", "nullable": true, "enum": ["i_did", "someone_else", "collective"] }, "when_made": { "type": "string", "description": "An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.", "nullable": true, "enum": [ "made_to_order", "2020_2025", "2010_2019", "2006_2009", "before_2006", "2000_2005", "1990s", "1980s", "1970s", "1960s", "1950s", "1940s", "1930s", "1920s", "1910s", "1900s", "1800s", "1700s", "before_1700" ] }, "is_supply": { "type": "boolean", "description": "When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.", "nullable": true }, "item_weight": { "type": "number", "description": "The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_weight_unit": { "type": "string", "description": "A string defining the units used to measure the weight of the product. Default value is null.", "nullable": true, "enum": ["oz", "lb", "g", "kg"] }, "item_length": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_width": { "type": "number", "description": "The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_height": { "type": "number", "description": "The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.", "format": "float", "nullable": true }, "item_dimensions_unit": { "type": "string", "description": "A string defining the units used to measure the dimensions of the product. Default value is null.", "nullable": true, "enum": ["in", "ft", "mm", "cm", "m", "yd", "inches"] }, "is_private": { "type": "boolean", "description": "When true, this is a private listing intended for a specific buyer and hidden from shop view." }, "style": { "type": "array", "description": "An array of style strings for this listing, each of which is free-form text string such as \"Formal\", or \"Steampunk\". When creating or updating a listing, the listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}]/u) Default value is null.", "items": { "type": "string" } }, "file_data": { "type": "string", "description": "A string describing the files attached to a digital listing." }, "has_variations": { "type": "boolean", "description": "When true, the listing has variations." }, "should_auto_renew": { "type": "boolean", "description": "When true, renews a listing for four months upon expiration." }, "language": { "type": "string", "description": "The IETF language tag for the default language of the listing. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ru`.", "nullable": true }, "price": { "description": "The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The [`getListingInventory`](/documentation/reference/#operation/getListingInventory) method requests exact prices for available offerings.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "taxonomy_id": { "type": "integer", "description": "The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.", "nullable": true }, "readiness_state_id": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "nullable": true, "minimum": 1 }, "suggested_title": { "type": "string", "description": "A title string suggested by Etsy. Only available for a user's own listings, when allow_suggested_title param is present, and when a shop's language setting is English. Not all listings will have suggestions.", "nullable": true }, "shipping_profile": { "description": "An array of data representing the shipping profile resource.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingProfile" } ], "nullable": true }, "user": { "description": "Represents a single user of the site", "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "shop": { "description": "A shop created by an Etsy user.", "allOf": [ { "$ref": "#/components/schemas/Shop" } ], "nullable": true }, "images": { "type": "array", "description": "Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image", "items": { "description": "Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image", "allOf": [ { "$ref": "#/components/schemas/ListingImage" } ] } }, "videos": { "type": "array", "description": "The single video associated with a listing.", "items": { "description": "The single video associated with a listing.", "allOf": [ { "$ref": "#/components/schemas/ListingVideo" } ] } }, "inventory": { "description": "An enumerated string that attaches a valid association. Default value is null.", "allOf": [ { "$ref": "#/components/schemas/ListingInventory" } ], "nullable": true }, "production_partners": { "type": "array", "description": "Represents a list of production partners for a shop.", "items": { "description": "Represents a list of production partners for a shop.", "allOf": [ { "$ref": "#/components/schemas/ShopProductionPartner" } ] } }, "skus": { "type": "array", "description": "A list of SKU strings for the listing. SKUs will only appear if the requesting user owns the shop and a valid matching OAuth 2 token is provided. When requested without the token it will be an empty array.", "items": { "type": "string" } }, "translations": { "description": "A map of translations for the listing. Default value is a map of all supported languages keyed to null.", "allOf": [ { "$ref": "#/components/schemas/ListingTranslations" } ], "nullable": true }, "views": { "type": "integer", "description": "The number of times the listing has been viewed. This value is tabulated once per day and **only for active listings**, so the value is not real-time. If `0`, the listing has either not been viewed, not yet tabulated, was not active during the last tabulation or there was an error fetching the value. If a value is expected, call `getListing` to confirm the value." } } }, "ShopShippingProfile": { "type": "object", "x-resource-id": "ShopShippingProfile", "description": "Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.", "properties": { "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the shipping profile.", "format": "int64", "minimum": 1 }, "title": { "type": "string", "description": "The name string of this shipping profile.", "nullable": true }, "user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) who owns the shipping profile.", "format": "int64", "minimum": 1 }, "origin_country_iso": { "type": "string", "description": "The ISO code of the country from which the listing ships.", "format": "ISO 3166-1 alpha-2" }, "is_deleted": { "type": "boolean", "description": "When true, someone deleted this shipping profile." }, "shipping_profile_destinations": { "type": "array", "description": "A list of [shipping profile destinations](/documentation/reference/#operation/createShopShippingProfileDestination) available for this shipping profile.", "items": { "description": "A list of [shipping profile destinations](/documentation/reference/#operation/createShopShippingProfileDestination) available for this shipping profile.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingProfileDestination" } ] } }, "shipping_profile_upgrades": { "type": "array", "description": "A list of [shipping profile upgrades](/documentation/reference/#operation/createShopShippingProfileUpgrade) available for this shipping profile.", "items": { "description": "A list of [shipping profile upgrades](/documentation/reference/#operation/createShopShippingProfileUpgrade) available for this shipping profile.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingProfileUpgrade" } ] } }, "origin_postal_code": { "type": "string", "description": "The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info", "nullable": true }, "profile_type": { "type": "string", "enum": ["manual", "calculated"], "default": "manual" }, "domestic_handling_fee": { "type": "number", "description": "The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.", "format": "float", "minimum": 0, "default": 0 }, "international_handling_fee": { "type": "number", "description": "The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.", "format": "float", "minimum": 0, "default": 0 } } }, "ShopShippingProfileDestination": { "type": "object", "x-resource-id": "ShopShippingProfileDestination", "description": "Represents a shipping destination assigned to a shipping profile.", "properties": { "shipping_profile_destination_id": { "type": "integer", "description": "The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.", "format": "int64", "minimum": 1 }, "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the shipping profile.", "format": "int64", "minimum": 1 }, "origin_country_iso": { "type": "string", "description": "The ISO code of the country from which the listing ships.", "format": "ISO 3166-1 alpha-2" }, "destination_country_iso": { "type": "string", "description": "The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided." }, "destination_region": { "type": "string", "description": "The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If `none`, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.", "enum": ["eu", "non_eu", "none"] }, "primary_cost": { "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "secondary_cost": { "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "nullable": true }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "nullable": true }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "nullable": true, "minimum": 1, "maximum": 45 }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "nullable": true, "minimum": 1, "maximum": 45 } } }, "ShopShippingProfileUpgrade": { "type": "object", "x-resource-id": "ShopShippingProfileUpgrade", "description": "A representation of a shipping profile upgrade option.", "properties": { "shipping_profile_id": { "type": "integer", "description": "The numeric ID of the base shipping profile.", "format": "int64", "minimum": 1 }, "upgrade_id": { "type": "integer", "description": "The numeric ID that is associated with a shipping upgrade", "format": "int64", "minimum": 1 }, "upgrade_name": { "type": "string", "description": "Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority." }, "type": { "type": "integer", "description": "The type of the shipping upgrade. Domestic (0) or international (1).", "enum": [0, 1] }, "rank": { "type": "integer", "description": "The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.", "minimum": 0 }, "language": { "type": "string", "description": "The IETF language tag for the language of the shipping profile. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`" }, "price": { "description": "Additional cost of adding the shipping upgrade.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "secondary_price": { "description": "Additional cost of adding the shipping upgrade for each additional item.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "shipping_carrier_id": { "type": "integer", "description": "The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.", "nullable": true }, "mail_class": { "type": "string", "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.", "nullable": true }, "min_delivery_days": { "type": "integer", "description": "The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.", "nullable": true, "minimum": 1, "maximum": 45 }, "max_delivery_days": { "type": "integer", "description": "The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.", "nullable": true, "minimum": 1, "maximum": 45 } } }, "User": { "type": "object", "x-resource-id": "User", "description": "Represents a single user of the site", "properties": { "user_id": { "type": "integer", "description": "The numeric ID of a user. This number is also a valid shop ID for the user's shop.", "format": "int64", "minimum": 1 }, "primary_email": { "type": "string", "description": "An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access", "format": "email", "nullable": true }, "first_name": { "type": "string", "description": "The user's first name.", "nullable": true }, "last_name": { "type": "string", "description": "The user's last name.", "nullable": true }, "image_url_75x75": { "type": "string", "description": "The user's avatar URL.", "nullable": true } } }, "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 }, "user_id": { "type": "integer", "description": "The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.", "format": "int64", "minimum": 1 }, "shop_name": { "type": "string", "description": "The shop's name string." }, "create_date": { "type": "integer", "description": "The date and time this shop was created, in epoch seconds.", "minimum": 0 }, "created_timestamp": { "type": "integer", "description": "The date and time this shop was created, in epoch seconds.", "minimum": 0 }, "title": { "type": "string", "description": "A brief heading string for the shop's main page.", "nullable": true }, "announcement": { "type": "string", "description": "An announcement string to buyers that displays on the shop's homepage.", "nullable": true }, "currency_code": { "type": "string", "description": "The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default." }, "is_vacation": { "type": "boolean", "description": "When true, this shop is not accepting purchases." }, "vacation_message": { "type": "string", "description": "The shop's message string displayed when `is_vacation` is true.", "nullable": true }, "sale_message": { "type": "string", "description": "A message string sent to users who complete a purchase from this shop.", "nullable": true }, "digital_sale_message": { "type": "string", "description": "A message string sent to users who purchase a digital item from this shop.", "nullable": true }, "update_date": { "type": "integer", "description": "The date and time of the last update to the shop, in epoch seconds.", "minimum": 0 }, "updated_timestamp": { "type": "integer", "description": "The date and time of the last update to the shop, in epoch seconds.", "minimum": 0 }, "listing_active_count": { "type": "integer", "description": "The number of active listings in the shop.", "minimum": 0 }, "digital_listing_count": { "type": "integer", "description": "The number of digital listings in the shop.", "minimum": 0 }, "login_name": { "type": "string", "description": "The shop owner's login name string." }, "accepts_custom_requests": { "type": "boolean", "description": "When true, the shop accepts customization requests." }, "policy_welcome": { "type": "string", "description": "The shop's policy welcome string (may be blank).", "nullable": true }, "policy_payment": { "type": "string", "description": "The shop's payment policy string (may be blank).", "nullable": true }, "policy_shipping": { "type": "string", "description": "The shop's shipping policy string (may be blank).", "nullable": true }, "policy_refunds": { "type": "string", "description": "The shop's refund policy string (may be blank).", "nullable": true }, "policy_additional": { "type": "string", "description": "The shop's additional policies string (may be blank).", "nullable": true }, "policy_seller_info": { "type": "string", "description": "The shop's seller information string (may be blank).", "nullable": true }, "policy_update_date": { "type": "integer", "description": "The date and time of the last update to the shop's policies, in epoch seconds.", "minimum": 0 }, "policy_has_private_receipt_info": { "type": "boolean", "description": "When true, EU receipts display private info." }, "has_unstructured_policies": { "type": "boolean", "description": "When true, the shop displays additional unstructured policy fields." }, "policy_privacy": { "type": "string", "description": "The shop's privacy policy string (may be blank).", "nullable": true }, "vacation_autoreply": { "type": "string", "description": "The shop's automatic reply string displayed in new conversations when `is_vacation` is true.", "nullable": true }, "url": { "type": "string", "description": "The URL string for this shop." }, "image_url_760x100": { "type": "string", "description": "The URL string for this shop's banner image.", "nullable": true }, "num_favorers": { "type": "integer", "description": "The number of users who marked this shop a favorite.", "minimum": 0 }, "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 }, "is_using_structured_policies": { "type": "boolean", "description": "When true, the shop accepted using structured policies." }, "has_onboarded_structured_policies": { "type": "boolean", "description": "When true, the shop accepted OR declined after viewing structured policies onboarding." }, "include_dispute_form_link": { "type": "boolean", "description": "When true, this shop's policies include a link to an EU online dispute form." }, "is_direct_checkout_onboarded": { "type": "boolean", "description": "(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments." }, "is_etsy_payments_onboarded": { "type": "boolean", "description": "When true, the shop has onboarded onto Etsy Payments." }, "is_calculated_eligible": { "type": "boolean", "description": "When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)" }, "is_opted_in_to_buyer_promise": { "type": "boolean", "description": "When true, the shop opted in to buyer promise." }, "is_shop_us_based": { "type": "boolean", "description": "When true, the shop is based in the US." }, "transaction_sold_count": { "type": "integer", "description": "The total number of sales ([transactions](/documentation/reference#tag/Shop-Receipt-Transactions)) for this shop.", "minimum": 0 }, "shipping_from_country_iso": { "type": "string", "description": "The country iso the shop is shipping from.", "format": "ISO 3166-1 alpha-2", "nullable": true }, "shop_location_country_iso": { "type": "string", "description": "The country iso where the shop is located.", "format": "ISO 3166-1 alpha-2", "nullable": true }, "review_count": { "type": "integer", "description": "Number of reviews of shop listings in the past year.", "nullable": true }, "review_average": { "type": "number", "description": "Average rating based on reviews of shop listings in the past year.", "format": "float", "nullable": true } } }, "ListingImage": { "type": "object", "x-resource-id": "ListingImage", "description": "Reference urls and metadata for an image associated with a specific listing. The `url_fullxfull` parameter contains the URL for full-sized binary image file.", "properties": { "listing_id": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "format": "int64", "minimum": 1 }, "listing_image_id": { "type": "integer", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "format": "int64", "minimum": 1 }, "hex_code": { "type": "string", "description": "The webhex string for the image's average color, in webhex notation.", "nullable": true }, "red": { "type": "integer", "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "nullable": true, "minimum": 0 }, "green": { "type": "integer", "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "nullable": true, "minimum": 0 }, "blue": { "type": "integer", "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "nullable": true, "minimum": 0 }, "hue": { "type": "integer", "description": "The numeric hue equal to the image's average hue, from 0-360 (HSV color).", "nullable": true, "minimum": 0 }, "saturation": { "type": "integer", "description": "The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).", "nullable": true, "minimum": 0 }, "brightness": { "type": "integer", "description": "The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).", "nullable": true, "minimum": 0 }, "is_black_and_white": { "type": "boolean", "description": "When true, the image is in black & white.", "nullable": true }, "creation_tsz": { "type": "integer", "description": "The listing image's creation time, in epoch seconds.", "minimum": 0 }, "created_timestamp": { "type": "integer", "description": "The listing image's creation time, in epoch seconds.", "minimum": 0 }, "rank": { "type": "integer", "description": "The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.", "minimum": 0 }, "url_75x75": { "type": "string", "description": "The url string for a 75x75 pixel thumbnail of the image." }, "url_170x135": { "type": "string", "description": "The url string for a 170x135 pixel thumbnail of the image." }, "url_570xN": { "type": "string", "description": "The url string for a thumbnail of the image, no more than 570 pixels wide with variable height." }, "url_fullxfull": { "type": "string", "description": "The url string for the full-size image, up to 3000 pixels in each dimension." }, "full_height": { "type": "integer", "description": "The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.", "nullable": true, "minimum": 0 }, "full_width": { "type": "integer", "description": "The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.", "nullable": true, "minimum": 0 }, "alt_text": { "type": "string", "description": "Alt text for the listing image. Max length 500 characters.", "nullable": true } } }, "ListingVideo": { "type": "object", "x-resource-id": "ListingVideo", "description": "Reference urls and metadata for a video associated with a specific listing.", "properties": { "video_id": { "type": "integer", "description": "The unique ID of a video associated with a listing.", "format": "int64", "minimum": 1 }, "height": { "type": "integer", "description": "The video height dimension in pixels." }, "width": { "type": "integer", "description": "The video width dimension in pixels." }, "thumbnail_url": { "type": "string", "description": "The url of the video thumbnail." }, "video_url": { "type": "string", "description": "The url of the video file." }, "video_state": { "type": "string", "description": "The current state of a given video. Value is one of `active`, `inactive`, `deleted` or `flagged`.", "enum": ["active", "inactive", "deleted", "flagged"] } } }, "ListingInventory": { "type": "object", "x-resource-id": "ListingInventory", "description": "A representation of a single listing's inventory record.", "properties": { "products": { "type": "array", "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.", "items": { "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.", "allOf": [ { "$ref": "#/components/schemas/ListingInventoryProduct" } ] } }, "price_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.", "items": { "type": "integer" } }, "quantity_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "sku_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "readiness_state_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } } }, "ListingInventoryProduct": { "type": "object", "x-resource-id": "ListingInventoryProduct", "description": "A representation of a product for a listing.", "properties": { "product_id": { "type": "integer", "description": "The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.", "format": "int64", "minimum": 1 }, "sku": { "type": "string", "description": "The SKU string for the product" }, "is_deleted": { "type": "boolean", "description": "When true, someone deleted this product." }, "offerings": { "type": "array", "description": "A list of product offering entries for this product.", "items": { "description": "A list of product offering entries for this product.", "allOf": [ { "$ref": "#/components/schemas/ListingInventoryProductOffering" } ] } }, "property_values": { "type": "array", "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "items": { "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "allOf": [ { "$ref": "#/components/schemas/ListingPropertyValue" } ] } } } }, "ListingInventoryProductOffering": { "type": "object", "x-resource-id": "ListingInventoryProductOffering", "description": "A representation of an offering for a listing.", "properties": { "offering_id": { "type": "integer", "description": "The ID for the ProductOffering", "format": "int64", "minimum": 1 }, "quantity": { "type": "integer", "description": "The quantity the ProductOffering", "minimum": 0 }, "is_enabled": { "type": "boolean", "description": "Whether or not the offering can be shown to buyers." }, "is_deleted": { "type": "boolean", "description": "Whether or not the offering has been deleted." }, "price": { "description": "Price data for this ProductOffering", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "readiness_state_id": { "type": "integer", "description": "Processing Profile for this ProductOffering", "format": "int64", "nullable": true, "minimum": 1 } } }, "ListingPropertyValue": { "type": "object", "x-resource-id": "ListingPropertyValue", "description": "A representation of structured data values.", "properties": { "property_id": { "type": "integer", "description": "The numeric ID of the Property.", "format": "int64", "minimum": 1 }, "property_name": { "type": "string", "description": "The name of the Property.", "nullable": true }, "scale_id": { "type": "integer", "description": "The numeric ID of the scale (if any).", "format": "int64", "nullable": true, "minimum": 1 }, "scale_name": { "type": "string", "description": "The label used to describe the chosen scale (if any).", "nullable": true }, "value_ids": { "type": "array", "description": "The numeric IDs of the Property values", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "values": { "type": "array", "description": "The Property values", "items": { "type": "string" } } } }, "ShopProductionPartner": { "type": "object", "x-resource-id": "ShopProductionPartner", "description": "Represents a description of a shop production partner.", "properties": { "production_partner_id": { "type": "integer", "description": "The numeric ID of a production partner.", "format": "int64", "minimum": 1 }, "partner_name": { "type": "string", "description": "The name or title of the production partner." }, "location": { "type": "string", "description": "A string representing the production partner location." } } }, "ListingTranslations": { "type": "object", "x-resource-id": "ListingTranslations", "description": "Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.", "properties": { "de": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "en-GB": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "en-IN": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "en-US": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "es": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "fr": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "it": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "ja": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "nl": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "pl": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "pt": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true }, "ru": { "allOf": [ { "$ref": "#/components/schemas/ListingTranslation" } ], "nullable": true } } }, "ListingTranslation": { "type": "object", "x-resource-id": "ListingTranslation", "description": "Represents the translation data for a Listing.", "properties": { "listing_id": { "type": "integer", "description": "The numeric ID for the Listing.", "format": "int64", "minimum": 1 }, "language": { "type": "string", "description": "The IETF language tag (e.g. 'fr') for the language of this translation." }, "title": { "type": "string", "description": "The title of the Listing of this Translation.", "nullable": true }, "description": { "type": "string", "description": "The description of the Listing of this Translation.", "nullable": true }, "tags": { "type": "array", "description": "The tags of the Listing of this Translation.", "items": { "type": "string" } } } }, "ListingImages": { "type": "object", "x-resource-id": "ListingImages", "description": "Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ListingImage" } ] } } } }, "ListingInventoryWithAssociations": { "type": "object", "x-resource-id": "ListingInventoryWithAssociations", "description": "A representation of a single listing's inventory record with associations", "properties": { "products": { "type": "array", "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.", "items": { "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.", "allOf": [ { "$ref": "#/components/schemas/ListingInventoryProduct" } ] } }, "price_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.", "items": { "type": "integer" } }, "quantity_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "sku_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer" } }, "readiness_state_on_property": { "type": "array", "description": "An array of unique [listing property](/documentation/reference#operation/getListingProperties) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.", "items": { "type": "integer", "format": "int64", "minimum": 1 } }, "listing": { "description": "An enumerated string that attaches a valid association. Default value is null.", "allOf": [ { "$ref": "#/components/schemas/ShopListing" } ] } } }, "ShopListingsWithAssociations": { "type": "object", "x-resource-id": "ShopListingsWithAssociations", "description": "A set of ShopListing resources with associations.", "properties": { "count": { "type": "integer", "description": "The number of ShopListing resources found.", "minimum": 0 }, "results": { "type": "array", "description": "The ShopListing resources found.", "items": { "description": "The ShopListing resources found.", "allOf": [ { "$ref": "#/components/schemas/ShopListingWithAssociations" } ] } } } }, "ListingPropertyValues": { "type": "object", "x-resource-id": "ListingPropertyValues", "description": "Represents several ListingPropertyValues.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ListingPropertyValue" } } } }, "ShopReceiptTransactions": { "type": "object", "x-resource-id": "ShopReceiptTransactions", "description": "A set of ShopReceiptTransaction resources", "properties": { "count": { "type": "integer", "description": "The number of ShopReceiptTransaction resources found." }, "results": { "type": "array", "description": "The ShopReceiptTransaction resources found.", "items": { "description": "The ShopReceiptTransaction resources found.", "allOf": [ { "$ref": "#/components/schemas/ShopReceiptTransaction" } ] } } } }, "ShopReceiptTransaction": { "type": "object", "x-resource-id": "ShopReceiptTransaction", "description": "A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.", "properties": { "transaction_id": { "type": "integer", "description": "The unique numeric ID for a transaction.", "format": "int64", "minimum": 1 }, "title": { "type": "string", "description": "The title string of the [listing](/documentation/reference#tag/ShopListing) purchased in this transaction.", "nullable": true }, "description": { "type": "string", "description": "The description string of the [listing](/documentation/reference#tag/ShopListing) purchased in this transaction.", "nullable": true }, "seller_user_id": { "type": "integer", "description": "The numeric user ID for the seller in this transaction.", "format": "int64", "minimum": 1 }, "buyer_user_id": { "type": "integer", "description": "The numeric user ID for the buyer in this transaction.", "format": "int64", "minimum": 1 }, "create_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "paid_timestamp": { "type": "integer", "description": "The transaction's paid date and time, in epoch seconds.", "nullable": true, "minimum": 946684800 }, "shipped_timestamp": { "type": "integer", "description": "The transaction's shipping date and time, in epoch seconds.", "nullable": true, "minimum": 946684800 }, "quantity": { "type": "integer", "description": "The numeric quantity of products purchased in this transaction.", "minimum": 0 }, "listing_image_id": { "type": "integer", "description": "The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.", "format": "int64", "nullable": true, "minimum": 1 }, "receipt_id": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 }, "is_digital": { "type": "boolean", "description": "When true, the transaction recorded the purchase of a digital listing." }, "file_data": { "type": "string", "description": "A string describing the files purchased in this transaction." }, "listing_id": { "type": "integer", "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.", "nullable": true, "minimum": 0 }, "transaction_type": { "type": "string", "description": "The type string for the transaction, usually \"listing\"." }, "product_id": { "type": "integer", "description": "The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.", "format": "int64", "nullable": true, "minimum": 1 }, "sku": { "type": "string", "description": "The SKU string for the product", "nullable": true }, "price": { "description": "A money object representing the price recorded the transaction.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "shipping_cost": { "description": "A money object representing the shipping cost for this transaction.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "variations": { "type": "array", "description": "Array of variations and personalizations the buyer chose.", "items": { "description": "Array of variations and personalizations the buyer chose.", "allOf": [ { "$ref": "#/components/schemas/TransactionVariations" } ] } }, "product_data": { "type": "array", "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "items": { "description": "A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.", "allOf": [ { "$ref": "#/components/schemas/ListingPropertyValue" } ] } }, "shipping_profile_id": { "type": "integer", "description": "The ID of the shipping profile selected for this listing.", "format": "int64", "nullable": true, "minimum": 1 }, "min_processing_days": { "type": "integer", "description": "The minimum number of days for processing the listing.", "nullable": true, "minimum": 0 }, "max_processing_days": { "type": "integer", "description": "The maximum number of days for processing the listing.", "nullable": true, "minimum": 0 }, "shipping_method": { "type": "string", "description": "Name of the selected shipping method.", "nullable": true }, "shipping_upgrade": { "type": "string", "description": "The name of the shipping upgrade selected for this listing. Default value is null.", "nullable": true }, "expected_ship_date": { "type": "integer", "description": "The date & time of the expected ship date, in epoch seconds.", "nullable": true, "minimum": 946684800 }, "buyer_coupon": { "type": "number", "description": "The amount of the buyer coupon that was discounted in the shop's currency.", "format": "float", "default": 0 }, "shop_coupon": { "type": "number", "description": "The amount of the shop coupon that was discounted in the shop's currency.", "format": "float", "default": 0 } } }, "TransactionVariations": { "type": "object", "x-resource-id": "TransactionVariations", "description": "A list of variations chosen by the buyer during checkout.", "properties": { "property_id": { "type": "integer", "description": "The variation property ID." }, "value_id": { "type": "integer", "description": "The ID of the variation value selected.", "nullable": true }, "formatted_name": { "type": "string", "description": "Formatted name of the variation." }, "formatted_value": { "type": "string", "description": "Value of the variation entered by the buyer." } } }, "ListingVariationImages": { "type": "object", "x-resource-id": "ListingVariationImages", "description": "Represents several ListingVariationImages.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ListingVariationImage" } } } }, "ListingVariationImage": { "type": "object", "x-resource-id": "ListingVariationImage", "description": "A representation of the associations of variations and images on a listing.", "properties": { "property_id": { "type": "integer", "description": "The numeric ID of the Property.", "format": "int64", "minimum": 1 }, "value_id": { "type": "integer", "description": "The numeric ID of the Value.", "format": "int64", "minimum": 1 }, "value": { "type": "string", "description": "The string value of the property.", "nullable": true }, "image_id": { "type": "integer", "description": "The numeric ID of the Image.", "format": "int64", "minimum": 1 } } }, "ListingVideos": { "type": "object", "x-resource-id": "ListingVideos", "description": "Represents a list of listing video resources, each of which contains the reference URLs for the videos.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ListingVideo" } ] } } } }, "PaymentAccountLedgerEntry": { "type": "object", "x-resource-id": "PaymentAccountLedgerEntry", "description": "Represents an entry in a shop's ledger.", "properties": { "entry_id": { "type": "integer", "description": "The ledger entry's numeric ID.", "format": "int64", "minimum": 1 }, "ledger_id": { "type": "integer", "description": "The ledger's numeric ID.", "format": "int64", "minimum": 1 }, "sequence_number": { "type": "integer", "description": "The sequence allows ledger entries to be sorted chronologically. The higher the sequence, the more recent the entry." }, "amount": { "type": "integer", "description": "The amount of money credited to the ledger." }, "currency": { "type": "string", "description": "The currency of the entry on the ledger." }, "description": { "type": "string", "description": "Details what kind of ledger entry this is: a payment, refund, reversal of a failed refund, disbursement, returned disbursement, recoupment, miscellaneous credit, miscellaneous debit, or bill payment." }, "balance": { "type": "integer", "description": "The amount of money in the shop's ledger the moment after this entry was applied." }, "create_date": { "type": "integer", "description": "The date and time the ledger entry was created in Epoch seconds.", "minimum": 0 }, "created_timestamp": { "type": "integer", "description": "The date and time the ledger entry was created in Epoch seconds.", "minimum": 0 }, "ledger_type": { "type": "string", "description": "The original reference type for the ledger entry." }, "reference_type": { "type": "string", "description": "The object type the ledger entry refers to." }, "reference_id": { "type": "string", "description": "The object id the ledger entry refers to.", "nullable": true }, "parent_entry_id": { "type": "integer", "description": "The parent ledger entry ID used to match related entries (e.g., vat_seller_services to originating seller fees).", "minimum": 0 }, "payment_adjustments": { "type": "array", "description": "List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.", "items": { "description": "List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.", "allOf": [ { "$ref": "#/components/schemas/PaymentAdjustment" } ] } } } }, "PaymentAdjustment": { "type": "object", "x-resource-id": "PaymentAdjustment", "description": "Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.", "properties": { "payment_adjustment_id": { "type": "integer", "description": "The numeric ID for a payment adjustment.", "format": "int64", "minimum": 1 }, "payment_id": { "type": "integer", "description": "A unique numeric ID for a payment to a specific Etsy [shop](/documentation/reference#tag/Shop).", "format": "int64", "minimum": 1 }, "status": { "type": "string", "description": "The status string of the payment adjustment." }, "is_success": { "type": "boolean", "description": "When true, the payment adjustment was or is likely to complete successfully." }, "user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) (seller) fulfilling the purchase.", "format": "int64", "minimum": 1 }, "reason_code": { "type": "string", "description": "A human-readable string describing the reason for the refund." }, "total_adjustment_amount": { "type": "integer", "description": "The total numeric amount of the refund in the payment currency.", "nullable": true, "minimum": 0 }, "shop_total_adjustment_amount": { "type": "integer", "description": "The numeric amount of the refund in the shop currency.", "nullable": true, "minimum": 0 }, "buyer_total_adjustment_amount": { "type": "integer", "description": "The numeric amount of the refund in the buyer currency.", "nullable": true, "minimum": 0 }, "total_fee_adjustment_amount": { "type": "integer", "description": "The numeric amount of card processing fees associated with a payment adjustment.", "nullable": true, "minimum": 0 }, "create_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "update_timestamp": { "type": "integer", "description": "The date and time of the last change to the payment adjustment in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The date and time of the last change to the payment adjustment in epoch seconds.", "minimum": 946684800 }, "payment_adjustment_items": { "type": "array", "description": "List of payment adjustment line items.", "items": { "description": "List of payment adjustment line items.", "allOf": [ { "$ref": "#/components/schemas/PaymentAdjustmentItem" } ] } } } }, "PaymentAdjustmentItem": { "type": "object", "x-resource-id": "PaymentAdjustmentItem", "description": "A payemnt adjustment line item for a payment adjustment.", "properties": { "payment_adjustment_id": { "type": "integer", "description": "The numeric ID for a payment adjustment.", "format": "int64", "minimum": 1 }, "payment_adjustment_item_id": { "type": "integer", "description": "Unique ID for the adjustment line item.", "format": "int64", "minimum": 1 }, "adjustment_type": { "type": "string", "description": "String indicating the type of adjustment for this line item.", "nullable": true }, "amount": { "type": "integer", "description": "Integer value for the amount of the adjustment in original currency.", "default": 0 }, "shop_amount": { "type": "integer", "description": "Integer value for the amount of the adjustment in currency for the shop.", "default": 0 }, "transaction_id": { "type": "integer", "description": "The unique numeric ID for a transaction.", "format": "int64", "nullable": true, "minimum": 1 }, "bill_payment_id": { "type": "integer", "description": "Unique ID for the bill payment adjustment.", "format": "int64", "nullable": true, "minimum": 1 }, "created_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The update date and time the payment adjustment in epoch seconds.", "minimum": 946684800 } } }, "PaymentAccountLedgerEntries": { "type": "object", "x-resource-id": "PaymentAccountLedgerEntries", "description": "A set of PaymentAccountLedgerEntry resources", "properties": { "count": { "type": "integer", "description": "The number of PaymentAccountLedgerEntry resources found.", "minimum": 0 }, "results": { "type": "array", "description": "The PaymentAccountLedgerEntry resources found.", "items": { "description": "The PaymentAccountLedgerEntry resources found.", "allOf": [ { "$ref": "#/components/schemas/PaymentAccountLedgerEntry" } ] } } } }, "Payments": { "type": "object", "x-resource-id": "Payments", "description": "Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.", "properties": { "count": { "type": "integer", "description": "The number of payments in the response.", "minimum": 0 }, "results": { "type": "array", "description": "A list of payments.", "items": { "description": "A list of payments.", "allOf": [ { "$ref": "#/components/schemas/Payment" } ] } } } }, "Payment": { "type": "object", "x-resource-id": "Payment", "description": "Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.", "properties": { "payment_id": { "type": "integer", "description": "A unique numeric ID for a payment to a specific Etsy [shop](/documentation/reference#tag/Shop).", "format": "int64", "minimum": 1 }, "buyer_user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) who paid the purchase.", "format": "int64", "minimum": 1 }, "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "receipt_id": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 }, "amount_gross": { "description": "An integer equal to gross amount of the order, in pennies, including shipping and taxes.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "amount_fees": { "description": "An integer equal to the original card processing fee of the order in pennies.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "amount_net": { "description": "An integer equal to the payment value, in pennies, less fees (`amount_gross` - `amount_fees`).", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "posted_gross": { "description": "The total gross value of the payment posted once the purchase ships. This is equal to the `amount_gross` UNLESS the seller issues a refund prior to shipping. We consider \"shipping\" to be the event which \"posts\" to the ledger. Therefore, if the seller refunds first, we reduce the `amount_gross` first and post then that amount. The seller never sees the refunded amount in their ledger. This is equal to the \"Credit\" amount in the ledger entry.", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "posted_fees": { "description": "The total value of the fees posted once the purchase ships. Etsy refunds a proportional amount of the fees when a seller refunds a buyer. When the seller issues a refund prior to shipping, the posted amount is less then the original.", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "posted_net": { "description": "The total value of the payment at the time of posting, less fees. (`posted_gross` - `posted_fees`)", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "adjusted_gross": { "description": "The gross payment amount after the seller refunds a payment, partially or fully.", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "adjusted_fees": { "description": "The new fee amount after a seller refunds a payment, partially or fully.", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "adjusted_net": { "description": "The total value of the payment after refunds, less fees (`adjusted_gross` - `adjusted_fees`).", "allOf": [ { "$ref": "#/components/schemas/Money" } ], "nullable": true }, "currency": { "type": "string", "description": "The ISO (alphabetic) code string for the payment's currency." }, "shop_currency": { "type": "string", "description": "The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.", "nullable": true }, "buyer_currency": { "type": "string", "description": "The currency string of the buyer.", "nullable": true }, "shipping_user_id": { "type": "integer", "description": "The numeric ID of the user to which the seller ships the order.", "format": "int64", "nullable": true, "minimum": 1 }, "shipping_address_id": { "type": "integer", "description": "The numeric id identifying the shipping address.", "format": "int64", "minimum": 1 }, "billing_address_id": { "type": "integer", "description": "The numeric ID identifying the billing address of the buyer.", "minimum": 0, "maximum": 9223372036854775807 }, "status": { "type": "string", "description": "A string indicating the current status of the payment, most commonly \"settled\" or \"authed\"." }, "shipped_timestamp": { "type": "integer", "description": "The transaction's shipping date and time, in epoch seconds.", "nullable": true, "minimum": 946684800 }, "create_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The transaction's creation date and time, in epoch seconds.", "minimum": 946684800 }, "update_timestamp": { "type": "integer", "description": "The date and time of the last change to the payment adjustment in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The date and time of the last change to the payment adjustment in epoch seconds.", "minimum": 946684800 }, "payment_adjustments": { "type": "array", "description": "List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.", "items": { "description": "List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.", "allOf": [ { "$ref": "#/components/schemas/PaymentAdjustment" } ] } } } }, "Pong": { "type": "object", "x-resource-id": "Pong", "description": "A confirmation that the current application has access to the Open API", "properties": { "application_id": { "type": "integer", "description": "The authenticated application's ID", "format": "int64", "minimum": 1 } } }, "ShopReceipt": { "type": "object", "x-resource-id": "ShopReceipt", "description": "The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.", "properties": { "receipt_id": { "type": "integer", "description": "The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.", "format": "int64", "minimum": 1 }, "receipt_type": { "type": "integer", "description": "The numeric value for the Etsy channel that serviced the purchase: 0 for Etsy.com, 1 for a Pattern shop.", "minimum": 0 }, "seller_user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) (seller) fulfilling the purchase.", "format": "int64", "minimum": 1 }, "seller_email": { "type": "string", "description": "The email address string for the seller of the listing.", "format": "email", "nullable": true }, "buyer_user_id": { "type": "integer", "description": "The numeric ID for the [user](/documentation/reference#tag/User) making the purchase.", "format": "int64", "minimum": 1 }, "buyer_email": { "type": "string", "description": "The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.", "nullable": true }, "name": { "type": "string", "description": "The name string for the recipient in the shipping address." }, "first_line": { "type": "string", "description": "The first address line string for the recipient in the shipping address.", "nullable": true }, "second_line": { "type": "string", "description": "The optional second address line string for the recipient in the shipping address.", "nullable": true }, "city": { "type": "string", "description": "The city string for the recipient in the shipping address.", "nullable": true }, "state": { "type": "string", "description": "The state string for the recipient in the shipping address.", "nullable": true }, "zip": { "type": "string", "description": "The zip code string (not necessarily a number) for the recipient in the shipping address.", "nullable": true }, "status": { "type": "string", "description": "The current order status string. One of: `paid`, `completed`, `open`, `payment processing` or `canceled`.", "enum": [ "paid", "completed", "open", "payment processing", "canceled", "fully refunded", "partially refunded" ] }, "formatted_address": { "type": "string", "description": "The formatted shipping address string for the recipient in the shipping address.", "nullable": true }, "country_iso": { "type": "string", "description": "The ISO-3166 alpha-2 country code string for the recipient in the shipping address.", "nullable": true }, "payment_method": { "type": "string", "description": "The payment method string identifying purchaser's payment method, which must be one of: 'cc' (credit card), 'paypal', 'check', 'mo' (money order), 'bt' (bank transfer), 'other', 'ideal', 'sofort', 'apple_pay', 'google', 'android_pay', 'google_pay', 'klarna', 'k_pay_in_4' (klarna), 'k_pay_in_3' (klarna), or 'k_financing' (klarna)." }, "payment_email": { "type": "string", "description": "The email address string for the email address to which to send payment confirmation", "nullable": true }, "message_from_seller": { "type": "string", "description": "An optional message string from the seller.", "nullable": true }, "message_from_buyer": { "type": "string", "description": "An optional message string from the buyer.", "nullable": true }, "message_from_payment": { "type": "string", "description": "The machine-generated acknowledgement string from the payment system.", "nullable": true }, "is_paid": { "type": "boolean", "description": "When true, buyer paid for this purchase." }, "is_shipped": { "type": "boolean", "description": "When true, seller shipped the products." }, "create_timestamp": { "type": "integer", "description": "The receipt's creation time, in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The receipt's creation time, in epoch seconds.", "minimum": 946684800 }, "update_timestamp": { "type": "integer", "description": "The time of the last update to the receipt, in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The time of the last update to the receipt, in epoch seconds.", "minimum": 946684800 }, "is_gift": { "type": "boolean", "description": "When true, the buyer indicated this purchase is a gift." }, "gift_message": { "type": "string", "description": "A gift message string the buyer requests delivered with the product." }, "gift_sender": { "type": "string", "description": "The name of the person who sent the gift." }, "grandtotal": { "description": "A number equal to the total_price minus the coupon discount plus tax and shipping costs.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "subtotal": { "description": "A number equal to the total_price minus coupon discounts. Does not included tax or shipping costs.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "total_price": { "description": "A number equal to the sum of the individual listings' (price * quantity). Does not included tax or shipping costs.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "total_shipping_cost": { "description": "A number equal to the total shipping cost of the receipt.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "total_tax_cost": { "description": "The total sales tax of the receipt.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "total_vat_cost": { "description": "A number equal to the total value-added tax (VAT) of the receipt.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "discount_amt": { "description": "The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "gift_wrap_price": { "description": "The numeric price of gift wrap for this receipt.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "shipments": { "type": "array", "description": "A list of shipment statements for this receipt.", "items": { "description": "A list of shipment statements for this receipt.", "allOf": [ { "$ref": "#/components/schemas/ShopReceiptShipment" } ] } }, "transactions": { "type": "array", "description": "Array of transactions for the receipt.", "items": { "description": "Array of transactions for the receipt.", "allOf": [ { "$ref": "#/components/schemas/ShopReceiptTransaction" } ] } }, "refunds": { "type": "array", "description": "Refunds for a given receipt.", "items": { "description": "Refunds for a given receipt.", "allOf": [ { "$ref": "#/components/schemas/ShopRefund" } ] } } } }, "ShopReceiptShipment": { "type": "object", "x-resource-id": "ShopReceiptShipment", "description": "The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.", "properties": { "receipt_shipping_id": { "type": "integer", "description": "The unique numeric ID of a Shop Receipt Shipment record.", "format": "int64", "nullable": true, "minimum": 1 }, "shipment_notification_timestamp": { "type": "integer", "description": "The time at which Etsy notified the buyer of the shipment event, in epoch seconds.", "minimum": 946684800 }, "carrier_name": { "type": "string", "description": "The name string for the carrier/company responsible for delivering the shipment." }, "tracking_code": { "type": "string", "description": "The tracking code string provided by the carrier/company for the shipment." } } }, "ShopRefund": { "type": "object", "x-resource-id": "ShopRefund", "description": "The refund record for a receipt.", "properties": { "amount": { "description": "A number equal to the refund total.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "created_timestamp": { "type": "integer", "description": "The date & time of the refund, in epoch seconds.", "minimum": 946684800 }, "reason": { "type": "string", "description": "The reason string given for the refund.", "nullable": true }, "note_from_issuer": { "type": "string", "description": "The note string created by the refund issuer.", "nullable": true }, "status": { "type": "string", "description": "The status indication string for the refund.", "nullable": true } } }, "ShopReceipts": { "type": "object", "x-resource-id": "ShopReceipts", "description": "The receipts for a specific Shop.", "properties": { "count": { "type": "integer", "description": "The number of Shop Receipts found." }, "results": { "type": "array", "description": "List of Shop Receipt resources found, with all Shop Receipt fields for each resource.", "items": { "description": "List of Shop Receipt resources found, with all Shop Receipt fields for each resource.", "allOf": [ { "$ref": "#/components/schemas/ShopReceipt" } ] } } } }, "ListingReviews": { "type": "object", "x-resource-id": "ListingReviews", "description": "A set of listing review records left by Users.", "properties": { "count": { "type": "integer", "description": "The number of TransactionReview resources found.", "minimum": 0 }, "results": { "type": "array", "description": "The TransactionReview resources found.", "items": { "description": "The TransactionReview resources found.", "allOf": [ { "$ref": "#/components/schemas/ListingReview" } ] } } } }, "ListingReview": { "type": "object", "x-resource-id": "ListingReview", "description": "A listing review record left by a User.", "properties": { "shop_id": { "type": "integer", "description": "The shop's numeric ID.", "format": "int64", "minimum": 1 }, "listing_id": { "type": "integer", "description": "The ID of the ShopListing that the TransactionReview belongs to.", "format": "int64", "minimum": 1 }, "rating": { "type": "integer", "description": "Rating value on scale from 1 to 5", "minimum": 1, "maximum": 5 }, "review": { "type": "string", "description": "A message left by the author, explaining the feedback, if provided.", "nullable": true }, "language": { "type": "string", "description": "The language of the TransactionReview" }, "image_url_fullxfull": { "type": "string", "description": "The url to a photo provided with the feedback, dimensions fullxfull. Note: This field may be absent, depending on the buyer's privacy settings.", "nullable": true }, "create_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was created in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was created in epoch seconds.", "minimum": 946684800 }, "update_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was updated in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was updated in epoch seconds.", "minimum": 946684800 } } }, "TransactionReviews": { "type": "object", "x-resource-id": "TransactionReviews", "description": "A set of transaction review records left by Users.", "properties": { "count": { "type": "integer", "description": "The number of TransactionReview resources found.", "minimum": 0 }, "results": { "type": "array", "description": "The TransactionReview resources found.", "items": { "description": "The TransactionReview resources found.", "allOf": [ { "$ref": "#/components/schemas/TransactionReview" } ] } } } }, "TransactionReview": { "type": "object", "x-resource-id": "TransactionReview", "description": "A transaction review record left by a User.", "properties": { "shop_id": { "type": "integer", "description": "The shop's numeric ID.", "format": "int64", "minimum": 1 }, "listing_id": { "type": "integer", "description": "The ID of the ShopListing that the TransactionReview belongs to.", "format": "int64", "minimum": 1 }, "transaction_id": { "type": "integer", "description": "The ID of the ShopReceipt Transaction that the TransactionReview belongs to.", "format": "int64", "minimum": 1 }, "buyer_user_id": { "type": "integer", "description": "The numeric ID of the user who was the buyer in this transaction. Note: This field may be absent, depending on the buyer's privacy settings.", "format": "int64", "nullable": true, "minimum": 1 }, "rating": { "type": "integer", "description": "Rating value on scale from 1 to 5", "minimum": 1, "maximum": 5 }, "review": { "type": "string", "description": "A message left by the author, explaining the feedback, if provided.", "default": "" }, "language": { "type": "string", "description": "The language of the TransactionReview" }, "image_url_fullxfull": { "type": "string", "description": "The url to a photo provided with the feedback, dimensions fullxfull. Note: This field may be absent, depending on the buyer's privacy settings.", "nullable": true }, "create_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was created in epoch seconds.", "minimum": 946684800 }, "created_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was created in epoch seconds.", "minimum": 946684800 }, "update_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was updated in epoch seconds.", "minimum": 946684800 }, "updated_timestamp": { "type": "integer", "description": "The date and time the TransactionReview was updated in epoch seconds.", "minimum": 946684800 } } }, "SellerTaxonomyNodes": { "type": "object", "x-resource-id": "SellerTaxonomyNodes", "description": "A list of taxonomy nodes from the seller taxonomy tree.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/SellerTaxonomyNode" } ] } } } }, "SellerTaxonomyNode": { "type": "object", "x-resource-id": "SellerTaxonomyNode", "description": "A taxonomy node in the seller taxonomy tree.", "properties": { "id": { "type": "integer", "description": "The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the \"shoes\" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than \"girls' shoes\" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes \"shoes\" or \"girls' shoes\" support access to the \"EU\" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:\"1394\", and `name`:\"38\".", "format": "int64", "minimum": 1 }, "level": { "type": "integer", "description": "The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.", "minimum": 0 }, "name": { "type": "string", "description": "The name string for this taxonomy node." }, "parent_id": { "type": "integer", "description": "The numeric taxonomy ID of the parent of this node.", "format": "int64", "nullable": true, "minimum": 1, "default": null }, "children": { "type": "array", "description": "An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.", "items": { "description": "An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.", "allOf": [ { "$ref": "#/components/schemas/SellerTaxonomyNode" } ] } }, "full_path_taxonomy_ids": { "type": "array", "description": "An array of `taxonomy_id`s including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.", "items": { "type": "integer", "format": "int64", "minimum": 1 } } } }, "TaxonomyNodeProperties": { "type": "object", "x-resource-id": "TaxonomyNodeProperties", "description": "A list of product property definitions.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/TaxonomyNodeProperty" } ] } } } }, "TaxonomyNodeProperty": { "type": "object", "x-resource-id": "TaxonomyNodeProperty", "description": "A product property definition.", "properties": { "property_id": { "type": "integer", "description": "The unique numeric ID of this product property.", "format": "int64", "minimum": 1 }, "name": { "type": "string", "description": "The name string for this taxonomy node." }, "display_name": { "type": "string", "description": "The human-readable product property name string." }, "scales": { "type": "array", "description": "A list of available scales.", "items": { "description": "A list of available scales.", "allOf": [ { "$ref": "#/components/schemas/TaxonomyPropertyScale" } ] } }, "is_required": { "type": "boolean", "description": "When true, listings assigned eligible taxonomy IDs require this property." }, "supports_attributes": { "type": "boolean", "description": "When true, you can use this property in listing attributes." }, "supports_variations": { "type": "boolean", "description": "When true, you can use this property in listing variations." }, "is_multivalued": { "type": "boolean", "description": "When true, you can assign multiple property values to this property" }, "max_values_allowed": { "type": "integer", "description": "When true, you can assign multiple property values to this property", "nullable": true }, "possible_values": { "type": "array", "description": "A list of supported property value strings for this property.", "items": { "description": "A list of supported property value strings for this property.", "allOf": [ { "$ref": "#/components/schemas/TaxonomyPropertyValue" } ] } }, "selected_values": { "type": "array", "description": "A list of property value strings automatically and always selected for the given property.", "items": { "description": "A list of property value strings automatically and always selected for the given property.", "allOf": [ { "$ref": "#/components/schemas/TaxonomyPropertyValue" } ] } } } }, "TaxonomyPropertyScale": { "type": "object", "x-resource-id": "TaxonomyPropertyScale", "description": "A scale defnining the assignable increments for the property values available to specific product properties.", "properties": { "scale_id": { "type": "integer", "description": "The unique numeric ID of a scale.", "format": "int64", "minimum": 1 }, "display_name": { "type": "string", "description": "The name string for a scale." }, "description": { "type": "string", "description": "The description string for a scale." } } }, "TaxonomyPropertyValue": { "type": "object", "x-resource-id": "TaxonomyPropertyValue", "description": "A property value for a specific product property, which may also employ a specific scale.", "properties": { "value_id": { "type": "integer", "description": "The numeric ID of this property value.", "format": "int64", "nullable": true, "minimum": 1 }, "name": { "type": "string", "description": "The name string of this property value." }, "scale_id": { "type": "integer", "description": "The numeric scale ID of the scale to which this property value belongs.", "format": "int64", "nullable": true, "minimum": 1 }, "equal_to": { "type": "array", "description": "A list of numeric property value IDs this property value is equal to (if any).", "items": { "type": "integer", "minimum": 0 } } } }, "ShippingCarriers": { "type": "object", "x-resource-id": "ShippingCarriers", "description": "Represents several ShippingCarriers.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingCarrier" } } } }, "ShippingCarrier": { "type": "object", "x-resource-id": "ShippingCarrier", "description": "A supported shipping carrier, which is used to calculate an Estimated Delivery Date.", "properties": { "shipping_carrier_id": { "type": "integer", "description": "The numeric ID of this shipping carrier.", "format": "int64", "minimum": 1 }, "name": { "type": "string", "description": "The name of this shipping carrier." }, "domestic_classes": { "type": "array", "description": "Set of domestic mail classes of this shipping carrier.", "items": { "description": "Set of domestic mail classes of this shipping carrier.", "allOf": [ { "$ref": "#/components/schemas/ShippingCarrierMailClass" } ] } }, "international_classes": { "type": "array", "description": "Set of international mail classes of this shipping carrier.", "items": { "description": "Set of international mail classes of this shipping carrier.", "allOf": [ { "$ref": "#/components/schemas/ShippingCarrierMailClass" } ] } } } }, "ShippingCarrierMailClass": { "type": "object", "x-resource-id": "ShippingCarrierMailClass", "description": "A shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", "properties": { "mail_class_key": { "type": "string", "description": "The unique identifier of this mail class." }, "name": { "type": "string", "description": "The name of this mail class." } } }, "ShopHolidayPreference": { "type": "object", "x-resource-id": "ShopHolidayPreference", "description": "Represents a shop's holiday preference", "properties": { "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "holiday_id": { "type": "integer", "description": "The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105 ] }, "country_iso": { "type": "string", "description": "The country iso where the shop is located.", "format": "ISO 3166-1 alpha-2" }, "is_working": { "type": "boolean", "description": "A boolean value for whether the shop will process orders on a particular holiday." }, "holiday_name": { "type": "string", "description": "The name of the holiday that a country observes." } } }, "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 }, "results": { "type": "array", "description": "The Shop resources.", "items": { "description": "The Shop resources.", "allOf": [ { "$ref": "#/components/schemas/Shop" } ] } } } }, "ShopReturnPolicy": { "type": "object", "x-resource-id": "ShopReturnPolicy", "description": "Represents a listing-level return policy.", "properties": { "return_policy_id": { "type": "integer", "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).", "format": "int64", "minimum": 1 }, "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "accepts_returns": { "type": "boolean", "description": "return_policy_accepts_returns" }, "accepts_exchanges": { "type": "boolean", "description": "return_policy_accepts_exchanges" }, "return_deadline": { "type": "integer", "description": "The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].", "nullable": true } } }, "ShopReturnPolicies": { "type": "object", "x-resource-id": "ShopReturnPolicies", "description": "Represents a shop's listing-level return policies list.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShopReturnPolicy" } } } }, "ShopProductionPartners": { "type": "object", "x-resource-id": "ShopProductionPartners", "description": "Represents a list of shop production partners.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ShopProductionPartner" } ] } } } }, "ShopProcessingProfile": { "type": "object", "x-resource-id": "ShopProcessingProfile", "description": "Represents a processing profile to set a product offering's readiness state and processing time info.", "properties": { "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 }, "readiness_state_id": { "type": "integer", "description": "The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.", "format": "int64", "minimum": 1 }, "readiness_state": { "type": "string", "description": "The readiness state of a product: \\\"1\\\" means \\\"ready_to_ship\\\", and \\\"2\\\" means \\\"made_to_order\\\"", "enum": ["ready_to_ship", "made_to_order"] }, "min_processing_days": { "type": "integer", "description": "The minimum number of days for processing a specific product.", "minimum": 0 }, "max_processing_days": { "type": "integer", "description": "The maximum number of days for processing a specific product.", "minimum": 0 }, "processing_days_display_label": { "type": "string", "description": "Translated display label string for processing days, for example \"3 - 5 days\"." } } }, "ShopProcessingProfiles": { "type": "object", "x-resource-id": "ShopProcessingProfiles", "description": "Represents several ProcessingProfiles.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShopProcessingProfile" } } } }, "ShopSection": { "type": "object", "x-resource-id": "ShopSection", "description": "A section within a shop, into which a user can sort listings.", "properties": { "shop_section_id": { "type": "integer", "description": "The numeric ID of a section in a specific Etsy shop.", "format": "int64", "minimum": 1 }, "title": { "type": "string", "description": "The title string for a shop section." }, "rank": { "type": "integer", "description": "The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.", "minimum": 0 }, "user_id": { "type": "integer", "description": "The numeric ID of the [user](/documentation/reference#tag/User) who owns this shop section.", "format": "int64", "minimum": 1 }, "active_listing_count": { "type": "integer", "description": "The number of active listings in one section of a specific Etsy shop.", "minimum": 0 } } }, "ShopSections": { "type": "object", "x-resource-id": "ShopSections", "description": "All the sections in a sprecific Shop.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ShopSection" } ] } } } }, "ShopShippingProfileDestinations": { "type": "object", "x-resource-id": "ShopShippingProfileDestinations", "description": "Represents a list of shipping destination objects.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingProfileDestination" } ] } } } }, "ShopShippingProfiles": { "type": "object", "x-resource-id": "ShopShippingProfiles", "description": "Represents several ShopShippingProfiles.", "properties": { "count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ShopShippingProfile" } } } }, "ShopShippingProfileUpgrades": { "type": "object", "x-resource-id": "ShopShippingProfileUpgrades", "description": "A list of shipping upgrade options.", "properties": { "count": { "type": "integer", "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", "description": "The list of requested resources.", "items": { "description": "The list of requested resources.", "allOf": [ { "$ref": "#/components/schemas/ShopShippingProfileUpgrade" } ] } } } }, "Scopes": { "type": "object", "x-resource-id": "Scopes", "description": "A list of scopes allowed for the token.", "properties": {} }, "UserAddress": { "type": "object", "x-resource-id": "UserAddress", "description": "Represents a user's address.", "properties": { "user_address_id": { "type": "integer", "description": "The numeric ID of the user's address.", "format": "int64", "minimum": 1 }, "user_id": { "type": "integer", "description": "The user's numeric ID.", "format": "int64", "minimum": 1 }, "name": { "type": "string", "description": "The user's name for this address." }, "first_line": { "type": "string", "description": "The first line of the user's address." }, "second_line": { "type": "string", "description": "The second line of the user's address.", "nullable": true }, "city": { "type": "string", "description": "The city field of the user's address." }, "state": { "type": "string", "description": "The state field of the user's address.", "nullable": true }, "zip": { "type": "string", "description": "The zip code field of the user's address.", "nullable": true }, "iso_country_code": { "type": "string", "description": "The ISO code of the country in this address.", "nullable": true }, "country_name": { "type": "string", "description": "The name of the user's country.", "nullable": true }, "is_default_shipping_address": { "type": "boolean", "description": "Is this the user's default shipping address." } } }, "UserAddresses": { "type": "object", "x-resource-id": "UserAddresses", "description": "Represents several UserAddress records.", "properties": { "count": { "type": "integer", "description": "The number of UserAddress records being returned.", "minimum": 0 }, "results": { "type": "array", "description": "An array of UserAddress resources.", "items": { "description": "An array of UserAddress resources.", "allOf": [ { "$ref": "#/components/schemas/UserAddress" } ] } } } }, "Self": { "type": "object", "x-resource-id": "Self", "description": "Represents a single user of the site", "properties": { "user_id": { "type": "integer", "description": "The numeric ID of a user. This number is also a valid shop ID for the user's shop.", "format": "int64", "minimum": 1 }, "shop_id": { "type": "integer", "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "format": "int64", "minimum": 1 } } } } } }