Transitioning from v1 Items to Catalog APIs

Earlier this year, Square released new catalog endpoints to help manage your items in a more streamlined and scalable way. You might be familiar with the v1 endpoints create,retrieve, update and delete (CRUD) operations with items and their associated variations, modifier lists, modifier options, discounts, fees, etc. Catalog endpoints streamline all of these different entities into a single CatalogObject type with new endpoints for doing batch operations for multiple items at once. As a result, managing items across multiple locations is much easier. For the rest of this post I’ll go over what these differences actually look like for a couple of operations.

Creating items & variations

Previously you only had available endpoints for creating new items, variations, modifiers, etc. Frequently you had to use all of them to create a new item, with complex chaining of requests to make sure that everything was associated correctly. Multiplying that workflow for all of the items in your account can quickly turn “importing your items” into waiting for a gazillion requests to finish as you create new items, variations, discounts, and modifiers, all in serial.

With the catalog endpoints, that workflow has been slimmed down into one endpoint, POST /v2/catalog/object, or upsert catalog object. While this might seem complex at first, catalog objects are very powerful and simplify the number of other calls that you need to make by adding multiple object types to the same request. You can now create your items in parallel to their variations, options, and modifiers, all while operating at great scale due to the batch endpoint options.

Let’s take a look at the code required to create a new item and a couple of variations.

Creating an item and variation with v1 item endpoints

<?php
$location_id = 'location_id';
$api_instance = new SquareConnect\Api\V1ItemsApi();
$body = array(
    'name'=>'Pots',
    'description'=> 'Containers for gardening',
    'variations'=> array(
      array(
        'name'=>'Large',
        'price_money'=>array(
          'amount'=>600,
          'currency_code'=>'USD'
        )
      ),
      array(
        'name'=>'Small',
        'price_money'=>array(
          'amount'=>300,
          'currency_code'=>'USD'
        )
      )
    )
  );
$result = $api_instance->createItem($location_id, $body);

Creating an item and variation with v2 Catalog endpoints

Retrieving items

This is another area where the Catalog endpoints can make a big difference, especially if you manage items for multiple locations.

Retrieving an item and variation with v1 item endpoints

<?php
$location_id = 'XXXXXXXX';
$item_id = "XXXXXXXXX"; // string | The item's ID.
$api_instance = new SquareConnect\Api\V1ItemsApi();
try {
    $result = $api_instance->retrieveItem($location_id, $item_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling V1ItemsApi->retrieveItem: ', $e->getMessage(), PHP_EOL;
}
?>

Retrieving an item and variation with v1 item endpoints

<?php
$api_instance = new SquareConnect\Api\CatalogApi();
$object_id = "XXXXXX"; 
$include_related_objects = true;
try {
    $result = $api_instance->retrieveCatalogObject($object_id, $include_related_objects);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling CatalogApi->retrieveCatalogObject: ', $e->getMessage(), PHP_EOL;
}
?>

At first glance, the two snippets look similar, but the little differences can make a big impact in how easy it is to manage a real world example. First of all, you don’t need a location to retrieve your items, since items are no longer necessarily scoped to individual locations. Further, you have the option of requesting all of the related objects with the $include_related_objects parameter, which includes all the related category, taxes, and modifier lists that apply to the item. The same operation with the v1 item’s endpoints would require you to call specific endpoints for each of the different properties you want to retrieve.

This is just a taste of what’s better about using the new Catalog APIs over the v1 items endpoints, so if you haven’t made the switch yet, give it a try and see how it might it simplify some of your code.

Square is also hiring now for our developer platform and more! Take a look at Square.com/careers to see if there is an opportunity you might be interested in. Come work with us :).