← Vimeo OTT Redeemer

Vimeo OTT Redeemer Documentation

Overview

Vimeo OTT Redeemer connects a WordPress website to the Vimeo OTT / VHX API and allows users to redeem access to configured Vimeo OTT products through WordPress.

The plugin is designed for promotional access, member benefits, complimentary subscriptions, event access, testing programs, and other workflows where access to a Vimeo OTT product should be provisioned from an existing WordPress site.

Administrators can create individual redemption offers, control when those offers are available, customize the user-facing messaging, review redemption history, inspect local entitlement records, and diagnose Vimeo OTT customer records directly from WordPress.

Current Version

1.1.15

Requirements

  • WordPress 6.4 or later
  • PHP 8.0 or later
  • An active Vimeo OTT account
  • Vimeo OTT API credentials with sufficient access to manage customers
  • HTTPS-enabled WordPress site

Installation

Install from ZIP

  1. Download the latest vimeo-ott-redeemer release ZIP.
  2. In WordPress, go to Plugins → Add New Plugin.
  3. Select Upload Plugin.
  4. Upload the Vimeo OTT Redeemer ZIP file.
  5. Click Install Now.
  6. Activate Vimeo OTT Redeemer.

The plugin installs into:

/wp-content/plugins/vimeo-ott-redeemer/

Do not rename the internal plugin folder.

Initial Setup

After activation, open the Vimeo OTT Redeemer administration area.

The initial configuration consists of four primary areas:

  1. General / Redemption Settings
  2. Default Messaging & Language
  3. Profile Defaults
  4. Debugging

Each section has its own save action so changes to one area do not overwrite settings in another.

Connecting Vimeo OTT

Vimeo OTT Redeemer requires a Vimeo OTT API key in order to create customers, look up existing customers, and provision product access.

Important

Vimeo OTT uses a separate API from the standard Vimeo developer API.

You need a Vimeo OTT API Key.

You do not need a standard Vimeo.com personal access token.

The Vimeo OTT API used by this plugin is:

https://api.vhx.tv

Generate a Vimeo OTT API Key

Follow these steps inside your Vimeo OTT administration account.

Step 1 — Sign In to Vimeo OTT

Sign in to the Vimeo OTT Admin Dashboard for the Vimeo OTT site you want to connect to WordPress.

Make sure you are working inside the correct Vimeo OTT site if your organization manages more than one.

Step 2 — Open Platforms

From the Vimeo OTT administration navigation, go to:

Manage → Platforms

Step 3 — Find the API Key Section

Scroll toward the bottom of the Platforms page.

Locate the area for API access or private API keys.

Step 4 — Create a New Key

Click Create Key.

Step 5 — Name the Key

Enter a descriptive name so you can identify what the API key is used for later.

Examples:

WordPress Vimeo OTT Redeemer

or:

BSM Strategy - Vimeo OTT Redeemer

or:

Website Redemption Integration

Using a descriptive name makes it easier to distinguish the integration from any other API connections your organization may create.

Step 6 — Create the API Key

Click Create Key.

Vimeo OTT will generate a private API key.

Step 7 — Copy the API Key

Click Copy Key and save the key in a secure location.

The private API key should be treated like a password.

You may not be able to retrieve the full private key again after leaving the page, so make sure you copy it before continuing.

Add the API Key to WordPress

After generating the Vimeo OTT API key:

  1. Return to your WordPress administration dashboard.
  2. Open Vimeo OTT Redeemer → Settings.
  3. Locate the Vimeo OTT API Key field.
  4. Paste your Vimeo OTT API key into the field.
  5. Click Save Settings.
  6. Run the plugin's Connection Test.

A successful connection confirms that WordPress can communicate with the Vimeo OTT API.

API Connection Test

The Connection Test verifies that:

  • WordPress can reach Vimeo OTT
  • The API key is accepted
  • The Vimeo OTT API is responding
  • The server can make outbound HTTPS requests

A successful connection does not necessarily confirm that every individual Vimeo OTT product or customer configuration is valid, but it confirms the base integration is functioning.

API Key Security

Treat the Vimeo OTT API key as a sensitive credential.

Do not:

  • Place it in a shortcode
  • Expose it in JavaScript
  • Include it in support tickets
  • Publish it in screenshots
  • Include it in public documentation
  • Commit it to a public Git repository
  • Email it unnecessarily

Vimeo OTT Redeemer performs API requests from the WordPress server so the API key does not need to be exposed to website visitors.

The plugin also attempts to redact sensitive credentials from diagnostic and debug output.

Passwords, authorization headers, WordPress nonces, cookies, and complete API keys should not appear in shared diagnostic information.

Vimeo OTT Site Ownership and API Keys

Vimeo OTT API keys are associated with the Vimeo OTT site and its administrative ownership.

If ownership or account administration changes, an existing API credential may need to be regenerated.

If Vimeo OTT Redeemer suddenly begins returning authentication failures after an account or ownership change, generating a new Vimeo OTT API key should be one of the first troubleshooting steps.

If You Lose the API Key

If you lose the private API key and can no longer retrieve it from your stored credentials, create a new API key in Vimeo OTT and update the key stored in WordPress.

After entering the new key, run the Connection Test again.

Do not continue using an API key that you believe may have been exposed or compromised.

Do Not Use a Standard Vimeo API Token

Vimeo provides multiple API systems. They are not interchangeable.

Vimeo OTT / VHX API

Used by Vimeo OTT Redeemer.

API endpoint:

https://api.vhx.tv

Credential type:

Vimeo OTT API Key

Standard Vimeo API

The standard Vimeo API is used for Vimeo.com developer applications, video uploads, metadata, playback information, and other standard Vimeo functionality.

This system typically uses:

  • Vimeo developer applications
  • Personal access tokens
  • OAuth credentials

A standard Vimeo personal access token should not be entered into the Vimeo OTT Redeemer API Key field.

Creating an Offer

Go to the Vimeo OTT Redeemer Offers area and select Add New Offer.

Each offer represents a specific redemption opportunity.

An offer can define:

  • Offer title
  • Offer slug
  • Vimeo OTT product
  • Access duration
  • Start date
  • End date
  • Approval behavior
  • User login requirements
  • Password handling
  • User-facing messaging
  • Profile messaging
  • Offer status

Offer Availability

Each offer has a start and end date.

An offer may appear as:

  • Scheduled — start time has not yet arrived
  • Active — currently available for redemption
  • Expired — end date has passed
  • Inactive — manually disabled

The availability rules are enforced on both the displayed form and the server-side redemption request.

Changing the HTML or manually submitting a request does not bypass the offer's configured availability.

Offer Duration

Offers can provide access for a defined period.

Examples include:

  • 2 days
  • 30 days
  • 3 months
  • 1 year

Current releases use Vimeo OTT's supported customer provisioning duration format where applicable.

Examples of the values sent to Vimeo OTT include:

2-days
5-weeks
3-months
1-years

Important

Vimeo OTT has advised that expires_in should not be used as a renewable entitlement-management mechanism.

The current plugin release retains its existing expiration behavior for compatibility.

A future release is intended to provide additional optional expiration-management methods, including WordPress-managed entitlement expiration and Vimeo product revocation.

Vimeo OTT Product

Each offer must be associated with a Vimeo OTT product.

The plugin normalizes products to the Vimeo API product URL format:

https://api.vhx.tv/products/PRODUCT_ID

Example:

https://api.vhx.tv/products/119144

The shortcode does not permit a visitor to substitute a different Vimeo product.

The product is determined by the server-side offer configuration.

Password Options

Offers can support different password workflows.

Vimeo Handles Password

No password is collected by the WordPress form where supported by the configured workflow.

User Chooses Password

The user enters the password that will be used when the Vimeo OTT customer is created.

The password is transmitted only as necessary to complete the provisioning request and is not intentionally stored by Vimeo OTT Redeemer.

Confirm WordPress Password

For logged-in WordPress users, an offer can require the user to confirm their existing WordPress password.

The plugin verifies it using WordPress authentication.

The password is not stored by Vimeo OTT Redeemer.

User Information

For logged-in users, the plugin can use information from the WordPress profile, including:

  • First name
  • Last name
  • Email address

Depending on the offer configuration, these values can be prefilled and locked to the WordPress account.

This prevents a logged-in user from redeeming an offer for an unrelated email address when the offer is intended to be tied to the WordPress account.

Existing Vimeo OTT Customers

Before attempting to create a new Vimeo OTT customer, the plugin searches for an existing customer using the submitted email address.

The lookup is designed to support addresses containing email subaddressing characters such as:

[email protected]

If Vimeo's direct email-filter response indicates that a matching customer exists but does not return the customer record, Vimeo OTT Redeemer performs an additional exact-match search.

This helps avoid creating unnecessary duplicate customers.

Redemption Form Shortcode

The standard shortcode is:

[vimeo_ott_offer offer="your-offer-slug"]

Example:

[vimeo_ott_offer offer="90-day-free"]

Add the shortcode to any WordPress page, post, or compatible page-builder module.

Supported Shortcode Presentation Options

The shortcode can accept selected presentation options.

Example:

[vimeo_ott_offer
    offer="90-day-free"
    button_text="Redeem Access"
    show_dates="yes"
    show_reference="no"
    css_class="special-redemption"
]

Supported presentation attributes include:

  • offer
  • button_text
  • show_dates
  • show_reference
  • css_class

Security Note

Shortcode attributes cannot override security-sensitive offer configuration.

For example, a shortcode cannot:

  • Change the Vimeo product
  • Bypass login requirements
  • Bypass offer availability
  • Weaken password requirements
  • Override redemption eligibility rules

Those settings remain controlled by the offer stored in WordPress.

Redemption Process

When a visitor submits a redemption form, the plugin performs several checks before calling Vimeo OTT.

  1. Validate the offer.
  2. Validate the offer availability.
  3. Validate the WordPress user if required.
  4. Validate form data.
  5. Check for a recent or existing redemption.
  6. Search Vimeo OTT for the customer.
  7. Determine the customer's current state.
  8. Create or process Vimeo OTT access as appropriate.
  9. Create or update the local entitlement.
  10. Write audit records.
  11. Return the appropriate user-facing result.

AJAX Redemption

JavaScript-enabled browsers use AJAX to process the redemption without reloading the entire page.

During processing:

  • The redemption button is disabled
  • The button displays a processing state
  • Validation errors appear inline
  • Server errors can be displayed above the form
  • Successful terminal states replace the redemption interface

A non-JavaScript server-side fallback is also retained.

Both methods use the same underlying PHP redemption engine.

Duplicate Redemption Protection

The plugin protects against accidental double-submission and duplicate active redemptions.

A newly submitted request is temporarily protected against an immediate duplicate request.

Requests that previously failed may be attempted again.

If a successful entitlement has expired, a new legitimate redemption can be permitted rather than permanently blocking the user because of the historical request.

Redemption Results

Depending on the transaction, a user may receive one of several states.

Success

The Vimeo OTT access was successfully provisioned.

Successful transactions retain an internal reference number for administration and auditing, although the reference does not need to appear to the user.

Existing

An applicable existing Vimeo OTT customer or access condition was detected.

Pending

The request requires additional processing or review.

Scheduled

The offer is not yet available.

Expired

The configured redemption window has ended.

Failure

The request could not be completed.

Where useful for customer support, operational failures can display a reference number.

Messaging and Language

The plugin includes configurable user-facing messaging.

Messaging uses the following priority:

Offer-specific message
        ↓
System default
        ↓
Built-in fallback

This allows most sites to establish global wording while customizing individual campaigns when necessary.

Available messaging includes content for:

  • Redemption instructions
  • Password label
  • Confirmation text
  • Success
  • Existing customer
  • Pending
  • Failure
  • Scheduled
  • Expired

The frontend intentionally does not require Vimeo branding in the user-facing language.

For example, the default password label is:

Choose a password

rather than:

Choose Vimeo password

Profile Link

Offers can optionally include a configurable profile message or link.

This is useful when a logged-in user's first name, last name, or email address needs to be changed before redeeming an offer.

The text and destination can be configured by the administrator.

Requests and Audit Records

Vimeo OTT Redeemer maintains internal records to support troubleshooting and reporting.

A request record can include:

  • Internal reference
  • User
  • Email association
  • Offer
  • Status
  • Reason
  • Vimeo customer ID
  • Product information
  • Timestamps

Audit records allow multiple events to be stored against the same redemption reference.

This provides a chronological record of important events during the transaction rather than limiting the reference to a single log row.

Entitlement Records

The plugin maintains a local entitlement record for successful access.

An entitlement can track information such as:

  • WordPress user
  • Email
  • Offer
  • Vimeo customer ID
  • Status
  • Start date
  • Expected expiration date
  • Latest redemption reference

The local expected expiration is useful for administration and diagnostics.

It should not be interpreted as proof that Vimeo OTT has already removed access at the exact recorded timestamp.

Customer Diagnostic Tools

Administrators can use the built-in Vimeo OTT Diagnostic Tools to inspect a customer without modifying the account.

Customer lookup can be performed using:

  • Email address
  • Vimeo customer ID

A product may also be supplied to inspect product-specific information.

Diagnostic results can include:

  • Customer ID
  • Name
  • Email
  • Platform
  • Creation date
  • Last update
  • Vimeo plan
  • Registration state
  • Subscription state
  • Recent Vimeo event data
  • Local request history
  • Local entitlement history
  • Product access information

These tools are read-only.

They do not intentionally alter the Vimeo customer's subscription or product access.

Product Access Diagnostics

A successful HTTP response from Vimeo does not, by itself, prove that a customer has access to a particular product.

The diagnostic tools inspect the returned customer/product information and attempt to determine whether the requested product actually appears to be attached or enabled.

The diagnostic interface therefore distinguishes between:

API request succeeded

and:

Product appears attached

This distinction is useful when troubleshooting an existing Vimeo customer.

Debug Mode

Debug Mode provides additional troubleshooting information.

When enabled, the plugin can record recent diagnostic checkpoints related to redemption processing.

Examples include:

  • Provisioning dispatch
  • API initialization
  • Processing start
  • Customer lookup attempt
  • Customer lookup result
  • API response status

Debug records are limited and temporary rather than being intended as permanent application logs.

Administrators can also use Clear Debug Data to remove the stored debug buffer.

Browser Console Diagnostics

When Debug Mode is enabled, authorized administrative sessions can receive additional browser-console diagnostics.

Sensitive information is intentionally redacted.

The console must not expose:

  • API keys
  • Passwords
  • Authorization headers
  • WordPress nonces
  • Cookies

Customer email addresses remain protected in shared debug output.

Administrator-only customer diagnostic views may display the complete email address when necessary to verify customer matching.

Database Repair

The plugin includes a database repair utility for situations where an earlier plugin version or interrupted upgrade left a required table, column, or index in an inconsistent state.

Use Check & Repair Plugin Database when instructed during troubleshooting.

The repair process is designed to preserve existing offers, requests, audit records, and entitlements.

It should not intentionally drop and recreate the plugin's data tables.

Plugin Updates

Beginning with version 1.1.14, Vimeo OTT Redeemer supports the BSM Strategy plugin update service.

The plugin checks:

https://bsmstrategy.com/wp-json/bsm-updates/plugin/vimeo-ott-redeemer

When a newer published release is available, WordPress can display the normal plugin update notification.

Administrators can then use the standard WordPress plugin update workflow.

The plugin identifies BSM Strategy as its authoritative update source rather than WordPress.org.

Update metadata is cached temporarily to reduce unnecessary requests to BSMStrategy.com.

A temporary failure of the BSM Strategy update service does not prevent Vimeo OTT redemption processing.

Troubleshooting

Vimeo Connection Test Fails

Check:

  • The API key is correct
  • You are using a Vimeo OTT API key, not a standard Vimeo token
  • Outbound HTTPS connections are permitted
  • api.vhx.tv is reachable from the WordPress server
  • The Vimeo OTT account is active
  • The API credential has sufficient access

If the API key was recently replaced, save the new key and run the Connection Test again.

Customer Exists but Plugin Cannot Find Them

Use Customer Diagnostic Tools.

Search by email first. If necessary, search by Vimeo customer ID.

Email aliases containing + are supported by the plugin's encoded customer lookup.

Offer Does Not Display

Verify:

  • The offer is active
  • The current date is between the offer start and end dates
  • The shortcode contains the correct offer slug
  • Required login conditions are satisfied

User Cannot Redeem Again

Review:

  • Most recent request status
  • Local entitlement
  • Expected expiration date
  • Vimeo customer record

An active entitlement may correctly prevent another redemption.

Failed requests should not permanently prevent a legitimate retry.

Redemption Fails With No Useful Information

Temporarily enable Debug Mode, reproduce the problem, and review:

  • Recent Debug Entries
  • Audit history
  • Customer Diagnostic Tools

Disable or clear debug information after troubleshooting when it is no longer needed.

Security Considerations

Vimeo OTT Redeemer uses standard WordPress security mechanisms, including:

  • WordPress capabilities
  • Nonces
  • Input sanitization
  • Output escaping
  • Prepared database operations
  • WordPress HTTP API
  • HTTPS Vimeo API requests
  • Password verification through WordPress
  • Server-side offer enforcement
  • Duplicate submission protection
  • API credential redaction
  • Sensitive debug-data filtering

No web application should be described as completely immune to security vulnerabilities.

Keep WordPress, PHP, Vimeo OTT Redeemer, your theme, and all other plugins up to date.

Uninstalling or Deactivating

Deactivating the plugin stops its WordPress functionality but does not automatically remove customers or product access already created in Vimeo OTT.

Administrators should review Vimeo OTT access before permanently removing a production installation.

Do not assume that deleting the WordPress plugin will revoke customer access in Vimeo OTT.

Support

Before requesting support, collect:

  • Vimeo OTT Redeemer version
  • WordPress version
  • PHP version
  • Offer name
  • Approximate redemption time
  • Internal reference number, if available
  • Relevant diagnostic output

Never send passwords or a complete Vimeo OTT API key in a support request.

Developer: BSM Strategy
Plugin: Vimeo OTT Redeemer
Current Version: 1.1.14

Need help? Visit Support & FAQ