Gift Card Webhooks

The Gift Cards API and Gift Card Activities API support the following webhook events:

EventPermissionDescription
gift_card.createdGIFTCARDS_READA digital gift card was created or a physical gift card was registered.
gift_card.updatedGIFTCARDS_READA 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_linkedGIFTCARDS_READA customer was linked to a gift card.
gift_card.customer_unlinkedGIFTCARDS_READA customer was unlinked from a gift card.
gift_card.activity.createdGIFTCARDS_READA gift card activity was created.
gift_card.activity.updatedGIFTCARDS_READA 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.

You can subscribe to these webhook events to be notified about gift card changes. For more information about using webhooks, see Square Webhooks Overview. For a list of all supported webhooks, see V2 Webhook Events Reference.

Link to section

Considerations

The following considerations apply to events related to gift cards and gift card activities.

Link to section

gift_card.created

A gift_card.created event is invoked when a digital gift card is created or a physical gift card is registered. Some actions that invoke this event are:

  • A physical gift card is sold in a store. For example, this event is invoked when a seller swipes a card to sell.
  • A digital gift card is sold online or in a store. A seller can use a custom Square web page to sell a digital card or in store using Square Point of Sale. For more information about online sales, see Sell Gift Cards on Your Square Online Site.
  • A digital gift card is created through a CreateGiftCard request.
  • A third-party gift card is imported.

The event data includes a GiftCard object.

Link to section

gift_card.updated

A gift_card.updated event is invoked when the gift card's state, balance, or customer_ids field changes. Some actions that invoke this event are:

  • A gift card is activated or deactivated.
  • A gift card is loaded.
  • A gift card is redeemed.
  • A gift card is refunded.
  • A gift card is blocked.
  • The balance of a gift card is adjusted.

These actions can be performed using a CreateGiftCardActivity, LinkCustomerToGiftCard, or UnlinkCustomerFromGiftcard request or by a seller using a Square product, such as Square Point of Sale or the Seller Dashboard.

The event data includes a GiftCard object.

Link to section

gift_card.customer_linked

A gift_card.customer_linked event is invoked when a customer is linked to a gift card using a LinkCustomerToGiftCard request or a Square product.

The event data includes a GiftCard object and the ID of the linked customer.

Link to section

gift_card.customer_unlinked

A gift_card.customer_unlinked event is invoked when a customer is unlinked from a gift card using an UnlinkCustomerFromGiftcard request or a Square product. For physical gift cards, customers are automatically unlinked from a gift card when its balance reaches zero. This prevents past customers from receiving receipts in the case that a seller resells the gift card to a new customer.

The event data includes a GiftCard object and the ID of the unlinked customer.

Link to section

gift_card.activity.created

A gift_card.activity.created event is invoked when a GiftCardActivity is created using a CreateGiftCardActivity request or a Square product. Some actions that invoke this event are:

  • A gift card is activated or deactivated.
  • A gift card is loaded.
  • A gift card is redeemed.
  • A gift card is refunded.
  • A gift card is imported.
  • The balance of a gift card is adjusted.

The event data includes a GiftCardActivity object.

Link to section

gift_card.activity.updated

A gift_card.activity.updated event is invoked when a GiftCardActivity is updated. The following actions invoke this event:

  • The status of a gift card redemption changed from PENDING to COMPLETED or CANCELED. Only gift cards that are redeemed using Square Point of Sale or the Seller Dashboard are subject to a status change. Gift cards redeemed using the Gift Card Activities API always have a COMPLETED status.
  • The balance of an imported third-party gift card is adjusted by Square.

The event data includes a GiftCardActivity object.

Link to section

See also