diff --git a/openapi.json b/openapi.json index abd25c0..bdd02ee 100644 --- a/openapi.json +++ b/openapi.json @@ -851,11 +851,11 @@ }, "name": { "type": "string", - "description": "A name for the file being uploaded." + "description": "The file name string for the digital or image file to upload." }, "rank": { "type": "integer", - "description": "The position of an element in a list, starting at 1.", + "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": 1, "default": 1 } @@ -964,7 +964,7 @@ "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTE: sort_on only works when combined with one of the search options (keywords, region, etc.). ", - "enum": ["created", "price", "score"], + "enum": ["created", "price"], "default": "created" } }, @@ -1072,7 +1072,7 @@ "/v3/application/shops/{shop_id}/listings/active": { "get": { "operationId": "findAllActiveListingsByShop", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nA list of all active listings on Etsy paginated by their creation date.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.", "tags": ["ShopListing"], "parameters": [ { @@ -1125,7 +1125,7 @@ ], "responses": { "200": { - "description": "A list of all active listings on Etsy paginated by their creation date.", + "description": "Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.", "content": { "application/json": { "schema": { @@ -1253,7 +1253,7 @@ "/v3/application/shop/{shop_id}/listings/{listing_id}/images/{listing_image_id}": { "get": { "operationId": "getListingImage", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves a ListingImage resource by ID.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves the references and metadata for a listing image with a specific image ID.", "tags": ["ShopListing Image"], "parameters": [ { @@ -1327,7 +1327,7 @@ "/v3/application/shops/{shop_id}/listings/{listing_id}/images": { "get": { "operationId": "getListingImages", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves all ListingImage resources for Listing.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves all listing image resources for a listing with a specific listing ID.", "tags": ["ShopListing Image"], "parameters": [ { @@ -1388,7 +1388,7 @@ }, "post": { "operationId": "uploadListingImage", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nUploads a ListingImage.\\n\\nA new ListingImage can be uploaded via the image param. A previously deleted ListingImage can be re-associated with a Listing via the listing_image_id param. Only one param should be included per request; if both are present in the request, the endpoint will upload the provided image.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nUploads a ListingImage. A new ListingImage can be uploaded via the image param. A previously deleted ListingImage can be re-associated with a Listing via the listing_image_id param. Only one param should be included per request; if both are present in the request, the endpoint will upload the provided image.", "tags": ["ShopListing Image"], "parameters": [ { @@ -1422,7 +1422,7 @@ "properties": { "image": { "type": "string", - "description": "A name for the file being uploaded.", + "description": "The file name string for the digital or image file to upload.", "format": "binary" }, "listing_image_id": { @@ -1432,7 +1432,7 @@ }, "rank": { "type": "integer", - "description": "The position of an element in a list, starting at 1.", + "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 }, @@ -1524,23 +1524,24 @@ "/v3/application/listings/{listing_id}/inventory": { "get": { "operationId": "getListingInventory", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nGet the inventory for a listing. When a listing has not been edited using the Etsy.com inventory tools, it will have no inventory records. This endpoint returns SKU data if you're the owner of the inventory records being fetched.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\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": "", + "description": "The unique numeric ID for a listing in a specific [shop](/openapi/developeres#tag/Shop).", "required": true, "schema": { "type": "integer", + "description": "The unique numeric ID for a listing in a specific [shop](/openapi/developeres#tag/Shop).", "minimum": 1 } } ], "responses": { "200": { - "description": "A single ListingInventory record.", + "description": "A single listing inventory record.", "content": { "application/json": { "schema": { @@ -1603,7 +1604,7 @@ "properties": { "products": { "type": "array", - "description": "Should be a JSON array of products, even if you only send a single product. All field names in the JSON blob should be lowercase.", + "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blob sare lowercase.", "items": { "type": "object", "properties": { @@ -1668,21 +1669,21 @@ }, "price_on_property": { "type": "array", - "description": "An array of the property_ids of the properties which price depends on (if any).", + "description": "An array of unique [listing property](/openapi/developers#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 the property_ids of the properties which quantity depends on (if any).", + "description": "An array of unique [listing property](/openapi/developers#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 the property_id of the properties which sku depends on (if any).", + "description": "An array of unique [listing property](/openapi/developers#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" } @@ -1694,7 +1695,7 @@ }, "responses": { "200": { - "description": "A single ListingInventory record.", + "description": "A single listing's inventory record.", "content": { "application/json": { "schema": { @@ -1949,7 +1950,7 @@ "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTE: sort_on only works when combined with one of the search options (keywords, region, etc.). ", - "enum": ["created", "price", "score"], + "enum": ["created", "price"], "default": "created" } }, @@ -2141,11 +2142,11 @@ { "name": "property_id", "in": "path", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "required": true, "schema": { "type": "integer", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "minimum": 1 } } @@ -2223,11 +2224,11 @@ { "name": "property_id", "in": "path", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "required": true, "schema": { "type": "integer", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "minimum": 1 } } @@ -2277,7 +2278,7 @@ }, "put": { "operationId": "updateListingProperty", - "description": "
Feedback only Give feedback

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

\n\nUpdate or populate properties for a Listing. Either values or value_ids is required.", + "description": "
Feedback only Give feedback

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

\n\nUpdates or populates properties for a Listing, which requires either `values` or `value_ids`.", "tags": ["ShopListing"], "parameters": [ { @@ -2294,11 +2295,11 @@ { "name": "property_id", "in": "path", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "required": true, "schema": { "type": "integer", - "description": "The unique ID of an Etsy ListingProperty.", + "description": "The unique ID of an Etsy [listing property](/openapi/developers#operation/getListingProperties).", "minimum": 1 } } @@ -2311,7 +2312,7 @@ "properties": { "value_ids": { "type": "array", - "description": "The unique IDs of multiple Etsy ListingProperty values.", + "description": "An array of unique IDs of multiple Etsy [listing property](/openapi/developers#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", "minimum": 1 @@ -2319,14 +2320,14 @@ }, "values": { "type": "array", - "description": "The values for multiple Etsy ListingProperty values.", + "description": "An array of value strings for multiple Etsy [listing property](/openapi/developers#operation/getListingProperties) values. For example, if your listing offers different colored products, then the values array contains the color strings for each color.", "items": { "type": "string" } }, "scale_id": { "type": "integer", - "description": "The numeric ID of a single Etsy.com measurement scale.", + "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.", "minimum": 1 } } @@ -2336,7 +2337,7 @@ }, "responses": { "200": { - "description": "A single ListingProperty.", + "description": "A single listing property.", "content": { "application/json": { "schema": { @@ -2542,12 +2543,14 @@ "title", "origin_country_iso", "primary_cost", - "secondary_cost" + "secondary_cost", + "min_processing_time", + "max_processing_time" ], "properties": { "title": { "type": "string", - "description": "The name of this shipping profile." + "description": "The name string of this shipping profile." }, "origin_country_iso": { "type": "string", @@ -2556,14 +2559,32 @@ }, "primary_cost": { "type": "number", - "description": "The cost of shipping to this country/region alone.", + "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float" }, "secondary_cost": { "type": "number", - "description": "The cost of shipping to this country/region with another item.", + "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float" }, + "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 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, or \"everywhere\" if destination_region is also \"none\".", @@ -2576,21 +2597,9 @@ "enum": ["eu", "non_eu", "none"], "default": "none" }, - "min_processing_days": { - "type": "integer", - "description": "The minimum number of days for processing the listing.", - "minimum": 0, - "default": null - }, - "max_processing_days": { - "type": "integer", - "description": "The maximum number of days for processing the listing.", - "minimum": 0, - "default": null - }, "origin_postal_code": { "type": "string", - "description": "The postal code that the shipping profile uses to ship listings from.", + "description": "The postal code string (not necessarily a number) for the location from which the listing ships.", "default": null }, "shipping_carrier_id": { @@ -2601,7 +2610,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "default": null }, "min_delivery_days": { @@ -2644,6 +2653,16 @@ } } }, + "400": { + "description": "There was a problem with the request data. 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": { @@ -2674,7 +2693,7 @@ }, "get": { "operationId": "getListingShippingProfiles", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 endpoint to retrieve a set of ShippingProfile objects associated to a User.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieve a list of shipping profiles objects available in the spedific Etsy shop identified by its shop ID.", "tags": ["ShopListing ShippingProfile"], "parameters": [ { @@ -2691,7 +2710,7 @@ ], "responses": { "200": { - "description": "A list of ShippingProfiles", + "description": "A list of shipping profiles", "content": { "application/json": { "schema": { @@ -2802,7 +2821,7 @@ }, "get": { "operationId": "getListingShippingProfile", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 endpoint to retrieve a ListingShippingProfile by id.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves a Shipping Profile for a specific listing referenced by listing ID and shipping profile ID.", "tags": ["ShopListing ShippingProfile"], "parameters": [ { @@ -2879,7 +2898,7 @@ }, "put": { "operationId": "updateListingShippingProfile", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 endpoint to update a ShippingProfile.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nChanges the settings in a shipping profile.", "tags": ["ShopListing ShippingProfile"], "parameters": [ { @@ -2913,26 +2932,34 @@ "properties": { "title": { "type": "string", - "description": "The name of this shipping profile." + "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_days": { + "min_processing_time": { "type": "integer", - "description": "The minimum number of days for processing the listing.", - "minimum": 0 + "description": "The minimum time required to process to ship listings with this shipping profile.", + "minimum": 1, + "maximum": 10 }, - "max_processing_days": { + "max_processing_time": { "type": "integer", - "description": "The maximum number of days for processing the listing.", - "minimum": 0 + "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 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 that the shipping profile uses to ship listings from.", + "description": "The postal code string (not necessarily a number) for the location from which the listing ships.", "default": null } } @@ -2942,7 +2969,7 @@ }, "responses": { "200": { - "description": "A single ShippingProfile", + "description": "The updated shipping profile.", "content": { "application/json": { "schema": { @@ -2971,6 +2998,16 @@ } } }, + "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": { @@ -3028,12 +3065,12 @@ "properties": { "primary_cost": { "type": "number", - "description": "The cost of shipping to this country/region alone.", + "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float" }, "secondary_cost": { "type": "number", - "description": "The cost of shipping to this country/region with another item.", + "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float" }, "destination_country_iso": { @@ -3056,7 +3093,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "default": null }, "min_delivery_days": { @@ -3337,13 +3374,13 @@ "properties": { "primary_cost": { "type": "number", - "description": "The cost of shipping to this country/region alone.", + "description": "The cost of shipping to this country/region alone, measured in the store's default currency.", "format": "float", "default": null }, "secondary_cost": { "type": "number", - "description": "The cost of shipping to this country/region with another item.", + "description": "The cost of shipping to this country/region with another item, measured in the store's default currency.", "format": "float", "default": null }, @@ -3367,7 +3404,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "default": null }, "min_delivery_days": { @@ -3517,7 +3554,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "default": null }, "min_delivery_days": { @@ -3823,7 +3860,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "default": null }, "min_delivery_days": { @@ -3992,7 +4029,7 @@ "/v3/application/shops/{shop_id}/listings/{listing_id}/translations/{language}": { "post": { "operationId": "createListingTranslation", - "description": "
Feedback only Give feedback

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

\n\nCreates a ListingTranslation by listing_id and language", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nCreates a ListingTranslation by listing_id and language", "tags": ["ShopListing Translation"], "parameters": [ { @@ -4033,6 +4070,7 @@ "application/x-www-form-urlencoded": { "schema": { "type": "object", + "required": ["title", "description"], "properties": { "title": { "type": "string", @@ -4085,16 +4123,6 @@ } } }, - "501": { - "description": "This endpoint is not functional at this time.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorSchema" - } - } - } - }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { @@ -4115,7 +4143,7 @@ }, "get": { "operationId": "getListingTranslation", - "description": "
Feedback only Give feedback

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

\n\nGet a Translation for a Listing in the given language", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nGet a Translation for a Listing in the given language", "tags": ["ShopListing Translation"], "parameters": [ { @@ -4182,16 +4210,6 @@ } } }, - "501": { - "description": "This endpoint is not functional at this time.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorSchema" - } - } - } - }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { @@ -4206,7 +4224,7 @@ }, "put": { "operationId": "updateListingTranslation", - "description": "
Feedback only Give feedback

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

\n\nUpdates a ListingTranslation by listing_id and language", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nUpdates a ListingTranslation by listing_id and language", "tags": ["ShopListing Translation"], "parameters": [ { @@ -4247,6 +4265,7 @@ "application/x-www-form-urlencoded": { "schema": { "type": "object", + "required": ["title", "description"], "properties": { "title": { "type": "string", @@ -4299,16 +4318,6 @@ } } }, - "501": { - "description": "This endpoint is not functional at this time.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorSchema" - } - } - } - }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { @@ -5219,7 +5228,7 @@ "/v3/application/shops/{shop_id}/receipts/{receipt_id}": { "get": { "operationId": "getShopReceipt", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRequests a Shop Receipt with a specific receipt id from a Shop", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves a receipt, identified by a receipt id, from an Etsy shop", "tags": ["Shop Receipt"], "parameters": [ { @@ -5922,16 +5931,17 @@ "/v3/application/shops/{shop_id}": { "get": { "operationId": "getShop", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 to retrieve a shop by ID.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves the shop identified by a specific shop ID.", "tags": ["Shop"], "parameters": [ { "name": "shop_id", "in": "path", - "description": "", + "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.", "minimum": 1 } } @@ -5994,19 +6004,19 @@ "properties": { "title": { "type": "string", - "description": "A brief heading for the shop's main page." + "description": "A brief heading string for the shop's main page." }, "announcement": { "type": "string", - "description": "An announcement to buyers that displays on the shop's homepage." + "description": "An announcement string to buyers that displays on the shop's homepage." }, "sale_message": { "type": "string", - "description": "A message that is sent to users who buy from this shop." + "description": "A message string sent to users who complete a purchase from this shop." }, "digital_sale_message": { "type": "string", - "description": "A message that is sent to users who buy a digital item from this shop." + "description": "A message string sent to users who purchase a digital item from this shop." } } } @@ -6076,17 +6086,17 @@ "/v3/application/users/{user_id}/shops": { "get": { "operationId": "getShopByOwnerUserId", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 to retrieve the Shop associated to a User.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves the shop identified by the shop owner's user ID.", "tags": ["Shop"], "parameters": [ { "name": "user_id", "in": "path", - "description": "The user to return a shop for.", + "description": "The numeric user ID of the [user](/openapi/developeres#tag/User) who owns this shop.", "required": true, "schema": { "type": "integer", - "description": "The user to return a shop for.", + "description": "The numeric user ID of the [user](/openapi/developeres#tag/User) who owns this shop.", "minimum": 1 } } @@ -6134,11 +6144,11 @@ { "name": "shop_name", "in": "query", - "description": "The shop's name.", + "description": "The shop's name string.", "required": true, "schema": { "type": "string", - "description": "The shop's name." + "description": "The shop's name string." } }, { @@ -6218,7 +6228,7 @@ "properties": { "title": { "type": "string", - "description": "The title of the section." + "description": "The title string for a shop section." } } } @@ -6286,23 +6296,24 @@ }, "get": { "operationId": "getShopSections", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 to retrieve a set of ShopSection objects associated to a Shop.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nRetrieves the list of shop sections available to a specific shop identified by a numeric shop ID.", "tags": ["Shop Section"], "parameters": [ { "name": "shop_id", "in": "path", - "description": "", + "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.", "minimum": 1 } } ], "responses": { "200": { - "description": "A list of ShopSections", + "description": "A list of shop sections", "content": { "application/json": { "schema": { @@ -6354,11 +6365,11 @@ { "name": "shop_section_id", "in": "path", - "description": "The unique ID of an Etsy Shop Section.", + "description": "The numeric ID of a section in a specific Etsy shop.", "required": true, "schema": { "type": "integer", - "description": "The unique ID of an Etsy Shop Section.", + "description": "The numeric ID of a section in a specific Etsy shop.", "minimum": 1 } } @@ -6397,10 +6408,10 @@ } } }, - "/v3/application/shops/{shop_id}/sections/listings": { + "/v3/application/shops/{shop_id}/sections/{shop_section_ids}/listings": { "get": { "operationId": "getListingsByShopSectionId", - "description": "
Feedback only Give feedback

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

\n\nFetch all Listings within a Shop's ShopSection.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nFetch all Listings within a Shop's ShopSection.", "tags": ["ShopListing"], "parameters": [ { @@ -6416,12 +6427,12 @@ }, { "name": "shop_section_ids", - "in": "query", - "description": "A list of unique Etsy Shop Section IDs.", + "in": "path", + "description": "The list of numeric IDS for all sections available in a specific Etsy shop.", "required": true, "schema": { "type": "array", - "description": "A list of unique Etsy Shop Section IDs.", + "description": "The list of numeric IDS for all sections available in a specific Etsy shop.", "items": { "type": "integer", "minimum": 1 @@ -6461,7 +6472,7 @@ "schema": { "type": "string", "description": "The value to sort a search result of listings on. NOTE: sort_on only works when combined with one of the search options (keywords, region, etc.). ", - "enum": ["created", "price", "score"], + "enum": ["created", "price"], "default": "created" } }, @@ -6496,16 +6507,6 @@ } } }, - "501": { - "description": "This endpoint is not functional at this time.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorSchema" - } - } - } - }, "500": { "description": "The server encountered an internal error. See the error message for details.", "content": { @@ -6792,7 +6793,7 @@ "/v3/application/users/{user_id}": { "get": { "operationId": "getUser", - "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nOpen API V3 to retrieve a user by ID.", + "description": "
AlphaGive feedback

This endpoint is ready for use as defined below, but is access-controlled and may change significantly before launch. If you'd like access, please email developers@etsy.com.

\n\nReturns user profile for the user identified by a user ID.", "tags": ["User"], "parameters": [ { @@ -6944,7 +6945,7 @@ }, "user_id": { "type": "integer", - "description": "The numeric ID for the user posting the listing.", + "description": "The numeric ID for the [user](/openapi/developeres#tag/User) posting the listing.", "minimum": 1 }, "shop_id": { @@ -6997,7 +6998,7 @@ }, "shop_section_id": { "type": "integer", - "description": "The unique ID of an Etsy Shop Section.", + "description": "The numeric ID of a section in a specific Etsy shop.", "nullable": true, "minimum": 1 }, @@ -7224,7 +7225,12 @@ "nullable": true }, "price": { - "$ref": "#/components/schemas/Money" + "description": "The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The getInventory method requests exact prices for available offerings.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] } } }, @@ -7324,7 +7330,12 @@ "type": "array", "description": "An array of ShopListingFile resources.", "items": { - "$ref": "#/components/schemas/ShopListingFile" + "description": "An array of ShopListingFile resources.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopListingFile" + } + ] } } } @@ -7343,14 +7354,19 @@ "type": "array", "description": "The ShopListing resources found.", "items": { - "$ref": "#/components/schemas/ShopListing" + "description": "The ShopListing resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopListing" + } + ] } } } }, "ListingImage": { "type": "object", - "description": "A photograph of a listing for sale.", + "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.", "required": [ "listing_id", "listing_image_id", @@ -7374,111 +7390,118 @@ "properties": { "listing_id": { "type": "integer", - "description": "The numeric ID of the ListingImage.", + "description": "The unique numeric ID for a listing in a specific [shop](/openapi/developeres#tag/Shop).", "minimum": 1 }, "listing_image_id": { "type": "integer", - "description": "The numeric ID of the Listing the ListingImage belongs to.", + "description": "The unique numeric image ID of an image in a listing.", "minimum": 1 }, "hex_code": { "type": "string", - "description": "The image's average color, in webhex notation.", + "description": "The webhex string for the image's average color, in webhex notation.", "nullable": true }, "red": { "type": "integer", - "description": "The image's average red value, 0-255 (RGB color).", + "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "minimum": 0 }, "green": { "type": "integer", - "description": "The image's average green value, 0-255 (RGB color).", + "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "minimum": 0 }, "blue": { "type": "integer", - "description": "The image's average blue value, 0-255 (RGB color).", + "description": "The numeric red value equal to the image's average red value, from 0-255 (RGB color).", "minimum": 0 }, "hue": { "type": "integer", - "description": "The image's average hue, 0-360 (HSV color).", + "description": "The numeric hue equal to the image's average hue, from 0-360 (HSV color).", "minimum": 0 }, "saturation": { "type": "integer", - "description": "The image's average saturation, 0-100 (HSV color).", + "description": "The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).", "minimum": 0 }, "brightness": { "type": "integer", - "description": "The image's average brightness, 0-100 (HSV color).", + "description": "The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).", "minimum": 0 }, "is_black_and_white": { "type": "boolean", - "description": "True if the image is in black & white." + "description": "When true, the image is in black & white." }, "creation_tsz": { "type": "integer", - "description": "Creation time, in epoch seconds.", + "description": "The listing image\\'s creation time, in epoch seconds.", "minimum": 0 }, "rank": { "type": "integer", - "description": "Display order.", + "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 to a 75x75 thumbnail of the image." + "description": "The url string for a 75x75 pixel thumbnail of the image." }, "url_170x135": { "type": "string", - "description": "The url to a 170x135 thumbnail of the image." + "description": "The url string for a 170x135 pixel thumbnail of the image." }, "url_570xN": { "type": "string", - "description": "The url to a thumbnail of the image, no more than 570px width by variable height." + "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 to the full-size image, up to 3000px in each dimension." + "description": "The url string for the full-size image, up to 3000p pixels in each dimension." }, "full_height": { "type": "integer", - "description": "Height of the image returned by url_fullxfull.", + "description": "The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.", "minimum": 0 }, "full_width": { "type": "integer", - "description": "Width of the image returned by url_fullxfull.", + "description": "The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.", "minimum": 0 } } }, "ListingImages": { "type": "object", - "description": "Represents several ListingImages.", + "description": "Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.", "required": ["count", "results"], "properties": { "count": { "type": "integer", + "description": "The number of results.", "minimum": 0 }, "results": { "type": "array", + "description": "The list of requested resources.", "items": { - "$ref": "#/components/schemas/ListingImage" + "description": "The list of requested resources.", + "allOf": [ + { + "$ref": "#/components/schemas/ListingImage" + } + ] } } } }, "ListingInventory": { "type": "object", - "description": "A representation of a listing's inventory.", + "description": "A representation of a single listing's inventory record.", "required": [ "products", "price_on_property", @@ -7488,28 +7511,33 @@ "properties": { "products": { "type": "array", - "description": "The products available for this listing.", + "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blob sare lowercase.", "items": { - "$ref": "#/components/schemas/ListingInventoryProduct" + "description": "A JSON array of products available in a listing, even if only one product. All field names in the JSON blob sare lowercase.", + "allOf": [ + { + "$ref": "#/components/schemas/ListingInventoryProduct" + } + ] } }, "price_on_property": { "type": "array", - "description": "Which properties control price?", + "description": "An array of unique [listing property](/openapi/developers#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": "Which properties control quantity?", + "description": "An array of unique [listing property](/openapi/developers#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": "Which properties control SKU?", + "description": "An array of unique [listing property](/openapi/developers#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" } @@ -7544,14 +7572,24 @@ "type": "array", "description": "ProductOffering data for this Product", "items": { - "$ref": "#/components/schemas/ListingInventoryProductOffering" + "description": "ProductOffering data for this Product", + "allOf": [ + { + "$ref": "#/components/schemas/ListingInventoryProductOffering" + } + ] } }, "property_values": { "type": "array", "description": "PropertyValue data for this Product", "items": { - "$ref": "#/components/schemas/ListingPropertyValue" + "description": "PropertyValue data for this Product", + "allOf": [ + { + "$ref": "#/components/schemas/ListingPropertyValue" + } + ] } } } @@ -7586,7 +7624,12 @@ "description": "Whether or not the offering has been deleted." }, "price": { - "$ref": "#/components/schemas/Money" + "description": "Price data for this ProductOffering", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] } } }, @@ -7651,7 +7694,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ListingPropertyValue" + "allOf": [ + { + "$ref": "#/components/schemas/ListingPropertyValue" + } + ] } } } @@ -7668,7 +7715,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ShippingCarrier" + "allOf": [ + { + "$ref": "#/components/schemas/ShippingCarrier" + } + ] } } } @@ -7696,14 +7747,24 @@ "type": "array", "description": "Set of domestic mail classes of this shipping carrier.", "items": { - "$ref": "#/components/schemas/ShippingCarrierMailClass" + "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": { - "$ref": "#/components/schemas/ShippingCarrierMailClass" + "description": "Set of international mail classes of this shipping carrier.", + "allOf": [ + { + "$ref": "#/components/schemas/ShippingCarrierMailClass" + } + ] } } } @@ -7742,17 +7803,17 @@ "properties": { "shipping_profile_id": { "type": "integer", - "description": "The numeric ID of this shipping profile.", + "description": "The numeric ID of the shipping profile.", "minimum": 1 }, "title": { "type": "string", - "description": "The name of this shipping profile.", + "description": "The name string of this shipping profile.", "nullable": true }, "user_id": { "type": "integer", - "description": "The numeric ID of the user who owns this shipping profile.", + "description": "The numeric ID for the [user](/openapi/developeres#tag/User) who owns the shipping profile.", "minimum": 1 }, "min_processing_days": { @@ -7769,7 +7830,7 @@ }, "processing_days_display_label": { "type": "string", - "description": "Translated display label for processing days." + "description": "Translated display label string for processing days." }, "origin_country_iso": { "type": "string", @@ -7778,25 +7839,35 @@ }, "is_deleted": { "type": "boolean", - "description": "Whether this shipping profile has been deleted." + "description": "When true, the shop owner deleted this shipping profile." }, "shipping_profile_destinations": { "type": "array", - "description": "Set of destinations of this shipping profile.", + "description": "A list of [shipping profile destinations](/openapi/developers#operation/createListingShippingProfileDestination) available for this shipping profile.", "items": { - "$ref": "#/components/schemas/ListingShippingProfileDestination" + "description": "A list of [shipping profile destinations](/openapi/developers#operation/createListingShippingProfileDestination) available for this shipping profile.", + "allOf": [ + { + "$ref": "#/components/schemas/ListingShippingProfileDestination" + } + ] } }, "shipping_profile_upgrades": { "type": "array", - "description": "Set of shipping upgrades for this shipping profile.", + "description": "A list of [shipping profile upgrades](/openapi/developers#operation/createListingShippingProfileUpgrade) available for this shipping profile.", "items": { - "$ref": "#/components/schemas/ListingShippingProfileUpgrade" + "description": "A list of [shipping profile upgrades](/openapi/developers#operation/createListingShippingProfileUpgrade) available for this shipping profile.", + "allOf": [ + { + "$ref": "#/components/schemas/ListingShippingProfileUpgrade" + } + ] } }, "origin_postal_code": { "type": "string", - "description": "The postal code where this shipping profile ships from.", + "description": "The postal code string (not necessarily a number) for the location from which the listing ships.", "nullable": true } } @@ -7843,10 +7914,20 @@ "enum": ["eu", "non_eu", "none"] }, "primary_cost": { - "$ref": "#/components/schemas/Money" + "description": "The shipping fee for this item, if shipped alone.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "secondary_cost": { - "$ref": "#/components/schemas/Money" + "description": "The shipping fee for this item, if shipped with another item.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "shipping_carrier_id": { "type": "integer", @@ -7921,10 +8002,20 @@ "description": "The language of the shipping ugprade." }, "price": { - "$ref": "#/components/schemas/Money" + "description": "Additional cost of adding the shipping upgrade.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "secondary_price": { - "$ref": "#/components/schemas/Money" + "description": "Additional cost of adding the shipping upgrade for each additional item.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "shipping_carrier_id": { "type": "integer", @@ -7933,7 +8024,7 @@ }, "mail_class": { "type": "string", - "description": "The unique ID of a shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.", + "description": "The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.", "nullable": true }, "min_delivery_days": { @@ -7964,7 +8055,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ListingShippingProfileDestination" + "allOf": [ + { + "$ref": "#/components/schemas/ListingShippingProfileDestination" + } + ] } } } @@ -7981,7 +8076,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ListingShippingProfile" + "allOf": [ + { + "$ref": "#/components/schemas/ListingShippingProfile" + } + ] } } } @@ -7998,7 +8097,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ListingShippingProfileUpgrade" + "allOf": [ + { + "$ref": "#/components/schemas/ListingShippingProfileUpgrade" + } + ] } } } @@ -8016,7 +8119,12 @@ "type": "array", "description": "The ShopReceiptTransaction resources found.", "items": { - "$ref": "#/components/schemas/ShopReceiptTransaction" + "description": "The ShopReceiptTransaction resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopReceiptTransaction" + } + ] } } } @@ -8125,10 +8233,20 @@ "minimum": 1 }, "price": { - "$ref": "#/components/schemas/Money" + "description": "The price of the transaction.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "shipping_cost": { - "$ref": "#/components/schemas/Money" + "description": "The shipping cost for this transaction.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] } } }, @@ -8154,11 +8272,13 @@ }, "title": { "type": "string", - "description": "The title of the Listing of this Translation." + "description": "The title of the Listing of this Translation.", + "nullable": true }, "description": { "type": "string", - "description": "The description of the Listing of this Translation." + "description": "The description of the Listing of this Translation.", + "nullable": true }, "tags": { "type": "array", @@ -8181,7 +8301,11 @@ "results": { "type": "array", "items": { - "$ref": "#/components/schemas/ListingVariationImage" + "allOf": [ + { + "$ref": "#/components/schemas/ListingVariationImage" + } + ] } } } @@ -8222,7 +8346,12 @@ "type": "array", "description": "The PaymentAccountLedgerEntry resources found.", "items": { - "$ref": "#/components/schemas/PaymentAccountLedgerEntry" + "description": "The PaymentAccountLedgerEntry resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentAccountLedgerEntry" + } + ] } } } @@ -8293,7 +8422,12 @@ "type": "array", "description": "The Payment resources found.", "items": { - "$ref": "#/components/schemas/Payment" + "description": "The Payment resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/Payment" + } + ] } } } @@ -8343,31 +8477,76 @@ "minimum": 1 }, "amount_gross": { - "$ref": "#/components/schemas/Money" + "description": "The original gross amount of the order, in pennies - this is grand total, including shipping and taxes.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "amount_fees": { - "$ref": "#/components/schemas/Money" + "description": "The original card processing fee of the order in pennies.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "amount_net": { - "$ref": "#/components/schemas/Money" + "description": "The total value of the payment less fees (amount_gross - amount_fees).", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "posted_gross": { - "$ref": "#/components/schemas/Money" + "description": "The gross amount which posted to the ledger once shipped. This is equal to the amount_gross UNLESS the seller issues a refund prior to shipping. We consider \"shipping\" to the event which \"posts\" to the ledger. Therefore, if the seller refunds first, we simply reduce the amount_gross and post 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" + } + ] }, "posted_fees": { - "$ref": "#/components/schemas/Money" + "description": "Amount of the fees that posted when shipped. We refund a proportional amount of the fees when a seller refunds a buyer. If they refund prior to shipping, the posted amount will be less then the original.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "posted_net": { - "$ref": "#/components/schemas/Money" + "description": "The total value of the payment at the time of posting it to the ledger less fees (posted_gross - posted_fees) ", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "adjusted_gross": { - "$ref": "#/components/schemas/Money" + "description": "If the payment is refunded, partially or fully, this is the new gross amount after the refund.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "adjusted_fees": { - "$ref": "#/components/schemas/Money" + "description": "If the payment is refunded, partially or fully, this is the new fee amount after the refund.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "adjusted_net": { - "$ref": "#/components/schemas/Money" + "description": "The total value of the payment after refunds less fees (adjusted_gross - adjusted_fees).", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "currency": { "type": "string", @@ -8423,7 +8602,12 @@ "type": "array", "description": "Represents refund on an Etsy Payments transaction. Please note all monetary amounts are in USD pennies unless otherwise specified.", "items": { - "$ref": "#/components/schemas/PaymentAdjustment" + "description": "Represents refund on an Etsy Payments transaction. Please note all monetary amounts are in USD pennies unless otherwise specified.", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentAdjustment" + } + ] } } } @@ -8657,34 +8841,79 @@ "description": "A gift message string the buyer requests delivered with the product." }, "grandtotal": { - "$ref": "#/components/schemas/Money" + "description": "A number equal to the total_price minus the coupon discount plus tax and shipping costs.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "subtotal": { - "$ref": "#/components/schemas/Money" + "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": { - "$ref": "#/components/schemas/Money" + "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": { - "$ref": "#/components/schemas/Money" + "description": "A number equal to the total shipping cost of the receipt.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "total_tax_cost": { - "$ref": "#/components/schemas/Money" + "description": "The total sales tax of the receipt.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "total_vat_cost": { - "$ref": "#/components/schemas/Money" + "description": "A number equal to the total value-added tax (VAT) of the receipt.", + "allOf": [ + { + "$ref": "#/components/schemas/Money" + } + ] }, "discount_amt": { - "$ref": "#/components/schemas/Money" + "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": { - "$ref": "#/components/schemas/Money" + "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": { - "$ref": "#/components/schemas/ShopReceiptShipment" + "description": "A list of shipment statements for this receipt.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopReceiptShipment" + } + ] } } } @@ -8733,7 +8962,12 @@ "type": "array", "description": "List of Shop Receipt resources found, with all Shop Receipt fields for each resource.", "items": { - "$ref": "#/components/schemas/ShopReceipt" + "description": "List of Shop Receipt resources found, with all Shop Receipt fields for each resource.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopReceipt" + } + ] } } } @@ -8752,7 +8986,12 @@ "type": "array", "description": "The TransactionReview resources found.", "items": { - "$ref": "#/components/schemas/TransactionReview" + "description": "The TransactionReview resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/TransactionReview" + } + ] } } } @@ -8844,7 +9083,12 @@ "type": "array", "description": "The SellerTaxonomyNode resources found.", "items": { - "$ref": "#/components/schemas/SellerTaxonomyNode" + "description": "The SellerTaxonomyNode resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/SellerTaxonomyNode" + } + ] } } } @@ -8885,7 +9129,12 @@ "type": "array", "description": "The child Taxonomy nodes, embedded directly in the response.", "items": { - "$ref": "#/components/schemas/SellerTaxonomyNode" + "description": "The child Taxonomy nodes, embedded directly in the response.", + "allOf": [ + { + "$ref": "#/components/schemas/SellerTaxonomyNode" + } + ] } }, "full_path_taxonomy_ids": { @@ -8912,7 +9161,12 @@ "type": "array", "description": "The TaxonomyNodeProperty resources found.", "items": { - "$ref": "#/components/schemas/TaxonomyNodeProperty" + "description": "The TaxonomyNodeProperty resources found.", + "allOf": [ + { + "$ref": "#/components/schemas/TaxonomyNodeProperty" + } + ] } } } @@ -8950,7 +9204,12 @@ "type": "array", "description": "A list of available scales.", "items": { - "$ref": "#/components/schemas/TaxonomyPropertyScale" + "description": "A list of available scales.", + "allOf": [ + { + "$ref": "#/components/schemas/TaxonomyPropertyScale" + } + ] } }, "is_required": { @@ -8973,14 +9232,24 @@ "type": "array", "description": "A list of allowed values.", "items": { - "$ref": "#/components/schemas/TaxonomyPropertyValue" + "description": "A list of allowed values.", + "allOf": [ + { + "$ref": "#/components/schemas/TaxonomyPropertyValue" + } + ] } }, "selected_values": { "type": "array", "description": "A list of values that are always selected for the given category.", "items": { - "$ref": "#/components/schemas/TaxonomyPropertyValue" + "description": "A list of values that are always selected for the given category.", + "allOf": [ + { + "$ref": "#/components/schemas/TaxonomyPropertyValue" + } + ] } } } @@ -9038,7 +9307,7 @@ }, "Shop": { "type": "object", - "description": "A store created by a member.", + "description": "A shop created by an Etsy user.", "required": [ "shop_id", "user_id", @@ -9079,64 +9348,68 @@ "is_calculated_eligible", "is_opted_in_to_buyer_promise", "is_shop_us_based", - "transaction_sold_count" + "transaction_sold_count", + "shipping_from_country_iso", + "shop_location_country_iso", + "review_count", + "review_average" ], "properties": { "shop_id": { "type": "integer", - "description": "The shop's numeric ID.", + "description": "The unique positive non-zero numeric ID for an Etsy Shop.", "minimum": 1 }, "user_id": { "type": "integer", - "description": "The numeric ID of the user that owns this shop.", + "description": "The numeric user ID of the [user](/openapi/developeres#tag/User) who owns this shop.", "minimum": 1 }, "shop_name": { "type": "string", - "description": "The shop's name." + "description": "The shop's name string." }, "create_date": { "type": "integer", - "description": "The date and time the shop was created, in epoch seconds.", + "description": "The date and time this shop was created, in epoch seconds.", "minimum": 0 }, "title": { "type": "string", - "description": "A brief heading for the shop's main page.", + "description": "A brief heading string for the shop\\'s main page.", "nullable": true }, "announcement": { "type": "string", - "description": "An announcement to buyers that displays on the shop's homepage.", + "description": "An announcement string to buyers that displays on the shop's homepage.", "nullable": true }, "currency_code": { "type": "string", - "description": "The ISO code (alphabetic) for the seller's currency. All prices are in this currency." + "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": "True if the seller is not currently accepting purchases." + "description": "When true, this shop is not accepting purchases." }, "vacation_message": { "type": "string", - "description": "The shop's message to display in case is_vacation is true.", + "description": "The shop's message string displayed when is_vacation is true.", "nullable": true }, "sale_message": { "type": "string", - "description": "A message that is sent to users who buy from this shop.", + "description": "A message string sent to users who complete a purchase from this shop.", "nullable": true }, "digital_sale_message": { "type": "string", - "description": "A message that is sent to users who buy a digital item from this shop.", + "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 the shop was last updated, in epoch seconds.", + "description": "The date and time of the last update to the shop, in epoch seconds.", "minimum": 0 }, "listing_active_count": { @@ -9146,128 +9419,151 @@ }, "digital_listing_count": { "type": "integer", - "description": "Number of digital listings the shop has.", + "description": "The number of digital listings in the shop.", "minimum": 0 }, "login_name": { "type": "string", - "description": "The user's login name." + "description": "The shop owner\\'s login name string." }, "accepts_custom_requests": { "type": "boolean", - "description": "True if the shop accepts requests for custom items." + "description": "When true, the shop accepts customization requests." }, "policy_welcome": { "type": "string", - "description": "The introductory text from the top of the seller's policies page (may be blank).", + "description": "The shop's policy welcome string (may be blank).", "nullable": true }, "policy_payment": { "type": "string", - "description": "The seller's policy on payment (may be blank).", + "description": "The shop's payment policy string (may be blank).", "nullable": true }, "policy_shipping": { "type": "string", - "description": "The seller's policy on shipping (may be blank).", + "description": "The shop's shipping policy string (may be blank).", "nullable": true }, "policy_refunds": { "type": "string", - "description": "The seller's policy on refunds (may be blank).", + "description": "The shop's refund policy string (may be blank).", "nullable": true }, "policy_additional": { "type": "string", - "description": "Any additional policy information the seller provides (may be blank).", + "description": "The shop's additional policies string (may be blank).", "nullable": true }, "policy_seller_info": { "type": "string", - "description": "The shop's seller information (may be blank).", + "description": "The shop's seller infomation string (may be blank).", "nullable": true }, "policy_update_date": { "type": "integer", - "description": "The date and time the shop's policy was last updated, in epoch seconds.", + "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": "True if seller has private info to show in EU receipts." + "description": "When true, EU receipts display private info." }, "has_unstructured_policies": { "type": "boolean", - "description": "True if shop has any unstructured policy fields filled out." + "description": "When true, the shop displays additional unstructured policy fields." }, "policy_privacy": { "type": "string", - "description": "Privacy policy information the seller provides (may be blank).", + "description": "The shop's privacy policy string (may be blank).", "nullable": true }, "vacation_autoreply": { "type": "string", - "description": "A message to buyers in response to new convos if is_vacation is true.", + "description": "The shop's automatic reply string displayed in new conversations when is_vacation is true.", "nullable": true }, "url": { "type": "string", - "description": "The URL of the shop." + "description": "The URL string for this shop." }, "image_url_760x100": { "type": "string", - "description": "The URL to the shop's banner image.", + "description": "The URL string for this shop's banner image.", "nullable": true }, "num_favorers": { "type": "integer", - "description": "The number of members who've marked this Shop as a favorite.", + "description": "The number of users who marked this shop a favorite.", "minimum": 0 }, "languages": { "type": "array", - "description": "The languages that this Shop is enrolled in.", + "description": "A list of language strings for the shop's enrolled languages.", "items": { "type": "string" } }, "icon_url_fullxfull": { "type": "string", - "description": "The url of the shop full-sized shop icon.", + "description": "The URL string for this shop's icon image.", "nullable": true }, "is_using_structured_policies": { "type": "boolean", - "description": "True if shop has accepted using structured policies." + "description": "When true, the shop accepted using structured policies." }, "has_onboarded_structured_policies": { "type": "boolean", - "description": "True if shop has viewed structured policies onboarding and accepted OR declined." + "description": "When true, the shop accepted OR declined after viewing structured policies onboarding." }, "include_dispute_form_link": { "type": "boolean", - "description": "True if shop policies include a link to EU online dispute form." + "description": "When true, this shop\\'s policies include a link to an EU online dispute form." }, "is_direct_checkout_onboarded": { "type": "boolean", - "description": "True if the shop has onboarded onto Etsy Payments." + "description": "When true, the shop has onboarded onto Etsy Payments." }, "is_calculated_eligible": { "type": "boolean", - "description": "True if the shop is elegible for calculated shipping profiles (Only available in the US and Canada)." + "description": "When true, the shop is elegible for calculated shipping profiles. (Only available in the US and Canada)" }, "is_opted_in_to_buyer_promise": { "type": "boolean", - "description": "True if opted in to buyer promise." + "description": "When true, the shop opted in to buyer promise." }, "is_shop_us_based": { "type": "boolean", - "description": "True if shop is based in the US." + "description": "When true, the shop is based in the US." }, "transaction_sold_count": { "type": "integer", - "description": "The total sales for the shop", + "description": "The total number of sales ([transactions](/openapi/developeres#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 } } }, @@ -9285,7 +9581,12 @@ "type": "array", "description": "The Shop resources.", "items": { - "$ref": "#/components/schemas/Shop" + "description": "The Shop resources.", + "allOf": [ + { + "$ref": "#/components/schemas/Shop" + } + ] } } } @@ -9303,26 +9604,26 @@ "properties": { "shop_section_id": { "type": "integer", - "description": "The unique ID of an Etsy Shop Section.", + "description": "The numeric ID of a section in a specific Etsy shop.", "minimum": 1 }, "title": { "type": "string", - "description": "The title of the section." + "description": "The title string for a shop section." }, "rank": { "type": "integer", - "description": "Display order.", + "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 ID of the user who owns this shop section.", + "description": "The numeric ID of the [user](/openapi/developeres#tag/User) who owns this shop section.", "minimum": 1 }, "active_listing_count": { "type": "integer", - "description": "The number of active listings currently in the section.", + "description": "The number of active listings in one section of a specific Etsy shop.", "minimum": 0 } } @@ -9341,7 +9642,12 @@ "type": "array", "description": "The Shop Section resources.", "items": { - "$ref": "#/components/schemas/ShopSection" + "description": "The Shop Section resources.", + "allOf": [ + { + "$ref": "#/components/schemas/ShopSection" + } + ] } } } @@ -9429,7 +9735,12 @@ "type": "array", "description": "An array of UserAddress resources.", "items": { - "$ref": "#/components/schemas/UserAddress" + "description": "An array of UserAddress resources.", + "allOf": [ + { + "$ref": "#/components/schemas/UserAddress" + } + ] } } } @@ -9441,40 +9752,95 @@ "user_id", "login_name", "primary_email", + "first_name", + "last_name", "create_timestamp", "referred_by_user_id", - "use_new_inventory_endpoints" + "use_new_inventory_endpoints", + "is_seller", + "bio", + "gender", + "birth_month", + "birth_day", + "transaction_buy_count", + "transaction_sold_count" ], "properties": { "user_id": { "type": "integer", - "description": "The user's numeric ID. This is also valid as the user's shop ID.", + "description": "The numeric ID of a user. This number is also a valid shop ID for the user\\'s shop.", "minimum": 1 }, "login_name": { "type": "string", - "description": "The user's login name." + "description": "The user\\'s login name string." }, "primary_email": { "type": "string", - "description": "The user's primary email address.", + "description": "An email address string for the user\\'s primary email address.", "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 + }, "create_timestamp": { "type": "integer", - "description": "The date and time the user was created, in epoch seconds.", + "description": "The date and time the user created their account, in epoch seconds.", "minimum": 946684800 }, "referred_by_user_id": { "type": "integer", - "description": "The numeric ID of the user that referred this user.", + "description": "The numeric ID of the user who referred this user.", "nullable": true, "minimum": 1 }, "use_new_inventory_endpoints": { "type": "boolean", - "description": "Should this user's listings be created or edited using the new Inventory endpoints?" + "description": "Deprecated. Always true." + }, + "is_seller": { + "type": "boolean", + "description": "True if the user is seller." + }, + "bio": { + "type": "string", + "description": "The user\\'s biography.", + "nullable": true + }, + "gender": { + "type": "string", + "description": "The user\\'s gender.", + "nullable": true + }, + "birth_month": { + "type": "string", + "description": "The user\\'s month of birth.", + "nullable": true + }, + "birth_day": { + "type": "string", + "description": "The user\\'s day of birth.", + "nullable": true + }, + "transaction_buy_count": { + "type": "integer", + "description": "The number of transactions where the user has bought.", + "nullable": true, + "minimum": 0 + }, + "transaction_sold_count": { + "type": "integer", + "description": "The number of transactions where the user has sold.", + "nullable": true, + "minimum": 0 } } }