• Content

Multi Item Upload Guide

The purpose of this guide is to showcase the process that will allow you to import all of the items from your existing item management system into Recurly’s Item Catalog.

We hope that you are as excited to use our Item Catalog as we are to release it, but you may already be managing your offerings in a database or other Product Information Management system. If you’re not able to leverage our API to sync all of your items, you might imagine it could be a hassle to go through the UI and add every single item by hand but that’s not the case! To add all your items into your new Recurly Item Catalog at once, just follow this step-by-step guide (or scroll to the end for an executable).

Requirements


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

Reference Documentation


Data Preparation


Starting with an export of data from your database or inventory management system, create a CSV that has the following fields. The columns can be in any order.

Column Required? Type Description
code Yes String Unique code to identify the item. Max 50 characters.
name Yes String Item name. Max 255 characters.
description No String Optional description, not displayed.
external_sku No String Optional stock keeping unit to link the item to other systems. Max 50 characters.
accounting_code No String Optional accounting code for invoice line items. Code may only contain the following characters: [a-z 0-9 @ - _ .]. Max 20 characters.
revenue_schedule_type No String Determines how revenue should be recognized. Available schedule types: never, evenly, at_range_start, at_range_end.
tax_exempt No Boolean true exempts tax to the item, false applies tax to the item.
tax_code No String Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. Max 50 characters.
default_price No Number Default price of the item. Uses the site’s default currency; cannot upload an item with prices in multiple currencies.
currency Yes* String Currency code for the price provided. Required if default_price has a value. Examples: USD, EUR, AUD

Here’s a sample CSV to give you an idea of what your input CSV 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 that you can use to upload your catalog of items into Recurly. Simply pass the API key and CSV file name as arguments to the script and run. The finished script is presented 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)

Finished!