You are viewing an old version of the API

All Versions

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, you create an ACTIVATE activity to activate a gift card with an initial balance before the gift card can be used.

Permissions

GIFTCARDS_WRITE

Guide

Manage the gift card balance or state Try in API Explorer

Request Body

Example code

Name	Description
`idempotency_key string` Required	A unique string that identifies the `CreateGiftCardActivity` request. Min Length 1 Max Length 128
`gift_card_activity GiftCardActivity` 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.

Response Fields

Name	Description
`errors Error [ ]`	Any errors that occurred during the request.
`gift_card_activity GiftCardActivity`	The gift card activity that was created.

Examples

POST /v2/gift-cards/activities

curl https://connect.squareup.com/v2/gift-cards/activities \
  -X POST \
  -H 'Square-Version: 2023-01-19' \
  -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"
    }
  }
}

Error Descriptions

400 Bad request	INSUFFICIENT_FUNDS The funding source has insufficient funds to cover the payment.	>
400 Bad request	PAYMENT_LIMIT_EXCEEDED Square declined the request because the payment amount exceeded the processing limit for this merchant.	>
400 Bad request	REFUND_AMOUNT_INVALID The requested refund amount exceeds the amount available to refund.	>

{
  "errors": [
    {
      "code": "INSUFFICIENT_FUNDS",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}