Importing into Perch Shop

Runway 3 added support for importing content into Collections and today we’re building on that by opening up those import mechanisms to be used by Runway add-ons too.

One of our most-requested features on the Shop Roadmap has been a way to import products, and it made sense to take the same approach for Shop as we have for Collections. Instead of requiring your content be formatted into some sort of data file like a CSV or XML document, we’ve provided a simple PHP API that enables a developer to take any type of source and push the data directly into your shop.

For this initial version, we have support for programmatically adding Products, Brands, Currencies and Countries, and have added the importing of Assets to go alongside Collections.

Adding a product

To get started, you need to create an instance of the Perch API, and a PerchShopProductImporter:

$API      = new PerchAPI(1.0, 'my_importer');
$Importer = $API->get('PerchShopProductImporter');

Then to import, it’s a case of calling the add_item() method with an array whose keys match the IDs in your shop/products/product.html template:

try {
    $Importer->add_item([
        'sku'               => 'TSHIRT01',
        'title'             => 'My first t-shirt',
        'slug'              => 'my-first-t-shirt',
        'description'       => 'This is a really smashing t-shirt.',
        'image_assetID'     => 630,
        'img_desc'          => 'An image of the product',
        'status'            => true,
        'brand'             => 1,
        'category'          => 'products/clothes/',
        'catalog_only'      => false,
        'price'             => ['gbp' => 10, 'eur'=>12, 'usd'=>13],
        'sale_price'        => ['gbp' => 8,  'eur'=>10, 'usd'=>11],
        'trade_price'       => ['gbp' => 7,  'eur'=>9,  'usd'=>10],
        'on_sale'           => false,
        'tax_group'         => 1,
        'stock_status'      => '1',
        'stock_level'       => '199',
        'stock_location'    => true,
        'max_in_cart'       => 10,
        'requires_shipping' => true,
        'weight'            => 100,
        'width'             => 20,
        'height'            => 15,
        'depth'             => 30,
    ]);    
} catch (Exception $e) {
    die('Error: '.$e->getMessage());
}

One trick here is that for the image field, we’re passing in an existing Asset ID (created using the new AssetImporter) so instead of using the image key to match the ID in our template, we use image_assetID to indicate that what we’re passing in is the ID of an asset already in the system. In this case, that’s asset 630.

The importer will validate for required fields, and perform some product-specific validations like checking that the SKU is unique. If any errors are found, an exception is thrown.

New in Shop 1.2

The data schema for Shop is fairly complex, especially as you get into product variants and options, tax groups and locations, and so on. As such, we’ve started simply in Perch Shop 1.2 with the ability to add top-level products, brands and so on. If you plan to use the importer API for Shop, we’d be very keen to hear your feedback and find out how it’s working for you so that we can prioritise the next steps to best suit customer needs.