Overview The Cart API allows you to manage customer shopping carts, including retrieving cart contents, adding products, clearing the cart, and creating checkout sessions from cart contents.
All cart operations require a customer token for authentication.
Get Cart Retrieves the current customer’s shopping cart with all line items and pricing.
storefront . cart . getCart ( config ? )
Parameters Configuration object for the request The ISO three-letter lowercase currency code (e.g., usd, eur, gbp) to display prices in. If not provided, the store’s default currency will be used.
The IP address (IPv4 or IPv6) of the customer. Required if the request is not being made from the customer’s browser.
x-paynow-customer-countrycode
The customer’s country code in ISO 3166-1 alpha-2 format. Optional, but recommended if you have this available.
Returns Returns a CartDto object containing:
The store’s unique identifier
The customer’s unique identifier
Array of line items in the cart
The total price of all items in the cart in the smallest currency unit (e.g., cents)
The currency code (e.g., usd, eur, gbp)
Example import { createStorefrontClient } from '@paynow-gg/sdk' ; const storefront = createStorefrontClient ( 'store-id' , 'customer-token' ); // Get cart with default currency const { data : cart } = await storefront . cart . getCart (); console . log ( `Cart total: ${ cart . total } ${ cart . currency } ` ); console . log ( `Items in cart: ${ cart . lines . length } ` ); // Get cart with specific currency const { data : cartEur } = await storefront . cart . getCart ({ params: { currency: 'eur' } }); // Get cart with customer IP for accurate VAT calculation const { data : cartWithVat } = await storefront . cart . getCart ({ headers: { 'x-paynow-customer-ip' : '203.0.113.42' , 'x-paynow-customer-countrycode' : 'DE' } });
Add Line Adds a product to the cart or updates the quantity of an existing product.
storefront . cart . addLine ( config )
Parameters Configuration object for the request The ID of the product to add to the cart
The quantity to set or increment
Set to ‘1’ or ‘true’ to store as a subscription line item
Set to ‘1’ or ‘true’ to indicate if the line should be trialed
A game server ID, required if single_game_server_only is enabled for the product
Set to ‘1’ or ‘true’ to increment (add quantity instead of setting). When true, the specified quantity will be added to any existing quantity. Otherwise, the quantity will be set to the specified value.
Dictionary of product custom variables where each entry consists of a string key (identifier) and its corresponding selected value
The ID of the customer this line is a gift for
The platform type (e.g., ‘steam’, ‘minecraft’)
The account ID on the platform (e.g., Steam ID)
The IP address (IPv4 or IPv6) of the customer
x-paynow-customer-countrycode
The customer’s country code in ISO 3166-1 alpha-2 format
Returns Returns 204 No Content on success.
Example // Add a product to cart (set quantity to 1) await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 1 } }); // Increment quantity (add 2 more) await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 2 , increment: 'true' } }); // Add subscription product await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 1 , subscription: 'true' } }); // Add product with custom variables await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 1 , custom_variables: { 'player-name' : 'JohnDoe' , 'server-region' : 'us-east' } } }); // Add product as a gift await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 1 , 'gift_to.platform' : 'steam' , 'gift_to.id' : '76561198152492642' } }); // Add product with game server selection await storefront . cart . addLine ({ params: { product_id: '411486491630370816' , quantity: 1 , gameserver_id: '411486491630370820' } });
Clear Cart Clears all items from the customer’s shopping cart.
storefront . cart . clearCart ( config ? )
Parameters Configuration object for the request The IP address (IPv4 or IPv6) of the customer
x-paynow-customer-countrycode
The customer’s country code in ISO 3166-1 alpha-2 format
Returns Returns 204 No Content on success.
Example // Clear the cart await storefront . cart . clearCart (); console . log ( 'Cart cleared successfully' );
Create Cart Checkout Creates a checkout session from the contents of the cart. After creating the checkout session, redirect the customer to the returned URL.
storefront . cart . createCartCheckout ( config ? )
Parameters Configuration object for the request The ID of a coupon to apply to the checkout
Optional affiliate code to track referrals
Optional URL to redirect to after successful checkout
Optional URL to redirect to if checkout is canceled
Whether to automatically redirect the customer (return_url must be set)
The IP address (IPv4 or IPv6) of the customer
x-paynow-customer-countrycode
The customer’s country code in ISO 3166-1 alpha-2 format
Returns Returns a checkout session object:
The token for the checkout session
The URL to redirect the customer to complete checkout
Example // Create basic checkout from cart const { data : checkout } = await storefront . cart . createCartCheckout (); console . log ( 'Checkout URL:' , checkout . url ); // Redirect customer to checkout.url window . location . href = checkout . url ; // Create checkout with coupon const { data : checkoutWithCoupon } = await storefront . cart . createCartCheckout ({ data: { coupon_id: '411486491630370817' } }); // Create checkout with return URLs const { data : checkoutWithUrls } = await storefront . cart . createCartCheckout ({ data: { return_url: 'https://example.com/success' , cancel_url: 'https://example.com/cancel' , auto_redirect: true } }); // Create checkout with affiliate tracking const { data : checkoutWithAffiliate } = await storefront . cart . createCartCheckout ({ data: { affiliate_code: 'PARTNER123' , return_url: 'https://example.com/success' } });
Cart Line Items Each cart line item (CartLineDto) contains:
The unique key for this line item
The price of the product in the smallest currency unit (e.g., cents)
The quantity of this product in the cart
Indicates whether this line item is a subscription
Indicates whether this line will be trialed by the customer
The URL to the product image
The selected game server ID
Detailed pricing information including sales and VAT
Selected custom variables for this cart line
The customer ID this line is a gift for
Best Practices
Always provide customer IP for accurate pricing
When making server-side requests, always include the customer’s IP address to ensure accurate VAT calculation and regional pricing: await storefront . cart . getCart ({ headers: { 'x-paynow-customer-ip' : customerIp , 'x-paynow-customer-countrycode' : customerCountry } });
Use increment for quantity updates
When updating quantities, use the increment parameter to add to existing quantities rather than replacing them: // Add 2 more items await storefront . cart . addLine ({ params: { product_id: 'product-id' , quantity: 2 , increment: 'true' } });
Handle custom variables correctly
When products have custom variables, ensure you provide all required variables: await storefront . cart . addLine ({ params: { product_id: 'product-id' , custom_variables: { 'required-variable' : 'value' , 'optional-variable' : 'value' } } });
Redirect customers to checkout URL
After creating a checkout session, always redirect the customer to the returned URL: const { data } = await storefront . cart . createCartCheckout (); window . location . href = data . url ;