Address Book Assist Widget - Widget Details


Details regarding all of the Address Book Widget methods, including the address schema and example usage.

Please see our Widget Configuration docs for more information about the UI modals.

Address Schema

PropertyTypeDescriptionRequired
idnumberSubscribe Pro Address ID.Yes
environmentIdnumberSubscribe Pro Environment ID.Yes
customerIdnumberSubscribe Pro Customer ID.Yes
firstNamestringCustomer's first name.Yes
middleNamestringCustomer's middle name.-
lastNamestringCustomer's last name.Yes
companystringName of customer's company.-
street1stringStreet address line 1.-
street2stringStreet address line 2.-
citystringCity or locality name.-
regionstringRegion or state name/code.-
postcodestringPostal code.-
countrystringCountry name OR two-letter ISO 3166-1 alpha-2 country code.-
phonestringTelephone number associated with the address.-

Example Addresses

Address:

var address = {
  id: 54321,
  environmentId: 2345,
  customerId: 12345,
  firstName: 'Joe',
  lastName: 'Jones',
  company: 'Stuff',
  street1: '123 St',
  street2: 'Apt B',
  city: 'Baltimore',
  region: 'MD',
  postcode: '21224',
  country: 'United States',
  phone: '123-456-7890',
};

New Address:

var newAddress = {
  environmentId: 2345,
  customerId: 12345,
  firstName: 'Joe',
  lastName: 'Jones',
  company: 'Stuff',
  street1: '123 St',
  street2: 'Apt B',
  city: 'Baltimore',
  region: 'MD',
  postcode: '21224',
  country: 'United States',
  phone: '123-456-7890',
};

Events & Example Usage

The Address Book widget uses the following methods that may be called depending on the customer's actions from the website's address book page:

onBeforeAddressDeleted

If the specified address is used for one or more subscriptions, a modal window will give the customer the option to select a different address for the subscription(s) before that address is deleted. If the specified address is not used for any subscriptions - or if the customer doesn't have any additional addresses to replace it - a simple confirmation modal will be shown to confirm the deletion of the address.

ParameterTypeDescription
addressobjectThe address JSON object that the customer wants to delete.
onContinuefunctionCallback function created by the client to proceed once the customer has made their choice in the modal. This function should expect the specified address as well as a string value as its parameters -- not_found if the address isn't found in Subscribe Pro (in which case the site should present its default address deletion modal), delete if the customer chose to delete the address, and do_not_delete if the customer clicked the cancel button.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var address = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

function onContinue(address, result) {
  if (result === 'delete')
    // Delete the address
    ...
  else if (result === 'do_not_delete')
    // Don't delete
    ...
  else if (result === 'not_found')
    // Show site's delete modal
    ...
}

// When a customer deletes a payment profile
AddressBookAssist.onBeforeAddressDeleted({address}, onContinue);

onAddressCreated

The new address is created in Subscribe Pro via API.

ParameterTypeDescription
addressobjectThe address JSON object that the customer just created in the address book.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var address = {
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

// newAddress is the address returned from Subscribe Pro API containing the SP address ID
const newAddress = await AddressBookAssist.onAddressCreated({address});

onAddressUpdated

The previousAddress is updated to the newAddress in Subscribe Pro via API.

ParameterTypeDescription
previousAddressobjectThe address JSON object of the address before it was updated.
newAddressobjectThe address JSON object of the updated address.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var previousAddress = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

var newAddress = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'New Company',
    "street1": '456 Road',
    "city": 'New City',
    "region": 'MD',
    "postcode": '67890',
    "country": 'United States',
    "phone": '123-456-7890',
}
// updatedAddress is the address returned from Subscribe Pro API
const updatedAddress = await AddressBookAssist.onAddressUpdated({previousAddress, newAddress});

onDefaultAddressChanged

When the customer sets a newDefaultAddress, a UI modal will display to allow the customer the option to apply the new default address to their subscriptions. In the modal, they're able to specify whether the new default should be used for billing, shipping, both, or neither. If the previousDefaultAddress is used on subscriptions, that modal will also include the option to apply the new default only to the subscriptions currently using the previous default address.

NOTE: This method should not be called on address book pages with specific Default Shipping Address and Default Billing Address options. For pages using those options, see onDefaultShippingChanged and onDefaultBillingChanged below.

ParameterTypeDescription
previousDefaultAddressobjectThe address JSON object of the previous default address.
newDefaultAddressobjectThe address JSON object of the new default address.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var previousDefaultAddress = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

var newDefaultAddress = {
    "id": 65432,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "street1": '456 Road',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21231',
    "country": 'United States',
    "phone": '123-456-7890',
}

AddressBookAssist.onDefaultAddressChanged({previousDefaultAddress, newDefaultAddress});

onDefaultShippingChanged

When the customer sets a new default shipping address, a UI modal will display to allow the customer the option to apply the newDefaultAddress to the shipping addresses on their subscriptions. If the previousDefaultAddress is still used on subscriptions, that modal will also include the option to apply the new default only to the subscriptions using the previous default shipping address.

NOTE: This method should only be called on address book pages with a specific Default Shipping Address option. For pages using the generic Default Address option, see onDefaultAddressChanged above.

ParameterTypeDescription
previousDefaultAddressobjectThe address JSON object of the previous default shipping address.
newDefaultAddressobjectThe address JSON object of the new default shipping address.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var previousDefaultAddress = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

var newDefaultAddress = {
    "id": 65432,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "street1": '456 Road',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21231',
    "country": 'United States',
    "phone": '123-456-7890',
}

AddressBookAssist.onDefaultShippingChanged({previousDefaultAddress, newDefaultAddress});

onDefaultBillingChanged

When the customer sets a new default billing address, a UI modal will display to allow the customer the option to apply the newDefaultAddress to the billing addresses on their subscriptions. If the previousDefaultAddress is still used on subscriptions, that modal will also include the option to apply the new default only to the subscriptions using the previous default billing address.

NOTE: This method should only be called on address book pages with a specific Default Billing Address option. For pages using the generic Default Address option, see onDefaultAddressChanged above.

ParameterTypeDescription
previousDefaultAddressobjectThe address JSON object of the previous default billing address.
newDefaultAddressobjectThe address JSON object of the new default billing address.

Example usage:
var widgetConfig = {
    version: 2,
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    themeName: 'my-custom-theme-name',
    modals: {
      ...
    }
};

AddressBookAssist.init(widgetConfig);

var previousDefaultAddress = {
    "id": 54321,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "company": 'Stuff',
    "street1": '123 St',
    "street2": 'Apt B',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21224',
    "country": 'United States',
    "phone": '123-456-7890',
};

var newDefaultAddress = {
    "id": 65432,
    "environmentId": 2345,
    "customerId": 12345,
    "firstName": 'Joe',
    "lastName": 'Jones',
    "street1": '456 Road',
    "city": 'Baltimore',
    "region": 'MD',
    "postcode": '21231',
    "country": 'United States',
    "phone": '123-456-7890',
}

AddressBookAssist.onDefaultBillingChanged({previousDefaultAddress, newDefaultAddress});