Get Gift Card

Feature: Gift Cards

Editions: Cloud, Corporate*

The giftcard endpoint can be queried to retrieve gift card information.

To enable various use cases – especially access by trusted and non-trusted API clients – several permissions are used to refine how gift card results are returned. The following permissions are the most common:

• FindGiftCardByCode – the client can query for a gift card by supplying the code. This is the most common use case.
• UseExternalGiftCardCodes – the client can view external codes; this use case is for third party integrations that manage their own gift card codes, e.g. an ecommerce system.
• UsePhysicalGiftCardCodes – the client can view physical codes.

There are additional permissions that can be used, but have limited use cases. These permissions should be used when necessary and for high-trust clients – e.g. server environments that you can secure – as they can expose sensitive gift card details:

• ListGiftCards – the client query gift cards without supplying a code value. This is a limited case that should be only used for high-trust clients.
• ViewUnmaskedGiftCardCodes – the client can view electronic (digital) codes. Again, this is a limited case that should only be used for high-trust clients.
• UseCryptoGiftCardCodes – the client can view electronic (digital) codes, either in masked form (recommended) or unmasked form (as specified above). This is a limited use case.
• UseShortPersonalGiftCardCodes – reserved for future use.

Examples

Get Card by Code

Return a gift card that matches a specific code:

query MyQuery {
  giftcard(code: "G59220000045", codeType: PHYSICAL) {
    limitedByPermission
    results {
      id
      memberId
      balance
      codes {
        id
        codeType
        code
        expiresOn
        isMasked
      }
    }
  }
}

Note:

• While the codeType parameter is optional, it is recommended.
  • Gift card codes must be unique within a code type, so that they uniquely identify a gift card.
  • It is recommended to keep codes unique across all code types, but it is not required.
  • If codes are not unique across all code types, the codeType parameter is required to resolve the correct gift card.
• This type of request requires FindGiftCardByCode permission.

Get Card by ID

Return a gift card that matches the specified internal ID:

query MyQuery {
  giftcard(id: "302") {
    limitedByPermission
    results {
      id
      memberId
      balance
      codes {
        id
        codeType
        code
        expiresOn
        isMasked
      }
    }
  }
}

This type of query should only be used by trusted clients, and requires ListGiftCardspermission.

List Cards for Member

Return the list of gift cards that are owned by a specific member:

query MyQuery {
  giftcard(memberId: "C000000113") {
    limitedByPermission
    results {
      id
      memberId
      balance
      codes {
        id
        codeType
        code
        expiresOn
        isMasked
      }
    }
  }
}

This type of query should only be used by trusted clients, and requires ListGiftCardspermission.