Address Book Assist Widget | Hosted Widgets | Subscribe Pro Documentation

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

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

Address Schema

Property	Type	Description	Required
`id`	number	Subscribe Pro Address ID.	Yes
`environmentId`	number	Subscribe Pro Environment ID.	Yes
`customerId`	number	Subscribe Pro Customer ID.	Yes
`firstName`	string	Customer's first name.	Yes
`middleName`	string	Customer's middle name.	-
`lastName`	string	Customer's last name.	Yes
`company`	string	Name of customer's company.	-
`street1`	string	Street address line 1.	-
`street2`	string	Street address line 2.	-
`city`	string	City or locality name.	-
`region`	string	Region or state name/code.	-
`postcode`	string	Postal code.	-
`country`	string	Country name OR two-letter ISO 3166-1 alpha-2 country code.	-
`phone`	string	Telephone 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.

Parameter	Type	Description
`address`	object	The address JSON object that the customer wants to delete.
`onContinue`	function	Callback 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.

Parameter	Type	Description
`address`	object	The 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.

Parameter	Type	Description
`previousAddress`	object	The address JSON object of the address before it was updated.
`newAddress`	object	The 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.

Parameter	Type	Description
`previousDefaultAddress`	object	The address JSON object of the previous default address.
`newDefaultAddress`	object	The 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.

Parameter	Type	Description
`previousDefaultAddress`	object	The address JSON object of the previous default shipping address.
`newDefaultAddress`	object	The 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.

Parameter	Type	Description
`previousDefaultAddress`	object	The address JSON object of the previous default billing address.
`newDefaultAddress`	object	The 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});

Address Book Assist Widget - Widget Details

Address Schema

Example Addresses

Events & Example Usage

onBeforeAddressDeleted

onAddressCreated

onAddressUpdated

onDefaultAddressChanged

onDefaultShippingChanged

onDefaultBillingChanged