The Promotions API allows you to apply and clear promotional codes on shopping carts. All promotion validation, discount calculation, and business rules are handled by the merchant’s e-commerce platform.Documentation Index
Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Promotions API provides two simple operations:- Add promotional codes to a cart
- Clear promotional codes from a cart
- Whether the code is valid
- What discounts apply
- How the cart totals are affected
Available Endpoints
Add Promo Codes
Apply promotional codes to the cart
Clear Promo Codes
Remove all promotional codes from the cart
How It Works
When you submit promotional codes through Firmly:- Firmly receives the promo code(s) from your request
- Forwards to merchant - The codes are sent to the merchant’s platform
- Merchant validates - The merchant system checks validity and applicability
- Returns updated cart - The cart response includes any applied discounts
Important Notes
Firmly does not control promotion logic. Each merchant platform determines:
- Which codes are valid
- Discount amounts and types
- Stacking rules for multiple codes
- Eligibility requirements
Error Handling
If a promotional code is invalid or cannot be applied, the merchant system will return an appropriate error. Common scenarios include:- Invalid or expired codes
- Codes that don’t meet requirements (e.g., minimum purchase amount)
- Codes that cannot be combined with other promotions
Next Steps
Add Promo Codes
Learn how to apply promotional codes
View Cart
Check cart totals after applying promotions