V2 Webhook Events Reference

Webhooks let you subscribe to Square API events and receive notice when an event occurs. For more information about how to set up a webhook subscription, see Square Webhooks Overview.

Link to section

Bank Accounts API

Event	Permission	Description
bank_account.disabled	BANK_ACCOUNTS_READ	Published when Square sets the status of a bank account to DISABLED.
bank_account.verified	BANK_ACCOUNTS_READ	Published when Square sets the status of a bank account to VERIFIED.
bank_account.created	BANK_ACCOUNTS_READ	Published when you link a seller's or buyer's bank account to a Square account. Square sets the initial status to VERIFICATION_IN_PROGRESS and publishes the event.

For information about using the Bank Accounts API, see Bank Accounts API.

Link to section

Bookings API

Event	Permission	Description
booking.created	APPOINTMENTS_READ	A booking is created by calling CreateBooking.
booking.updated	APPOINTMENTS_READ	An API-created booking is updated in the Seller Dashboard, on the seller's online booking site, or by calling UpdateBooking.

For more information about booking events, see Handle Booking Event Notifications with Webhooks. For information about using the Bookings API, see Manage Bookings for Square Sellers.

Link to section

Booking Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event	Description
booking.custom_attribute_definition.owned.created	A custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
boooking.custom_attribute_definition.owned.updated	A custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
booking.custom_attribute_definition.owned.deleted	A custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
booking.custom_attribute.owned.updated	A custom attribute owned by your application was created or updated for a booking.
booking.custom_attribute.owned.deleted	A custom attribute owned by your application was deleted from a booking.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you don't need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event	Description
booking.custom_attribute_definition.visible.created	A custom attribute definition that's visible to your application was created.
booking.custom_attribute_definition.visible.updated	A custom attribute definition that's visible to your application was updated.
booking.custom_attribute_definition.visible.deleted	A custom attribute definition that's visible to your application was deleted.
booking.custom_attribute.visible.updated	A custom attribute that's visible to your application was created or updated for a booking.
booking.custom_attribute.visible.deleted	A custom attribute that's visible to your application was deleted from a booking.

For more information about booking-related custom attribute events, see Webhooks. For information about using the Booking Custom Attributes API, see Custom Attributes for Bookings.

Link to section

Cards API

Event	Permission	Description
card.automatically_updated	PAYMENTS_READ	Published when card expiration information or pan is automatically updated.
card.created	PAYMENTS_READ	Published when a card is created or imported.
card.disabled	PAYMENTS_READ	Published when a card is disabled.
card.forgotten	PAYMENTS_READ	Published when a card is GDPR forgotten/vaulted.
card.updated	PAYMENTS_READ	Published when a card is updated by the developer using the UpdateCard endpoint.

For information about using the Cards API, see Cards API Overview.

Link to section

Catalog API

Event	Permission	Description
catalog.version.updated	ITEMS_READ	The catalog was updated. Webhook notification data is packaged as "catalog_version": { "updated_at": "2019-05-14T17:51:27Z"}.

For more information about catalog events, see Webhooks. For information about using the Catalog API, see What It Does.

Link to section

Customers API

Event	Permission	Description
customer.created	CUSTOMERS_READ	A customer profile is created, including when customer profiles are merged into a new customer profile.
customer.deleted	CUSTOMERS_READ	A customer profile is deleted, including when customer profiles are merged into a new customer profile.
customer.updated	CUSTOMERS_READ	An attribute on a customer profile is changed, except for the following: • cards (deprecated) • segment_ids

For more information about customer events, see Use Customer Webhooks. For information about using the Customers API, see Manage Customers and Integrate with Other Services.

Link to section

Customer Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event	Permission	Description
customer.custom_attribute_definition.owned.created	CUSTOMERS_READ	A custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes. This event replaces the deprecated customer.custom_attribute_definition.created event.
customer.custom_attribute_definition.owned.updated	CUSTOMERS_READ	A custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition. This event replaces the deprecated customer.custom_attribute_definition.updated event.
customer.custom_attribute_definition.owned.deleted	CUSTOMERS_READ	A custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition. This event replaces the deprecated customer.custom_attribute_definition.deleted event.
customer.custom_attribute.owned.updated	CUSTOMERS_READ	A custom attribute owned by your application was created or updated for a customer profile. This event replaces the deprecated customer.custom_attribute.updated event.
customer.custom_attribute.owned.deleted	CUSTOMERS_READ	A custom attribute owned by your application was deleted from a customer profile This event replaces the deprecated customer.custom_attribute.deleted event.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event	Permission	Description
customer.custom_attribute_definition.visible.created	CUSTOMERS_READ	A custom attribute definition that's visible to your application was created. This event replaces the deprecated customer.custom_attribute_definition.public.created event.
customer.custom_attribute_definition.visible.updated	CUSTOMERS_READ	A custom attribute definition that's visible to your application was updated. This event replaces the deprecated customer.custom_attribute_definition.public.updated event.
customer.custom_attribute_definition.visible.deleted	CUSTOMERS_READ	A custom attribute definition that's visible to your application was deleted. This event replaces the deprecated customer.custom_attribute_definition.public.deleted event.
customer.custom_attribute.visible.updated	CUSTOMERS_READ	A custom attribute that's visible to your application was created or updated for a customer profile. This event replaces the deprecated customer.custom_attribute.public.updated event.
customer.custom_attribute.visible.deleted	CUSTOMERS_READ	A custom attribute that's visible to your application was deleted from a customer profile. This event replaces the deprecated customer.custom_attribute.public.deleted event.

For more information about customer-related custom attribute events, see Webhooks. For information about using the Customer Custom Attributes API, see Custom Attributes for Customer Profiles.

Link to section

Devices API

Event	Permission	Description
device.code.paired	DEVICE_CREDENTIAL_MANAGEMENT	A Square Terminal has been paired with a Terminal API client and the device_id of the paired Square Terminal is available.

For information about using the Devices API, see Connect a Square Terminal.

Link to section

Disputes API

Event	Permission	Description
dispute.created	PAYMENTS_READ	A dispute was created.
DEPRECATED: dispute.state.changed	PAYMENTS_READ	The state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed.
dispute.state.updated	PAYMENTS_READ	The state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed.
DEPRECATED: dispute.evidence.added	PAYMENTS_READ	Evidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText).
dispute.evidence.created	PAYMENTS_READ	Evidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText).
dispute.evidence.deleted	PAYMENTS_READ	Evidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence.
DEPRECATED: dispute.evidence.removed	PAYMENTS_READ	Evidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence.

For more information about dispute events, see Disputes webhook notifications. For information about using the Disputes API, see Disputes Overview.

Link to section

Gift Cards API

Event	Permission	Description
gift_card.created	GIFTCARDS_READ	A digital gift card was created or a physical gift card was registered.
gift_card.updated	GIFTCARDS_READ	A gift card was updated. The balance_money, state, and customer_ids fields of a gift card can be updated through a gift card activity or when a customer is linked or unlinked.
gift_card.customer_linked	GIFTCARDS_READ	A customer was linked to a gift card.
gift_card.customer_unlinked	GIFTCARDS_READ	A customer was unlinked from a gift card.
gift_card.activity.created	GIFTCARDS_READ	A gift card activity was created.
gift_card.activity.updated	GIFTCARDS_READ	A REDEEM or IMPORT gift card activity was updated. For REDEEM activities, this event is invoked when the status changes from PENDING to COMPLETED or CANCELED. This status change applies only when the gift card was redeemed using Square Point of Sale or the Seller Dashboard. For IMPORT activities, this event is invoked when the balance of an imported third-party gift card is updated by Square.

For more information about gift card events, see Gift Card Webhooks. For information about using the Gift Cards API and Gift Card Activities API, see Gift Cards API Overview.

Link to section

Inventory API

Event	Permission	Description
inventory.count.updated	INVENTORY_READ	The quantity was updated for a catalog item variation. Webhook notification data is packaged as InventoryCount[].

For information about using the Inventory API, see What It Does.

Link to section

Invoices API

Event	Permission	Description
invoice.created	INVOICES_READ	A draft invoice was created.
invoice.published	INVOICES_READ	An invoice was published. This also applies to invoices that are published but scheduled to be processed at a later time.
invoice.updated	INVOICES_READ	An invoice was changed. This event is also invoked following invoice.published and invoice.canceled events.
invoice.payment_made	INVOICES_READ	A payment was made for an invoice.
invoice.scheduled_charge_failed	INVOICES_READ	A scheduled automatic payment has failed.
invoice.canceled	INVOICES_READ	An invoice was canceled.
invoice.refunded	INVOICES_READ	A refund was processed for an invoice.
invoice.deleted	INVOICES_READ	A draft invoice was deleted. A deleted invoice is removed entirely from the seller account and cannot be retrieved.

For information about using the Invoices API, see Invoices API Overview.

Link to section

Labor API

Event	Permission	Description
labor.shift.created	TIMECARDS_READ	A worker started a shift. Webhook notification data is packaged as a Shift.
labor.shift.updated	TIMECARDS_READ	A shift was updated. Typically a break was started or ended or a worker ended the shift. Webhook notification data is packaged as a Shift.
labor.shift.deleted	TIMECARDS_READ	A shift was deleted. Notification data includes the deleted shift ID and the isDeleted flag.

For information about using the Labor API, see Labor API.

Link to section

Locations API

Event	Permission	Description
location.created	MERCHANT_PROFILE_READ	A Location was created.
location.updated	MERCHANT_PROFILE_READ	A Location was updated.

For information about using the Locations API, see Locations API.

Link to section

Location Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event	Permission	Description
location.custom_attribute_definition.owned.created	MERCHANT_PROFILE_READ	A custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
location.custom_attribute_definition.owned.updated	MERCHANT_PROFILE_READ	A custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
location.custom_attribute_definition.owned.deleted	MERCHANT_PROFILE_READ	A custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
location.custom_attribute.owned.updated	MERCHANT_PROFILE_READ	A custom attribute owned by your application was created or updated for a location.
location.custom_attribute.owned.deleted	MERCHANT_PROFILE_READ	A custom attribute owned by your application was deleted from a location.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application. Therefore, you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event	Permission	Description
location.custom_attribute_definition.visible.created	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was created.
location.custom_attribute_definition.visible.updated	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was updated.
location.custom_attribute_definition.visible.deleted	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was deleted.
location.custom_attribute.visible.updated	MERCHANT_PROFILE_READ	A custom attribute that's visible to your application was created or updated for a location.
location.custom_attribute.visible.deleted	MERCHANT_PROFILE_READ	A custom attribute that's visible to your application was deleted from a location.

For more information about location-related custom attribute events, see Webhooks. For information about using the Location Custom Attributes API, see Custom Attributes for Locations.

Link to section

Loyalty API

Event	Permission	Description
loyalty.account.created	LOYALTY_READ	A loyalty account was created for a buyer. A loyalty account can be created using any of the following methods, which all publish this event: • An application calls the CreateLoyaltyAccount endpoint. • A buyer enrolls in the program from a Square Point of Sale application. • The seller enrolls a buyer using the Customer Directory. • The seller merges two customer accounts into one account using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.account.updated	LOYALTY_READ	A loyalty account was updated. For example: • The seller updates the phone number registered for the loyalty account using the Seller Dashboard. For more information, see Square Loyalty FAQ. • Any change in the loyalty point balance, such as points added for visits, points expiration, or a manual adjustment to the point balance that a seller might perform. • The customer ID of the loyalty account was changed. For example, the loyalty account moved to another customer.
loyalty.account.deleted	LOYALTY_READ	Published when a loyalty account is deleted. The published event does not contain the customer_id that was associated with the deleted account. The following actions to delete the account can publish this event: • The seller deletes an account using the Seller Dashboard. • The seller merges two customer profiles using the Customer Directory. In this process, sellers might merge the two corresponding loyalty accounts by creating a new account and deleting the existing accounts.
loyalty.program.created	LOYALTY_READ	A loyalty program was created. Loyalty programs can only be created from the Seller Dashboard.
loyalty.program.updated	LOYALTY_READ	A loyalty program was updated. Loyalty programs can only be updated from the Seller Dashboard.
loyalty.promotion.created	LOYALTY_READ	A loyalty promotion was created.
loyalty.promotion.updated	LOYALTY_READ	A loyalty promotion was canceled.
loyalty.event.created	LOYALTY_READ	A balance-changing event occurred. Square Loyalty maintains a ledger of events that occur over the lifetime of a loyalty account. Square publishes notifications for each loyalty event logged to the ledger. These loyalty events are immutable, which means they are never updated or deleted. For example, when a buyer redeems a reward and then returns the order, Square publishes separate notifications for the corresponding CREATE_REWARD and DELETE_REWARD events. Similarly, Square publishes a notification for the OTHER event when points are deducted after a purchase that accrued points is refunded.

For information about using the Loyalty API, see Loyalty API Overview.

Link to section

Merchant Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event	Permission	Description
merchant.custom_attribute_definition.owned.created	MERCHANT_PROFILE_READ	A custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
merchant.custom_attribute_definition.owned.updated	MERCHANT_PROFILE_READ	A custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
merchant.custom_attribute_definition.owned.deleted	MERCHANT_PROFILE_READ	A custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
merchant.custom_attribute.owned.updated	MERCHANT_PROFILE_READ	A custom attribute owned by your application was created or updated for a merchant.
merchant.custom_attribute.owned.deleted	MERCHANT_PROFILE_READ	A custom attribute owned by your application was deleted from a merchant.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application. Therefore, you don't need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event	Permission	Description
merchant.custom_attribute_definition.visible.created	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was created.
merchant.custom_attribute_definition.visible.updated	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was updated.
merchant.custom_attribute_definition.visible.deleted	MERCHANT_PROFILE_READ	A custom attribute definition that's visible to your application was deleted.
merchant.custom_attribute.visible.updated	MERCHANT_PROFILE_READ	A custom attribute that's visible to your application was created or updated for a merchant.
merchant.custom_attribute.visible.deleted	MERCHANT_PROFILE_READ	A custom attribute that's visible to your application was deleted from a merchant.

For information about using the Merchant Custom Attributes API, see Custom Attributes for Merchants.

Link to section

OAuth API

Event	Permission	Description
oauth.authorization.revoked	N/A	Notifies an application whenever a seller revokes all access tokens and refresh tokens granted to the application.

For information about using the OAuth API, see OAuth Overview.

Link to section

Orders API

Event	Permission	Description
order.created	ORDERS_READ	An Order was created. This event is triggered only by the CreateOrder endpoint call.
order.fulfillment.updated	ORDERS_READ	An OrderFulfillment was created or updated. This event is triggered only by the UpdateOrder endpoint call.
order.updated	ORDERS_READ	An Order was updated. This event is triggered only by the UpdateOrder endpoint call.

For information about using the Orders API, see Orders API Overview.

Link to section

Order Custom Attributes API

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are owned by your application:

Event	Permission	Description
order.custom_attribute_definition.owned.created	ORDERS_READ	A custom attribute definition was created by your application. The application that created the custom attribute definition is the owner of the definition and corresponding custom attributes.
order.custom_attribute_definition.owned.updated	ORDERS_READ	A custom attribute definition owned by your application was updated. Note that only the definition owner can update a custom attribute definition.
order.custom_attribute_definition.owned.deleted	ORDERS_READ	A custom attribute definition owned by your application was deleted. Note that only the definition owner can delete a custom attribute definition.
order.custom_attribute.owned.updated	ORDERS_READ	A custom attribute owned by your application was created or updated for an order.
order.custom_attribute.owned.deleted	ORDERS_READ	A custom attribute owned by your application was deleted from an order.

Subscribe to the following events to receive notifications for changes to custom attribute definitions and custom attributes that are visible to your application. These .visible events include changes to all custom attribute definitions and custom attributes that are owned by your application, so you do not need to subscribe to an .owned event when you subscribe to the corresponding .visible event.

Event	Permission	Description
order.custom_attribute_definition.visible.created	ORDERS_READ	A custom attribute definition that's visible to your application was created.
order.custom_attribute_definition.visible.updated	ORDERS_READ	A custom attribute definition that's visible to your application was updated.
order.custom_attribute_definition.visible.deleted	ORDERS_READ	A custom attribute definition that's visible to your application was deleted.
order.custom_attribute.visible.updated	ORDERS_READ	A custom attribute that's visible to your application was created or updated for an order.
order.custom_attribute.visible.deleted	ORDERS_READ	A custom attribute that's visible to your application was deleted from an order.

For information about using the Order Custom Attributes API, see Custom Attributes for Orders.

Link to section

Payments API

Event	Permission	Description
payment.created	PAYMENTS_READ	A Payment was created.
payment.updated	PAYMENTS_READ	A Payment field was updated. For example, the payment.status or card_details.status field is updated when a payment is authorized, canceled, or completed.

For information about using the Payments API, see Payments API and Refunds API Overview.

Link to section

Payouts API

Event	Permission	Description
payout.failed	PAYOUTS_READ	A Payout has failed.
payout.paid	PAYOUTS_READ	A Payout was completed.
payout.sent	PAYOUTS_READ	A Payout was sent.

For information about using the Payouts API, see Payouts API Overview.

Link to section

Refunds API

Event	Permission	Description
refund.created	PAYMENTS_READ	A Refund was created.
refund.updated	PAYMENTS_READ	A Refund was updated. Typically, the refund.status field changes when a refund is completed.

For information about using the Refunds API, see Payments API and Refunds API Overview.

Link to section

Subscriptions API

Event	Permission	Description
subscription.created	SUBSCRIPTIONS_READ	A Subscription object was created.
subscription.updated	SUBSCRIPTIONS_READ	A Subscription object was updated.

For information about using the Subscriptions API, see Manage Subscriptions Using the Subscriptions API.

Link to section

Team API

Event	Permission	Description
team_member.created	EMPLOYEES_READ	A new team member was created.
team_member.updated	EMPLOYEES_READ	A team member was updated.
team_member.wage_setting.updated	EMPLOYEES_READ	A new team member wage setting was updated.

For information about using the Team API, see Team API.

Link to section

Terminal API

Event	Permission	Description
terminal.checkout.created	PAYMENTS_READ	A TerminalCheckout request was created.
terminal.checkout.updated	PAYMENTS_READ	A TerminalCheckout status was changed.
terminal.refund.created	PAYMENTS_READ	A TerminalRefund request was created.
terminal.refund.updated	PAYMENTS_READ	A TerminalRefund status was changed.
terminal.action.created	PAYMENTS_READ	A TerminalAction request was created.
terminal.action.updated	PAYMENTS_READ	A TerminalAction status was updated.

For information about using the Terminal API, see Square Terminal Integration Overview.

Link to section

Vendors API

Event	Permission	Description
vendor.created	VENDOR_READ	Published when a vendor is created by calling CreateVendor or BulkCreateVendors, as well as using the Square Seller Dashboard.
vendor.updated	VENDOR_READ	Published when a vendor is updated by calling UpdateVendor or BulkUpdateVendors, as well as using the Seller Dashboard.

For more information about vendor events, see Receive Vendors Webhook Events. For information about using the Vendors API, see Manage Suppliers of a Seller.