Gift Card API

The Gift Card API enables programmatic management of gift cards in the OrbVPN system. You can create, redeem, and manage gift cards for different subscription groups.

Overview

Gift cards provide a way to:

• Create single or bulk gift cards for specific subscription groups
• Redeem gift cards for subscriptions
• Track gift card usage and expiration
• Manage gift card cancellations

GraphQL Schema

Types

type GiftCard {
  id: ID!
  code: String! # Unique gift card code (format: ORB-XXXX-XXXX-XXXX)
  groupId: Int! # Associated subscription group ID
  groupName: String! # Name of the subscription group
  amount: Float! # Value of the gift card
  used: Boolean! # Whether the gift card has been redeemed
  cancelled: Boolean! # Whether the gift card has been cancelled
  expirationDate: DateTime! # When the gift card expires
  redeemedAt: DateTime # When the gift card was redeemed
  redeemedByEmail: String # Email of user who redeemed the card
  cancelledAt: DateTime # When the gift card was cancelled
  cancelledByEmail: String # Email of admin who cancelled the card
  createdAt: DateTime! # Creation timestamp
  updatedAt: DateTime! # Last update timestamp
}

input GiftCardCreateInput {
  groupId: Int! # Subscription group ID for the gift card
  validityDays: Int! # Number of days the gift card remains valid
}

API Operations

Create Gift Card

Creates a single gift card for a specific subscription group.

mutation GenerateGiftCard($input: GiftCardCreateInput!) {
  generateGiftCard(input: $input) {
    id
    code
    groupName
    amount
    expirationDate
  }
}

Variables:

{
  "input": {
    "groupId": 1,
    "validityDays": 30
  }
}

Create Bulk Gift Cards

Generates multiple gift cards with the same configuration.

mutation GenerateBulkGiftCards($input: GiftCardCreateInput!, $count: Int!) {
  generateBulkGiftCards(input: $input, count: $count) {
    id
    code
    groupName
    amount
    expirationDate
  }
}

Variables:

{
  "input": {
    "groupId": 1,
    "validityDays": 30
  },
  "count": 5
}

Redeem Gift Card

Redeems a gift card to activate a subscription.

mutation RedeemGiftCard($code: String!) {
  redeemGiftCard(code: $code) {
    code
    groupName
    redeemedAt
    redeemedByEmail
  }
}

Variables:

{
  "code": "ORB-XXXX-XXXX-XXXX"
}

Cancel Gift Card

Cancels an unused gift card (Admin only).

mutation CancelGiftCard($id: ID!) {
  cancelGiftCard(id: $id) {
    code
    cancelled
    cancelledAt
    cancelledByEmail
  }
}

Query Gift Cards

Get Valid Gift Cards

query GetValidGiftCards {
  getValidGiftCards {
    id
    code
    groupName
    amount
    expirationDate
  }
}

Get Gift Cards by Group

query GetGiftCardsByGroup($groupId: Int!) {
  getGiftCardsByGroup(groupId: $groupId) {
    id
    code
    amount
    used
    expirationDate
  }
}

Get Gift Card by Code

query GetGiftCardByCode($code: String!) {
  getGiftCardByCode(code: $code) {
    id
    code
    groupName
    amount
    used
    expirationDate
  }
}

Authorization

• Creating and cancelling gift cards requires admin privileges (ADMIN role)
• Redeeming gift cards is available for authenticated users (USER role)
• Querying gift cards by group or all valid cards requires admin privileges
• Querying a specific gift card by code is available for authenticated users

Gift Card Code Format

Gift cards use a standardized format:

• Prefix: "ORB-"
• Three groups of 4 alphanumeric characters
• Example: ORB-A12B-C3D4-E5F6

Subscription Handling

When a gift card is redeemed:

1. For users without an active subscription:

   • A new subscription is created starting from the redemption date
   • The expiration is set based on the group's duration

2. For users with an active subscription:

   • The new subscription duration is added to the existing expiration date
   • The subscription is updated to the gift card's group if different

Error Handling

Common error scenarios:

• Invalid gift card code format
• Gift card not found
• Gift card already used
• Gift card expired
• Gift card cancelled
• Insufficient permissions

Example error response:

{
  "errors": [
    {
      "message": "Gift card has already been used",
      "extensions": {
        "errorType": "VALIDATION_ERROR"
      }
    }
  ]
}

Notes

• Gift card codes are unique and case-insensitive
• Once redeemed or cancelled, a gift card cannot be reused
• Gift cards have a validity period after which they expire
• Admins can track gift card usage and cancel unused cards
• System automatically validates gift cards during redemption