--- title: "Show Promotions" method: POST path: "/promotions" tags: ["Promotions"] --- # Show Promotions `POST /promotions` ## Request - Base URL: `https://api.liftforward.com` - URL: `https://api.liftforward.com/promotions` - Auth: API key in header `Api-Key` Returns a list of promotions with subscription plans available for the provided items. The request body must include at least 1 item with its SKU. Optionally, quantity, unit_sale_price and residual value category can be provided for each item. When optional values are not provided, defaults from the known product are used. If any SKUs are not recognized and no unit_sale_price is provided for that item, a 422 error is returned as the item's price can not be calculated. If a shipping_fee is provided, it will be included in the pricing calculations in the response. Each available subscription plan includes an items array with per-request-line financing figures. Rounded per-item payments may differ from the plan-level installment_payment by cents; shipping_fee is not allocated across items. ## Request body - PostPromotions: Show Promotions - `items` object[], required - `sku` string, required: The merchant SKU of the item. - `quantity` integer: The quantity of the item. Defaults to 1 if not provided. - `unit_sale_price` number, float: The sale price per unit of the item. If not provided, the product sale price known to LiftForward will be used. - `residual_value_category` string: The residual value category of the item, used to determine its value at the end of the subscription plans term. - `shipping_fee` number, float: A flat shipping fee for the entire order to include in pricing calculations. ## Response `201` Show Promotions - PromotionResponse: PromotionResponse model - `promotions` PromotionEntity[], required: List of available promotions for the provided items. - `promotion_code` string, required: String provided by LiftForward to identify the Promotion. - `title` string, required: Title of the promotion. - `type` string, required: Type of the promotion, e.g., "payment", "upgrade". - `category` string, required: Category of the promotion, e.g., "upgrade". - `description` string, required: Description of the promotion. - `available_subscription_plans` PromotionSubscriptionPlanEntity[], required: List of Subscription Plans available for the promotion. - `subscription_plan_id` string, required: The unique id for this plan. - `program_code` string, required: The program code for the subscription plan. - `plan_code` string, required: A short string that identifies the type of plan independent of the installment_count. - `plan_name` string, required: A displayable name for this plan. - `plan_subtitle` string, required: Promotional copy to display for this plan. - `plan_summary` string, required: Longer summary description on the plan and it's benefits - `financing_plan_type` 'financing' | 'upgrade', required: The type of financing plan for this product. - `installment_count` integer, required: Count of installments (aka payments) customer must make for this item. - `installment_count_to_trade_in` integer, required: Count of installments (aka payments) customer must make to trade in or upgrade this item. - `unit_installment_payment` number, float, required: Amount of each payment customer will make for 1 item under this subscription plan. - `installment_payment` number, float, required: Amount of each payment customer will make for all items under this subscription plan. (Deprecated in favor of total_installment_payment) - `total_installment_payment` number, float, required: Amount of each payment customer will make for all items under this subscription plan. Same value as installment_payment. - `total_over_term` number, float, required: The total amount the customer will pay over the term of the subscription if the customer choses to keep the item. - `installment_service_fee` number, float, required: Fee customer must pay along with the unit_installment_payment. Used only on some programs. - `residual_value` number, float, required: The amount this product is expected to be worth at then end of the term. (Deprecated in favor of total_residual_value) - `total_residual_value` number, float, required: The amount this product is expected to be worth at the end of the term. Same value as residual_value. - `total_payment_to_buy_out` number, float, required: The total amount the customer must pay before they buy out the item. - `total_payment_to_trade_in` number, float, required: The total amount the customer must pay before they can trade in or upgrade the item. - `total_interest` number, float, required: The total interest the customer will pay over the term of the subscription. - `apr` number, float, required: The annual percentage rate (APR) for the subscription. - `nominal_interest_rate` number, float, required: The nominal interest rate (debit rate) for the subscription. - `currency` string, required: ISO 4217 3 character currency code. - `items` MerchantApiEntitiesPlanItemFinancingEntity[], required: Per item financing breakdown for this SubscriptionPlan. Shipping and other non-item specific fees are not included in these calculations. - `sku` string, required: The merchant SKU of the item from the request. - `quantity` integer, required: The quantity of the item from the request. - `unit_sale_price` number, float, required: Sale price used for a single unit of this item (from the request, or the known product price when not provided). - `unit_amount_financed` number, float, required: Amount financed for a single unit of this item. - `unit_installment_payment` number, float, required: Monthly payment for a single unit of this item. - `total_installment_payment` number, float, required: Monthly payment for all units of this item line. - `total_residual_value` number, float, required: Expected residual value for this item line (all units) at end of term. ## Other responses - `400`: Invalid parameters - `401`: Unauthorized - `405`: Not Allowed - `408`: Request Time Out - `422`: Unprocessable - `500`: Internal Service Error - `503`: Service Unavailable --- [API](https://skmtc.dev/liftforward/apis/device-as-a-service-merchant-apis-lift-daas-service-producti.md) - [All operations](https://skmtc.dev/liftforward/apis/device-as-a-service-merchant-apis-lift-daas-service-producti/llms.txt) - [OpenAPI document](https://skmtc.dev/liftforward/apis/device-as-a-service-merchant-apis-lift-daas-service-producti/revisions/5a1383ffd271?raw)