POST /v2/apple-pay/domains
Activates a domain for use with Web Apple Pay and Square. A validation will be performed on this domain by Apple to ensure is it properly set up as an Apple Pay enabled domain.
This endpoint provides an easy way for platform developers to bulk activate Web Apple Pay with Square for merchants using their platform.
To learn more about Apple Pay on Web see the Apple Pay section in the Embedding the Square Payment Form guide.
Name | Type | Description |
---|---|---|
domain_name
(required) |
string
|
A domain name as described in RFC-1034 that will be registered with ApplePay |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
status
|
string
|
Status of the domain registration. See RegisterDomainResponseStatus for possible values. |
Example HTTP Request
POST /v2/apple-pay/domains
{ "domain_name": "example.com" }
Example Request in Python
api = squareconnect.apis.apple_pay_api.ApplePayApi()
response = api.register_domain(RegisterDomainRequest(domain_name='example.com'))
Example Request in C#
ApplePayApi api = new ApplePayApi();
RegisterDomainResponse response = api.RegisterDomain(new RegisterDomainRequest(
DomainName: "example.com"
));
Example Request in PHP
$api = new \SquareConnect\Api\ApplePayApi();
$apiResponse = $api->registerDomain(new \SquareConnect\Model\RegisterDomainRequest([
"domain_name" => "example.com"
]);
Example Request in Node.js
const api = new SquareConnect.ApplePayApi();
api.registerDomain({domain_name: 'example.com'})
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::ApplePayApi.new(client)
response = api.register_domain(domain_name: 'example.com')
Example Request in Java
ApplePayApi api = new ApplePayApi();
RegisterDomainResponse response = api.registerDomain(new RegisterDomainRequest()
.domainName("example.com"));
Example Response
{
"status": "VERIFIED"
}
POST /v2/catalog/batch-delete
Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its CatalogItemVariation children.
BatchDeleteCatalogObjects
succeeds even if only a portion of the targeted IDs can be deleted. The response will only
include IDs that were actually deleted.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
object_ids
|
string[]
|
The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariations). |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
deleted_object_ids
|
string[]
|
The IDs of all CatalogObjects deleted by this request. |
deleted_at
|
string
|
The database timestamp of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". |
Example HTTP Request
POST /v2/catalog/batch-delete
{ "object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" ] }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Create a list of object IDs to delete
body = BatchDeleteCatalogObjectsRequest([
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]
)
# Delete the objects
response = api.batch_delete_catalog_objects(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Create a list of object IDs to delete
var body = new BatchDeleteCatalogObjectsRequest(
ObjectIds: new List() { "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" }
);
// Delete the objects
var response = api.BatchDeleteCatalogObjects(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Create a list of object IDs to delete
$objectList = [
"object_ids" => [
"W62UWFY35CWMYGVWK6TWJDNI",
"AA27W3M2GGTF3H6AVPNB77CK"
]
];
// Delete the objects
$apiResponse = $api->BatchDeleteCatalogObjects($objectList);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Create a list of object IDs to delete
const body = {
object_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]
};
// Delete the objects
api.batchDeleteCatalogObjects(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Create a list of object IDs to delete
body = SquareConnect::BatchDeleteCatalogObjectsRequest.new(
object_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]
)
# Delete the objects
response = api.batch_delete_catalog_objects(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Create a list of object IDs to delete
BatchDeleteCatalogObjectsRequest body = new BatchDeleteCatalogObjectsRequest()
.objectIds(asList("W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"));
// Delete the objects
BatchDeleteCatalogObjectsResponse response = api.batchDeleteCatalogObjects(body);
Example Response
{
"deleted_object_ids": [
"W62UWFY35CWMYGVWK6TWJDNI",
"AA27W3M2GGTF3H6AVPNB77CK"
],
"deleted_at": "2016-11-16T22:25:24.878Z"
}
POST /v2/catalog/batch-retrieve
Returns a set of objects based on the provided ID. Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.
Required permissions:
ITEMS_READ
Name | Type | Description |
---|---|---|
object_ids
(required) |
string[]
|
The IDs of the CatalogObjects to be retrieved. |
include_related_objects
|
boolean
|
If If the |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
objects
|
CatalogObject[]
|
A list of CatalogObjects returned. |
related_objects
|
CatalogObject[]
|
A list of CatalogObjects referenced by the object in the |
Example HTTP Request
POST /v2/catalog/batch-retrieve
{ "object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK" ], "include_related_objects": true }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Create a list of object IDs to retrieve objects for
body = BatchRetrieveCatalogObjectsRequest(
object_ids=[
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
], include_related_objects=True
)
# Retrieve the objects
response = api.batch_retrieve_catalog_objects(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Create a list of object IDs to retrieve objects for
var body = new BatchRetrieveCatalogObjectsRequest(
ObjectIds: new List() {"W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"},
IncludeRelatedObjects: true
);
// Retrieve the objects
var response = api.BatchRetrieveCatalogObjects(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Create a list of IDs to retrieve obejcts for
$objectList = [
"object_ids" => [
"W62UWFY35CWMYGVWK6TWJDNI",
"AA27W3M2GGTF3H6AVPNB77CK"
],
"include_related_objects" => true
];
// Retrieve the objects
$apiResponse = $api->BatchRetrieveCatalogObjects($objectList);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Create a list of object IDs to retrieve objects for
const body = {
object_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
],
include_related_objects: true
};
// Retrieve the objects
api.batchRetrieveCatalogObjects(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Create a list of object IDs to retrieve objects for
body = SquareConnect::BatchRetrieveCatalogObjectsRequest.new(
object_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
],
include_related_objects: true
)
# Retrieve the objects
response = api.batch_retrieve_catalog_objects(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Create a list of object IDs to retrieve objects for
BatchRetrieveCatalogObjectsRequest body = new BatchRetrieveCatalogObjectsRequest()
.objectIds(asList("W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"))
.includeRelatedObjects(true);
// Retrieve the objects
BatchRetrieveCatalogObjectsResponse response = api.batchRetrieveCatalogObjects(body);
Example Response
{
"objects": [
{
"type": "ITEM",
"id": "W62UWFY35CWMYGVWK6TWJDNI",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea",
"description": "Hot Leaf Juice",
"category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
"tax_ids": [
"HURXQOOAIC4IZSI2BEXQRYFY"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "2TZFAOHWGG7PAK2QEXWYPZSP",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "W62UWFY35CWMYGVWK6TWJDNI",
"name": "Mug",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 150,
"currency": "USD"
}
}
}
]
}
},
{
"type": "ITEM",
"id": "AA27W3M2GGTF3H6AVPNB77CK",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Hot Bean Juice",
"category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
"tax_ids": [
"HURXQOOAIC4IZSI2BEXQRYFY"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "LBTYIHNHU52WOIHWT7SNRIYH",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "AA27W3M2GGTF3H6AVPNB77CK",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "PKYIC7HGGKW5CYVSCVDEIMHY",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "AA27W3M2GGTF3H6AVPNB77CK",
"name": "Large",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
]
}
}
],
"related_objects": [
{
"type": "CATEGORY",
"id": "BJNQCF2FJ6S6UIDT65ABHLRX",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "HURXQOOAIC4IZSI2BEXQRYFY",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"enabled": true
}
}
]
}
POST /v2/catalog/batch-upsert
Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
idempotency_key
(required) |
string
|
A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See Idempotency keys for more information. |
batches
|
CatalogObjectBatch[]
|
A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request. For each object, its To modify an existing object, supply its ID. To create a new object, use an ID starting with Any Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
objects
|
CatalogObject[]
|
The created CatalogObjects |
updated_at
|
string
|
The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". |
id_mappings
|
CatalogIdMapping[]
|
The mapping between client and server IDs for this Upsert. |
Example HTTP Request
POST /v2/catalog/batch-upsert
{ "idempotency_key": "789ff020-f723-43a9-b4b5-43b5dc1fa3dc", "batches": [ { "objects": [ { "type": "ITEM", "id": "#Tea", "present_at_all_locations": true, "item_data": { "name": "Tea", "description": "Hot Leaf Juice", "category_id": "#Beverages", "tax_ids": [ "#SalesTax" ], "variations": [ { "type": "ITEM_VARIATION", "id": "#Tea_Mug", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Tea", "name": "Mug", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 150, "currency": "USD" } } } ] } }, { "type": "ITEM", "id": "#Coffee", "present_at_all_locations": true, "item_data": { "name": "Coffee", "description": "Hot Bean Juice", "category_id": "#Beverages", "tax_ids": [ "#SalesTax" ], "variations": [ { "type": "ITEM_VARIATION", "id": "#Coffee_Regular", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Coffee", "name": "Regular", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 250, "currency": "USD" } } }, { "type": "ITEM_VARIATION", "id": "#Coffee_Large", "present_at_all_locations": true, "item_variation_data": { "item_id": "#Coffee", "name": "Large", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 350, "currency": "USD" } } } ] } }, { "type": "CATEGORY", "id": "#Beverages", "present_at_all_locations": true, "category_data": { "name": "Beverages" } }, { "type": "TAX", "id": "#SalesTax", "present_at_all_locations": true, "tax_data": { "name": "Sales Tax", "calculation_phase": "TAX_SUBTOTAL_PHASE", "inclusion_type": "ADDITIVE", "percentage": "5.0", "applies_to_custom_amounts": true, "enabled": true } } ] } ] }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Define some objects to upsert
item_tea = CatalogObject(
type='ITEM',
id='#Tea',
present_at_all_locations=True,
item_data=CatalogItem(
name='Tea',
description='Hot Leaf Juice',
category_id='#Beverages',
tax_ids=['#SalesTax'],
variations=[CatalogObject(
type='ITEM_VARIATION',
id='#Tea_Mug',
present_at_all_locations=True,
item_variation_data=CatalogItemVariation(
item_id='#Tea',
name='Mug',
pricing_type='FIXED_PRICING',
price_money=Money(150, 'USD')
)
)]
)
)
item_coffee = CatalogObject(
type='ITEM',
id='#Coffee',
present_at_all_locations=True,
item_data=CatalogItem(
name='Coffee',
description='Hot Bean Juice',
category_id='#Beverages',
tax_ids=['#SalesTax'],
variations=[CatalogObject(
type='ITEM_VARIATION',
id='#Coffee_Regular',
present_at_all_locations=True,
item_variation_data=CatalogItemVariation(
item_id='#Coffee',
name='Regular',
pricing_type='FIXED_PRICING',
price_money=Money(250, 'USD')
)
), CatalogObject(
type='ITEM_VARIATION',
id='#Coffee_Large',
present_at_all_locations=True,
item_variation_data=CatalogItemVariation(
item_id='#Coffee',
name='Large',
pricing_type='FIXED_PRICING',
price_money=Money(350, 'USD')
)
)]
)
)
category_beverages = CatalogObject(
type='CATEGORY',
id='#Beverages',
present_at_all_locations=True,
category_data=CatalogCategory(
name='Beverages'
)
)
tax_sales_tax = CatalogObject(
type='TAX',
id='#SalesTax',
present_at_all_locations=True,
tax_data=CatalogTax(
name='Sales Tax',
calculation_phase='TAX_SUBTOTAL_PHASE',
inclusion_type='ADDITIVE',
percentage='5.0',
applies_to_custom_amounts=True,
enabled=True)
)
# Create a batch of objects to upsert
# Set a unique idempotency key for each request
body = BatchUpsertCatalogObjectsRequest(
idempotency_key='789ff020-f723-43a9-b4b5-43b5dc1fa3dc',
batches=[CatalogObjectBatch([item_tea, item_coffee, category_beverages, tax_sales_tax])]
)
# Batch upsert the objects
response = api.batch_upsert_catalog_objects(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Define some objects to upsert
CatalogObject itemTea = new CatalogObject(
Type: TypeEnum.ITEM,
Id: "#Tea",
PresentAtAllLocations: true,
ItemData: new CatalogItem(
Name: "Tea",
Description: "Hot Leaf Juice",
CategoryId: "#Beverages",
TaxIds: new List() {"#SalesTax"},
Variations: List {
new CatalogObject(
Type: TypeEnum.ITEMVARIATION,
Id: "#Tea_Mug",
PresentAtAllLocations: true,
ItemVariationData: new CatalogItemVariation(
ItemId: "#Tea",
Name: "Mug"
PricingType: CatalogItemVariation.PricingTypeEnum.FIXEDPRICING,
PriceMoney: new Money(
Amount: 150L, Currency: Money.CurrencyEnum.USD
)
)
)
}
)
);
CatalogObject itemCoffee = new CatalogObject(
Type: TypeEnum.ITEM,
Id: "#Coffee",
PresentAtAllLocations: true,
ItemData: new CatalogItem(
Name: "Coffee",
Description: "Hot Bean Juice",
CategoryId: "#Beverages",
TaxIds: new List() {"#SalesTax"},
Variations: List {
new CatalogObject(
Type: TypeEnum.ITEMVARIATION,
Id: "#Coffee_Regular",
PresentAtAllLocations: true,
ItemVariationData: new CatalogItemVariation(
ItemId: "#Coffee",
Name: "Regular",
PricingType: CatalogItemVariation.PricingTypeEnum.FIXEDPRICING,
PriceMoney: new Money(
Amount: 250L, Currency: Money.CurrencyEnum.USD
)
)
),
new CatalogObject(
Type: TypeEnum.ITEMVARIATION,
Id: "#Coffee_Large",
PresentAtAllLocations: true,
ItemVariationData: new CatalogItemVariation(
ItemId: "#Coffee",
Name: "Large",
PricingType: CatalogItemVariation.PricingTypeEnum.FIXEDPRICING,
PriceMoney: new Money(
Amount: 350L, Currency: Money.CurrencyEnum.USD
)
)
)
}
)
);
CatalogObject categoryBeverages = new CatalogObject(
Type: TypeEnum.CATEGORY,
Id: "#Beverages",
PresentAtAllLocations: true,
CategoryData: new CatalogCategory(
Name: "Beverages"
)
);
CatalogObject taxSalesTax = new CatalogObject(
Type: TypeEnum.TAX,
Id: "#SalesTax",
PresentAtAllLocations: true,
TaxData: new CatalogTax(
Name: "Sales Tax"
CalculationPhase: CatalogTax.CalculationPhaseEnum.SUBTOTALPHASE,
InclusionType: CatalogTax.InclusionTypeEnum.ADDITIVE,
Percentage: "5.0",
AppliesToCustomAmounts: true,
Enabled: true
)
);
// Create a batch of objects to upsert
// Set a unique idempotency key for each request
BatchUpsertCatalogObjectsRequest body = new BatchUpsertCatalogObjectsRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
Batches(new List() {
new CatalogObjectBatch(
Objects: List {itemTea, itemCoffee, categoryBeverages, taxSalesTax}
)
})
);
// Batch upsert the objects
BatchUpsertCatalogObjectsResponse response = api.BatchUpsertCatalogObjects(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Define some objects to upsert
$item_tea = [
"type" => "ITEM",
"id" => "#Tea",
"present_at_all_locations" => true,
"item_data" => [
"name" => "Tea",
"description" => "Hot Leaf Juice",
"category_id" => "#Beverages",
"tax_ids" => ["#SalesTax"],
"variations" => [
[
"type" => "ITEM_VARIATION",
"id" => "#Tea_Mug",
"present_at_all_locations" => true,
"item_variation_data" => [
"item_id" => "#Tea",
"name" => "Mug",
"pricing_type" => "FIXED_PRICING",
"price_money" => [
"amount" => 150,
"currency" => "USD"
]
]
]
]
]
];
$item_coffee = [
"type" => "ITEM",
"id" => "#Coffee",
"present_at_all_locations" => true,
"item_data" => [
"name" => "Coffee",
"description" => "Hot Bean Juice",
"category_id" => "#Beverages",
"tax_ids" => ["#SalesTax"],
"variations" => [
[
"type" => "ITEM_VARIATION",
"id" => "#Coffee_Regular",
"present_at_all_locations" => true,
"item_variation_data" => [
"item_id" => "#Coffee",
"name" => "Regular",
"pricing_type" => "FIXED_PRICING",
"price_money" => [
"amount" => 250,
"currency" => "USD"
]
]
],
[
"type" => "ITEM_VARIATION",
"id" => "#Coffee_Large",
"present_at_all_locations" => true,
"item_variation_data" => [
"item_id" => "#Coffee",
"name" => "Large",
"pricing_type" => "FIXED_PRICING",
"price_money" => [
"amount" => 350,
"currency" => "USD"
]
]
]
]
]
];
$category_beverages = [
"type" => "CATEGORY",
"id" => "#Beverages",
"present_at_all_locations" => true,
"category_data" => [
"name" => "Beverages"
]
];
$tax_sales_tax = [
"type" => "TAX",
"id" => "#SalesTax",
"present_at_all_locations" => true,
"tax_data" => [
"name" => "Sales Tax",
"calculation_phase" => "TAX_SUBTOTAL_PHASE",
"inclusion_type" => "ADDITIVE",
"percentage" => "5.0",
"applies_to_custom_amounts" => true,
"enabled" => true
]
];
// Create a batch of the objects to upsert
// Set a unique idempotency key for each request
$myCatalogObjectBatch = [
"idempotency_key" => "789ff020-f723-43a9-b4b5-43b5dc1fa3dc",
"batches" => [
[
"objects" => [
$item_tea,
$item_coffee,
$category_beverages,
$tax_sales_tax
]
]
]
];
// Batch upsert the objects
$apiResponse = $api->BatchUpsertCatalogObjects($myCatalogObjectBatch);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Define some objects to upsert
const item_tea = {
type: 'ITEM',
id: '#Tea',
present_at_all_locations: true,
item_data: {
name: 'Tea',
description: 'Hot Leaf Juice',
category_id: '#Beverages',
tax_ids: ['#SalesTax'],
variations: [
{
type: 'ITEM_VARIATION',
id: '#Tea_Mug',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Tea',
name: 'Mug',
pricing_type: 'FIXED_PRICING',
price_money: {
amount: 150,
currency: 'USD'
}
}
}
]
}
};
const item_coffee = {
type: 'ITEM',
id: '#Coffee',
present_at_all_locations: true,
item_data: {
name: 'Coffee',
description: 'Hot Bean Juice',
category_id: '#Beverages',
tax_ids: ['#SalesTax'],
variations: [
{
type: 'ITEM_VARIATION',
id: '#Coffee_Regular',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Coffee',
name: 'Regular',
pricing_type: 'FIXED_PRICING',
price_money: {
amount: 250,
currency: 'USD'
}
}
},
{
type: 'ITEM_VARIATION',
id: '#Coffee_Large',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Coffee',
name: 'Large',
pricing_type: 'FIXED_PRICING',
price_money: {
amount: 350,
currency: 'USD'
}
}
}
]
}
};
const category_beverages = {
type: 'CATEGORY',
id: '#Beverages',
present_at_all_locations: true,
category_data: {
name: 'Beverages'
}
};
const tax_sales_tax = {
type: 'TAX',
id: '#SalesTax',
present_at_all_locations: true,
tax_data: {
name: 'Sales Tax',
calculation_phase: 'SUBTOTAL_PHASE',
inclusion_type: 'ADDITIVE',
percentage: '5.0',
applies_to_custom_amounts: true,
enabled: true
}
};
// Set a batch of objects to upsert
// Set a unique idempotency key for each request
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotencyKey,
batches: [{
objects: [item_tea, item_coffee, category_beverages, tax_sales_tax]
}]
};
// Batch upsert the objects
api.batchUpsertCatalogObjects(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Define some objects to upsert
item_tea = {
type: SquareConnect::CatalogObjectType::ITEM,
id: '#Tea',
present_at_all_locations: true,
item_data: {
name: 'Tea',
description: 'Hot Leaf Juice',
category_id: '#Beverages',
tax_ids: ['#SalesTax'],
variations: [
{
type: SquareConnect::CatalogObjectType::ITEM_VARIATION,
id: '#Tea_Mug',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Tea',
name: 'Mug',
pricing_type: SquareConnect::CatalogPricingType::FIXED_PRICING,
price_money: {
amount: 150,
currency: SquareConnect::Currency::USD
}
}
}
]
}
}
item_coffee = {
type: SquareConnect::CatalogObjectType::ITEM,
id: '#Coffee',
present_at_all_locations: true,
item_data: {
name: 'Coffee',
description: 'Hot Bean Juice',
category_id: '#Beverages',
tax_ids: ['#SalesTax'],
variations: [
{
type: SquareConnect::CatalogObjectType::ITEM_VARIATION,
id: '#Coffee_Regular',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Coffee',
name: 'Regular',
pricing_type: SquareConnect::CatalogPricingType::FIXED_PRICING,
price_money: {
amount: 250,
currency: SquareConnect::Currency::USD
}
}
},
{
type: SquareConnect::CatalogObjectType::ITEM_VARIATION,
id: '#Coffee_Large',
present_at_all_locations: true,
item_variation_data: {
item_id: '#Coffee',
name: 'Large',
pricing_type: SquareConnect::CatalogPricingType::FIXED_PRICING,
price_money: {
amount: 350,
currency: SquareConnect::Currency::USD
}
}
}
]
}
}
category_beverages = {
type: SquareConnect::CatalogObjectType::CATEGORY,
id: '#Beverages',
present_at_all_locations: true,
category_data: {
name: 'Beverages'
}
}
tax_sales_tax = {
type: SquareConnect::CatalogObjectType::TAX,
id: '#SalesTax',
present_at_all_locations: true,
tax_data: {
name: 'Sales Tax',
calculation_phase: SquareConnect::TaxCalculationPhase::SUBTOTAL_PHASE,
inclusion_type: SquareConnect::TaxInclusionType::ADDITIVE,
percentage: '5.0',
applies_to_custom_amounts: true,
enabled: true
}
}
# Create a batch of objects to upsert
# Set a unique idempotency key for each request
body = SquareConnect::BatchUpsertCatalogObjectsRequest.new
body.idempotency_key = '789ff020-f723-43a9-b4b5-43b5dc1fa3dc'
body.batches = [{
objects: [item_tea, item_coffee, category_beverages, tax_sales_tax]
}]
# Batch upsert the objects
response = api.batch_upsert_catalog_objects(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Define some objects to upsert
CatalogObject itemTea = new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM)
.id("#Tea")
.presentAtAllLocations(true)
.itemData(new CatalogItem()
.name("Tea")
.description("Hot Leaf Juice")
.categoryId("#Beverages")
.addTaxIdsItem("#SalesTax")
.addVariationsItem(new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM_VARIATION)
.id("#Tea_Mug")
.presentAtAllLocations(true)
.itemVariationData(new CatalogItemVariation()
.itemId("#Tea")
.name("Mug")
.pricingType(CatalogItemVariation.PricingTypeEnum.FIXED_PRICING)
.priceMoney(new Money()
.amount(150L)
.currency(Money.CurrencyEnum.USD)
)
)
)
);
CatalogObject itemCoffee = new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM)
.id("#Coffee")
.presentAtAllLocations(true)
.itemData(new CatalogItem()
.name("Coffee")
.description("Hot Bean Juice")
.categoryId("#Beverages")
.addTaxIdsItem("#SalesTax")
.addVariationsItem(new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM_VARIATION)
.id("#Coffee_Regular")
.presentAtAllLocations(true)
.itemVariationData(new CatalogItemVariation()
.itemId("#Coffee")
.name("Regular")
.pricingType(CatalogItemVariation.PricingTypeEnum.FIXED_PRICING)
.priceMoney(new Money()
.amount(250L)
.currency(Money.CurrencyEnum.USD)
)
)
)
.addVariationsItem(new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM_VARIATION)
.id("#Coffee_Large")
.presentAtAllLocations(true)
.itemVariationData(new CatalogItemVariation()
.itemId("#Coffee")
.name("Large")
.pricingType(CatalogItemVariation.PricingTypeEnum.FIXED_PRICING)
.priceMoney(new Money()
.amount(350L)
.currency(Money.CurrencyEnum.USD)
)
)
)
);
CatalogObject categoryBeverages = new CatalogObject()
.type(CatalogObject.TypeEnum.CATEGORY)
.id("#Beverages")
.presentAtAllLocations(true)
.categoryData(new CatalogCategory()
.name("Beverages")
);
CatalogObject taxSalesTax = new CatalogObject()
.type(CatalogObject.TypeEnum.TAX)
.id("#SalesTax")
.presentAtAllLocations(true)
.taxData(new CatalogTax()
.name("Sales Tax")
.calculationPhase(CatalogTax.CalculationPhaseEnum.SUBTOTAL_PHASE)
.inclusionType(CatalogTax.InclusionTypeEnum.ADDITIVE)
.percentage("5.0")
.appliesToCustomAmounts(true)
.enabled(true)
);
// Create a batch of objects to upsert
// Set a unique idempotency key for each request
BatchUpsertCatalogObjectsRequest body = new BatchUpsertCatalogObjectsRequest()
.idempotencyKey(UUID.randomUUID().toString())
.addBatchesItem(new CatalogObjectBatch()
.objects(Arrays.asList(itemTea, itemCoffee, categoryBeverages, taxSalesTax)));
// Batch upsert the objects
BatchUpsertCatalogObjectsResponse response = api.batchUpsertCatalogObjects(body);
Example Response
{
"objects": [
{
"type": "ITEM",
"id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea",
"description": "Hot Leaf Juice",
"category_id": "LYT72K3WGJFFCIMB63XARP3I",
"tax_ids": [
"XHSHLHNWSI3HVI4BW5ZUZXI3"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "NAYHET5R52MIYCEF34ZMAHFM",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "ZSDZN34NAXDLC6D5ZQMNSOUM",
"name": "Mug",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 150,
"currency": "USD"
}
}
}
]
}
},
{
"type": "ITEM",
"id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Coffee",
"description": "Hot Bean Juice",
"category_id": "LYT72K3WGJFFCIMB63XARP3I",
"tax_ids": [
"XHSHLHNWSI3HVI4BW5ZUZXI3"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "OTYDX45SPG7LJQUVCBZI4INH",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"name": "Regular",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
},
{
"type": "ITEM_VARIATION",
"id": "GZDA3JB37FYVOPI4AOEBOITI",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "PJMCEBHHUS3OKDB6PYUHLCPP",
"name": "Large",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 350,
"currency": "USD"
}
}
}
]
}
},
{
"type": "CATEGORY",
"id": "LYT72K3WGJFFCIMB63XARP3I",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "XHSHLHNWSI3HVI4BW5ZUZXI3",
"updated_at": "2017-05-10T18:48:39.798Z",
"version": 1494442119798,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"applies_to_custom_amounts": true,
"enabled": true
}
}
],
"id_mappings": [
{
"client_object_id": "#Tea",
"object_id": "ZSDZN34NAXDLC6D5ZQMNSOUM"
},
{
"client_object_id": "#Coffee",
"object_id": "PJMCEBHHUS3OKDB6PYUHLCPP"
},
{
"client_object_id": "#Beverages",
"object_id": "LYT72K3WGJFFCIMB63XARP3I"
},
{
"client_object_id": "#SalesTax",
"object_id": "XHSHLHNWSI3HVI4BW5ZUZXI3"
},
{
"client_object_id": "#Tea_Mug",
"object_id": "NAYHET5R52MIYCEF34ZMAHFM"
},
{
"client_object_id": "#Coffee_Regular",
"object_id": "OTYDX45SPG7LJQUVCBZI4INH"
},
{
"client_object_id": "#Coffee_Large",
"object_id": "GZDA3JB37FYVOPI4AOEBOITI"
}
]
}
GET /v2/catalog/info
Returns information about the Square Catalog API, such as batch size limits for BatchUpsertCatalogObjects
.
Required permissions:
ITEMS_READ
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
limits
|
CatalogInfoResponseLimits
|
Example HTTP Request
GET /v2/catalog/info
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Retrieve the request limit information for the Catalog API.
response = api.catalog_info()
Example Request in C#
CatalogApi api = new CatalogApi();
// Retrieve the request limit information for the Catalog API.
CatalogInfoResponse response = api.CatalogInfo();
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Retrieve the request limit information for the Catalog API.
$apiResponse = $api->catalogInfo();
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Retrieve the request limit information for the Catalog API.
api.catalogInfo()
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Retrieve the request limit information for the Catalog API.
response = api.catalog_info
Example Request in Java
CatalogApi api = new CatalogApi();
// Retrieve the request limit information for the Catalog API.
CatalogInfoResponse response = api.catalogInfo();
Example Response
{
"limits": {
"batch_upsert_max_objects_per_batch": 1000,
"batch_upsert_max_total_objects": 10000,
"batch_retrieve_max_object_ids": 1000,
"search_max_page_limit": 1000,
"batch_delete_max_object_ids": 200,
"update_item_taxes_max_item_ids": 1000,
"update_item_taxes_max_taxes_to_enable": 1000,
"update_item_taxes_max_taxes_to_disable": 1000,
"update_item_modifier_lists_max_item_ids": 1000,
"update_item_modifier_lists_max_modifier_lists_to_enable": 1000,
"update_item_modifier_lists_max_modifier_lists_to_disable": 1000
}
}
DELETE /v2/catalog/object/{object_id}
Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its CatalogItemVariation children.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
object_id
(required) |
string
|
The ID of the CatalogObject to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariations). |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
deleted_object_ids
|
string[]
|
The IDs of all CatalogObjects deleted by this request. Multiple IDs may be returned when associated objects are also deleted, for example a CatalogItemVariation will be deleted (and its ID included in this field) when its parent CatalogItem is deleted. |
deleted_at
|
string
|
The database timestamp of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". |
Example HTTP Request
DELETE /v2/catalog/object/{object_id}
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Delete the catalog entry with ID '7SB3ZQYJ5GDMVFL7JK46JCHT'
response = api.delete_catalog_object('7SB3ZQYJ5GDMVFL7JK46JCHT')
Example Request in C#
CatalogApi api = new CatalogApi();
// Delete the catalog entry with ID '7SB3ZQYJ5GDMVFL7JK46JCHT'
DeleteCatalogObjectResponse response = api.DeleteCatalogObject("7SB3ZQYJ5GDMVFL7JK46JCHT");
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Delete the catalog entry with ID "7SB3ZQYJ5GDMVFL7JK46JCHT"
$apiResponse = $api->DeleteCatalogObject("7SB3ZQYJ5GDMVFL7JK46JCHT");
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Delete the catalog entry with ID '7SB3ZQYJ5GDMVFL7JK46JCHT'
api.deleteCatalogObject('7SB3ZQYJ5GDMVFL7JK46JCHT')
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Delete the catalog entry with ID '7SB3ZQYJ5GDMVFL7JK46JCHT'
response = api.delete_catalog_object('7SB3ZQYJ5GDMVFL7JK46JCHT')
Example Request in Java
CatalogApi api = new CatalogApi();
// Delete the catalog entry with ID '7SB3ZQYJ5GDMVFL7JK46JCHT'
DeleteCatalogObjectResponse response = api.deleteCatalogObject("7SB3ZQYJ5GDMVFL7JK46JCHT");
Example Response
{
"deleted_object_ids": [
"7SB3ZQYJ5GDMVFL7JK46JCHT",
"KQLFFHA6K6J3YQAQAWDQAL57"
],
"deleted_at": "2016-11-16T22:25:24.878Z"
}
GET /v2/catalog/list
Returns a list of CatalogObjects that includes all objects of a set of desired types (for
example, all CatalogItem and CatalogTax objects) in the catalog. The types
parameter is specified as a comma-separated list of valid CatalogObject types: ITEM
,
ITEM_VARIATION
, MODIFIER
, MODIFIER_LIST
, CATEGORY
, DISCOUNT
, TAX
.
Required permissions:
ITEMS_READ
Name | Type | Description |
---|---|---|
cursor
|
string
|
The pagination cursor returned in the previous response. Leave unset for an initial request. See Paginating results for more information. |
types
|
string
|
An optional case-insensitive, comma-separated list of object types to retrieve, for example
The legal values are taken from the CatalogObjectType enumeration, namely |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
objects
|
CatalogObject[]
|
The CatalogObjects returned. |
Example HTTP Request
GET /v2/catalog/list?types=category,tax
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# List all Category and Tax objects in the catalog.
# The results are returned a page at a time.
types = '{},{}'.format('CATEGORY', 'TAX')
# Store all results in an array.
objects = []
cursor = ''
# When response.cursor is nil, the results are complete.
while cursor != None:
response = api.list_catalog(types=types, cursor=cursor)
if response.objects != None:
objects.extend(response.objects)
# Use response.cursor as the cursor for the subsequent request.
cursor = response.cursor
# Do something with the object results.
print(objects)
Example Request in C#
CatalogApi api = new CatalogApi();
// List all Category and Tax objects in the catalog.
// The results are returned a page at a time.
var cursor = "";
var types = TypeEnum.CATEGORY + "," + TypeEnum.TAX;
// Store all results in an list.
var objects = new List();
do {
var response = api.ListCatalog(cursor, types);
objects.Add(response.Objects())
cursor = response.Cursor();
// When response.cursor is nil, the results are complete.
} while(!string.IsNullOrEmpty(cursor));
// Do something with the object results.
objects;
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// List all Category and Tax objects in the catalog.
// The results are returned a page at a time.
$types = join(",", [
"CATEGORY",
"TAX"
]);
$cursor = null;
// Store all results in an array.
$objects = [];
do {
$apiResponse = $api->listCatalog($cursor, $types);
// Use the response cursor as the cursor for the subsequent request.
$cursor = $apiResponse['cursor'];
if ($apiResponse['objects'] != null) {
$objects = array_merge($objects, $apiResponse['objects']);
}
// When the response cursor is null, the results are complete.
} while ($apiResponse['cursor']);
// Do something with the object results
print_r($objects);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// List all Category and Tax objects in the catalog.
// The results are returned a page at a time.
const baseRequest = {
types: 'CATEGORY,TAX'
};
// Store all results in a list.
function listCatalogReq(baseRequest, objects, cursor) {
// Create new request object off baseRequest with cursor as the input cursor
const request = Object.assign({}, baseRequest, {cursor: cursor});
return api.listCatalog()
.then((response) => {
if (response.objects) {
objects = objects.concat(response.objects);
}
// Use the response cursor as the cursor for the subsequent request.
// When the response cursor is null, the results are complete.
if (response.cursor) {
// Get more available results
return listCatalogReq(baseRequest, objects, response.cursor);
}
return objects;
});
}
listCatalogReq(baseRequest, [])
.then((response) => {
// Handle Response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# List all Category and Tax objects in the catalog.
# The results are returned a page at a time.
opts = {
types: [
SquareConnect::CatalogObjectType::CATEGORY,
SquareConnect::CatalogObjectType::TAX
].join(',')
}
# Store all results in an array.
objects = []
loop do
response = api.list_catalog(opts)
objects.concat(response.objects) unless response.objects.nil?
# When response.cursor is nil, the results are complete.
break if response.cursor.nil?
# Use response.cursor as the cursor for the subsequent request.
opts[:cursor] = response.cursor
end
# Do something with the object results.
puts objects
Example Request in Java
CatalogApi api = new CatalogApi();
// List all Category and Tax objects in the catalog.
// The results are returned a page at a time.
String cursor = "";
String types = String.format("%s,%s", CatalogObject.TypeEnum.CATEGORY, CatalogObject.TypeEnum.TAX);
// Store all results in an list.
List objects = new ArrayList<>();
do {
ListCatalogResponse response = api.listCatalog(cursor, types);
if (response.getObjects() != null) {
objects.addAll(response.getObjects());
}
cursor = response.getCursor();
// When response.cursor is nil, the results are complete.
} while(cursor != null);
// Do something with the object results.
System.out.println(Arrays.toString(objects.toArray());
Example Response
{
"objects": [
{
"type": "CATEGORY",
"id": "5ZYQZZ2IECPVJ2IJ5KQPRDC3",
"updated_at": "2017-02-21T14:50:26.495Z",
"version": 1487688626495,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "L5R47DGBZOOVKCAFIXC56AEN",
"updated_at": "2017-02-21T14:50:26.495Z",
"version": 1487688626495,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"enabled": true
}
}
]
}
GET /v2/catalog/object/{object_id}
Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.
Required permissions:
ITEMS_READ
Name | Type | Description |
---|---|---|
object_id
(required) |
string
|
The object ID of any type of CatalogObjects to be retrieved. |
Name | Type | Description |
---|---|---|
include_related_objects
|
boolean
|
If If the Default value: |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
object
|
CatalogObject
|
The CatalogObjects returned. |
related_objects
|
CatalogObject[]
|
A list of CatalogObjects referenced by the object in the |
Example HTTP Request
GET /v2/catalog/object/{object_id}?include_related_objects=true
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Retrieve a single object by its id, along with related objects.
response = api.retrieve_catalog_object(object_id='W62UWFY35CWMYGVWK6TWJDNI', include_related_objects=True)
Example Request in C#
CatalogApi api = new CatalogApi();
// Retrieve a single object by its id, along with related objects.
var response = api.RetrieveCatalogObject("W62UWFY35CWMYGVWK6TWJDNI", true);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Retrieve a single object by its id.
$apiResponse = $api->retrieveCatalogObject("W62UWFY35CWMYGVWK6TWJDNI", true);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Retrieve a single object by its id, along with related objects.
const opts = {
include_related_objects: true
};
api.retrieveCatalogObject('W62UWFY35CWMYGVWK6TWJDNI', opts)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Retrieve a single object by its id, along with related objects.
opts = {
include_related_objects: true
}
response = api.retrieve_catalog_object('W62UWFY35CWMYGVWK6TWJDNI', opts)
Example Request in Java
CatalogApi api = new CatalogApi();
// Retrieve a single object by its id, along with related objects.
RetrieveCatalogObjectResponse response = api.retrieveCatalogObject("W62UWFY35CWMYGVWK6TWJDNI", true);
Example Response
{
"object": {
"type": "ITEM",
"id": "W62UWFY35CWMYGVWK6TWJDNI",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea",
"description": "Hot Leaf Juice",
"category_id": "BJNQCF2FJ6S6UIDT65ABHLRX",
"tax_ids": [
"HURXQOOAIC4IZSI2BEXQRYFY"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "2TZFAOHWGG7PAK2QEXWYPZSP",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "W62UWFY35CWMYGVWK6TWJDNI",
"name": "Mug",
"ordinal": 0,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 150,
"currency": "USD"
}
}
}
]
}
},
"related_objects": [
{
"type": "CATEGORY",
"id": "BJNQCF2FJ6S6UIDT65ABHLRX",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
},
{
"type": "TAX",
"id": "HURXQOOAIC4IZSI2BEXQRYFY",
"updated_at": "2016-11-16T22:25:24.878Z",
"version": 1479335124878,
"is_deleted": false,
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"enabled": true
}
}
]
}
POST /v2/catalog/search
Queries the targeted catalog using a variety of query types: CatalogQuerySortedAttribute, CatalogQueryExact, CatalogQueryRange, CatalogQueryText, CatalogQueryItemsForTax, and CatalogQueryItemsForModifierList.
Required permissions:
ITEMS_READ
Name | Type | Description |
---|---|---|
cursor
|
string
|
The pagination cursor returned in the previous response. Leave unset for an initial request. See Paginating results for more information. |
object_types
|
string[]
|
The desired set of object types to appear in the search results. The legal values are taken from the
CatalogObjectType enumeration, namely |
include_deleted_objects
|
boolean
|
If |
include_related_objects
|
boolean
|
If If a CatalogItem is returned in the object field of the response, its associated
CatalogCategory, CatalogTaxes, and
CatalogModifierLists will be included in the If a CatalogItemVariation is returned in the object field of the response, its parent
CatalogItem will be included in the |
begin_time
|
string
|
Return objects modified after this timestamp, in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".
The timestamp is exclusive - objects with a timestamp equal to |
query
|
CatalogQuery
|
A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned. |
limit
|
integer
|
A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
objects
|
CatalogObject[]
|
The CatalogObjects returned. |
related_objects
|
CatalogObject[]
|
A list of CatalogObjects referenced by the objects in the |
Example HTTP Request
POST /v2/catalog/search
{ "object_types": [ "ITEM" ], "query": { "prefix_query": { "attribute_name": "name", "attribute_prefix": "tea" } }, "limit": 100 }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Search for all Items with name prefix "tea".
body = SearchCatalogObjectsRequest(
object_types=[
"ITEM"
],
query=CatalogQuery(
prefix_query=CatalogQueryPrefix(
attribute_name='name',
attribute_prefix='tea'
)
),
limit=100
)
# Retrieve the first page of the response.
# Additional pages may be retrieved using the response cursor.
response = api.search_catalog_objects(body)
print(response)
Example Request in C#
CatalogApi api = new CatalogApi();
// Search for all Items.
var body = new SearchCatalogObjectsRequest(
ObjectTypes: new List { SearchCatalogObjectsRequest.ObjectTypesEnum.ITEM },
Query: new CatalogQuery(
PrefixQuery: new CatalogQueryPrefix(
AttributeName: "name",
AttributePrefix: "tea")),
Limit: 100);
// Retrieve the first page of the response.
// Additional pages may be retrieved using the response cursor.
var response = api.SearchCatalogObjects(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Search for Items with name prefix "tea".
$query = [
"object_types" => [
"ITEM"
]
"query" => [
"prefix_query" => [
"attribute_name" => "name",
"attribute_prefix" => "tea"
]
],
"limit" => 100
];
// Retrieve the first page of the response.
// Additional pages may be retrieved using the response cursor.
$apiResponse = $api->searchCatalogObjects($query);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Search for all Items.
const body = {object_types: ['ITEM']};
// Retrieve the first page of the response.
// Additional pages may be retrieved using the response cursor.
api.searchCatalogObjects(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Search for Items with name prefix "tea".
body = SquareConnect::SearchCatalogObjectsRequest.new(
object_types: [
SquareConnect::CatalogObjectType::ITEM
],
query: {
prefix_query: {
attribute_name: 'name',
attribute_prefix: 'tea'
}
},
limit: 100
)
# Retrieve the first page of the response.
# Additional pages may be retrieved using the response cursor.
response = api.search_catalog_objects(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Search for Items with name prefix "tea".
SearchCatalogObjectsRequest body = new SearchCatalogObjectsRequest()
.addObjectTypesItem(SearchCatalogObjectsRequest.ObjectTypesEnum.ITEM)
.query(new CatalogQuery().prefixQuery(
new CatalogQueryPrefix().attributeName("name").attributePrefix("tea")))
.limit(100);
// Retrieve the first page of the response.
// Additional pages may be retrieved using the response cursor.
SearchCatalogObjectsResponse response = api.searchCatalogObjects(body);
Example Response
{
"objects": [
{
"type": "ITEM",
"id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"updated_at": "2017-10-26T15:41:32.337Z",
"version": 1509032492337,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea - Black",
"description": "A delicious blend of black tea.",
"category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
"product_type": "REGULAR",
"tax_ids": [
"ZXITPM6RWHZ7GZ7EIP3YKECM"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "5GSZPX6EU7MM75S57OONG3V5",
"updated_at": "2017-10-26T15:27:31.626Z",
"version": 1509031651626,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"name": "Regular",
"ordinal": 1,
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
},
{
"type": "ITEM_VARIATION",
"id": "XVLBN7DU6JTWHJTG5F265B43",
"updated_at": "2017-10-26T15:27:31.626Z",
"version": 1509031651626,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "X5DZ5NWWAQ44CKBLKIFQGOWK",
"name": "Large",
"ordinal": 2,
"price_money": {
"amount": 225,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
}
],
"visibility": "PRIVATE"
}
},
{
"type": "ITEM",
"id": "NNNEM3LA656Q46NXLWCNI7S5",
"updated_at": "2017-10-26T15:41:23.232Z",
"version": 1509032483232,
"is_deleted": false,
"present_at_all_locations": true,
"item_data": {
"name": "Tea - Green",
"description": "Relaxing green herbal tea.",
"category_id": "E7CLE5RZZ744BHWVQQEAHI2C",
"product_type": "REGULAR",
"tax_ids": [
"ZXITPM6RWHZ7GZ7EIP3YKECM"
],
"variations": [
{
"type": "ITEM_VARIATION",
"id": "FHYBVIA6NVBCSOVETA62WEA4",
"updated_at": "2017-10-26T15:29:00.524Z",
"version": 1509031740524,
"is_deleted": false,
"present_at_all_locations": true,
"item_variation_data": {
"item_id": "NNNEM3LA656Q46NXLWCNI7S5",
"name": "Regular",
"ordinal": 1,
"price_money": {
"amount": 150,
"currency": "USD"
},
"pricing_type": "FIXED_PRICING"
}
}
],
"visibility": "PRIVATE"
}
}
]
}
POST /v2/catalog/update-item-modifier-lists
Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
item_ids
(required) |
string[]
|
The CatalogItems whose CatalogModifierLists are being updated. |
modifier_lists_to_enable
|
string[]
|
The set of CatalogModifierLists (referenced by ID) to enable for the CatalogItem. |
modifier_lists_to_disable
|
string[]
|
The set of CatalogModifierLists (referenced by ID) to disable for the CatalogItem. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
updated_at
|
string
|
The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". |
Example HTTP Request
POST /v2/catalog/update-item-modifier-lists
{ "item_ids": [ "H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6" ], "modifier_lists_to_enable": [ "H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6" ], "modifier_lists_to_disable": [ "7WRC16CJZDVLSNDQ35PP6YAD" ] }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Package the modifier information we want to enable/disable for the target IDs
body = UpdateItemModifierListsRequest(
item_ids=['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
modifier_lists_to_enable=['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
modifier_lists_to_disable=['7WRC16CJZDVLSNDQ35PP6YAD']
)
# Make the update
response = api.update_item_modifier_lists(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Package the modifier information we want to enable/disable for the target IDs
var body = new UpdateItemModifierListsRequest(
ItemIds: new List() {"H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"},
ModifierListsToEnable: new List() {"H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6},
ModifierListsToDisable: new List() {"7WRC16CJZDVLSNDQ35PP6YAD"});
// Make the update
var response = api.UpdateItemModifierLists(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Package the modifier information we want to enable/disable for the target IDs
$modifierListUpdates = [
"item_ids" => ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
"modifier_lists_to_enable" => ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
"modifier_lists_to_disable" => ["7WRC16CJZDVLSNDQ35PP6YAD"]
];
// Make the update
$apiResponse = $api->UpdateItemModifierLists($modifierListUpdates);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Package the modifier information we want to enable/disable for the target IDs
const body = {
item_ids: ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
modifier_lists_to_enable: ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
modifier_lists_to_disable: ['7WRC16CJZDVLSNDQ35PP6YAD']
};
// Make the update
api.updateItemModifierLists(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Package the modifier information we want to enable/disable for the target IDs
body = SquareConnect::UpdateItemModifierListsRequest.new
body.item_ids = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6']
body.modifier_lists_to_enable = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6']
body.modifier_lists_to_disable = ['7WRC16CJZDVLSNDQ35PP6YAD']
# Make the update
response = api.update_item_modifier_lists(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Package the modifier information we want to enable/disable for the target IDs
UpdateItemModifierListsRequest body = new UpdateItemModifierListsRequest()
.itemIds(Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"))
.modifierListsToEnable(Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"))
.addModifierListsToDisableItem("7WRC16CJZDVLSNDQ35PP6YAD");
// Make the update
UpdateItemModifierListsResponse response = api.updateItemModifierLists(body);
Example Response
{
"updated_at": "2016-11-16T22:25:24.878Z"
}
POST /v2/catalog/update-item-taxes
Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
item_ids
(required) |
string[]
|
The CatalogItems whose enabled/disabled CatalogTaxes are being updated. |
taxes_to_enable
|
string[]
|
The set of CatalogTaxes (referenced by ID) to enable for the CatalogItem. |
taxes_to_disable
|
string[]
|
The set of CatalogTaxes (referenced by ID) to disable for the CatalogItem. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
updated_at
|
string
|
The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z". |
Example HTTP Request
POST /v2/catalog/update-item-taxes
{ "item_ids": [ "H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6" ], "taxes_to_enable": [ "4WRCNHCJZDVLSNDQ35PP6YAD" ], "taxes_to_disable": [ "AQCEGCEBBQONINDOHRGZISEX" ] }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Add two Taxes to an existing Item.
body = UpdateItemTaxesRequest(
item_ids=['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
taxes_to_enable=['4WRCNHCJZDVLSNDQ35PP6YAD'],
taxes_to_disable=['AQCEGCEBBQONINDOHRGZISEX']
)
response = api.update_item_taxes(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Change Taxes to two existing Items.
var body = new UpdateItemTaxesRequest(
ItemIds: new List() {"H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"},
TaxesToEnable: new List() {"4WRCNHCJZDVLSNDQ35PP6YAD"},
TaxesToDisable: new List() {"AQCEGCEBBQONINDOHRGZISEX"});
var response = api.UpdateItemTaxes(body);
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Package the tax information we want to enable/disable for the target IDs
$taxUpdates = [
"item_ids" => ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
"taxes_to_enable" => ["4WRCNHCJZDVLSNDQ35PP6YAD"],
"taxes_to_disable" => ["AQCEGCEBBQONINDOHRGZISEX"]
];
// Make the update
$apiResponse = $api->UpdateItemTaxes($taxUpdates);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Change Taxes to two existing Items.
const body = {
item_ids: ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6'],
taxes_to_enable: ['4WRCNHCJZDVLSNDQ35PP6YAD'],
taxes_to_disable: ['AQCEGCEBBQONINDOHRGZISEX']
};
api.updateItemTaxes(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Change Taxes to two existing Items.
body = SquareConnect::UpdateItemTaxesRequest.new
body.item_ids = ['H42BRLUJ5KTZTTMPVSLFAACQ', '2JXOBJIHCWBQ4NZ3RIXQGJA6']
body.taxes_to_enable = ['4WRCNHCJZDVLSNDQ35PP6YAD']
body.taxes_to_disable = ['AQCEGCEBBQONINDOHRGZISEX']
response = api.update_item_taxes(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Change Taxes to two existing Items.
UpdateItemTaxesRequest body = new UpdateItemTaxesRequest()
.itemIds(Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"))
.addTaxesToEnableItem("4WRCNHCJZDVLSNDQ35PP6YAD")
.addTaxesToDisableItem("AQCEGCEBBQONINDOHRGZISEX");
UpdateItemTaxesResponse response = api.updateItemTaxes(body);
Example Response
{
"updated_at": "2016-11-16T22:25:24.878Z"
}
POST /v2/catalog/object
Creates or updates the target CatalogObject.
Required permissions:
ITEMS_WRITE
Name | Type | Description |
---|---|---|
idempotency_key
(required) |
string
|
A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See Idempotency keys for more information. |
object
(required) |
CatalogObject
|
A CatalogObject to be created or updated. The object's |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
The set of Errors encountered. |
catalog_object
|
CatalogObject
|
The created CatalogObject. |
id_mappings
|
CatalogIdMapping[]
|
The mapping between client and server IDs for this Upsert. |
Example HTTP Request
POST /v2/catalog/object
{ "idempotency_key": "af3d1afc-7212-4300-b463-0bfc5314a5ae", "object": { "type": "ITEM", "id": "#Cocoa", "item_data": { "name": "Cocoa", "description": "Hot chocolate", "abbreviation": "Ch" } } }
Example Request in Python
api = squareconnect.apis.catalog_api.CatalogApi()
# Create a new item and/or reconfigure an existing item
item_cocoa = CatalogObject(
type='ITEM',
id='#Cocoa',
item_data=CatalogItem(
name='Cocoa',
description='Hot chocolate',
abbreviation='Ch'
)
)
# Initialize request body.
# Set a unique idempotency key for each request.
body = UpsertCatalogObjectRequest(
idempotency_key='af3d1afc-7212-4300-b463-0bfc5314a5ae',
object=item_cocoa
)
# Upsert the catalog item
response = api.upsert_catalog_object(body)
Example Request in C#
CatalogApi api = new CatalogApi();
// Create a new item or reconfigure an existing item
CatalogObject itemCocoa = new CatalogObject(
Type: CatalogObject.TypeEnum.ITEM,
Id: "#Cocoa",
PresentAtAllLocations: true,
ItemData: new CatalogItem(
Name: "Cocoa",
Description: "Hot chocolate",
Abbreviation: "Ch")
);
// Initialize request body.
// Set a unique idempotency key for each request.
var body = new UpsertCatalogObjectRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
_Object: itemCocoa);
// Upsert the catalog item
response = api.UpsertCatalogObject(body)
Example Request in PHP
$api = new \SquareConnect\Api\CatalogApi();
// Create a new item and/or reconfigure an existing item
// Set a unique idempotency key for each request
$myCatalogObject = [
"idempotency_key" => "af3d1afc-7212-4300-b463-0bfc5314a5ae",
"object" => [
"type" => "ITEM",
"id" => "#Cocoa",
"item_data" => [
"name" => "Cocoa",
"description" => "Hot chocolate",
"abbreviation" => "Ch"
]
]
];
// Upsert the catalog item
$apiResponse = $api->UpsertCatalogObject($myCatalogObject);
Example Request in Node.js
const api = new SquareConnect.CatalogApi();
// Create a new item or reconfigure an existing item
const itemCocoa = {
type: 'ITEM',
id: '#Cocoa',
item_data: {
name: 'Cocoa',
description: 'Hot chocolate',
abbreviation: 'Ch'
}
};
// Initialize request body.
// Set a unique idempotency key for each request.
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotencyKey,
object: itemCocoa
};
// Upsert the catalog item
api.upsertCatalogObject(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CatalogApi.new
# Create a new item or reconfigure an existing item
item_cocoa = {
type: SquareConnect::CatalogObjectType::ITEM,
id: '#Cocoa',
item_data: {
name: 'Cocoa',
description: 'Hot chocolate',
abbreviation: 'Ch'
}
}
# Initialize request body.
# Set a unique idempotency key for each request.
idempotency_key = SecureRandom.uuid
body = SquareConnect::UpsertCatalogObjectRequest.new(
idempotency_key: idempotency_key,
object: item_cocoa
)
# Upsert the catalog item
response = api.upsert_catalog_object(body)
Example Request in Java
CatalogApi api = new CatalogApi();
// Create a new item or reconfigure an existing item
CatalogObject itemCocoa = new CatalogObject()
.type(CatalogObject.TypeEnum.ITEM)
.id("#Cocoa")
.presentAtAllLocations(true)
.itemData(new CatalogItem()
.name("Cocoa")
.description("Hot chocolate")
.abbreviation("Ch")
);
// Initialize request body.
// Set a unique idempotency key for each request.
UpsertCatalogObjectRequest body = new UpsertCatalogObjectRequest()
.idempotencyKey(UUID.randomUUID().toString())
.object(itemCocoa);
// Upsert the catalog item
UpsertCatalogObjectResponse response = api.upsertCatalogObject(body);
Example Response
{
"catalog_object": {
"type": "ITEM",
"id": "7SB3ZQYJ5GDMVFL7JK46JCHT",
"updated_at": "2016-11-16T22:32:42.996Z",
"version": 1479335562996,
"is_deleted": false,
"item_data": {
"name": "Cocoa",
"description": "Hot chocolate",
"abbreviation": "Ch"
}
},
"id_mappings": [
{
"client_object_id": "#Cocoa",
"object_id": "7SB3ZQYJ5GDMVFL7JK46JCHT"
}
]
}
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:
PAYMENTS_WRITE
ORDERS_WRITE
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the business location to associate the checkout with. |
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) |
CreateOrderRequest
|
The order including line items to be checked out. |
ask_for_shipping_address
|
boolean
|
If Default: |
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: none; only exists if explicitly set. |
pre_populate_buyer_email
|
string
|
If provided, the buyer's email is pre-populated on the checkout page as an editable text field. Default: none; only exists if explicitly set. |
pre_populate_shipping_address
|
Address
|
If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields. Default: none; only exists if explicitly set. |
redirect_url
|
string
|
The URL to redirect to after checkout is completed with
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: none; only exists if explicitly set. |
additional_recipients
|
ChargeRequestAdditionalRecipient[]
|
The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the This field requires This field is currently not supported in sandbox. |
note
|
string
|
An optional note to associate with the checkout object. This value cannot exceed 60 characters. |
Name | Type | Description |
---|---|---|
checkout
|
Checkout
|
The newly created checkout. If the same request was made with the same idempotency_key, this will be the checkout created with the idempotency_key. |
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
POST /v2/locations/{location_id}/checkouts
{ "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad6", "order": { "reference_id": "reference_id", "line_items": [ { "name": "Printed T Shirt", "quantity": "2", "base_price_money": { "amount": 1500, "currency": "USD" }, "discounts": [ { "name": "7% off previous season item", "percentage": "7" }, { "name": "$3 off Customer Discount", "amount_money": { "amount": 300, "currency": "USD" } } ] }, { "name": "Slim Jeans", "quantity": "1", "base_price_money": { "amount": 2500, "currency": "USD" } }, { "name": "Woven Sweater", "quantity": "3", "base_price_money": { "amount": 3500, "currency": "USD" }, "discounts": [ { "name": "$11 off Customer Discount", "amount_money": { "amount": 1100, "currency": "USD" } } ], "taxes": [ { "name": "Fair Trade Tax", "percentage": "5" } ] } ], "discounts": [ { "name": "Father's day 12% OFF", "percentage": "12" }, { "name": "Global Sales $55 OFF", "amount_money": { "amount": 5500, "currency": "USD" } } ], "taxes": [ { "name": "Sales Tax", "percentage": "8.5" } ] }, "additional_recipients": [ { "location_id": "057P5VYJ4A5X1", "description": "Application fees", "amount_money": { "amount": 60, "currency": "USD" } } ], "ask_for_shipping_address": true, "merchant_support_email": "[email protected]", "pre_populate_buyer_email": "[email protected]", "pre_populate_shipping_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", "first_name": "Jane", "last_name": "Doe" }, "redirect_url": "https://merchant.website.com/order-confirm" }
Example Request in Python
api = squareconnect.apis.checkout_api.CheckoutApi()
result = api.create_checkout(LOCATION_ID, CreateCheckoutRequest(
idempotency_key='74ae1696-b1e3-4328-af6d-f1e04d947a13',
order=CreateOrderRequest(
reference_id='reference_id',
line_items=[
CreateOrderRequestLineItem(
name='Printed T Shirt',
quantity='2',
base_price_money=Money(1500, 'USD'),
discounts=[
CreateOrderRequestDiscount(
name='7% off previous season item',
percentage='7'
),
CreateOrderRequestDiscount(
name='$3 off Customer Discount',
amount_money=Money(300, 'USD')
)
]
),
CreateOrderRequestLineItem(
name='Slim Jeans',
quantity='1',
base_price_money=Money(2500, 'USD')
),
CreateOrderRequestLineItem(
name='Woven Sweater',
quantity='3',
base_price_money=Money(3500, 'USD'),
discounts=[
CreateOrderRequestDiscount(
name='$11 off Customer Discount',
amount_money=Money(1100, 'USD')
)
],
taxes=[
CreateOrderRequestTax(
name='Fair Trade Tax',
percentage='5'
)
]
)
],
discounts=[
CreateOrderRequestDiscount(
name='Father's day 12% OFF',
percentage='12'
),
CreateOrderRequestDiscount(
name='Global Sales $55 OFF',
amount_money=Money(5500, 'USD')
)
],
taxes=[
CreateOrderRequestTax(
name='Sales Tax',
percentage='8.5'
)
]
),
additional_recipients=[
CreateCheckoutRequestAdditionalRecipient(
location_id='057P5VYJ4A5X1',
description='Application fees',
amount_money=Money(60, 'USD')
)
],
ask_for_shipping_address=True,
merchant_support_email='[email protected]',
pre_populate_buyer_email='[email protected]',
pre_populate_shipping_address=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',
first_name='Jane',
last_name='Doe'
),
redirect_url='https://merchant.website.com/order-confirm'
))
checkout = result.checkout()
Example Request in C#
CheckoutApi api = new CheckoutApi();
CreateCheckoutResponse response = api.CreateCheckout(LOCATION_ID, new CreateCheckoutRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
Order: new CreateOrderRequest(
ReferenceId: "reference_id",
LineItems: new List()
{
new CreateOrderRequestLineItem(
Name: "Printed T Shirt",
Quantity: "2",
BasePriceMoney: new Money(
Amount: 1500,
Currency: Currency.USD
),
Discounts: new List()
{
new CreateOrderRequestDiscount(
Name: "7% off previous season item",
Percentage: "7"
),
new CreateOrderRequestDiscount(
Name: "$3 off Customer Discount",
AmountMoney: new Money(
Amount: 300,
Currency: Currency.USD
)
)
}
),
new CreateOrderRequestLineItem(
Name: "Slim Jeans",
Quantity: "1",
BasePriceMoney: new Money(
Amount: 2500,
Currency: Currency.USD
)
),
new CreateOrderRequestLineItem(
Name: "Woven Sweater",
Quantity: "3",
BasePriceMoney: new Money(
Amount: 3500,
Currency: Currency.USD
),
Discounts: new List()
{
new CreateOrderRequestDiscount(
Name: "$11 off Customer Discount",
AmountMoney: new Money(
Amount: 1100,
Currency: Currency.USD
)
)
},
Taxes: new List()
{
new CreateOrderRequestTax(
Name: "Fair Trade Tax",
Percentage: "5"
)
}
)
},
Discounts: new List()
{
new CreateOrderDiscount(
Name: "Father's day 12% OFF",
Percentage: "12"
),
new CreateOrderDiscount(
Name: "Global Sales $55 OFF",
AmountMoney: new Money(
Amount: 5500,
Currency: Currency.USD
)
)
},
Taxes: new List()
{
new CreateOrderRequestTax(
Name: "Sales Tax",
Percentage: "8.5"
)
}
),
AdditionalRecipients: new List(){
new CreateCheckoutRequestAdditionalRecipient(
LocationId: "057P5VYJ4A5X1",
Description: "Application fees",
AmountMoney: new Money(60, Money.ToCurrencyEnum("USD"))
)
},
AskForShippingAddress: true,
MerchantSupportEmail: "[email protected]",
PrePopulateBuyerEmail: "[email protected]",
PrePopulateShippingAddress: new Address(
AddressLine1: "1455 Market St.",
AddressLine2: "Suite 600",
Locality: "San Francisco",
AdministrativeDistrictLevel1: "CA",
PostalCode: "94103",
Country: Address.CountryEnum.US
),
RedirectUrl: "https://merchant.website.com/order-confirm"
));
Checkout checkout = response.Checkout;
Example Request in PHP
$api = new \SquareConnect\Api\CheckoutApi();
$idempotencyKey = uniqid();
$result = $api->createCheckout($LOCATION_ID, [
'idempotency_key' => $idempotencyKey,
'order' => [
'reference_id' => 'reference_id',
'line_items' => [
[
'name' => 'Printed T Shirt',
'quantity' => '2',
'base_price_money' => [
'amount' => 1500,
'currency' => 'USD'
],
'discounts' => [
[
'name' => '7% off previous season item',
'percentage' => '7'
],
[
'name' => '$3 off Customer Discount',
'amount_money' => [
'amount': 300,
'currency': 'USD'
]
]
]
],
[
'name' => 'Slim Jeans',
'quantity' => '1',
'base_price_money' => [
'amount' => 2500,
'currency' => 'USD'
]
],
[
'name' => 'Woven Sweater',
'quantity' => '3',
'base_price_money' => [
'amount' => 3500,
'currency' => 'USD'
],
'discounts' => [
[
'name' => '$11 off Customer Discount',
'amount_money' => [
'amount': 1100,
'currency': 'USD'
]
]
],
'taxes' => [
[
'name' => 'Fair Trade Tax',
'percentage' => '5'
]
]
]
],
'discounts' => [
[
'name' => 'Father's day 12% OFF',
'percentage' => '12'
],
[
'name' => 'Global Sales $55 OFF',
'amount_money' => [
'amount': 5500,
'currency': 'USD'
]
]
],
'taxes' => [
[
'name' => 'Sales Tax',
'percentage' => '8.5'
]
]
],
'additional_recipients' => array(
array(
'location_id' => '057P5VYJ4A5X1',
'description' => 'Application fees',
'amount_money' => array(
'amount' => 60, 'currency' => 'USD'
)
)
),
'ask_for_shipping_address' => true,
'merchant_support_email' => '[email protected]',
'pre_populate_buyer_email' => '[email protected]',
'pre_populate_shipping_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',
'first_name' => 'Jane',
'last_name' => 'Doe'
],
'redirect_url' => 'https://merchant.website.com/order-confirm'
]);
$checkout = $result->getCheckout();
Example Request in Node.js
const api = new SquareConnect.CheckoutApi();
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotencyKey,
order: {
reference_id: 'reference_id',
line_items: [
{
name: 'Printed T Shirt',
quantity: '2',
base_price_money: {
amount: 1500,
currency: 'USD'
},
discounts: [
{
name: '7% off previous season item',
percentage: '7'
},
{
name: '$3 off Customer Discount',
amount_money: {
amount: 300,
currency: 'USD'
}
}
]
},
{
name: 'Slim Jeans',
quantity: '1',
base_price_money: {
amount: 2500,
currency: 'USD'
}
},
{
name: 'Woven Sweater',
quantity: '3',
base_price_money: {
amount: 3500,
currency: 'USD'
},
discounts: [
{
name: '$11 off Customer Discount',
amount_money: {
amount: 1100,
currency: 'USD'
}
}
],
taxes: [
{
name: 'Fair Trade Tax',
percentage: '5'
}
]
}
],
discounts: [
{
name: "Father's day 12% OFF",
percentage: '12'
},
{
name: "Global Sales $55 OFF",
amount_money: {
amount: 5500,
currency: 'USD'
}
}
],
taxes: [
{
name: 'Sales Tax',
percentage: '8.5'
}
]
},
additional_recipients: [
{
location_id: '057P5VYJ4A5X1',
description: 'Application fees',
amount_money: {
amount: 60, currency: 'USD'
}
}
],
ask_for_shipping_address: true,
merchant_support_email: '[email protected]',
pre_populate_buyer_email: '[email protected]',
pre_populate_shipping_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',
first_name: 'Jane',
last_name: 'Doe'
},
redirect_url: 'https://merchant.website.com/order-confirm'
};
api.createCheckout(LOCATION_ID, body)
.then((response) => {
const checkout = response.checkout;
// Handle checkout object
});
Example Request in Ruby
api = SquareConnect::CheckoutApi.new
idempotency_key = SecureRandom.uuid
result = api.create_checkout(LOCATION_ID, {
idempotency_key: idempotency_key,
order: {
reference_id: 'reference_id',
line_items: [
{
name: 'Printed T Shirt',
quantity: '2',
base_price_money: {
amount: 1500,
currency: 'USD'
},
discounts: [
{
name: '7% off previous season item',
percentage: '7'
},
{
name: '$3 off Customer Discount',
amount_money: {
amount: 300,
currency: 'USD'
}
}
]
},
{
name: 'Slim Jeans',
quantity: '1',
base_price_money: {
amount: 2500,
currency: 'USD'
}
},
{
name: 'Woven Sweater',
quantity: '3',
base_price_money: {
amount: 3500,
currency: 'USD'
},
discounts: [
{
name: '$11 off Customer Discount',
amount_money: {
amount: 1100,
currency: 'USD'
}
}
],
taxes: [
{
name: 'Fair Trade Tax',
percentage: '5'
}
]
}
],
discounts: [
{
name: "Father's day 12% OFF",
percentage: '12'
},
{
name: "Global Sales $55 OFF",
amount_money: {
amount: 5500,
currency: 'USD'
}
}
],
taxes: [
{
name: 'Sales Tax',
percentage: '8.5'
}
]
},
additional_recipients: [
{
location_id: '057P5VYJ4A5X1',
description: 'Application fees',
amount_money: {
amount: 60, currency: 'USD'
}
}
],
ask_for_shipping_address: true,
merchant_support_email: '[email protected]',
pre_populate_buyer_email: '[email protected]',
pre_populate_shipping_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',
first_name: 'Jane',
last_name: 'Doe'
},
redirect_url: 'https://merchant.website.com/order-confirm'
})
checkout = result.checkout
Example Request in Java
CheckoutApi api = new CheckoutApi();
CreateCheckoutResponse response = api.createCheckout(locationId, new CreateCheckoutRequest()
.idempotencyKey(UUID.randomUUID().toString())
.order(new CreateOrderRequestOrder()
.referenceId("reference_id")
.lineItems(Arrays.asList(
new CreateOrderRequestLineItem()
.name("Printed T Shirt")
.quantity("2")
.basePriceMoney(new Money()
.amount(1500L)
.currency(Money.CurrencyEnum.USD))
.addDiscountsItem(new CreateOrderRequestDiscount()
.name("7% off previous season item")
.percentage("7")
)
.addDiscountsItem(new CreateOrderRequestDiscount()
.name("$3 off Customer Discount")
.amountMoney(new Money()
.amount(300L)
.currency(Money.CurrencyEnum.USD))
)
new CreateOrderRequestLineItem()
.name("Slim Jeans")
.quantity("1")
.basePriceMoney(new Money()
.amount(2500L)
.currency(Money.CurrencyEnum.USD)),
new CreateOrderRequestLineItem()
.name("Woven Sweater")
.quantity("3")
.basePriceMoney(new Money()
.amount(3500L)
.currency(Money.CurrencyEnum.USD))
.addDiscountsItem(new CreateOrderRequestDiscount()
.name("$11 off Customer Discount")
.amountMoney(new Money()
.amount(1100L)
.currency(Money.CurrencyEnum.USD))
)
.addTaxesItem(new CreateOrderRequestTax()
.name("Fair Trade Tax"),
.percentage("5")
)
))
.discounts(Arrays.asList(
new CreateOrderRequestDiscount()
.name("Father's day 12% OFF")
.percentage("12"),
new CreateOrderRequestDiscount()
.name("Global Sales $55 OFF")
.amountMoney(new Money()
.amount(5500L)
.currency(Money.CurrencyEnum.USD))
))
.addTaxesItem(new CreateOrderRequestTax()
.name("Sales Tax")
.percentage("8.5")
)
)
.addAdditionalRecipientsItem(new CreateCheckoutRequestAdditionalRecipient()
.locationId("057P5VYJ4A5X1")
.description("Application fees")
.amountMoney(new Money()
.amount(60L)
.currency(Money.CurrencyEnum.USD)))
.askForShippingAddress(true)
.merchantSupportEmail("[email protected]")
.prePopulateBuyerEmail("[email protected]")
.prePopulateShippingAddress(new Address()
.addressLine1("1455 Market St.")
.addressLine2("Suite 600")
.locality("San Francisco")
.administrativeDistrictLevel1("CA")
.postalCode("94103")
.country(Address.CountryEnum.US)
)
.redirectUrl("https://merchant.website.com/order-confirm"));
Checkout checkout = response.getCheckout();
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": "[email protected]",
"pre_populate_buyer_email": "[email protected]",
"pre_populate_shipping_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",
"first_name": "Jane",
"last_name": "Doe"
},
"redirect_url": "https://merchant.website.com/order-confirm",
"order": {
"location_id": "CYTKRM7R7JMV8",
"reference_id": "reference_id",
"line_items": [
{
"name": "Printed T Shirt",
"quantity": "2",
"taxes": [
{
"name": "Sales Tax",
"type": "ADDITIVE",
"percentage": "8.5",
"applied_money": {
"amount": 103,
"currency": "USD"
}
}
],
"discounts": [
{
"name": "7% off previous season item",
"type": "FIXED_PERCENTAGE",
"percentage": "7",
"applied_money": {
"amount": 210,
"currency": "USD"
},
"scope": "LINE_ITEM"
},
{
"name": "Father's day 12% OFF",
"type": "FIXED_PERCENTAGE",
"percentage": "12",
"applied_money": {
"amount": 335,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "$3 off Customer Discount",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 300,
"currency": "USD"
},
"applied_money": {
"amount": 300,
"currency": "USD"
},
"scope": "LINE_ITEM"
},
{
"name": "Global Sales $55 OFF",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 5500,
"currency": "USD"
},
"applied_money": {
"amount": 949,
"currency": "USD"
},
"scope": "ORDER"
}
],
"base_price_money": {
"amount": 1500,
"currency": "USD"
},
"total_tax_money": {
"amount": 103,
"currency": "USD"
},
"total_discount_money": {
"amount": 1794,
"currency": "USD"
},
"total_money": {
"amount": 1309,
"currency": "USD"
}
},
{
"name": "Slim Jeans",
"quantity": "1",
"taxes": [
{
"name": "Sales Tax",
"type": "ADDITIVE",
"percentage": "8.5",
"applied_money": {
"amount": 105,
"currency": "USD"
}
}
],
"discounts": [
{
"name": "Father's day 12% OFF",
"type": "FIXED_PERCENTAGE",
"percentage": "12",
"applied_money": {
"amount": 300,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "Global Sales $55 OFF",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 5500,
"currency": "USD"
},
"applied_money": {
"amount": 968,
"currency": "USD"
},
"scope": "ORDER"
}
],
"base_price_money": {
"amount": 2500,
"currency": "USD"
},
"total_tax_money": {
"amount": 105,
"currency": "USD"
},
"total_discount_money": {
"amount": 1268,
"currency": "USD"
},
"total_money": {
"amount": 1337,
"currency": "USD"
}
},
{
"name": "Wooven Sweater",
"quantity": "3",
"taxes": [
{
"name": "Fair Trade Tax",
"type": "ADDITIVE",
"percentage": "5",
"applied_money": {
"amount": 228,
"currency": "USD"
}
},
{
"name": "Sales Tax",
"type": "ADDITIVE",
"percentage": "8.5",
"applied_money": {
"amount": 387,
"currency": "USD"
}
}
],
"discounts": [
{
"name": "Father's day 12% OFF",
"type": "FIXED_PERCENTAGE",
"percentage": "12",
"applied_money": {
"amount": 1260,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "$11 off Customer Discount",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 1100,
"currency": "USD"
},
"applied_money": {
"amount": 1100,
"currency": "USD"
},
"scope": "LINE_ITEM"
},
{
"name": "Global Sales $55 OFF",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 5500,
"currency": "USD"
},
"applied_money": {
"amount": 3583,
"currency": "USD"
},
"scope": "ORDER"
}
],
"base_price_money": {
"amount": 3500,
"currency": "USD"
},
"total_tax_money": {
"amount": 615,
"currency": "USD"
},
"total_discount_money": {
"amount": 5943,
"currency": "USD"
},
"total_money": {
"amount": 5172,
"currency": "USD"
}
}
],
"total_money": {
"amount": 7818,
"currency": "USD"
},
"total_tax_money": {
"amount": 823,
"currency": "USD"
},
"total_discount_money": {
"amount": 9005,
"currency": "USD"
}
},
"created_at": "2017-06-16T22:25:35Z",
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 60,
"currency": "USD"
}
}
]
}
}
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
Required permissions:
CUSTOMERS_WRITE
Name | Type | Description |
---|---|---|
idempotency_key
|
string
|
The idempotency key for the request. See the Idempotency guide for more information. |
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. |
birthday
|
string
|
The customer birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example:
|
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": "[email protected]", "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 Python
api = squareconnect.apis.customers_api.CustomersApi()
api.create_customer(CreateCustomerRequest(
given_name='Amelia',
family_name='Earhart',
email_address='[email protected]',
address=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 Request in C#
CustomersApi api = new CustomersApi();
api.CreateCustomer(new CreateCustomerRequest(
GivenName: "Amelia",
FamilyName: "Earhart",
EmailAddress: "[email protected]",
Address: new Address(
AddressLine1: "500 Electric Ave",
AddressLine2: "Suite 600",
Locality: "New York",
AdministrativeDistrictLevel1: "NY",
PostalCode: "20003",
Country: Address.ToCountryEnum("US")),
PhoneNumber: "1-555-555-0122",
ReferenceId: "YOUR_REFERENCE_ID",
Note: "a customer"
));
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->createCustomer(array(
'given_name' => 'Amelia',
'family_name' => 'Earhart',
'email_address' => '[email protected]',
'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 Node.js
const api = new SquareConnect.CustomersApi();
const body = {
given_name: 'Amelia',
family_name: 'Earhart',
email_address: '[email protected]',
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'
};
api.createCustomer(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.create_customer({
given_name: 'Amelia',
family_name: 'Earhart',
email_address: '[email protected]',
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 Request in Java
CustomersApi api = new CustomersApi();
CreateCustomerResponse response = api.createCustomer(new CreateCustomerRequest()
.givenName("Amelia")
.familyName("Earhart")
.emailAddress("[email protected]")
.address(new Address()
.addressLine1("500 Electric Ave")
.addressLine2("Suite 600")
.locality("New York")
.administrativeDistrictLevel1("NY")
.postalCode("20003")
.country(Address.CountryEnum.US)
)
.phoneNumber("1-555-555-0122")
.referenceId("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": "[email protected]",
"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"
}
}
POST /v2/customers/{customer_id}/cards
Adds a card on file to an existing customer.
As with charges, calls to CreateCustomerCard
are idempotent. Multiple calls with the same card nonce return the same
card record that was created with the provided nonce during the first call.
Required permissions:
CUSTOMERS_WRITE
Name | Type | Description |
---|---|---|
customer_id
(required) |
string
|
The ID of the customer to link the card on file to. |
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 Note: Card nonces generated by digital wallets (e.g., Apple Pay) cannot be used to create a customer card. |
billing_address
|
Address
|
Address information for the card on file. Only the |
cardholder_name
|
string
|
The cardholder's name. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
card
|
Card
|
The created card on file. |
Example HTTP Request
POST /v2/customers/{customer_id}/cards
{ "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 Python
api = squareconnect.apis.customers_api.CustomersApi()
api.create_customer_card(customer.id, CreateCustomerCardRequest(
card_nonce=CARD_NONCE,
billing_address=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 Request in C#
CustomersApi api = new CustomersApi();
api.CreateCustomerCard(customer.Id, new CreateCustomerCardRequest(
CardNonce: card_nonce,
BillingAddress: new Address(
AddressLine1: "1455 Market St",
AddressLine2: "Suite 600",
Locality: "San Francisco",
AdministrativeDistrictLevel1: "CA",
PostalCode: "94103",
Country: Address.ToCountryEnum("US")),
CardholderName: "Amelia Earhart"
));
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->createCustomerCard($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 Node.js
const api = new SquareConnect.CustomersApi();
const body = {
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'
};
api.createCustomerCard(customer.id, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.create_customer_card(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 Request in Java
CustomersApi api = new CustomersApi();
CreateCustomerCardResponse response = api.createCustomerCard(customer.getId(), new CreateCustomerCardRequest()
.cardNonce(cardNonce)
.billingAddress(new Address()
.addressLine1("500 Electric Ave")
.addressLine2("Suite 600")
.locality("New York")
.administrativeDistrictLevel1("NY")
.postalCode("94103")
.country(Address.CountryEnum.US))
.cardholderName("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"
}
}
}
DELETE /v2/customers/{customer_id}
Deletes a customer from a business, along with any linked cards on file. When two profiles are merged into a single
profile, that profile is assigned a new customer_id
. You must use the new customer_id
to delete merged profiles.
Required permissions:
CUSTOMERS_WRITE
Name | Type | Description |
---|---|---|
customer_id
(required) |
string
|
The ID of the customer to delete. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
DELETE /v2/customers/{customer_id}
Example Request in Python
api = squareconnect.apis.customers_api.CustomersApi()
api.delete_customer(customer.id)
Example Request in C#
CustomersApi api = new CustomersApi();
api.DeleteCustomer(customer.Id);
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->deleteCustomer($customer->getId());
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
api.deleteCustomer(customer.id)
.then((response) => {});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.delete_customer(customer.id)
Example Request in Java
CustomersApi api = new CustomersApi();
api.deleteCustomer(customer.getId());;
DELETE /v2/customers/{customer_id}/cards/{card_id}
Removes a card on file from a customer.
Required permissions:
CUSTOMERS_WRITE
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. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
DELETE /v2/customers/{customer_id}/cards/{card_id}
Example Request in Python
api = squareconnect.apis.customers_api.CustomersApi()
api.delete_customer_card(customer.id, customer_card.id)
Example Request in C#
CustomersApi api = new CustomersApi();
api.DeleteCustomerCard(customer.Id, card.Id);
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->deleteCustomerCard($customer->getId(), $customerCard->getId());
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
api.deleteCustomerCard(customer.id, customerCard.id)
.then((response) => {});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.delete_customer_card(customer.id, customer_card.id)
Example Request in Java
CustomersApi api = new CustomersApi();
api.deleteCustomerCard(customer.getId(), card.getId())
GET /v2/customers
Lists a business's customers.
Required permissions:
CUSTOMERS_READ
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. |
sort_field
|
string
|
Indicates how Customers should be sorted. Default: |
sort_order
|
string
|
Indicates whether Customers should be sorted in ascending ( |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
customers
|
Customer[]
|
An array of |
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 /v2/customers
Example Request in Python
api = squareconnect.apis.customers_api.CustomersApi()
api.list_customers()
Example Request in C#
CustomersApi api = new CustomersApi();
api.ListCustomers();
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->listCustomers();
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
api.listCustomers()
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.list_customers()
Example Request in Java
CustomersApi api = new CustomersApi();
api.listCustomers("");
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": "[email protected]",
"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"
}
]
}
]
}
GET /v2/customers/{customer_id}
Returns details for a single customer.
Required permissions:
CUSTOMERS_READ
Name | Type | Description |
---|---|---|
customer_id
(required) |
string
|
The ID of the customer to retrieve. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
customer
|
Customer
|
The requested customer. |
Example HTTP Request
GET /v2/customers/{customer_id}
Example Request in Python
api = squareconnect.apis.customers_api.CustomersApi()
api.retrieve_customer(customer.id)
Example Request in C#
CustomersApi api = new CustomersApi();
api.RetrieveCustomer(customer.Id);
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->retrieveCustomer($customer->getId());
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
api.retrieveCustomer(customer.id)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.retrieve_customer(customer.id)
Example Request in Java
CustomersApi api = new CustomersApi();
api.retrieveCustomer(customer.getId());
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": "[email protected]",
"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"
}
]
}
}
POST /v2/customers/search
Searches the customer profiles associated with a Square account. Calling SearchCustomers without an explicit query
parameter returns all customer profiles ordered alphabetically based on given_name
and family_name
.
Required permissions:
CUSTOMERS_READ
Name | Type | Description |
---|---|---|
cursor
|
string
|
Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. See Paginating results for more information. |
limit
|
integer
|
A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored. |
query
|
CustomerQuery
|
Query customers based on the given conditions and sort order. Calling SearchCustomers without an explicit query
parameter will return all customers ordered alphabetically based on |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
customers
|
Customer[]
|
An array of |
cursor
|
string
|
A pagination cursor that can be used during subsequent calls to SearchCustomers to retrieve the next set of results associated with the original query. Pagination cursors are only present when a request succeeds and additional results are available. See Paginating results for more information. |
Example HTTP Request
POST /v2/customers/search
{ "query": { "filter": { "creation_source": { "values": [ "THIRD_PARTY" ], "rule": "INCLUDE" }, "created_at": { "start_at": "2018-01-01T00:00:00-00:00", "end_at": "2018-02-01T00:00:00-00:00" } }, "sort": { "field": "CREATED_AT", "order": "ASC" } }, "limit": 2 }
Example Request in Python
api = CustomersApi()
response = api.search_customers(SearchCustomersRequest(
query=CustomerQuery(
filter=CustomerFilter(
creation_source=CustomerCreationSource(
values=['THIRD_PARTY'],
rule='INCLUDE'),
created_at=TimeRange(
start_at="2018-01-01T00:00:00-00:00",
end_at="2018-02-01T00:00:00-00:00")),
sort=CustomerSort(
field="CREATED_AT",
order="ASC"))
limit=2)
Example Request in C#
CustomerApi api = new CustomerApi();
SearchCustomersResponse response = api.SearchCustomers(new SearchCustomerRequest(
Query: new CustomerQuery(
Filter: new CustomerFilter(
CreationSource: new CustomerCreationSourceFilter(
Values: new List(){ Customer.CreationSourceEnum.THIRDPARTY },
Rule: CustomerInclusionExclusion.INCLUDE),
CreatedAt: new TimeRange(
StartAt: "2018-01-01T00:00:00-00:00"
EndAt: "2018-02-01T00:00:00-00:00")),
Sort: new CustomerSort(
Field: CustomerSortField.CREATED_AT,
Sort: SortOrder.ASC))),
Limit: 2);
List customers = response.Customers
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$response = $api->searchCustomers(new \SquareConnect\Api\Model\SearchCustomersRequest([
"query" => [
"filter" => [
"creation_source" => [
"values" => ["THIRD_PARTY"],
"rule" => "INCLUDE"
],
"created_at" => [
"start_at" => "2018-01-01T00:00:00-00:00",
"end_at" => "2018-02-01T00:00:00-00:00"
]
],
"sort": [
"field" => "CREATED_AT",
"order" => "ASC"
]
],
"limit" => 2
]));
$customers = $response->getCustomers();
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
const body = {
'query': {
'filter': {
'creation_source': {
'values': ['THIRD_PARTY'],
'rule': 'INCLUDE'
},
'created_at': {
'start_at': '2018-01-01T00:00:00-00:00',
'end_at': '2018-02-01T00:00:00-00:00'
}
},
'sort': {
'field': 'CREATED_AT',
'order': 'ASC'
}
},
'limit': 2
};
api.searchCustomers(body).then(response => {
// handle response.
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.search_customers({
query: {
filter: {
creation_source: {
values: [SquareConnect::CustomerCreationSource::THIRD_PARTY,],
rule: SquareConnect::CustomerInclusionExclusion::INCLUDE
},
created_at: {
start_at:"2018-01-01T00:00:00-00:00",
end_at: "2018-02-01T00:00:00-00:00"
}
},
sort: {
field: SquareConnect::CustomerSortField::CREATED_AT,
order: SquareConnect::SortOrder::ASC
}
},
limit: 2
})
Example Request in Java
CustomersApi api = new CustomersApi();
SearchCustomersResponse response = api.searchCustomers(new SearchCustomersRequest()
.query(new CustomerQuery()
.filter(new CustomerFilter()
.creationSource(new CustomerCreationSourceFilter()
.addValuesItem(CustomerCreationSourceFilter.ValuesEnum.THIRD_PARTY)
.rule(CustomerCreationSourceFilter.RuleEnum.INCLUDE))
.createdAt(new TimeRange()
.startAt("2018-01-01T00:00:00-00:00")
.endAt("2018-02-01T00:00:00-00:00")))
.sort(new CustomerSort()
.field(CustomerSort.FieldEnum.CREATED_AT)
.order(CustomerSort.OrderEnum.ASC)))
.limit(2L));
List customers = response.getCustomers();
Example Response
{
"customers": [
{
"id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"created_at": "2018-01-23T20:21:54.859Z",
"updated_at": "2018-04-20T10:02:43.083Z",
"given_name": "James",
"family_name": "Bond",
"email_address": "[email protected]",
"address": {
"address_line_1": "505 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-4250",
"reference_id": "YOUR_REFERENCE_ID_2",
"creation_source": "THIRD_PARTY"
},
{
"id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
"created_at": "2018-01-30T14:10:54.859Z",
"updated_at": "2018-03-08T18:25:54.859Z",
"given_name": "Amelia",
"family_name": "Earhart",
"email_address": "[email protected]",
"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_1",
"note": "a customer",
"creation_source": "THIRD_PARTY"
}
],
"cursor": "9dpS093Uy12AzeE"
}
PUT /v2/customers/{customer_id}
Updates the details of an existing customer. When two profiles are merged into a single profile, that profile is
assigned a new customer_id
. You must use the new customer_id
to update merged profiles.
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
Name | Type | Description |
---|---|---|
customer_id
(required) |
string
|
The ID of the customer to update. |
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. |
birthday
|
string
|
The customer birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example:
|
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": "[email protected]", "note": "updated customer note" }
Example Request in Python
api = squareconnect.apis.customers_api.CustomersApi()
api.update_customer(customer.id, UpdateCustomerRequest(
phone_number='1-555-555-0123',
email_address='[email protected]',
note='updated customer note'
))
Example Request in C#
CustomersApi api = new CustomersApi();
api.UpdateCustomer(customer.Id, new UpdateCustomerRequest(
PhoneNumber: "1-555-555-0123",
EmailAddress: "[email protected]",
Note: "updated customer note"
));
Example Request in PHP
$api = new \SquareConnect\Api\CustomersApi();
$api->updateCustomer($customer->getId(), array(
'phone_number' => '',
'email_address' => '[email protected]',
'note' => 'updated customer note'
));
Example Request in Node.js
const api = new SquareConnect.CustomersApi();
const body = {
phone_number: '',
email_address: '[email protected]',
note: 'updated customer note'
};
api.updateCustomer(customer.id, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::CustomersApi.new
api.update_customer(customer.id, {
phone_number: '',
email_address: '[email protected]',
note: 'updated customer note'
})
Example Request in Java
CustomersApi api = new CustomersApi();
UpdateCustomerResponse response = api.updateCustomer(customer.getId(), new UpdateCustomerRequest()
.phoneNumber("1-555-555-0123")
.emailAddress("[email protected]")
.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": "[email protected]",
"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"
}
]
}
}
POST /v2/inventory/batch-change
Applies adjustments and counts to the provided item quantities.
On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors.
Required permissions:
INVENTORY_WRITE
Name | Type | Description |
---|---|---|
idempotency_key
|
string
|
A client-supplied, universally unique identifier (UUID) for the request. See Idempotency in the API Development 101 section for more information. |
changes
|
InventoryChange[]
|
The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order. Max size is 100 changes. |
ignore_unchanged_counts
|
boolean
|
Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical
count. Default: |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
counts
|
InventoryCount[]
|
The current counts for all objects referenced in the request. |
Example HTTP Request
POST /v2/inventory/batch-change
{ "idempotency_key": "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe", "changes": [ { "type": "PHYSICAL_COUNT", "physical_count": { "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92", "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI", "state": "IN_STOCK", "location_id": "C6W5YS5QM06F5", "quantity": "53", "employee_id": "LRK57NSQ5X7PUD05", "occurred_at": "2016-11-16T22:25:24.878Z" } } ], "ignore_unchanged_counts": true }
Example Request in Python
inventoryApi = InventoryApi()
# Create an InventoryChange consisting of a physical count.
physicalCount = InventoryPhysicalCount()
physicalCount.referenceId = '1536bfbf-efed-48bf-b17d-a197141b2a92'
physicalCount.catalogObjectId = 'W62UWFY35CWMYGVWK6TWJDNI'
physicalCount.state = 'IN_STOCK'
physicalCount.locationId = 'C6W5YS5QM06F5'
physicalCount.quantity = '53'
physicalCount.employeeId = 'LRK57NSQ5X7PUD05'
physicalCount.occurredAt = '2016-11-16T22:25:24.878Z'
change = InventoryChange()
change.type = 'PHYSICAL_COUNT'
change.physicalCount = physicalCount
request = BatchChangeInventoryRequest()
request.idempotencyKey = uuid.uuid4()
request.changes = [change]
request.ignoreUnchangedCounts = True
response = inventoryApi.batchChangeInventory(request)
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Create an InventoryChange consisting of a physical count and adjustment.
List changes = new List();
changes.Add(new InventoryChange(
Type: InventoryChange.TypeEnum.PHYSICALCOUNT,
PhysicalCount: new InventoryPhysicalCount(
ReferenceId: "1536bfbf-efed-48bf-b17d-a197141b2a92",
CatalogObjectId: "W62UWFY35CWMYGVWK6TWJDNI",
State: InventoryPhysicalCount.StateEnum.INSTOCK,
LocationId: "C6W5YS5QM06F5",
Quantity: "53",
EmployeeId: "LRK57NSQ5X7PUD05",
OccurredAt: "2017-11-16T22:25:24.878Z")));
changes.Add(new InventoryChange(
Type: InventoryChange.TypeEnum.ADJUSTMENT,
Adjustment: new InventoryAdjustment(
ReferenceId: "1536bfbf-efed-48bf-b17d-a197141b2a92",
CatalogObjectId: "W62UWFY35CWMYGVWK6TWJDNS",
FromState: InventoryAdjustment.FromStateEnum.INSTOCK,
ToState: InventoryAdjustment.ToStateEnum.SOLD,
LocationId: "C6W5YS5QM06F5"
Quantity: "5",
EmployeeId: "LRK57NSQ5X7PUD05",
OccurredAt: "2017-11-16T22:25:24.878Z")));
BatchChangeInventoryRequest request = new BatchChangeInventoryRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
Changes: changes,
IgnoreUnchangedCounts: true);
BatchChangeInventoryResponse response = inventoryApi.BatchChangeInventory(request);
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Create an InventoryChange consisting of a physical count.
$physical_count = new \SquareConnect\Model\InventoryPhysicalCount();
$physical_count->setReferenceId("1536bfbf-efed-48bf-b17d-a197141b2a92");
$physical_count->setCatalogObjectId("W62UWFY35CWMYGVWK6TWJDNI");
$physical_count->setState("IN_STOCK");
$physical_count->setLocationId("C6W5YS5QM06F5");
$physical_count->setQuantity("53");
$physical_count->setEmployeeId("LRK57NSQ5X7PUD05");
$physical_count->setOccurredAt("2016-11-16T22:25:24.878Z");
$change = new \SquareConnect\Model\InventoryChange();
$change->setType("PHYSICAL_COUNT");
$change->setPhysicalCount($physical_count);
$request = new \SquareConnect\Model\BatchChangeInventoryRequest();
$request->setIdempotencyKey(uniqid());
$request->setChanges(array($change));
$request->setIgnoreUnchangedCounts(TRUE);
$response = $api->batchChangeInventory($request);
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Create an InventoryChange consisting of a physical count.
const change = {
type: 'PHYSICAL_COUNT',
physical_count: {
reference_id: '1536bfbf-efed-48bf-b17d-a197141b2a92',
catalog_object_id: 'W62UWFY35CWMYGVWK6TWJDNI',
state: 'IN_STOCK',
location_id: 'C6W5YS5QM06F5',
quantity: '53',
employee_id: 'LRK57NSQ5X7PUD05'
}
};
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotencyKey,
changes: [change],
ignore_unchanged_counts: true
};
api.batchChangeInventory(body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Create an InventoryChange consisting of a physical count.
change = SquareConnect::InventoryChange.new(
type: SquareConnect::InventoryChangeType::PHYSICAL_COUNT,
physical_count: SquareConnect::InventoryPhysicalCount.new(
reference_id: '1536bfbf-efed-48bf-b17d-a197141b2a92',
catalog_object_id: 'W62UWFY35CWMYGVWK6TWJDNI',
state: SquareConnect::InventoryStatus::IN_STOCK,
location_id: 'C6W5YS5QM06F5',
quantity: '53',
employee_id: 'LRK57NSQ5X7PUD05'
)
)
response = api.batch_change_inventory(SquareConnect::BatchChangeInventoryRequest.new(
idempotency_key: SecureRandom.uuid(),
changes: [change],
ignore_unchanged_counts: true
))
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Create an InventoryChange consisting of a physical count.
InventoryChange change = new InventoryChange()
.type(InventoryChange.TypeEnum.PHYSICAL_COUNT)
.physicalCount(new InventoryPhysicalCount()
.referenceId("1536bfbf-efed-48bf-b17d-a197141b2a92")
.catalogObjectId("W62UWFY35CWMYGVWK6TWJDNI")
.state(InventoryPhysicalCount.StateEnum.IN_STOCK)
.locationId("C6W5YS5QM06F5")
.quantity("53")
.employeeId("LRK57NSQ5X7PUD05")
.occurredAt("2016-11-16T22:25:24.878Z"));
BatchChangeInventoryRequest request = new BatchChangeInventoryRequest()
.idempotencyKey(UUID.randomUUID().toString())
.changes(asList(change))
.ignoreUnchangedCounts(true);
BatchChangeInventoryResponse response = inventoryApi.batchChangeInventory(request);
Example Response
{
"errors": [
],
"counts": [
{
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"state": "IN_STOCK",
"location_id": "C6W5YS5QM06F5",
"quantity": "53",
"calculated_at": "2016-11-16T22:28:01.223Z"
}
]
}
POST /v2/inventory/batch-retrieve-changes
Returns historical physical counts and adjustments based on the provided filter criteria.
Results are paginated and sorted in ascending order according their occurred_at
timestamp (oldest first).
BatchRetrieveInventoryChanges is a catch-all query endpoint for queries that cannot be handled by other, simpler endpoints.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
catalog_object_ids
|
string[]
|
Filters results by CatalogObject ID. Only applied when set. Default: unset. |
location_ids
|
string[]
|
Filters results by Location ID. Only applied when set. Default: unset. |
types
|
string[]
|
Filters results by InventoryChangeType. Default: [ |
states
|
string[]
|
Filters |
updated_after
|
string
|
Provided as an RFC 3339 timestamp. Returns results whose |
updated_before
|
string
|
Provided as an RFC 3339 timestamp. Returns results whose |
cursor
|
string
|
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See Paginating results for more information. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
changes
|
InventoryChange[]
|
The current calculated inventory changes for the requested objects and locations. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
Example HTTP Request
POST /v2/inventory/batch-retrieve-changes
{ "catalog_object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI" ], "location_ids": [ "C6W5YS5QM06F5" ], "types": [ "PHYSICAL_COUNT" ], "states": [ "IN_STOCK" ], "updated_after": "2016-11-01T00:00:00.000Z", "updated_before": "2016-12-01T00:00:00.000Z" }
Example Request in Python
inventoryApi = InventoryApi()
# Request all physical counts for a variation at a location in a given time range.
request = BatchRetrieveInventoryChangesRequest()
request.catalogObjectIds = ['W62UWFY35CWMYGVWK6TWJDNI']
request.locationIds = ['C6W5YS5QM06F5']
request.types = ['PHYSICAL_COUNT']
request.updatedAfter = '2016-11-01T00:00:00.000Z'
request.updatedBefore = '2016-12-01T00:00:00.000Z'
request.cursor = None
# Save all changes to a List.
changes = []
while True:
response = inventoryApi.batchRetrieveInventoryChanges(request)
changes.extend(response.changes)
# When the response cursor is null or empty, the results are complete.
cursor = response.cursor
if cursor is None or len(cursor) == 0:
break
# Use the response cursor as the cursor for the subsequent request.
request.cursor = cursor
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request all physical counts for a variation at a location in a given time range.
BatchRetrieveInventoryChangesRequest request = new BatchRetrieveInventoryChangesRequest(
CatalogObjectIds: new List { "W62UWFY35CWMYGVWK6TWJDNI" },
LocationIds: new List { "C6W5YS5QM06F5" },
Types: new List { BatchRetrieveInventoryChangesRequest.TypesEnum.PHYSICALCOUNT },
UpdatedAfter: "2016-11-01T00:00:00.000Z",
UpdatedBefore: "2016-12-01T00:00:00.000Z",
Cursor: null);
// Save all changes to a List.
List changes = new List();
while (true)
{
BatchRetrieveInventoryChangesResponse response = inventoryApi.BatchRetrieveInventoryChanges(request);
changes.AddRange(response.Changes);
// When the response cursor is null or empty, the results are complete.
if (string.IsNullOrEmpty(response.Cursor))
{
break;
}
// Use the response cursor as the cursor for the subsequent request.
request.Cursor = response.Cursor;
}
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request all physical counts for a variation at a location in a given time range.
$request = new \SquareConnect\Model\BatchRetrieveInventoryChangesRequest();
$request->setCatalogObjectIds(array("W62UWFY35CWMYGVWK6TWJDNI"));
$request->setLocationIds(array("C6W5YS5QM06F5"));
$request->setTypes(array("PHYSICAL_COUNT"));
$request->setUpdatedAfter("2016-11-01T00:00:00.000Z");
$request->setUpdatedBefore("2016-12-01T00:00:00.000Z");
// Save all changes to a List.
$changes = array();
while (true) {
$response = $api->batchRetrieveInventoryChanges($request);
if ($response->getChanges() > 0) {
$changes = array_merge($changes, $response->getChanges());
}
// When the response cursor is not set or empty, the results are complete.
$cursor = $response->getCursor();
if (!isset($cursor) || $cursor === '') {
break;
}
// Use the response cursor as the cursor for the subsequent request.
request.setCursor(cursor);
}
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request all physical counts for a variation at a location in a given time range.
const baseRequest = {
catalog_object_ids: ['W62UWFY35CWMYGVWK6TWJDNI'],
location_ids: ['C6W5YS5QM06F5'],
types: ['PHYSICAL_COUNT'],
updated_after: '2016-11-01T00:00:00.000Z',
updated_before: '2016-12-01T00:00:00.000Z',
};
// Save all changes to an array.
function retrieveInventoryChanges(baseRequest, changes, cursor) {
// Create new request object off baseRequest with cursor as the input cursor
const request = Object.assign({}, baseRequest, { cursor: cursor });
api.batchRetrieveInventoryChanges(request)
.then((response) => {
if (response.changes) {
changes = changes.concat(response.changes);
}
// Use the response cursor as the cursor for the subsequent request.
// When the response cursor is null, the results are complete.
if (response.cursor) {
return retrieveInventoryChanges(baseRequest, changes, response.cursor);
}
return changes;
});
};
retrieveInventoryChanges(baseRequest, [])
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request all physical counts for a variation at a location in a given time range.
request = SquareConnect::BatchRetrieveInventoryChangesRequest.new(
catalog_object_ids: ['W62UWFY35CWMYGVWK6TWJDNI'],
location_ids: ['C6W5YS5QM06F5'],
types: [SquareConnect::InventoryChangeType::PHYSICAL_COUNT],
updated_after: '2016-11-01T00:00:00.000Z',
updated_before: '2016-12-01T00:00:00.000Z',
cursor: nil
)
# Save all changes to an array.
changes = []
loop do
response = api.batch_retrieve_inventory_changes(request)
changes.concat(response.changes) unless response.changes.nil?
# When the response cursor is nil, the results are complete.
break if response.cursor.nil?
# Use the response cursor as the cursor for the subsequent request.
request.cursor = response.cursor
end
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request all physical counts for a variation at a location in a given time range.
BatchRetrieveInventoryChangesRequest request = new BatchRetrieveInventoryChangesRequest()
.catalogObjectIds(asList("W62UWFY35CWMYGVWK6TWJDNI"))
.locationIds(asList("C6W5YS5QM06F5"))
.types(asList(BatchRetrieveInventoryChangesRequest.TypesEnum.PHYSICAL_COUNT))
.updatedAfter("2016-11-01T00:00:00.000Z")
.updatedBefore("2016-12-01T00:00:00.000Z")
.cursor(null);
// Save all changes to a List.
List changes = new ArrayList<>();
while (true) {
BatchRetrieveInventoryChangesResponse response = inventoryApi.batchRetrieveInventoryChanges(request);
changes.addAll(response.getChanges());
// When the response cursor is null or empty, the results are complete.
String cursor = response.getCursor();
if (cursor == null || cursor.length() == 0) {
break;
}
// Use the response cursor as the cursor for the subsequent request.
request.setCursor(cursor);
}
Example Response
{
"errors": [
],
"changes": [
{
"type": "PHYSICAL_COUNT",
"physical_count": {
"id": "46YDTW253DWGGK9HMAE6XCAO",
"reference_id": "22c07cf4-5626-4224-89f9-691112019399",
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"state": "IN_STOCK",
"location_id": "C6W5YS5QM06F5",
"quantity": "86",
"source": {
"product": "SQUARE_POS",
"application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
"name": "Square Point of Sale 4.37"
},
"employee_id": "LRK57NSQ5X7PUD05",
"occurred_at": "2016-11-16T22:24:49.028Z",
"created_at": "2016-11-16T22:25:24.878Z"
}
}
]
}
POST /v2/inventory/batch-retrieve-counts
Returns current counts for the provided CatalogObjects at the requested Locations.
Results are paginated and sorted in descending order according to their calculated_at
timestamp (newest first).
When updated_after
is specified, only counts that have changed since that time (based on the server timestamp for the
most recent change) are returned. This allows clients to perform a "sync" operation, for example in response to
receiving a Webhook notification.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
catalog_object_ids
|
string[]
|
Filters results by CatalogObject ID. Only applied when set. Default: unset. |
location_ids
|
string[]
|
Filters results by Location ID. Only applied when set. Default: unset. |
updated_after
|
string
|
Provided as an RFC 3339 timestamp. Returns results whose |
cursor
|
string
|
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See Paginating results for more information. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
counts
|
InventoryCount[]
|
The current calculated inventory counts for the requested objects and locations. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
Example HTTP Request
POST /v2/inventory/batch-retrieve-counts
{ "catalog_object_ids": [ "W62UWFY35CWMYGVWK6TWJDNI" ], "location_ids": [ "59TNP9SA8VGDA" ], "updated_after": "2016-11-16T00:00:00.000Z" }
Example Request in Python
inventoryApi = InventoryApi()
# Request recent counts for a variation at a location.
request = BatchRetrieveInventoryCountsRequest()
request.catalogObjectIds = ['W62UWFY35CWMYGVWK6TWJDNI']
request.locationIds = ['59TNP9SA8VGDA']
request.updatedAfter = '2016-11-16T00:00:00.000Z'
# Save all counts to a List.
counts = []
while True:
response = inventoryApi.batchRetrieveInventoryCounts(request)
counts.extend(response.counts)
# When the response cursor is null or empty, the results are complete.
cursor = response.cursor
if cursor is None or len(cursor) == 0:
break
# Use the response cursor as the cursor for the subsequent request.
request.cursor = cursor
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request recent counts for a variation at a location.
BatchRetrieveInventoryCountsRequest request = new BatchRetrieveInventoryCountsRequest(
CatalogObjectIds: new List{ "W62UWFY35CWMYGVWK6TWJDNI" },
LocationIds: new List{ "59TNP9SA8VGDA" },
UpdatedAfter: "2016-11-16T00:00:00.000Z");
// Save all counts to a List.
List counts = new List();
while (true)
{
BatchRetrieveInventoryCountsResponse response =
inventoryApi.batchRetrieveInventoryCounts(request);
counts.AddRange(response.Counts);
// When the response cursor is null or empty, the results are complete.
if (string.IsNullOrEmpty(response.Cursor))
{
break;
}
// Use the response cursor as the cursor for the subsequent request.
request.Cursor = response.Cursor;
}
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request recent counts for a variation at a location.
$request = new \SquareConnect\Model\BatchRetrieveInventoryCountsRequest();
$request->setCatalogObjectIds(array("W62UWFY35CWMYGVWK6TWJDNI"));
$request->setLocationIds(array("59TNP9SA8VGDA"));
$request->setUpdatedAfter("2016-11-16T00:00:00.000Z");
// Save all counts to an array.
$counts = array();
while (true) {
$response = $api->batchRetrieveInventoryCounts($request);
if (count($response->getCounts()) > 0) {
$counts = array_merge($counts, $response->getCounts());
}
// When the response cursor is not set or empty, the results are complete.
$cursor = $response->getCursor();
if (!isset($cursor) || $cursor === '') {
break;
}
// Use the response cursor as the cursor for the subsequent request.
$request->setCursor($cursor);
}
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request recent counts for a variation at a location.
const baseRequest = {
catalog_object_ids: ['W62UWFY35CWMYGVWK6TWJDNI'],
location_ids: ['59TNP9SA8VGDA'],
updated_after: '2016-11-16T00:00:00.000Z',
};
// Save all counts to an array.
function retrieveInventoryCounts(baseRequest, counts, cursor) {
// Create new request object off baseRequest with cursor as the input cursor
const request = Object.assign({}, baseRequest, { cursor: cursor });
api.batchRetrieveInventoryCount(request)
.then((response) => {
if (response.counts) {
counts = counts.concat(response.counts);
}
// Use the response cursor as the cursor for the subsequent request.
// When the response cursor is null, the results are complete.
if (response.cursor) {
return retrieveInventoryCounts(baseRequest, counts, response.cursor);
}
return counts;
});
};
retrieveInventoryCounts(baseRequest, [])
.then((request) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request recent counts for a variation at a location.
request = SquareConnect::BatchRetrieveInventoryCountsRequest.new(
catalog_object_ids: ['W62UWFY35CWMYGVWK6TWJDNI'],
location_ids: ['59TNP9SA8VGDA'],
updated_after: '2016-11-16T00:00:00.000Z',
cursor: nil
)
# Save all counts to an array.
counts = []
loop do
response = api.batch_retrieve_inventory_counts(request)
counts.concat(response.counts) unless response.counts.nil?
# When the response cursor is nil, the results are complete.
break if response.cursor.nil?
# Use the response cursor as the cursor for the subsequent request.
request.cursor = response.cursor
end
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request recent counts for a variation at a location.
BatchRetrieveInventoryCountsRequest request = new BatchRetrieveInventoryCountsRequest()
.catalogObjectIds(asList("W62UWFY35CWMYGVWK6TWJDNI"))
.locationIds(asList("59TNP9SA8VGDA"))
.updatedAfter("2016-11-16T00:00:00.000Z");
// Save all counts to a List.
List counts = new ArrayList<>();
while (true) {
BatchRetrieveInventoryCountsResponse response =
inventoryApi.batchRetrieveInventoryCounts(request);
counts.addAll(response.getCounts());
// When the response cursor is null or empty, the results are complete.
String cursor = response.getCursor();
if (cursor == null || cursor.length() == 0) {
break;
}
// Use the response cursor as the cursor for the subsequent request.
request.setCursor(cursor);
}
Example Response
{
"errors": [
],
"counts": [
{
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"state": "IN_STOCK",
"location_id": "59TNP9SA8VGDA",
"quantity": "79",
"calculated_at": "2016-11-16T22:28:01.223Z"
}
]
}
GET /v2/inventory/adjustment/{adjustment_id}
Returns the InventoryAdjustment object with the provided adjustment_id
.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
adjustment_id
(required) |
string
|
ID of the InventoryAdjustment to retrieve. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
adjustment
|
InventoryAdjustment
|
The requested InventoryAdjustment. |
Example HTTP Request
GET /v2/inventory/adjustment/{adjustment_id}
Example Request in Python
inventoryApi = InventoryApi()
# Request a given adjustment.
adjustmentId = 'UDMOEO78BG6GYWA2XDRYX3KB'
response = inventoryApi.retrieveInventoryAdjustment(adjustmentId)
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request a given adjustment.
String adjustmentId = "UDMOEO78BG6GYWA2XDRYX3KB";
RetrieveInventoryAdjustmentResponse response =
inventoryApi.RetrieveInventoryAdjustment(adjustmentId);
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request a given adjustment.
$adjustment_id = 'UDMOEO78BG6GYWA2XDRYX3KB';
$response = $api->retrieveInventoryAdjustment($adjustment_id);
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request a given adjustment.
const adjustmentId = 'UDMOEO78BG6GYWA2XDRYX3KB';
api.retrieveInventoryAdjustment(adjustmentId)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request a given adjustment.
adjustment_id = 'UDMOEO78BG6GYWA2XDRYX3KB'
response = api.retrieve_inventory_adjustment(adjustment_id)
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request a given adjustment.
String adjustmentId = "UDMOEO78BG6GYWA2XDRYX3KB";
RetrieveInventoryAdjustmentResponse response =
inventoryApi.retrieveInventoryAdjustment(adjustmentId);
Example Response
{
"errors": [
],
"adjustment": {
"id": "UDMOEO78BG6GYWA2XDRYX3KB",
"reference_id": "4a366069-4096-47a2-99a5-0084ac879509",
"from_state": "IN_STOCK",
"to_state": "SOLD",
"location_id": "C6W5YS5QM06F5",
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"quantity": "7",
"total_cost_money": {
"amount": 3500,
"currency": "USD"
},
"total_price_money": {
"amount": 4550,
"currency": "USD"
},
"occurred_at": "2016-11-16T25:44:22.837Z",
"created_at": "2016-11-17T13:02:15.142Z",
"source": {
"product": "SQUARE_POS",
"application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
"name": "Square Point of Sale 4.37"
},
"employee_id": "LRK57NSQ5X7PUD05"
}
}
GET /v2/inventory/{catalog_object_id}/changes
Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations.
Results are paginated and sorted in descending order according to their occurred_at
timestamp (newest first).
There are no limits on how far back the caller can page. This endpoint is useful when displaying recent changes for a specific item. For more sophisticated queries, use a batch endpoint.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
catalog_object_id
(required) |
string
|
ID of the CatalogObject to retrieve. |
Name | Type | Description |
---|---|---|
location_ids
|
string
|
The Location IDs to look up as a comma-separated list. An empty list queries all locations. |
cursor
|
string
|
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See Paginating results for more information. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
changes
|
InventoryChange[]
|
The set of inventory changes for the requested object and locations. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
Example HTTP Request
GET /v2/inventory/{catalog_object_id}/changes?location_ids=&cursor=
Example Request in Python
inventoryApi = InventoryApi()
# Request changes for a variation at a location.
itemVariationId = 'W62UWFY35CWMYGVWK6TWJDNI'
locationIds = 'C6W5YS5QM06F5'
# Save all changes to a List.
changes = []
cursor = None
while True:
response = inventoryApi.retrieveInventoryChanges(itemVariationId, locationIds, cursor)
changes.extend(response.changes)
# When the response cursor is null or empty, the results are complete.
cursor = response.cursor
if cursor is None or len(cursor) == 0:
break
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request changes for a variation at a location.
String itemVariationId = "W62UWFY35CWMYGVWK6TWJDNI";
String locationIds = "C6W5YS5QM06F5";
// Save all changes to a List.
List changes = new List();
String cursor = null;
while (true)
{
RetrieveInventoryChangesResponse response =
inventoryApi.RetrieveInventoryChanges(itemVariationId, locationIds, cursor);
changes.AddRange(response.Changes);
// When the response cursor is null or empty, the results are complete.
if (string.IsNullOrEmpty(response.Cursor))
{
break;
}
// Use the response cursor as the cursor for the subsequent request.
cursor = response.Cursor;
}
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request changes for a variation at a location.
$item_variation_id = "W62UWFY35CWMYGVWK6TWJDNI";
$location_id = "C6W5YS5QM06F5";
// Save all changes to an array.
$changes = array();
$cursor = "";
while (true) {
$response = $api->retrieveInventoryChanges($item_variation_id, $location_id, $cursor);
if (count($response->getChanges()) > 0) {
$changes = array_merge($changes, $response->getChanges());
}
// When the response cursor is not set or empty, the results are complete.
$cursor = $response->getCursor();
if (!isset($cursor) || $cursor === '') {
break;
}
}
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request changes for a variation at a location.
const itemVariationId = 'W62UWFY35CWMYGVWK6TWJDNI';
const locationId = 'C6W5YS5QM06F5';
const baseRequest = {
location_ids: [locationId]
};
// Save all changes to an array.
function retrieveInventoryChanges (baseRequest, changes, cursor) {
// Create new request object off baseRequest with cursor as the input cursor
const request = Object.assign({}, baseRequest, { cursor: cursor });
api.retrieveInventoryChanges(itemVariationId, opts)
.then((response) => {
if (response.changes) {
changes = changes.concat(response.changes);
}
// Use the response cursor as the cursor for the subsequent request.
// When the response cursor is null, the results are complete.
if (response.cursor) {
return retrieveInventoryChanges(baseRequest, changes, response.cursor);
}
return changes;
});
};
retrieveInventoryChanges(baseRequest, [])
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request changes for a variation at a location.
item_variation_id = 'W62UWFY35CWMYGVWK6TWJDNI'
location_id = 'C6W5YS5QM06F5'
# Save all changes to an array.
changes = []
opts = {
location_ids: [location_id],
cursor: nil
}
loop do
response = api.retrieve_inventory_changes(item_variation_id, opts)
changes.concat(response.changes) unless response.changes.nil?
# When the response cursor is nil, the results are complete.
break if response.cursor.nil?
# Use the response cursor as the cursor for the subsequent request.
opts[:cursor] = response.cursor
end
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request changes for a variation at a location.
String itemVariationId = "W62UWFY35CWMYGVWK6TWJDNI";
String locationIds = "C6W5YS5QM06F5";
// Save all changes to a List.
List changes = new ArrayList<>();
String cursor = null;
while (true) {
RetrieveInventoryChangesResponse response =
inventoryApi.retrieveInventoryChanges(itemVariationId, locationIds, cursor);
changes.addAll(response.getChanges());
// When the response cursor is null or empty, the results are complete.
cursor = response.getCursor();
if (cursor == null || cursor.length() == 0) {
break;
}
}
Example Response
{
"errors": [
],
"changes": [
{
"type": "ADJUSTMENT",
"adjustment": {
"id": "OJKJIUANKLMLQANZADNPLKAD",
"reference_id": "d8207693-168f-4b44-a2fd-a7ff533ddd26",
"from_state": "IN_STOCK",
"to_state": "SOLD",
"location_id": "C6W5YS5QM06F5",
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"quantity": "3",
"total_cost_money": {
"amount": 3000,
"currency": "USD"
},
"total_price_money": {
"amount": 5000,
"currency": "USD"
},
"occurred_at": "2016-11-16T22:25:24.878Z",
"created_at": "2016-11-16T22:25:24.878Z",
"source": {
"product": "SQUARE_POS",
"application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
"name": "Square Point of Sale 4.37"
},
"employee_id": "AV7YRCGI2H1J5NQ8E1XIZCNA",
"transaction_id": "5APV6JYK1SNCZD11AND2RX1Z"
}
}
]
}
GET /v2/inventory/{catalog_object_id}
Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
catalog_object_id
(required) |
string
|
ID of the CatalogObject to retrieve. |
Name | Type | Description |
---|---|---|
location_ids
|
string
|
The Location IDs to look up as a comma-separated list. An empty list queries all locations. |
cursor
|
string
|
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See Paginating results for more information. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
counts
|
InventoryCount[]
|
The current calculated inventory counts for the requested object and locations. |
cursor
|
string
|
The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Paginating results for more information. |
Example HTTP Request
GET /v2/inventory/{catalog_object_id}?location_ids=C6W5YS5QM06F5&cursor=
Example Request in Python
inventoryApi = InventoryApi()
# Request counts for a variation at a location.
catalogObjectId = 'W62UWFY35CWMYGVWK6TWJDNI'
locationIds = 'C6W5YS5QM06F5'
cursor = None
# Save all counts to a List.
counts = []
while True:
response = inventoryApi.retrieveInventoryCount(catalogObjectId, locationIds, cursor)
counts.addAll(response.counts)
# When the response cursor is null or empty, the results are complete.
cursor = response.cursor
if cursor is None or len(cursor) == 0:
break
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request counts for a variation at a location.
String catalogObjectId = "W62UWFY35CWMYGVWK6TWJDNI";
String locationIds = "C6W5YS5QM06F5";
// Save all counts to a List.
List counts = new List();
String cursor = null;
while (true)
{
RetrieveInventoryCountResponse response =
inventoryApi.RetrieveInventoryCount(catalogObjectId, locationIds, cursor);
counts.AddRange(response.Counts);
// When the response cursor is null or empty, the results are complete.
if (string.IsNullOrEmpty(response.Cursor))
{
break;
}
// Use the response cursor as the cursor for the subsequent request.
cursor = response.Cursor;
}
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request counts for a variation at a location.
$catalog_object_id = "W62UWFY35CWMYGVWK6TWJDNI";
$location_id = "C6W5YS5QM06F5";
// Save all counts to an array.
$counts = array();
$cursor = "";
while (true) {
$response = $api->retrieveInventoryCount($catalog_object_id, $location_id, $cursor);
if (count($response->getCounts()) > 0) {
$counts = array_merge($counts, $response->getCounts());
}
// When the response cursor is not set or empty, the results are complete.
$cursor = $response->getCursor();
if (!isset($cursor) || $cursor === '') {
break;
}
}
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request counts for a variation at a location.
const catalogObjectId = 'W62UWFY35CWMYGVWK6TWJDNI';
const locationId = 'C6W5YS5QM06F5';
const baseRequest = {
location_ids: [locationIid]
};
// Save all counts to a List.
function retrieveInventoryCount(baseRequest, counts, cursor) {
// Create new request object off baseRequest with cursor as the input cursor
const request = Object.assign({}, baseRequest, { cursor: cursor });
api.retrieveInventoryCount(catalogObjectId, opts)
.then((response) => {
if (response.counts) {
counts = counts.concat(response.counts);
}
// Use the response cursor as the cursor for the subsequent request.
// When the response cursor is null, the results are complete.
if (response.cursor) {
retrieveInventoryCount(baseRequest, counts, response.cursor);
}
return counts;
});
};
retrieveInventoryCount(baseRequest, [])
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request counts for a variation at a location.
catalog_object_id = 'W62UWFY35CWMYGVWK6TWJDNI'
location_id = 'C6W5YS5QM06F5'
# Save all counts to a List.
counts = []
opts = {
location_ids: [location_id],
cursor: nil
}
loop do
response = api.retrieve_inventory_count(catalog_object_id, opts)
counts.concat(response.counts) unless response.counts.nil?
# When the response cursor is nil, the results are complete.
break if response.cursor.nil?
# Use the response cursor as the cursor for the subsequent request.
opts[:cursor] = response.cursor
end
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request counts for a variation at a location.
String catalogObjectId = "W62UWFY35CWMYGVWK6TWJDNI";
String locationIds = "C6W5YS5QM06F5";
// Save all counts to a List.
List counts = new ArrayList<>();
String cursor = null;
while (true) {
RetrieveInventoryCountResponse response =
inventoryApi.retrieveInventoryCount(catalogObjectId, locationIds, cursor);
counts.addAll(response.getCounts());
// When the response cursor is null or empty, the results are complete.
cursor = response.getCursor();
if (cursor == null || cursor.length() == 0) {
break;
}
}
Example Response
{
"errors": [
],
"counts": [
{
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"state": "IN_STOCK",
"location_id": "C6W5YS5QM06F5",
"quantity": "22",
"calculated_at": "2016-11-16T22:28:01.223Z"
}
]
}
GET /v2/inventory/physical-count/{physical_count_id}
Returns the InventoryPhysicalCount object with the provided physical_count_id
.
Required permissions:
INVENTORY_READ
Name | Type | Description |
---|---|---|
physical_count_id
(required) |
string
|
ID of the InventoryPhysicalCount to retrieve. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
count
|
InventoryPhysicalCount
|
The requested InventoryPhysicalCount. |
Example HTTP Request
GET /v2/inventory/physical-count/{physical_count_id}
Example Request in Python
inventoryApi = InventoryApi()
# Request a given physical count.
physicalCountId = 'ANZADNPLKADOJKJIUANKLMLQ'
response = inventoryApi.retrieveInventoryPhysicalCount(physicalCountId)
Example Request in C#
InventoryApi inventoryApi = new InventoryApi();
// Request a given physical count.
String physicalCountId = "ANZADNPLKADOJKJIUANKLMLQ";
RetrieveInventoryPhysicalCountResponse response =
inventoryApi.RetrieveInventoryPhysicalCount(physicalCountId);
Example Request in PHP
$api = new \SquareConnect\Api\InventoryApi();
// Request a given physical count.
$physical_count_id = "ANZADNPLKADOJKJIUANKLMLQ";
$response = $api->retrieveInventoryPhysicalCount($physical_count_id);
Example Request in Node.js
const api = new SquareConnect.InventoryApi();
// Request a given physical count.
const physicalCountId = 'ANZADNPLKADOJKJIUANKLMLQ';
api.retrieve_inventory_physical_count(physicalCountId)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::InventoryApi.new
# Request a given physical count.
physical_count_id = 'ANZADNPLKADOJKJIUANKLMLQ'
response = api.retrieve_inventory_physical_count(physical_count_id)
Example Request in Java
InventoryApi inventoryApi = new InventoryApi();
// Request a given physical count.
String physicalCountId = "ANZADNPLKADOJKJIUANKLMLQ";
RetrieveInventoryPhysicalCountResponse response =
inventoryApi.retrieveInventoryPhysicalCount(physicalCountId);
Example Response
{
"errors": [
],
"count": {
"id": "ANZADNPLKADOJKJIUANKLMLQ",
"reference_id": "f857ec37-f9a0-4458-8e23-5b5e0bea4e53",
"catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
"catalog_object_type": "ITEM_VARIATION",
"state": "IN_STOCK",
"location_id": "C6W5YS5QM06F5",
"quantity": "15",
"source": {
"product": "SQUARE_POS",
"application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
"name": "Square Point of Sale 4.37"
},
"employee_id": "LRK57NSQ5X7PUD05",
"occurred_at": "2016-11-16T22:25:24.878Z",
"created_at": "2016-11-16T22:25:24.878Z"
}
}
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
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
locations
|
Location[]
|
The business's locations. |
Example HTTP Request
GET /v2/locations
Example Request in Python
api = squareconnect.apis.locations_api.LocationsApi()
api.list_locations()
Example Request in C#
LocationsApi api = new LocationsApi();
api.ListLocations();
Example Request in PHP
$api = new \SquareConnect\Api\LocationsApi();
$api->listLocations();
Example Request in Node.js
const api = new SquareConnect.LocationsApi();
api.listLocations()
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::LocationsApi.new
api.list_locations()
Example Request in Java
LocationsApi api = new LocationsApi();
api.listLocations();
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"
],
"status": "ACTIVE",
"created_at": "2016-09-19T17:33:12Z",
"merchant_id": "3MYCJG5GVYQ8Q",
"country": "US",
"language_code": "en-US",
"currency": "USD",
"phone_number": "+1 650-354-7217",
"business_name": "Pumbaa's business name"
}
]
}
POST /v2/locations/{location_id}/orders/batch-retrieve
Retrieves a set of Orders by their IDs.
If a given Order ID does not exist, the ID is ignored instead of generating an error.
Required permissions:
ORDERS_READ
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the orders' associated location. |
Name | Type | Description |
---|---|---|
order_ids
(required) |
string[]
|
The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. |
Name | Type | Description |
---|---|---|
orders
|
Order[]
|
The requested orders. This will omit any requested orders that do not exist or are not charged. |
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
POST /v2/locations/{location_id}/orders/batch-retrieve
{ "order_ids": [ "CAISEM82RcpmcFBM0TfOyiHV3es", "CAISENgvlJ6jLWAzERDzjyHVybY" ] }
Example Request in Python
api = squareconnect.apis.catalog_api.OrdersApi()
response = api.batch_retrieve_orders(BatchRetrieveOrdersRequest(
order_ids = [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]))
Example Request in C#
OrdersApi api = new OrdersApi();
BatchRetrieveOrdersResponse response = api.BatchRetrieveOrders(new BatchRetrieveOrdersRequest(
OrderIds: new List() {
"CAISEM82RcpmcFBM0TfOyiHV3es",
"CAISENgvlJ6jLWAzERDzjyHVybY"
}));
Example Request in PHP
$api = new \SquareConnect\Api\OrdersApi();
$apiResponse = $api->BatchRetrieveOrders([
"order_ids" => [
"CAISEM82RcpmcFBM0TfOyiHV3es",
"CAISENgvlJ6jLWAzERDzjyHVybY"
]
]);
Example Request in Node.js
const api = new SquareConnect.OrdersApi();
const body = {
order_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]
}
api.batchRetrieveOrders()
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::OrdersApi.new
response = api.batch_retrieve_orders(SquareConnect::BatchRetrieveOrdersRequest.new(
order_ids: [
'W62UWFY35CWMYGVWK6TWJDNI',
'AA27W3M2GGTF3H6AVPNB77CK'
]))
Example Request in Java
OrdersApi api = new OrdersApi();
BatchRetrieveOrdersResponse response = api.batchRetrieveOrders(new BatchRetrieveOrdersRequest()
.orderIds(asList(
"CAISEM82RcpmcFBM0TfOyiHV3es",
"CAISENgvlJ6jLWAzERDzjyHVybY")));
Example Response
{
"orders": [
{
"id": "CAISEM82RcpmcFBM0TfOyiHV3es",
"location_id": "LOCATION_ID",
"reference_id": "my-order-001",
"line_items": [
{
"id": "945986d1-9586-11e6-ad5a-28cfe92138cf",
"name": "Awesome product",
"quantity": "1",
"base_price_money": {
"amount": 1599,
"currency": "USD"
},
"total_money": {
"amount": 1599,
"currency": "USD"
}
},
{
"id": "a8f4168c-9586-11e6-bdf0-28cfe92138cf",
"name": "Another awesome product",
"quantity": "3",
"base_price_money": {
"amount": 2000,
"currency": "USD"
},
"total_money": {
"amount": 6000,
"currency": "USD"
}
}
],
"total_money": {
"amount": 7599,
"currency": "USD"
}
}
]
}
POST /v2/locations/{location_id}/orders
Creates an Order that can then be referenced as order_id
in a request to the Charge
endpoint. Orders specify products for purchase, along with discounts, taxes, and other settings to apply to the
purchase.
To associate a created order with a request to the Charge endpoint, provide the order's id
in the order_id
field of
your request.
You cannot modify an order after you create it. If you need to modify an order, instead create a new order with modified details.
To learn more about the Orders API, see the Orders API Overview.
Required permissions:
ORDERS_WRITE
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the business location to associate the order with. |
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. |
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
(required) |
CreateOrderRequestLineItem[]
|
The line items to associate with this order. Each line item represents a different product to include in a purchase. |
taxes
|
CreateOrderRequestTax[]
|
The taxes to include on the order. |
discounts
|
CreateOrderRequestDiscount[]
|
The discounts to include on the order. |
Name | Type | Description |
---|---|---|
order
|
Order
|
The newly created order. |
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
POST /v2/locations/{location_id}/orders
{ "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf", "reference_id": "my-order-001", "line_items": [ { "name": "New York Strip Steak", "quantity": "1", "base_price_money": { "amount": 1599, "currency": "USD" } }, { "quantity": "2", "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB", "modifiers": [ { "catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ" } ], "discounts": [ { "name": "Sale - $1.00 off", "amount_money": { "amount": 100, "currency": "USD" } } ] } ], "taxes": [ { "name": "State Sales Tax", "percentage": "9" } ], "discounts": [ { "name": "Labor Day Sale", "percentage": "5" }, { "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7" } ] }
Example Request in Python
api = OrdersApi()
response = api.create_order(location_id, CreateOrderRequest(
idempotency_key=str(uuid.uuid1()),
reference_id='my-order-001',
line_items=[
CreateOrderRequestLineItem(
name='New York Strip Steak',
quantity='1',
base_price_money=Money(amount=1599, currency='USD')
),
CreateOrderRequestLineItem(
catalog_object_id='BEMYCSMIJL46OCDV4KYIKXIB',
quantity='2',
modifiers=[
CreateOrderRequestModifier(
catalog_object_id='CHQX7Y4KY6N5KINJKZCFURPZ'
)
],
discounts=[
CreateOrderRequestDiscount(
name='Sale - $1.00 off',
amount_money=Money(amount=100, currency='USD')
)
]
)
],
taxes=[
CreateOrderRequestTax(
name='State Sales Tax',
percentage='9'
)
],
discounts=[
CreateOrderRequestDiscount(
name='Labor Day Sale',
percentage='5'
),
CreateOrderRequestDiscount(
catalog_object_id='DB7L55ZH2BGWI4H23ULIWOQ7'
)
]
))
response.order
Example Request in C#
OrdersApi api = new OrdersApi();
CreateOrderResponse response = api.CreateOrder(locationId, new CreateOrderRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
ReferenceId: "order-reference-id",
LineItems: new List()
{
new CreateOrderRequestLineItem(
Name: "New York Strip Steak",
Quantity: "1",
BasePriceMoney: new Money(Amount: 1599, Currency: Money.CurrencyEnum.USD)
),
new CreateOrderRequestLineItem(
Quantity: "2",
CatalogObjectId: "BEMYCSMIJL46OCDV4KYIKXIB",
Modifiers: new List()
{
new CreateOrderRequestModifier(CatalogObjectId: "CHQX7Y4KY6N5KINJKZCFURPZ")
},
Discounts: new List()
{
new CreateOrderRequestDiscount(
Name: "Sale - $1.00 off",
AmountMoney: new Money(Amount: 100, Currency: Money.CurrencyEnum.USD)
)
}
)
},
Taxes: new List()
{
new CreateOrderRequestTax(
Name: "State Sales Tax",
Percentage: "9"
)
},
Discounts: new List()
{
new CreateOrderRequestDiscount(
Name: "Labor Day Sale",
Percentage: "5"
),
new CreateOrderRequestDiscount(
CatalogObjectId: "DB7L55ZH2BGWI4H23ULIWOQ7"
)
}
));
Order order = response.Order;
Example Request in PHP
$api = new \SquareConnect\Api\OrdersApi();
$response = $api->createOrder($location_id, new \SquareConnect\Model\CreateOrderRequest([
"idempotency_key" => uniqid(),
"reference_id" => "some optional reference id",
"line_items" => [
[
"name" => "New York Strip Steak",
"quantity" => "1",
"base_price_money" => [
"amount" => 1599.0,
"currency" => "USD"
]
],
[
"catalog_object_id" => "BEMYCSMIJL46OCDV4KYIKXIB",
"quantity" => "2",
"modifiers" => [
[
"catalog_object_id" => "CHQX7Y4KY6N5KINJKZCFURPZ",
]
],
"discounts" => [
[
"name" => "Sale - $1.00 off",
"base_price_money" => [
"amount" => 100.0,
"currency" => "USD"
]
]
],
]
],
"taxes" => [
[
"name" => "State Sales Tax",
"percentage" => "9"
]
],
"discounts" => [
[
"name" => "Labor Day Sale",
"percentage" => "5"
],
[
"catalog_object_id" => "DB7L55ZH2BGWI4H23ULIWOQ7"
]
]
]);
$order = $response->getOrder();
Example Request in Node.js
const api = new SquareConnect.OrdersApi();
const idempotency_key = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotency_key,
reference_id: 'my-order-001',
line_items: [
{
name: 'New York Strip Steak',
quantity: '1',
base_price_money: {amount: 1599, currency: 'USD'}
},
{
catalog_object_id: 'BEMYCSMIJL46OCDV4KYIKXIB',
quantity: '2',
modifiers: [
{catalog_object_id: 'CHQX7Y4KY6N5KINJKZCFURPZ'}
],
discounts: [
{
name: 'Sale - $1.00 off',
amount_money: {amount: 100, currency: 'USD'}
}
]
}
],
taxes: [
{
name: 'State Sales Tax',
percentage: '9'
}
],
discounts: [
{
name: 'Labor Day Sale',
percentage: '5'
},
{
catalog_object_id: 'DB7L55ZH2BGWI4H23ULIWOQ7'
}
]
};
api.createOrder(location_id, body)
.then((response) => {
const order = response.order;
// Handle order object
});
Example Request in Ruby
api = SquareConnect::OrdersApi.new()
response = api.create_order(location_id, {
idempotency_key: SecureRandom.uuid,
reference_id: 'my-order-001',
line_items: [
{
name: 'New York Strip Steak',
quantity: '1',
base_price_money: {amount: 1599, currency: 'USD'}
},
{
catalog_object_id: 'BEMYCSMIJL46OCDV4KYIKXIB',
quantity: '2',
modifiers: [
{catalog_object_id: 'CHQX7Y4KY6N5KINJKZCFURPZ'}
],
discounts: [
{
name: 'Sale - $1.00 off',
amount_money: {amount: 100, currency: 'USD'}
}
]
}
],
taxes: [
{
name: 'State Sales Tax',
percentage: '9'
}
],
discounts: [
{
name: 'Labor Day Sale',
percentage: '5'
},
{
catalog_object_id: 'DB7L55ZH2BGWI4H23ULIWOQ7'
}
]
})
response.order
Example Request in Java
OrdersApi api = new OrdersApi();
CreateOrderResponse response = api.createOrder(locationId, new CreateOrderRequest()
.idempotencyKey(UUID.randomUUID().toString())
.referenceId("my-order-001")
.addLineItemsItem(new CreateOrderRequestLineItem()
.name("New York Strip Steak")
.quantity("1")
.basePriceMoney(new Money().amount(15_99L).currency(CurrencyEnum.USD)))
.addLineItemsItem(new CreateOrderRequestLineItem()
.catalogObjectId("BEMYCSMIJL46OCDV4KYIKXIB")
.quantity("2")
.addModifiersItem(new CreateOrderRequestModifier()
.catalogObjectId("CHQX7Y4KY6N5KINJKZCFURPZ"))
.addDiscountsItem(new CreateOrderRequestDiscount()
.name("Sale - $1.00 off")
.amountMoney(new Money().amount(1_00L).currency(CurrencyEnum.USD)))
)
.addTaxesItem(new CreateOrderRequestTax()
.name("State Sales Tax")
.percentage("9"))
.addDiscountsItem(new CreateOrderRequestDiscount()
.name("Labor Day Sale")
.percentage("5"))
.addDiscountsItem(new CreateOrderRequestDiscount()
.catalogObjectId("DB7L55ZH2BGWI4H23ULIWOQ7")));
Order order = response.getOrder();
Example Response
{
"order": {
"id": "CAISENgvlJ6jLWAzERDzjyHVybY",
"location_id": "LOCATION_ID",
"line_items": [
{
"name": "New York Strip Steak",
"quantity": "1",
"taxes": [
{
"name": "State Sales Tax",
"type": "ADDITIVE",
"percentage": "9",
"applied_money": {
"amount": 136,
"currency": "USD"
}
}
],
"discounts": [
{
"catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
"name": "Membership Discount",
"type": "FIXED_PERCENTAGE",
"percentage": "0.5",
"applied_money": {
"amount": 8,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "Labor Day Sale",
"type": "FIXED_PERCENTAGE",
"percentage": "5",
"applied_money": {
"amount": 79,
"currency": "USD"
},
"scope": "ORDER"
}
],
"base_price_money": {
"amount": 1599,
"currency": "USD"
},
"gross_sales_money": {
"amount": 1599,
"currency": "USD"
},
"total_tax_money": {
"amount": 136,
"currency": "USD"
},
"total_discount_money": {
"amount": 87,
"currency": "USD"
},
"total_money": {
"amount": 1648,
"currency": "USD"
}
},
{
"name": "New York Steak",
"quantity": "2",
"catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
"variation_name": "Larger",
"modifiers": [
{
"catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ",
"name": "Well",
"base_price_money": {
"amount": 50,
"currency": "USD"
},
"total_price_money": {
"amount": 100,
"currency": "USD"
}
}
],
"taxes": [
{
"name": "State Sales Tax",
"type": "ADDITIVE",
"percentage": "9",
"applied_money": {
"amount": 374,
"currency": "USD"
}
}
],
"discounts": [
{
"catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
"name": "Membership Discount",
"type": "FIXED_PERCENTAGE",
"percentage": "0.5",
"applied_money": {
"amount": 22,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "Labor Day Sale",
"type": "FIXED_PERCENTAGE",
"percentage": "5",
"applied_money": {
"amount": 224,
"currency": "USD"
},
"scope": "ORDER"
},
{
"name": "Sale - $1.00 off",
"type": "FIXED_AMOUNT",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"applied_money": {
"amount": 100,
"currency": "USD"
},
"scope": "LINE_ITEM"
}
],
"base_price_money": {
"amount": 2200,
"currency": "USD"
},
"gross_sales_money": {
"amount": 4500,
"currency": "USD"
},
"total_tax_money": {
"amount": 374,
"currency": "USD"
},
"total_discount_money": {
"amount": 346,
"currency": "USD"
},
"total_money": {
"amount": 4528,
"currency": "USD"
}
}
],
"total_money": {
"amount": 6176,
"currency": "USD"
},
"total_tax_money": {
"amount": 510,
"currency": "USD"
},
"total_discount_money": {
"amount": 433,
"currency": "USD"
}
}
}
GET /v2/locations/{location_id}/additional-recipient-receivable-refunds
Returns a list of refunded transactions (across all possible originating locations) relating to monies credited to the
provided location ID by another Square account using the additional_recipients
field in a transaction.
Max results per page: 50
Required permissions:
PAYMENTS_READ
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the location to list AdditionalRecipientReceivableRefunds for. |
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 ( Default value: |
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. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
receivable_refunds
|
AdditionalRecipientReceivableRefund[]
|
An array of AdditionalRecipientReceivableRefunds that match your query. |
cursor
|
string
|
A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the See Paginating results for more information. |
Example HTTP Request
GET /v2/locations/{location_id}/additional-recipient-receivable-refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z
Example Request in Python
api = squareconnect.apis.reporting_api.ReportingApi()
api.list_additional_recipient_receivable_refunds(LOCATION_ID,
begin_time='2016-01-15T00:00:00Z',
end_time='2016-01-30T00:00:00Z')
Example Request in C#
ReportingApi api = new ReportingApi();
api.ListAdditionalRecipientReceivableRefunds(LOCATION_ID,
beginTime: "2016-01-15T00:00:00Z",
endTime: "2016-01-31T00:00:00Z");
Example Request in PHP
$api = new \SquareConnect\Api\ReportingApi();
$api->listAdditionalRecipientReceivableRefunds($LOCATION_ID,
'2016-01-15T00:00:00Z', '2016-01-31T00:00:00Z');
Example Request in Node.js
const api = new SquareConnect.ReportingApi();
const body = {
begin_time: Date.parse('2016-01-15 00:00:00 UTC'),
end_time: Date.parse('2016-01-30 00:00:00 UTC')
};
api.listAdditionalRecipientReceivableRefunds(LOCATION_ID, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::ReportingApi.new
api.list_additional_recipient_receivable_refunds(LOCATION_ID, {
begin_time: DateTime.parse('2016-01-15 00:00:00 UTC'),
end_time: DateTime.parse('2016-01-30 00:00:00 UTC')
})
Example Request in Java
ReportingApi api = new ReportingApi();
String beginTime = "2016-01-15T00:00:00Z";
String endTime = "2016-01-30T00:00:00Z";
api.listAdditionalRecipientReceivableRefunds(locationId, beginTime, endTime, sortOrder, cursor);
Example Response
{
"receivable_refunds": [
{
"id": "Ge2OT7KA6XAg1GC15qs5S",
"receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
"refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
"transaction_location_id": "18YC4JDH91E1H",
"amount_money": {
"amount": 10,
"currency": "USD"
},
"created_at": "2016-01-20T22:57:56Z"
}
]
}
GET /v2/locations/{location_id}/additional-recipient-receivables
Returns a list of receivables (across all possible sending locations) representing monies credited to the provided
location ID by another Square account using the additional_recipients
field in a transaction.
Max results per page: 50
Required permissions:
PAYMENTS_READ
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the location to list AdditionalRecipientReceivables for. |
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 ( Default value: |
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. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
receivables
|
AdditionalRecipientReceivable[]
|
An array of AdditionalRecipientReceivables that match your query. |
cursor
|
string
|
A pagination cursor for retrieving the next set of results, if any remain. Provide this value as the See Paginating results for more information. |
Example HTTP Request
GET /v2/locations/{location_id}/additional-recipient-receivables?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z
Example Request in Python
api = squareconnect.apis.reporting_api.ReportingApi()
api.list_additional_recipient_receivables(LOCATION_ID,
begin_time='2016-01-15T00:00:00Z',
end_time='2016-01-30T00:00:00Z')
Example Request in C#
ReportingApi api = new ReportingApi();
api.ListAdditionalRecipientReceivables(LOCATION_ID,
beginTime: "2016-01-15T00:00:00Z",
endTime: "2016-01-31T00:00:00Z");
Example Request in PHP
$api = new \SquareConnect\Api\ReportingApi();
$api->listAdditionalRecipientReceivables($LOCATION_ID,
'2016-01-15T00:00:00Z', '2016-01-31T00:00:00Z');
Example Request in Node.js
const api = new SquareConnect.ReportingApi();
const body = {
begin_time: Date.parse('2016-01-15 00:00:00 UTC'),
end_time: Date.parse('2016-01-30 00:00:00 UTC')
};
api.listAdditionalRecipientReceivables(LOCATION_ID, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::ReportingApi.new
api.list_additional_recipient_receivables(LOCATION_ID, {
begin_time: DateTime.parse('2016-01-15 00:00:00 UTC'),
end_time: DateTime.parse('2016-01-30 00:00:00 UTC')
})
Example Request in Java
ReportingApi api = new ReportingApi();
String beginTime = "2016-01-15T00:00:00Z";
String endTime = "2016-01-30T00:00:00Z";
api.listAdditionalRecipientReceivables(locationId, beginTime, endTime, sortOrder, cursor);
Example Response
{
"receivables": [
{
"id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"transaction_location_id": "18YC4JDH91E1H",
"amount_money": {
"amount": 20,
"currency": "USD"
},
"created_at": "2016-01-19T15:12:41Z",
"refunds": [
{
"id": "Ge2OT7KA6XAg1GC15qs5S",
"receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF",
"refund_id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
"transaction_location_id": "18YC4JDH91E1H",
"amount_money": {
"amount": 10,
"currency": "USD"
},
"created_at": "2016-01-20T22:57:56Z"
}
]
}
]
}
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
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
|
transaction_id
(required) |
string
|
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
POST /v2/locations/{location_id}/transactions/{transaction_id}/capture
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
api.capture_transaction(LOCATION_ID, transaction.id)
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.CaptureTransaction(LOCATION_ID, transaction.Id);
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$api->captureTransaction($LOCATION_ID, $transaction->getId());
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
api.captureTransaction(LOCATION_ID, transaction.id)
.then((response) => {});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
api.capture_transaction(LOCATION_ID, transaction.id)
Example Request in Java
TransactionsApi api = new TransactionsApi();
api.CaptureTransaction(LOCATION_ID, transaction.Id);
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:
card_nonce
parameter (to charge a card nonce generated with the SqPaymentForm
)customer_card_id
and customer_id
parameters (to charge a customer's card on file)In order for an eCommerce payment to potentially qualify for Square chargeback protection, you must provide values for the following parameters in your request:
buyer_email_address
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
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the location to associate the created transaction with. |
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 |
card_nonce
|
string
|
A nonce generated from the The application that provides a nonce to this endpoint must be the same application that generated the nonce with the
Do not provide a value for this field if you provide a value for |
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
If you provide this value, you must also provide a value for |
delay_capture
|
boolean
|
If Default value: |
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
|
|
customer_id
|
string
|
The ID of the customer to associate this transaction with. This field is required if you provide a value for
|
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
|
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 |
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. |
order_id
|
string
|
The ID of the order to associate with this transaction. If you provide this value, the |
additional_recipients
|
AdditionalRecipient[]
|
The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the This field requires the This field is currently not supported in sandbox. |
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": 200, "currency": "USD" }, "additional_recipients": [ { "location_id": "057P5VYJ4A5X1", "description": "Application fees", "amount_money": { "amount": 20, "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 Python
api = squareconnect.apis.transactions_api.TransactionsApi()
idempotency_key = str(uuid.uuid1())
api.charge(LOCATION_ID, ChargeRequest(
idempotency_key=idempotency_key,
amount_money=Money(200, 'USD'),
card_nonce=card_nonce,
shipping_address=Address(
address_line_1='123 Main St',
locality='San Francisco',
administrative_district_level_1='CA',
postal_code='94114',
country='US'
),
billing_address=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'
),
additional_recipients=[
ChargeRequestAdditionalRecipient(
location_id='057P5VYJ4A5X1',
description='Application fees',
amount_money=Money(20, 'USD')
)
],
reference_id='optional reference #112358',
note='optional note'
))
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.Charge(LOCATION_ID, new ChargeRequest(
AmountMoney: new Money(200, Money.ToCurrencyEnum("USD")),
IdempotencyKey: Guid.NewGuid().ToString(),
CardNonce: card_nonce,
ShippingAddress: new Address(
AddressLine1: "123 Main St",
Locality: "San Francisco",
AdministrativeDistrictLevel1: "CA",
PostalCode: "94114",
Country: Address.ToCountryEnum("US")),
BillingAddress: new Address(
AddressLine1: "500 Electric Ave",
AddressLine2: "Suite 600",
Locality: "New York",
AdministrativeDistrictLevel1: "NY",
PostalCode: "20003",
Country: Address.ToCountryEnum("US")),
AdditionalRecipients: new List(){
new ChargeRequestAdditionalRecipient(
LocationId: "057P5VYJ4A5X1",
Description: "Application fees",
AmountMoney: new Money(20, Money.ToCurrencyEnum("USD"))
)
},
ReferenceId: "optional reference #112358",
Note: "optional note"
));
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$idempotencyKey = uniqid();
$api->charge($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'
),
'additional_recipients' => array(
array(
'location_id' => '057P5VYJ4A5X1',
'description' => 'Application fees',
'amount_money' => array(
'amount' => 20, 'currency' => 'USD'
)
)
),
'reference_id' => 'optional reference #112358',
'note' => 'optional note'
));
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
idempotency_key: idempotencyKey,
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'
},
additional_recipients: [
{
location_id: '057P5VYJ4A5X1',
description: 'Application fees',
amount_money: {
amount: 20, currency: 'USD'
}
}
],
reference_id: 'optional reference #112358',
note: 'optional note'
};
api.charge(LOCATION_ID, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
idempotency_key = SecureRandom.uuid
api.charge(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'
},
additional_recipients: [
{
location_id: '057P5VYJ4A5X1',
description: 'Application fees',
amount_money: {
amount: 20, currency: 'USD'
}
}
],
reference_id: 'optional reference #112358',
note: 'optional note'
})
Example Request in Java
TransactionsApi api = new TransactionsApi();
ChargeRequest body = new ChargeRequest()
.idempotencyKey(UUID.randomUUID().toString())
.amountMoney(new Money()
.amount(200L)
.currency(Money.CurrencyEnum.USD))
.cardNonce(cardNonce)
.shippingAddress(new Address()
.addressLine1("123 Main St")
.locality("San Francisco")
.administrativeDistrictLevel1("CA")
.postalCode("94114")
.country(Address.CountryEnum.US))
.billingAddress(new Address()
.addressLine1("500 Electric Ave")
.addressLine2("Suite 600")
.administrativeDistrictLevel1("NY")
.locality("New York")
.postalCode("10003")
.country(Address.CountryEnum.US))
.addAdditionalRecipientsItem(new ChargeRequestAdditionalRecipient()
.locationId("057P5VYJ4A5X1")
.description("Application fees")
.amountMoney(new Money()
.amount(20L)
.currency(Money.CurrencyEnum.USD)))
.referenceId("optional reference #112358")
.note("optional note");
ChargeResponse response = api.charge(locationId, body);
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": 200,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 20,
"currency": "USD"
},
"receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
}
],
"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"
}
}
POST /v2/locations/{location_id}/transactions/{transaction_id}/refund
Initiates a refund for a previously charged tender.
You must issue a refund within 120 days of the associated payment. See this article for more information on refund behavior.
NOTE: Card-present transactions with Interac credit cards cannot be refunded using the Connect API. Interac transactions must refunded in-person (e.g., dipping the card using POS app).
Required permissions:
PAYMENTS_WRITE
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. |
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 |
reason
|
string
|
A description of the reason for the refund. Default value: |
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 |
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": "86ae1696-b1e3-4328-af6d-f1e04d947ad2", "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF", "reason": "a reason", "amount_money": { "amount": 100, "currency": "USD" } }
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
idempotency_key = str(uuid.uuid1())
api.create_refund(LOCATION_ID, transaction.id, CreateRefundRequest(
tender_id=transaction.tenders[0].id,
amount_money=Money(100, 'USD')
idempotency_key=idempotency_key,
reason='Cancelled order'
))
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.CreateRefund(LOCATION_ID, transaction.Id, new CreateRefundRequest(
IdempotencyKey: Guid.NewGuid().ToString(),
TenderId: transaction.Tenders[0].Id,
AmountMoney: new Money(100, Money.ToCurrencyEnum("USD")),
Reason: "Cancelled order"
));
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$idempotencyKey = uniqid();
$api->createRefund($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 Node.js
const api = new SquareConnect.TransactionsApi();
const idempotencyKey = require('crypto').randomBytes(32).toString('hex');
const body = {
tender_id: transaction.tenders.first.id,
amount_money: {
amount: 100,
currency: 'USD'
},
idempotency_key: idempotencyKey,
reason: 'Cancelled order'
};
api.createRefund(LOCATION_ID, transaction.id, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
idempotency_key = SecureRandom.uuid
api.create_refund(LOCATION_ID, transaction.id, {
tender_id: transaction.tenders.first.id,
amount_money: {
amount: 100,
currency: 'USD'
},
idempotency_key: idempotency_key,
reason: 'Cancelled order'
})
Example Request in Java
TransactionsApi api = new TransactionsApi();
CreateRefundResponse response = api.createRefund(locationId, transaction.getId(), new CreateRefundRequest()
.idempotencyKey(UUID.randomUUID().toString())
.tenderId(transaction.getTenders().get(0).getId())
.amountMoney(new Money()
.amount(100L)
.currency(Money.CurrencyEnum.USD))
.reason("Cancelled order"));
Example Response
{
"refund": {
"id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
"location_id": "18YC4JDH91E1H",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
"created_at": "2016-02-12T00:28:18Z",
"reason": "some reason",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 10,
"currency": "USD"
},
"receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
}
],
"status": "PENDING"
}
}
GET /v2/locations/{location_id}/refunds
Lists refunds for one of a business's locations.
In addition to full or partial tender refunds processed through Square APIs, refunds may result from itemized returns or exchanges through Square's Point of Sale applications.
Refunds with a status
of PENDING
are not currently included in this endpoint's response.
Max results per page: 50
Required permissions:
PAYMENTS_READ
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the location to list refunds for. |
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 ( Default value: |
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. |
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 See Paginating results for more information. |
Example HTTP Request
GET /v2/locations/{location_id}/refunds?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
api.list_refunds(LOCATION_ID,
begin_time='2016-08-10T21:35:15Z',
end_time='2016-08-10T23:40:00Z')
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.ListRefunds(LOCATION_ID,
beginTime: "2016-08-10T21:35:00Z",
endTime: "2016-08-10T21:35:15Z");
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$api->listRefunds($LOCATION_ID,
'2016-08-10T21:35:15Z', '2016-08-10T23:40:00Z');
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
const body = {
begin_time: Date.parse('2016-08-10 21:35:15 UTC'),
end_time: Date.parse('2016-08-10 23:40:00 UTC')
};
api.listRefunds(LOCATION_ID, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
api.list_refunds(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 Request in Java
TransactionsApi api = new TransactionsApi();
String beginTime = "2016-08-10T21:35:00Z";
String endTime = "2016-08-10T21:35:15Z";
ListRefundsResponse response = api.listRefunds(locationId, beginTime, endTime, sortOrder, cursor);
Example Response
{
"refunds": [
{
"id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
"location_id": "18YC4JDH91E1H",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
"created_at": "2016-01-20T00:28:18Z",
"reason": "some reason",
"amount_money": {
"amount": 100,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 10,
"currency": "USD"
}
}
],
"status": "APPROVED"
}
]
}
GET /v2/locations/{location_id}/transactions
Lists transactions for a particular location.
Transactions include payment information from sales and exchanges and refund information from returns and exchanges.
Max results per page: 50
Required permissions:
PAYMENTS_READ
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
The ID of the location to list transactions for. |
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 ( Default value: |
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. |
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 See Paginating results for more information. |
Example HTTP Request
GET /v2/locations/{location_id}/transactions?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
api.list_transactions(LOCATION_ID,
begin_time='2016-08-10T21:35:00Z',
end_time='2016-08-10T21:35:15Z')
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.ListTransactions(LOCATION_ID,
beginTime: "2016-08-10T21:35:00Z",
endTime: "2016-08-10T21:35:15Z");
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$api->listTransactions($LOCATION_ID,
'2016-08-10T21:35:00Z', '2016-08-10T21:35:15Z');
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
const body = {
begin_time: Date.parse('2016-08-10 21:35:00 UTC'),
end_time: Date.parse('2016-08-10 21:35:15 UTC')
};
api.listTransactions(LOCATION_ID, body)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
api.list_transactions(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 Request in Java
TransactionsApi api = new TransactionsApi();
String beginTime = "2016-08-10T21:35:00Z";
String endTime = "2016-08-10T21:35:15Z";
ListTransactionsResponse response = api.listTransactions(locationId, beginTime, endTime, sortOrder, cursor);
Example Response
{
"transactions": [
{
"id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"location_id": "18YC4JDH91E1H",
"created_at": "2016-01-20T22:57:56Z",
"tenders": [
{
"id": "MtZRYYdDrYNQbOvV7nbuBvMF",
"location_id": "18YC4JDH91E1H",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"created_at": "2016-01-20T22: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"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 20,
"currency": "USD"
}
}
]
}
],
"refunds": [
{
"id": "7a5RcVI0CxbOcJ2wMOkE",
"location_id": "18YC4JDH91E1H",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
"created_at": "2016-01-20T22:59:20Z",
"reason": "some reason why",
"amount_money": {
"amount": 5000,
"currency": "USD"
},
"status": "APPROVED",
"processing_fee_money": {
"amount": 138,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
],
"reference_id": "some optional reference id",
"product": "EXTERNAL_API"
}
]
}
GET /v2/locations/{location_id}/transactions/{transaction_id}
Retrieves details for a single transaction.
Required permissions:
PAYMENTS_READ
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. |
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
transaction
|
Transaction
|
The requested transaction. |
Example HTTP Request
GET /v2/locations/{location_id}/transactions/{transaction_id}
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
api.retrieve_transaction(LOCATION_ID, transaction.id)
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.RetrieveTransaction(LOCATION_ID, transaction.Id);
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$api->retrieveTransaction($LOCATION_ID, $transaction->getId());
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
api.retrieveTransaction(LOCATION_ID, transaction.id)
.then((response) => {
// Handle response
});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
api.retrieve_transaction(LOCATION_ID, transaction.id)
Example Request in Java
TransactionsApi api = new TransactionsApi();
api.retrieveTransaction(LOCATION_ID, transaction.getId())
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"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 20,
"currency": "USD"
}
}
]
}
],
"reference_id": "some optional reference id",
"product": "EXTERNAL_API"
}
}
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
Name | Type | Description |
---|---|---|
location_id
(required) |
string
|
|
transaction_id
(required) |
string
|
Name | Type | Description |
---|---|---|
errors
|
Error[]
|
Any errors that occurred during the request. |
Example HTTP Request
POST /v2/locations/{location_id}/transactions/{transaction_id}/void
Example Request in Python
api = squareconnect.apis.transactions_api.TransactionsApi()
api.void_transaction(LOCATION_ID, transaction.id)
Example Request in C#
TransactionsApi api = new TransactionsApi();
api.VoidTransaction(LOCATION_ID, transaction.Id);
Example Request in PHP
$api = new \SquareConnect\Api\TransactionsApi();
$api->voidTransaction($LOCATION_ID, $transaction->getId());
Example Request in Node.js
const api = new SquareConnect.TransactionsApi();
api.voidTransaction(LOCATION_ID, transaction.id)
.then((response) => {});
Example Request in Ruby
api = SquareConnect::TransactionsApi.new
api.void_transaction(LOCATION_ID, transaction.id)
Example Request in Java
TransactionsApi api = new TransactionsApi();
api.voidTransaction(LOCATION_ID, transaction.getId());
AdditionalRecipient
Represents an additional recipient (other than the merchant) receiving a portion of this tender.
Name | Type | Description |
---|---|---|
location_id
|
string
|
The location ID for a recipient (other than the merchant) receiving a portion of this tender. |
description
|
string
|
The description of the additional recipient. |
amount_money
|
Money
|
The amount of money distributed to the recipient. |
receivable_id
|
string
|
The unique ID for this AdditionalRecipientReceivable, assigned by the server. |
AdditionalRecipientReceivable
Represents a monetary distribution of part of a Transaction's amount for Transactions which included additional recipients. The location of this receivable is that same as the one specified in the AdditionalRecipient.
Name | Type | Description |
---|---|---|
id
|
string
|
The additional recipient receivable's unique ID, issued by Square payments servers. |
transaction_id
|
string
|
The ID of the transaction that the additional recipient receivable was applied to. |
transaction_location_id
|
string
|
The ID of the location that created the receivable. This is the location ID on the associated transaction. |
amount_money
|
Money
|
The amount of the receivable. This will always be non-negative. |
created_at
|
string
|
The time when the additional recipient receivable was created, in RFC 3339 format. |
refunds
|
AdditionalRecipientReceivableRefund[]
|
Any refunds of the receivable that have been applied. |
AdditionalRecipientReceivableRefund
A refund of an AdditionalRecipientReceivable. This includes the ID of the additional recipient receivable associated to this object, as well as a reference to the Refund that created this receivable refund.
Name | Type | Description |
---|---|---|
id
|
string
|
The receivable refund's unique ID, issued by Square payments servers. |
receivable_id
|
string
|
The ID of the receivable that the refund was applied to. |
refund_id
|
string
|
The ID of the refund that is associated to this receivable refund. |
transaction_location_id
|
string
|
The ID of the location that created the receivable. This is the location ID on the associated transaction. |
amount_money
|
Money
|
The amount of the refund. This will always be non-negative. |
created_at
|
string
|
The time when the refund was created, in RFC 3339 format. |
Address
Represents a physical address.
Name | Type | Description |
---|---|---|
address_line_1
|
string
|
The first line of the address. Fields that start with |
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 |
sublocality_2
|
string
|
A civil region within the address's |
sublocality_3
|
string
|
A civil region within the address's |
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_3
|
string
|
A civil entity within the address's |
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 payment details of a card to be used for payments. These details are determined by the card_nonce
generated by SqPaymentForm
.
Name | Type | Description |
---|---|---|
id
|
string
|
Unique ID for this card. Generated by Square. |
card_brand
|
string
|
The card's brand (such as |
last_4
|
string
|
The last 4 digits of the card number. |
exp_month
|
integer
|
The expiration month of the associated card as an integer between 1 and 12. |
exp_year
|
integer
|
The four-digit year of the card's expiration date. |
cardholder_name
|
string
|
The name of the cardholder. |
billing_address
|
Address
|
The billing address for this card. |
fingerprint
|
string
|
Not currently set. Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application. |
CatalogCategory
A category to which an CatalogItem belongs in the Catalog object model.
Name | Type | Description |
---|---|---|
name
|
string
|
The category's name. Searchable. |
CatalogCategory Example
{
"object": {
"type": "CATEGORY",
"id": "#Beverages",
"present_at_all_locations": true,
"category_data": {
"name": "Beverages"
}
}
}
CatalogDiscount
A discount in the Catalog object model.
Name | Type | Description |
---|---|---|
name
|
string
|
The discount's name. Searchable. |
discount_type
|
string
|
Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale. See CatalogDiscountType for all possible values. |
percentage
|
string
|
The percentage of the discount as a string representation of a decimal number, using a Do not include this field for amount-based or variable discounts. |
amount_money
|
Money
|
The amount of the discount. Specify an amount of Do not include this field for percentage-based or variable discounts. |
pin_required
|
boolean
|
Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app. |
label_color
|
string
|
The color of the discount's display label in the Square Point of Sale app. |
CatalogDiscount Example
{
"object": {
"type": "DISCOUNT",
"id": "#Maythe4th",
"present_at_all_locations": true,
"discount_data": {
"name": "Welcome to the Dark(Roast) Side!",
"discount_type": "FIXED_PERCENTAGE",
"percentage": "5.4",
"pin_required": false,
"label_color": "red"
}
}
}
CatalogIdMapping
A mapping between a client-supplied temporary ID and a permanent server ID.
Name | Type | Description |
---|---|---|
client_object_id
|
string
|
The client-supplied, temporary |
object_id
|
string
|
The permanent ID for the CatalogObject created by the server. |
CatalogInfoResponseLimits
Name | Type | Description |
---|---|---|
batch_upsert_max_objects_per_batch
|
integer
|
The maximum number of objects that may appear within a single batch in a |
batch_upsert_max_total_objects
|
integer
|
The maximum number of objects that may appear across all batches in a |
batch_retrieve_max_object_ids
|
integer
|
The maximum number of object IDs that may appear in a |
search_max_page_limit
|
integer
|
The maximum number of results that may be returned in a page of a |
batch_delete_max_object_ids
|
integer
|
The maximum number of object IDs that may be included in a single |
update_item_taxes_max_item_ids
|
integer
|
The maximum number of item IDs that may be included in a single |
update_item_taxes_max_taxes_to_enable
|
integer
|
The maximum number of tax IDs to be enabled that may be included in a single |
update_item_taxes_max_taxes_to_disable
|
integer
|
The maximum number of tax IDs to be disabled that may be included in a single |
update_item_modifier_lists_max_item_ids
|
integer
|
The maximum number of item IDs that may be included in a single |
update_item_modifier_lists_max_modifier_lists_to_enable
|
integer
|
The maximum number of modifier list IDs to be enabled that may be included in a single
|
update_item_modifier_lists_max_modifier_lists_to_disable
|
integer
|
The maximum number of modifier list IDs to be disabled that may be included in a single
|
CatalogItem
An item (i.e., product family) in the Catalog object model.
Name | Type | Description |
---|---|---|
name
|
string
|
The item's name. Searchable. |
description
|
string
|
The item's description. Searchable. |
abbreviation
|
string
|
The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. Searchable. |
label_color
|
string
|
The color of the item's display label in the Square Point of Sale app. |
available_online
|
boolean
|
If |
available_for_pickup
|
boolean
|
If |
available_electronically
|
boolean
|
If |
category_id
|
string
|
The ID of the item's category, if any. |
tax_ids
|
string[]
|
A set of IDs indicating the CatalogTaxes that are enabled for this item. When updating an item, any
taxes listed here will be added to the item. CatalogTaxes may also be added to or deleted from an
item using |
modifier_list_info
|
CatalogItemModifierListInfo[]
|
A set of CatalogItemModifierListInfo objects representing the modifier lists that
apply to this item, along with the overrides and min and max limits that are specific to this item.
CatalogModifierLists may also be added to or deleted from an item using
|
image_url
|
string
|
The URL of an image representing this item. |
variations
|
CatalogObject[]
|
A list of CatalogObjects containing the CatalogItemVariations for this item. |
product_type
|
string
|
The product type of the item. May not be changed once an item has been created. Only items of product type |
skip_modifier_screen
|
boolean
|
If If Third-party clients are encouraged to implement similar behaviors. |
CatalogItem Example
{
"object": {
"type": "ITEM",
"id": "#Cocoa",
"present_at_all_locations": true,
"item_data": {
"name": "Cocoa",
"description": "Hot chocolate",
"abbreviation": "Ch",
"visibility": "PRIVATE"
}
}
}
CatalogItemModifierListInfo
Controls the properties of a CatalogModifierList as it applies to this CatalogItem.
Name | Type | Description |
---|---|---|
modifier_list_id
|
string
|
The ID of the CatalogModifierList controlled by this CatalogModifierListInfo. |
modifier_overrides
|
CatalogModifierOverride[]
|
A set of CatalogModifierOverride objects that override whether a given CatalogModifier is enabled by default. |
min_selected_modifiers
|
integer
|
If zero or larger, the smallest number of CatalogModifiers that must be selected from this CatalogModifierList. |
max_selected_modifiers
|
integer
|
If zero or larger, the largest number of CatalogModifiers that can be selected from this CatalogModifierList. |
enabled
|
boolean
|
If |
CatalogItemVariation
An item variation (i.e., product) in the Catalog object model.
Name | Type | Description |
---|---|---|
item_id
|
string
|
The ID of the CatalogItem associated with this item variation. Searchable. |
name
|
string
|
The item variation's name. Searchable. |
sku
|
string
|
The item variation's SKU, if any. Searchable. |
upc
|
string
|
The item variation's UPC, if any. Searchable in the Connect API. This field is only exposed in the Connect API. It is not exposed in Square's Dashboard, Square Point of Sale app or Retail Point of Sale app. |
ordinal
|
integer
|
The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal for each item variation within a parent CatalogItem is set according to the item variations's position. On reads, the value is not guaranteed to be sequential or unique. |
pricing_type
|
string
|
Indicates whether the item variation's price is fixed or determined at the time of sale. See CatalogPricingType for all possible values. |
price_money
|
Money
|
The item variation's price, if fixed pricing is used. |
location_overrides
|
ItemVariationLocationOverrides[]
|
Per-location price and inventory overrides. |
track_inventory
|
boolean
|
If |
inventory_alert_type
|
string
|
Indicates whether the item variation displays an alert when its inventory quantity is less than or equal to its
|
inventory_alert_threshold
|
integer
|
If the inventory quantity for the variation is less than or equal to this value and This value is always an integer. |
user_data
|
string
|
Arbitrary user metadata to associate with the item variation. Cannot exceed 255 characters. Searchable. |
service_duration
|
integer
|
If the CatalogItem that owns this item variation is of type |
CatalogItemVariation Example
{
"object": {
"type": "ITEM_VARIATION",
"id": "#Coffee_Regular",
"present_at_all_locations": true,
"item_variation_data": {
"name": "Regular",
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
}
}
CatalogModifier
A modifier in the Catalog object model.
Name | Type | Description |
---|---|---|
name
|
string
|
The modifier's name. Searchable. |
price_money
|
Money
|
The modifier's price. |
CatalogModifier Example
{
"object": {
"type": "MODIFIER",
"present_at_all_locations": true,
"item_modifier": {
"name": "Almond Milk",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
}
}
CatalogModifierList
A modifier list in the Catalog object model. A CatalogModifierList contains Modifiers that can be applied to a CatalogItem at the time of sale.
For example, a modifier list "Condiments" that would apply to a "Hot Dog" CatalogItem might contain
CatalogModifiers "Ketchup", "Mustard", and "Relish". The selection_type
field specifies
whether or not multiple selections from the modifier list are allowed.
Name | Type | Description |
---|---|---|
name
|
string
|
The CatalogModifierList's name. Searchable. |
selection_type
|
string
|
Indicates whether multiple options from the CatalogModifierList can be applied to a single CatalogItem. See CatalogModifierListSelectionType for all possible values. |
modifiers
|
CatalogObject[]
|
The options included in the CatalogModifierList. You must include at least one
CatalogModifier. Each CatalogObject must have type |
CatalogModifierList Example
{
"type": "MODIFIER_LIST",
"id": "#MilkType",
"present_at_all_locations": true,
"modifier_list_data": {
"name": "Milk Type",
"selection_type": "SINGLE",
"modifiers": [
{
"type": "MODIFIER",
"present_at_all_locations": true,
"item_modifier": {
"name": "Whole Milk",
"price_money": {
"amount": 0,
"currency": "USD"
}
}
},
{
"type": "MODIFIER",
"present_at_all_locations": true,
"item_modifier": {
"name": "Almond Milk",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
},
{
"type": "MODIFIER",
"present_at_all_locations": true,
"item_modifier": {
"name": "Soy Milk",
"price_money": {
"amount": 250,
"currency": "USD"
}
}
}
]
}
}
CatalogModifierOverride
Name | Type | Description |
---|---|---|
modifier_id
|
string
|
The ID of the CatalogModifier whose default behavior is being overridden. |
on_by_default
|
boolean
|
If |
CatalogObject
The wrapper object for object types in the Catalog data model. The type of a particular CatalogObject
is determined by
the value of type
and only the corresponding data field may be set.
ITEM
, only item_data
will be populated and it will contain a valid CatalogItem
object.ITEM_VARIATION
, only item_variation_data
will be populated and it will contain a valid
CatalogItemVariation object.MODIFIER
, only modifier_data
will be populated and it will contain a valid
CatalogModifier object.MODIFIER_LIST
, only modifier_list_data
will be populated and it will contain a valid
CatalogModifierList object.CATEGORY
, only category_data
will be populated and it will contain a valid
CatalogCategory object.DISCOUNT
, only discount_data
will be populated and it will contain a valid
CatalogDiscount object.TAX
, only tax_data
will be populated and it will contain a valid CatalogTax
object.For a more detailed discussion of the Catalog data model, please see the Catalog Overview.
Name | Type | Description |
---|---|---|
type
|
string
|
The type of this object. Each object type has expected properties expressed in a structured format within its
corresponding See CatalogObjectType for all possible values. |
id
|
string
|
An identifier to reference this object in the catalog. When a new CatalogObject is inserted, the client should set the
id to a temporary identifier starting with a When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references. |
updated_at
|
string
|
Last modification timestamp in RFC 3339 format, e.g., |
version
|
integer
|
The version of the object. When updating an object, the version supplied by the must match the version in the database, otherwise the write will be rejected as conflicting. |
is_deleted
|
boolean
|
If |
catalog_v1_ids
|
CatalogV1Id[]
|
The Connect V1 IDs for this object at each location where it is present, where they differ from the object's Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs. |
present_at_all_locations
|
boolean
|
If |
present_at_location_ids
|
string[]
|
A list of locations where the object is present, even if |
absent_at_location_ids
|
string[]
|
A list of locations where the object is not present, even if |
item_data
|
CatalogItem
|
Structured data for a CatalogItem, set for CatalogObjects of type |
category_data
|
CatalogCategory
|
Structured data for a CatalogCategory, set for CatalogObjects of type |
item_variation_data
|
CatalogItemVariation
|
Structured data for a CatalogItemVariation, set for CatalogObjects of type
|
tax_data
|
CatalogTax
|
Structured data for a CatalogTax, set for CatalogObjects of type |
discount_data
|
CatalogDiscount
|
Structured data for a CatalogDiscount, set for CatalogObjects of type |
modifier_list_data
|
CatalogModifierList
|
Structured data for a CatalogModifierList, set for CatalogObjects of type |
modifier_data
|
CatalogModifier
|
Structured data for a CatalogModifier, set for CatalogObjects of type |
CatalogObject Schema
{
"catalog_object": {
"type": "{{ [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY | DISCOUNT | TAX] }}",
"id": "{{ set by Catalog during object creation }}",
"updated_at": "{{ date & time of most recent update }}",
"version": "{{ version of the CatalogObject }}",
"is_deleted": "{{ [true | false] }}",
"connect_v1_ids": {
"catalog_v1_id": "{{ itemID from Catalog v1 }}",
"location_id": "{{ location where v1 ID is used }}"
},
"present_at_all_locations": "{{ [true | false] }}",
"present_at_location_ids": [
"{{ LOCATIONID-1 }}",
"{{ LOCATIONID-N }}"
],
"absent_at_location_ids": [
"{{ LOCATIONID-1 }}",
"{{ LOCATIONID-N }}"
],
"item_data": "{{ CatalogItem object only if type=ITEM }}",
"item_variation_data": "{{ CatalogItemVariation object only if type=ITEM_VARIATION }}",
"modifier_data": "{{ CatalogModifier object only if type=MODIFIER }}",
"modifier_list_data": "{{ CatalogModifierList object only if type=MODIFIER_LIST }}",
"category_data": "{{ CatalogCategory object only if type=CATEGORY }}",
"discount_data": "{{ CatalogDiscount object only if type=DISCOUNT }}",
"tax_data": "{{ CatalogTax object only if type=TAX }}"
}
}
CatalogObjectBatch
A batch of CatalogObjects.
Name | Type | Description |
---|---|---|
objects
|
CatalogObject[]
|
A list of CatalogObjects belonging to this batch. |
CatalogQuery
A query to be applied to a SearchCatalogObjectsRequest. Only one query field may be present.
Where an attribute name is required, it should be specified as the name of any field marked "searchable" from the structured data types for the desired result object type(s) (CatalogItem, CatalogItemVariation, CatalogCategory, CatalogTax, CatalogDiscount, CatalogModifierList, CatalogModifier).
For example, a query that should return Items may specify attribute names from any of the searchable fields of the
CatalogItem data type, namely "name"
, "description"
, and "abbreviation"
.
Name | Type | Description |
---|---|---|
sorted_attribute_query
|
CatalogQuerySortedAttribute
|
A query that returns all objects, sorted by the given attribute. |
exact_query
|
CatalogQueryExact
|
A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive value. |
prefix_query
|
CatalogQueryPrefix
|
A query that returns only objects for which the given (string-valued) attribute has the given case-insensitive prefix. |
range_query
|
CatalogQueryRange
|
A query that returns only objects for which the given (integer-valued) attribute lies in the given range. |
text_query
|
CatalogQueryText
|
A query that returns only objects whose searchable attributes contain all of the given keywords as prefixes. For
example, if a CatalogItem contains attributes |
items_for_tax_query
|
CatalogQueryItemsForTax
|
A query that returns all CatalogItems that have any of the given CatalogTaxes enabled. |
items_for_modifier_list_query
|
CatalogQueryItemsForModifierList
|
A query that returns all CatalogItems that have any of the given CatalogModifierLists enabled. |
CatalogQueryExact
Name | Type | Description |
---|---|---|
attribute_name
|
string
|
The name of the attribute to be searched. |
attribute_value
|
string
|
The desired value of the search attribute. |
CatalogQueryItemsForModifierList
Name | Type | Description |
---|---|---|
modifier_list_ids
|
string[]
|
A set of CatalogModifierList IDs to be used to find associated CatalogItems. |
CatalogQueryItemsForTax
Name | Type | Description |
---|---|---|
tax_ids
|
string[]
|
A set of CatalogTax IDs to be used to find associated CatalogItems. |
CatalogQueryPrefix
Name | Type | Description |
---|---|---|
attribute_name
|
string
|
The name of the attribute to be searched. |
attribute_prefix
|
string
|
The desired prefix of the search attribute value. |
CatalogQueryRange
Name | Type | Description |
---|---|---|
attribute_name
|
string
|
The name of the attribute to be searched. |
attribute_min_value
|
integer
|
The desired minimum value for the search attribute (inclusive). |
attribute_max_value
|
integer
|
The desired maximum value for the search attribute (inclusive). |
CatalogQuerySortedAttribute
Name | Type | Description |
---|---|---|
attribute_name
|
string
|
The attribute whose value should be used as the sort key. |
initial_attribute_value
|
string
|
The first attribute value to be returned by the query. Ascending sorts will return only objects with this value or greater, while descending sorts will return only objects with this value or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts). |
sort_order
|
string
|
The desired SortOrder, |
CatalogQueryText
Name | Type | Description |
---|---|---|
keywords
|
string[]
|
A list of one, two, or three search keywords. Keywords with fewer than three characters are ignored. |
CatalogTax
A tax in the Catalog object model.
Name | Type | Description |
---|---|---|
name
|
string
|
The tax's name. Searchable. |
calculation_phase
|
string
|
Whether the tax is calculated based on a payment's subtotal or total. See TaxCalculationPhase for all possible values. |
inclusion_type
|
string
|
Whether the tax is |
percentage
|
string
|
The percentage of the tax in decimal form, using a |
applies_to_custom_amounts
|
boolean
|
If |
enabled
|
boolean
|
If |
CatalogTax Example
{
"object": {
"type": "TAX",
"id": "#SalesTax",
"present_at_all_locations": true,
"tax_data": {
"name": "Sales Tax",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"inclusion_type": "ADDITIVE",
"percentage": "5.0",
"fee_applies_to_custom_amounts": true,
"enabled": true
}
}
}
ChargeRequestAdditionalRecipient
Represents an additional recipient (other than the merchant) entitled to a portion of the tender. Support is currently limited to USD, CAD and GBP currencies
Name | Type | Description |
---|---|---|
location_id
|
string
|
The location ID for a recipient (other than the merchant) receiving a portion of the tender. |
description
|
string
|
The description of the additional recipient. |
amount_money
|
Money
|
The amount of money distributed to the recipient. |
Checkout
Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.
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 Default: |
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: none; only exists if explicitly set. |
pre_populate_buyer_email
|
string
|
If provided, the buyer's email is pre-populated on the checkout page as an editable text field. Default: none; only exists if explicitly set. |
pre_populate_shipping_address
|
Address
|
If provided, the buyer's shipping info is pre-populated on the checkout page as editable text fields. Default: none; only exists if explicitly set. |
redirect_url
|
string
|
The URL to redirect to after checkout is completed with
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. |
additional_recipients
|
AdditionalRecipient[]
|
Additional recipients (other than the merchant) receiving a portion of this checkout. For example, fees assessed on the purchase by a third party integration. |
CreateOrderRequest
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. |
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 to include in a purchase. |
taxes
|
CreateOrderRequestTax[]
|
The taxes to include on the order. |
discounts
|
CreateOrderRequestDiscount[]
|
The discounts to include on the order. |
CreateOrderRequest Example
{
"request_body": {
"idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
"reference_id": "my-order-001",
"line_items": [
{
"name": "New York Strip Steak",
"quantity": "1",
"base_price_money": {
"amount": 1599,
"currency": "USD"
}
},
{
"quantity": "2",
"catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
"modifiers": [
{
"catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ"
}
],
"discounts": [
{
"name": "Sale - $1.00 off",
"amount_money": {
"amount": 100,
"currency": "USD"
}
}
]
}
],
"taxes": [
{
"name": "State Sales Tax",
"percentage": "9"
}
],
"discounts": [
{
"name": "Labor Day Sale",
"percentage": "5"
},
{
"catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7"
}
]
}
}
CreateOrderRequestDiscount
Represents a discount that can apply to either a single line item or an entire order.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
Only used for catalog discounts. The catalog object ID for an existing CatalogDiscount. Do not provide a value for this field if you provide values in other fields for an ad hoc discount. |
name
|
string
|
Only used for ad hoc discounts. The discount's name. |
percentage
|
string
|
Only used for ad hoc discounts. The percentage of the discount, as a string representation of a decimal number. A value of |
amount_money
|
Money
|
Only used for ad hoc discounts. The monetary amount of the discount. |
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.
Line items can either reference objects from the merchant's catalog, or can alternatively specify a name and price instead.
Name | Type | Description |
---|---|---|
name
|
string
|
Only used for ad hoc line items. The name of the line item. This value cannot exceed 500 characters. Do not provide a value for this field if you provide a value for |
quantity
|
string
|
The quantity to purchase, as a string representation of a number. This string must have a positive integer value. |
base_price_money
|
Money
|
The base price for a single unit of the line item.
|
variation_name
|
string
|
Only used for ad hoc line items. The variation name of the line item. This value cannot exceed 255 characters. If this value is not set for an ad hoc line item, the default value of Do not provide a value for this field if you provide a value for the |
note
|
string
|
The note of the line item. This value cannot exceed 500 characters. |
catalog_object_id
|
string
|
Only used for Catalog line items. The catalog object ID for an existing CatalogItemVariation. Do not provide a value for this field if you provide a value for |
modifiers
|
CreateOrderRequestModifier[]
|
Only used for Catalog line items. The modifiers to include on the line item. |
taxes
|
CreateOrderRequestTax[]
|
The taxes to include on the line item. |
discounts
|
CreateOrderRequestDiscount[]
|
The discounts to include on the line item. |
CreateOrderRequestModifier
Represents a modifier applied to a single line item.
Modifiers can reference existing objects in a merchant catalog or be constructed ad hoc at the time of purchase by providing a name and price.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
The catalog object ID of a CatalogModifier. |
name
|
string
|
Only used for ad hoc modifiers. The name of the modifier. Do not provide a value for |
base_price_money
|
Money
|
The base price for the modifier.
|
CreateOrderRequestTax
Represents a tax that can apply to either a single line item or an entire order.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
Only used for catalog taxes. The catalog object ID of an existing CatalogTax. Do not provide a value for this field if you provide values in other fields for an ad hoc tax. |
name
|
string
|
Only used for ad hoc taxes. The tax's name. Do not provide a value for this field if you set |
type
|
string
|
Only used for ad hoc taxes. Indicates the calculation method used to apply the line item tax. Default: |
percentage
|
string
|
Only used for ad hoc taxes. The percentage of the tax, as a string representation of a decimal number. A value of |
Customer
Represents one of a business's customers, which can have one or more cards on file associated with it.
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 payment 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. |
birthday
|
string
|
The customer's birthday in RFC-3339 format. Year is optional, timezone and times are not allowed. Example:
|
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. |
creation_source
|
string
|
A creation source represents the method used to create the customer profile. |
CustomerCreationSourceFilter
Creation source filter.
If one or more creation sources are set, customer profiles are included in, or excluded from, the result if they match at least one of the filter criteria.
Name | Type | Description |
---|---|---|
values
|
string[]
|
The list of creation sources used as filtering criteria. See CustomerCreationSource for possible values. |
rule
|
string
|
Indicates whether a customer profile matching the filter criteria should be included in the result or excluded from the
result. Default: |
CustomerFilter
Represents a set of CustomerQuery
filters used to limit the set of Customers returned by
SearchCustomers
.
Name | Type | Description |
---|---|---|
creation_source
|
CustomerCreationSourceFilter
|
A filter to select customers based on their creation source. |
created_at
|
TimeRange
|
A filter to select customers based on when they were created. |
updated_at
|
TimeRange
|
A filter to select customers based on when they were updated. |
CustomerGroupInfo
Contains some brief information about a customer group with its identifier included.
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.
Name | Type | Description |
---|---|---|
email_unsubscribed
|
boolean
|
The customer has unsubscribed from receiving marketing campaign emails. |
CustomerQuery
Represents a query (filtering and sorting criteria) used to search for customer profiles.
Name | Type | Description |
---|---|---|
filter
|
CustomerFilter
|
A list of filter criteria. |
sort
|
CustomerSort
|
Sort criteria for query results. The default sort behavior is to order customers alphabetically by |
CustomerSort
Indicates the field to use for sorting customer profiles. For example, by total money spent with the merchant or the date of their first purchase.
Name | Type | Description |
---|---|---|
field
|
string
|
The field to sort the results on. It could be the total money spent at the merchant, the date of the first visit (etc).
See CustomerSortField for possible values. Default value: |
order
|
string
|
Indicates the order in which results should be displayed based on the value of the sort field. String comparisons use
standard alphabetic comparison to determine order. Strings representing numbers are sorted as strings. See
SortOrder for possible values. Default value: |
Device
Name | Type | Description |
---|---|---|
id
|
string
|
The device's Square-issued ID. |
name
|
string
|
The device's merchant-specified name. |
Error
Represents an error encountered during a request to the Connect API.
See Handling errors for more information.
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. |
InventoryAdjustment
Represents a change in state or quantity of product inventory at a particular time and location.
Name | Type | Description |
---|---|---|
id
|
string
|
A unique ID generated by Square for the InventoryAdjustment. |
reference_id
|
string
|
An optional ID provided by the application to tie the InventoryAdjustment to an external system. |
from_state
|
string
|
The InventoryState of the related quantity of items before the adjustment. |
to_state
|
string
|
The InventoryState of the related quantity of items after the adjustment. |
location_id
|
string
|
The Square ID of the Location where the related quantity of items are being tracked. |
catalog_object_id
|
string
|
The Square generated ID of the CatalogObject being tracked. |
catalog_object_type
|
string
|
The CatalogObjectType of the CatalogObject being tracked. Tracking is
only supported for the |
quantity
|
string
|
The number of items affected by the adjustment as a decimal string. Fractional quantities are not supported. |
total_price_money
|
Money
|
The read-only total price paid for goods associated with the adjustment. Present if and only if |
occurred_at
|
string
|
A client-generated timestamp in RFC 3339 format that indicates when the adjustment took place. For write actions, the
|
created_at
|
string
|
A read-only timestamp in RFC 3339 format that indicates when Square received the adjustment. |
source
|
SourceApplication
|
Read-only information about the application that caused the inventory adjustment. |
employee_id
|
string
|
The Square ID of the Employee responsible for the inventory adjustment. |
transaction_id
|
string
|
The read-only Square ID of the [Transaction][#type-transaction] that caused the adjustment. Only relevant for payment-related state transitions. |
refund_id
|
string
|
The read-only Square ID of the [Refund][#type-refund] that caused the adjustment. Only relevant for refund-related state transitions. |
purchase_order_id
|
string
|
The read-only Square ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app. |
goods_receipt_id
|
string
|
The read-only Square ID of the Square goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app. |
InventoryChange
Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject.
Name | Type | Description |
---|---|---|
type
|
string
|
Indicates how the inventory change was applied. See InventoryChangeType for all possible values. |
physical_count
|
InventoryPhysicalCount
|
Contains details about the physical count when |
adjustment
|
InventoryAdjustment
|
Contains details about the inventory adjustment when |
transfer
|
InventoryTransfer
|
Contains details about the inventory transfer when |
InventoryCount
Represents the estimated quantity of items in a particular state at a particular location based on the known history of physical counts and inventory adjustments.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
The Square generated ID of the CatalogObject being tracked. |
catalog_object_type
|
string
|
The CatalogObjectType of the CatalogObject being tracked. Tracking is
only supported for the |
state
|
string
|
The current InventoryState for the related quantity of items. |
location_id
|
string
|
The Square ID of the Location where the related quantity of items are being tracked. |
quantity
|
string
|
The number of items in the count as a decimal string. Fractional quantities are not supported. |
calculated_at
|
string
|
A read-only timestamp in RFC 3339 format that indicates when Square received the most recent physical count or adjustment that had an affect on the estimated count. |
InventoryPhysicalCount
Represents a verified (re)count of items in a given state at a specific location. For example, the quantity of items currently on hand at a physical store).
Name | Type | Description |
---|---|---|
id
|
string
|
A unique ID generated by Square for the InventoryPhysicalCount. |
reference_id
|
string
|
An optional ID provided by the application to tie the InventoryPhysicalCount to an external system. |
catalog_object_id
|
string
|
The Square generated ID of the CatalogObject being tracked. |
catalog_object_type
|
string
|
The CatalogObjectType of the CatalogObject being tracked. Tracking is
only supported for the |
state
|
string
|
The current InventoryState for the related quantity of items. |
location_id
|
string
|
The Square ID of the Location where the related quantity of items are being tracked. |
quantity
|
string
|
The number of items affected by the physical count as a decimal string. Fractional quantities are not supported. |
source
|
SourceApplication
|
Read-only information about the application that submitted the physical count. |
employee_id
|
string
|
The Square ID of the Employee responsible for the physical count. |
occurred_at
|
string
|
A client-generated timestamp in RFC 3339 format that indicates when the physical count took place. For write actions,
the |
created_at
|
string
|
A read-only timestamp in RFC 3339 format that indicates when Square received the physical count. |
InventoryTransfer
Represents the transfer of a quantity of product inventory at a particular time from one location to another.
Name | Type | Description |
---|---|---|
id
|
string
|
A unique ID generated by Square for the InventoryTransfer. |
reference_id
|
string
|
An optional ID provided by the application to tie the InventoryTransfer to an external system. |
state
|
string
|
The InventoryState for the quantity of items being transfered. |
from_location_id
|
string
|
The Square ID of the Location where the related quantity of items were tracked before the transfer. |
to_location_id
|
string
|
The Square ID of the Location where the related quantity of items were tracked after the transfer. |
catalog_object_id
|
string
|
The Square generated ID of the CatalogObject being tracked. |
catalog_object_type
|
string
|
The CatalogObjectType of the CatalogObject being tracked.Tracking is
only supported for the |
quantity
|
string
|
The number of items affected by the transfer as a decimal string. Fractional quantities are not supported. |
occurred_at
|
string
|
A client-generated timestamp in RFC 3339 format that indicates when the transfer took place. For write actions, the
|
created_at
|
string
|
A read-only timestamp in RFC 3339 format that indicates when Square received the transfer request. |
source
|
SourceApplication
|
Read-only information about the application that initiated the inventory transfer. |
employee_id
|
string
|
The Square ID of the Employee responsible for the inventory transfer. |
ItemVariationLocationOverrides
Price and inventory alerting overrides for a CatalogItemVariation at a specific location.
Name | Type | Description |
---|---|---|
location_id
|
string
|
The ID of the location. |
price_money
|
Money
|
The price of the CatalogItemVariation at the given location, or blank for variable pricing. |
pricing_type
|
string
|
The pricing type (fixed or variable) for the CatalogItemVariation at the given location. See CatalogPricingType for all possible values. |
track_inventory
|
boolean
|
If |
inventory_alert_type
|
string
|
Indicates whether the CatalogItemVariation displays an alert when its inventory quantity
is less than or equal to its |
inventory_alert_threshold
|
integer
|
If the inventory quantity for the variation is less than or equal to this value and This value is always an integer. |
Location
Represents one of a business's locations.
Name | Type | Description |
---|---|---|
id
|
string
|
The location's unique ID. |
name
|
string
|
The location's name. Location names are set by the account owner and displayed in the dashboard as the location's nickname |
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. |
status
|
string
|
The location's status See LocationStatus for possible values. |
created_at
|
string
|
The time when the location was created, in RFC 3339 format. |
merchant_id
|
string
|
The identifier of the merchant that owns the location. |
country
|
string
|
The location's country, in ISO 3166-1-alpha-2 format. See Country for possible values. |
language_code
|
string
|
The language associated with the location in BCP 47 format. |
currency
|
string
|
The currency used for all transactions at this location, specified in ISO 4217 format. For example, the currency for a location processing transactions in the United States is 'USD'. See Currency for possible values. |
phone_number
|
string
|
The location's phone_number. |
business_name
|
string
|
The location's business_name which is shown to its customers. For example, this is the name printed on its customer's receipts. |
type
|
string
|
The location's type, as set by the account owner in the Square dashboard. Typically used to indicate whether or not the location object represents a physical space like a building or mall space. See LocationType for possible values. |
website_url
|
string
|
The location's website, as set by the account owner in the Square dashboard. Default: none; only exists if explicitly set. |
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.)
Name | Type | Description |
---|---|---|
amount
|
integer
|
The amount of money, in the smallest denomination of the currency indicated by |
currency
|
string
|
The type of currency, in ISO 4217 format. For example, the currency code for US dollars is 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
Name | Type | Description |
---|---|---|
id
|
string
|
The order's unique ID. This value is only present for Order objects created by the Orders API through 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. |
total_tax_money
|
Money
|
The total tax amount of money to collect for the order. |
total_discount_money
|
Money
|
The total discount 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.
Name | Type | Description |
---|---|---|
name
|
string
|
The name of the line item. |
quantity
|
string
|
The quantity purchased, as a string representation of a number. This string must have a positive integer value. |
note
|
string
|
The note of the line item. |
catalog_object_id
|
string
|
The CatalogItemVariation id applied to this line item. |
variation_name
|
string
|
The name of the variation applied to this line item. |
modifiers
|
OrderLineItemModifier[]
|
The CatalogModifiers applied to this line item. |
taxes
|
OrderLineItemTax[]
|
The taxes applied to this line item. |
discounts
|
OrderLineItemDiscount[]
|
The discounts applied to this line item. |
base_price_money
|
Money
|
The base price for a single unit of the line item. |
gross_sales_money
|
Money
|
The gross sales amount of money calculated as (item base price + modifiers price) * quantity. |
total_tax_money
|
Money
|
The total tax amount of money to collect for the line item. |
total_discount_money
|
Money
|
The total discount amount of money to collect for the line item. |
total_money
|
Money
|
The total amount of money to collect for this line item. |
OrderLineItemDiscount
Represents a discount that applies to one or more line items in an order.
Fixed-amount, order-level discounts are distributed across all non-zero line item totals. The amount distributed to each line item is relative to that item’s contribution to the order subtotal.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
The catalog object id referencing CatalogDiscount. |
name
|
string
|
The discount's name. |
type
|
string
|
The type of the discount. If it is created by API, it would be either VARIABLE_* is not supported in API because the order is created at the time of sale and either percentage or amount has to be specified. See OrderLineItemDiscountType for possible values. |
percentage
|
string
|
The percentage of the tax, as a string representation of a decimal number. A value of The percentage won't be set for an amount-based discount. |
amount_money
|
Money
|
The total monetary amount of the applicable discount. If it is at order level, it is the value of the order level discount. If it is at line item level, it is the value of the line item level discount. The amount_money won't be set for a percentage-based discount. |
applied_money
|
Money
|
The amount of discount actually applied to this line item. Represents the amount of money applied to a line item as a discount When an amount-based discount is at order-level,
this value is different from |
scope
|
string
|
Indicates the level at which the discount applies. See OrderLineItemDiscountScope for possible values. |
OrderLineItemModifier
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
The catalog object id referencing CatalogModifier. |
name
|
string
|
The name of the item modifier. |
base_price_money
|
Money
|
The base price for the modifier.
|
total_price_money
|
Money
|
The total price of the item modifier for its line item. This is the modifier's base_price_money multiplied by the line item's quantity. |
OrderLineItemTax
Represents a tax that applies to one or more line items in an order.
Name | Type | Description |
---|---|---|
catalog_object_id
|
string
|
The catalog object id referencing CatalogTax. |
name
|
string
|
The tax's name. |
type
|
string
|
Indicates the calculation method used to apply the tax. See OrderLineItemTaxType for possible values. |
percentage
|
string
|
The percentage of the tax, as a string representation of a decimal number. A value of |
applied_money
|
Money
|
The amount of the money applied by the tax in an order. |
Refund
Represents a refund processed for a Square transaction.
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 ( |
processing_fee_money
|
Money
|
The amount of Square processing fee money refunded to the merchant. |
additional_recipients
|
AdditionalRecipient[]
|
Additional recipients (other than the merchant) receiving a portion of this refund. For example, fees assessed on a refund of a purchase by a third party integration. |
SourceApplication
Provides information about the application used to generate an inventory change.
Name | Type | Description |
---|---|---|
product
|
string
|
Read-only Product type for the application. |
application_id
|
string
|
Read-only Square ID assigned to the application. Only used for Product type |
name
|
string
|
Read-only display name assigned to the application (e.g. |
Tender
Represents a tender (i.e., a method of payment) used in a Square transaction.
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. |
tip_money
|
Money
|
The tip's 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_details
|
TenderCardDetails
|
The details of the card tender. This value is present only if the value of |
cash_details
|
TenderCashDetails
|
The details of the cash tender. This value is present only if the value of |
additional_recipients
|
AdditionalRecipient[]
|
Additional recipients (other than the merchant) receiving a portion of this tender. For example, fees assessed on the purchase by a third party integration. |
TenderCardDetails
Represents additional details of a tender with type
CARD
or SQUARE_GIFT_CARD
Name | Type | Description |
---|---|---|
status
|
string
|
The credit card payment's current state (such as |
card
|
Card
|
The credit card's non-confidential details. |
entry_method
|
string
|
The method used to enter the card's details for the transaction. |
TimeRange
Represents a generic time range. The start and end values are represented in RFC-3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevent endpoint-specific documentation to determine how time ranges are handled.
Name | Type | Description |
---|---|---|
start_at
|
string
|
A datetime value in RFC-3339 format indicating when the time range starts. |
end_at
|
string
|
A datetime value in RFC-3339 format indicating when the time range ends. |
Transaction
Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.
The tenders
field of this object lists all methods of payment used to pay in the transaction.
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 |
product
|
string
|
The Square product that processed the transaction. |
client_id
|
string
|
If the transaction was created in the Square Point of Sale app, this value is the ID generated for the transaction by Square Point of Sale. This ID has no relationship to the transaction's canonical It is not currently possible with the Connect API to perform a transaction lookup by this value. |
shipping_address
|
Address
|
The shipping address provided in the request, if any. |
order_id
|
string
|
The order_id is an identifier for the order associated with this transaction, if any. |
CardBrand
Indicates a credit card's brand, such as VISA
or MASTERCARD
.
Name | Description |
---|---|
OTHER_BRAND
|
|
VISA
|
|
MASTERCARD
|
|
AMERICAN_EXPRESS
|
|
DISCOVER
|
|
DISCOVER_DINERS
|
|
JCB
|
|
CHINA_UNIONPAY
|
|
SQUARE_GIFT_CARD
|
CatalogDiscountType
How to apply a CatalogDiscount to a CatalogItem.
Name | Description |
---|---|
FIXED_PERCENTAGE
|
Apply the discount as a fixed percentage (e.g., 5%) off the item price. |
FIXED_AMOUNT
|
Apply the discount as a fixed amount (e.g., $1.00) off the item price. |
VARIABLE_PERCENTAGE
|
Apply the discount as a variable percentage off the item price. The percentage will be specified at the time of sale. |
VARIABLE_AMOUNT
|
Apply the discount as a variable amount off the item price. The amount will be specified at the time of sale. |
CatalogItemProductType
The type of a CatalogItem. Connect V2 only allows the creation of REGULAR
items.
Name | Description |
---|---|
REGULAR
|
An ordinary item. |
GIFT_CARD
|
A Square gift card. |
APPOINTMENTS_SERVICE
|
A service that can be booked using the Square Appointments app. |
RETAIL_ITEM
|
An item associated with the Retail vertical. |
RESTAURANT_ITEM
|
An item associated with the Restaurants vertical. |
CatalogModifierListSelectionType
Indicates whether a CatalogModifierList supports multiple selections.
Name | Description |
---|---|
SINGLE
|
Indicates that a CatalogModifierList allows only a single CatalogModifier to be selected. |
MULTIPLE
|
Indicates that a CatalogModifierList allows multiple CatalogModifier to be selected. |
CatalogObjectType
Possible kinds of CatalogObjects returned from the Catalog, each contaning type-specific
properties in the *_data
field corresponding to the object type.
Name | Description |
---|---|
ITEM
|
An item, corresponding to CatalogItem. The item-specific data will be stored in the |
CATEGORY
|
A category, corresponding to CatalogCategory. The category-specific data will be stored in the
|
ITEM_VARIATION
|
An item variation, corresponding to CatalogItemVariation. The item variation-specific data
will be stored in the |
TAX
|
A tax, corresponding to CatalogTax. The tax-specific data will be stored in the |
DISCOUNT
|
A discount, corresponding to CatalogDiscount. The discount-specific data will be stored in the
|
MODIFIER_LIST
|
A modifier list, corresponding to CatalogModifierList. The modifier list-specific data will
be stored in the |
MODIFIER
|
A modifier, corresponding to CatalogModifier. The modifier-specific data will be stored in the
|
CatalogPricingType
Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.
Name | Description |
---|---|
FIXED_PRICING
|
The CatalogItemVariation's price is fixed. |
VARIABLE_PRICING
|
The CatalogItemVariation's price is entered at the time of sale. |
Country
Indicates the country associated with another entity, such as a business. Values are in ISO 3166-1-alpha-2 format.
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.
Name | Description |
---|---|
UNKNOWN_CURRENCY
|
|
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
|
CustomerCreationSource
Indicates the method used to create the customer profile.
Name | Description |
---|---|
OTHER
|
Default creation source. Typically used for backward/future compatibility when the original source of a customer profile is unrecognized. For example, when older clients do not support newer source types. |
APPOINTMENTS
|
Customer profile created automatically when an appointment was scheduled. |
COUPON
|
Customer profile created automatically when a coupon was issued using Square Point of Sale. |
DELETION_RECOVERY
|
Customer profile restored through Square's deletion recovery process. |
DIRECTORY
|
Customer profile created manually through Square Dashboard or Point of Sale application. |
EGIFTING
|
Customer profile created automatically when a gift card was issued using Square Point of Sale. Customer profiles are created for both the purchaser and the recipient of the gift card. |
EMAIL_COLLECTION
|
Customer profile created through Square Point of Sale when signing up for marketing emails during checkout. |
FEEDBACK
|
Customer profile created automatically when providing feedback through a digital receipt. |
IMPORT
|
Customer profile created automatically when importing customer data through Square Dashboard. |
INVOICES
|
Customer profile created automatically during an invoice payment. |
LOYALTY
|
Customer profile created automatically when customers provide a phone number for loyalty reward programs during checkout. |
MARKETING
|
Customer profile created as the result of a campaign managed through Square’s Facebook integration. |
MERGE
|
Customer profile created as the result of explicitly merging multiple customer profiles through the Square Dashboard or Point of Sale application. |
ONLINE_STORE
|
Customer profile created through Square's Online Store solution (legacy service). |
INSTANT_PROFILE
|
Customer profile created automatically as the result of a successful transaction that did not explicitly link to an existing customer profile. |
TERMINAL
|
Customer profile created through Square's Virtual Terminal. |
THIRD_PARTY
|
Customer profile created through a Square API call. |
THIRD_PARTY_IMPORT
|
Customer profile created by a third-party product and imported through an official integration. |
UNMERGE_RECOVERY
|
Customer profile restored through Square's unmerge recovery process. |
CustomerInclusionExclusion
Indicates whether customers should be included in, or excluded from, the result set when they match the filtering criteria.
Name | Description |
---|---|
INCLUDE
|
Customers should be included in the result set when they match the filtering criteria. |
EXCLUDE
|
Customers should be excluded from the result set when they match the filtering criteria. |
CustomerSortField
Indicates the sort criteria for a list of Customers.
Name | Description |
---|---|
DEFAULT
|
Use the default sort. By default, Customers are sorted alphanumerically by concatenating |
CREATED_AT
|
Sort Customers by their creation date ( |
ErrorCategory
Indicates which high-level category of error has occurred during a request to the Connect API.
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
|
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.
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_LENGTH_TOO_LONG
|
|
ARRAY_LENGTH_TOO_SHORT
|
|
ARRAY_EMPTY
|
|
EXPECTED_BOOLEAN
|
|
EXPECTED_INTEGER
|
|
EXPECTED_FLOAT
|
|
EXPECTED_STRING
|
|
EXPECTED_OBJECT
|
|
EXPECTED_ARRAY
|
|
EXPECTED_MAP
|
|
EXPECTED_BASE64_ENCODED_BYTE_ARRAY
|
|
INVALID_ARRAY_VALUE
|
|
INVALID_ENUM_VALUE
|
|
INVALID_CONTENT_TYPE
|
|
INVALID_FORM_VALUE
|
|
ONE_INSTRUMENT_EXPECTED
|
|
NO_FIELDS_SET
|
|
DEPRECATED_FIELD_SET
|
|
CARD_EXPIRED
|
|
INVALID_EXPIRATION
|
|
INVALID_EXPIRATION_YEAR
|
|
INVALID_EXPIRATION_DATE
|
|
UNSUPPORTED_CARD_BRAND
|
|
UNSUPPORTED_ENTRY_METHOD
|
|
INVALID_ENCRYPTED_CARD
|
|
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
|
|
LOCATION_MISMATCH
|
|
IDEMPOTENCY_KEY_REUSED
|
|
UNEXPECTED_VALUE
|
|
SANDBOX_NOT_SUPPORTED
|
|
INVALID_EMAIL_ADDRESS
|
|
INVALID_PHONE_NUMBER
|
|
CHECKOUT_EXPIRED
|
|
BAD_CERTIFICATE
|
|
CARD_DECLINED
|
|
VERIFY_CVV_FAILURE
|
|
VERIFY_AVS_FAILURE
|
|
CARD_DECLINED_CALL_ISSUER
|
|
NOT_FOUND
|
|
APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
|
|
METHOD_NOT_ALLOWED
|
|
REQUEST_TIMEOUT
|
|
CONFLICT
|
|
REQUEST_ENTITY_TOO_LARGE
|
|
UNSUPPORTED_MEDIA_TYPE
|
|
RATE_LIMITED
|
|
NOT_IMPLEMENTED
|
|
SERVICE_UNAVAILABLE
|
|
GATEWAY_TIMEOUT
|
InventoryAlertType
Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.
Name | Description |
---|---|
NONE
|
The variation does not display an alert. |
LOW_QUANTITY
|
The variation generates an alert when its quantity is low. |
InventoryChangeType
Indicates how the inventory change was applied to a tracked quantity of items.
Name | Description |
---|---|
PHYSICAL_COUNT
|
The change occurred as part of a physical count update. |
ADJUSTMENT
|
The change occurred as part of the normal lifecycle of goods (e.g., as an inventory adjustment). |
TRANSFER
|
The change occurred as part of an inventory transfer. |
InventoryState
Indicates the state of a tracked item quantity in the lifecycle of goods.
Name | Description |
---|---|
CUSTOM
|
The related quantity of items are in a custom state. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
IN_STOCK
|
The related quantity of items are on hand and available for sale. |
SOLD
|
The related quantity of items were sold as part of an itemized transaction. Quantities in the |
RETURNED_BY_CUSTOMER
|
The related quantity of items were returned through the Square Point of Sale application, but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
RESERVED_FOR_SALE
|
The related quantity of items are on hand, but not currently available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
SOLD_ONLINE
|
The related quantity of items were sold online. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
ORDERED_FROM_VENDOR
|
The related quantity of items were ordered from a vendor but not yet received. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
RECEIVED_FROM_VENDOR
|
The related quantity of items were received from a vendor but are not yet available for sale. READ-ONLY: the Inventory API cannot move quantities to or from this state. |
IN_TRANSIT_TO
|
The related quantity of items are in transit between locations. READ-ONLY*: the Inventory API cannot move quantities to or from this state. |
NONE
|
A placeholder indicating that the related quantity of items are not currently tracked in Square. Transferring quantities
from the |
WASTE
|
The related quantity of items are lost or damaged and cannot be sold. |
UNLINKED_RETURN
|
The related quantity of items were returned but not linked to a previous transaction. Unlinked returns are not tracked
in Square. Transferring a quantity from |
LocationCapability
Indicates payment capabilities that a business's location might or might not have enabled.
Name | Description |
---|---|
CREDIT_CARD_PROCESSING
|
The location can process credit cards with Square. If this value is not present in a |
LocationStatus
Indicates the location's status.
Name | Description |
---|---|
ACTIVE
|
A fully operational location. The location can be used across all Square products and APIs. |
INACTIVE
|
A functionally limited location. The location can only be used via Square APIs. NOTE: We strongly discourage the use of inactive locations. Making API calls with inactive locations will cause complications if the restrictions on inactive locations increase in the future. |
LocationType
Indicates the location's type.
Name | Description |
---|---|
PHYSICAL
|
A physical location of a business. |
MOBILE
|
A location without a physical address. For example: mobile food truck, online store, phone app. |
OrderLineItemDiscountScope
Indicates whether this is a line item or order level discount.
Name | Description |
---|---|
OTHER_DISCOUNT_SCOPE
|
Used for reporting only. The original transaction discount scope is currently not supported by the API. |
LINE_ITEM
|
The discount should be applied to a single line item. |
ORDER
|
The discount should be applied to the entire order. |
OrderLineItemDiscountType
Indicates how the discount is applied to the associated line item or order.
Name | Description |
---|---|
UNKNOWN_DISCOUNT
|
Used for reporting only. The original transaction discount type is currently not supported by the API. |
FIXED_PERCENTAGE
|
Apply the discount as a fixed percentage (e.g., 5%) off the item price. |
FIXED_AMOUNT
|
Apply the discount as a fixed monetary value (e.g., $1.00) off the item price. |
VARIABLE_PERCENTAGE
|
Apply the discount as a variable percentage off the item price. The variable percentage is defined in Register POS apps. Specific value is assigned at the time of the purchase. |
VARIABLE_AMOUNT
|
Apply the discount as a variable amount off the item price. The variable amount is defined in Square POS app. Specific value is assigned at the time of the purchase. |
OrderLineItemTaxType
Indicates how the tax is applied to the associated line item or order.
Name | Description |
---|---|
UNKNOWN_TAX
|
Used for reporting only. The original transaction tax type is currently not supported by the API. |
ADDITIVE
|
The tax is an additive tax. The tax amount is added on top of the price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10. |
INCLUSIVE
|
The tax is an inclusive tax. Inclusive taxes are already included in the line item price or order total. For example, a $1.00 item with a 10% inclusive tax would have a pre-tax cost of $0.91 (91 cents) and a $0.09 (9 cents) tax for a total cost of $1 to the buyer. |
Product
Indicates the Square product used to generate an inventory change.
Name | Description |
---|---|
SQUARE_POS
|
Square Point of Sale application. |
EXTERNAL_API
|
Square Connect APIs (Transactions API, Checkout API). |
BILLING
|
A Square subscription (various products). |
APPOINTMENTS
|
Square Appointments. |
INVOICES
|
Square Invoices. |
ONLINE_STORE
|
Square Online Store. |
PAYROLL
|
Square Payroll. |
DASHBOARD
|
Square Dashboard |
ITEM_LIBRARY_IMPORT
|
Item Library Import |
OTHER
|
A Square product that does not match any other value. |
RefundStatus
Indicates a refund's current status.
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. |
RegisterDomainResponseStatus
The status of domain registration.
Name | Description |
---|---|
PENDING
|
The domain is added, but not verified. |
VERIFIED
|
The domain is added and verified. It can be used to accept Apple Pay transactions. |
SortOrder
The order (e.g., chronological or alphabetical) in which results from a request are returned.
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. |
TaxCalculationPhase
When to calculate the taxes due on a cart.
Name | Description |
---|---|
TAX_SUBTOTAL_PHASE
|
The fee is calculated based on the payment's subtotal. |
TAX_TOTAL_PHASE
|
The fee is calculated based on the payment's total. |
TaxInclusionType
Whether to the tax amount should be additional to or included in to the CatalogItem price.
Name | Description |
---|---|
ADDITIVE
|
The tax is an additive tax. The tax amount is added on top of the CatalogItemVariation price. For example, a $1.00 item with a 10% additive tax would have a total cost to the buyer of $1.10. |
INCLUSIVE
|
The tax is an inclusive tax. The tax amount is included in the CatalogItemVariation price. For example, a $1.00 item with a 10% inclusive tax would have a total cost to the buyer of $1.00, with $0.91 (91 cents) of that total being the cost of the item and $0.09 (9 cents) being tax. |
TenderCardDetailsEntryMethod
Indicates the method used to enter the card's details.
Name | Description |
---|---|
SWIPED
|
The card was swiped through a Square reader or Square stand. |
KEYED
|
The card information was keyed manually into Square Point of Sale 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.
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.
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.
Name | Description |
---|---|
REGISTER
|
Square Point of Sale. |
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. |
Square provides client libraries for Connect V1 and V2 in a variety of programming languages. See Client libraries for a full list.
Version 1 and 2 of the Connect API are 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.
Postman is an app for easy RESTful API exploration. Use our "Postman Collection" to try Square's Connect endpoints. Read our blog post on setting up Postman and configuring it with your API credentials.
Click Run in Postman below to explore our V1 and V2 API Collection.
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.
Currently, Connect API has two major versions: v1 and v2 included in its path. Connect API applications can communicate
with endpoints from all available versions. In Connect v2 API, Square-Version
is supported for the evolutional
changes. Please refer to How Versioning Works for more details.
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.
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.
The way you provide parameters to a Connect API request depends on the HTTP method of the request.
GET
and DELETE
requestsFor 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
requestsFor 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" }
All monetary amounts in the Connect API are represented by the Money
object, which has the following structure:
{ "amount": 400, "currency_code": "USD" }
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 US dollars.
Note: Businesses located in the United States or Canada can set monitary amounts as low as 1 cent. For example, the following structure sets a monitary amount of 50 cents USD.
{ "amount": 50, "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 currency_code
field is in ISO 4217 format.
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.
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.
sort_order
is DESC
(newest-first), begin_time
is exclusive and end_time
is inclusive.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.
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.
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
.
List endpoints might return duplicate results. Use the id
attribute of the returned objects to identify any such
duplicates.
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.
You can replace your application's personal access token or application secret from the application dashboard.
Replacing an application credential immediately invalidates the previous credential. Make sure you update your application accordingly.
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.
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 can have 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.field
is the name of the field provided in the original request that the error pertains to, if any.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.
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.
To set up your PHP Ruby Java C# Python Node.js SDK, follow the example below:
// Setup authorization
Configuration::getDefaultConfiguration()->setAccessToken($ACCESS_TOKEN);
require 'square_connect'
# Setup authorization.
SquareConnect.configure do |config|
config.access_token = ACCESS_TOKEN
end
import com.squareup.connect.*;
import com.squareup.connect.auth.*;
// Configure OAuth2 access token for authorization: oauth2
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken(ACCESS_TOKEN);
using Square.Connect.Client;
// Setup authorization.
Configuration.Default.AccessToken = ACCESS_TOKEN;
import squareconnect
# Setup authorization.
squareconnect.configuration.access_token = ACCESS_TOKEN
const SquareConnect = require('square-connect');
# Setup authorization.
const defaultClient = SquareConnect.ApiClient.instance;
const oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = ACCESS_TOKEN