Feature: Gift Cards

Editions: Cloud, Corporate*

The giftcardAdd mutation endpoint can be used to create gift cards. Gift card creation and adding funds are separate API calls, as a common use case for physical cards is to create a card with PINs, order the physical cards from a card printer, then activate (add funds) when the customer purchases a card.

An important distinction is that gift cards can have one or more codes, each of which may be used for a different purpose:

• Physical codes are for printed gift cards, where the customer must physically present the card to a retailer to use funds from it. Physical possession of the card implies the customer has the right to use it.
  • A physical code may optionally have a scratch-off PIN; this enables the customer to also use the gift card in an online or mobile environment if they supply both the physical code and PIN.
• Personal codes associate a gift card to a customer’s membership account. The customer can present the personal code via their mobile app to use the gift card.
  • As the personal code is an electronic (digital) value, it has additional security implications. It is a long random code, generated by POS, and is always associated with a membership account.
• External codes are for gift card codes that are managed by a third party system, such as ecommerce site. The third party system must take responsibility for securing the external code.

Creating cards requires the CreateGiftCard permission.

Of note:

• The endpoint returns an internal ID for the gift card, which can be used in subsequent calls to giftcardEdit.
• Each code may have an optional expiration date; expiry is for the code itself and not the funds on the card.

Examples

Create Physical Card

Create a gift card with a physical code and optional PIN:

mutation AddCard {
  giftcardAdd(giftcard: {physicalCode: "GC49288330", physicalPin: "1234"}) {
    id
    codes {
      codeType
      code
      expiresOn
    }
  }
}

Create Personal Card

Creates a gift card with a personal electronic code:

mutation AddCard {
  giftcardAdd(giftcard: {addPersonalCode: true, memberId: "C000000212"}) {
    id
    memberId
    codes {
      codeType
      code
      expiresOn
    }
  }
}

Note that:

• A member ID must be provided.
• You do not specify the personal code; POS will generate the code.
• By default only a masked version of the generated personal code is returned in the API result. The non-masked code is only returned if you have ViewUnmaskedGiftCardCodes permission.

Create External Card

Create a gift card with an external code:

mutation AddCard {
  giftcardAdd(giftcard: {externalCode: "EX000034802"}) {
    id
    codes {
      codeType
      code
      expiresOn
    }
  }
}

This example can be used when a third-party system (such as an ecommerce site) is generating code values. The third-party system is responsible for generating and using the external code in a secure manner.

Create Card with Multiple Codes

You can also create a gift card with multiple codes associated with it – this example associates a physical code and personal code with the same card:

mutation AddCard {
  giftcardAdd(
    giftcard: {
      physicalCode: "GC49288331",
      physicalPin: "1234",
      addPersonalCode: true,
      memberId: "C000000212"
  } ) {
    id
    memberId
    codes {
      codeType
      code
      expiresOn
    }
  }
}