Multi-item upload guide

This guide will walk you through the process of importing all of your items from your existing item management system into Recurly’s Item Catalog.

We are excited for you to use our Item Catalog, and we understand you may already be managing your offerings in a database or another Product Information Management system. If you’re unable to sync all of your items via our API, manually adding each item might seem overwhelming. However, that’s not the case! You can easily add all your items at once by following this step-by-step guide (or skip to the end for an executable script).

Requirements

• CSV file of your data
• Python 3
• Text editor
• Recurly Python client library
• API key

Reference documentation

• Item Catalog v3 API documentation
• Python client library documentation
• Full Item Catalog documentation

Data Preparation

Start by exporting data from your database or inventory management system and create a CSV file with the following fields. The columns can appear in any order.

Here’s a sample CSV to give you an idea of what your input should look like:

code,name,description,external_sku,accounting_code,tax_exempt,tax_code,default_price,currency
code1,name1,This is an item.,sku1,acc1,true,,12.99,USD
code2,name2,This is another item.,sku2,acc2,true,,150.00,USD
code3,name3,This is a taxable item.,sku3,acc3,false,taxme,250.00,USD
code4,name4,This is an item but with no default price.,sku4,acc4,true,,,

Step by step data import

1. Install the python client library via the terminal: pip install --upgrade recurly
2. Obtain your private API key from the API Credentials page.
3. Export your data into a CSV file with the attributes listed above.
4. Create a python client:

    import recurly
    api_key = 'your_api_key'
    client = recurly.Client(api_key)
   

5. Iterate through your CSV using the Create Item action.

    import csv
    file = open('items.csv')
    csv_file = csv.DictReader(file)
   
    # iterate over your csv file and create one item per row
    for item in csv_file:
        currency = item.pop('currency', 'USD')
        unit_amount = item.pop('default_price', None)
        if unit_amount is not "":
            item['currencies'] = [{'currency': currency, 'unit_amount': unit_amount}]
        try:
            created_item = client.create_item(item)
            print("Created Item %s" % created_item)
        except recurly.ApiError as e:
            print("Could not Create item " % item)
            print(e)
   

6. Verify that all the items were successfully imported.

     items = client.list_items().items()
     for item in items:
     print(item.code)
   

   You may also verify your items in the Recurly Admin UI

Resources

You can find a complete script here to upload your item catalog into Recurly. Simply pass your API key and the CSV file name as arguments to the script, then run it. The finished script is shown below.

You may need to chmod +x ./upload_items.py after downloading it to make it executable.

Run with ./upload_items.py <key> <input>

#!/usr/bin/env python3

# Usage: upload_items.py api_key input.csv
import sys
import csv
import recurly

# first argument to the script
api_key = sys.argv[1]
# second argument to the script
file = open(sys.argv[2])
client = recurly.Client(api_key)

csv_file = csv.DictReader(file)

# iterate over your csv file and create one item per row
for item in csv_file:
    currency = item.pop('currency', 'USD')
    unit_amount = item.pop('default_price', None)
    if unit_amount is not "":
        item['currencies'] = [{'currency': currency, 'unit_amount': unit_amount}]
    try:
        created_item = client.create_item(item)
        print("Created Item %s" % created_item)
    except recurly.ApiError as e:
        print("Could not Create item " % item)
        print(e)