This guide covers the fundamental process in Promotions (formerly 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 Promotions 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 and PATCH 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 three sequential API calls.

The Three-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 steps.
2. Set the Promotion Name: Use the promotionId returned in Step 1 to set the promotion's name. This is a required follow-up step to identify your promotion:
   PATCH /v1/promotions/{promotionId}/metadata with body {"name": "your-promo-name"}.
3. 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

Shortcut: Create Promotions in One Call with One-Click

The three steps above — create the promotion, set its name, and attach a global promocode — can be collapsed into a single call with the One-Click endpoint. It also activates each promotion, so unlike the three-step flow you get live, ready-to-use promotions in one request.

Send a POST request to /v1/promotions/oneClickBatch with an items array of up to 150 entries, each carrying a name and a code. To create a single promotion, send one item. For every item it:

• creates a global (non-unique) promocode whose id is the literal code,
• creates the promotion, sets its name, and activates it,
• reports the new promotionId on the item's own row in the response.

A code can only ever be created once per tenant, and codes must be unique within the payload.

Reading the Response

Each item is processed independently and reported on its own row, so a batch can succeed in part: an item whose code is already taken fails on its own row while the other items are still created. The HTTP status tells you how the batch went as a whole:

• 200 — every promotion was created.
• 207 — some were created and some were not. Inspect the rows: a caller that only tests for a 2xx status will misread a partial failure as full success.
• 422 — no promotion was created; each row carries the reason.
• 400 — the request itself is invalid (empty items, more than 150 items, an item missing name or code, or the same code repeated within the payload). Nothing is created.

Every response body carries the same per-row report: how many were created, how many failed, and a results list with one row per item. Each row's status is one of:

• CREATED — the promotion is live; the row carries its promotionId.
• FAILED — nothing was created for this item; the row's error says why (for example Promocode "<code>" already exists).

Example — two items where one code is already taken (207):

{
  "created": 1,
  "failed": 1,
  "results": [
    {
      "code": "SUMMER25-A",
      "name": "Summer promo A",
      "status": "CREATED",
      "promotionId": "539f1d35-a49c-4cd9-90e3-5769a97f123c",
      "error": ""
    },
    {
      "code": "SUMMER25-B",
      "name": "Summer promo B",
      "status": "FAILED",
      "promotionId": "",
      "error": "Promocode \"SUMMER25-B\" already exists"
    }
  ]
}

API Reference

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, setting the name, and creating the 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. Promotions personalized (unique) codes: Configured and managed within the Promotions engine and tied to specific 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 Promotions at all.

What this means for you:

• Codes created inside one system are not recognized by the other. A user-specific code created in Promotions 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. Promotions is the modern, more powerful choice.

Next Steps

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