¶ Manage Voucher Programs Using Templates

Voucher Templates streamline the process of creating voucher programs by allowing users to define reusable sets of parameters. Instead of configuring a nearly identical voucher program from scratch each time, users can create a template once and generate multiple voucher programs from it.

We highly recommend implementing support for creating, managing, and utilizing voucher templates, as they help standardize workflows, reduce redundancy, and improve efficiency.

¶ Create Voucher Template

The Create Voucher Template endpoint allows users to define a reusable voucher template. Once created, this template can be used to generate multiple voucher programs.

Path Parameters

• organization_id (Path Parameter): The identifier of the U4B Organization for which the voucher template is being created.

Template Configuration

• General Fields

  • template_name: The name of the voucher template.
  • campaign_name: The default name displayed to riders for voucher programs created from this template.
  • timezone: The timezone used for the voucher template’s start and end time.
    • If not specified, the default timezone will be UTC.
    • A list of valid timezones can be found under the TZ column here.
  • currency_code: The currency of the offer value in this format.
  • is_fully_covered: Indicates whether trips are fully funded by the organization (true if fully covered).

• Value & Recurrence

  • value_recurrence_period: Defines the recurrence period for each voucher’s trip or credit allowance.
    • Default: SINGLE (no recurrence).
    • Can be set to DAILY or MONTHLY.
    • Example: If set to MONTHLY and value_per_period_max_trips = 5, then each rider can take 5 trips a month on vouchers under this program.
  • value_per_trip_deductible: The amount a rider must pay before the voucher is applied.
    • Example: If set to $5, for a $20 trip, the first $5 is charged to the rider, and the remaining $15 is covered by the voucher.
  • value_per_trip_percentage: The percentage of the fare covered by the voucher issuer.
    • Example: If set to 10%, for a $20 trip, $2 is paid by the issuer, and the remaining $18 is paid by the rider.

• Vehicle Category Restrictions

  • Defines which vehicle categories are allowed, like PREMIUM, ECONOMY, SHARED_RIDES, etc.
  • If not specified, all vehicle categories are allowed.

• Value-Based Constraints To manage spending limits, at least one of the following must be specified:

  • value_per_trip_max_amount: The maximum dollar amount a voucher covers per trip.

    • Any overage is charged to the rider.
    • Example:
      • If value_per_trip_max_amount = 30 and value_per_trip_deductible = 2:
        • The first $2 is paid by the rider.
        • The next $30 is paid by the issuer.
        • Any amount exceeding $32 is charged to the rider.
      • If value_per_trip_max_amount = 5 and value_per_trip_percentage = 20%:
        • For a $10 trip, $2 is paid by the issuer.
        • For a $30 trip, $5 is paid by the issuer.

    Note: If value_per_trip_max_amount is set, it overrides value_per_trip_deductible.

  • value_per_period_max_trips: Defines the number of trips a rider can take within a specified period.

    • Example:
      • If value_per_period_max_trips = 5 and value_recurrence_period = DAILY, each rider can take 5 trips per day.
      • If value_per_period_max_trips = 5 and value_recurrence_period = MONTHLY, each rider can take 5 trips per month.

  • value_per_period_max_credit: The maximum dollar credit a voucher can redeem per period.

    • The currency is defined by currency_code.
    • Example:
      • If value_per_period_max_credit = 100 and value_recurrence_period = SINGLE, each voucher can redeem up to $100 total during its active period.

¶ Admin Reviews Existing Templates

Recommended Front-End Interface for Voucher Templates

To enhance the front-end experience, we strongly recommend providing administrators with a way to review existing voucher templates. There are two key workflows to consider:

1. Viewing Templates by Creator

   • An admin should be able to see all voucher templates created by themselves or specific users.
   • To implement this, filter the returned list by matching creator_uuid with the relevant user in your front-end UI.

2. Viewing All Organization Templates

   • An admin should be able to see all voucher templates created within the organization.

API Endpoints Required:

• Both workflows require using the Get Voucher Templates endpoint, which takes organization_id as a parameter and returns all associated voucher templates, along with basic template details.
• To retrieve detailed parameters of a specific template, use the Get Voucher Template by ID endpoint.

Suggested Implementation:

• Use the Get Voucher Template endpoint to display a high-level list of available voucher templates.
• Allow admins to select a template from this list.
• Upon selection, call the Get Voucher Template by ID endpoint to fetch and display detailed parameters for the chosen template.

This approach ensures a smooth user experience while minimizing API calls.

¶ Create Voucher Program from Template

The Create Voucher Program From Template endpoint (link) allows you to create a voucher program using a predefined template for a U4B organization.

Required Parameters:

• Template

  • Selecting the right template is crucial, as the voucher program inherits all aspects from it.
  • Refer to the creation and management of templates section for more details.
  • Once a template is created, you will receive a template ID (template_id), which must be included in the request payload.

• Voucher Program Details

  • name: Provide a meaningful name for the voucher program.
  • creator_email:
    • Use an email address of one of the employees of your U4B dashboard to indicate that the voucher program creation is triggered by the specific user.
    • If the given email address is not present in the dashboard as an employee/admin, the voucher creation fails.

• Voucher Program Validity

  • Define the period for which the voucher program will be active.
  • Use starts_at and ends_at fields to specify start and end times in milliseconds.
  • Once the ends_at timestamp is reached, the voucher program will expire.

• Code Scheme There are two types of code schemes:

  1. SINGLE_CODE_MULTI_REDEEM
     • Creates a single voucher code that can be shared among multiple customers defined under redemptions_per_code.
     • Requires the redemptions_per_code field.
     • Example: If redemptions_per_code = 2, the same voucher code can be redeemed by two different customers.
  2. MULTI_CODE_SINGLE_REDEEM
     • Creates a multi-code voucher program that distributes individual codes to customers.
     • Requires number_of_codes specifying how many unique codes to generate.
     • Example: If number_of_codes = 5, five different voucher codes will be created.

     Note: Each rider only gets one voucher code and can only redeem once.

• Additional Configurations: Reporting: Expense Memo

  • Use the expense_memo field to track voucher usage:
    • Insurance Companies – Add policy or claim numbers.
    • Recruiting – Attach a cost center identifier.
    • Airlines – Include flight delay codes or ticket numbers.

  Template Inheritance & Overrides

  • Inherited (not overridable): voucher value, number of trips.
  • Overridable: location restrictions defined at the program level.

Voucher Program Response

• SINGLE_CODE_MULTI_REDEEM

  • Response includes:
    • Voucher Program ID
    • Voucher Code (code_text)
    • Redemption Link (code_link)

• MULTI_CODE_SINGLE_REDEEM

  • Response includes only the Voucher Program ID.
  • Retrieve codes via the Get Voucher Codes API.

Fetching Voucher Codes

• Codes are auto-generated upon program creation.
• Use “Generate Voucher Code” endpoint only if more codes are needed after initial creation.
• To fetch codes for MULTI_CODE_SINGLE_REDEEM, call the Get Vouchers Codes API using the voucher program ID. Returns:
  • total_number_of_codes
  • List of:
    • code_id
    • code_text
    • redemption_link
    • max_num_redemptions
    • usage_count
    • usage_amount
    • currency_code

Building a UI Component for Creating a Voucher Program from a Template

• Design a form-based UI where the admin inputs necessary parameters, and the system automatically triggers the Create Voucher Program from Template API.

Code Scheme Selection

• Support both:
  • SINGLE_CODE_MULTI_REDEEM
  • MULTI_CODE_SINGLE_REDEEM
• Display fields dynamically based on selection.

Input Fields

• Refer to the documentation for a full list of parameters.