Sell a gift card using the Gift Cards API and Customers API, and then load the gift card without the Orders API.
Gift Cards API: Walkthrough 1

Create and Activate a Gift Card When Using a Custom Processing System

This walkthrough shows how to sell a gift card when your application uses a custom order and payment processing system instead of the Orders API and Payments API. After processing the order to purchase a gift card, you create a gift card and activate it with an initial balance. Because you are using a custom processing system, you specify the balance amount and payment instrument IDs when you activate the card. After the gift card is activated, it is ready for use.

For the purposes of this walkthrough, assume that your application processed a $25 gift card purchase using your custom order and payment processing system.

Note

To learn how to use the Square Orders API and Payments API to process the gift card order and payment, see Create and Activate a Gift Card When Using Orders API Integration.

After the buyer pays for the gift card order, you create a gift card using the Gift Cards API and activate the gift card with an initial balance using the Gift Card Activities API.

  1. Call CreateGiftCard to create a digital gift card.

    Create Gift Card
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    curl https://connect.squareupsandbox.com/v2/gift-cards \
      -X POST \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "location_id": "{LOCATION_ID}",
        "gift_card": {
          "type": "DIGITAL"
        }
      }'

    The previous request specifies only the gift card type, which directs Square to generate the gift card account number (GAN). However, providing a custom GAN is also supported.

    Note

    This walkthrough creates a digital gift card in the Sandbox. Although testing physical gift cards is not supported in the Sandbox, you can register and activate physical gift cards in the production environment using the process described in this walkthrough.

    The following example response shows the gift card state is PENDING and the current balance is 0.

  2. Copy the id from the response. You use this value to activate the gift card.

  1. Call CreateGiftCardActivity to activate the gift card with an initial balance. The request must include either gift_card_id with the gift card ID or gift_card_gan with the GAN.

    This endpoint supports various activity types. For an ACTIVATE activity, you provide activity-specific details in the activate_activity_details field:

    • For amount_money, specify the amount of money to add to the gift card balance. This example adds $25.

    • For buyer_payment_instrument_ids, specify any card IDs, bank account IDs, or other payment instrument IDs used for the gift card purchase. Square uses this information to perform compliance checks. For this walkthrough, you can use the example values.

    • For reference_id, optionally reference an object from your custom order and payment processing system. For this walkthrough, you can use the example value.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "ACTIVATE",
          "location_id": "{LOCATION_ID}",
          "activate_activity_details": {
            "amount_money": {
              "amount": 2500,
              "currency": "USD"
            },
            "buyer_payment_instrument_ids": [
              "card-id-1",
              "card-id-2"
            ],
            "reference_id": "client-side-payment-id"
          }
        }
      }'

    The following is an example response:

  2. Optional. Call RetrieveGiftCard to see that the gift card state is set to ACTIVE and the balance is $25.

    Retrieve Gift Card
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/gift-cards/{id} \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    The following is an example response:

In the Seller Dashboard, the gift card is reported as activated. Because you are using the Sandbox for testing, you can view the report in the Seller Dashboard associated with your Sandbox test account.

  1. Open the Developer Dashboard.

  2. In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.

  3. Choose Reports.

  4. Choose Gift Cards and verify that Activations includes the activity and gift card amount.

    The gift card is also now listed in the Gift Cards section of the dashboard.

Buyers can purchase a gift card for themselves or for another recipient. The Gift Cards API does not provide email support, so your application must handle the delivery of the gift card information. For example, your application might choose to:

  • Show gift card information on the application website.

  • Email gift card information to the recipient.

Continue to Walkthrough 2: Use a Gift Card and learn how to pay for an order using an activated gift card.

In addition, you can explore the Gift Cards and Gift Card Activities APIs in other ways. For example, you can try out the Gift Cards sample (Node.js) or build and send API requests from API Explorer using your Sandbox access token.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.