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​

Square OAuth 2.0​

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

The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order.

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

The IDs of the CatalogObjects to be retrieved.

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

The IDs of the CatalogObjects to be retrieved.

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

The filter to return results by CatalogObject ID.

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. These IDs will be used to filter the results to specific locations.

Connection

The Square connection to use.

States

The filter to return results by InventoryState.

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

The IDs of the orders to retrieve. 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

A list of batches of CatalogObjects to be inserted/updated atomically. Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.

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

Used for optimistic concurrency. This token 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

Address in JSON format

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 IDs in JSON format

{
  "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, the job is eligible for tips. Defaults to true if not specified.

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. Please refer to the Square API documentation for the structure of this object.

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

The payment data object containing all necessary information for creating the payment.

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 data which will be used to create the TeamMember object.

{
  "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

The Subscription to create.

{
  "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 object ID of any type of catalog objects to be retrieved.

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

Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment.

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

Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment.

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 amount in the total_money for a payment (in the smallest currency unit, e.g., cents).

1000

{
  "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

Sorts the returned list by when the Subscription was created with the specified order. Options: ASC, DESC

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 amount of money to refund. This amount cannot be more than the total_money value of the payment minus the total amount of all previously completed refunds for this payment.

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 object ID of any type of catalog objects to be retrieved.

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

The category id query expression to return items containing the specified category IDs.

Cursor

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

Custom Attribute Filters

The customer-attribute filter to return items or item variations matching the specified custom attribute expressions.

Enabled Location IDs

The enabled-location query expression to return items and item variations having specified enabled locations.

Limit

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

100
Product Types

The product types query expression to return items or item variations having the specified product types.

Sort Order

Order to sort the customers.

Connection

The Square connection to use.

Stock Levels

The stock-level query expression to return item variations with the specified stock levels.

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

A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.

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

The desired set of object types to appear in the search results.

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. Please refer to the Square API documentation for the structure and options of this query.

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. Please refer to the Square API documentation for the structure and options of this query.

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. These IDs will be used to filter the results to specific locations.

Query

The query to search for orders. Please refer to the Square API documentation for the structure and options of this query.

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 the TeamMember objects.

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

Address in JSON format

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 IDs in JSON format

{
  "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 data to update an invoice. Please refer to the Square API documentation for the structure and options of this update.

{
  "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

Updated tip eligibility. 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

The current version of the object for optimistic concurrency control.

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 data which will be used to update the Location object.

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

The dot notation paths of fields to clear. For example, line_items[uid].note. This is optional.

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. Please refer to the Square API documentation for the structure of this object.

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

The payment object containing the amount_money and tip_money to be updated. The amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents).

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 data which will be used to create the TeamMember object.

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

The updated webhook subscription object. It should include properties that you want to update.

{
  "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

A CatalogObject to be created or updated.

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​

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