Skip to main content

Square Component

Manage payments, customers, orders, invoices, and team members in Square.

Component key: square · Changelog ↓

Description​

Square is a comprehensive commerce platform that provides payment processing, point-of-sale systems, online store capabilities, and business management tools. This component allows you to manage payments, customers, orders, inventory, invoices, team members, and webhooks in a Square account.

API Documentation​

This component was built using the Square API Documentation

A Note on Square Pagination​

Square's API supports pagination. This means that the API will return up to a specific limit of items for any query. If additional results are available, the API response includes a cursor field that can be used to retrieve the next page of data.

{
  "objects": [],
  "cursor": "next_page_cursor"
}

The cursor can be used in a subsequent query to fetch additional results.

See Square's Docs for information about Square's paginated API, and this quickstart for information on looping over a paginated API in Prismatic.

Connections​

OAuth 2.0​

key: oauth2

To connect to Square using OAuth 2.0, create an application in the Square Developer Portal.

Prerequisites​

Setup Steps​

  1. Navigate to the Square Developer Portal and sign in
  2. Create a new application or select an existing application
  3. In the application settings, navigate to the OAuth section
  4. Add https://oauth2.prismatic.io/callback as a Redirect URL
  5. Configure the required permissions (scopes) for the application based on the integration needs
  6. Copy the Application ID and Application Secret from the Credentials section

Configure the Connection​

  • Enter the Application ID as the Client ID
  • Enter the Application Secret as the Client Secret
  • For Scopes, configure the OAuth permissions the application requires. Refer to the Square OAuth Permissions documentation for available scopes.

Verify Connection​

After configuring the connection, users will be redirected to Square to authorize access to the account. Once authorized, the integration can interact with the Square API on behalf of the user.

InputNotesExample
API Version

Override the default Square API version (2025-08-20). Leave blank to use the default version. See Square API Versioning for version details.

2025-08-20
Authorize URL

The OAuth 2.0 Authorization URL for Square. Select Sandbox for testing or Production for live transactions.

https://connect.squareup.com/oauth2/authorize
Application ID

The Application ID from the Square Developer Dashboard. Navigate to Applications > Your App > Credentials to find this value.

sq0idp-XXXXXXXXXXXXXXXXXXXXXX
Application Secret

The Application Secret from the Square Developer Dashboard. Keep this value secure and never share it publicly.

Scopes

Space separated list of OAuth permission scopes. These scopes should be configured in your Square Application. See Square OAuth Permissions for available scopes.

MERCHANT_PROFILE_READ PAYMENTS_READ
Token URL

The OAuth 2.0 Token URL for Square. This must match the environment selected in the Authorize URL.

https://connect.squareup.com/oauth2/token

Triggers​

Webhook​

Receive and validate webhook requests from Square for webhooks you configure. | key: squareWebhookTrigger

A Square webhook can be configured to send information to a flow's webhook URL under certain conditions (a payment is created, an order is updated, a customer profile is modified, inventory counts change, etc.).

The trigger receives webhook notifications from Square and processes the event data automatically.

A full list of webhook event types is available in the Square Webhook Events Reference.

Data Sources​

Select Bank Accounts​

List and select from all of the bank accounts linked to a Square account. | key: selectBankAccounts | type: picklist

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Connection

The Square connection to use.

Select Catalog​

List and select from all of the catalog objects of the specified types. | key: selectCatalog | type: picklist

InputNotesExample
Catalog Version

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute.

1234567890123
Cursor

A pagination cursor returned by a previous call to this endpoint.

Connection

The Square connection to use.

Types

An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc.

ITEM, CATEGORY, TAX

Select Customers​

List and select from all customer profiles associated with a Square account. | key: selectCustomers | type: picklist

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Sort Field

Field to sort the customers on.

Sort Order

Order to sort the customers.

Connection

The Square connection to use.

Select Invoice​

A picklist of invoices in the Square account. | key: selectInvoice | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Job​

A picklist of jobs in the Square account. | key: selectJob | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Locations​

List and select from all of the seller's locations. | key: selectLocations | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Merchants​

List and select from all of the seller's merchants. | key: selectMerchants | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Order​

A picklist of orders in the Square account. | key: selectOrder | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Payment​

A picklist of payments in the Square account. | key: selectPayment | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Refund​

A picklist of payment refunds in your Square account. | key: selectRefund | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Team Member​

A picklist of team members in the Square account. | key: selectTeamMember | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Webhook Event Types​

List all webhook event types that can be subscribed to. | key: selectWebhookEventTypes | type: picklist

InputNotesExample
Connection

The Square connection to use.

Select Webhook Subscription​

A picklist of webhook subscriptions in the Square account. | key: selectWebhookSubscription | type: picklist

InputNotesExample
Connection

The Square connection to use.

Actions​

Batch Change Inventory​

Applies adjustments and counts to the provided item quantities. | key: batchChangeInventory

InputNotesExample
Inventory Changes

Array of inventory changes in JSON format. See Square Inventory Changes for change types.

Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Ignore Unchanged Counts

When true, unchanged inventory counts will be ignored.

false
Connection

The Square connection to use.

{
  "data": {
    "counts": [
      {
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "L88917AVBK2S5",
        "quantity": "100",
        "calculated_at": "2023-05-18T14:30:00.000Z"
      }
    ],
    "changes": [
      {
        "type": "PHYSICAL_COUNT",
        "physical_count": {
          "id": "M78TNM4H6KPC3A9WR3RWT",
          "reference_id": "inventory-count-001",
          "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
          "catalog_object_type": "ITEM_VARIATION",
          "state": "IN_STOCK",
          "location_id": "L88917AVBK2S5",
          "quantity": "100",
          "employee_id": "1yJlHapkseYnNPETIU1B",
          "occurred_at": "2023-05-18T14:30:00.000Z",
          "created_at": "2023-05-18T14:30:15.000Z"
        }
      }
    ]
  }
}

Batch Delete Catalog Objects​

Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. | key: batchDeleteCatalogObjects

InputNotesExample
Object IDs

Array of catalog object IDs to retrieve in JSON format.

Connection

The Square connection to use.

{
  "data": {
    "deleted_object_ids": [
      "W62UWFY35CWMYGVWK6TWJDNI",
      "X6NH6N2H6TK4W8AD4VFKZL8J"
    ],
    "deleted_at": "2023-05-21T10:30:00.000Z"
  }
}

Batch Retrieve Catalog Objects​

Returns a set of objects based on the provided ID. | key: batchRetrieveCatalogObjects

InputNotesExample
Catalog Version

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute.

1234567890123
Include Deleted Objects

When true, deleted objects will be included in the results.

false
Include Related Objects

When true, the response will include additional objects that are related to the requested objects.

false
Object IDs

Array of catalog object IDs to retrieve in JSON format.

Connection

The Square connection to use.

{
  "data": {
    "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": "BJNQCF2FJ6S6BYQYPG3BMA2C"
        }
      }
    ]
  }
}

Batch Retrieve Inventory Counts​

Returns current counts for the provided CatalogObjects at the requested Locations. | key: batchRetrieveInventoryCounts

InputNotesExample
Catalog Object IDs

Array of catalog object IDs in JSON format to filter inventory results.

Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Location IDs

Array of location IDs in JSON format. Used to filter results to specific locations.

Connection

The Square connection to use.

States

Array of inventory states in JSON format to filter results. Options: IN_STOCK, SOLD, RETURNED_BY_CUSTOMER, etc.

Updated After

The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp.

2024-01-01T00:00:00Z

{
  "data": {
    "counts": [
      {
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "L88917AVBK2S5",
        "quantity": "100",
        "calculated_at": "2023-05-18T14:30:00.000Z"
      },
      {
        "catalog_object_id": "X6NH6N2H6TK4W8AD4VFKZL8J",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "L88917AVBK2S5",
        "quantity": "50",
        "calculated_at": "2023-05-18T14:30:00.000Z"
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

Batch Retrieve Orders​

Retrieves a set of orders by their IDs. | key: batchRetrieveOrders

InputNotesExample
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Order IDs

Array of order IDs to retrieve in JSON format. A maximum of 100 orders can be retrieved per request.

Connection

The Square connection to use.

{
  "data": {
    "orders": [
      {
        "id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
        "location_id": "L88917AVBK2S5",
        "state": "OPEN",
        "version": 1,
        "created_at": "2023-05-08T14:30:00.000Z",
        "updated_at": "2023-05-08T14:30:00.000Z"
      }
    ]
  }
}

Batch Upsert Catalog Objects​

Creates or updates up to 10,000 target objects based on the provided list of objects. | key: batchUpsertCatalogObjects

InputNotesExample
Batches

Array of batches containing catalog objects in JSON format. Each batch may contain up to 1,000 objects. Maximum 10,000 objects total across all batches.

Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Connection

The Square connection to use.

{
  "data": {
    "objects": [
      {
        "type": "ITEM",
        "id": "X6NH6N2H6TK4W8AD4VFKZL8J",
        "updated_at": "2023-05-20T15:30:00.000Z",
        "version": 1684596600000,
        "is_deleted": false,
        "present_at_all_locations": true,
        "item_data": {
          "name": "Coffee"
        }
      }
    ],
    "id_mappings": [
      {
        "client_object_id": "#Coffee",
        "object_id": "X6NH6N2H6TK4W8AD4VFKZL8J"
      }
    ]
  }
}

Cancel Invoice​

Cancel an invoice. | key: cancelInvoice

InputNotesExample
Invoice ID

The ID of the invoice to retrieve.

inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
Connection

The Square connection to use.

{
  "data": {
    "invoice": {
      "id": "gt2j3hd5ci0b3lv",
      "version": 2,
      "location_id": "L88917AVBK2S5",
      "status": "CANCELED",
      "created_at": "2023-05-01T15:00:00Z",
      "updated_at": "2023-05-03T09:00:00Z"
    }
  }
}

Cancel Payment​

Cancels (voids) a payment. | key: cancelPayment

InputNotesExample
Payment ID

A unique ID for the desired payment.

KkAkhdMsgzn59SM8A89WgKwekxLZY
Connection

The Square connection to use.

{
  "data": {
    "payment": {
      "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "created_at": "2023-05-01T21:23:59.255Z",
      "updated_at": "2023-05-01T21:25:00.000Z",
      "amount_money": {
        "amount": 200,
        "currency": "USD"
      },
      "status": "CANCELED",
      "source_type": "CARD",
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "version_token": "dTuGP0LVjY3ND1VUIFi4IvKWXLBqW3OjUf1x"
    }
  }
}

Clone Order​

Creates a new order, in the DRAFT state, by duplicating an existing order. | key: cloneOrder

InputNotesExample
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Order ID

The ID of the order to retrieve.

CAISEHUwyPjyk5QFnMR1k5axW5YgAQ
Connection

The Square connection to use.

{
  "data": {
    "order": {
      "id": "EAISENgvhpdP05f1DWG9H8yMn4kZA",
      "location_id": "L88917AVBK2S5",
      "line_items": [
        {
          "uid": "0wTxgzvUPRF6AiZ",
          "name": "New York Strip Steak",
          "quantity": "1",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        }
      ],
      "state": "DRAFT",
      "version": 1,
      "total_money": {
        "amount": 1599,
        "currency": "USD"
      },
      "created_at": "2023-05-09T11:00:00.000Z",
      "updated_at": "2023-05-09T11:00:00.000Z"
    }
  }
}

Complete Payment​

Completes (captures) a payment. | key: completePayment

InputNotesExample
Payment ID

A unique ID for the desired payment.

KkAkhdMsgzn59SM8A89WgKwekxLZY
Connection

The Square connection to use.

Version Token

Version token for optimistic concurrency control. Identifies the current payment version.

gVCJTjmQHQC2VQCFTe3pRHJsaJl

{
  "data": {
    "payment": {
      "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "created_at": "2023-05-01T21:23:59.255Z",
      "updated_at": "2023-05-01T21:24:30.000Z",
      "amount_money": {
        "amount": 200,
        "currency": "USD"
      },
      "status": "COMPLETED",
      "source_type": "CARD",
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "total_money": {
        "amount": 200,
        "currency": "USD"
      },
      "approved_money": {
        "amount": 200,
        "currency": "USD"
      },
      "version_token": "cTuGP0LVjY3ND1VUIFi4IvKWXLBqW3OjUf1w"
    }
  }
}

Create Customer​

Create a new customer profile. | key: createCustomer

InputNotesExample
Address

The customer's address in JSON format. See Square Address Object for field details.

Birthday

The customer's birthday in YYYY-MM-DD format.

1990-01-15
Company Name

The name of the customer's company.

Acme Corporation
Email Address

The customer's email address.

john.doe@example.com
Family Name

The customer's family name (last name).

Doe
Given Name

The customer's given name (first name).

John
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Nickname

A nickname for the customer.

Johnny
Note

A note to associate with the customer.

Preferred customer - offer special discounts
Phone Number

The customer's phone number in E.164 format (e.g., +14155552671).

+14155552671
Reference Id

An optional reference ID to associate with the customer.

customer-ref-001
Connection

The Square connection to use.

Tax IDs

Tax identification numbers in JSON format. Only applicable for EU countries. See Square Tax IDs for supported formats.

{
  "data": {
    "customer": {
      "id": "8DM2W1WQYG3VXFYGXVF9W9M8N3",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-15T10:00:00.000Z",
      "given_name": "Jane",
      "family_name": "Smith",
      "email_address": "jane.smith@example.com",
      "phone_number": "+1-415-555-2671",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "version": 0
    }
  }
}

Create Job​

Create a job in a seller account with a title and tip eligibility. | key: createJob

InputNotesExample
Idempotency Key

A unique string that identifies this CreateJob request.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Is Tip Eligible

When true, employees in this job role are eligible to receive tips.

true
Job Title

The job designation (e.g., Cashier, Server, Manager).

Cashier
Connection

The Square connection to use.

{
  "data": {
    "job": {
      "id": "1yJlHapkseYnNPETIU1B",
      "title": "Cashier",
      "is_tip_eligible": true,
      "created_at": "2021-06-11T22:55:45Z",
      "updated_at": "2021-06-11T22:55:45Z",
      "version": 1
    }
  }
}

Create Order​

Create a new order. | key: createOrder

InputNotesExample
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Order Object

The complete order object in JSON format. See Square Order Object for field details.

Connection

The Square connection to use.

{
  "data": {
    "order": {
      "id": "DAISENgvhpdP05f1DWG9H8yMn4kZZ",
      "location_id": "L88917AVBK2S5",
      "line_items": [
        {
          "uid": "9vSwfzvUPRF6AiY",
          "name": "Cheeseburger",
          "quantity": "2",
          "base_price_money": {
            "amount": 899,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 1798,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1798,
            "currency": "USD"
          }
        }
      ],
      "state": "OPEN",
      "version": 1,
      "total_money": {
        "amount": 1798,
        "currency": "USD"
      },
      "created_at": "2023-05-09T10:15:00.000Z",
      "updated_at": "2023-05-09T10:15:00.000Z"
    }
  }
}

Create Payment​

Creates a payment using the provided source. | key: createPayment

InputNotesExample
Payment Data

Payment data in JSON format. Amounts are in cents (smallest currency unit). See Square Create Payment for field details.

Connection

The Square connection to use.

{
  "data": {
    "payment": {
      "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "created_at": "2023-05-01T21:23:59.255Z",
      "updated_at": "2023-05-01T21:23:59.446Z",
      "amount_money": {
        "amount": 200,
        "currency": "USD"
      },
      "status": "COMPLETED",
      "source_type": "CARD",
      "card_details": {
        "status": "CAPTURED",
        "card": {
          "card_brand": "VISA",
          "last_4": "1111",
          "exp_month": 11,
          "exp_year": 2023,
          "fingerprint": "sq-1-Tvruf3vPQxlvI6n0IyWZ4YgqXMiL...",
          "card_type": "CREDIT",
          "prepaid_type": "NOT_PREPAID",
          "bin": "411111"
        },
        "entry_method": "KEYED",
        "cvv_status": "CVV_ACCEPTED",
        "avs_status": "AVS_ACCEPTED",
        "statement_description": "SQ *DEFAULT TEST ACCOUNT",
        "card_payment_timeline": {
          "authorized_at": "2023-05-01T21:23:59.255Z",
          "captured_at": "2023-05-01T21:23:59.446Z"
        }
      },
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "risk_evaluation": {
        "created_at": "2023-05-01T21:23:59.255Z",
        "risk_level": "NORMAL"
      },
      "processing_fee": [
        {
          "effective_at": "2023-05-03T21:23:59.255Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": 59,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 200,
        "currency": "USD"
      },
      "approved_money": {
        "amount": 200,
        "currency": "USD"
      },
      "receipt_number": "KkAk",
      "receipt_url": "https://squareup.com/receipt/preview/KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "version_token": "zpCBiO0YgSg5cCEqjUxHQGEuZA9SJBdp1WwI"
    }
  }
}

Create Team Member​

Create a new team member. | key: createTeamMember

InputNotesExample
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Connection

The Square connection to use.

Team Member

The team member data in JSON format. See Square TeamMember Object for field details.

{
  "data": {
    "team_member": {
      "id": "1yJlHapkseYnNPETIU1B",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Joe",
      "family_name": "Doe",
      "email_address": "joe.doe@example.com",
      "phone_number": "+1-415-555-1234",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-15T10:00:00.000Z",
      "assigned_locations": {
        "assignment_type": "EXPLICIT_LOCATIONS",
        "location_ids": [
          "L88917AVBK2S5"
        ]
      }
    }
  }
}

Create Webhook Subscription​

Creates a webhook subscription. | key: createWebhookSubscription

InputNotesExample
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Connection

The Square connection to use.

Webhook Subscription

Webhook subscription data in JSON format. See Square Webhook Subscription for configuration details.

{
  "data": {
    "subscription": {
      "id": "wbhk_c46g7c4256185dg0be624721897d20e6",
      "name": "New Webhook Subscription",
      "enabled": true,
      "event_types": [
        "order.created",
        "order.updated"
      ],
      "notification_url": "https://example.com/webhook/orders",
      "api_version": "2023-05-17",
      "signature_key": "2m0cJLLji1RR...",
      "created_at": "2023-05-16T14:00:00.000Z",
      "updated_at": "2023-05-16T14:00:00.000Z"
    }
  }
}

Delete Catalog Object​

Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. | key: deleteCatalogObject

InputNotesExample
Object ID

The unique identifier of the catalog object.

W62UWFY35CWMYGVWK6TWJDNI
Connection

The Square connection to use.

{
  "data": {
    "deleted_object_ids": [
      "W62UWFY35CWMYGVWK6TWJDNI"
    ],
    "deleted_at": "2023-05-21T10:30:00.000Z"
  }
}

Delete Customer​

Delete a customer profile from a business. | key: deleteCustomer

InputNotesExample
Customer ID

The ID of the customer to retrieve details for.

JDKYHBWT1D4F8MFH63DBMEN8Y4
Connection

The Square connection to use.

{
  "data": {}
}

Delete Instance Webhooks​

Delete all webhooks that point to a flow in this instance | key: deleteInstanceWebhooks

InputNotesExample
Connection

The Square connection to use.

{
  "data": "All webhooks deleted"
}

Delete Invoice​

Delete an invoice. | key: deleteInvoice

InputNotesExample
Invoice ID

The ID of the invoice to retrieve.

inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
Connection

The Square connection to use.

{
  "data": {}
}

Delete Webhook Subscription​

Deletes a webhook subscription. | key: deleteWebhookSubscription

InputNotesExample
Subscription ID

The ID of the Subscription to delete.

wbhk_b35f6b3145074cf9ad513610786c19d5
Connection

The Square connection to use.

{
  "data": {}
}

Get Invoice​

Retrieve an invoice by its ID. | key: getInvoice

InputNotesExample
Invoice ID

The ID of the invoice to retrieve.

inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
Connection

The Square connection to use.

{
  "data": {
    "invoice": {
      "id": "gt2j3hd5ci0b3lv",
      "version": 0,
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "primary_recipient": {
        "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
        "given_name": "Amelia",
        "family_name": "Earhart",
        "email_address": "amelia.earhart@example.com",
        "phone_number": "+1-212-555-4240"
      },
      "payment_requests": [
        {
          "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
          "request_type": "BALANCE",
          "due_date": "2030-01-24",
          "computed_amount_money": {
            "amount": 10000,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      ],
      "invoice_number": "000001",
      "title": "Event Planning Services",
      "description": "We appreciate your business!",
      "scheduled_at": "2030-01-13T10:00:00Z",
      "public_url": "https://squareup.com/pay-invoice/gt2j3hd5ci0b3lv",
      "status": "DRAFT",
      "timezone": "America/Los_Angeles",
      "created_at": "2023-05-01T15:00:00Z",
      "updated_at": "2023-05-01T15:00:00Z",
      "accepted_payment_methods": {
        "card": true,
        "square_gift_card": false,
        "bank_account": false,
        "buy_now_pay_later": false,
        "cash_app_pay": false
      }
    }
  }
}

Get Payment​

Retrieves details for a specific payment. | key: getPayment

InputNotesExample
Payment ID

A unique ID for the desired payment.

KkAkhdMsgzn59SM8A89WgKwekxLZY
Connection

The Square connection to use.

{
  "data": {
    "payment": {
      "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "created_at": "2023-05-01T21:23:59.255Z",
      "updated_at": "2023-05-01T21:23:59.446Z",
      "amount_money": {
        "amount": 200,
        "currency": "USD"
      },
      "status": "COMPLETED",
      "source_type": "CARD",
      "card_details": {
        "status": "CAPTURED",
        "card": {
          "card_brand": "VISA",
          "last_4": "1111",
          "exp_month": 11,
          "exp_year": 2023,
          "fingerprint": "sq-1-Tvruf3vPQxlvI6n0IyWZ4YgqXMiL...",
          "card_type": "CREDIT",
          "prepaid_type": "NOT_PREPAID",
          "bin": "411111"
        },
        "entry_method": "KEYED",
        "cvv_status": "CVV_ACCEPTED",
        "avs_status": "AVS_ACCEPTED",
        "statement_description": "SQ *DEFAULT TEST ACCOUNT",
        "card_payment_timeline": {
          "authorized_at": "2023-05-01T21:23:59.255Z",
          "captured_at": "2023-05-01T21:23:59.446Z"
        }
      },
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "risk_evaluation": {
        "created_at": "2023-05-01T21:23:59.255Z",
        "risk_level": "NORMAL"
      },
      "processing_fee": [
        {
          "effective_at": "2023-05-03T21:23:59.255Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": 59,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 200,
        "currency": "USD"
      },
      "approved_money": {
        "amount": 200,
        "currency": "USD"
      },
      "receipt_number": "KkAk",
      "receipt_url": "https://squareup.com/receipt/preview/KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "version_token": "zpCBiO0YgSg5cCEqjUxHQGEuZA9SJBdp1WwI"
    }
  }
}

Get Payment Refund​

Retrieves a specific refund using the refund_id. | key: getPaymentRefund

InputNotesExample
Refund ID

The unique ID for the desired PaymentRefund.

KTSQvpHJMXp5hUtvZMgKr5EXhfZZY
Connection

The Square connection to use.

{
  "data": {
    "refund": {
      "id": "MgnD48yfyFb4sT0hMYqc0RCduDFZY",
      "status": "COMPLETED",
      "location_id": "L88917AVBK2S5",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "payment_id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "created_at": "2023-05-02T10:15:30.000Z",
      "updated_at": "2023-05-02T10:16:00.000Z",
      "reason": "Customer requested refund",
      "processing_fee": [
        {
          "effective_at": "2023-05-02T10:16:00.000Z",
          "type": "INITIAL",
          "amount_money": {
            "amount": -29,
            "currency": "USD"
          }
        }
      ]
    }
  }
}

List Catalog​

Returns a list of all CatalogObjects of the specified types in the catalog. | key: listCatalog

InputNotesExample
Catalog Version

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute.

1234567890123
Cursor

A pagination cursor returned by a previous call to this endpoint.

Connection

The Square connection to use.

Types

An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc.

ITEM, CATEGORY, TAX

{
  "data": {
    "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": "BJNQCF2FJ6S6BYQYPG3BMA2C",
          "tax_ids": [
            "ZDHQCF2FJ6S6BYQYPG3BMA3E"
          ],
          "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": "Large",
                "ordinal": 1,
                "pricing_type": "FIXED_PRICING",
                "price_money": {
                  "amount": 150,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "cursor": "BwUbDYr9HXzXVmkLu7j5S8fVEoJYo5EZxqBq3Pc2kBa..."
  }
}

List Customers​

List customer profiles associated with a Square account. | key: listCustomers

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Sort Field

Field to sort the customers on.

Sort Order

Order to sort the customers.

Connection

The Square connection to use.

{
  "data": {
    "customers": [
      {
        "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
        "created_at": "2016-03-23T20:21:54.859Z",
        "updated_at": "2016-03-23T20:21:55Z",
        "given_name": "Amelia",
        "family_name": "Earhart",
        "email_address": "amelia.earhart@example.com",
        "address": {
          "address_line_1": "500 Electric Ave",
          "address_line_2": "Suite 600",
          "locality": "New York",
          "administrative_district_level_1": "NY",
          "postal_code": "10003",
          "country": "US"
        },
        "phone_number": "+1-212-555-4240",
        "reference_id": "YOUR_REFERENCE_ID",
        "note": "a customer",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "segment_ids": [
          "gv2:KF92J8MYVJ80E9B7HF1FAC6J1M"
        ],
        "version": 0
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

List Invoices​

Returns a list of invoices for a given location. | key: listInvoices

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Connection

The Square connection to use.

{
  "data": {
    "invoices": [
      {
        "id": "gt2j3hd5ci0b3lv",
        "version": 0,
        "location_id": "L88917AVBK2S5",
        "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
        "primary_recipient": {
          "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
          "given_name": "Amelia",
          "family_name": "Earhart",
          "email_address": "amelia.earhart@example.com"
        },
        "payment_requests": [
          {
            "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
            "request_type": "BALANCE",
            "due_date": "2030-01-24",
            "computed_amount_money": {
              "amount": 10000,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            }
          }
        ],
        "invoice_number": "000001",
        "title": "Event Planning Services",
        "description": "We appreciate your business!",
        "scheduled_at": "2030-01-13T10:00:00Z",
        "public_url": "https://squareup.com/pay-invoice/gt2j3hd5ci0b3lv",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2023-05-01T15:00:00Z",
        "updated_at": "2023-05-01T15:00:00Z"
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

List Jobs​

List jobs in a seller account, sorted by title in ascending order. | key: listJobs

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Fetch All

When true, fetches all pages of results using pagination.

false
Connection

The Square connection to use.

{
  "data": {
    "jobs": [
      {
        "id": "VDNpRv8da51NU8qZFC5zDWpF",
        "title": "Cashier",
        "is_tip_eligible": true,
        "created_at": "2021-06-11T22:55:45Z",
        "updated_at": "2021-06-11T22:55:45Z",
        "version": 2
      },
      {
        "id": "1yJlHapkseYnNPETIU1B",
        "title": "Server",
        "is_tip_eligible": true,
        "created_at": "2021-06-12T10:30:00Z",
        "updated_at": "2021-06-12T10:30:00Z",
        "version": 1
      }
    ]
  }
}

List Locations​

List all of the seller's locations, including those with an inactive status. | key: listLocations

InputNotesExample
Connection

The Square connection to use.

{
  "data": {
    "locations": [
      {
        "id": "L88917AVBK2S5",
        "name": "Downtown Store",
        "address": {
          "address_line_1": "123 Main St",
          "locality": "San Francisco",
          "administrative_district_level_1": "CA",
          "postal_code": "94103",
          "country": "US"
        },
        "timezone": "America/Los_Angeles",
        "capabilities": [
          "CREDIT_CARD_PROCESSING",
          "AUTOMATIC_TRANSFERS"
        ],
        "status": "ACTIVE",
        "created_at": "2022-02-19T17:58:25Z",
        "merchant_id": "ML82H4QPKMGXY",
        "country": "US",
        "language_code": "en-US",
        "currency": "USD",
        "phone_number": "+1 415-555-1234",
        "business_name": "Example Business",
        "type": "PHYSICAL",
        "business_email": "hello@example.com"
      }
    ]
  }
}

List Payment Refunds​

Retrieves a list of refunds for the account making the request. | key: listPaymentRefunds

InputNotesExample
Begin Time

Return objects modified after this timestamp, in RFC 3339 format.

2024-01-01T00:00:00Z
Cursor

A pagination cursor returned by a previous call to this endpoint.

End Time

End of the time range to retrieve payments for in RFC 3339 format. Filtered using the created_at field.

2024-12-31T23:59:59Z
Limit

The maximum number of results to be returned in a single page.

100
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Sort Order

Order to sort the customers.

Source Type

If provided, only returns refunds whose payments have the indicated source type.

CARD
Connection

The Square connection to use.

Status

If provided, only refunds with the given status are returned.

COMPLETED

{
  "data": {
    "refunds": [
      {
        "id": "MgnD48yfyFb4sT0hMYqc0RCduDFZY",
        "status": "COMPLETED",
        "location_id": "L88917AVBK2S5",
        "amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "payment_id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
        "created_at": "2023-05-02T10:15:30.000Z",
        "updated_at": "2023-05-02T10:16:00.000Z"
      }
    ],
    "cursor": "5Dkfj4JXW8dJxBSXVYEIWkOcW9h8PBDyQg..."
  }
}

List Payments​

Retrieves a list of payments taken by the account making the request. | key: listPayments

InputNotesExample
Begin Time

Return objects modified after this timestamp, in RFC 3339 format.

2024-01-01T00:00:00Z
Card Brand

The brand of the payment card (for example, VISA, MASTERCARD, AMEX).

VISA
Cursor

A pagination cursor returned by a previous call to this endpoint.

End Time

End of the time range to retrieve payments for in RFC 3339 format. Filtered using the created_at field.

2024-12-31T23:59:59Z
Last 4 digits of Card

The last four digits of a payment card.

1234
Limit

The maximum number of results to be returned in a single page.

100
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Sort Order

Order to sort the customers.

Connection

The Square connection to use.

Total

The exact payment amount in cents (smallest currency unit). For example, 1500 for $15.00.

1500

{
  "data": {
    "payments": [
      {
        "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
        "created_at": "2023-05-01T21:23:59.255Z",
        "updated_at": "2023-05-01T21:23:59.446Z",
        "amount_money": {
          "amount": 200,
          "currency": "USD"
        },
        "status": "COMPLETED",
        "source_type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "VISA",
            "last_4": "1111",
            "exp_month": 11,
            "exp_year": 2023,
            "fingerprint": "sq-1-Tvruf3vPQxlvI6n0IyWZ4YgqXMiL...",
            "card_type": "CREDIT",
            "prepaid_type": "NOT_PREPAID",
            "bin": "411111"
          },
          "entry_method": "KEYED",
          "cvv_status": "CVV_ACCEPTED",
          "avs_status": "AVS_ACCEPTED",
          "statement_description": "SQ *DEFAULT TEST ACCOUNT",
          "card_payment_timeline": {
            "authorized_at": "2023-05-01T21:23:59.255Z",
            "captured_at": "2023-05-01T21:23:59.446Z"
          }
        },
        "location_id": "L88917AVBK2S5",
        "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
        "risk_evaluation": {
          "created_at": "2023-05-01T21:23:59.255Z",
          "risk_level": "NORMAL"
        },
        "processing_fee": [
          {
            "effective_at": "2023-05-03T21:23:59.255Z",
            "type": "INITIAL",
            "amount_money": {
              "amount": 59,
              "currency": "USD"
            }
          }
        ],
        "total_money": {
          "amount": 200,
          "currency": "USD"
        },
        "approved_money": {
          "amount": 200,
          "currency": "USD"
        },
        "receipt_number": "KkAk",
        "receipt_url": "https://squareup.com/receipt/preview/KkAkhdMsgzn59SM8A89WgKwekxLZY",
        "delay_action": "CANCEL",
        "delayed_until": "2023-05-08T21:23:59.255Z",
        "version_token": "zpCBiO0YgSg5cCEqjUxHQGEuZA9SJBdp1WwI"
      }
    ],
    "cursor": "5Ckfj4JXW8dJxBSXVYEIWkOcW9h8PBDyQf..."
  }
}

List Webhook Subscriptions​

Lists all webhook subscriptions owned by your application. | key: listWebhookSubscriptions

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Include Disabled

When true, includes disabled Subscriptions. By default, only enabled Subscriptions are returned.

false
Limit

The maximum number of results to be returned in a single page.

100
Sort Order

Sort order for subscriptions by creation date. Options: ASC (oldest first), DESC (newest first).

DESC
Connection

The Square connection to use.

{
  "data": {
    "subscriptions": [
      {
        "id": "wbhk_b35f6b3145074cf9ad513610786c19d5",
        "name": "Example Webhook Subscription",
        "enabled": true,
        "event_types": [
          "payment.created",
          "payment.updated"
        ],
        "notification_url": "https://example.com/webhook",
        "api_version": "2023-05-17",
        "created_at": "2023-05-15T10:00:00.000Z",
        "updated_at": "2023-05-15T10:00:00.000Z"
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

Publish Invoice​

Publish an invoice. | key: publishInvoice

InputNotesExample
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Invoice ID

The ID of the invoice to retrieve.

inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
Connection

The Square connection to use.

{
  "data": {
    "invoice": {
      "id": "gt2j3hd5ci0b3lv",
      "version": 1,
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "primary_recipient": {
        "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4"
      },
      "payment_requests": [
        {
          "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
          "request_type": "BALANCE",
          "due_date": "2030-01-24",
          "computed_amount_money": {
            "amount": 10000,
            "currency": "USD"
          }
        }
      ],
      "invoice_number": "000001",
      "title": "Event Planning Services",
      "public_url": "https://squareup.com/pay-invoice/gt2j3hd5ci0b3lv",
      "status": "UNPAID",
      "timezone": "America/Los_Angeles",
      "created_at": "2023-05-01T15:00:00Z",
      "updated_at": "2023-05-02T11:00:00Z"
    }
  }
}

Raw Request​

Send raw HTTP request to Square | key: rawRequest

InputNotesExample
Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Connection

The Square connection to use.

Timeout

The maximum time that a client will await a response to its request

2000
URL

This is the URL to call.

/v2/locations
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

{
  "data": {
    "locations": [
      {
        "id": "L88917AVBK2S5",
        "name": "Downtown Store",
        "status": "ACTIVE"
      }
    ]
  }
}

Refund Payment​

Refunds a payment. You can refund the entire payment amount or a portion of it. | key: refundPayment

InputNotesExample
Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Payment ID

A unique ID for the desired payment.

KkAkhdMsgzn59SM8A89WgKwekxLZY
Reason

A description of the reason for the refund.

Customer requested refund due to defective product
Refund Amount

The refund amount in JSON format. Amount is in cents (smallest currency unit). Cannot exceed the payment total minus previous refunds.

Connection

The Square connection to use.

{
  "data": {
    "refund": {
      "id": "MgnD48yfyFb4sT0hMYqc0RCduDFZY",
      "status": "PENDING",
      "location_id": "L88917AVBK2S5",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "payment_id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "created_at": "2023-05-02T10:15:30.000Z",
      "updated_at": "2023-05-02T10:15:30.000Z",
      "reason": "Customer requested refund"
    }
  }
}

Retrieve Catalog Object​

Returns a single CatalogObject based on the provided ID. | key: retrieveCatalogObject

InputNotesExample
Catalog Version

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute.

1234567890123
Include Related Objects

When true, the response will include additional objects that are related to the requested objects.

false
Object ID

The unique identifier of the catalog object.

W62UWFY35CWMYGVWK6TWJDNI
Connection

The Square connection to use.

{
  "data": {
    "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": "BJNQCF2FJ6S6BYQYPG3BMA2C",
        "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": "Large",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 150,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  }
}

Retrieve Customer​

Retrieve details for a single customer. | key: retrieveCustomer

InputNotesExample
Customer ID

The ID of the customer to retrieve details for.

JDKYHBWT1D4F8MFH63DBMEN8Y4
Connection

The Square connection to use.

{
  "data": {
    "customer": {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2016-03-23T20:21:54.859Z",
      "updated_at": "2023-05-10T14:30:00Z",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "amelia.earhart@example.com",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "+1-212-555-4240",
      "reference_id": "YOUR_REFERENCE_ID",
      "note": "a customer",
      "birthday": "1897-07-24",
      "preferences": {
        "email_unsubscribed": false
      },
      "creation_source": "THIRD_PARTY",
      "segment_ids": [
        "gv2:KF92J8MYVJ80E9B7HF1FAC6J1M"
      ],
      "version": 3
    }
  }
}

Retrieve Job​

Retrieve a specified job by ID. | key: retrieveJob

InputNotesExample
Job ID

The unique identifier of the job.

1yJlHapkseYnNPETIU1B
Connection

The Square connection to use.

{
  "data": {
    "job": {
      "id": "1yJlHapkseYnNPETIU1B",
      "title": "Cashier",
      "is_tip_eligible": true,
      "created_at": "2021-06-11T22:55:45Z",
      "updated_at": "2021-06-11T22:55:45Z",
      "version": 2
    }
  }
}

Retrieve Location​

Retrieves details of a specific location. | key: retrieveLocation

InputNotesExample
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Connection

The Square connection to use.

{
  "data": {
    "location": {
      "id": "L88917AVBK2S5",
      "name": "Downtown Store",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING",
        "AUTOMATIC_TRANSFERS"
      ],
      "status": "ACTIVE",
      "created_at": "2022-02-19T17:58:25Z",
      "merchant_id": "ML82H4QPKMGXY",
      "country": "US",
      "language_code": "en-US",
      "currency": "USD",
      "phone_number": "+1 415-555-1234",
      "business_name": "Example Business",
      "type": "PHYSICAL",
      "business_email": "hello@example.com",
      "description": "Our main downtown location",
      "business_hours": {
        "periods": [
          {
            "day_of_week": "MON",
            "start_local_time": "09:00",
            "end_local_time": "17:00"
          }
        ]
      }
    }
  }
}

Retrieve Order​

Retrieves an Order by its ID. | key: retrieveOrder

InputNotesExample
Order ID

The ID of the order to retrieve.

CAISEHUwyPjyk5QFnMR1k5axW5YgAQ
Connection

The Square connection to use.

{
  "data": {
    "order": {
      "id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "location_id": "L88917AVBK2S5",
      "line_items": [
        {
          "uid": "8uSwfzvUPRF6AiX",
          "name": "New York Strip Steak",
          "quantity": "1",
          "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
          "catalog_version": 1479335124878,
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_tax_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_discount_money": {
            "amount": 0,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        }
      ],
      "fulfillments": [
        {
          "uid": "zQtAx35fPVLLx6V",
          "type": "PICKUP",
          "state": "PROPOSED",
          "pickup_details": {
            "recipient": {
              "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
              "display_name": "John Doe",
              "email_address": "john.doe@example.com",
              "phone_number": "+1-415-555-1234"
            },
            "schedule_type": "SCHEDULED",
            "pickup_at": "2023-05-10T18:00:00Z",
            "pickup_window_duration": "PT30M"
          }
        }
      ],
      "state": "OPEN",
      "version": 1,
      "total_money": {
        "amount": 1599,
        "currency": "USD"
      },
      "total_tax_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_discount_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "total_service_charge_money": {
        "amount": 0,
        "currency": "USD"
      },
      "created_at": "2023-05-08T14:30:00.000Z",
      "updated_at": "2023-05-08T14:30:00.000Z",
      "source": {
        "name": "My App"
      }
    }
  }
}

Retrieve Team Member​

Retrieve a team member based on the provided ID. | key: retrieveTeamMember

InputNotesExample
Connection

The Square connection to use.

Team Member ID

The ID of the TeamMember to be retrieved.

1yJlHapkseYnNPETIU1B

{
  "data": {
    "team_member": {
      "id": "1yJlHapkseYnNPETIU1B",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Joe",
      "family_name": "Doe",
      "email_address": "joe.doe@example.com",
      "phone_number": "+1-415-555-1234",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-15T10:00:00.000Z",
      "assigned_locations": {
        "assignment_type": "EXPLICIT_LOCATIONS",
        "location_ids": [
          "L88917AVBK2S5"
        ]
      }
    }
  }
}

Retrieve Webhook Subscription​

Retrieves a webhook subscription identified by its ID. | key: retrieveWebhookSubscription

InputNotesExample
Connection

The Square connection to use.

Subscription ID

The ID of the Subscription to retrieve.

wbhk_b35f6b3145074cf9ad513610786c19d5

{
  "data": {
    "subscription": {
      "id": "wbhk_b35f6b3145074cf9ad513610786c19d5",
      "name": "Example Webhook Subscription",
      "enabled": true,
      "event_types": [
        "payment.created",
        "payment.updated",
        "refund.created",
        "refund.updated"
      ],
      "notification_url": "https://example.com/webhook",
      "api_version": "2023-05-17",
      "signature_key": "1k9bIJKhi0QQ...",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-15T10:00:00.000Z"
    }
  }
}

Search Catalog Items​

Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters. | key: searchCatalogItems

InputNotesExample
Category IDs

Array of category IDs in JSON format to filter items by category.

Cursor

A pagination cursor returned by a previous call to this endpoint.

Custom Attribute Filters

Array of custom attribute filters in JSON format to match items with specific custom attributes.

Enabled Location IDs

Array of location IDs in JSON format to filter items by enabled locations.

Limit

The maximum number of results to be returned in a single page.

100
Product Types

Array of product types in JSON format to filter items. Options: REGULAR, APPOINTMENTS_SERVICE.

Sort Order

Order to sort the customers.

Connection

The Square connection to use.

Stock Levels

Array of stock levels in JSON format to filter items. Options: OUT, LOW.

Text Filter

The text filter expression to return items or item variations containing specified text.

coffee mug

{
  "data": {
    "items": [
      {
        "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": "BJNQCF2FJ6S6BYQYPG3BMA2C",
          "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": "Large",
                "ordinal": 1,
                "pricing_type": "FIXED_PRICING",
                "price_money": {
                  "amount": 150,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      }
    ],
    "cursor": "BwUbDYr9HXzXVmkLu7j5S8fVEoJYo5EZxqBq3Pc2kBa..."
  }
}

Search Catalog Objects​

Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters. | key: searchCatalogObjects

InputNotesExample
Begin Time

Return objects modified after this timestamp, in RFC 3339 format.

2024-01-01T00:00:00Z
Catalog Query

Query to filter or sort catalog results in JSON format. See Square Catalog Query for query options.

Cursor

A pagination cursor returned by a previous call to this endpoint.

Include Deleted Objects

When true, deleted objects will be included in the results.

false
Include Related Objects

When true, the response will include additional objects that are related to the requested objects.

false
Limit

The maximum number of results to be returned in a single page.

100
Object Types

Comma-separated list of catalog object types to include in search results. Options: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, etc.

ITEM,CATEGORY,TAX
Connection

The Square connection to use.

{
  "data": {
    "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": "BJNQCF2FJ6S6BYQYPG3BMA2C"
        }
      }
    ],
    "cursor": "BwUbDYr9HXzXVmkLu7j5S8fVEoJYo5EZxqBq3Pc2kBa..."
  }
}

Search Customers​

Search customer profiles. | key: searchCustomers

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Query

The query to search for customers. See Square Search Customers for filter and sort options.

Connection

The Square connection to use.

{
  "data": {
    "customers": [
      {
        "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
        "created_at": "2016-03-23T20:21:54.859Z",
        "updated_at": "2016-03-23T20:21:55Z",
        "given_name": "Amelia",
        "family_name": "Earhart",
        "email_address": "amelia.earhart@example.com",
        "preferences": {
          "email_unsubscribed": false
        },
        "creation_source": "THIRD_PARTY",
        "version": 0
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

Search Invoices​

Searches for invoices from a location specified in the filter. | key: searchInvoices

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Query

The query to search for invoices. See Square Search Invoices for filter and sort options.

Limit

The maximum number of results to be returned in a single page.

100
Connection

The Square connection to use.

{
  "data": {
    "invoices": [
      {
        "id": "gt2j3hd5ci0b3lv",
        "version": 0,
        "location_id": "L88917AVBK2S5",
        "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
        "primary_recipient": {
          "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
          "given_name": "Amelia",
          "family_name": "Earhart",
          "email_address": "amelia.earhart@example.com"
        },
        "payment_requests": [
          {
            "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
            "request_type": "BALANCE",
            "due_date": "2030-01-24",
            "computed_amount_money": {
              "amount": 10000,
              "currency": "USD"
            },
            "total_completed_amount_money": {
              "amount": 0,
              "currency": "USD"
            }
          }
        ],
        "invoice_number": "000001",
        "title": "Event Planning Services",
        "description": "We appreciate your business!",
        "scheduled_at": "2030-01-13T10:00:00Z",
        "public_url": "https://squareup.com/pay-invoice/gt2j3hd5ci0b3lv",
        "status": "DRAFT",
        "timezone": "America/Los_Angeles",
        "created_at": "2023-05-01T15:00:00Z",
        "updated_at": "2023-05-01T15:00:00Z"
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

Search Orders​

Search all orders for one or more locations. | key: searchOrders

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Location IDs

Array of location IDs in JSON format. Used to filter results to specific locations.

Query

The query to search for orders. See Square Search Orders for filter and sort options.

Return Entries

When true, the entries associated with the orders will be returned.

true
Connection

The Square connection to use.

{
  "data": {
    "orders": [
      {
        "id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
        "location_id": "L88917AVBK2S5",
        "line_items": [
          {
            "uid": "8uSwfzvUPRF6AiX",
            "name": "New York Strip Steak",
            "quantity": "1",
            "base_price_money": {
              "amount": 1599,
              "currency": "USD"
            },
            "gross_sales_money": {
              "amount": 1599,
              "currency": "USD"
            },
            "total_tax_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_discount_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_money": {
              "amount": 1599,
              "currency": "USD"
            }
          }
        ],
        "fulfillments": [
          {
            "uid": "zQtAx35fPVLLx6V",
            "type": "PICKUP",
            "state": "PROPOSED",
            "pickup_details": {
              "recipient": {
                "display_name": "John Doe",
                "phone_number": "+1-415-555-1234"
              },
              "schedule_type": "SCHEDULED",
              "pickup_at": "2023-05-10T18:00:00Z"
            }
          }
        ],
        "state": "OPEN",
        "version": 1,
        "total_money": {
          "amount": 1599,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_tip_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_service_charge_money": {
          "amount": 0,
          "currency": "USD"
        },
        "created_at": "2023-05-08T14:30:00.000Z",
        "updated_at": "2023-05-08T14:30:00.000Z"
      }
    ],
    "cursor": "5Ekfj4JXW8dJxBSXVYEIWkOcW9h8PBDyQh..."
  }
}

Search Team Members​

Search for team members based on given filters. | key: searchTeamMembers

InputNotesExample
Cursor

A pagination cursor returned by a previous call to this endpoint.

Limit

The maximum number of results to be returned in a single page.

100
Search Query

The query parameters to filter team members. See Square Search Team Members for filter options.

Connection

The Square connection to use.

{
  "data": {
    "team_members": [
      {
        "id": "1yJlHapkseYnNPETIU1B",
        "is_owner": false,
        "status": "ACTIVE",
        "given_name": "Joe",
        "family_name": "Doe",
        "email_address": "joe.doe@example.com",
        "phone_number": "+1-415-555-1234",
        "created_at": "2023-05-15T10:00:00.000Z",
        "updated_at": "2023-05-15T10:00:00.000Z"
      }
    ],
    "cursor": "MTY1Njk2OTU5NjEzMjAwMDAwMA=="
  }
}

Update Customer​

Update a customer profile. | key: updateCustomer

InputNotesExample
Address

The customer's address in JSON format. See Square Address Object for field details.

Birthday

The customer's birthday in YYYY-MM-DD format.

1990-01-15
Company Name

The name of the customer's company.

Acme Corporation
Customer ID

The ID of the customer to retrieve details for.

JDKYHBWT1D4F8MFH63DBMEN8Y4
Email Address

The customer's email address.

john.doe@example.com
Family Name

The customer's family name (last name).

Doe
Given Name

The customer's given name (first name).

John
Nickname

A nickname for the customer.

Johnny
Note

A note to associate with the customer.

Preferred customer - offer special discounts
Phone Number

The customer's phone number in E.164 format (e.g., +14155552671).

+14155552671
Reference Id

An optional reference ID to associate with the customer.

customer-ref-001
Connection

The Square connection to use.

Tax IDs

Tax identification numbers in JSON format. Only applicable for EU countries. See Square Tax IDs for supported formats.

{
  "data": {
    "customer": {
      "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "created_at": "2016-03-23T20:21:54.859Z",
      "updated_at": "2023-05-16T11:22:33.000Z",
      "given_name": "Amelia",
      "family_name": "Earhart-Smith",
      "email_address": "amelia.earhart@example.com",
      "address": {
        "address_line_1": "500 Electric Ave",
        "address_line_2": "Suite 600",
        "locality": "New York",
        "administrative_district_level_1": "NY",
        "postal_code": "10003",
        "country": "US"
      },
      "phone_number": "+1-212-555-4240",
      "note": "Updated customer information",
      "preferences": {
        "email_unsubscribed": false
      },
      "version": 4
    }
  }
}

Update Invoice​

Update an invoice. | key: updateInvoice

InputNotesExample
Invoice ID

The ID of the invoice to retrieve.

inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
Connection

The Square connection to use.

Update Invoice

The invoice data to update in JSON format. See Square Update Invoice for field details.

{
  "data": {
    "invoice": {
      "id": "gt2j3hd5ci0b3lv",
      "version": 1,
      "location_id": "L88917AVBK2S5",
      "order_id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "primary_recipient": {
        "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
        "given_name": "Amelia",
        "family_name": "Earhart",
        "email_address": "amelia.earhart@example.com"
      },
      "payment_requests": [
        {
          "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
          "request_type": "BALANCE",
          "due_date": "2030-01-25",
          "computed_amount_money": {
            "amount": 12000,
            "currency": "USD"
          },
          "total_completed_amount_money": {
            "amount": 0,
            "currency": "USD"
          }
        }
      ],
      "invoice_number": "000001",
      "title": "Event Planning Services - Updated",
      "description": "Updated invoice details",
      "status": "DRAFT",
      "timezone": "America/Los_Angeles",
      "created_at": "2023-05-01T15:00:00Z",
      "updated_at": "2023-05-02T10:00:00Z"
    }
  }
}

Update Job​

Update the title or tip eligibility of a job. Changes propagate to all job assignments, shifts, and wage settings. | key: updateJob

InputNotesExample
Is Tip Eligible

When true, employees in this job role are eligible to receive tips. Only include if changing tip eligibility.

true
Job ID

The unique identifier of the job.

1yJlHapkseYnNPETIU1B
Job Title

Updated job title. Only include if changing the title.

Cashier
Connection

The Square connection to use.

Version

Version number for optimistic concurrency control. Ensures the object hasn't been modified by another request.

1

{
  "data": {
    "job": {
      "id": "1yJlHapkseYnNPETIU1B",
      "title": "Senior Cashier",
      "is_tip_eligible": true,
      "created_at": "2021-06-11T22:55:45Z",
      "updated_at": "2021-06-13T12:55:45Z",
      "version": 2
    }
  }
}

Update Location​

Updates a location associated with a Square account. | key: updateLocation

InputNotesExample
Location ID

The ID of the location to retrieve details for.

LH2G9VFHJRWKR
Location Update

The location data to update in JSON format. See Square Location Object for field details.

Connection

The Square connection to use.

{
  "data": {
    "location": {
      "id": "L88917AVBK2S5",
      "name": "Downtown Store - Updated",
      "address": {
        "address_line_1": "123 Main St",
        "address_line_2": "Suite 200",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "capabilities": [
        "CREDIT_CARD_PROCESSING",
        "AUTOMATIC_TRANSFERS"
      ],
      "status": "ACTIVE",
      "created_at": "2022-02-19T17:58:25Z",
      "merchant_id": "ML82H4QPKMGXY",
      "country": "US",
      "language_code": "en-US",
      "currency": "USD",
      "phone_number": "+1 415-555-5678",
      "business_name": "Example Business",
      "type": "PHYSICAL",
      "business_email": "hello@example.com",
      "description": "Our updated main downtown location"
    }
  }
}

Update Order​

Updates an open order by adding, replacing, or deleting fields. | key: updateOrder

InputNotesExample
Fields to Clear

Array of dot notation paths for fields to clear in JSON format. For example: line_items[uid].note or discounts[uid].

Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Order ID

The ID of the order to retrieve.

CAISEHUwyPjyk5QFnMR1k5axW5YgAQ
Order Object

The complete order object in JSON format. See Square Order Object for field details.

Connection

The Square connection to use.

{
  "data": {
    "order": {
      "id": "CAISENgvhpdP05f1DWG9H8yMn4kZY",
      "location_id": "L88917AVBK2S5",
      "line_items": [
        {
          "uid": "8uSwfzvUPRF6AiX",
          "name": "New York Strip Steak",
          "quantity": "2",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "gross_sales_money": {
            "amount": 3198,
            "currency": "USD"
          },
          "total_money": {
            "amount": 3198,
            "currency": "USD"
          }
        }
      ],
      "state": "OPEN",
      "version": 2,
      "total_money": {
        "amount": 3198,
        "currency": "USD"
      },
      "created_at": "2023-05-08T14:30:00.000Z",
      "updated_at": "2023-05-08T15:00:00.000Z"
    }
  }
}

Update Payment​

Updates a payment with the APPROVED status. | key: updatePayment

InputNotesExample
Payment

Payment data in JSON format. Amounts are in cents (smallest currency unit). See Square Payment Object for field details.

Payment ID

A unique ID for the desired payment.

KkAkhdMsgzn59SM8A89WgKwekxLZY
Connection

The Square connection to use.

{
  "data": {
    "payment": {
      "id": "KkAkhdMsgzn59SM8A89WgKwekxLZY",
      "created_at": "2023-05-01T21:23:59.255Z",
      "updated_at": "2023-05-01T21:30:00.000Z",
      "amount_money": {
        "amount": 200,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 30,
        "currency": "USD"
      },
      "total_money": {
        "amount": 230,
        "currency": "USD"
      },
      "approved_money": {
        "amount": 230,
        "currency": "USD"
      },
      "status": "APPROVED",
      "source_type": "CARD",
      "version_token": "bTuGP0LVjY3ND1VUIFi4IvKWXLBqW3OjUf1v"
    }
  }
}

Update Team Member​

Update a team member. | key: updateTeamMember

InputNotesExample
Connection

The Square connection to use.

Team Member

The team member data in JSON format. See Square TeamMember Object for field details.

Team Member ID

The ID of the TeamMember to be retrieved.

1yJlHapkseYnNPETIU1B

{
  "data": {
    "team_member": {
      "id": "1yJlHapkseYnNPETIU1B",
      "is_owner": false,
      "status": "ACTIVE",
      "given_name": "Joseph",
      "family_name": "Doe",
      "email_address": "joseph.doe@example.com",
      "phone_number": "+1-415-555-1234",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-16T11:30:00.000Z",
      "assigned_locations": {
        "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
      }
    }
  }
}

Update Webhook Subscription​

Updates a webhook subscription. | key: updateWebhookSubscription

InputNotesExample
Connection

The Square connection to use.

Subscription ID

The ID of the Subscription to retrieve.

wbhk_b35f6b3145074cf9ad513610786c19d5
Webhook Subscription

Updated webhook subscription data in JSON format. Only include fields you want to modify.

{
  "data": {
    "subscription": {
      "id": "wbhk_b35f6b3145074cf9ad513610786c19d5",
      "name": "Updated Webhook Subscription",
      "enabled": true,
      "event_types": [
        "payment.created",
        "payment.updated",
        "order.created"
      ],
      "notification_url": "https://example.com/webhook/updated",
      "api_version": "2023-05-17",
      "signature_key": "1k9bIJKhi0QQ...",
      "created_at": "2023-05-15T10:00:00.000Z",
      "updated_at": "2023-05-17T09:00:00.000Z"
    }
  }
}

Upsert Catalog Object​

Creates a new or updates the specified CatalogObject. | key: upsertCatalogObject

InputNotesExample
Catalog Object

Catalog object data in JSON format. See Square Catalog Object for field details.

Idempotency Key

A unique string that identifies this request to ensure idempotent operations.

a7c8e4b1-3f5d-4e2a-9c1b-7d3e5f8a2c6b
Connection

The Square connection to use.

{
  "data": {
    "catalog_object": {
      "type": "ITEM",
      "id": "X6NH6N2H6TK4W8AD4VFKZL8J",
      "updated_at": "2023-05-20T15:30:00.000Z",
      "version": 1684596600000,
      "is_deleted": false,
      "present_at_all_locations": true,
      "item_data": {
        "name": "Coffee",
        "description": "Fresh brewed coffee",
        "category_id": "BJNQCF2FJ6S6BYQYPG3BMA2C",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "3TZFAOHWGG7PAK2QEXWYPZTP",
            "updated_at": "2023-05-20T15:30:00.000Z",
            "version": 1684596600000,
            "is_deleted": false,
            "present_at_all_locations": true,
            "item_variation_data": {
              "item_id": "X6NH6N2H6TK4W8AD4VFKZL8J",
              "name": "Regular",
              "ordinal": 1,
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250,
                "currency": "USD"
              }
            }
          }
        ]
      }
    },
    "id_mappings": [
      {
        "client_object_id": "#Coffee",
        "object_id": "X6NH6N2H6TK4W8AD4VFKZL8J"
      }
    ]
  }
}

Changelog​

2026-03-31​

Various modernizations and documentation updates

2026-02-26​

Added inline data source for refunds to enable dynamic dropdown selection

2025-11-17​

Added Jobs API support with actions for managing jobs:

  • List Jobs - List jobs in a seller account, sorted by title
  • Create Job - Create a new job with title and tip eligibility
  • Retrieve Job - Retrieve a specific job by ID
  • Update Job - Update job title, tip eligibility, or version

Added inline data sources for Jobs, Team Members, Invoices, Orders, Payments, and Webhook Subscriptions to enhance data selection capabilities