POST /v2/gift-cards/activities - Square API Reference

Create gift card activity

POST

/v2/gift-cards/activities

Creates a gift card activity to manage the balance or state of a gift card.

For example, create an ACTIVATE activity to activate a gift card with an initial balance before first use.

Link to section

Request body

Example code

Link to section

idempotency_key

string

Required

A unique string that identifies the CreateGiftCardActivity request.

Min Length

Max Length

128

Link to section

gift_card_activity

Required

The activity to create for the gift card. This activity must specify gift_card_id or gift_card_gan for the target gift card, the location_id where the activity occurred, and the activity type along with the corresponding activity details.

Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

gift_card_activity

The gift card activity that was created.

curl https://connect.squareup.com/v2/gift-cards/activities \ -X POST \ -H 'Square-Version: 2025-06-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "U16kfr-kA70er-q4Rsym-7U7NnY", "gift_card_activity": { "gift_card_id": "gftc:6d55a72470d940c6ba09c0ab8ad08d20", "type": "ACTIVATE", "location_id": "81FN9BNFZTKS4", "activate_activity_details": { "order_id": "jJNGHm4gLI6XkFbwtiSLqK72KkAZY", "line_item_uid": "eIWl7X0nMuO9Ewbh0ChIx" } } }'

{ "gift_card_activity": { "id": "gcact_c8f8cbf1f24b448d8ecf39ed03f97864", "gift_card_id": "gftc:6d55a72470d940c6ba09c0ab8ad08d20", "gift_card_gan": "7783320002929081", "type": "ACTIVATE", "gift_card_balance_money": { "amount": 1000, "currency": "USD" }, "location_id": "81FN9BNFZTKS4", "created_at": "2021-05-20T22:26:54.000Z", "activate_activity_details": { "amount_money": { "amount": 1000, "currency": "USD" }, "order_id": "jJNGHm4gLI6XkFbwtiSLqK72KkAZY", "line_item_uid": "eIWl7X0nMuO9Ewbh0ChIx" } } }

Create gift card activity

Request body

Response fields

Error descriptions