Connect API v2 Reference

Connect API v2 Conventions

Client libraries

Square provides client libraries for Connect V2 in a variety of programming languages. See Client libraries for a full list.

Swagger specification

Version 2 of the Connect API is defined with the Swagger specification. The definition is available on Github. You can use this definition to simplify certain development tasks, such as by generating custom client libraries.

See Generating client libraries and other tools with Swagger for more information.

Endpoint paths

Connect API endpoints are hosted from the base URL https://connect.squareup.com. For example, the ListTransactions endpoint's full path is:

https://connect.squareup.com/v2/locations/{location_id}/transactions

Most endpoint paths include a location_id parameter that indicates which of a business's locations your application is acting on behalf of. You can get a business's location IDs with the ListLocations endpoint.

API versions

An endpoint's API version is included in its path. Bug fixes and minor feature additions might be made to an endpoint's behavior without advancing its version number. This can include adding optional parameters or response fields. To prevent future compatibility issues, your application should be prepared to receive response fields beyond those currently returned by a given endpoint.

Functionality is never removed from a particular version of an endpoint, nor do field names or types change.

The most recent version of the the Connect API is v2. Connect API applications can communicate with endpoints from all available versions.

Endpoint names and return values

An endpoint's name indicates the type of data it handles and the action it performs on that data. The most common actions are:

Action HTTP Method Description
Create POST Creates and persists an entity of the corresponding type.
List GET Returns all instances of a particular entity that match query parameters you provide.
Retrieve GET Returns the single instance of an entity that matches the identifier you provide.
Update PUT Modifies the existing entity that matches the identifier you provide.
Delete DELETE Deletes the existing entity that matches the identifier you provide. Deleted entities cannot be retrieved or undeleted.

For example, the ListTransactions endpoint returns an array of processed payments, and the CreateCustomer endpoint creates and persists a customer.

Request and response headers

Requests to Connect API endpoints must include the following HTTP headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

In the place of YOUR_ACCESS_TOKEN, provide either your application's personal access token (available from the application dashboard) or an access token you generated with the OAuth API.

POST and PUT requests must include one additional header:

Content-Type: application/json

By default, all endpoint responses provide data as JSON in the response body and include a Content-Type: application/json header.

Providing parameters

The way you provide parameters to a Connect API request depends on the HTTP method of the request.

GET and DELETE requests

For GET and DELETE requests, you provide parameters in a query string you append to your request's URL. For example, you provide the sort_order parameter to the ListTransactions endpoint like so:

https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?sort_order=ASC

Values for query parameters must be URL-escaped. For example, to provide the value 2016-01-15T00:00:00+02:00 as the begin_time parameter of the ListTransactions endpoint, you specify the following:

https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?begin_time=2016-01-15T00%3A00%3A00%2B02%3A00

POST and PUT requests

For POST and PUT requests, you instead provide parameters as JSON in the body of your request.

For example, the body of a request to the CreateCustomer endpoint looks like this:

{
  "given_name": "Amelia",
  "family_name": "Earhart"
}

Working with monetary amounts

All monetary amounts in the Connect API are represented by the Money object, which has the following structure:

{
  "amount": 400,
  "currency_code": "USD"
}

Important: Unlike version 1 of the Connect API, all monetary amounts returned by v2 endpoints are positive. (In v1, monetary amounts are negative if they represent money being paid by a merchant, instead of money being paid to a merchant.)

The amount field is always in the smallest denomination of the currency indicated by currency_code. When currency_code is USD (US dollars), amount is in cents. The object shown above represents $4.00.

The currency_code field is in ISO 4217 format.

Working with dates

All representations of dates are strings in RFC 3339 format.

You can provide date strings that are either UTC (for example, 2016-01-15T00:00:00Z) or offset from UTC to indicate time zone (for example, 2016-01-15T00:00:00-08:00 for eight hours behind UTC). If you provide offset dates, be sure to account for daylight saving time correctly, if applicable.

Date strings returned by the Connect API are always UTC.

Date ranges

List endpoints such as ListTransactions often accept an optional date range with the begin_time and end_time parameters. They also accept an optional sort_order parameter, which indicates whether results are returned in chronological order (oldest first) or reverse-chronological order (newest first).

Regardless of sort_order, begin_time is the earlier date and end_time is the later date.

  • When sort_order is DESC (newest-first), begin_time is exclusive and end_time is inclusive.
  • When sort_order is ASC (oldest-first), begin_time is inclusive and end_time is exclusive.

The described date range must cover at least one millisecond.

Idempotency keys

Certain Connect API endpoints (currently Charge and CreateRefund) require an idempotency_key string parameter. Any time you want to initiate a new card transaction or refund, you should provide a new, unique value for this parameter.

Virtually all popular programming languages provide a function for generating unique strings. For example:

Language Function
Ruby SecureRandom.uuid
PHP uniqid
Java UUID.randomUUID
Python uuid

Idempotency keys must be unique per business, not per application. They cannot exceed 128 characters.

If you're unsure whether a particular transaction succeeded (for example, if you don't receive a response from an endpoint for some reason), you can reattempt it with the same idempotency key without worrying about creating a duplicate transaction.

Paginating results

List endpoints such as ListTransactions might paginate the results they return. This means that instead of returning all results in a single response, these endpoints might return some of the results, along with a cursor in the response body that links to the next set of results.

Send a followup request to the same endpoint, providing the cursor value returned in the previous response as a query parameter, to fetch the next set of results. Repeat this process until you receive a response without a cursor.

Handling duplicate results

List endpoints might return duplicate results. Use the id attribute of the returned objects to identify any such duplicates.

Handling the enum value OTHER

Some Connect API enums include the value OTHER. If you retrieve an object that currently has the value OTHER for one of its fields, that field might have a different value if you retrieve the object again at a later date, when an appropriate value has been added to the enum.

Enum values besides OTHER never change retroactively.

Replacing application credentials

You can replace your application's personal access token or application secret from the application dashboard.

  • Click Replace Token next to the Personal Access Token field to generate a new token for your application.
  • Click Replace Secret next to the Application Secret field to generate a new secret for your application.

Replacing an application credential immediately invalidates the previous credential. Make sure you update your application accordingly.

Rate limiting

If Connect API endpoints receive too many requests associated with the same application or access token in a short time window, they might respond with a 429 Too Many Requests error. If this occurs, try your request again at a later time.

Handling errors

Connect API endpoints use HTTP protocol status codes to indicate errors. Error code values range from 400 to 599.

All Connect v2 endpoints include an errors array in their response body if any errors occurred during a request. The response body has the following structure:

{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "UNAUTHORIZED",
      "detail": "This request could not be authorized."
    }
  ]
}

Each error in the array has the following fields:

  • category indicates which high-level category the error falls into. This value never changes for a particular error. See ErrorCategory for possible values.
  • code indicates the exact type of error that occurred. This value never changes for a particular error. See ErrorCode for possible values.
  • detail is a human-readable string that will help you diagnose the error. This value can change for a particular error.

Using OAuth

If you are developing a Connect v2 application for multiple merchants to use, you must request specific permissions from those merchants with the OAuth API. See the OAuth API Reference for more information.

API Sandbox Credentials

Connect API v2 provides a sandbox that lets you test out API endpoints in a non-production environment. Transactions created in the sandbox are not sent through to card networks, and cards are never charged. Below are API credentials you can use to play with Square's APIs.

Access Token
Application ID
Location ID

Read the HTTP PHP Ruby documentation:

API Endpoints

Charge

POST /v2/locations/{location_id}/transactions

Charges a card represented by a card nonce or a customer's card on file.

Your request to this endpoint must include either:

  • A value for the card_nonce parameter (to charge a card nonce generated with the SqPaymentForm)
  • Values for the customer_card_id and customer_id parameters (to charge a customer's card on file)

In order for an e-commerce payment to potentially qualify for Square chargeback protection, you must provide values for the following parameters in your request:

  • buyer_email_address
  • At least one of billing_address or shipping_address

When this response is returned, the amount of Square's processing fee might not yet be calculated. To obtain the processing fee, wait about ten seconds and call RetrieveTransaction. See the processing_fee_money field of each Tender included in the transaction.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to associate the created transaction with.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this transaction among transactions you've created.

If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about double-charging the buyer.

See Idempotency keys for more information.

amount_money
(required)
Money

The amount of money to charge.

Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details.

The value of currency must match the currency associated with the business that is charging the card.

card_nonce string

A nonce generated from the SqPaymentForm that represents the card to charge.

The application that provides a nonce to this endpoint must be the same application that generated the nonce with the SqPaymentForm. Otherwise, the nonce is invalid.

Do not provide a value for this field if you provide a value for customer_card_id.

customer_card_id string

The ID of the customer card on file to charge. Do not provide a value for this field if you provide a value for card_nonce.

If you provide this value, you must also provide a value for customer_id.

delay_capture boolean

If true, the request will only perform an Auth on the provided card. You can then later perform either a Capture (with the CaptureTransaction endpoint) or a Void (with the VoidTransaction endpoint).

Default value: false

reference_id string

An optional ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database).

This value cannot exceed 40 characters.

note string

An optional note to associate with the transaction.

This value cannot exceed 60 characters.

customer_id string

The ID of the customer to associate this transaction with. This field is required if you provide a value for customer_card_id, and optional otherwise.

billing_address Address

The buyer's billing address. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor shipping_address is provided.

shipping_address Address

The buyer's shipping address, if available. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor billing_address is provided.

buyer_email_address string

The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The created transaction.

Example HTTP Request

POST /v2/locations/LOCATION_ID/transactions{
  "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
  "shipping_address": {
    "address_line_1": "123 Main St",
    "locality": "San Francisco",
    "administrative_district_level_1": "CA",
    "postal_code": "94114",
    "country": "US"
  },
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "administrative_district_level_1": "NY",
    "locality": "New York",
    "postal_code": "10003",
    "country": "US"
  },
  "amount_money": {
    "amount": 5000,
    "currency": "USD"
  },
  "card_nonce": "card_nonce_from_square_123",
  "reference_id": "some optional reference id",
  "note": "some optional note",
  "delay_capture": false
}

Example Request in PHP

$api = new \SquareConnect\Api\TransactionApi();
$idempotencyKey = uniqid();
$api->charge($ACCESS_TOKEN, $LOCATION_ID, array(
  'idempotency_key' => $idempotencyKey,
  'amount_money' => array(
    'amount' => 200, 'currency' => 'USD'
  ),
  'card_nonce' => $cardNonce,
  'shipping_address' => array(
    'address_line_1' => '123 Main St',
    'locality' => 'San Francisco',
    'administrative_district_level_1' => 'CA',
    'postal_code' => '94114',
    'country' => 'US'
  ),
  'billing_address' => array(
    'address_line_1' => '500 Electric Ave',
    'address_line_2' => 'Suite 600',
    'administrative_district_level_1' => 'NY',
    'locality' => 'New York',
    'postal_code' => '20003',
    'country' => 'US'
  ),
  'reference_id' => 'optional reference #112358',
  'note' => 'optional note'
));

Example Request in Ruby

api = SquareConnect::TransactionApi.new
idempotency_key = SecureRandom.uuid
api.charge(ACCESS_TOKEN, LOCATION_ID, {
  idempotency_key: idempotency_key,
  amount_money: {
    amount: 200, currency: 'USD'
  },
  card_nonce: card_nonce,
  shipping_address: {
    address_line_1: '123 Main St',
    locality: 'San Francisco',
    administrative_district_level_1: 'CA',
    postal_code: '94114',
    country: 'US'
  },
  billing_address: {
    address_line_1: '500 Electric Ave',
    address_line_2: 'Suite 600',
    administrative_district_level_1: 'NY',
    locality: 'New York',
    postal_code: '20003',
    country: 'US'
  },
  reference_id: 'optional reference #112358',
  note: 'optional note'
})

Example Response

{
  "transaction": {
    "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "location_id": "18YC4JDH91E1H",
    "created_at": "2016-03-10T22:57:56Z",
    "tenders": [
      {
        "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
        "location_id": "18YC4JDH91E1H",
        "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
        "created_at": "2016-03-10T22:57:56Z",
        "note": "some optional note",
        "amount_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111"
          },
          "entry_method": "KEYED"
        }
      }
    ],
    "reference_id": "some optional reference id",
    "product": "EXTERNAL_API"
  }
}

ListTransactions

GET /v2/locations/{location_id}/transactions

Lists transactions for a particular location.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list transactions for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Paginating results for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transactions Transaction[]

An array of transactions that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Paginating results for more information.

Example HTTP Request

GET https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Request in PHP

$api = new \SquareConnect\Api\TransactionApi();
$api->listTransactions($ACCESS_TOKEN, $LOCATION_ID,
  '2016-08-10T21:35:00Z', '2016-08-10T21:35:15Z');

Example Request in Ruby

api = SquareConnect::TransactionApi.new
api.list_transactions(ACCESS_TOKEN, LOCATION_ID, {
  begin_time: DateTime.parse('2016-08-10 21:35:00 UTC'),
  end_time: DateTime.parse('2016-08-10 21:35:15 UTC')
})

Example Response

{
  "transactions": [
    {
      "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
      "location_id": "18YC4JDH91E1H",
      "created_at": "2016-03-10T22:57:56Z",
      "tenders": [
        {
          "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
          "location_id": "18YC4JDH91E1H",
          "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
          "created_at": "2016-03-10T22:57:56Z",
          "note": "some optional note",
          "amount_money": {
            "amount": 5000,
            "currency": "USD"
          },
          "processing_fee_money": {
            "amount": 138,
            "currency": "USD"
          },
          "type": "CARD",
          "card_details": {
            "status": "CAPTURED",
            "card": {
              "card_brand": "VISA",
              "last_4": "1111"
            },
            "entry_method": "KEYED"
          }
        }
      ],
      "reference_id": "some optional reference id",
      "product": "EXTERNAL_API"
    }
  ]
}

CaptureTransaction

POST /v2/locations/{location_id}/transactions/{transaction_id}/capture

Captures a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string
transaction_id
(required)
string

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example HTTP Request

POST https://connect.squareup.com/v2/locations/LOCATION_ID/transactions/TRANSACTION_ID/capture

Example Request in PHP

$api = new \SquareConnect\Api\TransactionApi();
$api->captureTransaction($ACCESS_TOKEN, $LOCATION_ID, $transaction->getId());

Example Request in Ruby

api = SquareConnect::TransactionApi.new
api.capture_transaction(ACCESS_TOKEN, LOCATION_ID, transaction.id)

Example Response

{}

VoidTransaction

POST /v2/locations/{location_id}/transactions/{transaction_id}/void

Cancels a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string
transaction_id
(required)
string

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example HTTP Request

POST https://connect.squareup.com/v2/locations/LOCATION_ID/transactions/TRANSACTION_ID/void

Example Request in PHP

$api = new \SquareConnect\Api\TransactionApi();
$api->voidTransaction($ACCESS_TOKEN, $LOCATION_ID, $transaction->getId());

Example Request in Ruby

api = SquareConnect::TransactionApi.new
api.void_transaction(ACCESS_TOKEN, LOCATION_ID, transaction.id)

Example Response

{}

RetrieveTransaction

GET /v2/locations/{location_id}/transactions/{transaction_id}

Retrieves details for a single transaction.

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the transaction's associated location.

transaction_id
(required)
string

The ID of the transaction to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

transaction Transaction

The requested transaction.

Example HTTP Request

GET https://connect.squareup.com/v2/locations/LOCATION_ID/transactions/TRANSACTION_ID

Example Request in PHP

$api = new \SquareConnect\Api\TransactionApi();
$api->retrieveTransaction($ACCESS_TOKEN, $LOCATION_ID, $transaction->getId());

Example Request in Ruby

api = SquareConnect::TransactionApi.new
api.retrieve_transaction(ACCESS_TOKEN, LOCATION_ID, transaction.id)

Example Response

{
  "transaction": {
    "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "location_id": "18YC4JDH91E1H",
    "created_at": "2016-03-10T22:57:56Z",
    "tenders": [
      {
        "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
        "location_id": "18YC4JDH91E1H",
        "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
        "created_at": "2016-03-10T22:57:56Z",
        "note": "some optional note",
        "amount_money": {
          "amount": 5000,
          "currency": "USD"
        },
        "processing_fee_money": {
          "amount": 138,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111"
          },
          "entry_method": "KEYED"
        }
      }
    ],
    "reference_id": "some optional reference id",
    "product": "EXTERNAL_API"
  }
}

CreateRefund

POST /v2/locations/{location_id}/transactions/{transaction_id}/refund

Initiates a refund for a previously charged tender.

Required permissions: PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the original transaction's associated location.

transaction_id
(required)
string

The ID of the original transaction that includes the tender to refund.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A value you specify that uniquely identifies this refund among refunds you've created for the tender.

If you're unsure whether a particular refund succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the refund.

See Idempotency keys for more information.

tender_id
(required)
string

The ID of the tender to refund.

A Transaction has one or more tenders (i.e., methods of payment) associated with it, and you refund each tender separately with the Connect API.

reason string

A description of the reason for the refund.

Default value: Refund via API

amount_money
(required)
Money

The amount of money to refund.

Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details.

This amount cannot exceed the amount that was originally charged to the tender that corresponds to tender_id.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

refund Refund

The created refund.

Example HTTP Request

POST /v2/locations/LOCATION_ID/transactions/TRANSACTION_ID/refund{
  "idempotency_key": "YOUR_IDEMPOTENCY_KEY",
  "tender_id": "TENDER_ID",
  "reason": "a reason",
  "amount_money": {
    "amount": 100,
    "currency": "USD"
  }
}

Example Request in PHP

$api = new \SquareConnect\Api\RefundApi();
$idempotencyKey = uniqid();
$api->createRefund($ACCESS_TOKEN, $LOCATION_ID, $transaction->getId(), array(
  'tender_id' => $transaction->getTenders()[0]->getId(),
  'amount_money' => array(
    'amount' => 100,
    'currency' => 'USD'
  ),
  'idempotency_key' => $idempotencyKey,
  'reason' => 'Cancelled order'
));

Example Request in Ruby

api = SquareConnect::RefundApi.new
idempotency_key = SecureRandom.uuid
api.create_refund(ACCESS_TOKEN, LOCATION_ID, transaction.id, {
  tender_id: transaction.tenders.first.id,
  amount_money: {
    amount: 100,
    currency: 'USD'
  },
  idempotency_key: idempotency_key,
  reason: 'Cancelled order'
})

Example Response

{
  "refund": {
    "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
    "location_id": "18YC4JDH91E1H",
    "transaction_id": "TRANSACTION_ID",
    "tender_id": "TENDER_ID",
    "created_at": "2016-02-12T00:28:18Z",
    "reason": "some reason",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "PENDING"
  }
}

ListRefunds

GET /v2/locations/{location_id}/refunds

Lists refunds for one of a business's locations.

Refunds with a status of PENDING are not currently included in this endpoint's response.

Max results per page: 50

Required permissions: PAYMENTS_READ

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the location to list refunds for.

Query Parameters

Name Type Description
begin_time string

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time string

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order string

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Paginating results for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

refunds Refund[]

An array of refunds that match your query.

cursor string

A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the cursor parameter in a subsequent request to this endpoint.

See Paginating results for more information.

Example HTTP Request

GET https://connect.squareup.com/v2/locations/LOCATION_ID/refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z

Example Request in PHP

$api = new \SquareConnect\Api\RefundApi();
$api->listRefunds($ACCESS_TOKEN, $LOCATION_ID,
  '2016-08-10T21:35:15Z', '2016-08-10T23:40:00Z');

Example Request in Ruby

api = SquareConnect::RefundApi.new
api.list_refunds(ACCESS_TOKEN, LOCATION_ID, {
  begin_time: DateTime.parse('2016-08-10 21:35:15 UTC'),
  end_time: DateTime.parse('2016-08-10 23:40:00 UTC')
})

Example Response

{
  "refunds": [
    {
      "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
      "location_id": "18YC4JDH91E1H",
      "transaction_id": "TRANSACTION_ID",
      "tender_id": "TENDER_ID",
      "created_at": "2016-02-12T00:28:18Z",
      "reason": "some reason",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "status": "APPROVED"
    }
  ]
}

ListLocations

GET /v2/locations

Provides the details for all of a business's locations.

Most other Connect API endpoints have a required location_id path parameter. The id field of the Location objects returned by this endpoint correspond to that location_id parameter.

Required permissions: MERCHANT_PROFILE_READ

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

locations Location[]

The business's locations.

Example HTTP Request

GET https://connect.squareup.com/v2/locations

Example Request in PHP

$api = new \SquareConnect\Api\LocationApi();
$api->listLocations($ACCESS_TOKEN);

Example Request in Ruby

api = SquareConnect::LocationApi.new
api.list_locations(ACCESS_TOKEN)

Example Response

{
  "locations": [
    {
      "id": "18YC4JDH91E1H",
      "name": "your location name",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94114",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING"
      ]
    }
  ]
}

CreateCustomer

POST /v2/customers

Creates a new customer for a business, which can have associated cards on file.

You must provide at least one of the following values in your request to this endpoint:

  • given_name
  • family_name
  • company_name
  • email_address
  • phone_number

This endpoint does not accept an idempotency key. If you accidentally create a duplicate customer, you can delete it with the DeleteCustomer endpoint.

Required permissions: CUSTOMERS_WRITE

Body Parameters

Name Type Description
given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

company_name string

The name of the customer's company.

nickname string

A nickname for the customer.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

reference_id string

An optional second ID you can set to associate the customer with an entity in another system.

note string

An optional note to associate with the customer.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The created customer.

Example HTTP Request

POST /v2/customers{
  "given_name": "Amelia",
  "family_name": "Earhart",
  "email_address": "Amelia.Earhart@example.com",
  "address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "phone_number": "1-212-555-4240",
  "reference_id": "YOUR_REFERENCE_ID",
  "note": "a customer"
}

Example Request in PHP

$api = new \SquareConnect\Api\CustomerApi();
$api->createCustomer($ACCESS_TOKEN, array(
  'given_name' => 'Amelia',
  'family_name' => 'Earhart',
  'email_address' => 'Amelia.Earhart@example.com',
  'address' => array(
    'address_line_1' => '500 Electric Ave',
    'address_line_2' => 'Suite 600',
    'locality' => 'New York',
    'administrative_district_level_1' => 'NY',
    'postal_code' => '10003',
    'country' => 'US'
  ),
  'phone_number' => '1-555-555-0122',
  'reference_id' => 'YOUR_REFERENCE_ID',
  'note' => 'a customer'
));

Example Request in Ruby

api = SquareConnect::CustomerApi.new
api.create_customer(ACCESS_TOKEN, {
  given_name: 'Amelia',
  family_name: 'Earhart',
  email_address: 'Amelia.Earhart@example.com',
  address: {
    address_line_1: '500 Electric Ave',
    address_line_2: 'Suite 600',
    locality: 'New York',
    administrative_district_level_1: 'NY',
    postal_code: '10003',
    country: 'US'
  },
  phone_number: '1-555-555-0122',
  reference_id: 'YOUR_REFERENCE_ID',
  note: 'a customer'
})

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer"
  }
}

ListCustomers

GET /v2/customers

Lists a business's customers.

Required permissions: CUSTOMERS_READ

Query Parameters

Name Type Description
cursor string

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Paginating results for more information.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customers Customer[]

An array of Customer objects that match your query.

cursor string

A pagination cursor to retrieve the next set of results for your original query to the endpoint. This value is present only if the request succeeded and additional results are available.

See Paginating results for more information.

Example HTTP Request

GET https://connect.squareup.com/v2/customers

Example Request in PHP

$api = new \SquareConnect\Api\CustomerApi();
$api->listCustomers($ACCESS_TOKEN);

Example Request in Ruby

api = SquareConnect::CustomerApi.new
api.list_customers(ACCESS_TOKEN)

Example Response

{
  "customers": [
    {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2016-03-23T20:21:54.859Z",
      "updated_at": "2016-03-23T20:21:55Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "Amelia.Earhart@example.com",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "1-212-555-4240",
      "reference_id": "YOUR_REFERENCE_ID",
      "note": "a customer",
      "groups": [
        {
          "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
          "name": "Aviation Enthusiasts"
        }
      ]
    }
  ]
}

UpdateCustomer

PUT /v2/customers/{customer_id}

Updates the details of an existing customer.

You cannot edit a customer's cards on file with this endpoint. To make changes to a card on file, you must delete the existing card on file with the DeleteCustomerCard endpoint, then create a new one with the CreateCustomerCard endpoint.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to update.

Body Parameters

Name Type Description
given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

company_name string

The name of the customer's company.

nickname string

A nickname for the customer.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

reference_id string

An optional second ID you can set to associate the customer with an entity in another system.

note string

An optional note to associate with the customer.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The updated customer.

Example HTTP Request

PUT /v2/customers/CUSTOMER_ID{
  "phone_number": "",
  "email_address": "New.Amelia.Earhart@example.com",
  "note": "updated customer note"
}

Example Request in PHP

$api = new \SquareConnect\Api\CustomerApi();
$api->updateCustomer($ACCESS_TOKEN, $customer->getId(), array(
  'phone_number' => '',
  'email_address' => 'New.Amelia.Earhart@example.com',
  'note' => 'updated customer note'
));

Example Request in Ruby

api = SquareConnect::CustomerApi.new
api.update_customer(ACCESS_TOKEN, customer.id, {
  phone_number: '',
  email_address: 'New.Amelia.Earhart@example.com',
  note: 'updated customer note'
})

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-25T20:21:55Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "New.Amelia.Earhart@example.com",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "updated customer note",
    "groups": [
      {
        "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
        "name": "Aviation Enthusiasts"
      }
    ]
  }
}

RetrieveCustomer

GET /v2/customers/{customer_id}

Returns details for a single customer.

Required permissions: CUSTOMERS_READ

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to retrieve.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

customer Customer

The requested customer.

Example HTTP Request

GET https://connect.squareup.com/v2/customers/CUSTOMER_ID

Example Request in PHP

$api = new \SquareConnect\Api\CustomerApi();
$api->retrieveCustomer($ACCESS_TOKEN, $customer->getId());

Example Request in Ruby

api = SquareConnect::CustomerApi.new
api.retrieve_customer(ACCESS_TOKEN, customer.id)

Example Response

{
  "customer": {
    "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
    "created_at": "2016-03-23T20:21:54.859Z",
    "updated_at": "2016-03-23T20:21:54.859Z",
    "given_name": "Amelia",
    "family_name": "Earhart",
    "email_address": "Amelia.Earhart@example.com",
    "address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    },
    "phone_number": "1-212-555-4240",
    "reference_id": "YOUR_REFERENCE_ID",
    "note": "a customer",
    "groups": [
      {
        "id": "16894e93-96eb-4ced-b24b-f71d42bf084c",
        "name": "Aviation Enthusiasts"
      }
    ]
  }
}

DeleteCustomer

DELETE /v2/customers/{customer_id}

Deletes a customer from a business, along with any linked cards on file.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example HTTP Request

DELETE https://connect.squareup.com/v2/customers/CUSTOMER_ID

Example Request in PHP

$api = new \SquareConnect\Api\CustomerApi();
$api->deleteCustomer($ACCESS_TOKEN, $customer->getId());

Example Request in Ruby

api = SquareConnect::CustomerApi.new
api.delete_customer(ACCESS_TOKEN, customer.id)

Example Response

{}

CreateCustomerCard

POST /v2/customers/{customer_id}/cards

Adds a card on file to an existing customer.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer to link the card on file to.

Body Parameters

Name Type Description
card_nonce
(required)
string

A card nonce representing the credit card to link to the customer.

Card nonces are generated by the SqPaymentForm that buyers enter their card information into. See Embedding the payment form for more information.

billing_address Address

Address information for the card on file. Only the postal_code field is required for payments in the US and Canada.

cardholder_name string

The cardholder's name.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

card Card

The created card on file.

Example HTTP Request

POST /v2/CUSTOMER_ID{
  "card_nonce": "YOUR_CARD_NONCE",
  "billing_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "country": "US"
  },
  "cardholder_name": "Amelia Earhart"
}

Example Request in PHP

$api = new \SquareConnect\Api\CustomerCardApi();
$api->createCustomerCard($ACCESS_TOKEN, $customer->getId(), array(
  'card_nonce' => $cardNonce,
  'billing_address' => array(
    'address_line_1' => '1455 Market St',
    'address_line_2' => 'Suite 600',
    'locality' => 'San Francisco',
    'administrative_district_level_1' => 'CA',
    'postal_code' => '94103',
    'country' => 'US'
  ),
  'cardholder_name' => 'Amelia Earhart'
));

Example Request in Ruby

api = SquareConnect::CustomerCardApi.new
api.create_customer_card(ACCESS_TOKEN, customer.id, {
  card_nonce: card_nonce,
  billing_address: {
    address_line_1: '1455 Market St',
    address_line_2: 'Suite 600',
    locality: 'San Francisco',
    administrative_district_level_1: 'CA',
    postal_code: '94103',
    country: 'US'
  },
  cardholder_name: 'Amelia Earhart'
})

Example Response

{
  "card": {
    "id": "icard-card_id",
    "card_brand": "VISA",
    "last_4": "1111",
    "exp_month": 11,
    "exp_year": 2018,
    "cardholder_name": "Amelia Earhart",
    "billing_address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "country": "US"
    }
  }
}

DeleteCustomerCard

DELETE /v2/customers/{customer_id}/cards/{card_id}

Removes a card on file from a customer.

Required permissions: CUSTOMERS_WRITE

Path Parameters

Name Type Description
customer_id
(required)
string

The ID of the customer that the card on file belongs to.

card_id
(required)
string

The ID of the card on file to delete.

Response fields

Name Type Description
errors Error[]

Any errors that occurred during the request.

Example HTTP Request

DELETE https://connect.squareup.com/v2/customers/CUSTOMER_ID

Example Request in PHP

$api = new \SquareConnect\Api\CustomerCardApi();
$api->deleteCustomerCard($ACCESS_TOKEN, $customer->getId(), $customerCard->getId());

Example Request in Ruby

api = SquareConnect::CustomerCardApi.new
api.delete_customer_card(ACCESS_TOKEN, customer.id, customer_card.id)

Example Response

{}

CreateCheckout

POST /v2/locations/{location_id}/checkouts

Creates a Checkout response that links a checkoutId and checkout_page_url that customers can be directed to in order to provide their payment information using a payment processing workflow hosted on connect.squareup.com.

Required permissions: ORDERS_V2_WRITE PAYMENTS_WRITE

Path Parameters

Name Type Description
location_id
(required)
string

The ID of the business location to associate the checkout with.

Body Parameters

Name Type Description
idempotency_key
(required)
string

A unique string that identifies this checkout among others you've created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than once. If you're unsure whether a particular checkout was created successfully, you can reattempt it with the same idempotency key and all the same other parameters without worrying about creating duplicates.

We recommend using a random number/string generator native to the language you are working in to generate strings for your idempotency keys.

See Idempotency keys for more information.

order
(required)
CreateOrderRequestOrder

The order including line items to be checked out.

ask_for_shipping_address boolean

If true, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard.

Default is false.

merchant_support_email string

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account.

Default is unset.

pre_populate_buyer_email string

If provided, the buyer's email is pre-populated on the checkout page as an editable text field.

Default is unset.

pre_populate_shipping_address Address

If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields.

Default is unset.

redirect_url string

The URL to redirect to after checkout is completed with checkoutId, Square's orderId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect_url is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

Default is unset.

Response fields

Name Type Description
checkout Checkout

The newly created checkout. If the same request was made with the same idempotencykey, this will be the checkout created with the idempotencykey.

errors Error[]

Any errors that occurred during the request.

Example HTTP Request

POST /v2/locations/LOCATION_ID/checkouts{
  "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
  "order": {
    "reference_id": "my-order-001",
    "line_items": [
      {
        "name": "line-item-1",
        "quantity": "1",
        "base_price_money": {
          "amount": 1599,
          "currency": "USD"
        }
      },
      {
        "name": "line-item-2",
        "quantity": "2",
        "base_price_money": {
          "amount": 799,
          "currency": "USD"
        }
      }
    ]
  },
  "ask_for_shipping_address": true,
  "merchant_support_email": "merchant+support@website.com",
  "pre_populate_buyer_email": "buyer@email.com",
  "pre_populate_shipping_address": {
    "address_line_1": "500 Electric Ave",
    "address_line_2": "Suite 600",
    "locality": "New York",
    "administrative_district_level_1": "NY",
    "postal_code": "10003",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "redirect_url": "https://merchant.website.com/order-confirm"
}

Example Response

{
  "checkout": {
    "id": "CAISEHGimXh-C3RIT4og1a6u1qw",
    "checkout_page_url": "https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8",
    "ask_for_shipping_address": true,
    "merchant_support_email": "merchant+support@website.com",
    "pre_populate_buyer_email": "buyer@email.com",
    "pre_populate_shipping_address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "locality": "New York",
      "administrative_district_level_1": "NY",
      "postal_code": "10003",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "order": {
      "id": "CAISEJOSTTqtofh-wiJrEXpkEAg",
      "location_id": "CYTKRM7R7JMV8",
      "reference_id": "my-order-001",
      "line_items": [
        {
          "id": "51fa1d80-0720-5b3f-6804-a18f7861d2c7",
          "name": "line-item-1",
          "quantity": "1",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        },
        {
          "id": "0d53440b-b9f4-5271-7555-cb43c7af9575",
          "name": "line-item-2",
          "quantity": "2",
          "base_price_money": {
            "amount": 799,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1598,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 3197,
        "currency": "USD"
      }
    },
    "created_at": "2017-01-18T22:25:54Z"
  }
}

API Data Types

Address

Represents a physical address.

Fields

Name Type Description
address_line_1 string

The first line of the address.

Fields that start with address_line provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).

address_line_2 string

The second line of the address, if any.

address_line_3 string

The third line of the address, if any.

locality string

The city or town of the address.

sublocality string

A civil region within the address's locality, if any.

sublocality_2 string

A civil region within the address's sublocality, if any.

sublocality_3 string

A civil region within the address's sublocality_2, if any.

administrative_district_level_1 string

A civil entity within the address's country. In the US, this is the state.

administrative_district_level_2 string

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

administrative_district_level_3 string

A civil entity within the address's administrative_district_level_2, if any.

postal_code string

The address's postal code.

country string

The address's country, in ISO 3166-1-alpha-2 format.

first_name string

Optional first name when it's representing recipient.

last_name string

Optional last name when it's representing recipient.

organization string

Optional organization name when it's representing recipient.

Card

Represents the non-confidential details of a credit card.

Fields

Name Type Description
id string

The card's unique ID, if any.

card_brand string

The card's brand (such as VISA). See CardBrand for all possible values.

last_4 string

The last 4 digits of the card's number.

exp_month integer

The month of the card's expiration date. This value is always between 1 and 12, inclusive.

exp_year integer

The four-digit year of the card's expiration date.

cardholder_name string

The cardholder name. This value is present only if this object represents a customer's card on file.

billing_address Address

The card's billing address. This value is present only if this object represents a customer's card on file.

Checkout

Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.

Fields

Name Type Description
id string

ID generated by Square Checkout when a new checkout is requested.

checkout_page_url string

The URL that the buyer's browser should be redirected to after the checkout is completed.

ask_for_shipping_address boolean

If true, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard.

Default is false.

merchant_support_email string

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant.

If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account.

Default is unset.

pre_populate_buyer_email string

If provided, the buyer's email is pre-populated on the checkout page as an editable text field.

Default is unset.

pre_populate_shipping_address Address

If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields.

Default is unset.

redirect_url string

The URL to redirect to after checkout is completed with checkoutId, Square's orderId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect_url is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

order Order

Order to be checked out.

created_at string

The time when the checkout was created, in RFC 3339 format.

CreateOrderRequest

Defines the parameters that can be included in the body of a request to the CreateOrder endpoint.

Fields

Name Type Description
idempotency_key string

A value you specify that uniquely identifies this order among orders you've created.

If you're unsure whether a particular order was created successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate orders.

See Idempotency keys for more information.

order Order

The order to be created.

CreateOrderRequestLineItem

Represents a line item to include in an order. Each line item describes a different product to purchase, with its own quantity and price details.

Fields

Name Type Description
name string

The name of the line item. This value cannot exceed 500 characters.

quantity string

The quantity to purchase, as a string representation of a number. Currently, only integer values are supported.

base_price_money Money

The base price for a single unit of the line item's associated variation. If a line item represents a Custom Amount instead of a particular product, this field indicates that amount.

CreateOrderRequestOrder

The object describes the order.

Fields

Name Type Description
reference_id string

An optional ID you can associate with the order for your own purposes (such as to associate the order with an entity ID in your own database).

This value cannot exceed 40 characters.

line_items CreateOrderRequestLineItem[]

The line items to associate with this order.

Each line item represents a different product (or a custom monetary amount) to include in a purchase.

Customer

Represents one of a business's customers, which can have one or more cards on file associated with it.

Fields

Name Type Description
id string

The customer's unique ID.

created_at string

The time when the customer was created, in RFC 3339 format.

updated_at string

The time when the customer was last updated, in RFC 3339 format.

cards Card[]

The non-confidential details of the customer's cards on file.

given_name string

The customer's given (i.e., first) name.

family_name string

The customer's family (i.e., last) name.

nickname string

The customer's nickname.

company_name string

The name of the customer's company.

email_address string

The customer's email address.

address Address

The customer's physical address.

phone_number string

The customer's phone number.

reference_id string

A second ID you can set to associate the customer with an entity in another system.

note string

A note to associate with the customer.

preferences CustomerPreferences

The customer's preferences.

groups CustomerGroupInfo[]

The groups the customer belongs to.

CustomerGroupInfo

Contains some brief information about a customer group with its identifier included.

Fields

Name Type Description
id string

The ID of the customer group.

name string

The name of the customer group.

CustomerPreferences

Represents a particular customer's preferences.

Fields

Name Type Description
email_unsubscribed boolean

The customer has unsubscribed from receiving marketing campaign emails.

Error

Represents an error encountered during a request to the Connect API.

See Handling errors for more information.

Fields

Name Type Description
category string

The error's high-level category. See ErrorCategory for possible values.

code string

The error's specific code. See ErrorCode for possible values

detail string

A human-readable description of the error for debugging purposes.

field string

The name of the field provided in the original request that the error pertains to, if any.

Location

Represents one of a business's locations.

Fields

Name Type Description
id string

The location's unique ID.

name string

The location's name.

address Address

The location's physical address.

timezone string

The IANA Timezone Database identifier for the location's timezone.

capabilities string[]

Indicates which Square features are enabled for the location.

See LocationCapability for possible values.

Money

Represents an amount of money.

Important: Unlike version 1 of the Connect API, all monetary amounts returned by v2 endpoints are positive. (In v1, monetary amounts are negative if they represent money being paid by a merchant, instead of money being paid to a merchant.)

Fields

Name Type Description
amount integer

The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.

currency string

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

Order

Contains all information related to a single order to process with Square, including line items that specify the products to purchase

Fields

Name Type Description
id string

The order's unique ID.

This value is not present if the order was not created with the CreateOrder endpoint.

location_id string

The ID of the merchant location this order is associated with.

reference_id string

A client specified identifier to associate an entity in another system with this order.

line_items OrderLineItem[]

The line items included in the order. Every order has at least one line item.

total_money Money

The total amount of money to collect for the order.

OrderLineItem

Represents a line item in an order. Each line item describes a different product to purchase, with its own quantity and price details.

Fields

Name Type Description
id string

The line item's ID, unique only within this order.

name string

The name of the line item.

quantity string

The quantity of the product to purchase. Currently, this string must have an integer value.

base_price_money Money

The base price for a single unit of the line item's associated variation.

If a line item represents a Custom Amount instead of a particular product, this field indicates that amount.

total_money Money

The total amount of money to collect for this line item.

Refund

Represents a refund processed for a Square transaction.

Fields

Name Type Description
id string

The refund's unique ID.

location_id string

The ID of the refund's associated location.

transaction_id string

The ID of the transaction that the refunded tender is part of.

tender_id string

The ID of the refunded tender.

created_at string

The time when the refund was created, in RFC 3339 format.

reason string

The reason for the refund being issued.

amount_money Money

The amount of money refunded to the buyer.

status string

The current status of the refund (PENDING, APPROVED, REJECTED, or FAILED).

processing_fee_money Money

The amount of Square processing fee money refunded to the merchant.

Tender

Represents a tender (i.e., a method of payment) used in a Square transaction.

Fields

Name Type Description
id string

The tender's unique ID.

location_id string

The ID of the transaction's associated location.

transaction_id string

The ID of the tender's associated transaction.

created_at string

The time when the tender was created, in RFC 3339 format.

note string

An optional note associated with the tender at the time of payment.

amount_money Money

The amount of the tender.

processing_fee_money Money

The amount of any Square processing fees applied to the tender.

This field is not immediately populated when a new transaction is created. It is usually available after about ten seconds.

customer_id string

If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.

type string

The type of tender, such as CARD or CASH.

card_details TenderCardDetails

The details of the card tender.

This value is present only if the value of type is CARD.

cash_details TenderCashDetails

The details of the cash tender.

This value is present only if the value of type is CASH.

TenderCardDetails

Represents additional details of a tender with type CARD or SQUARE_GIFT_CARD

Fields

Name Type Description
status string

The credit card payment's current state (such as AUTHORIZED or CAPTURED). See TenderCardDetailsStatus for possible values.

card Card

The credit card's non-confidential details.

entry_method string

The method used to enter the card's details for the transaction.

TenderCashDetails

Represents the details of a tender with type CASH.

Fields

Name Type Description
buyer_tendered_money Money

The total amount of cash provided by the buyer, before change is given.

change_back_money Money

The amount of change returned to the buyer.

Transaction

Represents a transaction processed with Square, either with the Connect API or with Square Register.

The tenders field of this object lists all methods of payment used to pay in the transaction.

Fields

Name Type Description
id string

The transaction's unique ID, issued by Square payments servers.

location_id string

The ID of the transaction's associated location.

created_at string

The time when the transaction was created, in RFC 3339 format.

tenders Tender[]

The tenders used to pay in the transaction.

refunds Refund[]

Refunds that have been applied to any tender in the transaction.

reference_id string

If the transaction was created with the Charge endpoint, this value is the same as the value provided for the reference_id parameter in the request to that endpoint. Otherwise, it is not set.

product string

The Square product that processed the transaction.

client_id string

If the transaction was created in the Square Register app, this value is the ID generated for the transaction by Square Register.

This ID has no relationship to the transaction's canonical id, which is generated by Square's backend servers. This value is generated for bookkeeping purposes, in case the transaction cannot immediately be completed (for example, if the transaction is processed in offline mode).

It is not currently possible with the Connect API to perform a transaction lookup by this value.

order Order

The order associated with this transaction, if any.

shipping_address Address

The shipping address provided in the request, if any.

API Enums

CardBrand

Indicates a credit card's brand, such as VISA.

Fields

Name Description
OTHER_BRAND
VISA
MASTERCARD
AMERICAN_EXPRESS
DISCOVER
DISCOVER_DINERS
JCB
CHINA_UNIONPAY
SQUARE_GIFT_CARD

Country

Indicates the country associated with another entity, such as a business. Values are in ISO 3166-1-alpha-2 format.

Fields

Name Description
ZZ
AD
AE
AF
AG
AI
AL
AM
AO
AQ
AR
AS
AT
AU
AW
AX
AZ
BA
BB
BD
BE
BF
BG
BH
BI
BJ
BL
BM
BN
BO
BQ
BR
BS
BT
BV
BW
BY
BZ
CA
CC
CD
CF
CG
CH
CI
CK
CL
CM
CN
CO
CR
CU
CV
CW
CX
CY
CZ
DE
DJ
DK
DM
DO
DZ
EC
EE
EG
EH
ER
ES
ET
FI
FJ
FK
FM
FO
FR
GA
GB
GD
GE
GF
GG
GH
GI
GL
GM
GN
GP
GQ
GR
GS
GT
GU
GW
GY
HK
HM
HN
HR
HT
HU
ID
IE
IL
IM
IN
IO
IQ
IR
IS
IT
JE
JM
JO
JP
KE
KG
KH
KI
KM
KN
KP
KR
KW
KY
KZ
LA
LB
LC
LI
LK
LR
LS
LT
LU
LV
LY
MA
MC
MD
ME
MF
MG
MH
MK
ML
MM
MN
MO
MP
MQ
MR
MS
MT
MU
MV
MW
MX
MY
MZ
NA
NC
NE
NF
NG
NI
NL
NO
NP
NR
NU
NZ
OM
PA
PE
PF
PG
PH
PK
PL
PM
PN
PR
PS
PT
PW
PY
QA
RE
RO
RS
RU
RW
SA
SB
SC
SD
SE
SG
SH
SI
SJ
SK
SL
SM
SN
SO
SR
SS
ST
SV
SX
SY
SZ
TC
TD
TF
TG
TH
TJ
TK
TL
TM
TN
TO
TR
TT
TV
TW
TZ
UA
UG
UM
US
UY
UZ
VA
VC
VE
VG
VI
VN
VU
WF
WS
YE
YT
ZA
ZM
ZW

Currency

Indicates the associated currency for an amount of money. Values correspond to ISO 4217.

Fields

Name Description
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
AWG
AZN
BAM
BBD
BDT
BGN
BHD
BIF
BMD
BND
BOB
BOV
BRL
BSD
BTN
BWP
BYR
BZD
CAD
CDF
CHE
CHF
CHW
CLF
CLP
CNY
COP
COU
CRC
CUC
CUP
CVE
CZK
DJF
DKK
DOP
DZD
EGP
ERN
ETB
EUR
FJD
FKP
GBP
GEL
GHS
GIP
GMD
GNF
GTQ
GYD
HKD
HNL
HRK
HTG
HUF
IDR
ILS
INR
IQD
IRR
ISK
JMD
JOD
JPY
KES
KGS
KHR
KMF
KPW
KRW
KWD
KYD
KZT
LAK
LBP
LKR
LRD
LSL
LTL
LVL
LYD
MAD
MDL
MGA
MKD
MMK
MNT
MOP
MRO
MUR
MVR
MWK
MXN
MXV
MYR
MZN
NAD
NGN
NIO
NOK
NPR
NZD
OMR
PAB
PEN
PGK
PHP
PKR
PLN
PYG
QAR
RON
RSD
RUB
RWF
SAR
SBD
SCR
SDG
SEK
SGD
SHP
SLL
SOS
SRD
SSP
STD
SVC
SYP
SZL
THB
TJS
TMT
TND
TOP
TRY
TTD
TWD
TZS
UAH
UGX
USD
USN
USS
UYI
UYU
UZS
VEF
VND
VUV
WST
XAF
XAG
XAU
XBA
XBB
XBC
XBD
XCD
XDR
XOF
XPD
XPF
XPT
XTS
XXX
YER
ZAR
ZMK
ZMW
BTC

ErrorCategory

Indicates which high-level category of error has occurred during a request to the Connect API.

Fields

Name Description
API_ERROR

An error occurred with the Connect API itself.

AUTHENTICATION_ERROR

An authentication error occurred. Most commonly, the request had a missing, malformed, or otherwise invalid Authorization header.

INVALID_REQUEST_ERROR

The request was invalid. Most commonly, a required parameter was missing, or a provided parameter had an invalid value.

RATE_LIMIT_ERROR

Your application reached the Connect API rate limit. Retry your request after a while.

PAYMENT_METHOD_ERROR

An error occurred while processing a payment method. Most commonly, the details of the payment method were invalid (such as a card's CVV or expiration date).

REFUND_ERROR

An error occurred while attempting to process a refund.

ErrorCode

Indicates specific errors that can occur during a request to the Connect API.

Fields

Name Description
INTERNAL_SERVER_ERROR
UNAUTHORIZED
ACCESS_TOKEN_EXPIRED
ACCESS_TOKEN_REVOKED
FORBIDDEN
INSUFFICIENT_SCOPES
APPLICATION_DISABLED
V1_APPLICATION
V1_ACCESS_TOKEN
CARD_PROCESSING_NOT_ENABLED
BAD_REQUEST
MISSING_REQUIRED_PARAMETER
INCORRECT_TYPE
INVALID_TIME
INVALID_TIME_RANGE
INVALID_VALUE
INVALID_CURSOR
UNKNOWN_QUERY_PARAMETER
CONFLICTING_PARAMETERS
EXPECTED_JSON_BODY
INVALID_SORT_ORDER
VALUE_REGEX_MISMATCH
VALUE_TOO_SHORT
VALUE_TOO_LONG
VALUE_TOO_LOW
VALUE_TOO_HIGH
VALUE_EMPTY
ARRAY_EMPTY
EXPECTED_BOOLEAN
EXPECTED_INTEGER
EXPECTED_FLOAT
EXPECTED_STRING
EXPECTED_OBJECT
EXPECTED_ARRAY
EXPECTED_BASE64_ENCODED_BYTE_ARRAY
INVALID_ARRAY_VALUE
INVALID_ENUM_VALUE
INVALID_CONTENT_TYPE
INVALID_FORM_VALUE
ONE_INSTRUMENT_EXPECTED
NO_FIELDS_SET
CARD_EXPIRED
INVALID_EXPIRATION
INVALID_EXPIRATION_YEAR
INVALID_EXPIRATION_DATE
UNSUPPORTED_CARD_BRAND
INVALID_CARD
DELAYED_TRANSACTION_EXPIRED
DELAYED_TRANSACTION_CANCELED
DELAYED_TRANSACTION_CAPTURED
DELAYED_TRANSACTION_FAILED
CARD_TOKEN_EXPIRED
CARD_TOKEN_USED
AMOUNT_TOO_HIGH
UNSUPPORTED_INSTRUMENT_TYPE
REFUND_AMOUNT_INVALID
REFUND_ALREADY_PENDING
PAYMENT_NOT_REFUNDABLE
INVALID_CARD_DATA
IDEMPOTENCY_KEY_REUSED
UNEXPECTED_VALUE
CARD_DECLINED
VERIFY_CVV_FAILURE
VERIFY_AVS_FAILURE
CARD_DECLINED_CALL_ISSUER
NOT_FOUND
REQUEST_TIMEOUT
CONFLICT
REQUEST_ENTITY_TOO_LARGE
UNSUPPORTED_MEDIA_TYPE
RATE_LIMITED
NOT_IMPLEMENTED
SERVICE_UNAVAILABLE

LocationCapability

Indicates account capabilities that a business's location might or might not have enabled.

Fields

Name Description
CREDIT_CARD_PROCESSING

The location can process credit cards with Square.

If this value is not present in a Location's' capabilities array, the location cannot process credit cards.

RefundStatus

Indicates a refund's current status.

Fields

Name Description
PENDING

The refund is pending.

APPROVED

The refund has been approved by Square.

REJECTED

The refund has been rejected by Square.

FAILED

The refund failed.

SortOrder

The order (e.g., chronological or alphabetical) in which results from a request are returned.

Fields

Name Description
DESC

The results are returned in descending (e.g., newest-first or Z-A) order.

ASC

The results are returned in ascending (e.g., oldest-first or A-Z) order.

TenderCardDetailsEntryMethod

Indicates the method used to enter the card's details.

Fields

Name Description
SWIPED

The card was swiped through a Square reader or Square stand.

KEYED

The card information was keyed manually into Square Register or a Square-hosted web form.

EMV

The card was processed via EMV with a Square reader.

ON_FILE

The buyer's card details were already on file with Square.

CONTACTLESS

The card was processed via a contactless (i.e., NFC) transaction with a Square reader.

TenderCardDetailsStatus

Indicates the card transaction's current status.

Fields

Name Description
AUTHORIZED

The card transaction has been authorized but not yet captured.

CAPTURED

The card transaction was authorized and subsequently captured (i.e., completed).

VOIDED

The card transaction was authorized and subsequently voided (i.e., canceled).

FAILED

The card transaction failed.

TenderType

Indicates a tender's type.

Fields

Name Description
CARD

A credit card.

CASH

Cash.

THIRD_PARTY_CARD

A credit card processed with a card processor other than Square.

This value applies only to merchants in countries where Square does not yet provide card processing.

SQUARE_GIFT_CARD

A Square gift card.

NO_SALE

This tender represents the register being opened for a "no sale" event.

OTHER

A form of tender that does not match any other value.

TransactionProduct

Indicates the Square product used to process a transaction.

Fields

Name Description
REGISTER

Square Register.

EXTERNAL_API

The Square Connect API.

BILLING

A Square subscription for one of multiple products.

APPOINTMENTS

Square Appointments.

INVOICES

Square Invoices.

ONLINE_STORE

Square Online Store.

PAYROLL

Square Payroll.

OTHER

A Square product that does not match any other value.

Connect API v2 Changelog

Additions and changes to the API are described here.

Date Description
2016-04-06

Added the buyer_email_address parameter to the Charge endpoint.

2016-03-30

Initial release of Connect API v2.