Catalog API

Build With Catalog

Create a simple catalog with a single API call.

Catalog API

Prerequisites
Permalink Get a link to this section

  • You have a Square Account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.

We also assume the following:

  • You have read the What It Does page for this product.

  • You are familiar with HTTPS. If this is your first time working with HTTPS, consider reading our TLS/HTTPS Guide before continuing.

Information you will need
Permalink Get a link to this section

To use the steps in this guide you need the following information from the Developer Portal:

  • A valid access token. Square recommends testing with sandbox credentials whenever possible. See Square API Access Tokens for more information.

Step 1: Initialize API object and set your access token
Permalink Get a link to this section

Initialize your Catalog API object and set your personal access token.

//Replace with your access token
$accessToken = '{REPLACE_ME}';

// 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);

Step 2: Set catalog object ID variables
Permalink Get a link to this section

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.

The example code below creates temporary IDs for the catalog objects. Square converts the temporary object IDs to permanent IDs when you update the product catalog. If you want to make updates to these catalog objects in the future, you will need to save the permanent IDs returned by the API. Setting 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 3: Build an item
Permalink Get a link to this section

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.

First, create a catalog item data object called coffeeData. Then, create a catalog object of the ITEM type and set coffeeData as the catalog item ID.

// Create a Catalog item
$coffeeData = new \SquareConnect\Model\CatalogItem;

$coffeeData->setName("Coffee");
$coffeeData->setDescription("Coffee Drink");
$coffeeData->setAbbreviation("Co");

// Create a new catalog object of the ITEM type
$coffee = new \SquareConnect\Model\CatalogObject;
$coffee->setType("ITEM");

// Use the saved Catalog Item ID
$coffee->setId($coffeeItemId);

Step 4: Build some item variations
Permalink Get a link to this section

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

Create a catalog item variation object called smallCoffeeData and set price and pricing type. Then create a catalog object of the ITEM_VARIATION type and set smallCoffeeData as the itemVariationData field.

Once that's done, let's create a second item variation object called largeCoffeeData.

/* SMALL COFFEE ITEM VARIATION */
// Create an item variation data object for information on small coffees
$smallCoffeeData = new \SquareConnect\Model\CatalogItemVariation;

$smallCoffeeData->setName("Small");
$smallCoffeeData->setItemId($coffeeItemId); // Parent Catalog Item ID from Step 3

//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);
$smallCoffeeData->setPricingType("FIXED_PRICING");

// Create an catalog object of the `ITEM_VARIATION` type and set smallCoffeeData.

// 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->setItemVariationData($smallCoffeeData);

/* LARGE COFFEE ITEM VARIATION */
// Create an second item variation for Large coffee
$largeCoffeeData = new \SquareConnect\Model\CatalogItemVariation;

$largeCoffeeData->setName("Large");
// Temporary ID that Square will replace
$largeCoffeeData->setItemId($coffeeItemId); // Parent Catalog Item ID from Step 3

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

$largeCoffeeData->setPriceMoney($price);
$largeCoffeeData->setPricingType("FIXED_PRICING");

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

Step 5: Set item variations to item
Permalink Get a link to this section

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($coffeeSizes);
$coffee->setItemData($coffeeData);

Step 6: Build two item modifiers
Permalink Get a link to this section

To make a milk modifier list, we need two modifier objects to represent two types of milk. The process is similar to making an item variation catalog object. Make a catalog object of the MODIFIER type to represent skim milk, then set the price and ID.


/* 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($skimMilkPrice);

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


/* 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 7: Build a modifier list to contain your two modifiers
Permalink Get a link to this section

Put your milk modifiers in an array called milkModifiers. Then, create a modifier list object called milkList and set milkModifiers in the modifiers field. Finally, create a catalog object of the type MODIFIER_LIST using milkList.

//put milk modifiers in an array
$milkModifiers = array($skimMilk, $wholeMilk);

$milkList = new \SquareConnect\Model\CatalogModifierList;
$milkList->setName("Milk Types");
$milkList->setModifiers($milkModifiers);

// Make a catalog obejct of the MODIFIER_LIST type
$milkOptions = new \SquareConnect\Model\CatalogObject;
$milkOptions->setType("MODIFIER_LIST");
$milkOptions->setId($milkModifierListId);
$milkOptions->setModifierListData($milkList);

Step 8: Apply modifier list to the $coffee item.
Permalink Get a link to this section

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

//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 9: Update the coffee catalog
Permalink Get a link to this section

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

Make a batch with the catalog objects we just made. The item variations ($smallCoffeeand $largeCoffee) and the modifier list are nested inside the item ($coffee) so we only need to set $coffee.

For testing purposes, we will print the result to the screen.

//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);


// 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);


// 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;
}