List Memberships
GET /v2/b2b/memberships
Inputs:
- updatedStartTime: (optional) only return memberships updated after this start time.
- updatedEndTime: (optional) only return memberships updated before this time.
- program: (optional) only return memberships of this program type.
- category: (optional) only return memberships of this category.
- subCategory: (optional) only return memberships of this sub category.
- updatedBy: (optional) only return memberships updated by this userId.
Returns:
A list of Membership objects
Get Membership
GET /v2/b2b/memberships/{id}Returns:
The Membership object with the specified membership id. The ID is the Membership Database ID, which can be found in the B2B URL for a given membership.
Update a Membership
PUT /v2/b2b/memberships
Body:
The updated Membership object, which must contain the Membership ID and the Membership Import Id of the Membership being updated. This can be used to update the cardholder demographic information, cardholder dates, or change the dates on the membership. To delete a cardholder, set the cardStatus to "dropped". Note: there must be a primary card that is active throughout the entire length of the membership so if the dates on the membership are changed, the API will require that the primary cardholder dates are changed to match. When creating the body, the primary cardholder must always be included in the list of cards, even if you are not changing anything on that card. Secondaries do not need to be included unless you wish to update information on them.
Returns:
The updated Membership object.
Required Fields
| Field | Description |
| id | A unique ID for the membership |
| importId | A unique value that does not change for the membership. |
| membershipStanding | The standing of the membership (active, lapsed, new, dropped) |
| membershipExpirationDate | The date that the membership term will expire. |
| cardholders [] | An array of cardholder information. At least the primary card must be sent. |
| cardholders[x].id | Membership Cardholder ID |
| cardholders[x].constituentImportId | The Constituent Import ID for the customer associated with the cardholder.
|
| cardholders[x].cardType | The type of cardholder (primary or secondary) This field is case sensitive. Accepted values are 'primary' or 'secondary'. |
| cardholders[x].cardStatus | Valid card status are:
|
| cardholders[x].expirationDate | Cardholder expiration date. Validation will ensure that is is not after the membership expiration date. The primary card must be active through the full membership term otherwise it will error. |
| cardholders[x].name | The name on the card.
|
Additional optional fields are listed here.
Example Payloads
Get Membership Info by ID
GET /v2/b2b/memberships/6911520
{ "id": 6911520, "importId": "ACMEACS314670906", "program": "golden2_program", "category": "golden2_category", "subcategory": "golden2_subcategory", "membershipTypeId": 616, "externalMembershipId": "ACS314670906", "membershipJoinedDate": "2016-12-23T00:00:00-08:00", "membershipStartDate": "2024-02-28T04:16:13-08:00", "membershipExpirationDate": "2025-02-28T23:59:59-08:00", "membershipStanding": "active", "cardholders": [ { "id": 22800544, "membershipId": 6911520, "constituentImportId": "ACMEACS269150004", "constituentId": "ACS269150004", "cardImportId": "ACMEACS369056059", "cardType": "primary", "name": "Vanor Zhang", "barcode": "ACS369056059", "acmeBarcode": "ACS369056059", "firstName": "Vanor", "lastName": "Zhang", "streetAddress1": "46380 Sentinel", "city": "Fremont", "state": "Arizona", "zipCode": "95678", "country": "United States", "deceased": "no", "primaryCard": "yes", "solicitationCodes": "", "startDate": "2024-02-28T04:16:13-08:00", "expirationDate": "2025-02-28T23:59:59-08:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "acmeCustomerNumber": "ACS269150004", "addressId": 1104236, "excludeCardOnMemberCreation": false, "customerId": 1229417, "ignoreUpdates": false }, { "id": 22800545, "membershipId": 6911520, "cardImportId": "ACMEACS374959567", "cardType": "secondary", "name": "Guest of Vanor Zhang", "barcode": "ACS374959567", "acmeBarcode": "ACS374959567", "deceased": "no", "primaryCard": "no", "solicitationCodes": "", "startDate": "2024-02-28T04:16:13-08:00", "expirationDate": "2025-02-28T23:59:59-08:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "excludeCardOnMemberCreation": false, "ignoreUpdates": false } ], "entitlements": [], "membershipCategory": "SFDC Level A", "categoryId": "584f7aa179e71d507664059c", "acmeMembershipNumber": "ACS314670906", "isGift": false, "auxiliaryMembership": false, "offeringName": "SFDC Level A Offering", "updatedOn": "2024-02-28T04:16:14-08:00", "updatedBy": 2258, "offeringId": "069e1a4051aa45ebb53e3705455cb31b", "pricePointId": "598a50281f021633a8691405" } |
Additional fields that may be returned if originally imported with memberships:
- program: The program for this membership.
- category: Name of the membership (e.g. Individual, Dual, Family)
- subcategory: A sub category for this membership.
- fund: The specific financial purposes of gifts. Read Only
- campaign: The overall objective to raise money. Read Only
- appeal: The solicitations and promotions that bring in gifts. Read Only
- membershipTypeId: A linking back to our membership_types table with the type of membership.
- cardholders[x].suburb
The following are ACME internal fields - do not use:
- cardholders[x].visitorId
Update Membership
Scenario: Update the Start Date and Expiration date of the above membership & cardholders.
Note, there are limitations to changing the dates:
1. The primary card must be active for the entire length of the membership.
2. Card start date cannot be before the membership start date.
3. Card expiration date cannot be after the membership expiration date.
PUT /v2/b2b/memberships/
{ "id":6911520, "importId":"ACMEACS314670906", "membershipJoinedDate": "2016-12-23T00:00:00-08:00", "membershipStartDate": "2024-02-20T04:16:13-08:00", "membershipExpirationDate": "2025-03-31T23:59:59-07:00", "membershipStanding":"active", "cardholders":[ { "id":22800544, "constituentImportId":"ACMEACS269150004", "cardType":"primary", "startDate": "2024-02-20T04:16:13-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus":"active", "name": "Vanor Zhang", "firstName": "Vanor", "lastName": "Zhang", "streetAddress1": "46380 Sentinel", "city": "Fremont", "state": "Arizona", "zipCode": "95678", "country": "United States" }, { "id": 22800545, "cardType": "secondary", "name": "Guest of Vanor Zhang", "startDate": "2024-02-20T04:16:13-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus": "active" } ] } |
Response
{ "id": 6911520, "importId": "ACMEACS314670906", "membershipTypeId": 616, "externalMembershipId": "ACS314670906", "membershipJoinedDate": "2016-12-23T00:00:00-08:00", "membershipStartDate": "2024-02-20T00:00:00-08:00", "membershipExpirationDate": "2025-03-31T23:59:59-07:00", "membershipStanding": "active", "cardholders": [ { "id": 22800544, "membershipId": 6911520, "constituentImportId": "ACMEACS269150004", "cardImportId": "ACMEACS369056059", "cardType": "primary", "name": "Vanor Zhang", "barcode": "ACS369056059", "acmeBarcode": "ACS369056059", "firstName": "Vanor", "lastName": "Zhang", "streetAddress1": "46380 Sentinel", "city": "Fremont", "state": "Arizona", "zipCode": "95678", "country": "United States", "deceased": "no", "primaryCard": "yes", "solicitationCodes": "", "startDate": "2024-02-20T00:00:00-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "acmeCustomerNumber": "ACS269150004", "addressId": 1104236, "excludeCardOnMemberCreation": false, "customerId": 1229417, "ignoreUpdates": false }, { "id": 22800545, "membershipId": 6911520, "cardImportId": "ACMEACS374959567", "cardType": "secondary", "name": "Guest of Vanor Zhang", "barcode": "ACS374959567", "acmeBarcode": "ACS374959567", "deceased": "no", "primaryCard": "no", "solicitationCodes": "", "startDate": "2024-02-20T00:00:00-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "excludeCardOnMemberCreation": false, "ignoreUpdates": false } ], "entitlements": [], "membershipCategory": "SFDC Level A", "categoryId": "584f7aa179e71d507664059c", "acmeMembershipNumber": "ACS314670906", "isGift": false, "auxiliaryMembership": false, "offeringName": "SFDC Level A Offering", "updatedOn": "2024-02-28T04:32:38-08:00", "updatedBy": 340, "offeringId": "069e1a4051aa45ebb53e3705455cb31b", "pricePointId": "598a50281f021633a8691405" } |
Update Membership
Scenario: Edit the cardholder details of the above membership. Changing the primary's firstName "Connor", lastName to "Reeves", and name to "Connor L Reeves".
Note, since we are only editing the primary card we do not need to send the secondary as well. If you were to only edit the secondary though, the primary must always be sent as well.
Allowable card edits: name, firstName, lastName, barcode, address, phone, email, startDate, and expirationDate. Note, there are limitations to changing the dates:
1. The primary card must be active for the entire length of the membership.
2. Card start date cannot be before the membership start date.
3. Card expiration date cannot be after the membership expiration date.
PUT /v2/b2b/memberships/
{ "id":6911520, "importId":"ACMEACS314670906", "membershipJoinedDate": "2016-12-23T00:00:00-08:00", "membershipStartDate": "2024-02-20T04:16:13-08:00", "membershipExpirationDate": "2025-03-31T23:59:59-07:00", "membershipStanding":"active", "cardholders":[ { "id":22800544, "constituentImportId":"ACMEACS269150004", "cardType":"primary", "startDate": "2024-02-20T04:16:13-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus":"active", "name": "Connor L Reeves", "firstName": "Connor", "lastName": "Reeves", "streetAddress1": "46380 Sentinel", "city": "Fremont", "state": "Arizona", "zipCode": "95678", "country": "United States" } ] } |
Response
{ "id": 6911520, "importId": "ACMEACS314670906", "membershipTypeId": 616, "externalMembershipId": "ACS314670906", "membershipJoinedDate": "2016-12-23T00:00:00-08:00", "membershipStartDate": "2024-02-20T00:00:00-08:00", "membershipExpirationDate": "2025-03-31T23:59:59-07:00", "membershipStanding": "active", "cardholders": [ { "id": 22800544, "membershipId": 6911520, "constituentImportId": "ACMEACS269150004", "cardImportId": "ACMEACS369056059", "cardType": "primary", "name": "Connor L Reeves", "barcode": "ACS369056059", "acmeBarcode": "ACS369056059", "firstName": "Connor", "lastName": "Reeves", "streetAddress1": "46380 Sentinel", "city": "Fremont", "state": "Arizona", "zipCode": "95678", "country": "United States", "deceased": "no", "primaryCard": "yes", "solicitationCodes": "", "startDate": "2024-02-20T00:00:00-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "acmeCustomerNumber": "ACS269150004", "addressId": 1104236, "excludeCardOnMemberCreation": false, "customerId": 1229417, "ignoreUpdates": false }, { "id": 22800545, "membershipId": 6911520, "cardImportId": "ACMEACS374959567", "cardType": "secondary", "name": "Guest of Vanor Zhang", "barcode": "ACS374959567", "acmeBarcode": "ACS374959567", "deceased": "no", "primaryCard": "no", "solicitationCodes": "", "startDate": "2024-02-20T00:00:00-08:00", "expirationDate": "2025-03-31T23:59:59-07:00", "cardStatus": "active", "printCount": 0, "printStatus": "notPrinted", "excludeCardOnMemberCreation": false, "ignoreUpdates": false } ], "entitlements": [], "membershipCategory": "SFDC Level A", "categoryId": "584f7aa179e71d507664059c", "acmeMembershipNumber": "ACS314670906", "isGift": false, "auxiliaryMembership": false, "offeringName": "SFDC Level A Offering", "updatedOn": "2024-02-28T04:32:38-08:00", "updatedBy": 340, "offeringId": "069e1a4051aa45ebb53e3705455cb31b", "pricePointId": "598a50281f021633a8691405" } |
Update Membership
Scenario: Swap the primary and secondary cardholders.
In order to do this, both cardholders must be true cardholders (attached to a customer). If the secondary is a 'guest of' cardholder, then you must provide enough information in the call to make them a true customer: firstName, lastName, and one of email, phone, or address. For best practice, we always recommend adding address so that when you swap the primary and secondary in the next call, the primary still has an address.
PUT /v2/b2b/memberships/
Sample JSON payload:
Note: the secondary in this example call was only a "Guest of" card. We are providing enough information to turn it into a customer but since there is no customer yet, we are not sending constituentImportId for the secondary. If the secondary in your scenario IS a true customer already, be sure to send that in the payload.
{
"id":4593208,
"importId":"ACME344056729",
"membershipExpirationDate":"2025-04-14T23:59:59-07:00",
"membershipStanding":"active",
"cardholders":[
{
"id":11155604,
"constituentImportId":"ACME212595422",
"cardType":"secondary",
"expirationDate":"2025-04-14T23:59:59-07:00",
"cardStatus":"active",
"name":"Harry Love",
"email":"harry@love.com",
"firstName":"Harry",
"lastName":"Love",
"phoneNumber":"3338883333",
"streetAddress1":"2343 Merlot Lane",
"city":"Reno",
"state":"Nevada",
"zipCode":"89521",
"country":"United States",
"barcode": "HL12345"
},
{
"id":11155605,
"cardType":"primary",
"expirationDate":"2025-04-14T23:59:59-07:00",
"cardStatus":"active",
"name":"Sorsha Love",
"firstName":"Sorsha",
"lastName":"Love",
"email":"sorsha@love.com",
"phoneNumber":"3338883334",
"streetAddress1":"2343 Merlot Lane",
"city":"Reno",
"state":"Nevada",
"zipCode":"89521",
"country":"United States",
"barcode": "SL12345"
}
],
}