# Process promo code decisions

The Promo Code decision would execute the discount rule defined behind the given promo code, which is configured from the Zephr console.
The decision request would require a list of relevant products with its pricing data, typically it would have come from a Dynamic Offer decision response.
The Promo Code decision would generate decision response like a regular Dynamic Offer, but with the discount output according to the Promo Code's discount rule.

Alternatively, if configured and the feature is enabled, this api can execute a dynamic offer rule that is linked to this promo code. Selected products are not required for executing promo codes using this method.
Parameters supplied to the dynamic offers decisions api can also be supplied to this api for this promo code flow (session, foreign_keys, etc).

Endpoint: POST /zephr/public/decisions/v1/promo-codes
Version: 2025-07-30
Security: CookieBlaizeSession, JwtQuery, JwtHeaderXBlaizeJwt, JwtHeaderXZephrJwt, JwtBearer, JwtCookie

## Request fields (application/json):

  - `promo_code` (string)
    The Promo Code, generated from the Zephr console.

  - `promo_code_definition` (string)
    The Definition ID of Promo Code, generated from the Zephr console. This is useful for previewing a draft promo code rule/offer as there won't be any downloadble/usable promo code generated.

  - `selected_products` (array,null)

  - `selected_products.id` (string)
    The product identifier
    Example: "product-a"

  - `selected_products.payment_plan` (object)

  - `selected_products.payment_plan.provider` (string)
    The payment provider that provides the pricing data associated with the product
    Example: "zuora-billing"

  - `selected_products.payment_plan.plan_id` (string)
    The payment plan identifier, typically this would be the product rate plan id

  - `selected_products.payment_plan.charges` (array)

  - `selected_products.payment_plan.charges.charge_definition_id` (string)
    The Product Charge Definition identifier

  - `selected_products.payment_plan.charges.currency` (string)
    The chosen currency against this product

  - `selected_products.payment_plan.charges.price` (number)
    The chosen price against this product

  - `session` (string,null)
    Zephr Session ID, required for trials. Only relevant for executing promo code with a linked dynamic offer.

  - `foreign_keys` (object,null)
    Foreign system and ID used to identify the user. Only relevant for executing promo code with a linked dynamic offer.

  - `ip` (string,null)
    Client IP address, defaults to request IP. Only relevant for executing promo code with a linked dynamic offer.

  - `user_agent` (string,null)
    Client user agent. Only relevant for executing promo code with a linked dynamic offer.

  - `jwt` (string,null)
    A Json Web Token, may include identity or product holding claims. Only relevant for executing promo code with a linked dynamic offer.

  - `path` (string,null)
    Request path, required for trials if used. Only relevant for executing promo code with a linked dynamic offer.

  - `content_id` (string)
    Content ID, used to perform requests to a 3rd party API for additional content information used in making a decision. Only relevant for executing promo code with a linked dynamic offer.

## Response 200 fields (application/json):

  - `products` (array)
    The processed output for mainly the Product rule. Price and Discount, if present, the output of those would be nested under each product element according to the rule specification.

  - `products.id` (string)

  - `products.label` (string)

  - `products.description` (string)

  - `products.features` (array)

  - `products.features.type` (string)

  - `products.sharingLimit` (number)

  - `products.metadata` (object)

  - `products.metadata.order` (number)

  - `products.metadata.recommended` (boolean)

  - `products.paymentPlans` (array)

  - `products.paymentPlans.planId` (string)

  - `products.paymentPlans.planData` (object)
    Any addition fields on the product rate plan level

  - `products.paymentPlans.charges` (array)

  - `products.paymentPlans.charges.chargeId` (string)

  - `products.paymentPlans.charges.prices` (array)
    The prices associated with this charge, filtered/sorted according to the price rule of the Dynamic Offer

  - `products.paymentPlans.charges.prices.currency` (string)

  - `products.paymentPlans.charges.prices.price` (number)

  - `products.paymentPlans.charges.chargeDefinitionData` (object)
    Any addition fields on the product charge definition level

  - `products.paymentPlans.charges.chargeData` (object)
    Any addition fields on the product rate plan charge level

  - `products.paymentPlans.charges.discounts` (array)
    The discounts associated with this charge, according to the discount rule output of this Dynamic Offer.

  - `products.paymentPlans.charges.discounts.items` (array)

  - `products.paymentPlans.charges.discounts.items.order` (number)
    The order with defines the priority of this discount

  - `products.paymentPlans.charges.discounts.items.type` (string)
    The type of the discount
    Enum: "FIXED", "PERCENTAGE", "OVERRIDE"

  - `products.paymentPlans.charges.discounts.items.value` (number)

  - `products.paymentPlans.charges.discounts.items.occurrence` (string)
    The frequency this discount occurs, if it's recurring then an end policy is expected to be present
    Enum: "ONE_OFF", "RECURRING"

  - `products.paymentPlans.charges.discounts.items.startPolicy` (object)

  - `products.paymentPlans.charges.discounts.items.startPolicy.offset` (object)

  - `products.paymentPlans.charges.discounts.items.startPolicy.offset.unit` (string)
    Enum: "CHARGE_BILLING_PERIOD", "DAY", "WEEK", "MONTH", "YEAR"

  - `products.paymentPlans.charges.discounts.items.endPolicy` (object)

  - `products.paymentPlans.charges.discounts.items.attributes` (object)
    Discount Attributes you've defined in the Discount output within the Discount rule.

  - `products.paymentPlans.charges.discounts.orderType` (string)
    Specify how multiple discounts, if there is any, should be applied together
    Enum: "SEQUENTIAL", "STACKED"

  - `products.attributes` (object)
    Product Attributes you've defined in the Product catalog and application overrides that you've specified in the Product rule.

  - `tagline` (string)
    The tagline rule output

  - `custom` (object)
    key value pair of any custom property rule output. The key would be the property id, the value would be its rule output

  - `outcomes` (array)
    The rule outcome for each property rule within the offer. If you wish to record user conversion data, you would need to send these outcome data back to Zephr upon when the conversion is happening.

  - `outcomes.ruleId` (string)
    An identifier for the property rule

  - `outcomes.outcomeId` (string)
    An identifier for the outcome of this property rule execution

  - `errors` (array)

  - `errors.property` (string)
    The offer property id in which the rule failed to execute

  - `errors.error` (string)
    The error message explaining why this decision failed to resolve. Present only if there was an error.


## Response 400 fields

## Response 404 fields