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 |
|---|---|---|---|
| membershipId | string | Database id of the source membership | yes |
| saleChannels | string | Filter 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:
| |
| actions | string | Filter 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:
| |
| summarize | boolean | Omit 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.
| MembershipLevelChangeType | Order Item type |
| upgrade | MembershipUpgrade |
| downgrade | MembershipDowngrade |
| renew | MembershipRenewal |
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 |
|---|---|---|
| refundAmount | currency | Amount paid for the membership. Only applicable for memberships purchased in ACME |
| membershipOptions | Membership Level Change Eligibility Object | see below |
| externalMembership | boolean | indicates whether the membership was purchased in ACME |
| canCancel | boolean | indicates whether the membership can cancel |
| membershipId | Long | database id of the membership |
Membership Level Change Eligibility Object
Field | Type | Description |
|---|---|---|
| id | string | The id of the eligibility object. Level change eligibility objects are created when upgrade/downgrade mappings are set in backoffice |
| sourceMembershipLevel | Membership Level Object | the source membership level, including offerings and price points |
| eligibleMembershipLevels | a list of Eligible Membership Level Objects | see below |
Eligible Membership Level Object
Field | Type | Description |
|---|---|---|
| type | Membership Level Change Type Enum | The lifecycle action applicable to this group of levels. Same possible values as actions in the request. |
| targetLevels | a list of Membership Level Objects | All 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": 3247483Note that this sample response has summarize = true. With summarize = false it will be a lot longer!