Shutterstock UI - Licensing | Shutterstock Image, Video, Music API

Licensing

To license images or video, you add pages that guide the user through the process of viewing an asset, selecting the appropriate subscription and size, and confirming the licensing transaction. To avoid putting your Shutterstock API credentials in client-side code, you must set up server-side code to get subscription info and complete the license and download process.

To set up the licensing and downloading process on the widget, follow these general steps:

Create an image or video details page, which is an object of the type ShutterstockWidget.components.ImageDetailsPage or ShutterstockWidget.components.VideoDetailsPage.
On the details page, using the props.button parameter, create a button that sends the user to the appropriate licensing page. See Setting up the details page.
On the server side, using the Shutterstock API, retrieve information about the user's subscriptions.
Retrieve information about the asset sizes that are available.
Pass the information about the asset and information about the user's subscriptions to the appropriate licensing page.
Create an image or video licensing page, which is an object of the type ShutterstockWidget.components.ImageLicensingPage or ShutterstockWidget.components.VideoLicensingPage. See Setting up the licensing page.
Add one or more buttons to the page and add callback functions to the buttons. These callbacks can do whatever you need to do, but in most cases, use the callbacks to call server-side code that uses the Shutterstock API to license the asset or run some other task.
On the server side or the client side, download the asset or handle the file in some other way.

Setting up the details page

A straightforward way to move the user to a licensing page is to start from the details page. This example includes a button that sends the user to the image licensing page:

const myImageDetailsPage = {
  component: ShutterstockWidget.components.ImageDetailsPage,
  name: 'myImageDetailsPage',
  props: {
    buttons: [
      {
        label: 'License',
        icon: '/shopping-cart.svg',
        isPrimary: true,
        onClick: async (e, item) => {
          e.preventDefault();
          // Fetch user subscriptions
          const subscriptions = await fetch('YOUR_BACKEND_ROUTE_TO_FETCH_SUBSCRIPTIONS');
          widget.navigateTo('myImageLicensingPage', {
            subscriptions,
            item,
          });
        },
      },
    ],
  },
};

To get the correct data to the licensing page, the onClick handler for the button must retrieve the user's subscriptions from the GET /v2/user/subscriptions endpoint in the Shutterstock API. You must configure server-side or backend code to retrieve this subscription information.

The onClick handler also receives an item object with information about the image or video that the user clicked. You can pass this object along with the response from the GET /v2/user/subscriptions endpoint to the appropriate licensing page. These parameters become the licensing page's props.subscriptions and props.item properties.

Showing the available sizes

To show the dimensions and DPI of each size of asset that is available, you must retrieve information about the available sizes and add that information to the subscription information. The Shutterstock API endpoints GET /v2/images/{id} and GET /v2/videos/{id} provide the sizes that are available for assets.

To set the dimensions for an image to license, follow these steps:

Retrieve the subscription information from the GET /v2/user/subscriptions endpoint.
Get information about the dimensions of the image from the GET /v2/images/{id} endpoint and add it to the subscription data in the format.details_for_image field.
Pass the merged subscription information to the details page's props.subscriptions parameter.

For example, the GET /v2/images/{id} endpoint might show that an image is available in two sizes and provide the dimensions for each size, as in this example:

{
  "medium_jpg": {
    "display_name": "Med",
    "dpi": 300,
    "file_size": 662723,
    "format": "jpg",
    "height": 563,
    "is_licensable": true,
    "width": 1000
  },
  "small_jpg": {
    "display_name": "Small",
    "dpi": 300,
    "file_size": 178812,
    "format": "jpg",
    "height": 282,
    "is_licensable": true,
    "width": 500
  }
}

The medium_jpg and small_jpg sizes in this response correspond to the medium and small formats in the subscription information. The merged subscription information is shown in the next example:

[
  {
    "id": "s12345678",
    "license": "premier",
    "description": "Premier Account",
    "asset_type": "videos",
    "price_per_download": {
      "local_amount": 100,
      "local_currency": "USD"
    },
    "allotment": {
      "downloads_left": 50000,
      "downloads_limit": 50000
    },
    "formats": [
      {
        "height": 1080,
        "width": 1920,
        "fps": 29.97,
        "format": "mov",
        "file_size": 16294912,
        "display_name": "HD MPEG",
        "is_licensable": true
      },
      {
        "height": 480,
        "width": 853,
        "fps": 29.97,
        "format": "mov",
        "file_size": 4689920,
        "display_name": "Standard Definition MPEG",
        "is_licensable": true
      },
    ]
  }
];

To set the dimensions for a video to license, follow these steps:

Retrieve the subscription information from the GET /v2/user/subscriptions endpoint.
Get information about the dimensions of the video from the GET /v2/videos/{id} endpoint.
In the subscription information, in the formats field, replace each format with the matching format from the dimensions of the video.
Pass the merged subscription information to the details page's props.subscriptions parameter.

Here is an example of the merged video subscription information:

[
  {
    "id": "s12345678",
    "license": "premier",
    "description": "Premier Account",
    "asset_type": "videos",
    "price_per_download": {
      "local_amount": 100,
      "local_currency": "USD"
    },
    "allotment": {
      "downloads_left": 50000,
      "downloads_limit": 50000
    },
    "formats": [
      {
        "height": 1080,
        "width": 1920,
        "fps": 29.97,
        "format": "mov",
        "file_size": 16294912,
        "display_name": "HD MPEG",
        "is_licensable": true
      },
      {
        "height": 480,
        "width": 853,
        "fps": 29.97,
        "format": "mov",
        "file_size": 4689920,
        "display_name": "Standard Definition MPEG",
        "is_licensable": true
      },
    ]
  }
]

Now when a user goes to the image licensing page, the page shows the dimensions for each size:

Similarly, the video licensing page shows the dimensions for each size:

Setting up the licensing page

If you pass subscription and size information as described in Setting up the details page, the licensing page automatically shows the subscriptions and sizes. You must add the button that the user clicks to license the asset.

In the onClick handler for the button, you must call server-side or backend code to call the Shutterstock API's POST /v2/images/licenses or POST /v2/videos/licenses endpoint. It is up to you to implement this code and what the widget does after the licensing request. You might configure the widget to show the download link or add the new image or video to the page.

const myImageLicensingPage = {
  name: 'myImageLicensingPage',
  component: ShutterstockWidget.components.ImageLicensingPage,
  props: {
    showSearchBar: true,
    subscriptions: [],
    buttons: [
      {
        label: 'License',
        icon: '/shopping-cart.svg',
        isPrimary: true,
        onClick: (e, item, props) => {
          e.preventDefault();
          await fetch('Your backend route to license images');
        }
      },
    ],
  }
};

Documentation

Licensing

Setting up the details page

Showing the available sizes

Setting up the licensing page