Manage Products

Orders API Setup Guide

Create orders for itemized transactions and inventory tracking.

This document provides guidance for creating orders with Square's Orders API.

Prerequisites

This document provides step-by-step guidance for setting up the Orders API. For information on how the Orders API works, please see the Orders API Overview.

To use the Orders API, you need:

  • A Square account. Create a Square account in minutes if you do not already have one.
  • A hosting solution that allows you to create dynamic pages with server side scripting (e.g., PHP, Ruby, ASP, Java). If your hosting solution only supports HTML, you cannot use the Orders API at this time.
  • If you are building an app using OAuth, you need the ORDERS_WRITE permission to create orders and the ORDERS_READ permission to retrieve orders.

Assumptions

This guide makes the following assumptions:

  • You have read the Orders API Overview, which covers general functionality of the API.
  • You can create and run websites on localhost or a development server.
  • You are familiar with HTML and PHP.
  • You are familiar with HTTPS. If this is your first time working with HTTPS, consider reading the TLS and HTTPS Overview.

Working example

Our sample code has the following characteristics. These characteristics are not required to use the Orders 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, OAuth is not currently supported in sandbox and unscoped tokens (sandbox tokens, personal access tokens) provide an easy way to get started quickly.
  • We use PHP version 5.4 or later. But the Orders API is language agnostic and the setup steps are comparable across languages.
  • We use the Square Connect PHP SDK. Installing the SDK makes development easier, but it is optional. As long as you can package and receive JSON messages you can use Square's APIs.

Step 1: Get your application credentials

We recommend using sandbox ID and locations for testing and development. To get your sandbox ID:

  1. Open your Application Dashboard.
  2. If you DO have an application you want to use for accepting online payments, click on the application.
  3. 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.
  4. Copy the Sandbox Access Token value on the Credentials tab of the application control panel.

Instead of a sandbox or personal access token, you can also use OAuth and the ORDERS_WRITE and ORDERS_READ permission. OAuth is the preferred API authorization mechanism for production applications because it allows you to scope permissions. You can also review, renew, or revoke access at any time. Sandbox tokens and personal access tokens are appropriate for testing and development.

Step 2: Download and install the SDK

Install the Square Connect PHP SDK if you have not already. You can read the installation instructions here.

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

Important: Remember to change the path depending on where you place the SDK in relation to your other php files.

Step 3: Set your application credentials and create an API client

  1. Set your application credentials.
//Replace your access token and location ID
$accessToken = '{REPLACE_ME}';
$locationId = '{REPLACE_ME}';
  1. Create an API client using the PHP SDK.
// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();
$defaultApiConfig->setAccessToken($accessToken);
$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$api_instance = new SquareConnect\Api\OrdersApi($defaultApiClient);

Step 4: Create an ad-hoc line item

Order requests must include at least 1 line item. You can create line items that reference an existing catalog, or you can create an ad-hoc line item.

For now, we will create an ad-hoc line item because it is faster to get started with ad-hoc line items. However, we strongly recommend that you create line items by referencing catalog IDs.

//Create a Money object to represent the price of the line item.
$price = new \SquareConnect\Model\Money;
$price->setAmount(600);
$price->setCurrency('USD');

//Create the line item and set details
$book = new \SquareConnect\Model\CreateOrderRequestLineItem;
$book->setName('The Shining');
$book->setQuantity('2');
$book->setBasePriceMoney($price);

//Puts our line item object in an array called lineItems.
$lineItems = array();
array_push($lineItems, $book);

Step 5: Create and send the Order request

  1. Create the Order request object. Orders require an idempotency key.
//Create the Order request object and set the idempotency key and line items.
$request = new \SquareConnect\Model\CreateOrderRequest();

$request->setIdempotencyKey(uniqid()); //uniqid() generates a random string.
$request->setLineItems($lineItems);

  1. Send the Order request object to the CreateOrder endpoint. For now, we'll print the raw result to the screen.
try {
    $result = $api_instance->createOrder($locationId, $request);
    print_r($result);
}
catch (Exception $e) {
    echo '<pre>';
    echo 'Exception when calling OrdersApi->createOrder:', $e->getMessage(), PHP_EOL;
}

We recommend first creating a catalog for your items, then referencing catalog object IDs when creating line items for your orders. While it might require extra work to get started, creating catalog objects simplifies long term maintenance and reporting for orders. For example, you can enable inventory tracking for orders built using catalog object IDs. Square can use catalog object IDs to track catalog objects across multiple orders.

Learn more about catalogs by reading the Catalog API Overview.

To reference a line item in your order

Fetch the IDs for the catalog item variations in the order. If you are building an eCommerce site with the Catalog API, you may already have it in your shopping cart session.

You can search for Catalog objects with the SearchCatalogObject endpoint.

//Set your catalog ID.
$catalogId = '{REPLACE_ME}';

Line items built from a product catalog only include a quantity and an optional note. The base price and name of the line item is configured as part of the catalog object.

//Create the line item and set details
$book = new \SquareConnect\Model\CreateOrderRequestLineItem;
$book->setCatalogObjectId($catalogId);
$book->setQuantity('2');
$book->setNote('An optional note that will appear as the item description in the Items report list');

// Add this line item to an array called lineItems.
$lineItems = array();
array_push($lineItems, $book);

Next Steps

Once you create an order, you can link it to a transaction. Completed orders can be retrieved using the BatchRetrieveOrders endpoint.

Next
Transactions Setup Guide >

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