Setup 

Use the membership eligible options API to determine what lifecycle actions a membership can take. Afterward, use the checkout API to perform the lifecycle action.  This is only applicable for existing memberships, not new purchases. For memberships to show up in eligible options:

  • The source membership must have the desired lifecycle action enabled
  • The source membership must have a sale channel set for the lifecycle action
  • For any upgrades or downgrades, the source and destination memberships must have an eligible option (configured in backoffice: Membership > Rules > Upgrade/Downgrade)


Eligible Options Request

GET /v2/b2b/membership/eligibleoptions/levels


Request Parameters

Field
Type
Description
Required
membershipIdstringDatabase id of the source membership
yes
saleChannelsstringFilter the result based on a comma-separated list of sale channels. If no channels are included, results for all channels will be shown. Valid sale channels are:
  • online
  • pointOfSale
  • insideSalesIndividual 
  • customerRep
  • salesForce



actionsstringFilter the result based on a comma-separated list of lifecycle actions. If no actions are included, results for all actions will be shown. Valid lifecycle actions are:
  • upgrade
  • downgrade
  • renew
  • renewUpgrade
  • renewDowngrade
  • postTermRenew
  • postTermRenewUpgrade
  • postTermRenewDowngrade
  • rejoin
  • rejoinUpgrade
  • rejoinDowngrade

summarizebooleanOmit some offering details to make the result more readable. It is recommended to set this as true. The default is false. 


Mapping of the actions to the order item types

This table shows based on the eligible actions for a given membership, (ie what is the member allowed to do), what order item type does this correspond to for checking out.


MembershipLevelChangeTypeOrder Item type
upgradeMembershipUpgrade
downgradeMembershipDowngrade
renewMembershipRenewal

renewUpgrade

MembershipRenewalUpgrade

renewDowngrade

MembershipRenewalDowngrade

postTermRenew

MembershipPostTermRenewal

postTermRenewUpgrade

MembershipPostTermRenewalUpgrade

postTermRenewDowngrade

MembershipPostTermRenewalDowngrade

rejoin

MembershipRejoin

rejoinUpgrade

MembershipRejoinUpgrade

rejoinDowngrade

MembershipRejoinDowngrade

   

Sample Request

GET https://sand10-buy.acmeticketing.net/v2/b2c/membership/eligibleoptions/levels/?membershipId=3247483&saleChannels=online,pointOfSale&actions=upgrade,downgrade


Eligible Options Response

The eligible options response object is complex, as such it is recommended to use summarize = true.


Membership Level Change Eligibility With Refund Object


Field
Type
Description
refundAmountcurrencyAmount paid for the membership. Only applicable for memberships purchased in ACME
membershipOptionsMembership Level Change Eligibility Objectsee below
externalMembershipbooleanindicates whether the membership was purchased in ACME
canCancelbooleanindicates whether the membership can cancel
membershipIdLongdatabase id of the membership



Membership Level Change Eligibility Object


Field
Type
Description
idstringThe id of the eligibility object. Level change eligibility objects are created when upgrade/downgrade mappings are set in backoffice
sourceMembershipLevelMembership Level Objectthe source membership level, including offerings and price points
eligibleMembershipLevelsa list of Eligible Membership Level Objectssee below



Eligible Membership Level Object


Field
Type
Description
typeMembership Level Change Type EnumThe lifecycle action applicable to this group of levels. Same possible values as actions in the request. 
targetLevelsa list of Membership Level ObjectsAll possible destination levels for the current membership level change type.



Sample Response

"refundAmount": "3.00",
"membershipOptions": {
    "id": "598a53e368d6096e9bfa4f23",
    "sourceMembershipLevel": {
        "id": "598a53acc1a3ef6ec7227398",
        "name": "SFDC Gold",
        "description": "<p>Long Description SFDC Gold</p>",
        "shortDescription": "Short Description SFDC Gold",
        "rules": {
            "numberOfCardHolders": 3,
            "canGift": true,
            "startBeginningOfMonth": false,
            "expireEndOfMonth": false
        },
        "benefits": [
            {
                "description": "Benefit SFDC Gold A"
            },
            {
                "description": "Benefit SFDC Gold B"
            }
        ],
        "offerings": [
            {
                "id": "2e6700bd99b64af69fa62f1eb166c83f",
                "name": "Offering SFDC Gold",
                "subtitle": "Subtitle SFDC Gold",
                "description": "Short Description SFDC Gold",
                "duration": 12,
                "benefits": [],
                "rules": {
                    "numberOfCardHolders": 0,
                    "canGift": false,
                    "startBeginningOfMonth": false,
                    "expireEndOfMonth": false
                },
                "priceLists": [
                    {
                        "id": "598a534ec1a3ef6ec7227393",
                        "name": "Offering SFDC Gold",
                        "description": "Subtitle SFDC Gold",
                        "prices": [
                            {
                                "personType": {
                                    "id": "598a50281f021633a8691405",
                                    "name": "QA SFDC Membership",
                                    "description": "QA SFDC Membership Category",
                                    "active": true,
                                    "type": "Membership",
                                    "displayOrder": 0
                                },
                                "price": "3.00",
                                "primePrice": "0.00",
                                "displayOrder": 1,
                                "pricePoint": {
                                    "id": "598a50281f021633a8691405",
                                    "name": "QA SFDC Membership",
                                    "description": "QA SFDC Membership Category",
                                    "active": true,
                                    "type": "Membership",
                                    "displayOrder": 0
                                },
                                "discountedPrice": "3.00"
                            }
                        ],
                        "priceListType": "membership",
                        "startTime": "2018-06-21T14:24:49-07:00"
                    }
                ],
                "externalMembershipPriceRequired": false,
                "membershipStartDate": "2021-05-01T00:00:00-07:00",
                "membershipExpirationDate": "2022-04-30T23:59:59-07:00"
            }
        ],
        "state": "published",
        "membershipLevelGroup": "individualAndFamily",
        "displayOrder": 3,
        "subtitle": "Subtitle SFDC Gold",
        "auxiliary": false
    },
    "eligibleMembershipLevels": [
        {
            "type": "downgrade",
            "targetLevels": [
                {
                    "id": "598a50e8ca6afe3dc034be1e",
                    "name": "SFDC Bronze",
                    "description": "<p>Long Description SFDC Bronze</p>",
                    "shortDescription": "Short Description SFDC Bronze",
                    "rules": {
                        "numberOfCardHolders": 2,
                        "canGift": true,
                        "startBeginningOfMonth": false,
                        "expireEndOfMonth": false
                    },
                    "benefits": [
                        {
                            "description": "Benefit SFDC Bronze A"
                        },
                        {
                            "description": "Benefit SFDC Bronze B"
                        }
                    ],
                    "offerings": [
                        {
                            "id": "2bd9c162c4f0484bab5736910d112559",
                            "name": "Offering SFDC Bronze",
                            "subtitle": "Subtitle SFDC Bronze",
                            "description": "Short Description SFDC Bronze",
                            "duration": 12,
                            "benefits": [],
                            "rules": {
                                "numberOfCardHolders": 0,
                                "canGift": false,
                                "startBeginningOfMonth": false,
                                "expireEndOfMonth": false
                            },
                            "priceLists": [
                                {
                                    "id": "598a506261a30735e69e6bca",
                                    "name": "Offering SFDC Bronze",
                                    "description": "Offering Details SFDC Bronze",
                                    "prices": [
                                        {
                                            "personType": {
                                                "id": "598a50281f021633a8691405",
                                                "name": "QA SFDC Membership",
                                                "description": "QA SFDC Membership Category",
                                                "active": true,
                                                "type": "Membership",
                                                "displayOrder": 0
                                            },
                                            "price": "1.00",
                                            "primePrice": "0.00",
                                            "displayOrder": 1,
                                            "pricePoint": {
                                                "id": "598a50281f021633a8691405",
                                                "name": "QA SFDC Membership",
                                                "description": "QA SFDC Membership Category",
                                                "active": true,
                                                "type": "Membership",
                                                "displayOrder": 0
                                            },
                                            "discountedPrice": "-2.00"
                                        }
                                    ],
                                    "priceListType": "membership",
                                    "startTime": "2019-05-31T11:37:12-07:00"
                                }
                            ],
                            "externalMembershipPriceRequired": false,
                            "membershipStartDate": "2020-04-27T00:00:00-07:00",
                            "membershipExpirationDate": "2021-04-30T23:59:59-07:00"
                        }
                    ],
                    "state": "published",
                    "membershipLevelGroup": "individualAndFamily",
                    "displayOrder": 5,
                    "subtitle": "Subtitle SFDC Bronze",
                    "auxiliary": false
                },
                {
                    "id": "598a524e554bd476dc83e9de",
                    "name": "SFDC Silver",
                    "description": "<p>Long Description SFDC Silver</p>",
                    "shortDescription": "Short Description SFDC Silver",
                    "rules": {
                        "numberOfCardHolders": 2,
                        "canGift": true,
                        "startBeginningOfMonth": false,
                        "expireEndOfMonth": false
                    },
                    "benefits": [
                        {
                            "description": "Benefit SFDC Silver A"
                        },
                        {
                            "description": "Benefit SFDC Silver B"
                        }
                    ],
                    "offerings": [
                        {
                            "id": "5a14bedd80ad4466958da4989394fe11",
                            "name": "Offering SFDC Silver",
                            "subtitle": "Subtitle SFDC Silver",
                            "description": "Short Description SFDC Silver",
                            "duration": 12,
                            "benefits": [],
                            "rules": {
                                "numberOfCardHolders": 0,
                                "canGift": false,
                                "startBeginningOfMonth": false,
                                "expireEndOfMonth": false
                            },
                            "priceLists": [
                                {
                                    "id": "598a51ebf71d1a492abce485",
                                    "name": "Offering SFDC Silver",
                                    "description": "Subtitle SFDC Silver",
                                    "prices": [
                                        {
                                            "personType": {
                                                "id": "598a50281f021633a8691405",
                                                "name": "QA SFDC Membership",
                                                "description": "QA SFDC Membership Category",
                                                "active": true,
                                                "type": "Membership",
                                                "displayOrder": 0
                                            },
                                            "price": "2.00",
                                            "primePrice": "0.00",
                                            "displayOrder": 1,
                                            "pricePoint": {
                                                "id": "598a50281f021633a8691405",
                                                "name": "QA SFDC Membership",
                                                "description": "QA SFDC Membership Category",
                                                "active": true,
                                                "type": "Membership",
                                                "displayOrder": 0
                                            },
                                            "discountedPrice": "-1.00"
                                        }
                                    ],
                                    "priceListType": "membership",
                                    "startTime": "2018-06-21T14:24:31-07:00"
                                }
                            ],
                            "externalMembershipPriceRequired": false,
                            "membershipStartDate": "2020-04-27T00:00:00-07:00",
                            "membershipExpirationDate": "2021-04-30T23:59:59-07:00"
                        }
                    ],
                    "state": "published",
                    "membershipLevelGroup": "individualAndFamily",
                    "displayOrder": 2,
                    "subtitle": "Subtitle SFDC Silver",
                    "auxiliary": false
                }
            ]
        }
    ]
},
"externalMembership": false,
"canCancel": true,
"membershipId": 3247483


Note that this sample response has summarize = true. With summarize = false it will be a lot longer!