# Etsy

> Run your Etsy shop: create and update listings with their photos, prices and stock, find and ship orders with tracking, read reviews and payment records, and start workflows on new orders, shipped orders and reviews.

App · 26 actions. Web page: https://docs.lodol.com/docs/integrations/etsy

## Actions

### Add listing image

Add a photo to a listing, from a file or a public link (JPEG, PNG or GIF, up to 10 MB). A listing can have up to 20.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.
- Image (`image`, text, required): The image: a file, or a link to one starting https://.
- Position (`rank`, number): Where it goes among the listing's images, 1 being first. Leave empty to add it first. From 1 to 20.
- Alt text (`alt_text`, text): A short description of the image for people using screen readers.

**Outputs**

- `image` (object): A listing image

**Example output**

```json
{
  "image": {
    "alt_text": "Speckled white mug on a wooden table",
    "created_timestamp": 1761307300,
    "full_height": 2000,
    "full_width": 2000,
    "listing_id": 1234567890,
    "listing_image_id": 6012345678,
    "rank": 1,
    "url_570xN": "https://i.etsystatic.com/30123456/r/il/1a2b3c/6012345678/il_570xN.6012345678_abcd.jpg",
    "url_75x75": "https://i.etsystatic.com/30123456/d/il/1a2b3c/6012345678/il_75x75.6012345678_abcd.jpg",
    "url_fullxfull": "https://i.etsystatic.com/30123456/r/il/1a2b3c/6012345678/il_fullxfull.6012345678_abcd.jpg"
  }
}
```

### Create draft listing

Create a listing as a draft: hidden from buyers and free until you publish it. Add images with 'Add listing image', then publish with 'Update listing'.

**Inputs**

- Title (`title`, text, required): The listing's title, up to 140 characters.
- Description (`description`, text, required): What you're selling, as buyers will read it.
- Price (`price`, number, required): The price in your shop's currency, such as 24.50. At least 0.01.
- Quantity (`quantity`, number, required): How many are for sale, 1 to 999. From 1 to 999.
- Who made it (`who_made`, text, required): Who made the item. One of: `i_did` (I did), `collective` (A member of my shop), `someone_else` (Another company or person).
- When it was made (`when_made`, text, required): When the item was made. One of: `made_to_order` (Made to order), `2020_2026` (2020 to 2026), `2010_2019` (2010 to 2019), `2007_2009` (2007 to 2009), `before_2007` (Before 2007), `2000_2006` (2000 to 2006), `1990s`, `1980s`, `1970s`, `1960s`, and 9 more.
- Category (`taxonomy_id`, text, required): The category buyers find it under. Pick one, or give a category ID from 'Search categories'.
- Type (`listing_type`, text): A physical item, a digital download, or both. One of: `physical` (Physical item (default)), `download` (Digital download), `both` (Physical item with a digital download). Default: `physical`.
- Shipping profile (`shipping_profile_id`, text): How it ships and what shipping costs. Pick one of your shipping profiles. Needed for a physical item.
- Processing profile (`readiness_state_id`, text): How long it takes to be ready to ship. Pick one of your processing profiles. Needed for a physical item.
- Return policy (`return_policy_id`, text): Its return policy. Pick one of your shop's policies.
- Shop section (`shop_section_id`, text): The shop section to show it in.
- Craft supply (`is_supply`, true/false): Switch on for a craft supply or tool rather than a finished item. Default: `false`.
- Tags (`tags`, list): Up to 13 words or phrases buyers might search for, each up to 20 characters.
- Materials (`materials`, list): What it's made of, such as cotton or silver.

**Outputs**

- `listing` (object): An Etsy listing

**Example output**

```json
{
  "listing": {
    "created_timestamp": 1761307200,
    "description": "A 12 oz stoneware mug, thrown and glazed by hand.",
    "has_variations": false,
    "is_supply": false,
    "listing_id": 1234567890,
    "listing_type": "physical",
    "materials": [
      "stoneware"
    ],
    "num_favorers": 0,
    "price": {
      "amount": 2450,
      "currency_code": "USD",
      "divisor": 100
    },
    "quantity": 5,
    "readiness_state_id": 1402336022581,
    "return_policy_id": 1066663425433,
    "shipping_profile_id": 198765432101,
    "shop_id": 30123456,
    "shop_section_id": null,
    "state": "draft",
    "tags": [
      "ceramic mug",
      "handmade"
    ],
    "taxonomy_id": 1063,
    "title": "Handmade ceramic mug, speckled white",
    "updated_timestamp": 1761307200,
    "url": "https://www.etsy.com/listing/1234567890/handmade-ceramic-mug",
    "when_made": "made_to_order",
    "who_made": "i_did"
  }
}
```

### Create shipping profile

Create a shipping profile with a flat cost to one country or region and a delivery estimate. Add more destinations in Shop Manager.

**Inputs**

- Name (`title`, text, required): The profile's name, such as Standard US shipping.
- Shipping cost (`primary_cost`, number, required): What one item costs to ship, in your shop's currency. 0 for free. At least 0.
- Each additional item (`secondary_cost`, number, required): What each extra item in the same order adds, in your shop's currency. At least 0.
- Fewest delivery days (`min_delivery_days`, number, required): The fewest business days delivery takes once shipped, 1 to 45. From 1 to 45.
- Most delivery days (`max_delivery_days`, number, required): The most business days delivery takes once shipped, 1 to 45. From 1 to 45.
- Ships from (`origin_country_iso`, text): The two-letter country code it ships from, such as US. Leave empty for the country your shop ships from.
- Ships from postal code (`origin_postal_code`, text): The postal code it ships from, where the country has them.
- Ships to (`destination_country_iso`, text): The two-letter country code it ships to. Leave this and Ships to region empty to ship within the country it ships from.
- Ships to region (`destination_region`, text): A region to ship to instead of one country. One of: `eu` (European Union), `non_eu` (Europe outside the EU).

**Outputs**

- `shipping_profile` (object): A shipping profile

**Example output**

```json
{
  "shipping_profile": {
    "is_deleted": false,
    "origin_country_iso": "US",
    "origin_postal_code": "97201",
    "profile_type": "manual",
    "shipping_profile_destinations": [
      {
        "destination_country_iso": "US",
        "max_delivery_days": 5,
        "min_delivery_days": 3,
        "primary_cost": {
          "amount": 500,
          "currency_code": "USD",
          "divisor": 100
        },
        "secondary_cost": {
          "amount": 200,
          "currency_code": "USD",
          "divisor": 100
        },
        "shipping_profile_destination_id": 298765432101
      }
    ],
    "shipping_profile_id": 198765432101,
    "shipping_profile_upgrades": [],
    "title": "Standard US shipping"
  }
}
```

### Create shop section

Add a section to your shop, such as Mugs, to group listings in.

**Inputs**

- Name (`title`, text, required): The section's name, as buyers see it.

**Outputs**

- `section` (object): A shop section

**Example output**

```json
{
  "section": {
    "active_listing_count": 12,
    "rank": 1,
    "shop_section_id": 41234567,
    "title": "Mugs"
  }
}
```

### Delete listing

Delete a listing for good. Etsy can't bring it back.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.

**Outputs**

- `deleted` (true/false): True once deleted
- `listing_id` (number): The listing deleted

**Example output**

```json
{
  "deleted": true,
  "listing_id": 1234567890
}
```

### Delete listing image

Remove an image from a listing.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.
- Image ID (`listing_image_id`, text, required): The image's ID, from 'List listing images' or 'Add listing image'.

**Outputs**

- `deleted` (true/false): True once deleted
- `listing_id` (number): The listing's ID
- `listing_image_id` (number): The image deleted

**Example output**

```json
{
  "deleted": true,
  "listing_id": 1234567890,
  "listing_image_id": 6012345678
}
```

### Delete shipping profile

Delete a shipping profile that no listing uses.

**Inputs**

- Shipping profile (`shipping_profile_id`, text, required): The shipping profile to delete.

**Outputs**

- `deleted` (true/false): True once deleted
- `shipping_profile_id` (number): The shipping profile deleted

**Example output**

```json
{
  "deleted": true,
  "shipping_profile_id": 198765432101
}
```

### Delete shop section

Delete a shop section. Its listings stay in your shop.

**Inputs**

- Shop section (`shop_section_id`, text, required): The section to delete.

**Outputs**

- `deleted` (true/false): True once deleted
- `shop_section_id` (number): The section deleted

**Example output**

```json
{
  "deleted": true,
  "shop_section_id": 41234567
}
```

### Get listing

Get one listing: title, description, status, price, quantity, tags, category and profiles.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.

**Outputs**

- `listing` (object): An Etsy listing

**Example output**

```json
{
  "listing": {
    "created_timestamp": 1761307200,
    "description": "A 12 oz stoneware mug, thrown and glazed by hand.",
    "has_variations": false,
    "is_supply": false,
    "listing_id": 1234567890,
    "listing_type": "physical",
    "materials": [
      "stoneware"
    ],
    "num_favorers": 0,
    "price": {
      "amount": 2450,
      "currency_code": "USD",
      "divisor": 100
    },
    "quantity": 5,
    "readiness_state_id": 1402336022581,
    "return_policy_id": 1066663425433,
    "shipping_profile_id": 198765432101,
    "shop_id": 30123456,
    "shop_section_id": null,
    "state": "draft",
    "tags": [
      "ceramic mug",
      "handmade"
    ],
    "taxonomy_id": 1063,
    "title": "Handmade ceramic mug, speckled white",
    "updated_timestamp": 1761307200,
    "url": "https://www.etsy.com/listing/1234567890/handmade-ceramic-mug",
    "when_made": "made_to_order",
    "who_made": "i_did"
  }
}
```

### Get my shop

Get the connected Etsy shop: name, link, currency, announcement, active listings, sales, reviews and where it ships from.

**Inputs**: None.

**Outputs**

- `shop` (object): The connected Etsy shop

**Example output**

```json
{
  "shop": {
    "announcement": "New autumn glazes are in.",
    "created_timestamp": 1514764800,
    "currency_code": "USD",
    "digital_sale_message": null,
    "is_vacation": false,
    "listing_active_count": 42,
    "policy_additional": null,
    "review_average": 4.9,
    "review_count": 318,
    "sale_message": "Thank you for your order!",
    "shipping_from_country_iso": "US",
    "shop_id": 30123456,
    "shop_name": "SpeckledClay",
    "title": "Handmade stoneware for everyday",
    "transaction_sold_count": 1290,
    "url": "https://www.etsy.com/shop/SpeckledClay",
    "user_id": 812345678
  }
}
```

### Get order

Get one order: buyer, shipping address, items, totals, status and any tracking.

**Inputs**

- Order ID (`receipt_id`, text, required): The order's receipt ID, from 'List orders', a trigger, or the order's page in Shop Manager.

**Outputs**

- `order` (object): An order (Etsy's receipt)

**Example output**

```json
{
  "order": {
    "buyer_email": null,
    "buyer_user_id": 912345678,
    "country_iso": "US",
    "created_timestamp": 1761310800,
    "formatted_address": "Jordan Lee\n12 Elm St\nPortland, OR 97201\nUnited States",
    "grandtotal": {
      "amount": 5390,
      "currency_code": "USD",
      "divisor": 100
    },
    "is_paid": true,
    "is_shipped": false,
    "message_from_buyer": "It's a gift, thank you!",
    "name": "Jordan Lee",
    "receipt_id": 3456789012,
    "shipments": [],
    "status": "paid",
    "subtotal": {
      "amount": 4900,
      "currency_code": "USD",
      "divisor": 100
    },
    "total_shipping_cost": {
      "amount": 0,
      "currency_code": "USD",
      "divisor": 100
    },
    "total_tax_cost": {
      "amount": 490,
      "currency_code": "USD",
      "divisor": 100
    },
    "transactions": [
      {
        "created_timestamp": 1761310800,
        "expected_ship_date": 1761570000,
        "is_digital": false,
        "listing_id": 1234567890,
        "paid_timestamp": 1761310800,
        "price": {
          "amount": 2450,
          "currency_code": "USD",
          "divisor": 100
        },
        "product_id": 15012345678,
        "quantity": 2,
        "receipt_id": 3456789012,
        "shipped_timestamp": null,
        "shipping_cost": {
          "amount": 0,
          "currency_code": "USD",
          "divisor": 100
        },
        "sku": "MUG-WHT",
        "title": "Handmade ceramic mug, speckled white",
        "transaction_id": 4123456789,
        "variations": []
      }
    ],
    "updated_timestamp": 1761310800
  }
}
```

### Get price and quantity

Get a listing's price, quantity and SKU, for each variation if it has them.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.

**Outputs**

- `inventory` (object): The inventory exactly as Etsy gives it
- `listing_id` (number): The listing's ID
- `products` (list): Its products, one per variation

**Example output**

```json
{
  "inventory": {
    "price_on_property": [],
    "products": [
      {
        "is_deleted": false,
        "offerings": [
          {
            "is_deleted": false,
            "is_enabled": true,
            "offering_id": 16012345678,
            "price": {
              "amount": 2450,
              "currency_code": "USD",
              "divisor": 100
            },
            "quantity": 5,
            "readiness_state_id": 1402336022581
          }
        ],
        "product_id": 15012345678,
        "property_values": [],
        "sku": "MUG-WHT"
      }
    ],
    "quantity_on_property": [],
    "readiness_state_on_property": [],
    "sku_on_property": []
  },
  "listing_id": 1234567890,
  "products": [
    {
      "currency_code": "USD",
      "is_enabled": true,
      "price": 24.5,
      "product_id": 15012345678,
      "quantity": 5,
      "sku": "MUG-WHT",
      "variations": []
    }
  ]
}
```

### List listing images

List a listing's images in order, with links to each size.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.

**Outputs**

- `count` (number): How many were returned
- `images` (list): The images

**Example output**

```json
{
  "count": 1,
  "images": [
    {
      "alt_text": "Speckled white mug on a wooden table",
      "created_timestamp": 1761307300,
      "full_height": 2000,
      "full_width": 2000,
      "listing_id": 1234567890,
      "listing_image_id": 6012345678,
      "rank": 1,
      "url_570xN": "https://i.etsystatic.com/30123456/r/il/1a2b3c/6012345678/il_570xN.6012345678_abcd.jpg",
      "url_75x75": "https://i.etsystatic.com/30123456/d/il/1a2b3c/6012345678/il_75x75.6012345678_abcd.jpg",
      "url_fullxfull": "https://i.etsystatic.com/30123456/r/il/1a2b3c/6012345678/il_fullxfull.6012345678_abcd.jpg"
    }
  ]
}
```

### List listings

List your shop's listings in one status: active, draft, inactive, sold out or expired.

**Inputs**

- Status (`state`, text): Which listings to list. Defaults to active. One of: `active` (Active (default)), `draft`, `inactive`, `sold_out` (Sold out), `expired`. Default: `active`.
- How many (`limit`, number): How many to get, 1 to 500. Defaults to 25. From 1 to 500.

**Outputs**

- `count` (number): How many were returned
- `listings` (list): The listings
- `total` (number): How many Etsy has in all

**Example output**

```json
{
  "count": 1,
  "listings": [
    {
      "created_timestamp": 1761307200,
      "description": "A 12 oz stoneware mug, thrown and glazed by hand.",
      "has_variations": false,
      "is_supply": false,
      "listing_id": 1234567890,
      "listing_type": "physical",
      "materials": [
        "stoneware"
      ],
      "num_favorers": 0,
      "price": {
        "amount": 2450,
        "currency_code": "USD",
        "divisor": 100
      },
      "quantity": 5,
      "readiness_state_id": 1402336022581,
      "return_policy_id": 1066663425433,
      "shipping_profile_id": 198765432101,
      "shop_id": 30123456,
      "shop_section_id": null,
      "state": "draft",
      "tags": [
        "ceramic mug",
        "handmade"
      ],
      "taxonomy_id": 1063,
      "title": "Handmade ceramic mug, speckled white",
      "updated_timestamp": 1761307200,
      "url": "https://www.etsy.com/listing/1234567890/handmade-ceramic-mug",
      "when_made": "made_to_order",
      "who_made": "i_did"
    }
  ],
  "total": 1
}
```

### List order items

List what was bought in an order: each listing, variation, SKU, quantity and price.

**Inputs**

- Order ID (`receipt_id`, text, required): The order's receipt ID, from 'List orders', a trigger, or the order's page in Shop Manager.

**Outputs**

- `count` (number): How many were returned
- `items` (list): The items bought

**Example output**

```json
{
  "count": 1,
  "items": [
    {
      "created_timestamp": 1761310800,
      "expected_ship_date": 1761570000,
      "is_digital": false,
      "listing_id": 1234567890,
      "paid_timestamp": 1761310800,
      "price": {
        "amount": 2450,
        "currency_code": "USD",
        "divisor": 100
      },
      "product_id": 15012345678,
      "quantity": 2,
      "receipt_id": 3456789012,
      "shipped_timestamp": null,
      "shipping_cost": {
        "amount": 0,
        "currency_code": "USD",
        "divisor": 100
      },
      "sku": "MUG-WHT",
      "title": "Handmade ceramic mug, speckled white",
      "transaction_id": 4123456789,
      "variations": []
    }
  ]
}
```

### List orders

List your shop's orders, newest first, by status and when they were placed, with their items, totals and shipping address.

**Inputs**

- Status (`status`, text): Which orders to list. Defaults to all. One of: `all` (All orders (default)), `to_ship` (Paid, not shipped yet), `shipped`, `unpaid` (Not paid yet), `canceled`. Default: `all`.
- Created after (`created_after`, date and time): Only those made at or after this moment.
- Created before (`created_before`, date and time): Only those made at or before this moment.
- How many (`limit`, number): How many to get, 1 to 500. Defaults to 25. From 1 to 500.

**Outputs**

- `count` (number): How many were returned
- `orders` (list): The orders
- `total` (number): How many Etsy has in all

**Example output**

```json
{
  "count": 1,
  "orders": [
    {
      "buyer_email": null,
      "buyer_user_id": 912345678,
      "country_iso": "US",
      "created_timestamp": 1761310800,
      "formatted_address": "Jordan Lee\n12 Elm St\nPortland, OR 97201\nUnited States",
      "grandtotal": {
        "amount": 5390,
        "currency_code": "USD",
        "divisor": 100
      },
      "is_paid": true,
      "is_shipped": false,
      "message_from_buyer": "It's a gift, thank you!",
      "name": "Jordan Lee",
      "receipt_id": 3456789012,
      "shipments": [],
      "status": "paid",
      "subtotal": {
        "amount": 4900,
        "currency_code": "USD",
        "divisor": 100
      },
      "total_shipping_cost": {
        "amount": 0,
        "currency_code": "USD",
        "divisor": 100
      },
      "total_tax_cost": {
        "amount": 490,
        "currency_code": "USD",
        "divisor": 100
      },
      "transactions": [
        {
          "created_timestamp": 1761310800,
          "expected_ship_date": 1761570000,
          "is_digital": false,
          "listing_id": 1234567890,
          "paid_timestamp": 1761310800,
          "price": {
            "amount": 2450,
            "currency_code": "USD",
            "divisor": 100
          },
          "product_id": 15012345678,
          "quantity": 2,
          "receipt_id": 3456789012,
          "shipped_timestamp": null,
          "shipping_cost": {
            "amount": 0,
            "currency_code": "USD",
            "divisor": 100
          },
          "sku": "MUG-WHT",
          "title": "Handmade ceramic mug, speckled white",
          "transaction_id": 4123456789,
          "variations": []
        }
      ],
      "updated_timestamp": 1761310800
    }
  ],
  "total": 1
}
```

### List payment account entries

List the entries in your Etsy Payments account: sales, fees, refunds and deposits, with the balance after each. Amounts are in cents. Covers the last 30 days unless you choose dates.

**Inputs**

- Created after (`created_after`, date and time): Only those made at or after this moment.
- Created before (`created_before`, date and time): Only those made at or before this moment.
- How many (`limit`, number): How many to get, 1 to 500. Defaults to 25. From 1 to 500.

**Outputs**

- `count` (number): How many were returned
- `entries` (list): The entries
- `total` (number): How many Etsy has in all

**Example output**

```json
{
  "count": 1,
  "entries": [
    {
      "amount": 4900,
      "balance": 18250,
      "created_timestamp": 1761310900,
      "currency": "USD",
      "description": "Payment",
      "entry_id": 51234567890,
      "ledger_id": 7123456,
      "ledger_type": "PAYMENT_GROSS",
      "reference_id": "3456789012",
      "reference_type": "receipt",
      "sequence_number": 1042
    }
  ],
  "total": 1
}
```

### List processing profiles

List your processing profiles: whether items are ready to ship or made to order, and how many days they take.

**Inputs**: None.

**Outputs**

- `count` (number): How many were returned
- `processing_profiles` (list): The processing profiles

**Example output**

```json
{
  "count": 1,
  "processing_profiles": [
    {
      "max_processing_days": 3,
      "min_processing_days": 1,
      "processing_days_display_label": "1-3 days",
      "readiness_state": "ready_to_ship",
      "readiness_state_id": 1402336022581
    }
  ]
}
```

### List reviews

List your shop's reviews, with rating, text and listing.

**Inputs**

- Created after (`created_after`, date and time): Only those made at or after this moment.
- Created before (`created_before`, date and time): Only those made at or before this moment.
- How many (`limit`, number): How many to get, 1 to 500. Defaults to 25. From 1 to 500.

**Outputs**

- `count` (number): How many were returned
- `reviews` (list): The reviews
- `total` (number): How many Etsy has in all

**Example output**

```json
{
  "count": 1,
  "reviews": [
    {
      "buyer_user_id": 912345678,
      "created_timestamp": 1761915600,
      "image_url_fullxfull": null,
      "language": "en",
      "listing_id": 1234567890,
      "rating": 5,
      "review": "Beautiful mug, arrived quickly and well packed.",
      "shop_id": 30123456,
      "transaction_id": 4123456789,
      "updated_timestamp": 1761915600
    }
  ],
  "total": 1
}
```

### List shipping profiles

List your shipping profiles, with where each ships and what it costs.

**Inputs**: None.

**Outputs**

- `count` (number): How many were returned
- `shipping_profiles` (list): The shipping profiles

**Example output**

```json
{
  "count": 1,
  "shipping_profiles": [
    {
      "is_deleted": false,
      "origin_country_iso": "US",
      "origin_postal_code": "97201",
      "profile_type": "manual",
      "shipping_profile_destinations": [
        {
          "destination_country_iso": "US",
          "max_delivery_days": 5,
          "min_delivery_days": 3,
          "primary_cost": {
            "amount": 500,
            "currency_code": "USD",
            "divisor": 100
          },
          "secondary_cost": {
            "amount": 200,
            "currency_code": "USD",
            "divisor": 100
          },
          "shipping_profile_destination_id": 298765432101
        }
      ],
      "shipping_profile_id": 198765432101,
      "shipping_profile_upgrades": [],
      "title": "Standard US shipping"
    }
  ]
}
```

### List shop sections

List your shop's sections, with how many active listings each has.

**Inputs**: None.

**Outputs**

- `count` (number): How many were returned
- `sections` (list): The sections

**Example output**

```json
{
  "count": 1,
  "sections": [
    {
      "active_listing_count": 12,
      "rank": 1,
      "shop_section_id": 41234567,
      "title": "Mugs"
    }
  ]
}
```

### Mark order shipped

Mark an order shipped, with its tracking number and carrier if you have them. Etsy emails the buyer to say it's on its way.

**Inputs**

- Order ID (`receipt_id`, text, required): The order's receipt ID, from 'List orders', a trigger, or the order's page in Shop Manager.
- Tracking number (`tracking_code`, text): The parcel's tracking number. Leave this and Carrier empty to mark it shipped without tracking.
- Carrier (`carrier_name`, text): Who is delivering it. Pick one, or type its name.
- Note to buyer (`note_to_buyer`, text): A message to include in Etsy's email to the buyer.
- Copy me (`send_bcc`, true/false): Send you a copy of the email Etsy sends the buyer. Default: `false`.

**Outputs**

- `order` (object): An order (Etsy's receipt)

**Example output**

```json
{
  "order": {
    "buyer_email": null,
    "buyer_user_id": 912345678,
    "country_iso": "US",
    "created_timestamp": 1761310800,
    "formatted_address": "Jordan Lee\n12 Elm St\nPortland, OR 97201\nUnited States",
    "grandtotal": {
      "amount": 5390,
      "currency_code": "USD",
      "divisor": 100
    },
    "is_paid": true,
    "is_shipped": true,
    "message_from_buyer": "It's a gift, thank you!",
    "name": "Jordan Lee",
    "receipt_id": 3456789012,
    "shipments": [
      {
        "carrier_name": "USPS",
        "receipt_shipping_id": 987654321,
        "shipment_notification_timestamp": 1761397200,
        "tracking_code": "9400111899223344556677"
      }
    ],
    "status": "completed",
    "subtotal": {
      "amount": 4900,
      "currency_code": "USD",
      "divisor": 100
    },
    "total_shipping_cost": {
      "amount": 0,
      "currency_code": "USD",
      "divisor": 100
    },
    "total_tax_cost": {
      "amount": 490,
      "currency_code": "USD",
      "divisor": 100
    },
    "transactions": [
      {
        "created_timestamp": 1761310800,
        "expected_ship_date": 1761570000,
        "is_digital": false,
        "listing_id": 1234567890,
        "paid_timestamp": 1761310800,
        "price": {
          "amount": 2450,
          "currency_code": "USD",
          "divisor": 100
        },
        "product_id": 15012345678,
        "quantity": 2,
        "receipt_id": 3456789012,
        "shipped_timestamp": null,
        "shipping_cost": {
          "amount": 0,
          "currency_code": "USD",
          "divisor": 100
        },
        "sku": "MUG-WHT",
        "title": "Handmade ceramic mug, speckled white",
        "transaction_id": 4123456789,
        "variations": []
      }
    ],
    "updated_timestamp": 1761397200
  }
}
```

### Search categories

Find Etsy categories by name, such as mugs or earrings, for a listing's category. Categories without subcategories come first; a listing needs one of those.

**Inputs**

- Search for (`query`, text, required): Words in the category's name or path, such as ceramic mug.
- How many (`limit`, number): How many categories to return, 1 to 100. Defaults to 20. From 1 to 100.

**Outputs**

- `categories` (list): The matching categories
- `count` (number): How many were returned
- `total` (number): How many categories matched

**Example output**

```json
{
  "categories": [
    {
      "id": 1063,
      "is_leaf": true,
      "level": 4,
      "name": "Mugs",
      "path": "Home & Living > Kitchen & Dining > Drink & Barware > Drinkware > Mugs"
    }
  ],
  "count": 1,
  "total": 1
}
```

### Update listing

Change a listing's details, or publish or hide it. Only what you fill in changes. Price and quantity change with 'Update price and quantity'.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.
- Title (`title`, text): A new title, up to 140 characters.
- Description (`description`, text): A new description.
- Tags (`tags`, list): Tags to replace the current ones, up to 13.
- Materials (`materials`, list): Materials to replace the current ones.
- Who made it (`who_made`, text): Who made the item. One of: `i_did` (I did), `collective` (A member of my shop), `someone_else` (Another company or person).
- When it was made (`when_made`, text): When the item was made. One of: `made_to_order` (Made to order), `2020_2026` (2020 to 2026), `2010_2019` (2010 to 2019), `2007_2009` (2007 to 2009), `before_2007` (Before 2007), `2000_2006` (2000 to 2006), `1990s`, `1980s`, `1970s`, `1960s`, and 9 more.
- Craft supply (`is_supply`, true/false): On for a craft supply or tool, off for a finished item.
- Category (`taxonomy_id`, text): The category buyers find it under. Pick one, or give a category ID from 'Search categories'.
- Shipping profile (`shipping_profile_id`, text): How it ships and what shipping costs. Pick one of your shipping profiles.
- Return policy (`return_policy_id`, text): Its return policy. Pick one of your shop's policies.
- Shop section (`shop_section_id`, text): The shop section to show it in.
- Status (`state`, text): Publish the listing (Active) or hide it (Inactive). Publishing charges Etsy's listing fee and needs at least one image. One of: `inactive` (Inactive (hidden from buyers)), `active` (Active (published: Etsy charges its listing fee)).

**Outputs**

- `listing` (object): An Etsy listing

**Example output**

```json
{
  "listing": {
    "created_timestamp": 1761307200,
    "description": "A 12 oz stoneware mug, thrown and glazed by hand.",
    "has_variations": false,
    "is_supply": false,
    "listing_id": 1234567890,
    "listing_type": "physical",
    "materials": [
      "stoneware"
    ],
    "num_favorers": 0,
    "price": {
      "amount": 2450,
      "currency_code": "USD",
      "divisor": 100
    },
    "quantity": 5,
    "readiness_state_id": 1402336022581,
    "return_policy_id": 1066663425433,
    "shipping_profile_id": 198765432101,
    "shop_id": 30123456,
    "shop_section_id": null,
    "state": "draft",
    "tags": [
      "ceramic mug",
      "handmade"
    ],
    "taxonomy_id": 1063,
    "title": "Handmade ceramic mug, speckled white",
    "updated_timestamp": 1761307200,
    "url": "https://www.etsy.com/listing/1234567890/handmade-ceramic-mug",
    "when_made": "made_to_order",
    "who_made": "i_did"
  }
}
```

### Update price and quantity

Set a listing's price or quantity, or one variation's by its SKU. Everything else in the listing's inventory stays as it is.

**Inputs**

- Listing (`listing_id`, text, required): The listing. Pick one, or give its ID from an earlier step.
- Price (`price`, number): The new price in your shop's currency, such as 24.50. At least 0.01.
- Quantity (`quantity`, number): How many are for sale, 0 to 999. From 0 to 999.
- Variation SKU (`sku`, text): For a listing with variations, the SKU of the one to change. Leave empty for a listing without variations.

**Outputs**

- `inventory` (object): The inventory exactly as Etsy gives it
- `listing_id` (number): The listing's ID
- `products` (list): Its products, one per variation

**Example output**

```json
{
  "inventory": {
    "price_on_property": [],
    "products": [
      {
        "is_deleted": false,
        "offerings": [
          {
            "is_deleted": false,
            "is_enabled": true,
            "offering_id": 16012345678,
            "price": {
              "amount": 2450,
              "currency_code": "USD",
              "divisor": 100
            },
            "quantity": 5,
            "readiness_state_id": 1402336022581
          }
        ],
        "product_id": 15012345678,
        "property_values": [],
        "sku": "MUG-WHT"
      }
    ],
    "quantity_on_property": [],
    "readiness_state_on_property": [],
    "sku_on_property": []
  },
  "listing_id": 1234567890,
  "products": [
    {
      "currency_code": "USD",
      "is_enabled": true,
      "price": 24.5,
      "product_id": 15012345678,
      "quantity": 5,
      "sku": "MUG-WHT",
      "variations": []
    }
  ]
}
```

### Update shop

Change your shop's heading, announcement, the messages buyers get after a purchase, or its additional policies. Only what you fill in changes.

**Inputs**

- Heading (`title`, text): The short heading on your shop's page.
- Announcement (`announcement`, text): The announcement on your shop's page.
- Message to buyers (`sale_message`, text): The message buyers get after they order.
- Message to buyers of digital items (`digital_sale_message`, text): The message buyers get after ordering a digital download.
- Additional policies (`policy_additional`, text): Your shop's additional policies and FAQs.

**Outputs**

- `shop` (object): The connected Etsy shop

**Example output**

```json
{
  "shop": {
    "announcement": "New autumn glazes are in.",
    "created_timestamp": 1514764800,
    "currency_code": "USD",
    "digital_sale_message": null,
    "is_vacation": false,
    "listing_active_count": 42,
    "policy_additional": null,
    "review_average": 4.9,
    "review_count": 318,
    "sale_message": "Thank you for your order!",
    "shipping_from_country_iso": "US",
    "shop_id": 30123456,
    "shop_name": "SpeckledClay",
    "title": "Handmade stoneware for everyday",
    "transaction_sold_count": 1290,
    "url": "https://www.etsy.com/shop/SpeckledClay",
    "user_id": 812345678
  }
}
```
