Walkthrough 1: Sell a Gift Card

This walkthrough provides step-by-step instructions that show how to create a digital gift card and then activate it with an initial balance. The walkthrough includes separate procedures for applications that process gift card orders with the Square Orders and Payments APIs or with a custom order and payment processing system.

To prepare for the walkthrough, you review information about using the Square Sandbox for testing. You also copy the Sandbox access token and location ID for your Square account.

Link to section

Step 1: Review Sandbox testing considerations

The Square Sandbox is an isolated server environment provisioned for each Sandbox test account. You use your Sandbox access token to create and access account resources in the Sandbox.

In this walkthrough, you create and activate a gift card in the Sandbox. If you follow the procedure that integrates with the Orders API and Payments API, you also create a gift card order and use a test payment token (cnon:card-nonce-ok) to pay for the order. Sandbox payment methods are easy to use and are never charged. For more information, see Testing a card payment.

In addition, you view gift card status in the Sandbox Seller Dashboard.


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

Link to section

Step 2: Gather account information

Follow these steps to get the access token and location ID used in this walkthrough.

  1. Sign in to the Developer Dashboard and open your application. If you don't have a Square account, see Get Started to learn how to create an account and an application.

  2. Get your Sandbox access token:

    1. At the top of the page, in the Sandbox and Production toggle, choose Sandbox.
    2. On the Credentials page, under Sandbox Access Token, choose Show and then copy the token. All Square API requests require an access token for authorization. This personal access token grants full access to the Sandbox resources in your account.


    The Sandbox access token is a secure secret. Don't share it with anyone.

  3. Get your location ID:

    1. In the left pane, choose Locations.
    2. On the Locations page, keep Default Test Account selected and copy a location ID.

    An animation showing how to get the Sandbox access token and location ID in the Developer Dashboard.


    To retrieve location IDs programmatically, call ListLocations.

Link to section

Next step

You are now ready to sell a gift card. To do so, your application creates and processes an order for the gift card amount and then creates and activates the gift card with the initial balance.

This walkthrough provides two separate application flows:

Link to section

See also