View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Brian Phillips > WebService-Shutterstock-0.004 > WebService::Shutterstock::Customer



Annotate this POD


View/Report Bugs
Module Version: 0.004   Source   Latest Release: WebService-Shutterstock-0.006


WebService::Shutterstock::Customer - Class allowing API operations in the context of a specific customer


version 0.004


        my $customer = $shutterstock->auth("my-user" => "my-password");

        # retrieve list of lightboxes
        my $lightboxes = $customer->ligthboxes;

        # retrieve a specific lightbox for this user
        my $lightbox = $customer->lightbox(123);

        my $subscriptions = $customer->subscriptions;
        my $enhanced_subscription = $customer->subscription(license => 'enhanced');

        my $download_history = $customer->downloads;

        # license an image (if you only have a single active subscription)
        my $licensed_image = $customer->license_image(
                image_id => 59915404,
                size     => 'huge'

        # license an image (if you have more than one active subscription)
        my $licensed_image = $customer->license_image(
                image_id     => 59915404,
                size         => 'huge',
                subscription => { license => 'standard' }


This class provides access to API operations (download history, lightbox interaction, subscriptions, etc) that require an authenticated customer (via "auth" in WebService::Shutterstock).



Retrieves the account ID for this account.


Retrieves the set of metadata fields for your account (if so configured by Shutterstock). Returns an ArrayRef of HashRefs (or undef if this feature doesn't apply to your account). When licensing an image you should provide the required metadata values using the name_api values specified for each metadata field returned by this method.


Returns an ArrayRef of WebService::Shutterstock::Subscription objects for this customer account.


Convenience wrapper around the find_subscriptions method that always returns the first match (useful when you're matching on a field that is unique like id or license).

        # find the (single) subscription providing an enhanced license
        my $media_digital_subscription = $customer->subscription(license => 'enhanced');


Retrieve a list of WebService::Shutterstock::Subscription objects, based on the criteria passed in to the method. Filter criteria should have WebService::Shutterstock::Subscription attribute names as keys with the value to be matched as the value. Subscriptions that match ALL the provided criteria are returned as a list. Some examples:

        # simple equality filters
        my @active_subscriptions = $customer->find_subscriptions( is_active => 1 );
        my @active_subscriptions = $customer->find_subscriptions( is_active => 1 );

        # regular expressions work too
        my @all_media_subscriptions = $customer->find_subscriptions( license => qr{^media} );

        # use an anonymous sub for more detailed filters (i.e. subscriptions expiring in the 
        my @soon_to_expire = $customer->find_subscriptions(
                is_active            => 1,
                unix_expiration_time => sub { shift < time + ( 60 * 60 * 24 * 30 ) }


Returns an ArrayRef of WebService::Shutterstock::Lightbox objects for this customer acount. By default, it gets only the lightbox information and the list of image IDs in the lightbox. If you would like to retrieve more details about those images (specifically sizes and thumbnail URLs) in a single HTTP request, just pass a true value as the only argument to this method.


Returns a specific lightbox (as a WebService::Shutterstock::Lightbox object) for the given $id (it must belong to this user). If that lightbox doesn't exist, undef will be returned. Unfortunately, Shutterstock's API currently returns an HTTP status of 500 on an unknown lightbox ID (which could mask other error situations).


Retrieve the download history for this customer account. You can specify a page_number argument if you prefer to retrieve a single page of results (starting with page 0). Or, you can fetch the redownloadable_state of a particular image:

        my $redownloadable_state = $customer->downloads(
                image_id => 11024440,
                field    => "redownloadable_state"

The data returned will look something like this:

                        image_id => 1,
                        license  => 'standard',
                        time     => '2012-11-01 14:16:08',
                        image_id => 2,
                        license  => 'premier',
                        metadata => { purchase_order => 'XYZ', client => 'My Client' },
                        time     => '2012-11-01 14:18:39',
                # etc...

license_image(image_id => $image_id, size => $size)

Licenses a specific image in the requested size. Returns a WebService::Shutterstock::LicensedImage object.

If you have more than one active subscription, you will need to specify which subscription you would like to use for licensing with a subscription argument. You can pass in a WebService::Shutterstock::Subscription object or any criteria that can be passed to "find_subscriptions" that will identify a single subscription. For instance:

        # by "license"
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => { license => 'standard' }

        # by "id"
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => { id => 63746273 }

        # or explicitly, with a subscription object
        my $enhanced = $customer->subscription( license => 'enhanced' );
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => $enhanced

If your account is configured by Shutterstock to require custom metadata values to be provided when licensing images (see "metadata_field_definitions"), you can provide those values using the metadata parameter. For instance:

        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => $subscription,
                metadata     => { purchase_order => '<value here>', }


Brian Phillips <>


This software is copyright (c) 2012 by Brian Phillips and Shutterstock, Inc. (

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: