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

# Etsy fields

> Which Etsy field each Your shop field comes from, how Alura normalizes it, and which Etsy fields are left out

Your shop objects carry the data Alura syncs from Etsy's v3 API. Where Etsy's name is clear, the API keeps it: `title`, `description`, `tags`, `materials`, `state`, `quantity`, `skus`, `who_made`, `when_made`, `is_supply` and the like. This page lists every field whose name or shape changes, and the Etsy fields left out.

The Etsy column shows the field as Alura stores it from Etsy, which follows Etsy's v3 names.

## How fields are normalized

| Etsy | Alura | Notes |
| - | - | - |
| Epoch timestamps (`creation_timestamp`, `paid_timestamp`, ...) | `*_at`, ISO 8601 in UTC | `created_at`, `updated_at`, `paid_at` and so on. |
| Money as `{amount, divisor, currency_code}` | `{amount, currency, usd}` | `amount` is a decimal string, such as `"24.99"`. `usd` is its US dollar value at today's rate, `null` when Alura has no rate. Shop settings money has no `usd`. |
| `num_favorers` | `favorites` | |
| `taxonomy_id` | `category {id, path}` | `path` is the category's names from the top, from Alura's category tree. |
| `-1` and other placeholders, empty strings | `null` | A value Etsy didn't give is `null`, never `0` or `""`. |
| Numeric IDs | Strings | Etsy IDs are strings, such as `"22841907"`. One exception: a shipping profile's `shipping_carrier_id` stays a number, as Etsy sends it. |

## Listings

| Etsy | Alura | Notes |
| - | - | - |
| `listing_id` | `id` | |
| `shop_id` | `shop_id` | |
| `price` | `price` | `{amount, currency, usd}`. `null` when Etsy's amount or divisor isn't usable. |
| `shop_section_id` | `section.id` | `section.title` is the section's title. |
| `views` | `views` | Etsy's lifetime count. |
| `num_favorers` | `favorites` | Etsy's lifetime count. |
| `original_creation_timestamp` (or `creation_timestamp`) | `created_at` | |
| `last_modified_timestamp` (or `updated_timestamp`) | `updated_at` | |
| `ending_timestamp` | `ends_at` | Detail only. |
| `taxonomy_id` | `category {id, path}` | Detail only. |
| `listing_type` | `is_digital` | `true` for `download` or `both`, `false` for `physical`, `null` when unknown. |
| `processing_min`, `processing_max` | `processing {min_days, max_days}` | |
| `item_length`, `item_width`, `item_height`, `item_dimensions_unit`, `item_weight`, `item_weight_unit` | `dimensions` | A value of 0 or less is `null`. |
| `featured_rank` | Not shown | The `featured` filter matches a listing that has a featured rank. |

Detail also keeps `description`, `tags`, `materials`, `skus`, `has_variations`, `who_made`, `when_made`, `is_supply`, `is_personalizable`, `language`, `shipping_profile_id`, `return_policy_id` and `should_auto_renew` under Etsy's names.

**Alura adds:** `image_url` (the first photo), `reviews {count, average}` from the stored reviews, `sales` and `period` from your orders ([Listing stats](/methodology/listing-stats)), and `listing_score` ([Listing score](/methodology/listing-score)). Etsy has none of these per listing.

### Images and videos

| Etsy | Alura | Notes |
| - | - | - |
| `listing_image_id` | `images[].id` | Up to 100, by `rank`. |
| `url_fullxfull` | `images[].url` | |
| `url_570xN` | `images[].thumbnail_url` | Also the listing's `image_url`, from the first photo. |
| `full_width`, `full_height` | `images[].width`, `images[].height` | |
| `alt_text`, `rank` | `images[].alt_text`, `images[].rank` | |
| `video_id` | `videos[].id` | Up to 20. Deleted videos are left out. |
| `video_url` | `videos[].url` | |
| `video_state` | `videos[].state` | |
| `thumbnail_url`, `width`, `height` | `videos[].thumbnail_url`, `videos[].width`, `videos[].height` | |

### Expansions

Each block carries its own `as_of`. A block Alura hasn't fetched yet is `null` with `{block}_error: "not_fetched"`, never an empty list; a stored block Alura can't read is `null` with `{block}_error: "unreadable"`.

| Etsy | Alura | Notes |
| - | - | - |
| Inventory `products[]` | `inventory.products[]` | `product_id` becomes `id`. `sku` and `property_values[]` keep Etsy's names. Deleted products are left out. |
| Inventory `offerings[]` | `inventory.products[].offerings[]` | `offering_id` becomes `id`. `price` is `{amount, currency, usd}`. `quantity` and `is_enabled` keep their names. Deleted offerings are left out. |
| Property values | `attributes.values[]` | `property_id`, `property_name`, `scale_id`, `scale_name`, `value_ids` and `values`, as in inventory. |
| Translations, keyed by language | `translations.languages[]` | One item per language: `{language, title, description, tags}`, sorted by language. |
| `personalization_questions` | `personalization.questions[]` | `question_id`, `question_type` and `question_text` become `id`, `type` and `text`. `max_allowed_characters` and `max_allowed_files` become `max_characters` and `max_files`. `instructions` and `required` keep their names. |
| Variation images | `variation_images.images[]` | `property_id`, `value_id`, `value`, `image_id`. |

### Left out

`user_id`, the photo colour fields, digital `file_data`, `featured_rank` (see above), and Alura's own lifetime figures that would mislead: the `monthly_*` averages, `conversion_rate` (lifetime views against a partial count of orders) and `sold_count`.

## Orders

An order is Etsy's receipt. Its `items` are Etsy's transactions.

| Etsy | Alura | Notes |
| - | - | - |
| `receipt_id` | `id` | |
| `status` | `status` | Lower case with `_`: `paid`, `completed`, `open`, `payment_processing`, `canceled`, `fully_refunded`, `partially_refunded`. Etsy can add others. |
| `is_paid`, `is_shipped` | `paid`, `shipped` | |
| `was_delivered` | `delivered` | |
| `create_timestamp` | `created_at` | |
| `update_timestamp` | `updated_at` | Detail only. |
| `buyer_user_id` | `buyer.id` | `null` for a guest buyer. |
| `name` | `buyer.name`, `shipping_address.name` | |
| `first_line`, `second_line` | `shipping_address.line1`, `shipping_address.line2` | |
| `city`, `state`, `zip` | `shipping_address.city`, `.state`, `.zip` | |
| `country_iso` | `shipping_address.country` | |
| `formatted_address` | `shipping_address.formatted` | |
| `is_gift`, `gift_message`, `message_from_buyer`, `message_from_seller`, `payment_method` | Same names | Over MCP, the messages come only with `expand`. |
| `subtotal`, `total_shipping_cost`, `total_tax_cost`, `total_vat_cost`, `discount_amt`, `gift_wrap_price`, `grandtotal` | `totals.subtotal`, `.shipping`, `.tax`, `.vat`, `.discount`, `.gift_wrap`, `.grand_total` | `{amount, currency, usd}`. The summary has `grand_total`. |

**Alura adds:** `item_count` (the sum of the items' quantities), `items[].image_url`, and `shipping_address_error`, which says why `shipping_address` is `null`: `etsy_restricted`, `no_physical_items` or `not_fetched`.

### Items, shipments, refunds and payment

| Etsy | Alura | Notes |
| - | - | - |
| `transaction_id` | `items[].id` | |
| `listing_id`, `title`, `quantity`, `sku`, `is_digital` | `items[].listing_id`, `.title`, `.quantity`, `.sku`, `.is_digital` | |
| `price` | `items[].price` | The price of one unit. |
| `shipping_cost` | `items[].shipping_cost` | |
| `variations` | `items[].variations` | `null` for now: Alura doesn't store them yet. |
| `paid_timestamp`, `shipped_timestamp` | `items[].paid_at`, `items[].shipped_at` | |
| Shipment `carrier_name`, `tracking_code` | `shipments[].carrier`, `shipments[].tracking_code` | |
| Shipment `shipment_notification_timestamp` | `shipments[].notified_at` | |
| Refund `amount`, `reason`, `status` | `refunds[].amount`, `.reason`, `.status` | |
| Refund `created_timestamp` | `refunds[].created_at` | |
| Payment `amount_gross`, `amount_fees`, `amount_net` | `payment.gross`, `payment.fees`, `payment.net` | With `expand=payment`. `null` with `payment_error`: `not_fetched` (no payment stored), `currency_unknown` (the payment's or the order's currency isn't stored), `currency_unverified` (the payment's currency differs from the order's) or `amount_unreadable` (one of gross, fees or net can't be read, so the whole payment is withheld). |

### Left out

`buyer_email`, `seller_email`, `payment_email`, `message_from_payment`, `receipt_type`, `seller_user_id`, Alura's internal IDs, the items' `file_data`, `buyer_user_id` and coupons, the shipments' `mail_class`, the refunds' `note_from_issuer`, and every payment field except the three amounts.

## Shops

| Etsy | Alura | Notes |
| - | - | - |
| `shop_id` | `id` | |
| `shop_name` | `name` | |
| `icon_url_fullxfull` | `icon_url` | |
| `image_url_760x100` | `banner_url` | |
| `currency_code` | `currency` | The currency of the shop's listings. Shop stats use the payment account's currency, which can differ. |
| `shop_location_country_iso` | `country` | |
| `create_date` | `opened_at` | |
| `is_vacation` | `on_vacation` | |
| `listing_active_count`, `digital_listing_count` | `catalog.active_listings`, `catalog.digital_listings` | |
| `num_favorers` | `favorites` | |
| `review_count`, `review_average` | `reviews.count`, `reviews.average` | `average` is `null` with no reviews. |
| `transaction_sold_count` | `sales.lifetime_units` | Etsy's own count. |
| `policy_welcome`, `policy_payment`, `policy_shipping`, `policy_refunds`, `policy_additional`, `policy_privacy` | `policies.welcome`, `.payment`, `.shipping`, `.refunds`, `.additional`, `.privacy` | |
| `policy_update_date` | `policies.updated_at` | |

`url`, `title`, `announcement`, `sale_message`, `digital_sale_message`, `languages`, `vacation_message` and `accepts_custom_requests` keep Etsy's names.

**Alura adds:** `connection` (whether the Etsy connection works, and what it allows), `sync` and `coverage`. See [Connect a shop and sync it](/guides/your-shop-connect-and-sync) and [Coverage](/guides/your-shop-coverage).

**Left out:** `login_name`, the seller and payment emails, `policy_seller_info`, Etsy's onboarding flags and internal IDs.

## Shop settings

Every settings object carries `fetched_at`, when Alura last fetched that kind of setting from Etsy.

| Etsy | Alura | Notes |
| - | - | - |
| Section `shop_section_id` | `id` | |
| Section `title`, `rank` | `title`, `rank` | |
| Section `active_listing_count` | `active_listings` | As Etsy gave it when Alura fetched the sections. |
| Shipping profile `shipping_profile_id` | `id` | |
| `origin_country_iso` | `origin_country` | |
| `min_processing_days`, `max_processing_days`, `processing_days_display_label` | `processing.min_days`, `.max_days`, `.label` | |
| Destination `shipping_profile_destination_id` | `destinations[].id` | |
| `destination_country_iso` | `destination_country` | `destination_region` keeps its name: `eu`, `non_eu` or `none`. |
| `primary_cost`, `secondary_cost` | `primary_cost`, `secondary_cost` | `{amount, currency}`. `null`, with a `shipping_cost_inexact` notice, when Etsy's amount has more decimals than the currency. It's never rounded. |
| Upgrade `upgrade_id`, `upgrade_name` | `upgrades[].id`, `upgrades[].name` | |
| Upgrade `type` | `upgrades[].type` | `0` is `domestic`, `1` is `international`. |
| Upgrade `price`, `secondary_price` | `price`, `secondary_price` | `{amount, currency}`. |
| `shipping_carrier_id`, `mail_class`, `min_delivery_days`, `max_delivery_days`, `rank`, `language` | Same names | |
| Return policy `return_policy_id` | `id` | |
| `accepts_returns`, `accepts_exchanges` | Same names | |
| `return_deadline` | `return_deadline_days` | |
| Processing profile `readiness_state_definition_id` | `id` | |
| `readiness_state` | `readiness_state` | `ready_to_ship` or `made_to_order`. |
| `min_processing_time`, `max_processing_time`, `processing_time_unit` | `min`, `max`, `unit` | `unit` is `days` or `weeks`. |
| Holiday `holiday_id`, `country_iso`, `holiday_name`, `is_working` | `holidays[].id`, `.country`, `.name`, `.is_working` | Etsy keeps holidays for US and Canadian shops only. |
| Production partner `production_partner_id`, `partner_name`, `location` | `id`, `name`, `location` | |

**Alura adds:** `listings_count` on a return policy, which Alura counts from your synced listings.

**Left out:** the shipping profile's `origin_postal_code`, `profile_type`, `domestic_handling_fee` and `international_handling_fee`, and user IDs.

## Changes

A change records a write to a listing made through Alura, with its fields' before and after values. Its field names are the listing's own Alura names, which differ from what the Alura app stores in a few places:

| Stored | In `fields[].field` | Notes |
| - | - | - |
| `taxonomy_id` | `category_id` | |
| `shop_section_id` | `section_id` | |
| `item_weight`, `item_length`, `item_width`, `item_height` | `dimensions.weight`, `.length`, `.width`, `.height` | |
| `item_weight_unit`, `item_dimensions_unit` | `dimensions.weight_unit`, `dimensions.unit` | |
| `renewal_option` | `should_auto_renew` | `automatic` is `true`, `manual` is `false`. |
| `personalization_questions` | `personalization` | |
| An attribute by property ID | `attributes[<id>]` | |
| A translation's title, description or tags | `translations[<language>].title`, and so on | |

IDs in a change, such as `category_id` and `section_id`, are strings. Any other stored field is reported as `other`.

## Next steps

> **[What Your shop can't do](/your-shop/limits)**
>
> What Etsy's API doesn't allow, and what isn't in this version.

> **[Buyer data](/guides/your-shop-buyer-data)**
>
> Which fields are your buyers' data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.