Working With Resources

Fields

Each resource type contains a number of fields; those with the visibility level of "public" are available through both the public and private entry points, those with the visibility level "private" are only available through the private entry point.

In addition, you can control which fields are returned using the standard parameter fields:

/v2/listings/active?fields=listing_id,title,price

(Note: only the fields you explicitly request will be returned. This applies to all fields including IDs.)

Associations

Each resource has one or more associations that can be included using the standard includes parameter:

/v2/listings/active?includes=Images

Multiple associations can be separated with commas:

/v2/listings/active?includes=Images,Shop

In addition, associations can specify limit/offset parameters. The following example loads only the first image (limit 1, offset 0:)

/v2/listings/active?includes=Images:1:0

You can also specify which fields of an association are returned:

/v2/listings/active?includes=Images(url_75x75,hex_code)

Finally, associations can be nested up to three levels deep, using slashes:

/v2/listings/active?includes=Shop/User
/v2/shops/etsystore?includes=Listings:1:0/Images

Scopes

Scopes define a subset of resources according to a condition. For instance, the "active" scope of listings specifies that the "state" field of each listing must be "active" (these are listings that are still for sale on Etsy and are not sold out or expired.)

Scopes are typically appended to the resource name in a URL:

/v2/listings/active
/v2/shops/etsystore/listings/active

Scopes can also be used when including associations, and can be combined with limit/offset parameters:

/v2/shops/etsystore?includes=Listings:active
/v2/shops/etsystore?includes=Listings:active:1:0

Association Syntax

For reference, here's the complete Association inclusion syntax. Elements in [square brackets] are optional.

?includes=Association[(fieldname[,fieldname...])][:scope][:limit[:offset]][,Assocation...]