Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Gift Cards API

Gift Cards API Webhooks

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

EventDescription
gift_card.createdA gift card was created.
gift_card.updatedA gift card was updated. The attributes on a gift card that can be updated are balance_money, state, and customer_ids.
gift_card.customer_linkedA customer was linked to a gift card.
gift_card.customer_unlinkedA customer was unlinked from a gift card.
gift_card.activity.createdA gift card activity was created.

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

Note the following considerations about gift card-related events:

  • gift_card.created. Some actions that invoke this event are:

    • A physical gift card is sold in a store. For example, when a seller swipes a card to sell, the event is published.

    • A digital gift card is sold online. A seller can use a custom Square web page to sell a digital card (see Gift Cards for Square Online) or in store using Square Point of Sale.

    • A digital gift card is created through a CreateGiftCard request.

    • A third-party gift card is imported.

    The event data includes a GiftCard object.

  • gift_card.updated. This event is published when the 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 balance is adjusted.

    • A gift card is blocked.

    These actions can be invoked by a CreateGiftCardActivity, LinkCustomerToGiftCard, or UnlinkCustomerFromGiftcard request or by a seller performing an activity using a Square first-party application (such as the Square Point of Sale application or Seller Dashboard).

    The event data includes a GiftCard object.

  • gift_card.customer_linked. This event is published when a customer is linked to a gift card through a LinkCustomerToGiftCard request or Square first-party application flow.

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

  • gift_card.customer_unlinked. This event is published when a customer is unlinked from a gift card through an UnlinkCustomerFromGiftcard request or Square first-party application flow. 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.

  • gift_card.activity.created. This event is published when a GiftCardActivity object is created through a CreateGiftCardActivity request or Square first-party application flow. Some actions that invoke this event are:

    • A gift card is activated or deactivated.

    • A gift card is imported.

    • A gift card is loaded.

    • A gift card is redeemed.

    • A gift card is refunded.

    • A gift card balance is adjusted.

    The event data includes a GiftCardActivity object.

Related topics Permalink Get a link to this section