# Promo Codes Create and manage promotional codes (v2 and v3). V3 promo codes reference discount catalog items instead of embedding discount rules inline. ## Create Promo Code Objects > Create new promo code objects in Limio. Only promo codes v2 are supported via this endpoint. Promo codes can be configured with product-specific or whole-basket discounts and associated eligibility rules. ```json {"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Promo Codes","description":"Create and manage promotional codes (v2 and v3). V3 promo codes reference discount catalog items instead of embedding discount rules inline."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer `"}},"schemas":{"UpdatePromoCodeObjects":{"type":"object","properties":{"name":{"type":"string","description":"The object name. Not included values will not be updated and nested values will require the structure to update. Updates will only occur for the id provided. WARNING! Changing this field might break integrations"},"id":{"type":"string","description":"The object id. This is the record_type and name concatenated such as promo_code_v2-abc123. Not included values will not be updated and nested values will require the structure to update. Updates will only occur for the id provided. WARNING! Changing this field might break integrations"},"data":{"oneOf":[{"$ref":"#/components/schemas/PromoCodeWholeBasket"},{"$ref":"#/components/schemas/PromoCodeSelectedItems"}]}},"required":["name","id","data"]},"PromoCodeWholeBasket":{"type":"object","allOf":[{"properties":{"applicationLevel":{"type":"string","enum":["wholeBasket"],"description":"Specifies if the promo code applies to the whole basket."}}},{"$ref":"#/components/schemas/PromoCodeData"}],"required":["applicationLevel"]},"PromoCodeData":{"type":"object","properties":{"promoCode":{"type":"string","description":"The object name. Not included values will not be updated and nested values will require the structure to update. Updates will only occur for the id provided. WARNING! Changing this field might break integrations"},"status":{"type":"boolean","description":"Sets the status of the promo code. If true, the promo code is active. If false, the promo code is inactive."},"description":{"type":"string","description":"A brief description of the promo code."},"promoStartDate":{"type":"string","format":"date","description":"The start date for the promo code. If no start date is provided, the promo code will be active immediately providing the status is set to active."},"promoExpiryDate":{"type":"string","format":"date","description":"The expiry date for the promo code. If no expiry date is provided, the promo code will be active indefinitely."},"productDetails":{"$ref":"#/components/schemas/PromoCodeProductDetails"},"usage":{"type":"object","properties":{"availableQuantity":{"type":"number","description":"The number of times the promo code can be used. If undefined, the promo code can be used an unlimited number of times."}}},"discount":{"type":"object","oneOf":[{"title":"Discount Type Percentage","properties":{"discountType":{"type":"string","const":"DiscountPercentage"},"percentageDiscount":{"type":"number","description":"The percentage discount. Can be specified to 2 decimal places. This should only be set if the discountType is DiscountPercentage."},"durationLength":{"type":"integer","description":"The duration length of the discount."},"durationType":{"type":"string","enum":["Days","Weeks","Months","Years"],"description":"The duration type (e.g., months)."}}},{"title":"Discount Type Fixed Amount","properties":{"discountType":{"type":"string","const":"DiscountFixedAmount"},"amountDiscount":{"type":"number","description":"The amount discount. Can be specified to 2 decimal places. This should only be set if the discountType is DiscountFixedAmount."},"currency":{"type":"string","description":"The currency of the discount. Remember to activate the associated currency of the rate plan in the billing system."},"durationLength":{"type":"integer","description":"The duration length of the discount."},"durationType":{"type":"string","enum":["Days","Weeks","Months","Years"],"description":"The duration type (e.g., months)."}}}]}},"required":["promoCode","status","productDetails","discount"]},"PromoCodeProductDetails":{"type":"object","properties":{"product":{"type":"object","properties":{"path":{"type":"string","description":"Path to the Limio Product."}}},"ratePlan":{"type":"object","properties":{"path":{"type":"string","description":"The name of the rate plan. This rate plan should exist in the product specified. Its type should match the discount type specified in the payload"}}}},"required":["product","ratePlan"]},"PromoCodeSelectedItems":{"type":"object","allOf":[{"properties":{"applicationLevel":{"type":"string","enum":["selectedItems"],"description":"Specifies if the promo code applies to selected items."},"referencedOfferLabel":{"type":"string","description":"A label referencing the specific offer. This corresponds to the label__limio value set in the offer or add-on"}}},{"$ref":"#/components/schemas/PromoCodeData"}],"required":["applicationLevel","referencedOfferLabel"]},"UpdateObjectsResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the object"},"name":{"type":"string","description":"The name of the object"},"status":{"type":"string","description":"The status of the object"},"record_type":{"type":"string","description":"The record type of the object"},"service":{"type":"string","description":"The service of the object"},"data":{"type":"object","description":"The data of the object sent in the request"}}}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/objects/limio/promo_codes_v2":{"post":{"operationId":"createPromoCodeObjects","summary":"Create Promo Code Objects","tags":["Promo Codes"],"description":"Create new promo code objects in Limio. Only promo codes v2 are supported via this endpoint. Promo codes can be configured with product-specific or whole-basket discounts and associated eligibility rules.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePromoCodeObjects"}}}},"responses":{"200":{"description":"Promo codes created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectsResponse"}}}},"400":{"description":"Bad request — missing or invalid required fields."},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Not found."}}}}}} ``` ## Create Promo Code V3 > Create a new promo code (v3) in Limio. V3 promo codes reference a discount catalog item via \`attachedDiscount\` rather than embedding discount rules inline. ```json {"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Promo Codes","description":"Create and manage promotional codes (v2 and v3). V3 promo codes reference discount catalog items instead of embedding discount rules inline."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer `"}},"schemas":{"CreatePromoCodeV3Request":{"type":"object","required":["name","id","data"],"properties":{"name":{"type":"string","description":"The promo code name. Used as the code identifier."},"id":{"type":"string","description":"The object ID. This is the record_type and name concatenated, e.g. `promo_code_v3-SPRING2026`."},"data":{"$ref":"#/components/schemas/PromoCodeV3Data"}}},"PromoCodeV3Data":{"type":"object","required":["promoCode","status"],"properties":{"promoCode":{"type":"string","description":"The promo code string that customers enter at checkout."},"status":{"type":"boolean","description":"Whether the promo code is active. When `true` the code can be redeemed; when `false` it is disabled."},"description":{"type":"string","description":"A brief description of the promo code."},"promoStartDate":{"type":"string","format":"date","description":"The date the promo code becomes redeemable (YYYY-MM-DD). If omitted the code is active immediately (when status is true)."},"promoExpiryDate":{"type":"string","format":"date","description":"The date the promo code expires (YYYY-MM-DD). If omitted the code does not expire."},"usage":{"type":"object","properties":{"availableQuantity":{"type":"integer","description":"Maximum number of times this code can be redeemed. If omitted the code has unlimited uses."},"redeemedQuantity":{"type":"integer","description":"Number of times the code has been redeemed so far."}}},"attachedDiscount":{"type":"object","description":"Reference to the discount catalog item that defines the pricing rules applied when this code is redeemed.","required":["id","path","name"],"properties":{"id":{"type":"string","description":"The Elasticsearch document ID of the discount."},"path":{"type":"string","description":"The catalog path of the discount."},"name":{"type":"string","description":"Display name of the discount."}}}}},"UpdateObjectsResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the object"},"name":{"type":"string","description":"The name of the object"},"status":{"type":"string","description":"The status of the object"},"record_type":{"type":"string","description":"The record type of the object"},"service":{"type":"string","description":"The service of the object"},"data":{"type":"object","description":"The data of the object sent in the request"}}}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/objects/limio/promo_codes_v3":{"post":{"operationId":"createPromoCodeV3Objects","summary":"Create Promo Code V3","tags":["Promo Codes"],"description":"Create a new promo code (v3) in Limio. V3 promo codes reference a discount catalog item via `attachedDiscount` rather than embedding discount rules inline.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromoCodeV3Request"}}}},"responses":{"200":{"description":"Promo code created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectsResponse"}}}},"400":{"description":"Bad request — missing or invalid required fields."},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Not found."}}}}}} ```