### Install etsy-ts

Source: https://context7.com/granga/etsy-ts/llms.txt

Install the etsy-ts library using npm or yarn.

```bash
npm install etsy-ts
# or
yarn add etsy-ts
```

--------------------------------

### End-to-End Example

Source: https://context7.com/granga/etsy-ts/llms.txt

Demonstrates a complete workflow: authentication, shop retrieval, draft listing creation, image upload, and activation.

```APIDOC
## End-to-End Example

### Description
Combining multiple modules: authenticate, find the shop, create a draft listing, upload an image, and mark it active.

### Workflow
```typescript
import * as fs from "fs-extra";
import { Etsy } from "etsy-ts";
import { SecurityDataStorage } from "./SecurityDataStorage";

(async () => {
  const client = new Etsy({
    apiKey: process.env.ETSY_API_KEY!,
    sharedSecret: process.env.ETSY_SHARED_SECRET!,
    securityDataStorage: new SecurityDataStorage(),
  });

  const etsyUserId = 92841371;

  try {
    // 1. Verify connectivity
    await client.Other.ping();

    // 2. Get authenticated user + their shop
    const { data: me } = await client.User.getMe({ etsyUserId });
    const { data: shop } = await client.Shop.getShopByOwnerUserId(me.user_id!, { etsyUserId });

    // 3. Create a draft listing
    const { data: draft } = await client.ShopListing.createDraftListing(
      { shopId: shop.shop_id! },
      {
        title: "Hand-Thrown Ceramic Mug",
        description: "Wheel-thrown stoneware, dishwasher safe.",
        price: 38.00,
        quantity: 10,
        who_made: "i_did",
        when_made: "made_to_order",
        taxonomy_id: 1,
      },
      { etsyUserId }
    );

    // 4. Upload an image
    await client.ShopListingImage.uploadListingImage(
      shop.shop_id!,
      draft.listing_id!,
      { image: fs.createReadStream("./mug.jpg"), rank: 1 },
      { etsyUserId }
    );

    // 5. Activate the listing
    await client.ShopListing.updateListing(
      { shopId: shop.shop_id!, listingId: draft.listing_id! },
      { state: "active" },
      { etsyUserId }
    );

    console.log("Listing live:", draft.listing_id);
  } catch (err: any) {
    console.error("Error:", err.response?.data || err.message);
  }
})();
```
```

--------------------------------

### Implement ISecurityDataStorage

Source: https://context7.com/granga/etsy-ts/llms.txt

Implement the ISecurityDataStorage interface to manage OAuth2 tokens. This example uses a JSON file for storage.

```typescript
import fs from "fs-extra";
import { ISecurityDataStorage, Tokens } from "etsy-ts";
import { SecurityDataFilter } from "etsy-ts/src/types/SecurityDataFilter";

type SecurityDataItem = Tokens & { etsyUserId: number };

export class SecurityDataStorage implements ISecurityDataStorage {
  filepath = "./security-data.json";

  async storeAccessToken(filter: SecurityDataFilter, tokens: Tokens): Promise<void> {
    const all: SecurityDataItem[] = fs.existsSync(this.filepath)
      ? await fs.readJson(this.filepath)
      : [];

    const etsyUserId = parseInt(tokens.accessToken.split(".")[0]);
    const index = all.findIndex((item) => item.etsyUserId === etsyUserId);

    const entry = { etsyUserId, ...tokens };
    if (index === -1) all.push(entry);
    else all[index] = entry;

    await fs.writeJSON(this.filepath, all, { spaces: 2 });
  }

  async findAccessToken(filter: SecurityDataFilter): Promise<Tokens | undefined> {
    if (!fs.existsSync(this.filepath)) return undefined;
    const all: SecurityDataItem[] = (await fs.readJson(this.filepath)) || [];
    return all.find((item) => item.etsyUserId === filter.etsyUserId);
  }
}
```

--------------------------------

### End-to-End Etsy Listing Creation and Activation

Source: https://context7.com/granga/etsy-ts/llms.txt

A comprehensive example showing the workflow from authentication and shop retrieval to creating a draft listing, uploading an image, and finally activating the listing. This requires Etsy API credentials, a SecurityDataStorage implementation, and an image file named 'mug.jpg'.

```typescript
import * as fs from "fs-extra";
import { Etsy } from "etsy-ts";
import { SecurityDataStorage } from "./SecurityDataStorage";

(async () => {
  const client = new Etsy({
    apiKey: process.env.ETSY_API_KEY!,
    sharedSecret: process.env.ETSY_SHARED_SECRET!,
    securityDataStorage: new SecurityDataStorage(),
  });

  const etsyUserId = 92841371;

  try {
    // 1. Verify connectivity
    await client.Other.ping();

    // 2. Get authenticated user + their shop
    const { data: me } = await client.User.getMe({ etsyUserId });
    const { data: shop } = await client.Shop.getShopByOwnerUserId(me.user_id!, { etsyUserId });

    // 3. Create a draft listing
    const { data: draft } = await client.ShopListing.createDraftListing(
      { shopId: shop.shop_id! },
      {
        title: "Hand-Thrown Ceramic Mug",
        description: "Wheel-thrown stoneware, dishwasher safe.",
        price: 38.00,
        quantity: 10,
        who_made: "i_did",
        when_made: "made_to_order",
        taxonomy_id: 1,
      },
      { etsyUserId }
    );

    // 4. Upload an image
    await client.ShopListingImage.uploadListingImage(
      shop.shop_id!,
      draft.listing_id!,
      { image: fs.createReadStream("./mug.jpg"), rank: 1 },
      { etsyUserId }
    );

    // 5. Activate the listing
    await client.ShopListing.updateListing(
      { shopId: shop.shop_id!, listingId: draft.listing_id! },
      { state: "active" },
      { etsyUserId }
    );

    console.log("Listing live:", draft.listing_id);
  } catch (err: any) {
    console.error("Error:", err.response?.data || err.message);
  }
})();
```

--------------------------------

### Get Taxonomy Properties by ID

Source: https://context7.com/granga/etsy-ts/llms.txt

Fetches allowed product properties (e.g., color, size) and their valid values for a given taxonomy node ID. Requires a valid taxonomy node ID.

```typescript
const { data: properties } = await client.BuyerTaxonomy.getPropertiesByBuyerTaxonomyId(1);
properties.results?.forEach(p => console.log(p.name, p.possible_values?.map(v => v.name)));
```

--------------------------------

### Get Buyer Taxonomy Category Tree

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves the complete Etsy buyer taxonomy hierarchy. Useful for identifying the correct `taxonomy_id` when creating listings. Filters for top-level categories.

```typescript
const { data: taxonomy } = await client.BuyerTaxonomy.getBuyerTaxonomyNodes();
const topLevel = taxonomy.results?.filter(n => n.level === 0);
topLevel?.forEach(n => console.log(n.id, n.name));
// 68887045  "Accessories"
// 68887046  "Art & Collectibles"
// ...
```

--------------------------------

### Get Authenticated User Info

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves basic identity information for the user associated with the OAuth2 token. Requires etsyUserId in request parameters.

```typescript
const etsyUserId = 92841371;
const { data: me } = await client.User.getMe({ etsyUserId });
console.log(me.user_id, me.login_name);
```

--------------------------------

### Initialize Etsy Client

Source: https://context7.com/granga/etsy-ts/llms.txt

Instantiate the Etsy client with API credentials and a security data storage implementation. Token refresh is enabled by default.

```typescript
import { Etsy } from "etsy-ts";
import { SecurityDataStorage } from "./SecurityDataStorage"; // your implementation

const client = new Etsy({
  apiKey: "your_api_key",
  sharedSecret: "your_shared_secret",          // required since Etsy v7 / Jan 2026
  securityDataStorage: new SecurityDataStorage(),
  enableTokenRefresh: true,                    // default: true
});
```

--------------------------------

### Create and List Shop Sections with etsy-ts

Source: https://context7.com/granga/etsy-ts/llms.txt

Demonstrates how to create a new shop section and then retrieve all sections within a shop. Requires shop_id for operations.

```typescript
import { ShopSection } from "etsy-ts";

// Create a section
const { data: section } = await client.ShopSection.createShopSection(
  shop.shop_id!,
  { title: "Mugs & Cups" },
  { etsyUserId }
);
console.log(section.shop_section_id);

// List all sections
const { data: sections } = await client.ShopSection.getShopSections(shop.shop_id!);
sections.results?.forEach(s => console.log(s.shop_section_id, s.title));
```

--------------------------------

### Create a Draft Listing

Source: https://context7.com/granga/etsy-ts/llms.txt

Creates a new physical draft listing. Requires a shipping profile and return policy to be set for activation. Includes parameters for title, description, price, quantity, and more.

```typescript
const { data: draft } = await client.ShopListing.createDraftListing(
  { shopId: shop.shop_id! },
  {
    title: "Hand-Thrown Ceramic Mug",
    description: "Each mug is unique, wheel-thrown and kiln-fired.",
    price: 38.00,
    quantity: 5,
    who_made: "i_did",
    when_made: "made_to_order",
    taxonomy_id: 1,
  },
  { etsyUserId }
);
console.log(draft.listing_id, draft.state);
```

--------------------------------

### ShopListing.getListing

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves a single listing with optional associated data (images, shipping, etc.).

```APIDOC
## ShopListing.getListing — Fetch Single Listing

### Description
Retrieves a single listing with optional associated data (images, shipping, etc.).

### Method
GET (assumed based on common REST practices for retrieving a single resource)

### Endpoint
/v3/listings/{listing_id}

### Parameters
#### Path Parameters
- **listing_id** (number) - Required - The numeric ID of the listing to retrieve.
#### Query Parameters
- **includes** (array of strings) - Optional - Specifies associated data to include (e.g., ["Images", "ShippingProfile"]).

### Request Example
```typescript
const { data: listing } = await client.ShopListing.getListing(
  { listingId: 987654321, includes: ["Images", "ShippingProfile"] }
);
console.log(listing.title, listing.price);
```

### Response
#### Success Response (200)
- **listing_id** (number) - The unique identifier for the listing.
- **title** (string) - The title of the listing.
- **price** (string) - The price of the listing.
```

--------------------------------

### ShopSection

Source: https://context7.com/granga/etsy-ts/llms.txt

Organizes listings into sections by creating and listing shop sections.

```APIDOC
## ShopSection — Organize Listings into Sections

### Description
Create a new shop section and then list all sections in the shop.

### Create Section
```typescript
import { ShopSection } from "etsy-ts";

// Create a section
const { data: section } = await client.ShopSection.createShopSection(
  shop.shop_id!,
  { title: "Mugs & Cups" },
  { etsyUserId }
);
console.log(section.shop_section_id);
```

### List Sections
```typescript
// List all sections
const { data: sections } = await client.ShopSection.getShopSections(shop.shop_id!);
sections.results?.forEach(s => console.log(s.shop_section_id, s.title));
```
```

--------------------------------

### ShopListingImage.uploadListingImage (Buffer)

Source: https://context7.com/granga/etsy-ts/llms.txt

Uploads an image from a Buffer by wrapping it in a PassThrough stream.

```APIDOC
## ShopListingImage.uploadListingImage — Upload from Buffer

### Description
Uploads an image from a Buffer by wrapping it in a PassThrough stream, including necessary metadata.

### Method
POST (assumed based on upload operation)

### Endpoint
`/shops/{shop_id}/listings/{listing_id}/images` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.
- **listing_id** (integer) - Required - The ID of the listing.

#### Request Body
- **image** (ReadableStream) - Required - The image stream created from a Buffer.

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
import { PassThrough } from "stream";
import * as fs from "fs-extra";

const imageBuffer = await fs.readFile("./photo.png");
const imageStream = new PassThrough();
imageStream.end(imageBuffer);
Object.assign(imageStream, { path: "./photo.png", filename: "photo.png", mimetype: "image/png" });

const { data: image } = await client.ShopListingImage.uploadListingImage(
  shop.shop_id!,
  listing.listing_id!,
  { image: imageStream as any },
  { etsyUserId }
);
```

### Response
#### Success Response (200)
- **listing_image_id** (integer) - The ID of the uploaded listing image.
- **url_fullxfull** (string) - The URL of the full-size image.
```

--------------------------------

### ShopListing.createDraftListing

Source: https://context7.com/granga/etsy-ts/llms.txt

Creates a new physical draft listing. Requires a shipping profile and return policy to activate.

```APIDOC
## ShopListing.createDraftListing — Create a Draft Listing

### Description
Creates a new physical draft listing. Requires a shipping profile and return policy to activate.

### Method
POST (assumed based on common REST practices for creating resources)

### Endpoint
/v3/shops/{shop_id}/listings/draft

### Parameters
#### Path Parameters
- **shop_id** (number) - Required - The numeric ID of the shop where the draft listing will be created.
#### Request Body
- **title** (string) - Required - The title of the listing.
- **description** (string) - Required - The description of the listing.
- **price** (number) - Required - The price of the listing.
- **quantity** (number) - Required - The available quantity of the listing.
- **who_made** (string) - Required - Indicates who made the item (e.g., "i_did").
- **when_made** (string) - Required - Indicates when the item was made (e.g., "made_to_order").
- **taxonomy_id** (number) - Required - The ID of the relevant category for the listing.
#### Query Parameters
- **etsyUserId** (number) - Required - The numeric ID of the Etsy user making the request, used for authentication and permissions.

### Request Example
```typescript
const { data: draft } = await client.ShopListing.createDraftListing(
  { shopId: shop.shop_id! },
  {
    title: "Hand-Thrown Ceramic Mug",
    description: "Each mug is unique, wheel-thrown and kiln-fired.",
    price: 38.00,
    quantity: 5,
    who_made: "i_did",
    when_made: "made_to_order",
    taxonomy_id: 1,
  },
  { etsyUserId }
);
console.log(draft.listing_id, draft.state);
// 112233445  "draft"
```

### Response
#### Success Response (200)
- **listing_id** (number) - The unique identifier for the newly created draft listing.
- **state** (string) - The current state of the listing (should be "draft").
```

--------------------------------

### Batch Fetch Listings

Source: https://context7.com/granga/etsy-ts/llms.txt

Fetches up to 100 listings by their IDs in a single request. Requires a list of listing IDs.

```typescript
const { data } = await client.ShopListing.getListingsByListingIds(
  { listing_ids: [111111, 222222, 333333] }
);
data.results?.forEach(l => console.log(l.listing_id, l.title));
```

--------------------------------

### Create Shipping Profile

Source: https://context7.com/granga/etsy-ts/llms.txt

Creates a reusable shipping profile for listings. Requires details like title, origin, costs, and processing times. Ensure all required fields are provided.

```typescript
const { data: profile } = await client.ShopShippingProfile.createShopShippingProfile(
  shop.shop_id!,
  {
    title: "Standard US Shipping",
    origin_country_iso: "US",
    primary_cost: 5.00,
    secondary_cost: 2.00,
    destination_country_iso: "US",
    min_processing_time: 1,
    max_processing_time: 3,
    processing_time_unit: "business_days",
  },
  { etsyUserId }
);
console.log(profile.shipping_profile_id);
```

--------------------------------

### Search Shops by Name

Source: https://context7.com/granga/etsy-ts/llms.txt

Searches for Etsy shops by name and returns a paginated list of results.

```typescript
const { data: shops } = await client.Shop.findShops(
  { shop_name: "handmade ceramics", limit: 10, offset: 0 }
);
shops.results?.forEach(s => console.log(s.shop_id, s.shop_name));
```

--------------------------------

### Upload Listing Image using File Stream

Source: https://context7.com/granga/etsy-ts/llms.txt

Uploads an image file to a listing using a readable file stream. Ensure the file exists at the specified path.

```typescript
import * as fs from "fs-extra";

const { data: image } = await client.ShopListingImage.uploadListingImage(
  shop.shop_id!,
  listing.listing_id!,
  { image: fs.createReadStream("./photo.jpg"), rank: 1 },
  { etsyUserId }
);
console.log(image.listing_image_id, image.url_fullxfull);
```

--------------------------------

### ShopReceipt.createReceiptShipment

Source: https://context7.com/granga/etsy-ts/llms.txt

Submits shipment tracking information for an order and notifies the buyer.

```APIDOC
## ShopReceipt.createReceiptShipment — Mark Order Shipped

### Description
Submits shipment tracking for an order. Etsy sends a shipping notification email to the buyer.

### Method
POST (assumed based on creation/update operation)

### Endpoint
`/shops/{shop_id}/receipts/{receipt_id}/shipments` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.
- **receipt_id** (integer) - Required - The ID of the receipt.

#### Request Body
- **tracking_code** (string) - Required - The shipment tracking code.
- **carrier_name** (string) - Required - The name of the shipping carrier.
- **send_bcc** (boolean) - Optional - Whether to send a BCC email to the seller.
- **note_to_buyer** (string) - Optional - A message to include in the shipping notification.

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
const { data: updatedReceipt } = await client.ShopReceipt.createReceiptShipment(
  { shopId: shop.shop_id!, receiptId: 9988776655 },
  {
    tracking_code: "9400111899223397238466",
    carrier_name: "usps",
    send_bcc: true,
    note_to_buyer: "Your order is on its way!",
  },
  { etsyUserId }
);
console.log(updatedReceipt.status);  // "shipped"
```

### Response
#### Success Response (200)
- **status** (string) - The updated status of the receipt, expected to be "shipped".
```

--------------------------------

### ShopListing.updateListingProperty

Source: https://context7.com/granga/etsy-ts/llms.txt

Assigns a product property value (such as color or size) to a listing.

```APIDOC
## ShopListing.updateListingProperty — Set Listing Property

### Description
Assigns a product property value (such as color or size) to a listing.

### Method
```typescript
await client.ShopListing.updateListingProperty(
  shop.shop_id!,
  listing.listing_id!,
  200,          // property_id for "Color"
  {
    value_ids: [1213],   // value_id for "Red"
    values: ["Red"],
    scale_id: null,
  },
  { etsyUserId }
);
```
```

--------------------------------

### Check Etsy API Connectivity

Source: https://context7.com/granga/etsy-ts/llms.txt

Use the Other.ping endpoint to confirm your API key is valid and the application can reach the Etsy Open API. This is useful for startup health checks.

```typescript
const { data: pong } = await client.Other.ping();
console.log(pong);
// { application_id: 12345 }
```

--------------------------------

### Upload Listing Image from Buffer

Source: https://context7.com/granga/etsy-ts/llms.txt

Uploads an image from a Buffer by wrapping it in a PassThrough stream and adding necessary metadata. Ensure the buffer contains valid image data.

```typescript
import { PassThrough } from "stream";
import * as fs from "fs-extra";

const imageBuffer = await fs.readFile("./photo.png");
const imageStream = new PassThrough();
imageStream.end(imageBuffer);
Object.assign(imageStream, { path: "./photo.png", filename: "photo.png", mimetype: "image/png" });

const { data: image } = await client.ShopListingImage.uploadListingImage(
  shop.shop_id!,
  listing.listing_id!,
  { image: imageStream as any },
  { etsyUserId }
);
```

--------------------------------

### User.getMe

Source: https://context7.com/granga/etsy-ts/llms.txt

Returns basic identity information for the user whose OAuth2 token is being used. Pass `etsyUserId` in the request params so the library fetches the correct token from storage.

```APIDOC
## User.getMe — Authenticated User Info

### Description
Returns basic identity information for the user whose OAuth2 token is being used. Pass `etsyUserId` in the request params so the library fetches the correct token from storage.

### Method
GET (assumed based on common REST practices for retrieving user info)

### Endpoint
/v3/users/me

### Parameters
#### Query Parameters
- **etsyUserId** (number) - Required - The numeric ID of the Etsy user.

### Request Example
```typescript
const etsyUserId = 92841371;
const { data: me } = await client.User.getMe({ etsyUserId });
console.log(me.user_id, me.login_name);
// 92841371  "myshopname"
```

### Response
#### Success Response (200)
- **user_id** (number) - The unique identifier for the user.
- **login_name** (string) - The user's login name.
```

--------------------------------

### ShopListing.findAllListingsActive

Source: https://context7.com/granga/etsy-ts/llms.txt

Returns a paginated list of all active listings across Etsy, newest-first by default.

```APIDOC
## ShopListing.findAllListingsActive — Browse All Active Listings

### Description
Returns a paginated list of all active listings across Etsy, newest-first by default.

### Method
GET (assumed based on common REST practices for searching/browsing resources)

### Endpoint
/v3/listings/active

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of results to return (default: 25).
- **offset** (number) - Optional - The number of results to skip (for pagination).
- **keywords** (string) - Optional - Filters listings by keywords.

### Request Example
```typescript
const { data } = await client.ShopListing.findAllListingsActive(
  { limit: 20, offset: 0, keywords: "ceramic mug" }
);
data.results?.forEach(l => console.log(l.listing_id, l.title));
```

### Response
#### Success Response (200)
- **results** (array) - A list of active listing objects.
  - **listing_id** (number) - The unique identifier for the listing.
  - **title** (string) - The title of the listing.
```

--------------------------------

### ShopReceipt.getShopReceipts

Source: https://context7.com/granga/etsy-ts/llms.txt

Fetches a paginated list of shop receipts (orders) with optional filtering.

```APIDOC
## ShopReceipt.getShopReceipts — Fetch Orders

### Description
Returns a paginated list of shop receipts (orders), with optional filtering by paid/shipped status and date range.

### Method
GET (assumed based on retrieval operation)

### Endpoint
`/shops/{shop_id}/receipts` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.

#### Query Parameters
- **was_paid** (boolean) - Optional - Filter by paid status.
- **was_shipped** (boolean) - Optional - Filter by shipped status.
- **limit** (integer) - Optional - The number of results to return.
- **offset** (integer) - Optional - The starting offset for pagination.

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
const { data: receipts } = await client.ShopReceipt.getShopReceipts(
  {
    shopId: shop.shop_id!,
    was_paid: true,
    was_shipped: false,
    limit: 25,
    offset: 0,
  },
  { etsyUserId }
);
receipts.results?.forEach(r =>
  console.log(r.receipt_id, r.buyer_user_id, r.grandtotal?.amount)
);
```

### Response
#### Success Response (200)
- **results** (array) - An array of receipt objects.
  - **receipt_id** (integer) - The ID of the receipt.
  - **buyer_user_id** (integer) - The ID of the buyer.
  - **grandtotal** (object) - The total amount of the order.
    - **amount** (number) - The order total amount.
    - **currency_code** (string) - The currency code.
```

--------------------------------

### Update Shop Settings

Source: https://context7.com/granga/etsy-ts/llms.txt

Updates shop metadata including title, announcement, and sale message. Requires shop ID and etsyUserId.

```typescript
const { data: updated } = await client.Shop.updateShop(
  shop.shop_id!,
  {
    title: "Handmade Ceramics Studio",
    announcement: "Free shipping on orders over $50!",
    sale_message: "Thank you for your purchase!",
  },
  { etsyUserId }
);
console.log(updated.title);
```

--------------------------------

### BuyerTaxonomy.getBuyerTaxonomyNodes

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves the complete Etsy buyer taxonomy hierarchy.

```APIDOC
## BuyerTaxonomy.getBuyerTaxonomyNodes — Get Category Tree

### Description
Returns the full Etsy buyer taxonomy hierarchy, used to pick the correct `taxonomy_id` when creating listings.

### Method
GET (assumed based on retrieval operation)

### Endpoint
`/taxonomies/categories` (assumed based on context)

### Parameters
(No parameters specified in the source.)

### Request Example
```typescript
const { data: taxonomy } = await client.BuyerTaxonomy.getBuyerTaxonomyNodes();
const topLevel = taxonomy.results?.filter(n => n.level === 0);
topLevel?.forEach(n => console.log(n.id, n.name));
// 68887045  "Accessories"
// 68887046  "Art & Collectibles"
// ...
```

### Response
#### Success Response (200)
- **results** (array) - An array of taxonomy nodes.
  - **id** (integer) - The ID of the taxonomy node.
  - **name** (string) - The name of the taxonomy node.
  - **level** (integer) - The level of the node in the hierarchy.
```

--------------------------------

### Manual TokenRefresher Usage

Source: https://context7.com/granga/etsy-ts/llms.txt

Manually initialize TokenRefresher if you are not using the default Etsy client constructor. This is typically needed when building a custom HttpClient.

```typescript
import { TokenRefresher } from "etsy-ts";
import { SecurityDataStorage } from "./SecurityDataStorage";

// Manual usage (only needed if you build your own HttpClient):
const storage = new SecurityDataStorage();
const refresher = new TokenRefresher(
  "your_api_key",
  axiosInstance,   // your AxiosInstance
  storage
);
refresher.init();
// Interceptor is now active; 401 responses trigger a silent token refresh.
```

--------------------------------

### Shop.findShops

Source: https://context7.com/granga/etsy-ts/llms.txt

Searches Etsy shops by name and returns a paginated list.

```APIDOC
## Shop.findShops — Search Shops by Name

### Description
Searches Etsy shops by name and returns a paginated list.

### Method
GET (assumed based on common REST practices for searching shops)

### Endpoint
/v3/shops

### Parameters
#### Query Parameters
- **shop_name** (string) - Required - The name or partial name of the shop to search for.
- **limit** (number) - Optional - The maximum number of results to return (default: 25).
- **offset** (number) - Optional - The number of results to skip (for pagination).

### Request Example
```typescript
const { data: shops } = await client.Shop.findShops(
  { shop_name: "handmade ceramics", limit: 10, offset: 0 }
);
shops.results?.forEach(s => console.log(s.shop_id, s.shop_name));
```

### Response
#### Success Response (200)
- **results** (array) - A list of shop objects matching the search criteria.
  - **shop_id** (number) - The unique identifier for the shop.
  - **shop_name** (string) - The name of the shop.
- **count** (number) - The total number of shops found.
```

--------------------------------

### Fetch Single Listing

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves a single Etsy listing by its ID. Can include associated data like images and shipping profiles.

```typescript
const { data: listing } = await client.ShopListing.getListing(
  { listingId: 987654321, includes: ["Images", "ShippingProfile"] }
);
console.log(listing.title, listing.price);
```

--------------------------------

### ShopListing.getListingsByListingIds

Source: https://context7.com/granga/etsy-ts/llms.txt

Fetches up to 100 listings by their IDs in a single request.

```APIDOC
## ShopListing.getListingsByListingIds — Batch Fetch Listings

### Description
Fetches up to 100 listings by their IDs in a single request.

### Method
GET (assumed based on common REST practices for batch retrieval)

### Endpoint
/v3/listings/batch

### Parameters
#### Query Parameters
- **listing_ids** (array of numbers) - Required - A comma-separated string or array of up to 100 listing IDs to retrieve.

### Request Example
```typescript
const { data } = await client.ShopListing.getListingsByListingIds(
  { listing_ids: [111111, 222222, 333333] }
);
data.results?.forEach(l => console.log(l.listing_id, l.title));
```

### Response
#### Success Response (200)
- **results** (array) - A list of listing objects matching the provided IDs.
  - **listing_id** (number) - The unique identifier for the listing.
  - **title** (string) - The title of the listing.
```

--------------------------------

### BuyerTaxonomy.getPropertiesByBuyerTaxonomyId

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves allowed product properties and their values for a given taxonomy node.

```APIDOC
## BuyerTaxonomy.getPropertiesByBuyerTaxonomyId — Get Taxonomy Properties

### Description
Returns the allowed product properties (color, size, material, etc.) and their valid values for a specific taxonomy node ID.

### Method
GET (assumed based on retrieval operation)

### Endpoint
`/taxonomies/categories/{taxonomy_id}/properties` (assumed based on context)

### Parameters
#### Path Parameters
- **taxonomy_id** (integer) - Required - The ID of the taxonomy node.

### Request Example
```typescript
const { data: properties } = await client.BuyerTaxonomy.getPropertiesByBuyerTaxonomyId(1);
properties.results?.forEach(p => console.log(p.name, p.possible_values?.map(v => v.name)));
```

### Response
#### Success Response (200)
- **results** (array) - An array of property objects.
  - **name** (string) - The name of the property (e.g., "color").
  - **possible_values** (array) - An array of possible values for the property.
    - **name** (string) - The name of the possible value.
```

--------------------------------

### Fetch Orders (Shop Receipts)

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves a paginated list of orders for a shop, with options to filter by payment and shipping status, and date range. Ensure shopId is valid.

```typescript
const { data: receipts } = await client.ShopReceipt.getShopReceipts(
  {
    shopId: shop.shop_id!,
    was_paid: true,
    was_shipped: false,
    limit: 25,
    offset: 0,
  },
  { etsyUserId }
);
receipts.results?.forEach(r =>
  console.log(r.receipt_id, r.buyer_user_id, r.grandtotal?.amount)
);
```

--------------------------------

### List Listing Images

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves all images associated with a specific listing. The results may be paginated.

```typescript
const { data: images } = await client.ShopListingImage.getListingImages(listingId);
images.results?.forEach(img => console.log(img.listing_image_id, img.url_570xN));
```

--------------------------------

### ShopListing.getListingsByShop

Source: https://context7.com/granga/etsy-ts/llms.txt

Returns all listings belonging to a shop, with optional filtering by state.

```APIDOC
## ShopListing.getListingsByShop — List Shop Listings

### Description
Returns all listings belonging to a shop, with optional filtering by state.

### Method
GET (assumed based on common REST practices for retrieving listings)

### Endpoint
/v3/shops/{shop_id}/listings

### Parameters
#### Path Parameters
- **shop_id** (number) - Required - The numeric ID of the shop whose listings to retrieve.
#### Query Parameters
- **state** (string) - Optional - Filters listings by their state (e.g., "active", "inactive").
- **limit** (number) - Optional - The maximum number of results to return (default: 25).
- **offset** (number) - Optional - The number of results to skip (for pagination).
- **etsyUserId** (number) - Required - The numeric ID of the Etsy user making the request, used for authentication and permissions.

### Request Example
```typescript
const { data: { results: listings, count } } = await client.ShopListing.getListingsByShop(
  { shopId: shop.shop_id!, state: "active", limit: 25, offset: 0 },
  { etsyUserId }
);
console.log(`Found ${count} listings`);
listings?.forEach(l => console.log(l.listing_id, l.title));
```

### Response
#### Success Response (200)
- **results** (array) - A list of listing objects belonging to the shop.
  - **listing_id** (number) - The unique identifier for the listing.
  - **title** (string) - The title of the listing.
- **count** (number) - The total number of listings found.
```

--------------------------------

### Shop.updateShop

Source: https://context7.com/granga/etsy-ts/llms.txt

Updates shop metadata such as title, announcement, and sale message.

```APIDOC
## Shop.updateShop — Update Shop Settings

### Description
Updates shop metadata such as title, announcement, and sale message.

### Method
PUT (assumed based on common REST practices for updating resources)

### Endpoint
/v3/shops/{shop_id}

### Parameters
#### Path Parameters
- **shop_id** (number) - Required - The numeric ID of the shop to update.
#### Request Body
- **title** (string) - Optional - The new title for the shop.
- **announcement** (string) - Optional - The new announcement message for the shop.
- **sale_message** (string) - Optional - The new sale message for the shop.
#### Query Parameters
- **etsyUserId** (number) - Required - The numeric ID of the Etsy user making the request, used for authentication and permissions.

### Request Example
```typescript
const { data: updated } = await client.Shop.updateShop(
  shop.shop_id!,
  {
    title: "Handmade Ceramics Studio",
    announcement: "Free shipping on orders over $50!",
    sale_message: "Thank you for your purchase!",
  },
  { etsyUserId }
);
console.log(updated.title);
```

### Response
#### Success Response (200)
- **title** (string) - The updated title of the shop.
```

--------------------------------

### Shop.getShop

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves a shop record by its numeric shop ID.

```APIDOC
## Shop.getShop — Fetch Shop by ID

### Description
Retrieves a shop record by its numeric shop ID.

### Method
GET (assumed based on common REST practices for retrieving shop info)

### Endpoint
/v3/shops/{shop_id}

### Parameters
#### Path Parameters
- **shop_id** (number) - Required - The numeric ID of the shop to retrieve.

### Request Example
```typescript
const { data: shop } = await client.Shop.getShop(12345678);
console.log(shop.shop_name, shop.listing_active_count);
```

### Response
#### Success Response (200)
- **shop_id** (number) - The unique identifier for the shop.
- **shop_name** (string) - The name of the shop.
- **listing_active_count** (number) - The number of currently active listings in the shop.
```

--------------------------------

### ShopListingImage.uploadListingImage (File Stream)

Source: https://context7.com/granga/etsy-ts/llms.txt

Uploads an image file to a listing using a readable file stream.

```APIDOC
## ShopListingImage.uploadListingImage — Upload an Image File Stream

### Description
Uploads an image file to a listing using a readable file stream.

### Method
POST (assumed based on upload operation)

### Endpoint
`/shops/{shop_id}/listings/{listing_id}/images` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.
- **listing_id** (integer) - Required - The ID of the listing.

#### Request Body
- **image** (ReadableStream) - Required - The image file stream.
- **rank** (integer) - Optional - The display order of the image.

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
import * as fs from "fs-extra";

const { data: image } = await client.ShopListingImage.uploadListingImage(
  shop.shop_id!,
  listing.listing_id!,
  { image: fs.createReadStream("./photo.jpg"), rank: 1 },
  { etsyUserId }
);
console.log(image.listing_image_id, image.url_fullxfull);
```

### Response
#### Success Response (200)
- **listing_image_id** (integer) - The ID of the uploaded listing image.
- **url_fullxfull** (string) - The URL of the full-size image.
```

--------------------------------

### ShopShippingProfile.createShopShippingProfile

Source: https://context7.com/granga/etsy-ts/llms.txt

Creates a reusable shipping profile for listings.

```APIDOC
## ShopShippingProfile.createShopShippingProfile — Create Shipping Profile

### Description
Creates a reusable shipping profile that can be attached to many listings.

### Method
POST (assumed based on creation operation)

### Endpoint
`/shops/{shop_id}/shipping/profiles` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.

#### Request Body
- **title** (string) - Required - The name of the shipping profile.
- **origin_country_iso** (string) - Required - The ISO code of the origin country.
- **primary_cost** (number) - Required - The primary shipping cost.
- **secondary_cost** (number) - Optional - The secondary shipping cost.
- **destination_country_iso** (string) - Required - The ISO code of the destination country.
- **min_processing_time** (integer) - Required - The minimum processing time.
- **max_processing_time** (integer) - Required - The maximum processing time.
- **processing_time_unit** (string) - Required - The unit for processing time (e.g., "business_days").

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
const { data: profile } = await client.ShopShippingProfile.createShopShippingProfile(
  shop.shop_id!,
  {
    title: "Standard US Shipping",
    origin_country_iso: "US",
    primary_cost: 5.00,
    secondary_cost: 2.00,
    destination_country_iso: "US",
    min_processing_time: 1,
    max_processing_time: 3,
    processing_time_unit: "business_days",
  },
  { etsyUserId }
);
console.log(profile.shipping_profile_id);
```

### Response
#### Success Response (200)
- **shipping_profile_id** (integer) - The ID of the created shipping profile.
```

--------------------------------

### List Shop Listings

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves all active listings for a specific shop. Supports filtering by state and pagination.

```typescript
const { data: { results: listings, count } } = await client.ShopListing.getListingsByShop(
  { shopId: shop.shop_id!, state: "active", limit: 25, offset: 0 },
  { etsyUserId }
);
console.log(`Found ${count} listings`);
listings?.forEach(l => console.log(l.listing_id, l.title));
```

--------------------------------

### Other.ping — Connectivity Check

Source: https://context7.com/granga/etsy-ts/llms.txt

Confirms that your API key is valid and the application can reach the Etsy Open API. Useful as a health check at startup.

```APIDOC
## Other.ping — Connectivity Check

### Description
Confirms that your API key is valid and the application can reach the Etsy Open API. Useful as a health check at startup.

### Method
GET

### Endpoint
/v3/other/ping

### Request Example
```typescript
const { data: pong } = await client.Other.ping();
console.log(pong);
```

### Response
#### Success Response (200)
- **application_id** (number) - The application ID.

### Response Example
```json
{
  "application_id": 12345
}
```
```

--------------------------------

### ShopListingImage.getListingImages

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves all images associated with a specific listing.

```APIDOC
## ShopListingImage.getListingImages — List Listing Images

### Description
Returns all images attached to a given listing.

### Method
GET (assumed based on retrieval operation)

### Endpoint
`/shops/{shop_id}/listings/{listing_id}/images` (assumed based on context)

### Parameters
#### Path Parameters
- **listing_id** (integer) - Required - The ID of the listing.

#### Query Parameters
- **shop_id** (integer) - Required - The ID of the shop.

### Request Example
```typescript
const { data: images } = await client.ShopListingImage.getListingImages(listingId);
images.results?.forEach(img => console.log(img.listing_image_id, img.url_570xN));
```

### Response
#### Success Response (200)
- **results** (array) - An array of listing image objects.
  - **listing_image_id** (integer) - The ID of the listing image.
  - **url_570xN** (string) - The URL of the 570px wide image.
```

--------------------------------

### Browse All Active Listings

Source: https://context7.com/granga/etsy-ts/llms.txt

Returns a paginated list of all active listings across Etsy, ordered by newest first by default. Supports filtering by keywords.

```typescript
const { data } = await client.ShopListing.findAllListingsActive(
  { limit: 20, offset: 0, keywords: "ceramic mug" }
);
data.results?.forEach(l => console.log(l.listing_id, l.title));
```

--------------------------------

### ShopReceipt.getShopReceipt

Source: https://context7.com/granga/etsy-ts/llms.txt

Fetches a single order receipt by its ID.

```APIDOC
## ShopReceipt.getShopReceipt — Fetch Single Receipt

### Description
Fetches a single order receipt by receipt ID.

### Method
GET (assumed based on retrieval operation)

### Endpoint
`/shops/{shop_id}/receipts/{receipt_id}` (assumed based on context)

### Parameters
#### Path Parameters
- **shop_id** (integer) - Required - The ID of the shop.
- **receipt_id** (integer) - Required - The ID of the receipt.

#### Headers
- **x-etsy-user-id** (string) - Required - The Etsy User ID for authentication.

### Request Example
```typescript
const { data: receipt } = await client.ShopReceipt.getShopReceipt(
  { shopId: shop.shop_id!, receiptId: 9988776655 },
  { etsyUserId }
);
console.log(receipt.status, receipt.grandtotal?.amount);
```

### Response
#### Success Response (200)
- **status** (string) - The status of the order.
- **grandtotal** (object) - The total amount of the order.
  - **amount** (number) - The order total amount.
  - **currency_code** (string) - The currency code.
```

--------------------------------

### ShopListing.updateListing

Source: https://context7.com/granga/etsy-ts/llms.txt

Patches a listing's fields. Also used to publish a draft listing by setting `state: "active"`.

```APIDOC
## ShopListing.updateListing — Update a Listing

### Description
Patches a listing's fields. Also used to publish a draft listing by setting `state: "active"`.

### Method
PUT (assumed based on common REST practices for updating resources)

### Endpoint
/v3/shops/{shop_id}/listings/{listing_id}

### Parameters
#### Path Parameters
- **shop_id** (number) - Required - The numeric ID of the shop containing the listing.
- **listing_id** (number) - Required - The numeric ID of the listing to update.
#### Request Body
- **title** (string) - Optional - The new title for the listing.
- **price** (number) - Optional - The new price for the listing.
- **state** (string) - Optional - The new state for the listing (e.g., "active" to publish).
#### Query Parameters
- **etsyUserId** (number) - Required - The numeric ID of the Etsy user making the request, used for authentication and permissions.

### Request Example
```typescript
await client.ShopListing.updateListing(
  { shopId: shop.shop_id!, listingId: draft.listing_id! },
  {
    title: "Hand-Thrown Ceramic Mug – Updated",
    price: 42.00,
    state: "active",
  },
  { etsyUserId }
);
```

### Response
#### Success Response (200)
(No specific response fields mentioned in the source, typically returns the updated listing object or a success status.)
```

--------------------------------

### Fetch Shop by ID

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves a shop record using its numeric shop ID.

```typescript
const { data: shop } = await client.Shop.getShop(12345678);
console.log(shop.shop_name, shop.listing_active_count);
```

--------------------------------

### Fetch Shop by Owner User ID

Source: https://context7.com/granga/etsy-ts/llms.txt

Retrieves the shop owned by a specific Etsy user ID. Useful when only the authenticated user's ID is known.

```typescript
const { data: me } = await client.User.getMe({ etsyUserId });
const { data: shop } = await client.Shop.getShopByOwnerUserId(me.user_id!, { etsyUserId });
console.log(shop.shop_id, shop.shop_name);
```