> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Etsy Integration for AI Agents & Workflows

> Etsy marketplace listing management via the Open API v3

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/zKB2qsP6Q61VNLfB/logos/etsy.svg?fit=max&auto=format&n=zKB2qsP6Q61VNLfB&q=85&s=002012b0470f337def43dfbe959d6c63" alt="Etsy logo" width="72" height="72" data-path="logos/etsy.svg" />

## 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`).

<Info>
  **Categories**: E-Commerce · Marketplace · **Auth**: OAuth2 · **Actions**: 6
</Info>

## Authentication

### OAuth2 Authentication

Connect using Etsy OAuth2 (recommended)

#### Required Credentials

| Field         | Description                        | Required | Format                                     |
| ------------- | ---------------------------------- | -------- | ------------------------------------------ |
| Client ID     | Etsy OAuth App Client ID (API Key) | Yes      | `xxxxxxxxxxxxxxxxxxxxxxxx`                 |
| Client Secret | Etsy OAuth App Client Secret       | Yes      | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

#### 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

<AccordionGroup>
  <Accordion title="create_draft_listing_product — Creates a physical draft listing product in a shop on Etsy">
    ### Parameters

    <ResponseField name="quantity" type="integer" required>
      The positive non-zero number of products available for purchase
    </ResponseField>

    <ResponseField name="title" type="string" required>
      The listing's title string
    </ResponseField>

    <ResponseField name="description" type="string" required>
      A description of the product for sale in the listing
    </ResponseField>

    <ResponseField name="price" type="string" required>
      The positive non-zero price of the product as a decimal string (e.g. '29.99')
    </ResponseField>

    <ResponseField name="who_made" type="string" required>
      Who made the product: i\_did, collective, someone\_else
    </ResponseField>

    <ResponseField name="when_made" type="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
    </ResponseField>

    <ResponseField name="taxonomy_id" type="string" required>
      The numerical taxonomy ID of the listing
    </ResponseField>

    <ResponseField name="is_supply" type="boolean" required>
      When true, tags the listing as a supply product; otherwise a finished product
    </ResponseField>

    <ResponseField name="listing_type" type="string" required>
      Listing type: physical, download, both
    </ResponseField>

    <ResponseField name="shipping_profile_id" type="string">
      The numeric ID of the shipping profile. Required when listing type is physical.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="delete_listing — Delete an Etsy listing by listing ID">
    ### Parameters

    <ResponseField name="listing_id" type="string" required>
      The ID of the listing to delete
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "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"
    }
    ```
  </Accordion>

  <Accordion title="get_listing — Retrieve an Etsy listing record by listing ID">
    ### Parameters

    <ResponseField name="listing_id" type="string" required>
      The ID of the listing to retrieve
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="get_listing_inventory — Retrieve the inventory record for a listing by listing ID">
    ### Parameters

    <ResponseField name="listing_id" type="string" required>
      The ID of the listing whose inventory to retrieve
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="update_listing_inventory — Update the inventory for a listing identified by listing ID">
    ### Parameters

    <ResponseField name="listing_id" type="string" required>
      The ID of the listing whose inventory to update
    </ResponseField>

    <ResponseField name="products" type="array">
      JSON array of product objects containing sku, property\_values, and offerings
    </ResponseField>

    <ResponseField name="price_on_property" type="array">
      List of listing property ID integers for properties that change product prices
    </ResponseField>

    <ResponseField name="quantity_on_property" type="array">
      List of listing property ID integers for properties that change product quantity
    </ResponseField>

    <ResponseField name="sku_on_property" type="array">
      List of listing property ID integers for properties that change the product SKU
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="update_listing_property — Update or populate the properties list defining product offerings for a listing">
    ### Parameters

    <ResponseField name="listing_id" type="string" required>
      The ID of the listing
    </ResponseField>

    <ResponseField name="property_id" type="string" required>
      The ID of the property to update
    </ResponseField>

    <ResponseField name="value_ids" type="array" required>
      Array of integer value IDs for the property
    </ResponseField>

    <ResponseField name="values" type="array" required>
      Array of string value labels for the property (e.g. 'Black', 'Christmas')
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

## Related integrations

<CardGroup cols={3}>
  <Card title="Amazon Selling Partner" href="/integrations/tools/amazon-selling-partner" />

  <Card title="Google Merchant Center" href="/integrations/tools/google-merchant-center" />

  <Card title="Instacart" href="/integrations/tools/instacart" />
</CardGroup>

## Links

* [Etsy](https://www.etsy.com)