@datafire/squareup

Client library for Square Connect

Installation and Usage

``bash
npm install --save @datafire/squareup
`
`js
let squareup = require('@datafire/squareup').create({
access_token: "",
refresh_token: "",
client_id: "",
client_secret: "",
redirect_uri: ""
});

.then(data => {
console.log(data);
});
`

Description

Client library for accessing the Square Connect APIs

Actions

$3

Exchange the code passed to your redirect URI for an access_token


`js
squareup.oauthCallback({
"code": ""
}, context)
`

#### Input
* input object
* code required string

#### Output
* output object
* access_token string
* refresh_token string
* token_type string
* scope string
* expiration string

$3

Exchange a refresh_token for an access_token


`js
squareup.oauthRefresh(null, context)
`

#### Input
This action has no parameters

#### Output
* output object
* access_token string
* refresh_token string
* token_type string
* scope string
* expiration string

$3

Get a business's information.


`js
squareup.RetrieveBusiness(null, context)
`

#### Input
This action has no parameters

#### Output
* output v1Merchant

$3

Provides summary information for all of a business's employees.


`js
squareup.ListEmployees({}, context)
`

#### Input
* input object
* order string (values: ASC, DESC): The order in which employees are listed in the response, based on their created_at field. Default value: ASC
* begin_updated_at string: If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format
* end_updated_at string: If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.
* begin_created_at string: If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.
* end_created_at string: If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.
* status string (values: ACTIVE, INACTIVE): If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).
* external_id string: If provided, the endpoint returns only employee entities with the specified external_id.
* limit integer: The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Employee

$3

Creates an employee for a business.


`js
squareup.CreateEmployee({
"body": {
"first_name": "",
"last_name": ""
}
}, context)
`

#### Input
* input object
* body required v1Employee

#### Output
* output v1Employee

$3

Provides the details for a single employee.


`js
squareup.RetrieveEmployee({
"employee_id": ""
}, context)
`

#### Input
* input object
* employee_id required string: The employee's ID.

#### Output
* output v1Employee

$3

V1 UpdateEmployee


`js
squareup.UpdateEmployee({
"employee_id": "",
"body": {
"first_name": "",
"last_name": ""
}
}, context)
`

#### Input
* input object
* employee_id required string: The ID of the role to modify.
* body required v1Employee

#### Output
* output v1Employee

$3

Provides details for a business's locations, including their IDs.


`js
squareup.v1.me.locations.get(null, context)
`

#### Input
This action has no parameters

#### Output
* output array
* items v1Merchant

$3

Provides summary information for all of a business's employee roles.


`js
squareup.ListEmployeeRoles({}, context)
`

#### Input
* input object
* order string (values: ASC, DESC): The order in which employees are listed in the response, based on their created_at field.Default value: ASC
* limit integer: The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1EmployeeRole

$3

Creates an employee role you can then assign to employees.


`js
squareup.CreateEmployeeRole({
"EmployeeRole": {
"name": "",
"permissions": []
}
}, context)
`

#### Input
* input object
* EmployeeRole required v1EmployeeRole

#### Output
* output v1EmployeeRole

$3

Provides the details for a single employee role.


`js
squareup.RetrieveEmployeeRole({
"role_id": ""
}, context)
`

#### Input
* input object
* role_id required string: The role's ID.

#### Output
* output v1EmployeeRole

$3

Modifies the details of an employee role.


`js
squareup.UpdateEmployeeRole({
"role_id": "",
"body": {
"name": "",
"permissions": []
}
}, context)
`

#### Input
* input object
* role_id required string: The ID of the role to modify.
* body required v1EmployeeRole

#### Output
* output v1EmployeeRole

$3

Provides summary information for all of a business's employee timecards.


`js
squareup.ListTimecards({}, context)
`

#### Input
* input object
* order string (values: ASC, DESC): The order in which timecards are listed in the response, based on their created_at field.
* employee_id string: If provided, the endpoint returns only timecards for the employee with the specified ID.
* begin_clockin_time string: If filtering results by their clockin_time field, the beginning of the requested reporting period, in ISO 8601 format.
* end_clockin_time string: If filtering results by their clockin_time field, the end of the requested reporting period, in ISO 8601 format.
* begin_clockout_time string: If filtering results by their clockout_time field, the beginning of the requested reporting period, in ISO 8601 format.
* end_clockout_time string: If filtering results by their clockout_time field, the end of the requested reporting period, in ISO 8601 format.
* begin_updated_at string: If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format.
* end_updated_at string: If filtering results by their updated_at field, the end of the requested reporting period, in ISO 8601 format.
* deleted boolean: If true, only deleted timecards are returned. If false, only valid timecards are returned.If you don't provide this parameter, both valid and deleted timecards are returned.
* limit integer: The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Timecard

$3

Creates a timecard for an employee. Each timecard corresponds to a single shift.


`js
squareup.CreateTimecard({
"body": {
"employee_id": ""
}
}, context)
`

#### Input
* input object
* body required v1Timecard

#### Output
* output v1Timecard

$3

Deletes a timecard. Deleted timecards are still accessible from Connect API endpoints, but the value of their deleted field is set to true. See Handling deleted timecards for more information.


`js
squareup.DeleteTimecard({
"timecard_id": ""
}, context)
`

#### Input
* input object
* timecard_id required string: The ID of the timecard to delete.

#### Output
* output object

$3

Provides the details for a single timecard.


`js
squareup.RetrieveTimecard({
"timecard_id": ""
}, context)
`

#### Input
* input object
* timecard_id required string: The timecard's ID.

#### Output
* output v1Timecard

$3

Modifies a timecard's details. This creates an API_EDIT event for the timecard. You can view a timecard's event history with the List Timecard Events endpoint.


`js
squareup.UpdateTimecard({
"timecard_id": "",
"body": {
"employee_id": ""
}
}, context)
`

#### Input
* input object
* timecard_id required string: TThe ID of the timecard to modify.
* body required v1Timecard

#### Output
* output v1Timecard

$3

Provides summary information for all events associated with a particular timecard.


`js
squareup.ListTimecardEvents({
"timecard_id": ""
}, context)
`

#### Input
* input object
* timecard_id required string: The ID of the timecard to list events for.

#### Output
* output array
* items v1TimecardEvent

$3

Provides non-confidential details for all of a location's associated bank accounts. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.


`js
squareup.ListBankAccounts({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list bank accounts for.

#### Output
* output array
* items v1BankAccount

$3

Provides non-confidential details for a merchant's associated bank account. This endpoint does not provide full bank account numbers, and there is no way to obtain a full bank account number with the Connect API.


`js
squareup.RetrieveBankAccount({
"location_id": "",
"bank_account_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the bank account's associated location.
* bank_account_id required string: The bank account's Square-issued ID. You obtain this value from Settlement objects returned.

#### Output
* output v1BankAccount

$3

Provides the details for all of a location's cash drawer shifts during a date range. The date range you specify cannot exceed 90 days.


`js
squareup.ListCashDrawerShifts({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list cash drawer shifts for.
* order string (values: ASC, DESC): The order in which cash drawer shifts are listed in the response, based on their created_at field. Default value: ASC
* begin_time string: The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time minus 90 days.
* end_time string: The beginning of the requested reporting period, in ISO 8601 format. Default value: The current time.

#### Output
* output array
* items v1CashDrawerShift

$3

Provides the details for a single cash drawer shift, including all events that occurred during the shift.


`js
squareup.RetrieveCashDrawerShift({
"location_id": "",
"shift_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list cash drawer shifts for.
* shift_id required string: The shift's ID.

#### Output
* output v1CashDrawerShift

$3

Lists all of a location's item categories.


`js
squareup.ListCategories({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list categories for.

#### Output
* output array
* items v1Category

$3

Creates an item category.


`js
squareup.CreateCategory({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create an item for.
* body required v1Category

#### Output
* output v1Category

$3

Deletes an existing item category.


`js
squareup.DeleteCategory({
"location_id": "",
"category_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* category_id required string: The ID of the category to delete.

#### Output
* output v1Category

$3

Modifies the details of an existing item category.


`js
squareup.UpdateCategory({
"location_id": "",
"category_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the category's associated location.
* category_id required string: The ID of the category to edit.
* body required v1Category

#### Output
* output v1Category

$3

Lists all of a location's discounts.


`js
squareup.ListDiscounts({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list categories for.

#### Output
* output array
* items v1Discount

$3

Creates a discount.


`js
squareup.CreateDiscount({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create an item for.
* body required v1Discount

#### Output
* output v1Discount

$3

Deletes an existing discount.


`js
squareup.DeleteDiscount({
"location_id": "",
"discount_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* discount_id required string: The ID of the discount to delete.

#### Output
* output v1Discount

$3

Modifies the details of an existing discount.


`js
squareup.UpdateDiscount({
"location_id": "",
"discount_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the category's associated location.
* discount_id required string: The ID of the discount to edit.
* body required v1Discount

#### Output
* output v1Discount

$3

Lists all of a location's fees (taxes).


`js
squareup.ListFees({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list fees for.

#### Output
* output array
* items v1Fee

$3

Creates a fee (tax).


`js
squareup.CreateFee({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create a fee for.
* body required v1Fee

#### Output
* output v1Fee

$3

Deletes an existing fee (tax).


`js
squareup.DeleteFee({
"location_id": "",
"fee_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the fee's associated location.
* fee_id required string: The ID of the fee to delete.

#### Output
* output v1Fee

$3

Modifies the details of an existing fee (tax).


`js
squareup.UpdateFee({
"location_id": "",
"fee_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the fee's associated location.
* fee_id required string: The ID of the fee to edit.
* body required v1Fee

#### Output
* output v1Fee

$3

Provides inventory information for all of a merchant's inventory-enabled item variations.


`js
squareup.ListInventory({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* limit integer: The maximum number of inventory entries to return in a single response. This value cannot exceed 1000.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1InventoryEntry

$3

Adjusts an item variation's current available inventory.


`js
squareup.AdjustInventory({
"location_id": "",
"variation_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* variation_id required string: The ID of the variation to adjust inventory information for.
* body required v1AdjustInventoryRequest

#### Output
* output v1InventoryEntry

$3

Provides summary information for all of a location's items.


`js
squareup.ListItems({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list items for.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Item

$3

Creates an item and at least one variation for it.


`js
squareup.CreateItem({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create an item for.
* body required v1Item

#### Output
* output v1Item

$3

Deletes an existing item and all item variations associated with it.


`js
squareup.DeleteItem({
"location_id": "",
"item_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The ID of the item to modify.

#### Output
* output v1Item

$3

Provides the details for a single item, including associated modifier lists and fees.


`js
squareup.RetrieveItem({
"location_id": "",
"item_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The item's ID.

#### Output
* output v1Item

$3

Modifies the core details of an existing item.


`js
squareup.UpdateItem({
"location_id": "",
"item_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The ID of the item to modify.
* body required v1Item

#### Output
* output v1Item

$3

Removes a fee assocation from an item, meaning the fee is no longer automatically applied to the item in Square Register.


`js
squareup.RemoveFee({
"location_id": "",
"item_id": "",
"fee_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the fee's associated location.
* item_id required string: The ID of the item to add the fee to.
* fee_id required string: The ID of the fee to apply.

#### Output
* output v1Item

$3

Associates a fee with an item, meaning the fee is automatically applied to the item in Square Register.


`js
squareup.ApplyFee({
"location_id": "",
"item_id": "",
"fee_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the fee's associated location.
* item_id required string: The ID of the item to add the fee to.
* fee_id required string: The ID of the fee to apply.

#### Output
* output v1Item

$3

Removes a modifier list association from an item, meaning modifier options from the list can no longer be applied to the item.


`js
squareup.RemoveModifierList({
"location_id": "",
"modifier_list_id": "",
"item_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to remove.
* item_id required string: The ID of the item to remove the modifier list from.

#### Output
* output v1Item

$3

Associates a modifier list with an item, meaning modifier options from the list can be applied to the item.


`js
squareup.ApplyModifierList({
"location_id": "",
"modifier_list_id": "",
"item_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to apply.
* item_id required string: The ID of the item to add the modifier list to.

#### Output
* output v1Item

$3

Creates an item variation for an existing item.


`js
squareup.CreateVariation({
"location_id": "",
"item_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The item's ID.
* body required v1Variation

#### Output
* output v1Variation

$3

Deletes an existing item variation from an item.


`js
squareup.DeleteVariation({
"location_id": "",
"item_id": "",
"variation_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The ID of the item to delete.
* variation_id required string: The ID of the variation to delete.

#### Output
* output v1Variation

$3

Modifies the details of an existing item variation.


`js
squareup.UpdateVariation({
"location_id": "",
"item_id": "",
"variation_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* item_id required string: The ID of the item to modify.
* variation_id required string: The ID of the variation to modify.
* body required v1Variation

#### Output
* output v1Variation

$3

Lists all of a location's modifier lists.


`js
squareup.ListModifierLists({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list modifier lists for.

#### Output
* output array
* items v1ModifierList

$3

Creates an item modifier list and at least one modifier option for it.


`js
squareup.CreateModifierList({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create a modifier list for.
* body required v1ModifierList

#### Output
* output v1ModifierList

$3

Deletes an existing item modifier list and all modifier options associated with it.


`js
squareup.DeleteModifierList({
"location_id": "",
"modifier_list_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to delete.

#### Output
* output v1ModifierList

$3

Provides the details for a single modifier list.


`js
squareup.RetrieveModifierList({
"location_id": "",
"modifier_list_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The modifier list's ID.

#### Output
* output v1ModifierList

$3

Modifies the details of an existing item modifier list.


`js
squareup.UpdateModifierList({
"location_id": "",
"modifier_list_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to edit.
* body required v1UpdateModifierListRequest

#### Output
* output v1ModifierList

$3

Creates an item modifier option and adds it to a modifier list.


`js
squareup.CreateModifierOption({
"location_id": "",
"modifier_list_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to edit.
* body required v1ModifierOption

#### Output
* output v1ModifierOption

$3

Deletes an existing item modifier option from a modifier list.


`js
squareup.DeleteModifierOption({
"location_id": "",
"modifier_list_id": "",
"modifier_option_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to delete.
* modifier_option_id required string: The ID of the modifier list to edit.

#### Output
* output v1ModifierOption

$3

Modifies the details of an existing item modifier option.


`js
squareup.UpdateModifierOption({
"location_id": "",
"modifier_list_id": "",
"modifier_option_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the item's associated location.
* modifier_list_id required string: The ID of the modifier list to edit.
* modifier_option_id required string: The ID of the modifier list to edit.
* body required v1ModifierOption

#### Output
* output v1ModifierOption

$3

Provides summary information for a merchant's online store orders.


`js
squareup.ListOrders({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list online store orders for.
* order string (values: ASC, DESC): TThe order in which payments are listed in the response.
* limit integer: The maximum number of payments to return in a single response. This value cannot exceed 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Order

$3

Provides comprehensive information for a single online store order, including the order's history.


`js
squareup.RetrieveOrder({
"location_id": "",
"order_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the order's associated location.
* order_id required string: The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint

#### Output
* output v1Order

$3

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:


`js
squareup.UpdateOrder({
"location_id": "",
"order_id": "",
"body": {
"action": ""
}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the order's associated location.
* order_id required string: The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint
* body required v1UpdateOrderRequest

#### Output
* output v1Order

$3

Lists all of a location's Favorites pages in Square Register.


`js
squareup.ListPages({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list Favorites pages for.

#### Output
* output array
* items v1Page

$3

Creates a Favorites page in Square Register.


`js
squareup.CreatePage({
"location_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to create an item for.
* body required v1Page

#### Output
* output v1Page

$3

Deletes an existing Favorites page and all of its cells.


`js
squareup.DeletePage({
"location_id": "",
"page_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the Favorites page's associated location.
* page_id required string: The ID of the page to delete.

#### Output
* output v1Page

$3

Modifies the details of a Favorites page in Square Register.


`js
squareup.UpdatePage({
"location_id": "",
"page_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the Favorites page's associated location
* page_id required string: The ID of the page to modify.
* body required v1Page

#### Output
* output v1Page

$3

Deletes a cell from a Favorites page in Square Register.


`js
squareup.DeletePageCell({
"location_id": "",
"page_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the Favorites page's associated location.
* page_id required string: The ID of the page to delete.
* row string: The row of the cell to clear. Always an integer between 0 and 4, inclusive. Row 0 is the top row.
* column string: The column of the cell to clear. Always an integer between 0 and 4, inclusive. Column 0 is the leftmost column.

#### Output
* output v1Page

$3

Modifies a cell of a Favorites page in Square Register.


`js
squareup.UpdatePageCell({
"location_id": "",
"page_id": "",
"body": {}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the Favorites page's associated location.
* page_id required string: The ID of the page the cell belongs to.
* body required v1PageCell

#### Output
* output v1Page

$3

Provides summary information for all payments taken by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length. See Date ranges for details of inclusive and exclusive dates.


`js
squareup.ListPayments({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations.
* order string (values: ASC, DESC): The order in which payments are listed in the response.
* begin_time string: The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
* end_time string: The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
* limit integer: The maximum number of payments to return in a single response. This value cannot exceed 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Payment

$3

Provides comprehensive information for a single payment.


`js
squareup.RetrievePayment({
"location_id": "",
"payment_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the payment's associated location.
* payment_id required string: The payment's Square-issued ID. You obtain this value from Payment objects returned by the List Payments endpoint, or Settlement objects returned by the List Settlements endpoint.

#### Output
* output v1Payment

$3

Provides the details for all refunds initiated by a merchant or any of the merchant's mobile staff during a date range. Date ranges cannot exceed one year in length.


`js
squareup.v1.location_id.refunds.get({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list refunds for.
* order string (values: ASC, DESC): TThe order in which payments are listed in the response.
* begin_time string: The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
* end_time string: The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
* limit integer: The maximum number of payments to return in a single response. This value cannot exceed 200.
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Refund

$3

Issues a refund for a previously processed payment. You must issue a refund within 60 days of the associated payment.


`js
squareup.v1.location_id.refunds.post({
"location_id": "",
"body": {
"payment_id": "",
"type": "",
"reason": ""
}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the original payment's associated location.
* body required v1CreateRefundRequest

#### Output
* output v1Refund

$3

Provides summary information for all deposits and withdrawals initiated by Square to a merchant's bank account during a date range. Date ranges cannot exceed one year in length.


`js
squareup.ListSettlements({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list settlements for. If you specify me, this endpoint returns payments aggregated from all of the business's locations.
* order string (values: ASC, DESC): TThe order in which payments are listed in the response.
* begin_time string: The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
* end_time string: The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
* limit integer: The maximum number of payments to return in a single response. This value cannot exceed 200.
* status string (values: SENT, FAILED): Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED).
* batch_token string: A pagination cursor to retrieve the next set of results for your

#### Output
* output array
* items v1Settlement

$3

Provides comprehensive information for a single settlement, including the entries that contribute to the settlement's total.


`js
squareup.RetrieveSettlement({
"location_id": "",
"settlement_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the settlements's associated location.
* settlement_id required string: The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.

#### Output
* output v1Settlement

$3

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.


`js
squareup.BatchDeleteCatalogObjects({
"body": {}
}, context)
`

#### Input
* input object
* body required BatchDeleteCatalogObjectsRequest

#### Output
* output BatchDeleteCatalogObjectsResponse

$3

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.


`js
squareup.BatchRetrieveCatalogObjects({
"body": {
"object_ids": []
}
}, context)
`

#### Input
* input object
* body required BatchRetrieveCatalogObjectsRequest

#### Output
* output BatchRetrieveCatalogObjectsResponse

$3

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.


`js
squareup.BatchUpsertCatalogObjects({
"body": {
"idempotency_key": ""
}
}, context)
`

#### Input
* input object
* body required BatchUpsertCatalogObjectsRequest

#### Output
* output BatchUpsertCatalogObjectsResponse

$3


Returns information about the Square Catalog API, such as batch size
limits for BatchUpsertCatalogObjects.


`js
squareup.CatalogInfo(null, context)
`

#### Input
This action has no parameters

#### Output
* output CatalogInfoResponse

$3


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.


`js
squareup.ListCatalog({}, context)
`

#### Input
* input object
* cursor string: The pagination cursor returned in the previous response. Leave unset for an initial request.
* types string: An optional case-insensitive, comma-separated list of object types to retrieve, for example

#### Output
* output ListCatalogResponse

$3

Creates or updates the target CatalogObject.


`js
squareup.UpsertCatalogObject({
"body": {
"idempotency_key": "",
"object": {
"type": "",
"id": ""
}
}
}, context)
`

#### Input
* input object
* body required UpsertCatalogObjectRequest

#### Output
* output UpsertCatalogObjectResponse

$3

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.


`js
squareup.DeleteCatalogObject({
"object_id": ""
}, context)
`

#### Input
* input object
* object_id required string: The ID of the CatalogObject to be deleted. When an object is deleted, other

#### Output
* output DeleteCatalogObjectResponse

$3

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.


`js
squareup.RetrieveCatalogObject({
"object_id": ""
}, context)
`

#### Input
* input object
* object_id required string: The object ID of any type of CatalogObjects to be retrieved.
* include_related_objects boolean: If true, the response will include additional objects that are related to the

#### Output
* output RetrieveCatalogObjectResponse

$3

Queries the targeted catalog using a variety of query types
(CatalogQuerySortedAttribute,
(CatalogQueryExact,
(CatalogQueryRange,
(CatalogQueryText,
(CatalogQueryItemsForTax,
(CatalogQueryItemsForModifierList).


`js
squareup.SearchCatalogObjects({
"body": {}
}, context)
`

#### Input
* input object
* body required SearchCatalogObjectsRequest

#### Output
* output SearchCatalogObjectsResponse

$3

Updates the CatalogModifierList objects
that apply to the targeted CatalogItem without having
to perform an upsert on the entire item.


`js
squareup.UpdateItemModifierLists({
"body": {
"item_ids": []
}
}, context)
`

#### Input
* input object
* body required UpdateItemModifierListsRequest

#### Output
* output UpdateItemModifierListsResponse

$3

Updates the CatalogTax objects that apply to the
targeted CatalogItem without having to perform an
upsert on the entire item.


`js
squareup.UpdateItemTaxes({
"body": {
"item_ids": []
}
}, context)
`

#### Input
* input object
* body required UpdateItemTaxesRequest

#### Output
* output UpdateItemTaxesResponse

$3

Lists a business's customers.


`js
squareup.ListCustomers({}, context)
`

#### Input
* input object
* cursor string: A pagination cursor returned by a previous call to this endpoint.

#### Output
* output ListCustomersResponse

$3

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

You must provide __at least one__ of the following values in your request to this
endpoint:

- given_name
- family_name
- company_name
- email_address
- phone_number

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


`js
squareup.CreateCustomer({
"body": {}
}, context)
`

#### Input
* input object
* body required CreateCustomerRequest

#### Output
* output CreateCustomerResponse

$3

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


`js
squareup.DeleteCustomer({
"customer_id": ""
}, context)
`

#### Input
* input object
* customer_id required string: The ID of the customer to delete.

#### Output
* output DeleteCustomerResponse

$3

Returns details for a single customer.


`js
squareup.RetrieveCustomer({
"customer_id": ""
}, context)
`

#### Input
* input object
* customer_id required string: The ID of the customer to retrieve.

#### Output
* output RetrieveCustomerResponse

$3

Updates the details of an existing customer.
The ID of the customer may change if the customer has been merged into another customer.

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


`js
squareup.UpdateCustomer({
"customer_id": "",
"body": {}
}, context)
`

#### Input
* input object
* customer_id required string: The ID of the customer to update.
* body required UpdateCustomerRequest

#### Output
* output UpdateCustomerResponse

$3

Adds a card on file to an existing customer. In the United States
Square takes care of automatically updating any cards on file that might
have expired since you first attached them to a customer.


`js
squareup.CreateCustomerCard({
"customer_id": "",
"body": {
"card_nonce": ""
}
}, context)
`

#### Input
* input object
* customer_id required string: The ID of the customer to link the card on file to.
* body required CreateCustomerCardRequest

#### Output
* output CreateCustomerCardResponse

$3

Removes a card on file from a customer.


`js
squareup.DeleteCustomerCard({
"customer_id": "",
"card_id": ""
}, context)
`

#### Input
* input object
* 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.

#### Output
* output DeleteCustomerCardResponse

$3

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.


`js
squareup.v2.locations.get(null, context)
`

#### Input
This action has no parameters

#### Output
* output ListLocationsResponse

$3


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.


`js
squareup.CreateCheckout({
"location_id": "",
"body": {
"idempotency_key": "",
"order": {
"line_items": []
}
}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the business location to associate the checkout with.
* body required CreateCheckoutRequest

#### Output
* output CreateCheckoutResponse

$3

Lists refunds for one of a business's locations.

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

Max results per page: 50


`js
squareup.v2.locations.location_id.refunds.get({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list refunds for.
* begin_time string: The beginning of the requested reporting period, in RFC 3339 format.
* end_time string: The end of the requested reporting period, in RFC 3339 format.
* sort_order string (values: DESC, ASC): The order in which results are listed in the response (ASC for
* cursor string: A pagination cursor returned by a previous call to this endpoint.

#### Output
* output ListRefundsResponse

$3

Lists transactions for a particular location.

Max results per page: 50


`js
squareup.ListTransactions({
"location_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to list transactions for.
* begin_time string: The beginning of the requested reporting period, in RFC 3339 format.
* end_time string: The end of the requested reporting period, in RFC 3339 format.
* sort_order string (values: DESC, ASC): The order in which results are listed in the response (ASC for
* cursor string: A pagination cursor returned by a previous call to this endpoint.

#### Output
* output ListTransactionsResponse

$3

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

Your request to this endpoint must include _either_:

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

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

- buyer_email_address
- At least one of billing_address or shipping_address

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


`js
squareup.Charge({
"location_id": "",
"body": {
"idempotency_key": "",
"amount_money": {}
}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the location to associate the created transaction with.
* body required ChargeRequest

#### Output
* output ChargeResponse

$3

Retrieves details for a single transaction.


`js
squareup.RetrieveTransaction({
"location_id": "",
"transaction_id": ""
}, context)
`

#### Input
* input object
* location_id required string: The ID of the transaction's associated location.
* transaction_id required string: The ID of the transaction to retrieve.

#### Output
* output RetrieveTransactionResponse

$3


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

See Delayed capture transactions
for more information.


`js
squareup.CaptureTransaction({
"location_id": "",
"transaction_id": ""
}, context)
`

#### Input
* input object
* location_id required string
* transaction_id required string

#### Output
* output CaptureTransactionResponse

$3

Initiates a refund for a previously charged tender.

You must issue a refund within 120 days of the associated payment. See
(this article)[https://squareup.com/help/us/en/article/5060] for more information
on refund behavior.


`js
squareup.v2.locations.location_id.transactions.transaction_id.refund.post({
"location_id": "",
"transaction_id": "",
"body": {
"idempotency_key": "",
"tender_id": "",
"amount_money": {}
}
}, context)
`

#### Input
* input object
* location_id required string: The ID of the original transaction's associated location.
* transaction_id required string: The ID of the original transaction that includes the tender to refund.
* body required CreateRefundRequest

#### Output
* output CreateRefundResponse

$3


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

See Delayed capture transactions
for more information.


`js
squareup.VoidTransaction({
"location_id": "",
"transaction_id": ""
}, context)
`

#### Input
* input object
* location_id required string
* transaction_id required string

#### Output
* output VoidTransactionResponse

Definitions

$3


* Address object: Represents a physical address.
* address_line_1 string: The first line of the address.
* address_line_2 string: The second line of the address, if any.
* address_line_3 string: The third line of the address, if any.
* administrative_district_level_1 string: A civil entity within the address's country. In the US, this
* administrative_district_level_2 string: A civil entity within the address's administrative_district_level_1.
* administrative_district_level_3 string: A civil entity within the address's administrative_district_level_2,
* country string (values: 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): 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.
* locality string: The city or town of the address.
* organization string: Optional organization name when it's representing recipient.
* postal_code string: The address's postal code.
* sublocality string: A civil region within the address's locality, if any.
* sublocality_2 string: A civil region within the address's sublocality, if any.
* sublocality_3 string: A civil region within the address's sublocality_2, if any.

$3

* BatchDeleteCatalogObjectsRequest object
* object_ids array: The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects
* items string

$3

* BatchDeleteCatalogObjectsResponse object
* deleted_at string: The database timestamp of this deletion in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".
* deleted_object_ids array: The IDs of all CatalogObjects deleted by this request.
* items string
* errors array: The set of Errors encountered.
* items Error

$3

* BatchRetrieveCatalogObjectsRequest object
* include_related_objects boolean: If true, the response will include additional objects that are related to the
* object_ids required array: The IDs of the CatalogObjects to be retrieved.
* items string

$3

* BatchRetrieveCatalogObjectsResponse object
* errors array: The set of Errors encountered.
* items Error
* objects array: A list of CatalogObjects returned.
* items CatalogObject
* related_objects array: A list of CatalogObjects referenced by the object in the objects field.
* items CatalogObject

$3

* BatchUpsertCatalogObjectsRequest object
* batches array: A batch of CatalogObjects to be inserted/updated atomically.
* items CatalogObjectBatch
* idempotency_key required string: A value you specify that uniquely identifies this

$3

* BatchUpsertCatalogObjectsResponse object
* errors array: The set of Errors encountered.
* items Error
* id_mappings array: The mapping between client and server IDs for this Upsert.
* items CatalogIdMapping
* objects array: The created CatalogObjects
* items CatalogObject
* updated_at string: The database timestamp of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".

$3

* CaptureTransactionRequest object

$3

* CaptureTransactionResponse object: Defines the fields that are included in the response body of
* errors array: Any errors that occurred during the request.
* items Error

$3

* Card object: Represents the non-confidential details of a credit card.
* billing_address Address
* card_brand string (values: OTHER_BRAND, VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DISCOVER_DINERS, JCB, CHINA_UNIONPAY, SQUARE_GIFT_CARD): The card's brand (such as VISA). See CardBrand
* cardholder_name string: The cardholder name. This value is present only if this object
* exp_month integer: The month of the card's expiration date. This value is always between
* exp_year integer: The four-digit year of the card's expiration date.
* fingerprint string: The unique string fingerprint for the card.
* id string: The card's unique ID, if any.
* last_4 string: The last 4 digits of the card's number.

$3

* CardBrand string (values: OTHER_BRAND, VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DISCOVER_DINERS, JCB, CHINA_UNIONPAY, SQUARE_GIFT_CARD): Indicates a credit card's brand, such as VISA.

$3

* CatalogCategory object: A category to which an CatalogItem belongs in the Catalog object model.
* name required string: The category's name. Searchable.

$3

* CatalogDiscount object: A discount in the Catalog object model.
* amount_money Money
* discount_type string (values: FIXED_PERCENTAGE, FIXED_AMOUNT, VARIABLE_PERCENTAGE, VARIABLE_AMOUNT): Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.
* label_color string: The color of the discount's display label in the Square Point of Sale app.
* name required string: The discount's name. Searchable.
* percentage string: The percentage of the discount as a string representation of a decimal number, using a . as the decimal
* pin_required boolean: Indicates whether a mobile staff member needs to enter their PIN to apply the

$3

* CatalogDiscountType string (values: FIXED_PERCENTAGE, FIXED_AMOUNT, VARIABLE_PERCENTAGE, VARIABLE_AMOUNT): How to apply a CatalogDiscount to a CatalogItem.

$3

* CatalogIdMapping object: A mapping between a client-supplied temporary ID and a permanent server ID.
* client_object_id string: The client-supplied, temporary #-prefixed ID for a new CatalogObject.
* object_id string: The permanent ID for the CatalogObject created by the server.

$3

* CatalogInfoRequest object

$3

* CatalogInfoResponse object
* errors array: The set of Errors encountered.
* items Error
* limits CatalogInfoResponseLimits

$3

* CatalogInfoResponseLimits object
* batch_delete_max_object_ids integer: The maximum number of object IDs that may be included in a single
* batch_retrieve_max_object_ids integer: The maximum number of object IDs that may appear in a /v2/catalog/batch-retrieve
* 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
* search_max_page_limit integer: The maximum number of results that may be returned in a page of a
* 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_disable integer: The maximum number of modifier list IDs to be disabled that may be included in
* 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
* 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_disable integer: The maximum number of tax IDs to be disabled 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

$3

* CatalogItem object: An item (i.e., product family) in the Catalog object model.
* 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.
* available_electronically boolean: If true, the item can be added to electronically fulfilled orders from the merchant's online store.
* available_for_pickup boolean: If true, the item can be added to pickup orders from the merchant's online store.
* available_online boolean: If true, the item can be added to shipping orders from the merchant's online store.
* category_id string: The ID of the item's category, if any.
* description string: The item's description. Searchable.
* image_url string: The URL of an image representing this item.
* label_color string: The color of the item's display label in the Square Point of Sale app.
* modifier_list_info array: A set of CatalogItemModifierListInfo objects
* items CatalogItemModifierListInfo
* name required string: The item's name. Searchable.
* product_type string (values: REGULAR, GIFT_CARD, APPOINTMENTS_SERVICE, RETAIL_ITEM, RESTAURANT_ITEM): The product type of the item. May not be changed once an item has been created.
* skip_modifier_screen boolean: If false, the Square Point of Sale app will present the CatalogItem's
* tax_ids array: A set of IDs indicating the CatalogTaxes that are enabled for
* items string
* variations array: A list of CatalogObjects containing the CatalogItemVariations for this item.
* items CatalogObject

$3

* CatalogItemModifierListInfo object: Controls the properties of a CatalogModifierList as it applies to this CatalogItem.
* enabled boolean: If true, enable this CatalogModifierList.
* max_selected_modifiers integer: If zero or larger, the largest number of CatalogModifiers that can be selected from this CatalogModifierList.
* min_selected_modifiers integer`: If zero or larger, the smallest number of CatalogModifiers that must be selected from this [CatalogModifierList](#type-catalogmodifierlis