Create a promotion

Once you have setup an account and authenticated, you can then proceed to create a new promotion.

What is a promotion?

A promotion contains the key details for how codes are delivered, redeemed as well as other metadata that may impact how a promotion and its codes work.

Depending on the connected service in use, some fields may or may not be required.

Promotion types

Value Mapper supports several promotion types that determine how the reward is applied:

Discount promotions

• DISCOUNT_FIXED - A fixed monetary discount (e.g., $10 off an order)
• DISCOUNT_PERCENTAGE - A percentage-based discount (e.g., 15% off)

Credit promotions

• CREDIT_GLOBAL_CURRENCY - Store credit in a global currency (e.g., USD)
• CREDIT_LOCAL_CURRENCY - Store credit in a local currency (e.g., loyalty points)

Product and shipping promotions

• FREE_PRODUCT - Entitles the recipient to a free product
• FREE_SHIPPING - Provides free shipping on an order
• DISCOUNTED_SHIPPING_FIXED - A fixed discount on shipping costs
• DISCOUNTED_SHIPPING_PERCENTAGE - A percentage discount on shipping costs

Promotion subjects

The subject determines what the promotion applies to:

• ORDER - The promotion applies to the entire order
• PRODUCT - The promotion applies to specific products
• SHIPPING - The promotion applies to shipping costs

Creating a promotion

Creating a promotion can be done via the GraphQL API:

mutation CreatePromotion($promotion: CreatePromotionInput!, $exportOnSuccess: Boolean!) {
    createPromotion(promotion: $promotion, exportOnSuccess: $exportOnSuccess) {
        success
        promotion {
            uuid
            name
            promotionType
            active
        }
        errors {
            field
            message
        }
    }
}

Input parameters

Parameter	Type	Required	Description
name	String	Yes	The name of the promotion
promotionType	PromotionType	Yes	The type of promotion (see above)
active	Boolean	No	Whether the promotion is active upon creation
subject	PromotionSubject	No	What the promotion applies to (ORDER, PRODUCT, SHIPPING)
discountValue	Float	No	The discount value (for discount-type promotions)
creditValue	Float	No	The credit value (for credit-type promotions)
rules	[CreateRuleInput]	No	Rules that must be met for the promotion to apply
redemptionCodeFormat	String	No	Custom format for generated codes
redemptionCodeCount	Int	No	Number of codes to generate (max 999)
connectedServiceType	ConnectedServiceType	No	The connected service type (SHOPIFY, TREMENDOUS)
tremendous	CreateTremendousPromotionInput	No	Additional config for Tremendous promotions
channels	[PromotionChannel]	No	Distribution channels (e.g., SHOP_MINI)

Example: Creating a percentage discount promotion

mutation {
    createPromotion(promotion: {
        name: "Summer Sale 20% Off"
        promotionType: DISCOUNT_PERCENTAGE
        subject: ORDER
        discountValue: 20
        active: true
        connectedServiceType: SHOPIFY
    }, exportOnSuccess: false) {
        success
        promotion {
            uuid
            name
        }
        errors {
            message
        }
    }
}

Example: Creating a credit promotion with pre-generated codes

mutation {
    createPromotion(promotion: {
        name: "Loyalty Reward $25"
        promotionType: CREDIT_GLOBAL_CURRENCY
        creditValue: 25
        redemptionCodeCount: 100
        connectedServiceType: SHOPIFY
    }, exportOnSuccess: true) {
        success
        promotion {
            uuid
            redemptionCodeCount
        }
    }
}

tip

Set exportOnSuccess: true to automatically export the generated codes after creation. This triggers an email with a CSV file containing all the codes.

Example: Creating a Tremendous reward promotion

mutation {
    createPromotion(promotion: {
        name: "Customer Appreciation Gift Card"
        promotionType: CREDIT_GLOBAL_CURRENCY
        creditValue: 50
        connectedServiceType: TREMENDOUS
        tremendous: {
            campaignId: "YOUR_TREMENDOUS_CAMPAIGN_ID"
            deliveryMethod: EMAIL
        }
    }, exportOnSuccess: false) {
        success
        promotion {
            uuid
        }
    }
}

Updating a promotion

You can update an existing promotion using the updatePromotion mutation:

mutation UpdatePromotion($uuid: String!, $promotion: UpdatePromotionInput!) {
    updatePromotion(uuid: $uuid, promotion: $promotion) {
        success
        promotion {
            uuid
            name
            active
        }
        errors {
            message
        }
    }
}

Activating or deactivating a promotion

Toggle a promotion's active status:

mutation {
    togglePromotionActivation(uuid: "your-promotion-uuid", active: false) {
        uuid
        active
    }
}

Creating redemptions

Now that you have a promotion, next up we can create redemptions.