--- title: "Create MerchantCustomer Session" method: POST path: "/merchant_customers/{merchant_customer_id}/session" tags: ["Merchant Customer Sessions"] --- # Create MerchantCustomer Session `POST /merchant_customers/{merchant_customer_id}/session` ## Request - Base URL: `https://api.liftforward.com` - URL: `https://api.liftforward.com/merchant_customers/{merchant_customer_id}/session` - Auth: API key in header `Api-Key` Creates a new MerchantCustomer Session for the provided `merchant_customer_id`. MerchantCustomer Sessions are used as a secure way for merchants to pass customer details to LiftForward before redirecting the customer to a LiftForward hosted credit application. This feature is not supported for all programs. ## Path parameters - `merchant_customer_id` string, required ## Request body - PostMerchantCustomersMerchantCustomerIdSession: Create MerchantCustomer Session - `session` object, required - `program_code` string, required: String provided by LiftForward to identify the Device as a Service Program. - `merchant_approval_url` string, required: URL on the merchant site the customer is redirected to after a customer's application is approved. - `merchant_decline_url` string, required: URL on the merchant site the customer is redirected to after a customer's application is declined. - `merchant_cancel_url` string, required: URL on the merchant site the customer is redirected to after a customer cancels their application. - `merchant_pending_url` string: URL on the merchant site the customer is redirected to when a customer's application is pending. - `language` string: Preferred language for the customer experience. - `payment` object: The first installment the merchant took at its own checkout. Required by programs that collect later installments through the payment processor. - `processor` string: The payment processor that handled the first installment. - `token` string: The merchant's reference for the first installment payment, such as the Shopify payment ID. - `first_installment_captured` boolean: Whether the merchant has captured the first installment. - `tracking_consents` object: Tracking consent preferences provided at session creation. - `strictly_necessary` object, required - `granted` boolean, required: Whether strictly necessary tracking is granted. - `required` boolean: Whether strictly necessary tracking is required. - `functional` object, required - `granted` boolean, required: Whether functional tracking is granted. - `required` boolean: Whether functional tracking is required. - `performance_analytics` object, required - `granted` boolean, required: Whether performance and analytics tracking is granted. - `required` boolean: Whether performance and analytics tracking is required. - `marketing_targeting` object, required - `granted` boolean, required: Whether marketing and targeting tracking is granted. - `required` boolean: Whether marketing and targeting tracking is required. - `simulate_outcome` 'approved' | 'checkout': One of [approved, checkout] to simulate a specific session outcome. For testing purposes only. - `customer` object: Pre-fill customer details for the session. - `personal_details` object: Personal details of the customer. - `first_name` string: First name of the customer. - `middle_name` string: Middle name of the customer. - `last_name` string: Last name of the customer. - `email` string: Email address of the customer. - `mobile_phone_number` string: Mobile phone number of the customer. Format: NNNNNNNNNN. - `home_phone_number` string: Home phone number of customer. Format: NNNNNNNNNN. Required if mobile phone number not provided. - `date_of_birth` string, date: Date of birth of customer. Format: YYYY-MM-DD - `tax_id` string: Tax id (SSN) of customer. Format: NNNNNNNNN - `annual_income` integer: Gross annual income of customer in local currency. Values between 0 and 9,999,999 allowed. - `billing_address` object: Billing address of the customer. - `address_line_1` string: First line of the billing address. - `address_line_2` string: Second line of the billing address. - `city` string: City of the billing address. - `state_code` string: State code of the billing address. For US addresses, provide 2-letter state code. - `postal_code` string: Postal code of the billing address. - `country_code` string: ISO 3166-1 alpha-2 country code of the billing address. - `order` object: Order details for the session. - `currency` 'USD' | 'CAD' | 'EUR' | 'GBP' | 'AUD' | 'CHF' | 'MYR': ISO 4217 3-character currency code. - `plan_code` string: String provided by LiftForward to identify the Device as a Service Plan. Required if the program has multiple plans. - `merchant_order_id` string: Unique identifier used by merchant for this order. Should be provided if possible. - `shipping_fee` number, float: A flat shipping fee for the entire order, separate from individual item shipping fees - `merchant` object: Merchant-specific order details. - `source_channel_id` 'IN_STORE' | 'ONLINE_IN_STORE' | 'ONLINE_SHIP_TO_HOME': Channel through which the order was placed. - `store_id` string: Identifier for the merchant store. - `employee_id` string: Identifier for the merchant employee. - `tender_type` string: Payment method used by the merchant for this order. - `merchant_metadata` object: Arbitrary metadata for the session - `shipping_address` object: Shipping address for the order. - `first_name` string: First name of customer. - `last_name` string: Last name of customer. - `address_line_1` string, required: Street address - `address_line_2` string: Apt, Floor, Suite etc.. - `city` string, required: Address city. - `state_code` string: 2 letter US state code abbreviation. - `postal_code` string, required: Address zip code. Format NNNNN, NNNNNNNNN or NNNNN-NNNN in the US. - `country_code` string, required: 2 letter ISO-3166-1 country code. - `merchant_items` object[]: Array of items in the order. - `sku` string, required: Merchant stock-keeping unit identifier for the item. - `description` string: Description of the item. - `image_url` string: URL for an image of the item. - `unit_sale_price` number, float: Sale price per unit of the item. - `unit_retail_price` number, float: Regular retail price per unit before any discounts. - `quantity` integer: Quantity of the item ordered. - `merchant_order_item_id` string: Merchant-provided identifier for this order item. - `parent_merchant_order_item_id` string: Merchant-provided identifier for another order item this item belongs to. Typically used to link insurance products to their devices. - `unit_total_price` number, float: Total price per unit including all fees and taxes. - `unit_balloon_payment` number, float: Balloon payment amount per unit due at end of term. - `shipping_fee` number, float: Shipping fee for this individual item. - `subscription_plan_id` string: Identifier for the subscription plan associated with this item. - `service_term_length` integer: Length of the service term in months. - `sales_tax_rates` object[]: Breakdown of sales tax rates for this line item. - `sales_tax_rate_code` 'VAT' | 'GST' | 'HST' | 'PST' | 'QST', required: Tax rate code identifying the type of tax levy. - `rate` number, float, required: Tax rate as a decimal (e.g. 0.08 for 8%). - `amount` number, float, required: Tax amount applied at this rate. ## Response `201` success - MerchantApiEntitiesSessionResponse: MerchantApi_Entities_SessionResponse model - `session` MerchantApiEntitiesSessionResponseEntity, required - `session_id` string: Unique identifer for this Session. - `status` string: Current status of the session (e.g., applying, checking_out, etc.) - `reservation_status` string: Current reservation status of the session (e.g., waiting, active, expired, etc.) - `credit_application_url` string: URL for the LiftForward hosted credit application. - `account_url` string: URL for the hosted customer account page. - `cart_url` string: URL for the hosted customer cart page. - `cart_id` string: ID of the cart associated with the session. - `merchant_customer_id` string, required: Unique identifier for customer. Provided by the Merchant on create. - `program_code` string, required: String provided by LiftForward to identify the Device as a Service Program. - `language` string: Preferred language for the customer experience. - `merchant_approval_url` string, required: URL on the merchant site the customer is redirected to after a customer's application is approved. - `merchant_decline_url` string, required: URL on the merchant site the customer is redirected to after a customer's application is declined. - `merchant_cancel_url` string: URL on the merchant site the customer is redirected to after a customer's cancels their application. - `merchant_pending_url` string: URL on the merchant site the customer is redirected to when a customer's application is pending. - `tracking_consents` MerchantApiEntitiesTrackingConsentEntity - `strictly_necessary` MerchantApiEntitiesTrackingConsentEntityConsentEntity - `granted` boolean, required: Whether consent has been granted. - `required` boolean: Whether consent is required. - `functional` MerchantApiEntitiesTrackingConsentEntityConsentEntity - `granted` boolean, required: Whether consent has been granted. - `required` boolean: Whether consent is required. - `performance_analytics` MerchantApiEntitiesTrackingConsentEntityConsentEntity - `granted` boolean, required: Whether consent has been granted. - `required` boolean: Whether consent is required. - `marketing_targeting` MerchantApiEntitiesTrackingConsentEntityConsentEntity - `granted` boolean, required: Whether consent has been granted. - `required` boolean: Whether consent is required. - `order` MerchantApiEntitiesSessionOrder, required - `merchant` MerchantApiEntitiesMerchantEntity - `source_channel_id` 'IN_STORE' | 'ONLINE_IN_STORE' | 'ONLINE_SHIP_TO_HOME': String identifying the sales channel the order originated from. ONLINE_SHIP_TO_HOME for typical ecommerce, ONLINE_IN_STORE for click and collect, IN_STORE for point of sale. - `store_id` string: String to identify merchant's store. - `employee_id` string: String to identify merchant's employee who assisted with sale. - `merchant_metadata` object: Arbitrary metadata for the session - `merchant_order_id` string: Unique identifier used by merchant for this order. Should be provided if possible. - `plan_code` string: String provided by LiftForward to identify the Device as a Service Plan. - `currency` string: ISO 4217 3 character currency code. - `shipping_fee` number, float: A flat shipping fee for the entire order, separate from individual item shipping fees - `shipping_address` MerchantApiEntitiesOrderAddress - `address_line_1` string, required: Street address - `address_line_2` string: Apt, Floor, Suite etc.. - `city` string, required: Address city. - `state_code` string, required: 2 letter US state code abbreviation. - `postal_code` string, required: Address zip code. Format NNNNN, NNNNNNNNN or NNNNN-NNNN in the US. - `country_code` string, required: 2 letter ISO-3166-1 country code. - `first_name` string, required: First name of customer. - `last_name` string, required: Last name of customer. - `merchant_items` MerchantApiEntitiesSessionOrderItemEntity[], required: Array of OrderItems describing the merchant items in this order. - `sku` string, required: Merchant defined SKU for this item. - `description` string: Short description or title of the product. - `merchant_order_item_id` string: Merchant provided identifier for this OrderItem. - `quantity` integer: Quantity of items purchased. Only available for some programs. Typically must be 1. - `unit_retail_price` number, float: Unit retail price for the item before any discount. Defaults to unit_sale_price. - `unit_sale_price` number, float: Unit price the item was sold for including any discount. - `unit_balloon_payment` number, float: Used with select device as a service programs. Amount of a balloon payment due at the end of upgrade period. - `unit_total_price` number, float: Total unit price for the item including any taxes and fees. - `shipping_fee` number, float: Shipping fee for this line item. - `sales_tax` number, float: Sales tax for this line item. - `sales_tax_rates` MerchantApiEntitiesSalesTaxRateEntity[]: Breakdown of sales tax rates for this line item. Only returned on plan_items. - `sales_tax_rate_code` 'VAT' | 'GST' | 'HST' | 'PST' | 'QST', required: The unique code for this sales tax rate - `rate` number, float, required: Tax rate in decimal - `amount` number, float, required: Tax amount in purchase currency - `misc_fees` number, float: Miscellaneous fees for this line item. - `apr` number, float: Annual Percentage Rate, expressed as a decimal, for this line item. - `installment_count` integer: Count of installments (aka payments) for this line item. - `unit_installment_payment` number, float: Amount of each payment customer will make per unit item. - `unit_total_interest` number, float: Total interest paid per unit item assuming all installments indicated by installment_count are made. - `parent_merchant_order_item_id` string: Merchant provided identifier for another OrderItem this order item belongs to. Typically used to link insurance products to their devices. - `image_url` string: Product image url. Should be using HTTPS always to avoid mixed content errors. - `description_list` string[]: Array of strings describing the product. Typically used the describe product features. ## Other responses - `400`: Invalid parameters - one or more required parameters are invalid or missing - `401`: Unauthorized - `404`: Not Found - a customer matching the provided parameters was not found - `405`: Not Allowed - `408`: Request Time Out - `409`: Conflict - a session could not be created due to the customer having an existing purchase in the provided program. - `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)