This is a sample command line application providing examples of common Catalog API interactions.
This README assumes you are using Maven to build and run Java code. If you are not using Maven, the app should still work, but you will need to follow your existing build/execution steps.
To execute the examples in this demo, you'll need a personal access token from Square. If you already have one, you can use it for this demo. If you don't already have one (or want to use a different one) you can generate a new access token:
-
Visit the Developer Dashboard at https://developer.squareup.com/apps
-
Click "+" under Applications to create a new application.
-
Create an application with the name "Catalog API Demo".
-
Click on the application you have just created, and navigate to "Credentials"
-
Copy the Access Token on that page and save it to an environment variable:
export SQUARE_ACCESS_TOKEN={{ YOUR NEW ACCESS TOKEN }}
The src directory should contain everything you need to compile and run the
demo app. To build catalog-api-demo:
mvn compileTo confirm the demo is runnable, use the -list-examples flag to see all
the available examples:
mvn -q exec:java "-Dexec.args=-list-examples"For simplicity, here is a list of available examples and their description:
| Example Name | Description |
|---|---|
| create_item | Creates an item, then retrieve it |
| delete_all_items | Deletes ALL items. This is a destructive action and cannot be undone |
| apply_tax_to_all_items | Applies a selected tax to all items |
| deduplicate_taxes | Merges identical taxes (same name, percentage, and inclusion type) |
| delete_category | Creates a category with three items, then delete the category and items |
| list_categories | Lists all categories |
| list_discounts | Lists all discounts |
| location_specific_price | Creates an item with a location-specific price. Must have at least 2 locations to run this example |
| search_items | Searches for items |
| retrieve_catalog_object | Retrieves a catalog object by ID |
| globally_enable_items | Makes all items available at all locations |
| clone_catalog | Clones catalog objects from one merchant account to another |
Source code for each of the examples is listed under
src/main/java/com/squareup/catalog/demo/example/.
Running an example has the following syntax:
mvn -q exec:java "-Dexec.args={{ example name }} -token {{ accessToken }}"For example, if your SQUARE_ACCESS_TOKEN is set:
mvn -q exec:java "-Dexec.args=create_item"By default, the example will use the sandbox environment: https://connect.squareupsandbox.com/
In order to use the production environment, use the -env flag with the production argument:
mvn -q exec:java "-Dexec.args=create_item -token $SQUARE_ACCESS_TOKEN -env production"In order to use a different/custom URL, use the -base-url flag with your custom URL and omit the -env flag.
Some examples create items and other catalog objects in your merchant catalog. You can
cleanup the objects created by an example using the -cleanup flag.
Note that the cleanup code will delete items and other objects by name, and as such may delete items with the same name that were not created by the example.
For example:
mvn -q exec:java "-Dexec.args=create_item -token $SQUARE_ACCESS_TOKEN -cleanup"Rate this sample app here!