This guide covers the fundamental process in OptiPromo: creating a basic promotion and attaching promo codes to it. In many marketing scenarios, a simple, one-time reward mechanism is enough to incentivize users, and this flow is designed for exactly that.

This setup is particularly useful when:

• You want to launch a quick bonus or offer campaign with a shared, reusable code (e.g., WELCOME2025).
• You want a promotion where each eligible user receives their own personal, unique promo code.
• You need a reliable and reusable promotional link between your internal system and OptiPromo for seamless execution within Optimove's Campaign Builder.

Completing these steps is a foundational prerequisite before you can add more advanced features like metadata, budget limits, or conditional tiers.

Prerequisites

Before you begin, ensure you have:

• A valid Optimove API Key.
• Familiarity with sending POST requests to an API.

Creating a Promotion with a Global (Non-Unique) Promo Code

Global promo codes are shared codes—like WELCOME2025—that multiple users can redeem under the same promotion. They’re great for quick, broad campaigns, making setup and distribution simple and efficient.

To create and assign a basic global promocode, you will make two sequential API calls.

The Two-Step Process

1. Create the Promotion: First, send a POST request to the /promotions endpoint to define the core promotion entity. You will receive a promotionId in the response, which you will need for the next step.
2. Create the Promocode & Assign: Next, send a POST request to create the promocode. Crucially, you must include the promotionId you received from Step 1 in the body of this request. This action creates the promocode and assigns it to the promotion in a single step.

API Reference for Global Promo Codes

Creating a Promotion with Personalized (Unique) Promo Codes

Personalized promo codes are one-time, user-specific codes that ensure each eligible user receives a distinct code. This allows for precision targeting, reduces misuse, and enables accurate tracking per recipient.

When configuring unique promo codes, the following parameters and options apply:

• Unique codes file: A CSV file containing the list of unique codes to be used within the promotion.
• Default code: A fallback code that is used once the pool of unique codes is exhausted. It is generated automatically if not specified.
• Allocation method: Defines how the promo codes are assigned to customers across multiple campaigns under the same promotion:
  • Consistent: Each customer receives the same code throughout the campaign.
  • Varying: A new code is assigned on every trigger, even if the previous one was not used.

Additional code files can be uploaded at any time to replenish the unique code pool.

API Reference for Personalized Promo Codes

The process for setting up personalized codes involves creating the promotion and promocode first, then configuring them and uploading your codes.

Exporting Allocated Codes

The Export Allocated Codes feature allows you to download a CSV file containing records of which unique codes were allocated to which customers. This can be used for auditing, compliance verification, and analyzing code distribution.

Export Levels

You can export allocated codes at two levels:

• By File: Export allocations from a specific uploaded code file. Useful when you want to audit a particular batch of codes.
• By Promocode: Export all allocations across all files for the entire promocode. Useful for comprehensive reporting.

CSV Export Fields

The exported CSV contains the following columns:

Common Use Cases

• Audit & Compliance: Verify which customers received specific codes for regulatory or internal review.
• Troubleshooting: Investigate code allocation issues for specific customers.
• Analytics: Analyze allocation patterns and code usage rates across campaigns.
• Reconciliation: Match allocated codes against redemption records in your external systems.

Important Clarification: Two Separate Unique-Code Systems

Please note that Optimove supports two distinct ways to create unique promo codes—and they operate completely independently:

1. OptiPromo personalized (unique) codes: Configured and managed within the OptiPromo engine and tied to specific OptiPromo promotions. These are the modern and recommended method for unique codes.
2. Legacy unique codes via Optimove settings: This older system lives within Optimove’s settings menu and is not connected to OptiPromo at all.

What this means for you:

• Codes created inside one system are not recognized by the other. A user-specific code created in OptiPromo will not be tracked in the legacy system—and vice versa.
• Distributing or managing codes across both systems simultaneously can lead to confusion, tracking gaps, or failed redemptions.

To ensure clarity and consistency, it's best practice to choose one method for unique codes per campaign and stick with it. OptiPromo is the modern, more powerful choice.

Next Steps

• Add conditional rewards to your promotion: ➡️ Configuring Promotion Tiers