Applies to: Gift Cards API | Gift Card Activities API
Learn about Square Gift Cards API webhooks. You can subscribe to these webhook events to get notified when changes occur.
The Gift Cards API and Gift Card Activities API support the following webhook events:
| 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 Square 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. For a list of all supported webhooks, see Webhook Events Reference.
The following considerations apply to events related to gift cards and gift card activities.
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.
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 Square Dashboard.
The event data includes a GiftCard object.
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.
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.
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.
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
PENDINGtoCOMPLETEDorCANCELED. Only gift cards that are redeemed using Square Point of Sale or the Square Dashboard are subject to a status change. Gift cards redeemed using the Gift Card Activities API always have aCOMPLETEDstatus. - The balance of an imported third-party gift card is adjusted by Square.
The event data includes a GiftCardActivity object.