shopp_add_product()

create a new product and saves it to the Shopp product catalog.

shopp_add_product( $data );

@param array $data (required) associative array structure containing a single product definition, see examples for how this array is structured.

@return Product the created product object, or boolean false on a failure.

Description

This function is used to create a new product.

The data array is structured hierarchically. While most elements and sub-elements of the data array are optional, the data array may not be empty.

Base Data Array

Below are the base data array keys and values:

  • name: required (string) the product name.
  • slug: optional (string) the product slug. It is recommended that you sanitize the slug using sanitize_title_with_dashes(). If the slug is not unique it will be made unique.
  • description: optional (string) the product description text.
  • summary: optional (string) the product summary description text.
  • featured: optional (bool) the featured product flag.
  • packaging: optional (bool) flags product for separate package when using online shipping service module.
  • publish: optional (array) the publishing setting array. See below.
  • categories: optional (array) product category terms. See Category Terms Array below.
  • tags: optional (array) product tag terms. See Tag Terms Array below.
  • terms: optional (array) product taxonomy terms. See Taxonomy Terms Array below.
  • specs: optional (array) name, value pairs for product specs and details.
  • variants: required for variant products only (array) for products with variants, contains the option menu set array, and also one variant data array for each variant. See Variants Options Array.
  • single: required for single product only (array) for single products (non-variant), contains a single “variant” option array. See Variant Option Array below.
$data = array(
    'name' => 'Product Name',
    'slug' => 'product_name',
    'description' => 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce accumsan elit ac erat ornare cursus.',
    'summary' => 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin bibendum.',
    'featured' => true,
    'packaging' => true,
    'publish' => array(...), // see below
    'categories' => array(...), // see below
    'tags' => array(...), // see below
    'terms' => array(...), // see below
    'specs' => array('Spec Name 1' => 'Spec Value', 'Spec Name 2' => 'Spec Value'...),
    'single' => array(...), // see below
    'variants' => array(...), // see below
);

Publish Settings Array

Below are the publish settings array keys and values:

  • flag: required (bool) true to publish, false for draft.
  • publishtime: optional (array) the publish time array, with required keys month, day, year, hour, minute, meridian (AM or PM)
$data['publish'] = array(
    'flag' => true,
    'publishtime' = array(
        'month' => 12,
        'day' => 31,
        'year' => 2012,
        'hour' => 11,
        'minute' => 59,
        'meridian' => 'PM'
    )
);

Category Terms Array

Below is the category term array key and values:

  • terms: required (array) Integer product category ids to be assigned to the product.
$data['categories'] = array( 
    'terms' => array(1, 2, 3) // cat ids
);

Tag Terms Array

Below is the tag term array key and values:

  • terms: required (array) Integer product tag ids or string tag names to be assigned to the product.
$data['tags'] = array( 
    'terms' => array(1, 2, 'tagname') // tag ids and names
);

Taxonomy Terms Array

Below are the taxonomy term array keys and values:

  • terms: required (array) Integer product term ids to be assigned to the product.
  • taxonomy: required (string) String name of the taxonomy for the terms array.
$data['terms'] = array( 
    'terms' => array(1, 2, 3), // term ids
    'taxonomy' => 'my_product_taxonomy'
);

Variants Option Array

The variants data contains the following array keys and values:

  • menu: required (array) Two-dimensional array, with one array of specific characteristics for each option menu label index. For instance, if the product has multiple colors and multiple sizes, the menu array will have an array of colors options (indexed by the option menu label “Color”), and an array of size options (indexed by the option menu label “Color”).
  • numeric indices: required (array) For each combination of options specified in the menu element, there should be one variant option array. For instance, if the menu describes two colors and two sizes, there will be 4 numeric indices, each specifying one of the color/size combinations. See Variant Option Array below.
$data['variants'] = array(
    'menu' => array(
        'Color' => array('Blue','Red'),
        'Size' => array('L','XL')
    ),

    // four combo variant option arrays
    0 => array(...), // see below
    1 => array(...), // see below
    2 => array(...), // see below
    3 => array(...)  // see below
);

Variant Option Array

The variant option array is used to specify the settings for a single variant option. The variant option array contains the following array keys and descriptions.

  • option: required unless single product option (array) specifies the one specific option from each option menu representing this variant option combination. For example, if there is a Color option menu and a Size option menu, this array will specify the particular Color and Size represented by this option array.
  • type: required (string) the variant type, one of Shipped, Virtual, Download, Donation, Subscription, or N/A to disable this option combination.
  • price: required (float) tax exclusive regular price of the product.
  • taxed: optional (bool) flags the variant as taxable.
  • sale: optional (array) sale price array. See Sale Price Array below.
  • shipping: optional (array) shipping settings array. See Shipping Settings Array below.
  • inventory: optional (array) inventory settings array. See Inventory Settings Array below.
  • donation: optional and only valid for Donation type variants (array) donation settings array. See Donation Settings Array below.
  • subscription: optional and only valid for Subscription type variants (array) subscription settings array. See Subscription Settings Array below.

Single variant

$data['single'] = array(
    // 'option' => array(), Not for single product, see multiple variant example.
    // 'donation' => array(...), Donation type only, see below.
    // 'subscription' => array(...), Subscription type only, see below.

    'type' => 'Shipped',
    'price' => 9.99,
    'taxed' => true,
    'sale' => array(...),       // see below
    'shipping' => array(...),   // see below
    'inventory' => array(...),  // see below
);

Multiple Variants

$data['variants'] = array(
    'menu' => array(
        'Color' => array('Blue','Red'),
        'Size' => array('L','XL')
    )
);

$data['variants'][0] = array(
    // 'donation' => array(...), Donation type only, see below.
    // 'subscription' => array(...), Subscription type only, see below.

    'option' => array('Color'=>'Red','Size'=>'L'),
    'type' => 'Shipped'
    'price' => 9.99,
    'taxed' => true,
    'sale' => array(...),       // see below
    'shipping' => array(...),   // see below
    'inventory' => array(...),  // see below
);

Sale Price Array

The sale price array contains the following keys and values:

  • flag: required (bool) flag true to enable a sale price
  • price: required (float) the sale price
$data['single']['sale'] = array(
    'flag' => true,
    'price' => 5.99
);
$data['variants'][0]['sale'] = array(
    'flag' => true,
    'price' => 5.99
);

Shipping Settings Array

The shipping settings array contains the following keys and values:

  • flag: required (bool) flag true to enable shipping charges
  • fee: optional (float) an additional flat shipping fee for the variant
  • weight: optional (float) non-zero variant product weight
  • width: optional (fload) non-zero variant product width
  • length: optional (fload) non-zero variant product length
  • height: optional (fload) non-zero variant product height
$data['single']['shipping'] = array(
    'flag' => true,
    'fee' => 1.00,
    'weight' => 10,
    'width' => 5.0,
    'length' => 5.0,
    'height' => 5.0
);
$data['variants'][0]['shipping'] = array(
    'flag' => true,
    'fee' => 1.00,
    'weight' => 10,
    'width' => 5.0,
    'length' => 5.0,
    'height' => 5.0
);

Inventory Settings Array

The inventory settings array contains the following keys and values:

  • flag: required (bool) flag true to enable inventory tracking
  • stock: optional (int) the initial stock level of the product variant
  • sku: optional (string) the stock keeping unit code that is used for the product variant.
$data['single']['inventory'] = array(
    'flag' => true,
    'stock' => 10,
    'sku' => 'SKU1',
);
$data['variants'][0]['inventory'] = array(
    'flag' => true,
    'stock' => 15,
    'sku' => 'SKU2',
);

Donation Settings Array

The donation settings array is only used when the product variant is of type Donation. The donation settings array contains the following keys and values:

  • variable: (bool) flag whether or not variable donations are used.
  • minimum: variable price only (bool) flag the price of the variant as the minimum donation.
$data['single']['donation'] = array(
    'variable' => true,
    'minimum' => true,
);
$data['variants'][0]['donation'] = array(
    'variable' => true,
    'minimum' => true,
);

Subscription Settings Array

The subscription settings array is only used when the product variant is of type Subscription. The subscription settings array contains the following keys and values:

  • trial: optional (array) trial period settings array. See Trial Period Settings Array.
  • billcycle: required (array) the billing cycle settings array. See Billing Cycle Settings Array.
$data['single']['subscription'] = array(
    'trial' => array(...),      // see below
    'billcycle' => array(...),  // see below
);
$data['variants'][0]['subscription'] = array(
    'trial' => array(...),      // see below
    'billcycle' => array(...),  // see below
);

Trial Period Settings Array

For subscription product variants, the trial period settings array contains the following keys and values:

  • cycle: required (array) a time cycle array defining the trial period. See Time Cycle Array.
  • price: required (float) the trial price to be used for the trial period.

Billing Cycle Settings Array

For subscription product variants, the billing cycle settings contains the following keys and values:

  • cycle: required (array) a time cycle array See Time Cycle Array.
  • cycles: required (int) the number of cycles billing cycles to repeat. 0 for unlimited cycles.

Time Cycle Array

An array that defines a time period that can repeat in a cycle. The cycle array contains the following keys and values:

  • period: required (string) one of ‘d’,’w’,’m’, or ‘y’, for days, weeks, months, or years, respectively.
  • interval: required (int) number of time units of the cycle period.
$trial = array();
$trial['cycle'] = array(
    'period' => 'd',
    'interval' => 30
);
$trial['price'] = 1.00;

$billcycle = array();
$billcycle['cycle'] = array(
    'period' => 'm',
    'interval' => 1
);
$billcycle['cycles'] = 5;

$data['single']['subscription'] = array(
    'trial' => $trial,          // see below
    'billcycle' => $billcycle,  // see below
);

More Examples

A Jacket with Size and Color Variations

$data = array(
    'name' => 'Water Repellent Jacket',

    // publishing information
    'publish' => 
        array( 
            'flag' => false, // product is not published
            'publishtime' => // date and time the product will be published
                array(
                'month' => 12,
                'day' => 25,
                'year' => 2011,
                'hour' => 0,
                'minute' => 0,
                'meridian' => 'AM'
                )
                ),

    // The product description
    'description' =>
    'This water-repellent windbreaker offers lightweight protection on those gusty days.'
    .'<ul>'
    .'<li>hood with drawstring</li>'
    .'<li>zip front</li>'
    .'<li>2 inner pockets</li>'
    .'<li>on-seam pockets</li>'
    .'<li>contrast side panels</li>'
    .'<li>elastic cuffs</li>'
    .'<li>side elastic on bottom</li>'
    .'<li>contrast mesh lining</li>'
    .'<li>polyester microfiber</li>'
    .'<li>polyester mesh lining</li>'
    .'<li>washable</li>'
    .'<li>imported</li>'
    .'</ul>',

    // The summary description
    'summary' => 'This water-repellent windbreaker offers lightweight protection on those gusty days.',

    // Is the product a featured product?
    'featured' => true,

    // category ids the product belongs to
    'categories'=> array('terms' => array(5)),

    // tag names or ids the product belongs to
    'tags'=>array('terms'=>array('water-tight')),

    // term ids, and shopp product taxonomy
    // the product belongs to. You can only add set of custom taxonomy terms this way.
    // use shopp_product_add_terms() for more.
    'terms'=>array(
        'terms'=>array(15,38)
        'taxonomy'=>'my_product_taxonomy'
        ),

    // Details/Specs name value pairs
    'specs'=>array(
        'pockets'=>2,
        'drawstring'=>'yes',
        'washable'=>'yes'
        ),

    'variants'=>array(
        //variation menu options
        'menu' => array(
            'Size' => array('medium','large','x-large','small','xx-large','large-tall','x-large tall','2x-large tall','2x-large'),
            'Color' => array('Black/Grey Colorbi', 'Navy Baby Solid','Red/Iron Colorbloc','Iron Solid','Dark Avocado Soil')
        )
    ),

    'addons'=> array(
        // addon menu options
        'menu' => array('Special' => array('Embroidered')) 
    ),

    // whether or not the product is packaged separately or not
    'packaging' => true 
);

// build out each product variant like so
$data['variants'][] = array(
    // the option set for this variant
    'option' => array('Size'=>'medium', 'Color' => 'Navy Baby Solid'), 

    // product "type" for this variant
    'type' => 'Shipped',  // 'Shipped', 'Download', 'Virtual', 'N/A' (Disabled)

    // regular price
    'price' => 40.00,

    // variant sale settings
    'sale' => 
        array(
            // flagged on sale or not
            'flag'=>true,

            // the sale price
            'price' => 19.99
        ),

    // variant shipping settings
    'shipping' => 
        array(
            // charge shipping fees for this variant
            'flag'=>true,

            // additional s/h fee for this variant
            'fee'=>1.50,

            // shipping dimensions
            'weight'=>1.1,
            'length'=>10.0,
            'width'=>10.0,
            'height'=>2.0
            ),

    // inventory tracking settings
    'inventory'=>
        array(
            // track inventory on this variant?
            'flag'=>true,

            // number of this variant that you will be stocking
            'stock'=>10,

            // the variants Stock Keeping Unit
            'sku'=>'WINDBREAKER1'
            )
);

// build each addon option (very similar to variant structure)
$data['addons'][] = array(
    // specify the addon option
    'option' => array('Special'=>'Embroidered'), 

    // the "type" of addon
    'type' => 'Shipped', // 'Shipped', 'Download', 'Virtual', 'N/A' (Disabled)

    // the addons regular price
    'price' => 10.00
);

$Product = shopp_add_product( $data );

See Also

You must be logged in to post a comment.

© Ingenesis Limited. Shopp™ is a registered trademark of Ingenesis Limited.

Skip to toolbar