Managing Inventory and Product Variants with the Etsy API (with Python Examples)
By: Nicole Dow
Tags: Programming, Rest Api, Inventory Software, Etsy, Python

Authenticate Yourself with OAuth So You Can Manage Inventory

I will save a deep dive into how to get an OAuth token for Etsy for another post, but this Etsy Documentation is a good place to start.

You will need to save an OAth1 session object to a variable. For this you will need your app’s API key, your app’s API secret, and the shop’s OAuth token and token secret for this app.

from requests_oauthlib import OAuth1Session def create_etsy_session(self):

session = OAuth1Session(API_KEY, API_SECRET, self.token,

self.token_secret) return session

Create an Etsy Listing

If you already have an etsy listing, you just need the listing_id , which can be found in your listing’s URL, right after /listing .

Otherwise, create an Etsy listing via a simple POST request to https://openapi.etsy.com/v2/listings , with a simple Python dictionary converted to JSON as the request body. The example below will include some comments explaining what certain fields signify. For more information, visit the Etsy listing documentation here.

*Please note all request URLs for the Etsy API will begin with https://openapi.etsy.com/v2/

import requests

import json etsy = self.create_etsy_session() listing_data = {

'quantity': 999, # a maximum of 1000 is allowed

'title': 'Merry Christmas Ornament',

'description': 'A beautiful hand-painted ornament',

'price': 14.99,

'shipping_template_id': 1234,

'taxonomy_id': int(self.etsy_taxonomy_id),

'state': 'draft',

'who_made': 'i_did',

'is_supply': False,

'when_made': 'made_to_order',

'write_missing_inventory': True,

'item_height': 3,

'item_length': 3,

'item_width': 3,

'item_dimensions_unit': 'in',

'item_weight_unit': 'oz',

'item_weight': 2

}

request_url = 'https://openapi.etsy.com/v2/listings'

etsy.post(request_url, listing_data)

A few notes on listing pushes in Etsy:

A default shipping template ID is required. This is how Etsy will know what shipping information to display in your listing. If you don’t have a shipping template, create one via a POST request to /shipping/templates , as described here in the createShippingTemplate method.

request to , as described here in the method. The keys who_made , is_supply , and when_made are required by Etsy and only accept certain string values, which you can find here under the respective fields.

Updating the Inventory and Setting Variant Data

Etsy once supported “Variations”, i.e. specific combinations of product attributes such as Size and Color. Now, the concept of a variant is tied to the ListingInventory and ListingOffering endpoints.

The ListingInventory endpoint returns an array of products (among other information), which represent these combinations of attributes, with information on how many of each combination are in stock.

At this time, you cannot update the inventory for just one specific product. You must completely replace the inventory with all your products and their quantity data each time the inventory is updated.

How you determine your variants will depend on your database structure and your application. You will need to serialize all your product attributes and inventory quantities into a dictionary that looks like this:

inventory = [

{

'sku': 'product1sku',

'property_values': [

{

'property_id': 100,

'property_name': 'Size',

'values': ['Medium']

},

{

'property_id': 100,

'property_name': 'Color',

'values': ['Pink']

}

],

'offerings': [

{'price': variant_price, 'quantity': 10}

]

}

]

A few notes on the above code:

The example inventory array has only one inventory item — a medium pink shirt. You will need an object like this one for each combination of size and color.

array has only one inventory item — a medium pink shirt. You will need an object like this one for each combination of size and color. The property_ids are not random — they are predefined by Etsy. If you know the taxonomy classification you want to sell your product in, you can find the available property ids via a call to GET /taxonomy/seller/:taxonomy_id/properties . See here for more information.

Now, we will add this array, as JSON, to the ‘products’ key in the rest of our request body. We will then set up an OAuth client (a little differently this time, as Etsy gets picky with PUT requests).

Our final request will look like this:

from requests_oauthlib import oauth1

import json

import requests inventory_request_data = {

'listing_id': 1234567,

'products': json.dumps(inventory),

'price_on_property': #here, add the property_id of any attribute that determines price

} client = oauth1.Client(API_KEY, API_SECRET, token, token_secret, signature_method=SIGNATURE_PLAINTEXT) req_url = 'https://openapi.etsy.com/v2/listings/%s/inventory'%(listing_id) uri, headers, body = client.sign(req_url) headers['Content-Type'] = 'application/x-www-form-urlencoded' r = requests.session()

r.put(uri, headers=headers, data=inventory_request_data)

One thing to watch out for here is that if you add a property to the “price_on_property” key, you must keep your pricing consistent for all variants with a specific property value attached to this property. For example, if you say the price depends on size, all of your “small” shirts must align in price and all your “medium” shirts must align in price, and so on and so forth.

And voilà ! Your Etsy inventory is updated.