Skip to main content
Etsy logo

​
Overview

Add Etsy to any ModuleX agent or workflow. Manage Etsy marketplace listings, inventory, and properties via the Etsy Open API v3 (openapi.etsy.com/v3).
Categories: E-Commerce · Marketplace · Auth: OAuth2 · Actions: 6

​
Authentication

​
OAuth2 Authentication

Connect using Etsy OAuth2 (recommended)

​
Required Credentials

FieldDescriptionRequiredFormat
Client IDEtsy OAuth App Client ID (API Key)Yesxxxxxxxxxxxxxxxxxxxxxxxx
Client SecretEtsy OAuth App Client SecretYesxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
OAuth Configuration

  • Authorization URL: https://www.etsy.com/oauth/connect
  • Token URL: https://api.etsy.com/v3/public/oauth/token
  • Scopes: listings_r, listings_w, listings_d, transactions_r, shops_r

​
Available Actions

​
Parameters

​
quantity
integer
required
The positive non-zero number of products available for purchase
​
title
string
required
The listing’s title string
​
description
string
required
A description of the product for sale in the listing
​
price
string
required
The positive non-zero price of the product as a decimal string (e.g. ‘29.99’)
​
who_made
string
required
Who made the product: i_did, collective, someone_else
​
when_made
string
required
Era when product was made: made_to_order, 2020_2023, 2010_2019, 2004_2009, before_2004, 2000_2003, 1990s, 1980s, 1970s, 1960s, 1950s, 1940s, 1930s, 1920s, 1910s, 1900s, 1800s, 1700s, before_1700
​
taxonomy_id
string
required
The numerical taxonomy ID of the listing
​
is_supply
boolean
required
When true, tags the listing as a supply product; otherwise a finished product
​
listing_type
string
required
Listing type: physical, download, both
​
shipping_profile_id
string
The numeric ID of the shipping profile. Required when listing type is physical.

​
Response

{
  "$defs": {
    "ListingResource": {
      "additionalProperties": false,
      "properties": {
        "listing_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Listing Id"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Description"
        },
        "state": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "State"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Url"
        },
        "quantity": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Quantity"
        },
        "price": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Price"
        },
        "who_made": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Who Made"
        },
        "when_made": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "When Made"
        },
        "taxonomy_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Taxonomy Id"
        },
        "is_supply": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Is Supply"
        },
        "listing_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Listing Type"
        },
        "views": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Views"
        },
        "num_favorers": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Num Favorers"
        },
        "shipping_profile_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Shipping Profile Id"
        }
      },
      "title": "ListingResource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "listing": {
      "anyOf": [
        {
          "$ref": "#/$defs/ListingResource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateDraftListingProductOutput",
  "type": "object"
}

​
Parameters

​
listing_id
string
required
The ID of the listing to delete

​
Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "listing_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Listing Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "DeleteListingOutput",
  "type": "object"
}

​
Parameters

​
listing_id
string
required
The ID of the listing to retrieve

​
Response

{
  "$defs": {
    "ListingResource": {
      "additionalProperties": false,
      "properties": {
        "listing_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Listing Id"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Title"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Description"
        },
        "state": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "State"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Url"
        },
        "quantity": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Quantity"
        },
        "price": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Price"
        },
        "who_made": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Who Made"
        },
        "when_made": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "When Made"
        },
        "taxonomy_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Taxonomy Id"
        },
        "is_supply": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Is Supply"
        },
        "listing_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Listing Type"
        },
        "views": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Views"
        },
        "num_favorers": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Num Favorers"
        },
        "shipping_profile_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Shipping Profile Id"
        }
      },
      "title": "ListingResource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "listing": {
      "anyOf": [
        {
          "$ref": "#/$defs/ListingResource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "GetListingOutput",
  "type": "object"
}

​
Parameters

​
listing_id
string
required
The ID of the listing whose inventory to retrieve

​
Response

{
  "$defs": {
    "InventoryProduct": {
      "additionalProperties": false,
      "properties": {
        "product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Product Id"
        },
        "sku": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sku"
        },
        "property_values": {
          "items": {
            "$ref": "#/$defs/PropertyValue"
          },
          "title": "Property Values",
          "type": "array"
        },
        "offerings": {
          "items": {
            "$ref": "#/$defs/Offering"
          },
          "title": "Offerings",
          "type": "array"
        }
      },
      "title": "InventoryProduct",
      "type": "object"
    },
    "Offering": {
      "additionalProperties": false,
      "properties": {
        "offering_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Offering Id"
        },
        "price": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Price"
        },
        "quantity": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Quantity"
        },
        "is_enabled": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Is Enabled"
        }
      },
      "title": "Offering",
      "type": "object"
    },
    "PropertyValue": {
      "additionalProperties": false,
      "properties": {
        "property_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Id"
        },
        "property_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Name"
        },
        "value_ids": {
          "items": {
            "type": "integer"
          },
          "title": "Value Ids",
          "type": "array"
        },
        "values": {
          "items": {
            "type": "string"
          },
          "title": "Values",
          "type": "array"
        }
      },
      "title": "PropertyValue",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "products": {
      "items": {
        "$ref": "#/$defs/InventoryProduct"
      },
      "title": "Products",
      "type": "array"
    },
    "price_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Price On Property",
      "type": "array"
    },
    "quantity_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Quantity On Property",
      "type": "array"
    },
    "sku_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Sku On Property",
      "type": "array"
    }
  },
  "required": [
    "success"
  ],
  "title": "GetListingInventoryOutput",
  "type": "object"
}

​
Parameters

​
listing_id
string
required
The ID of the listing whose inventory to update
​
products
array
JSON array of product objects containing sku, property_values, and offerings
​
price_on_property
array
List of listing property ID integers for properties that change product prices
​
quantity_on_property
array
List of listing property ID integers for properties that change product quantity
​
sku_on_property
array
List of listing property ID integers for properties that change the product SKU

​
Response

{
  "$defs": {
    "InventoryProduct": {
      "additionalProperties": false,
      "properties": {
        "product_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Product Id"
        },
        "sku": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sku"
        },
        "property_values": {
          "items": {
            "$ref": "#/$defs/PropertyValue"
          },
          "title": "Property Values",
          "type": "array"
        },
        "offerings": {
          "items": {
            "$ref": "#/$defs/Offering"
          },
          "title": "Offerings",
          "type": "array"
        }
      },
      "title": "InventoryProduct",
      "type": "object"
    },
    "Offering": {
      "additionalProperties": false,
      "properties": {
        "offering_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Offering Id"
        },
        "price": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Price"
        },
        "quantity": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Quantity"
        },
        "is_enabled": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Is Enabled"
        }
      },
      "title": "Offering",
      "type": "object"
    },
    "PropertyValue": {
      "additionalProperties": false,
      "properties": {
        "property_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Id"
        },
        "property_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Name"
        },
        "value_ids": {
          "items": {
            "type": "integer"
          },
          "title": "Value Ids",
          "type": "array"
        },
        "values": {
          "items": {
            "type": "string"
          },
          "title": "Values",
          "type": "array"
        }
      },
      "title": "PropertyValue",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "products": {
      "items": {
        "$ref": "#/$defs/InventoryProduct"
      },
      "title": "Products",
      "type": "array"
    },
    "price_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Price On Property",
      "type": "array"
    },
    "quantity_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Quantity On Property",
      "type": "array"
    },
    "sku_on_property": {
      "items": {
        "type": "integer"
      },
      "title": "Sku On Property",
      "type": "array"
    }
  },
  "required": [
    "success"
  ],
  "title": "UpdateListingInventoryOutput",
  "type": "object"
}

​
Parameters

​
listing_id
string
required
The ID of the listing
​
property_id
string
required
The ID of the property to update
​
value_ids
array
required
Array of integer value IDs for the property
​
values
array
required
Array of string value labels for the property (e.g. ‘Black’, ‘Christmas’)

​
Response

{
  "$defs": {
    "ListingProperty": {
      "additionalProperties": false,
      "properties": {
        "property_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Id"
        },
        "property_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Property Name"
        },
        "scale_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Scale Id"
        },
        "value_ids": {
          "items": {
            "type": "integer"
          },
          "title": "Value Ids",
          "type": "array"
        },
        "values": {
          "items": {
            "type": "string"
          },
          "title": "Values",
          "type": "array"
        }
      },
      "title": "ListingProperty",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "listing_property": {
      "anyOf": [
        {
          "$ref": "#/$defs/ListingProperty"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "UpdateListingPropertyOutput",
  "type": "object"
}

​
Limits & Quotas

  • Etsy Open API v3 rate limit: 10,000 requests per day per API key.
  • Burst limit: approximately 10 requests per second.
  • Error model: non-2xx responses raise httpx.HTTPStatusError (Pattern A). The agent should retry on 429/5xx.

Amazon Selling Partner

Google Merchant Center

Instacart