|
…
|
||
|---|---|---|
| .. | ||
| apiDefinition.swagger.json | ||
| apiProperties.json | ||
| readme.md | ||
readme.md
Etsy
This connector uses your API key to access various Etsy.com features. It supports actions for inventory, sales orders, and shop management. All actions are based on Etsy Open API v3 which does have endpoints that are still in beta. If such actions use the beta API, the action with include Beta in the title and will return a 501 response code.
Publisher: Troy Taylor, Hitachi Solutions
Prerequisites
An Etsy Developer account connected to your store and an API key. Be sure to review the API rate limits, especially the 10 queries per second limit, and the API testing policy.
Obtaining Credentials
The API key is generated by registering a personal/development app with Etsy which gives you essential access to only your shop using the V3 endpoints. More information about obtaining your API key can be found here and information about essential access can be found here. Please note that OAuth 2.0 access is not supported due to the PCKE requirement.
Supported Operations
Ping
Check to confirm connectivity to the Etsy API with an application.
Listing Management
Create a draft listing
Creates a physical draft listing product in a shop on the Etsy channel.
Create a listing translation
Creates a listing translation by listing ID and language.
Delete a file from listing
When you delete the final file for a digital listing, the listing converts into a physical listing. The response to a delete request returns a list of the remaining file records associated with the given listing.
Delete a listing
This action deletes a shop listing. A listing can be deleted only if the state is one of the following: SOLD_OUT, DRAFT, EXPIRED, INACTIVE, ACTIVE and is_available or ACTIVE and has seller flags: SUPRESSED (frozen), VACATION, CUSTOM_SHOPS (pattern), SELL_ON_FACEBOOK.
Delete a listing image
Deletes a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image.
Delete a listing property
Deletes a property from a listing.
Get active listings
A list of all active listings on Etsy paginated by their creation date. Without sort order listings will be returned newest-first by default.
Get featured listings by shop
Retrieves listings associated to a shop that are featured.
Get a file from a listing
Retrieves a single file associated with the given digital listing. Requesting a file from a physical listing returns an empty result.
Get a listing
Retrieves a listing record by listing ID.
Get a listing image
Retrieves the references and metadata for a listing image with a specific image ID.
Get a listing's images
Retrieves all listing image resources for a listing with a specific listing ID.
Get a listing's inventory
Retrieves the inventory record for a listing. Listings you did not edit using the Etsy.com inventory tools have no inventory records. This endpoint returns SKU data if you are the owner of the inventory records being fetched.
Get a listing's offering
Get an offering for a listing.
Get a listing's product
Retrieve a listing product by ID.
Get a listing's properties
Returns a list of a listing's properties.
Get a listing's property (Beta)
Retrieves a listing's property. Development for this endpoint is in progress. It will only return a 501 response.
Get a listing's translation
Returns the translation for a listing in the given language.
Get listing's variation images
Gets all variation images on a listing.
Get all listing files
Retrieves all the files associated with the given digital listing. Requesting files from a physical listing returns an empty result.
Get listings by ID
Allows to query multiple listing IDs at once. Limit 100 IDs maximum per query.
Get listings by shop
Returns listings that belong to a Shop. Listings can be filtered using the state parameter.
Get listings by shop receipt
Gets all listings associated with a receipt.
Get listings by shop section ID
Retrieves all the listings from the section of a specific shop.
Get product properties by taxonomy ID
Retrieves a list of product properties, with applicable scales and values, supported for a specific seller taxonomy ID.
Get seller taxonomy nodes
Retrieves the full hierarchy tree of seller taxonomy nodes.
Update a listing
Updates a listing, identified by a listing ID, for a specific shop identified by a shop ID.
Update a listing property
Updates or populates the properties list defining product offerings for a listing. Each offering requires both a value and a value ID that are valid for a scale ID assigned to the listing or that you assign to the listing with this request.
Update a listing translation
Updates a listing translation by listing ID and language.
Update a listing's inventory
Updates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product SKU, offering quantity, and/or price are incompatible with values in on property fields. When setting a price, assign a float equal to amount divided by divisor as specified in the money resource.
Update a listing's variation images
Creates variation images on a listing.
Upload a listing file
Uploads a new file for a digital listing, or associates an existing file with a specific listing. You must either provide the listing file ID of an existing file, or the name and binary file data for a file to upload. Associating an existing file to a physical listing converts the physical listing into a digital listing, which removes all shipping costs and any product and inventory variations.
Upload a listing image
Uploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the image parameter. You can assign a previously deleted image to a listing using the deleted image's image ID in the listing image ID parameter. When a request contains both image and listing image ID parameter values, the endpoint uploads the image in the image parameter only.
Payment Management
Get a list of payments
Retrieves a list of payments from a shop identified by shop ID. You can also filter results using a list of payment IDs.
Get a payment from a payment account ledger entry ID
Get a Payment from a Payment Account Ledger Entry ID, if applicable.
Get a payment from a specific receipt
Retrieves a payment from a specific receipt, identified by receipt ID, from a specific shop, identified by shop ID.
Get a shop payment account ledger's entries
Retrieve the entries of a shop's payment account ledger.
Receipt Management
Create a Shipment Receipt
Submits tracking information for a shop receipt, which creates a shop receipt Shipment entry for the given receipt ID. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send BCC is true, Etsy sends shipping notifications to the seller as well. When tracking code and carrier name aren't sent, the receipt is marked as shipped only.
Get receipts
Requests the shop receipts from a specific shop, unfiltered or filtered by receipt ID range or offset, date, paid, and/or shipped purchases.
Get a receipt
Retrieves a receipt, identified by a receipt ID, from an Etsy shop.
Get a receipt's transaction
Retrieves the list of transactions associated with a specific receipt.
Get a shop's transaction
Retrieves the list of transactions associated with a shop.
Get a transaction
Retrieves a transaction by transaction ID.
Retrieve a listing's transactions
Retrieves the list of transactions associated with a listing.
Review Management
Get reviews
Retrieves the reviews from a shop given its ID.
Shipping Management
Create a shipping profile
Creates a new shipping profile. You can pass a country ISO code or a region when creating a shipping profile, but not both. Only one is required. You must pass either a shipping carrier ID and mail class, or both min and max delivery days.
Create a shipping profile destination
Creates a new shipping destination, which sets the shipping cost, carrier, and class for a destination in a shipping profile. This assigns costs using the currency of the associated shop. Set the destination using either destination country ISO or destination region; destination country ISO and destination region are mutually exclusive — set one or the other. Setting both triggers error 400. If the request sets neither destination country ISO nor destination region, the default destination is everywhere. You must also either assign both a shipping carrier ID and mail class or both min delivery days and max delivery days.
Create a shipping profile upgrade
Creates a new shipping profile upgrade, which can establish a price for a shipping option, such as an alternate carrier or faster delivery.
Delete a shipping profile
Deletes a shipping profile by given ID.
Delete a shipping profile destination
Deletes a shipping destination and removes the destination option from every listing that uses the associated shipping profile. A shipping profile requires at least one shipping destination, so this endpoint cannot delete the final shipping destination for any shipping profile. To delete the final shipping destination from a shipping profile, you must delete the entire shipping profile.
Delete a shipping profile upgrade
Deletes a shipping profile upgrade and removes the upgrade option from every listing that uses the associated shipping profile.
Get shipping carriers
Retrieves a list of available shipping carriers and the mail classes associated with them for a given country.
Get profile destinations by shipping profile
Retrieves a list of shipping destination objects associated with a shipping profile.
Get shipping profiles
Retrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.
Get shipping profile upgrades
Retrieves the list of shipping profile upgrades assigned to a specific shipping profile.
Get a shipping profile
Retrieves a shipping profile referenced by shipping profile ID.
Update a shipping profile
Changes the settings in a shipping profile.
Update a shipping profile destination
Updates an existing shipping destination, which can set or reassign the shipping cost, carrier, and class for a destination.
Update a shipping profile upgrade
Updates a shipping profile upgrade and updates any listings that use the shipping profile.
Shop Management
Create a shop section
Creates a new section in a specific shop.
Get shop by owner ID
Retrieves the shop identified by the shop owner's user ID.
Get shop sections
Retrieves the list of shop sections in a specific shop identified by shop ID.
Get shop section
Retrieves a shop section, referenced by section ID and shop ID.
Search shops
Returns a list of shops with the matching name.
Update a shop
Update a shop. Assumes that all string parameters are provided in the shop's primary language.
User Management
Get user
Returns user profile for the user identified by a user ID.
Get user addresses
Retrieve a list of user addresses.
Get user's address
Retrieves the user's address. Development for this endpoint is in progress. It will only return a 501 response.
Known Issues and Limitations
There are no known issues at this time. Please note that some v3 APIs are still in beta and will return a 501 response. Please note that OAuth 2.0 access is not supported due to the PCKE requirement.