Manage Products

Catalog API Overview

Create a simple catalog with a single API call.

This guide provides step-by-step instruction for creating catalog objects with the Catalog API.

Prerequisites

  • You must have a Square account to use the Catalog API. Create a Square account in minutes if you don't already have one.

Assumptions

This guide makes the following assumptions:

  • You have read the Catalog API Overview , which covers general functionality of the API.
  • You are familiar with HTTPS. If this is your first time working with HTTPS, consider reading the HTTPS Guide before continuing.

Working example

Our sample code has the following characteristics. These characteristics are not required to use the Catalog API.

  • We authorize API calls with a personal access token instead of an OAuth token. While we recommend using OAuth for authorization whenever possible in production, personal access tokens provide an easy way to get started quickly.
  • We use PHP version 5.4 or later. But the Catalog API is language agnostic and the setup steps are comparable across languages.

Step 1: Get your personal access token.

  1. Click on your business name in the top right corner. You may need to log in first.
  2. Click the application you want to work on to open that application's control panel.
  3. If you DO have an application you want to use for accepting online payments, click on the application.
  4. If you DO NOT have an application you want to use for accepting online payments, click New Application, enter a name for your application (e.g., "My Online Store") and click Create Application.
  5. Copy the Personal Access Token value on the Credentials tab of the application control panel.

Step 2: Install the Connect PHP SDK

The Create a Square account provides a helpful wrapper for interacting with our APIs. Though it takes an extra step to install the SDK, it will make interacting with Connect APIs much easier. We will be using the SDK for the rest of this guide.

  1. Follow the Square PHP SDK installation steps to install the SDK. You can clone the SDK directly from Github or you can use Composer, a dependency manager for PHP.
  2. Include the Connect PHP SDK in your file. Remember to change the path depending on where you place the SDK in relation to your other php files.
// Include the Square Connect API resources
require_once(__DIR__ . '/local/path/to/Square/Connect/SDK/autoload.php');

You can read the documentation for the Connect PHP SDK here. We also have SDKs available in other languages.

Note that using the Connect PHP SDK is optional. As long as you can package and receive JSON messages you can use Square's APIs.

Step 3: Initialize API object and set your catalog object ID variables

Step 3.A: Initialize the API object

  1. Use this code to initialize your Catalog API object.
//Replace with your access token
$accessToken = '{REPLACE_ME}';

// Include the Square Connect API resources
require_once(__DIR__ . '/local/path/to/Square/Connect/SDK/autoload.php');

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setAccessToken($accessToken);

$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$catalogApi = new SquareConnect\Api\CatalogApi($defaultApiClient);
  1. Replace your personal access token.
  2. Replace with your local path to the Square PHP SDK.

Step 3.B: Set catalog object ID variables

In this setup guide, we will be making the following catalog objects:

  • An item called Coffee
  • Two item variations called Small and Large
  • Two modifiers called Skim Milk and Whole Milk that you can apply to item variations
  • A modifier list to contain the two modifiers.

If you want to make updates to these catalog objects in the future, you will need to those permanent IDs. Setting your IDs as variables makes them easier to update or replace with permanent IDs.

$coffeeItemId = "#coffee";
$smallItemVariationId = "#small_coffee";
$largeItemVariationId = "#large_coffee";
$wholeMilkModifierId = "#whole_milk";
$skimMilkModifierId = "#skim_milk";
$milkModifierListId = "#milk_options";

Step 4: Build an item with an item variation.

Let's create an item and associated item variation. Items need at least one item variation to have a price and SKU, so we will create an item that contains an item variation using the UpsertCatalogObject endpoint.

In the following example, we are going to make an item called Coffee, with two item variations: Small and Large.

Step 4.A: Build an item

To create a catalog item, you need to create a catalog object of the ITEM type.

  1. Create a catalog item data object called itemData.
// Create a Catalog item
$coffeeData = new \SquareConnect\Model\CatalogItem;

$coffeeData->setName("Coffee");
$coffeeData->setDescription("Coffee Drink");
$coffeeData->setAbbreviation("Co");
  1. Create a catalog object of the ITEM type.
// Create a new catalog object of the ITEM type
$coffee = new \SquareConnect\Model\CatalogObject;
$coffee->setType("ITEM");
$coffee->setId($coffeeItemId); // Temporary ID that Square will replace

Step 4.B: Build some item variations

To create an item variation, you need to create a catalog object of the ITEM_VARIATION type.

  1. Create a catalog item variation object called itemVariationData. Note that the price field requires a Money data type, so we also create a money object to represent the price.
// Create an item variation data object for information on small coffees
$smallCoffeeData = new \SquareConnect\Model\CatalogItemVariation;

$smallCoffeeData->setName("Small");
$smallCoffeeData->setItemId($coffeeItemId); // Temporary ID for the coffee item

//Create a Money object to represent the price of this item variation
$price = new \SquareConnect\Model\Money;
$price->setAmount(300); //Prices are specified in cents. This represents $3.00
$price->setCurrency('USD');

$smallCoffeeData->setPriceMoney($price);

  1. Create an catalog object of the ITEM_VARIATION type using itemVariationData.
// Create a new catalog object of the ITEM VARIATION
$smallCoffee = new \SquareConnect\Model\CatalogObject;
$smallCoffee->setType("ITEM_VARIATION");
// The item variation data object we just made
$smallCoffee->setItemData($smallCoffeeData);
  1. For good measure, let's create a second item variation to represent a Large sized coffee.
// Create an item variation data object for Large coffee
$largeCoffeeData = new \SquareConnect\Model\CatalogItemVariation;

$largeCoffeeData->setName("Large");
// Temporary ID that Square will replace
$largeCoffeeData->setItemId($coffeeItemId);

$price = new \SquareConnect\Model\Money;
$price->setAmount(300); //Prices are specified in cents. This represents $3.00
$price->setCurrency('USD');

$largeCoffeeData->setPriceMoney($price);

// Create a new item variation using $largeCoffeeData
$largeCoffee = new \SquareConnect\Model\CatalogObject;
$largeCoffee->setType("ITEM_VARIATION");
$largeCoffee->setItemData($largeCoffeeData);

Step 4.C: Set item variations to item

Next, we need to set variations as the item variation we created in step 4.A. The variations field expects an array of catalog objects, so we put the item variation inside an array called $coffeeSizes.

// Set variations for $coffeeData
$coffeeSizes = array($smallCoffee, $largeCoffee);
$coffeeData->setVariations($variations);
$coffee->setItemData($coffeeData);

Step 5: Build a modifier list

Step 5.A: Build two modifiers to represent two types of milk

  1. Make a catalog object of the MODIFIER type to represent skim milk.
/* SKIM MILK */
// Create a new modifier data object for skim milk
$skimMilkData = new \SquareConnect\Model\CatalogModifier;
$skimMilkData->setName("2%");

//Create a Money object to represent the price of 2% milk
$skimMilkPrice = new \SquareConnect\Model\Money;
$skimMilkPrice->setCurrency('USD');
$skimMilkPrice->setAmount(100); //Represents $3.00 Amount is specified in cents
$skimMilkData->setPriceMoney($skimPrice);

//Create catalog object of the MODIFIER type
$skimMilk = new \SquareConnect\Model\CatalogObject;
$skimMilk->setId("#skim_milk");
$skimMilk->setType("MODIFIER");
$skimMilk->setModifierData($skimMilkData);
  1. Make a catalog object of the MODIFIER type to represent whole milk.
/* WHOLE MILK */
// Create a new modifier data object for whole milk
$wholeMilkData = new \SquareConnect\Model\CatalogModifier;
$wholeMilkData->setName("2%");

//Create a Money object to represent the price of this item modifier
$wholeMilkPrice = new \SquareConnect\Model\Money;
$wholeMilkPrice->setCurrency('USD');
$wholeMilkPrice->setAmount(100);//Represents $3.00 Amount is specified in cents
$wholeMilkData->setPriceMoney($wholeMilkPrice);

//Create catalog object of the MODIFIER type
$wholeMilk = new \SquareConnect\Model\CatalogObject;
$wholeMilk->setId("#whole_milk");
$wholeMilk->setType("MODIFIER");
$wholeMilk->setModifierData($wholeMilkData);

Step 5.B: Build a modifier list to contain your two modifiers

  1. Build a modifier list called $milkList.
//put milk modifiers in an array
$milkModifiers = array($skimMilk, $wholeMilk);

$milkList = new \SquareConnect\Model\CatalogModifierList;
$milkList->setName("Milk Types");
$milkList->setModifiers($milkModifiers);
  1. Make a catalog object of the MODIFIER_LIST type using $milkList.
// Make the actual catalog obejct of the MODIFIER_LIST type
$milkOptions = new \SquareConnect\Model\CatalogObject;
$milkOptions->setType("MODIFIER_LIST");
$milkOptions->setId($milkModifierListId);
$milkOptions->setModifierListData($milkList);

Step 5.C: Apply modifier list to the $coffee item.

We need to apply this modifier list to our $coffee item. You can do this by setting this modifier list as the modifier list for $coffeeData.

// Set modifier list for $coffeeData
//We need to make an modifier list information object for $coffeeData
$modifierInfo = new \SquareConnect\Model\CatalogItemModifierListInfo;
$modifierInfo->        setModifierListId($milkModifierListId);

//modifier_list_info expects an array
$modifierInfoLists = array($modifierInfo);

$coffeeData->setModifierListInfo($modifierInfoLists);

Step 6: Use the BatchUpsertCatalogObjects request to create a category item with associated items and item variations.

Now we are going to use the BatchUpsertCatalogObjects endpoint to create all three of these catalog objects at the same time.

  1. Make a batch with the catalog objects we just made. The item variations ($smallCoffeeand $largeCoffee) are nested inside the item ($coffee) so we only need to set $coffee.
//put item and modifiers in an array
$objects = array($coffee, $milkOptions);

//Set $objects as the value for batch.
$batch = new \SquareConnect\Model\CatalogObjectBatch;
$batch->setObjects($objects);

  1. Make the BatchUpsertCatalogObjects request.
// Create the request object for UpsertCatalogObject
$body = new \SquareConnect\Model\BatchUpsertCatalogObjectsRequest();
$body->setIdempotencyKey(uniqid()); // uniqid() generates a random string.

//The batch field for the BatchUpsert request expects an array
$batches = array($batch);
$body->setBatches($batches);

  1. Send your request. For testing purposes, the code below prints the result.
// Make the call
try {
    $result = $catalogApi->batchUpsertCatalogObjects($body);
    echo 'Success!';
    print_r($result);

} catch (Exception $e) {
    echo 'Exception when calling CatalogApi->batchUpsertCatalogObjects: ', $e->getMessage(), PHP_EOL;
}

Optional: Update a catalog object

You can update existing catalog objects with the Upsert and BatchUpsert endpoints. To update a catalog object, you need to get the permanent ID assigned to the catalog object by Square.

  1. Get the catalog object ID using the ListCatalog endpoint.
$cursor = "";
$returnedTypes = "ITEM_VARIATION"; //Filter to return only ITEM objects.

//initiate our variable for the permanent ID
$itemVariationPermanentId = "";
try {
  //Get the list of ITEM_VARIATION objects in the catalog.
  $result = $catalogApi->listCatalog($cursor, $returnedTypes);
  $objects = $result->getObjects();

  //Get array of returned catalog objects from result and iterate through the items.
  foreach($objects as $itemVariation){
    $itemVariationData = $itemVariation->getItemVariationData();
    $itemVariationName = $itemVariationData->getName(); // Get ITEM_VARIATION name

    // If the item variation's name is "Small", save the item_variation_id
    if ($itemVariationName == "Small"){
          $itemVariationId = $itemVariation->getId(); //get ITEM_VARIATION ID
          $itemId = $itemVariationData->getItemId(); //get ITEM ID
          return;

    }

  }
} catch (Exception $e) {
  echo $e;
  error_log(sprintf("Exception %s: %s",$e->getCode(), $e->getMessage()));
}
  1. Go back to your BatchUpsertCatalogObject request and replace the temporary IDs for Coffee and Small.
$coffeeItemId = $itemId;
$smallItemVariationId = $itemVariationPermanentId;
  1. Update the price of Small.
//Create a Money object to represent the price of this item variation
$price = new \SquareConnect\Model\Money;
$price->setAmount(400); //Prices are specified in cents, so this represents $3.00

$price->setCurrency('USD');

$smallCoffeeData->setPriceMoney($price);

  1. Resend your BatchUpsert request. The BatchUpsertCartalogObject endpoint will update your changes and ignore everything else.
// Make the call
try {
    $result = $catalogApi->batchUpsertCatalogObjects($body);
    echo 'Success!';
    print_r($result);

} catch (Exception $e) {
    echo 'Exception when calling CatalogApi->batchUpsertCatalogObjects: ', $e->getMessage(), PHP_EOL;
}

Next
Orders API Overview >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow