- 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
- Item Catalog v3 API reference documentation
- Python client library documentation
- Full Item Catalog 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
- Install the python client library via the terminal:
pip install --upgrade recurly
- Obtain your private API key from the API Credentials page
- Export your data into a CSV file with the attributes listed above.
- Create a python client:
import recurly api_key = 'your_api_key' client = recurly.Client(api_key)
-
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)
- 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)