ShopListing

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ShopListing",
  "description": "A listing from a shop, which contains a product quantity, title, description, price, etc.",
  "$id": "https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/json-schema/open-api-v3-shop-listing-schema.json",
  "type": "object",
  "properties": {
    "listing_id": {
      "type": "integer",
      "description": "The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.",
      "format": "int64",
      "minimum": 1,
      "example": 123456789
    },
    "user_id": {
      "type": "integer",
      "description": "The numeric ID for the [user](/documentation/reference#tag/User) posting the listing.",
      "format": "int64",
      "minimum": 1,
      "example": 456789
    },
    "shop_id": {
      "type": "integer",
      "description": "The unique positive non-zero numeric ID for an Etsy Shop.",
      "format": "int64",
      "minimum": 1,
      "example": 123456
    },
    "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.",
      "example": "Handmade Ceramic Mug \u2014 Stoneware"
    },
    "description": {
      "type": "string",
      "description": "A description string of the product for sale in the listing.",
      "example": "Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio."
    },
    "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"
      ],
      "example": "active"
    },
    "creation_timestamp": {
      "type": "integer",
      "description": "The listing's creation time, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "created_timestamp": {
      "type": "integer",
      "description": "The listing's creation time, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "ending_timestamp": {
      "type": "integer",
      "description": "The listing's expiration time, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "original_creation_timestamp": {
      "type": "integer",
      "description": "The listing's creation time, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "last_modified_timestamp": {
      "type": "integer",
      "description": "The time of the last update to the listing, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "updated_timestamp": {
      "type": "integer",
      "description": "The time of the last update to the listing, in epoch seconds.",
      "minimum": 946684800,
      "example": 1758153645
    },
    "state_timestamp": {
      "type": "integer",
      "description": "The date and time of the last state change of this listing.",
      "nullable": true,
      "minimum": 946684800,
      "example": 1758153645
    },
    "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,
      "example": 1
    },
    "shop_section_id": {
      "type": "integer",
      "description": "The numeric ID of a section in a specific Etsy shop.",
      "format": "int64",
      "nullable": true,
      "minimum": 1,
      "example": 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.",
      "example": 1
    },
    "url": {
      "type": "string",
      "description": "The full URL to the listing's page on Etsy.",
      "example": "https://www.etsy.com/listing/123456789"
    },
    "num_favorers": {
      "type": "integer",
      "description": "The number of users who marked this Listing a favorite.",
      "minimum": 0,
      "example": 1
    },
    "non_taxable": {
      "type": "boolean",
      "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates do not apply to this listing at checkout.",
      "example": true
    },
    "is_taxable": {
      "type": "boolean",
      "description": "When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout.",
      "example": true
    },
    "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.",
      "example": true
    },
    "is_personalizable": {
      "type": "boolean",
      "description": "When true, this listing is personalizable. The default value is false.",
      "example": 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"
      ],
      "example": "physical"
    },
    "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,
      "example": 1
    },
    "return_policy_id": {
      "type": "integer",
      "description": "The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).",
      "format": "int64",
      "nullable": true,
      "minimum": 1,
      "example": 1
    },
    "processing_min": {
      "type": "integer",
      "description": "The minimum number of days required to process this listing. Default value is null.",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "processing_max": {
      "type": "integer",
      "description": "The maximum number of days required to process this listing. Default value is null.",
      "nullable": true,
      "minimum": 0,
      "example": 1
    },
    "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"
      ],
      "example": "i_did"
    },
    "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_2026",
        "2010_2019",
        "2007_2009",
        "before_2007",
        "2000_2006",
        "1990s",
        "1980s",
        "1970s",
        "1960s",
        "1950s",
        "1940s",
        "1930s",
        "1920s",
        "1910s",
        "1900s",
        "1800s",
        "1700s",
        "before_1700"
      ],
      "example": "made_to_order"
    },
    "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,
      "example": 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,
      "example": 0.5
    },
    "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"
      ],
      "example": "oz"
    },
    "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,
      "example": 1.0
    },
    "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,
      "example": 1.0
    },
    "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,
      "example": 1.0
    },
    "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"
      ],
      "example": "in"
    },
    "is_private": {
      "type": "boolean",
      "description": "When true, this is a private listing intended for a specific buyer and hidden from shop view.",
      "example": true
    },
    "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) Each style string is limited to 45 characters. Default value is null.",
      "items": {
        "type": "string"
      }
    },
    "file_data": {
      "type": "string",
      "description": "A string describing the files attached to a digital listing.",
      "nullable": true,
      "example": "example string"
    },
    "has_variations": {
      "type": "boolean",
      "description": "When true, the listing has variations.",
      "example": true
    },
    "should_auto_renew": {
      "type": "boolean",
      "description": "When true, renews a listing for four months upon expiration.",
      "example": true
    },
    "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,
      "example": "en-US"
    },
    "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.",
      "oneOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "example": "example"
    },
    "converted_price": {
      "description": "The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.",
      "oneOf": [
        {
          "$ref": "#/components/schemas/Money"
        }
      ],
      "nullable": true,
      "example": "example"
    },
    "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,
      "example": 1234
    },
    "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,
      "example": 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,
      "example": "Handmade Ceramic Mug \u2014 Stoneware"
    }
  }
}