Manage Memberships & Entitlements

Manage Memberships

Register a membership

→ Use the /memberships endpoint to register a DragonPass membership for your end user.

The header parameters X-Program-ID specifying the associated program, which determines the membership's initial validity period and entitlement settings.

Request

Membership Registration - Request

{
    "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
    "firstName": "DragonPass",
    "lastName": "DragonPass",
    "phoneNumber": "8081966002",
    "callingCode": "44",
    "email": "developer@dragonpass.com",
    "activationDate": "2028-10-31T23:59:59+00:00",
    "expirationDate": "2028-12-31T23:59:59+00:00"
}

Response

The response returns:

Membership Registration - Response

{
    "code": 0,
    "data": {
        "programId": "1876920048220766208",
        "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
        "membershipId": "8888000066668888",
        "status": 1,
        "registrationDate": "2025-01-31T23:59:59+00:00",
        "activationDate": "2028-10-31T23:59:59+00:00",
        "expirationDate": "2028-12-31T23:59:59+00:00",
        "entitlements": {
            "moduleExclusiveEntitlements": [
                {
                    "module": 1,
                    "details": {
                        "cardholderExclusiveEntitlements": 1,
                        "guestsExclusiveEntitlements": 1,
                        "sharedEntitlements": 0,
                        "allowedGuestsPerUsage": 1,
                        "maxGuestsNextUse": 1
                    }
                }
            ]
        }
    }
}

Update a membership

→ Use the /memberships/update endpoint to update membership information.

Currently, the information that can be updated via the API includes:

Membership expiration date

Membership status

Membership Status Update Matrix

From \ To	0-Pending Activation	1-Active	2-Suspended	3-Cancelled	9-Expired
0-Pending Activation	-	✅	✅	✅	❌ (Will update automatically)
1-Active	❌	-	✅	✅	❌ (Will update automatically)
2-Suspended	✅	✅	-	✅	❌ (Will update automatically)
3-Cancelled	❌	❌	❌	-	❌
9-Expired	❌	✅	❌	✅	-

When attempting to activate a membership that has already expired, a new expiration date to be provided. This ensures that the reactivated membership has a valid period of use.

Request

Update A Membership - Request

{
    "membershipId": "8888000066668888",
    "status": 2,
    "activationDate": "2028-10-31T23:59:59+00:00",
    "expirationDate": "2035-12-31T23:59:59+00:00"
}

Response

Update A Membership - Response

{
  "code": 0,
  "data": {
    "membershipId": "8888000066668888",
    "status": 1,
    "registrationDate": "2025-12-31T23:59:59+00:00",
    "activationDate": "2028-10-31T23:59:59+00:00",
    "expirationDate": "2035-12-31T23:59:59+00:00"
  }
}

Retrieve membership information

→ Use the /memberships/search endpoint to retrieve membership information.

Request

Retrieve Membership Information - Request

{
    "membershipId": "8888000066668888"
}

Response

Retrieve Membership Information - Response

{
  "code": 0,
  "data": {
    "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
    "programId": "1876920048220766208",
    "membershipId": "8888000066668888",
    "status": 1,
    "registrationDate": "2028-12-31T23:59:59+00:00",
    "activationDate": "2028-10-31T23:59:59+00:00",
    "expirationDate": "2028-12-31T23:59:59+00:00"
  }
}

Generate membership dynamic QR code

→ Use the /memberships/qrCodes endpoint to generate membership dynamic QR codes.

In addition to using a fixed membershipId, clients can also choose to generate a dynamic membership QR code and display it in the application for enhanced security.

Request

You can use durationInSeconds to specify the validity period of the QR code, with a maximum duration of 7200 seconds.

Generate Membership Dynamic QR Codes - Request

{
  "membershipId": "8888000066668888",
  "durationInSeconds": 7200
}

Response

Generate Membership Dynamic QR Codes - Response

{
  "code": 0,
  "data": {
    "qrCode": "8886520686",
    "validUntil": 1923263999
  }
}

Change Membership Program(Upgrade/Downgrade)

For clients aiming to enrich and expand their loyalty program ecosystem, there is a business requirement to support membership upgrade and downgrade operations.

This scenario typically occurs when a single end user (clientUserId) holds memberships corresponding to different loyalty tiers on the client side, each mapped to a distinct loyalty program, and needs the flexibility to move between tiers as their status changes.

This API enables a controlled and standardized membership migration between programs, ensuring data consistency, entitlement integrity, and correct membership lifecycle management.

Upgrade / Downgrade Mechanism

After a successful upgrade or downgrade:

The current Active membership will be set to Suspended

Existing entitlements on the Suspended membership remain unchanged.

For the target program:

If no valid membership exists, a new membership will be created.

If a Suspended membership already exists, it will be Reactivated.

Migration Strategies

The migration operation supports two independent strategy dimensions at the moment:

Entitlement Strategy (entitlementOptions)

Defines how entitlements are handled after migration.

Strategy	Description
`1`	If no membership exists under the target program, a new membership will be created and the corresponding entitlements will be issued. If a membership already exists under the target program(in `Suspended` status), all existing entitlements of this membership will be cleared, and entitlements will be reissued according to the target program configuration.
`2`	Keep existing entitlements unchanged on the target membership.

Validity Strategy (validityOptions)

Defines how valid period are handled after migration.

Strategy	Description
`1`	Membership validity period remains unchanged after upgrade or downgrade.

Business Rules

Only active memberships are allowed to initiate an upgrade or downgrade.

For both the current program and the target program:

If multiple valid memberships exist under the same program, migration is not allowed.

Memberships with status Cancelled or Deleted are not considered valid.

If the target program contains an inactive (not activated) membership, migration is not allowed.

Endpoint

/memberships/programChange

Request

Change Membership Program - Request

{
    "membershipId": "8888888800000000",
    "programId": "1876920048220766208",
    "targetProgramId": "1876920048220766200",
    "entitlementOptions": {
        "strategy": 1
    },
    "validityOptions": {
        "strategy": 1
    }
}

Response

Change Membership Program - Response

{
    "code": 0,
    "data": {
        "membershipId": "8888000066668888",
        "programId": "1876920048220766200",
        "previousProgramId": "1876920048220766208"
    }
}

Manage Entitlement

Update membership entitlement

→ Use the /entitlements/update endpoint to update the membership entitlement.

Request

Use the mandatory fields in the request to specify the entitlements of the change.

Currently, the following modules support entitlement updates, with some modules only allowing the issuance of cardholder-exclusive entitlements.

Module	Enum	Cardholder-exclusive	Guests-exclusive	Shared
Lounge	1	✅	✅	✅
Fast Track	2	✅	✅	✅
Dining Coupon	4	✅	✅	✅
Fitness	7	✅	❌	❌

Update Membership Entitlements - Request

Add one cardholder-exclusive entitlement for lounge module to the membership.

Specify membershipId.

Specify the number of entitlements to be added in the quantity field.

Specify the module in the module field, where 1 represents Lounge module.

Set the usageRestriction field to 1 to designate the entitlement as cardholder-exclusive.

{
  "membershipId": "8888000066668888",
  "quantity": 1,
  "module": 1,
  "usageRestriction": 1
}

Add two shared entitlements for Fast Track module to the membership.

Specify membershipId.

Specify the number of entitlements to be added in the quantity field.

Specify the module in the module field, where 4 represents Dining Coupon module.

Set the usageRestriction field to 3 to designate the entitlement as shared.

{
  "membershipId": "8888000066668888",
  "quantity": 2,
  "module": 4,
  "usageRestriction": 3
}

Response

In the response, the entitlement details for each module will be returned as an array.

Update Membership Entitlements - Response

{
  "code": 0,
  "data": {
    "membershipId": "8888000066668888",
    "entitlements": {
      "moduleExclusiveEntitlements": [
        {
          "module": 1,
          "details": {
            "cardholderExclusiveEntitlements": 1,
            "guestsExclusiveEntitlements": 1,
            "sharedEntitlements": 0,
            "allowedGuestsPerUsage": 1,
            "maxGuestsNextUse": 1
          }
        }
      ]
    }
  }
}

Example 1

{
    "moduleExclusiveEntitlements": [
        {
            "module": 1,
            "details": {
                "cardholderExclusiveEntitlements": 1,
                "guestsExclusiveEntitlements": 1,
                "sharedEntitlements": 0,
                "allowedGuestsPerUsage": 1,
                "maxGuestsNextUse": 1
            }
        }
    ]
}

"module": 1 specifies that the current object lists the entitlement details for the lounge module.

"cardholderExclusiveEntitlements": 1 means this current membership has 1 cardholder-exclusive entitlement for the lounge module.

"guestsExclusiveEntitlements": 1 means that this membership has 1 guest-exclusive entitlement for the lounge module.

"sharedEntitlements": 0 means that this membership has no shared entitlements for the lounge module.

"allowedGuestsPerUsage": 1 specifies that, based on program settings, the maximum number of guests allowed per visit for this membership's lounge entitlement is 1.

"maxGuestsNextUse": 1 specifies that, based on the above entitlements data, the cardholder can bring 1 guest on the next lounge visit.

Example 2

{
    "moduleExclusiveEntitlements": [
        {
            "module": 4,
            "details": {
                "cardholderExclusiveEntitlements": -1,
                "guestsExclusiveEntitlements": 0,
                "sharedEntitlements": 0,
                "allowedGuestsPerUsage": 0,
                "maxGuestsNextUse": 0
            }
        }
    ]
}

"module": 3 specifies that the current object lists the entitlement details for the Dining Coupon module.

"cardholderExclusiveEntitlements": -1 means this current membership has unlimited cardholder-exclusive entitlement for the Dining Coupon module.

"guestsExclusiveEntitlements": 0 means that this membership has no guest-exclusive entitlement for the Dining Coupon module.

"sharedEntitlements": 0 means that this membership has no shared entitlements for the Dining Coupon module.

"allowedGuestsPerUsage": 0 specifies that, based on program settings, the maximum number of guests allowed per visit for this membership's dining set meal module entitlement is 0.

"maxGuestsNextUse": 0 specifies that, based on the above entitlements data, the cardholder is not allowed to bring guests when using this module next time.

Example 3

{
    "moduleExclusiveEntitlements": [
        {
            "module": 1,
            "details": {
                "cardholderExclusiveEntitlements": -1,
                "guestsExclusiveEntitlements": 0,
                "sharedEntitlements": -1,
                "allowedGuestsPerUsage": 4,
                "maxGuestsNextUse": 4
            }
        }
    ]
}

The above response indicates that, under this membership, both the cardholder and guests have unlimited entitlements for the lounge module, but the cardholder can only bring a maximum of 4 guests per visit.

Retrieve membership entitlement information

→ Use the /entitlements/search endpoint to retrieve the membership entitlement information.

Request

Retrieve Membership Entitlement Information - Request

{
    "membershipId": "8888000066668888"
}

Response

Retrieve Membership Entitlement Information - Response

{
    "code": 0,
    "data": {
        "entitlements": {
            "moduleExclusiveEntitlements": [
                {
                    "module": 1,
                    "details": {
                        "cardholderExclusiveEntitlements": 1,
                        "guestsExclusiveEntitlements": 1,
                        "sharedEntitlements": 0,
                        "allowedGuestsPerUsage": 1,
                        "maxGuestsNextUse": 1
                    }
                }
            ]
        }
    }
}