TABLE OF CONTENTS


Note: Updating cardholder fields will update the customer record as well.


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.
  • page
  • pageSize


Returns:

A list of Membership objects.


GET /v2/b2b/membership/summaries/advancedsearch/v2/b2b/membership/summaries/search


Params


This API requires at least 1 search field.  You may send EITHER:

One or a combination of:
  • firstName
  • lastName
  • address
  • zip
  • email
One of: 
  • memberId (accepts ACME Membership Number, External Membership ID, ACME Barcode, or External Barcode)
  • cardName



FieldDescription
pageSizeHow many records to return per page
pageWhich page of the results to return
sortFieldAccepts one value at a time. Available values:

  • name (i.e. Name on Card)
  • externalMembershipId
  • acmeMembershipNumber
  • membershipStanding
  • auxiliary (i.e. Is Aux)
  • membershipLevelCollectionName (i.e. Auxiliary Group Name)
  • membershipCategory (i.e. ACME Level)
  • firstName
  • lastName
  • email
  • cardType
  • streetAddress1
  • city
  • state
  • zipCode
  • membershipJoinedDateDisplay
  • membershipExpirationDateDisplay
  • acmeBarcode
  • barcode (i.e. External Barcode)
  • acmeCustomerNumber
  • category
  • subcategory
sortDirection{asc,desc}
firstNameCardholder's first name
lastNameCardholder's last name
addressCardholder's Street Address 1
zipCardholder's Zip
emailCardholder's email
memberIdAccepts:

  • ACME Membership Number
  • External Membership ID
  • ACME Barcode
  • External Barcode
cardNameSearches the "Name on Card" field for a match


Headers

x-acme-api-key


Example Payload

curl --location 'https://sand8-api.acmeticketing.net/v2/b2b/membership/summaries/advancedsearch?pageSize=50&page=1&sortField=name&sortDirection=desc&firstName=tucker&lastName=reed&email=tucker%40reed.com' \
--header 'x-acme-api-key: XXXXX' \

Example Response

{
    "list": [
        {
            "id": 11155725,
            "visitorId": 2049352,
            "membershipId": 4593324,
            "constituentImportId": "ACME201123685",
            "cardType": "primary",
            "categoryId": "65036194d0c686446a60f583",
            "offeringId": "3eb9ded882354772815ffb19e2716e99",
            "pricePointId": "62bf21f0357c362b5da3ff94",
            "name": "Tucker Reed",
            "barcode": "315517620",
            "acmeBarcode": "315517620",
            "email": "tucker@reed.com",
            "firstName": "Tucker",
            "lastName": "Reed",
            "streetAddress1": "2343 N 24th Ave",
            "streetAddress2": "Apt C",
            "city": "Reno",
            "state": "Idaho",
            "zipCode": "83938",
            "country": "United States",
            "primaryCard": true,
            "externalMembershipId": "321373895",
            "membershipJoinedDate": "2024-01-29T00:00:00-08:00",
            "membershipStartDate": "2024-05-14T00:00:00-07:00",
            "membershipExpirationDate": "2025-01-28T23:59:59-08:00",
            "membershipStanding": "active",
            "membershipCategory": "Student",
            "middleName": "",
            "acmeMembershipNumber": "321373895",
            "cardStartDate": "2024-05-14T00:00:00-07:00",
            "cardExpirationDate": "2025-01-28T23:59:59-08:00",
            "cardStanding": "active",
            "auxiliary": false,
            "customerId": 7240696
        }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 50,
        "sortDirection": "asc",
        "sortField": "id",
        "count": 1
    }
}

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 deactivate 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


FieldDescription
idA unique ID for the membership
importIdA unique value that does not change for the membership.
membershipStandingThe standing of the membership (active, lapsed, new, dropped)
membershipExpirationDateThe date that the membership term will expire.
cardholders []An array of cardholder information. At least the primary card must be sent. 
cardholders[x].idMembership Cardholder ID
cardholders[x].constituentImportIdThe Constituent Import ID for the customer associated with the cardholder. 
  • Required for existing cardholders that are customers. Ensure this matches the correct customer record.
  • When not provided, a new customer will be created and associated to the membership. Use this for new cardholders on a membership.
cardholders[x].cardTypeThe type of cardholder (primary or secondary)
This field is case sensitive. Accepted values are 'primary' or 'secondary'.
cardholders[x].cardStatusValid card status are:
  • new
  • active
  • dropped 
  • lapsed
  • noMembership
  • replaced
cardholders[x].expirationDateCardholder 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].nameThe name on the card.
  • Optional for members that are customers - will be populated by First Name + Last Name if not provided.
  • Required for Name on Card only cardholders.


Additional optional fields are listed here.


Example Payloads


Get Membership Info by ID

GET /v2/b2b/memberships/6911520
Sample JSON Response

{

    "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/
Sample JSON Payload

{

    "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


Sample JSON 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/
Sample JSON Payload

{

    "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


Sample JSON 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"
        }
    ],
  
}