Orders API

Build with Orders API

Build with Orders API to create orders for itemized transactions and inventory tracking.

Backend

Prerequisites and assumptions
Permalink Get a link to this section

To build with the Orders API, the following must be true:

  • 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.

  • You are using HTTPS. HTTPS is required for all production Square API calls. HTTP calls are only supported for developing and testing on localhost.

  • 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.


Additionally this guide makes the following assumptions:

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

  • You can create and run websites on localhost or a development server. If you are new to testing webpages locally, we recommend reading Running Local Web Servers before continuing.

  • You are familiar with basic web development. If you are new to web development, we recommend reading Getting started with the Web by Mozilla.org before continuing.

  • You are familiar with HTTPS. If this is your first time working with HTTPS, consider reading the TLS and HTTPS Overview.

Information you will need
Permalink Get a link to this section

To use the steps in this guide you will need the following information:

  • Your application ID. Find your application ID on the Credentials setting page of your Square application.

  • An active location ID. Copy a valid Developer Account location ID from the Locations setting page of your Square application in the Developer Dashboard, or set the dashboard to Sandbox Settings mode and then copy a sandbox location ID.

Step 1: Set your application credentials and create an API client
Permalink Get a link to this section

Set your application credentials and create an API client.

//Set your application credentials.
$accessToken = '{REPLACE_ME}';
$locationId = '{REPLACE_ME}';

// 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 2: Create an ad-hoc line item.
Permalink Get a link to this section

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\OrderLineItem;
$book->setName('The Shining');
$book->setQuantity('2');
$book->setBasePriceMoney($price);

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

Step 3: Create an Order with an ad-hoc line item.
Permalink Get a link to this section

Create an Order object using your ad-hoc line item.

Important

Item names must match exactly to make the best use of Square's reporting with ad-hoc items. For example, "Red Dog Collar: Leather", "Red Dog Collar - Leather", "Red Dog collar Leather", and "Red Dog Collar - Leather" are all considered different items because the strings use different punctuation, whitespace, and capitalization.

You can avoid issues with item names by referencing catalog IDs instead. Note that orders can have both ad-hoc and catalog line items.

//Create the Order object and set lineItems.
$order = new \SquareConnect\Model\Order;

$order->setLineItems($lineItems);

Step 4: Create and send the Order request
Permalink Get a link to this section

Create the Order request object and send it to the CreateOrder endpoint. For now, we will print the raw result to the screen.

Note that Orders require an idempotency key.

//Create the Order request object and set the idempotency key and Order.
$request = new \SquareConnect\Model\CreateOrderRequest();

$request->setIdempotencyKey(uniqid()); //uniqid() generates a random string.
$request->setOrder($order);

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