Promo codes

A promo code lowers the monthly fee of some or all products in the customer's offer. Promo codes are created by Flowpay, for example for a joint campaign with you.

Note

You need this only if you use:

Fully Embedded (Native), or
Embedded (iFrame) with the customer integration type.

In all other integrations, the customer enters the code in myFlowpay, and you do not need to implement anything.

The steps below extend Offers & installment plans.

sequenceDiagram
    autonumber
    participant App as Your app
    participant Backend as Your backend
    participant FP as Flowpay Partner API

    App->>Backend: Promo code
    Backend->>FP: Preview the code (codeSlug)
    FP-->>Backend: Offer with promo rates
    Backend-->>App: Offer with promo rates
    Note over App,FP: Recalculate the installment plan with the promo offer
    App->>Backend: Customer's choice
    Backend->>FP: Submit application (promoCodeSlug)

1. Apply the code

When the customer enters a code, send it to Flowpay:

POST /partner-api/v1/customers/{id}/promo-codes/preview – Validate a promo code and preview the adjusted offer

This call checks the code and, if it is valid, reserves it for the customer's current offer:

The reserved code counts towards the code's usage limit.
The reserved code stays valid for the customer's application, even if the code expires or reaches its usage limit before they submit.
When the customer enters a different code, it replaces the reserved one.

Request

DataExample

Field	Type	Required	Description
`codeSlug`	string	Yes	Code the customer entered. 8–64 characters: letters, digits, `-` and `_`. Not case-sensitive.

{
    "codeSlug": "FLOWPAY10"
}

Response

DataExample

The customer's offer in the same shape as the offer, with the promo code applied:

Field	Type	Description
`id`	string	Offer identifier.
`country`	string	Country code.
`products[].ratePerc`	number	Rate with the promo code.
`products[].baseRatePerc`	number	Rate without the promo code.
`products[].effectiveRatePerc`	number	Rate with the promo code, same as `ratePerc`. Equal to `baseRatePerc` if the code does not apply to the product.
other `products[]` fields		Same as in the offer.

{
    "id": "ce649557-fc75-4574-961e-2592228f3f13",
    "country": "CZ",
    "products": [
        {
            "product": "M6",
            "minAmount": 100000,
            "maxAmount": 600000,
            "currency": "CZK",
            "ratePerc": 0.8,
            "balloon": false,
            "installmentCount": 6,
            "prolongationEnabled": false,
            "postponeEnabled": true,
            "maxPostponeLength": 2,
            "maxProlongationLength": 0,
            "interestRateMultiplier": 1,
            "postponeFeeMultiplier": 1,
            "prolongationFeeMultiplier": 1,
            "baseRatePerc": 1,
            "effectiveRatePerc": 0.8
        }
    ]
}

Errors

HTTP status	Error code	Cause
`400`	–	`codeSlug` is missing or has a wrong format.
`422`	`INVALID_CODE`	The code cannot be used for this customer, or the customer has no offer.

INVALID_CODE does not say why the code was rejected. Show the customer one general message, for example "This promo code is not valid".

2. Recalculate the plan

Calculate the installment plan from the preview response instead of the original offer. Its ratePerc already carries the promo rate, and baseRatePerc the rate without the code. Each plan then also contains:

Field	Description
`feeMonthlyBase`	Monthly fee without the promo code.
`amountTotalBase`	Total to repay without the promo code.
`promoSaving`	Amount the customer saves with the promo code. `0` if the code does not apply to the product.

Use them to show the original price next to the promo price. No second calculation is needed.

JavaScript SDKPartner API

Pass the preview response unchanged. Requires @flowpay-io/offer 3.2.0 or later.

const plan = calculateInstallmentPlan(preview, ProductType.M6, 150000, new Date(), postponeLength, prolongation);

plan.feeMonthly;      // 1200
plan.feeMonthlyBase;  // 1500
plan.amountTotal;     // 157200
plan.amountTotalBase; // 159000
plan.promoSaving;     // 1800

Send the preview products the same way as offer products, including baseRatePerc.

{
    "productType": "M6",
    "eligible": true,
    "feeMonthly": 1200,
    "amountTotal": 157200,
    "regularInstallmentAmount": 26200,
    "lastInstallmentAmount": 26200,
    "installmentCount": 6,
    "firstDueDate": "2026-12-05",
    "amountTotalBase": 159000,
    "feeMonthlyBase": 1500,
    "promoSaving": 1800
}

3. Submit the application with the code

Fully Embedded (Native)

Send the code in promoCodeSlug when you submit the application:

POST /partner-api/v2/financings – Submit financing application

Flowpay checks the code again and applies the promo rate. If the customer removed the code, leave out promoCodeSlug.

Embedded (iFrame), customer integration type

Start the application as usual. The code reserved in step 1 stays with the application, and the customer submits it in myFlowpay.