THE ESSENTIALS

Here below are some common terms used throughout CRM.COM regarding pass plans and passes.

Pass Plan

Generating passes requires defining a pass plan that outlines the characteristics and behaviour of the passes.

Classifications

The pass plan Classification setting determines the type of passes that will be generated by the pass plan and their key characteristics.

• Promotion - The pass can only be redeemed against a reward offer or a promotion when placing an order and is subject to the conditions of the reward offer or promotion.

• Gift - This pass is typically used by someone other than the purchaser. The beneficiary can be either a registered contact or an anonymous contact in the system.

• Top-up - The pass would normally be used by the purchaser themselves to top-up their Business Pocket balance.

Distribution Method

Passes can be generated either in printed or electronic format.

• Printed Passes - These are pre-generated with a unique code and are usually sold over the counter.

• Electronic Passes - These are generated on demand via third-party integrators, e.g. through a portal.

Validity

Validity is defined by the pass plan and inherited by each individual pass at the time of creation; it defines the period in which the pass must be redeemed. If a pass is not redeemed within the validity period, then it expires, and the Contact can no longer benefit from it.

The pass validity date should not be confused with the pass value expiration date - this is an optional setting that determines whether the pass's value (which has been redeemed to the Business Commerce Pocket) will expire if not consumed by a specific date.

Pass Value

Pass plans of type gift or top-up allow a fixed or variable pass value to be set for both printed and electronic passes. A value is not required for promotion passes since it will be determined by the reward offer they are linked to.

• Fixed - The pass value is fixed, and all passes generated for the pass plan will have the same value (e.g. €50)

• Variable - A minimum and maximum value range is set on the pass plan (e.g. €50-€250), allowing the actual pass value to be set either at the time of creation (for electronic passes), or at a later stage but before being redeemed (for printed passes).

Pass Code Format

Every pass generated by the system has a pass code; for promotion-type passes, the pass code can either be a unique code or a single code for all passes. For gift and top-up passes, the pass code is always unique. CRM.COM allows the pass code format to be defined by the system user and is adhered to when creating the passes.

PIN

Gift and top-up passes can optionally carry a PIN for additional security purposes. This implies that the contact must provide the pass code and PIN to initially redeem the pass, and then for each purchase where the pass funds will be spent. PINs are not applicable for promotion passes.

State

From the moment of creation, each pass has a state that dictates its current situation and permitted actions.

• Draft - The pass has been generated but is not yet ready to be redeemed; a pass in this state would normally then become Active

• Active - The pass is ready to be Redeemed (after setting a value for variable value passes)

• Redeemed - The pass has been used, i.e. the promotion was consumed, or the Contact’s wallet has been credited with the value of the pass and can be spent for future purchases

• Cancelled - The pass is cancelled and cannot be used; only Draft and Activate passes can be cancelled

Hashing

Hashing is a feature that can be optionally enabled to scramble pass codes using a specific algorithm. The hashed pass code is used instead of the actual pass code in subsequent API calls.

Generating Passes

This is the process of creating a pass and can be achieved in one of two ways:

• Electronic passes - These are created on demand (i.e. not pre-created) and can either be created via an API call from a third-party integration system or through a landing page configured in CRM.COM.

• Printed passes - These are pre-created either via the back-end system or via the respective API call.

Redeeming a Pass

Redeeming a pass is the action whereby the Contact’s wallet is credited with the value of the (Gift or Top-up) pass so that the Contact can spend the wallet funds, or the (Promotion) pass was used to enable an offer during a purchase, thus resulting in an instant price reduction.

A gift or top-up pass can be redeemed either by calling the Redeem Pass self-service API (when redeeming through front-end apps) or via the back-end system UI from the Contact screen.

Promotion passes can only be redeemed as part of a Create Purchase Event API call from an integration system.

In any case, when a Contact redeems a pass, the Contact information (e.g. name and email) is added to the pass.

Commerce Pool Conditions

Commerce pool conditions are the spending rules which dictate how/where the value of the pass can be spent. These conditions are optionally set on the pass plan configuration and only apply to Gift and Top-up passes.

Exporting Passes

The passes of a pass plan can be exported in .csv format and are automatically emailed to the logged-in user’s email address.

Gift Pass Beneficiary Information

The pass beneficiary is the person who received a pass and can redeem it. In CRM.COM, the beneficiary information (i.e. name, email/phone) is only necessary for electronic Gift passes and is provided by the person purchasing the gift pass. This information is subsequently used to notify the beneficiary that they have been sent a gift pass with instructions on redeeming and using it.

Managing Pass Plans & Passes

Pass Plans

A Pass Plan defines the behaviour and characteristics of the passes to be generated; it’s necessary to configure a Pass Plan to be able to generate passes of any type.

To view or create a new Pass Plan, navigate to Finance > Pass Plans using the main menu on the left-hand side of the screen.

Open

Select Create Pass Plan to create a new pass plan.

Open

Name

Provide a unique name for the pass plan.

Classifications

Pass Plans can be classified into one of three types:

• Promotion - Promotion passes consume a Reward Offer and abide by the offer definition regarding the applicable discount (amount or percentage) and award & spend conditions. Promotion-type passes can be configured for multiple uses but require an accompanying communication plan to notify the relevant Contacts of the promotion pass or offer details.

• Gift - A Gift pass would normally be purchased and loaded with an amount of money before being offered to another person as a gift. The beneficiary of the gift pass can be either an existing Contact in the system or an unnamed Contact.

• Top-up - Top-up passes are usually purchased to credit the wallet of an existing Contact, who uses their wallet to pay for subsequent purchases

These are the main characteristics of the three types of Pass Plan classifications, which in turn determine the behaviour of the passes to be generated.

Validity

The validity setting of the pass plan defines the duration of time whereby the pass must be redeemed and not the actual expiration of already redeemed pass funds in the Contact’s wallet. The validity of each pass is set when the pass is created and according to the pass plan setting.

Available validity settings are:

• Always - The passes generated through this pass plan will never expire; they can be redeemed without any date restrictions

• Period - Set a validity period using day, month, and year time intervals; a pass will expire if not redeemed within the defined time period from the date of creation

• Date - Passes will expire on a fixed date if not redeemed

Printed Passes vs Electronic Passes

Pass plans (and subsequently, passes) can be defined as either having a printed or electronic format. Printed passes are pre-generated (via the backend system or API) and can have a fixed or variable value. They can also be exported for printing purposes. Electronic passes are generated on demand (only via API) and again support fixed or variable values.

Number of Passes

The number of passes determines the maximum number of passes that can be generated using the specific Pass Plan. If the Pass Plan is configured for printed passes, then the number of passes to be generated must be set. For electronic Pass Plans, a maximum number of passes can be set, or use 0 (zero) for an unlimited number.

If a maximum number of passes has been defined for a Pass Plan, then no more passes can be generated once the maximum number has been reached.

Pass Values

Both printed and electronic (gift or top-up) passes can be defined as having either fixed or variable values.

• Fixed value - The value of the pass is set when the pass is created and cannot be amended

• Variable value - The value of the pass must be within the given range; it can either be set upon creation or at a later stage (via an API call), but certainly before redeeming the pass

Which wallet balance to credit with the value of the pass

Define which of the Contact’s wallet balances, Open or Commerce, will be credited upon redeeming the pass. Open (Business Pocket) funds can be consumed unconditionally, whereas Commerce (Business Commerce Pocket) funds can be subject to spend conditions (commerce pool rules), e.g. the pass funds can be spent at specific locations, and/or on specific products, and/or within a given time frame.

Commerce Pool Rules

Adding conditional spending rules to the pass plan configuration can restrict how and when the pass value can be spent; such conditions can only be set if the Commerce wallet balance will be credited upon redeeming the pass.

Commerce pool rules can be created and re-used, or new rules can be created on-the-fly. Either select an existing commerce pool condition or choose Create new Commerce Pool to create a new one instantly.

When creating a new commerce pool rule, you will be prompted to provide a Pool Rule name and the restrictions to be applied, choose from the following:

• Time - Set specific days and/or times when the funds can be spent; any day and any time is the default

• Location - Set specific locations where the funds can be spent; any location is the default

• Products - Select specific products to spend the funds on (using families, types, brands or SKUs); spending is allowed on all products by default

• Expiration - Select the pass funds expiry period, e.g. any unconsumed pass funds will expire 1 year after redeeming the pass

Pass Code Format

Define the format of a pass code when it is created. Pass codes are randomly generated (i.e., they are not sequential numbers) and are unique across the business.

Format

• Alphanumeric - pass codes will consist of a combination of letters and numbers (e.g. 3YX7DDG08)

• Alphabetic - pass codes will consist of letters only (e.g. UNLRXDQU)

• Numeric - only numbers will be used for pass codes (e.g. 811256347026)

Length

Define the length of the pass code, not including the prefix and suffix; the minimum permitted length is 7, and the maximum is 16.

Prefix

Provide a prefix to proceed with all pass codes for this pass plan. Multiple pass plans can use the same prefix (e.g. if the prefix is ‘GIFT’, then the pass code would be GIFT811256347026).

Suffix

Provide a suffix to be added at the end of all pass codes (e.g. if the suffix is ‘GIFT', then the pass code would be 811256347026GIFT).

PINs

Will the passes have an associated PIN? If so, then the pass PIN is initially required to redeem the pass, and after that, for any future purchases that consume pass funds. PINs have a length of 4 digits.

Custom Preferences

Custom fields can be used to include any additional data on passes that are not covered by CRM.COM. Whenever a new pass is created, the value of the custom fields will be automatically copied.

If you need to modify the custom fields of a printed pass, you have two options. Firstly, you can make use of the Update Pass API. Secondly, for printed passes only, you can access and edit the individual pass custom fields through the back-end system while the pass is still in the Draft state. To do so, navigate to Finance > Pass Plans > Manage Passes > View Pass in the back-end system.

In addition, custom fields are also included in the exported pass files.

Refer to the Custom Extensibility manual for information on configuring and managing custom fields.

Activating a Pass Plan

Once a Pass Plan has been defined and saved, it appears in an Inactive state on the Pass Plan summary screen. A Pass Plan must be Activated to allow passes to be generated.

• Navigate to the Pass Plan summary screen

• Locate the Pass Plan and select pass plan options (…) > Activate

Generating & Activating Printed Passes

Electronic passes are generated, activated and redeemed upon demand through API calls, typically via third-party system integration. Electronic gift passes can also be generated through a Landing page configured via the back-end system.

However, printed passes must be pre-generated and activated in order to be used:

• Navigate to the Pass Plan summary screen

• Locate the Pass Plan for printed passes

• Select pass plan options (…) > Generate (number of passes generated in accordance to Pass Plan configuration)

• Locate the Pass Plan

• Select Pass Plan options (…) > Manage Passes (this option is available only after passes have been generated)

• Select options (…) > Activate All Passes

A batch of printed passes will typically be activated once they have been printed and distributed.

Activating a single printed pass

It’s also possible to activate individual passes instead of activating all passes of a pass plan.

• Select Pass Plan options (…) > Manage Passes to see all the passes generated for the pass plan

• From the Actions column, select the button with the tick

Cancelling Passes

Similarly, to cancel all passes of a pass plan or just a single pass:

• Select Pass Plan options (…) > Manage Passes to see all the passes generated for the pass plan

• Select the options button (…) > Cancel all passes

OR

• Select the prohibited symbol under the Actions column to cancel a single pass

Sending Electronic Pass Communications

In cases where Gift or Top-up electronic passes are purchased from an online platform, or Promotion passes need to be distributed by a business, it’s necessary to send a communication to the beneficiary in order to inform them that they have received a pass, and how to go about using it. In such cases, an Automation with communication or a Communication plan must be configured.

Promotion passes

It should be noted that the only way to communicate promotion pass details to Contacts is through the use of a Communication Plan.

• If the Promotion pass is configured to use the same pass code for all Contacts, simply type the pass code in the communication plan message area (e.g. ‘use pass code 123456 on your next purchase…)

• If the Promotion pass is configured to use a unique pass code per Contact, use the #link_for_pass communication tag in the message area, and select the respective pass plan from the listed promotion pass plans

• Use the same segment in the communication plan as for the reward offer so that only those Contacts who are eligible for the offer will get the communication

Gift & Top-up Passes

To communicate the details of an electronic Gift or Top-up pass, you need to configure an Automation with a trigger event of Generate Electronic Passes, along with the communication content to be sent to the beneficiary of the pass.

Copying Pass Plans

A back-end system user can copy an existing pass plan and its configuration. The user must provide a unique pass plan name and any other settings can be changed before the pass plan is saved.

When copying the pass plan, it’s possible to copy it in another currency, too.

Passes

Redeeming a Pass via the back-end

It’s possible for a user to redeem a pass for an existing Contact through the back-end system.

• Contacts > My Contacts

• Locate and select the Contact

• Select the Financials tab

• Select the Options button (…)

• Redeem Pass

If the pass is redeemed successfully, the Contact’s wallet will be credited with the value of the pass.

Good to Know

1. Electronic passes are largely managed through third-party integration systems with the use of APIs, or through Landing Pages for electronic gift passes.

2. When variable value printed passes are generated, the pass value is not set until the pass has been purchased.

3. Passes with a state of Active can be redeemed, whereas passes with a state of Inactive or Cancelled cannot be redeemed.

4. Only passes in Draft state can be cancelled.

5. A whole batch of printed passes can be Activated or Cancelled in one go, or a single pass at a time.

6. If a pass has an accompanying PIN, then it must be provided to redeem the pass, and also when using the pass to pay for purchases.

7. Promotion and Top-up passes can only be redeemed for existing (registered) Contacts in the system.

8. Gift passes can be redeemed for both existing and non-existing Contacts. In the case of a non-existing Contact, the system will create a fictitious Contact with the pass code set as the Contact name.

9. Upon redeeming a Gift or Top-up pass, the Contact's wallet is credited with the value of the pass.

10. A Promotion Pass Plan is linked to a reward offer. In such cases, the reward offer will need to be defined and activated before configuring the Pass Plan.

11. A Promotion Pass Plan should be accompanied by the relevant communication informing the eligible Contacts of the pass code and validity period.

12. An Automation with a message must be configured to send to the electronic Gift or Top-up pass beneficiary with their pass code information, unless the business has a different process in place.

13. Automations can be configured to trigger webhooks upon creation of both printed passes (e.g. for a printing house) and electronic passes.

Pass Settings

Configure pass settings by navigating to Settings (from the sidebar menu) > Financials > Passes.

Enable Hashing

If you want to use hashed pass codes, you must enable this setting and choose the hashing algorithm. Available algorithms:

• SHA-1

If you decide to implement hashing of pass codes, you must use the hashed pass codes for any integrations with CRM.COM.

Landing Pages & Mobile Passes

(Settings > Platform > Contact Facing Essentials > Landing Pages/Mobile Pass Cards)

CRM.COM provides an additional stand-alone solution for purchasing passes through a web page (Landing page for Purchasing a pass) which can be created and managed through the back-end system. The pass recipient can then register and redeem their pass using another Landing Page (to Register a Contact), with the option of uploading their pass funds to either an Apple Wallet or an (Android) Wallet Passes app. Refer to the Landing Pages and Mobile Pass Cards manuals for more details.

Reports

Check out the passes-related reports by navigating to Analytics > Reports > Passes.

Reference Material

You may also find it useful to refer to the following manuals for further reading about to Passes.

Passes Integration Guide

https://crmcom.stoplight.io/docs/integrators-hub/branches/main/53i7g8plaod7a-introduction

Contacts

https://crmdevelopment.atlassian.net/wiki/spaces/CRM/pages/424247365

CRM.COM Wallet

https://crmdevelopment.atlassian.net/wiki/spaces/CRM/pages/1938882561

Accounts

Communications

Reward Offers

Automations

Integrations

Landing Pages

Mobile Pass Cards

TABLE OF CONTENTS