Skip to main content

Shopping Cart Creation Guide

Nexway provides a few integration options for creating a shopping cart, allowing businesses to seamlessly connect with Nexway’s payment processing, fraud detection, and tax management solutions based on their specific requirements.

Integration Options​

  • Buy-Link Integration: The quickest and easiest method
  • API Integration: A more customizable approach for a tailored user experience.

A shopping cart is created when the shopper clicks on the buy-link, automatically redirecting them to the checkout page. To generate a shopping cart using a Buy-Link, use the following format:

https://{storeHostName}/checkout/add?productId={productId}
Query ParameterDescriptionRequired
productId or productSpecifies the product ID from the Nexway catalog. Multiple product IDs can be added like checkout/add?productId=e187828b-e7cb-4cdb-bc42-66b51c1fff87&productId=e187828b-e7cb-4cdb-bc42-66b51c1fff88.Yes
layout and themeCustomizes the checkout layout and design.No
localeDefines the checkout language. If not specified, the default store locale applies.No
countrySets the end-user billing address country. Defaults to GeoIP location or the store's default country (depending on your store configuration) if not specified.No
newCart=trueEnsures the creation of a new cart instance. If not specified, the system first checks whether a cart already exists based on the given parameters, the end-user's IP, and additional conditions. If a cart is already present, the product from the Buy-Link will be added to it.No
scenarioActivates a specific checkout flow. Some scenarios may require additional attributes. Scenarios: acquisition (default), retention, upgrade, subscriptionimport.No
salesFlagUsed mostly for tracking purposes. Multiple flags could be provided: /add?salesFlag=OE,AZ. The flags will be added to order.No
quantitySets the product quantity. /add?productId=2f9bb37b-3558-49f0-bea6-69ab834013de&quantity=2. Will not work if you have multiple products in a buy-link. Use cart api for the case of multiple products customization.No
seats or nodes any price function parameterIf the product has custom price function parameter (say seats), you can specify it like this: products=a8eee7f3-0e3b-4119-adaf-3151c3f43fc8[seats=50].No
lockSelector=truePrevents tier or any other product variation parameter (seats, nodes, years, etc.) selection in the UI.No
discountApplies a specified coupon code.No
discountPlanApplies a discount plan tag to a subscription. As a value specify the name of the subscription discount plan tag. discountStep specifies the step from which the discount plan should start (by default step count starts at zero). ignorePurchaseDiscount (optional) prevents the discount from applying to the initial purchase price, ensuring it only takes effect from the first renewal. By default, the discount applies to the acquisition price as well. Sample: /add?discountTag=test&discountStep=0&ignorePurchaseDiscount=true.No
isRemotePrice=trueFetches a price from an external service. isRemotePrice=true activates the functionality offerId specifies the identifier in the external service Nexway uses to retrieve the price. If multiple products exist in the Buy-link, the remote price applies only to the first product ID in alphabetical order. Use cart API to fine-tune remote price for each product. Sample: /add?isRemotePrice=true&offerId=externalOfferId.No
upsell/crosssell=falseHides upsell or cross-sell recommendations in the UI. Defaults to true if configured in Nexway.No
optmons=exitOptinmonster Pop Up parameter. Allows the presentation of certain marketing ads in the shopping cart. [optmons=exit] leads to popup being raised.No
emailPre-fills the email field. Use with caution due to personal data exposure. Use cart API to set up obfuscated email address.No

Option 2: API Integration​

A shopping cart can also be created via API. The cartId is returned in the Location header of the API response. To redirect the shopper to checkout, retrieve the cart content using the cartId with the GET /carts/{cartId}. The response contains checkoutUrl, which should be used to redirect the shopper to the checkout page.

API Use Cases​

1. Public Cart Creation API​

Creates a cart using products from the Nexway catalog.
POST /carts/public
API Request Example

{
    "country": "FR",
    "locale": "en-US",
    "storeId": "36f48867-d6ca-42d3-bf55-5f54a6740803",
    "wantedProducts": [
        {"id": "2f9bb37b-3558-49f0-bea6-69ab834013de"}
    ]
}

2. Thank you page upgrade offer (cart)​

This endpoint allows upgrading a license immediately after purchase with a more functional product at a higher price. The shopper is charged only the difference between the current and upgraded product prices, without using a prorated formula. The request should include the ID of the line item from the purchase order.
POST /carts/public/upgrade
API Request Example

{
    "previousLineItemId": "36f48867-d6ca-42d3-bf55-5f54a6740803",
    "upgradeProductId": "2f9bb37b-3558-49f0-bea6-69ab834013de"
}

3. Cart with Remote Price​

Creates a shopping cart with a product price retrieved from an external service.
POST /carts/public
API Request Example

{
    "country": "FR",
    "locale": "en-US",
    "storeId": "36f48867-d6ca-42d3-bf55-5f54a6740803",
    "wantedProducts": [
        {
        "id": "2f9bb37b-3558-49f0-bea6-69ab834013de",
        "isRemotePrice": true,
	    "offerId": "1234567890" // Identifies the external price source
        }
    ]
}

4. Cart with Discount plan​

Creates a shopping cart with a discount plan applied to the subscription. The tag and discountStep attributes are required.
POST /carts/public
API Request Example

{
    "country": "FR",
    "locale": "en-US",
    "storeId": "36f48867-d6ca-42d3-bf55-5f54a6740803",
    "wantedProducts": [
        {
        "id": "2f9bb37b-3558-49f0-bea6-69ab834013de",
		"discountPlan": {
            "tag": "Level1", // The name of the subscription discount plan configured in Nexway
            "discountStep": 0, // Specifies the step (or subscription term) from which the discount should be applied
            "ignorePurchaseDiscount": false //Prevents the discount from applying to the initial purchase price, ensuring it only takes effect from the first renewal
            }
        }
    ]
}

5. Authorized Cart​

Creates a shopping cart with prefilled shopper's billing information.
POST /carts
API Request Example

--header 'Authorization: Bearer <API_key>'
{
    "country": "FR",
    "locale": "fr-FR",
    "storeId": "36f48867-d6ca-42d3-bf55-5f54a6740803",
    "wantedProducts": [
        {
        "id": "2f9bb37b-3558-49f0-bea6-69ab834013de"
        }
    ],
    "endUser": { 
        "firstName": "John",
        "lastName": "Smith",
        "email": "[email protected]",
        "maskedEmail": true, // Obfuscates the email
        "city": "Marseille",
        "country": "FR",
        "streetAddress": "Queen Street, 12",
        "zipCode": "2601"
        // Add more billing information if necessary.
    }
}

6. Custom Cart​

Creates a shopping cart with a custom catalog that is not managed by Nexway. This will create the catalog dynamically in Nexway, and the product IDs will be prefixed with the catalog ID. This method cannot be used to create a cart with subscription products. The method also has other business related limitations. Please discuss usage with your account manager first.
POST /carts/createCheckout
API Request Example

--header 'Authorization: Bearer <API_key>'
{
    "cart": {
        "locale": "fr-FR",
        "country": "FR",
        "storeId": "6fdd8d20-b31b-4e24-83c1-30681f112b5c",
        "products": {
            "product0": {
                 "quantity": 1
            }
        }
    },
    "fullCatalog": {
        "catalog": {
            "name": "Catalog#1", 
            "status": "ENABLED", 
            "type": "INTERNAL", 
            "singleUse": true 
            },
        "products": [
            {
                "id": "product0",
                "name": "Test product",
                "publisherRefId": "123456", // Product reference ID
                "price": {
                    "value": 10.00,
                    "currency": "EUR",
                    "vatIncluded": true 
                    }
            }
        ]
    }
}