# Cart

## Get cart

> Retrieves the current customer's shopping cart.

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"cart"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"CartDto":{"required":["currency","customer_id","lines","store_id","total"],"type":"object","properties":{"store_id":{"$ref":"#/components/schemas/FlakeId"},"customer_id":{"$ref":"#/components/schemas/FlakeId"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLineDto"},"description":"The line items in the cart"},"total":{"type":"integer","description":"The total price of all items in the cart in the smallest currency unit (e.g., cents)","format":"int64"},"currency":{"type":"string","description":"The currency code (e.g., usd, eur, gbp)"}},"additionalProperties":false,"description":"Represents a customer's shopping cart"},"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"CartLineDto":{"required":["custom_variables","line_key","name","price","pricing","product_id","quantity","slug","subscription","trial"],"type":"object","properties":{"line_key":{"type":"string","description":"The unique key for this line item"},"product_id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"The name of the product"},"slug":{"type":"string","description":"The slug of the product"},"price":{"type":"integer","description":"The price of the product in the smallest currency unit (e.g., cents)","format":"int64"},"quantity":{"type":"integer","description":"The quantity of this product in the cart","format":"int32"},"subscription":{"type":"boolean","description":"Indicates whether this line item should be a subscription"},"trial":{"type":"boolean","description":"Indicates whether this line will be trialied by the customer."},"image_url":{"type":["null","string"],"description":"The URL to the product image"},"selected_gameserver_id":{"$ref":"#/components/schemas/FlakeId"},"selected_gameserver":{"$ref":"#/components/schemas/StorefrontGameServerDto"},"pricing":{"$ref":"#/components/schemas/StorefrontProductPricingDetailsDto"},"custom_variables":{"type":"array","items":{"$ref":"#/components/schemas/CartLineCustomVariableDto"},"description":"Selected custom variables for this cart line."},"gift_to_customer":{"$ref":"#/components/schemas/CustomerDto"},"gift_to_customer_id":{"$ref":"#/components/schemas/FlakeId"}},"additionalProperties":false,"description":"Represents a line item in a cart"},"StorefrontGameServerDto":{"required":["enabled","id","name","store_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"store_id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"The display name of the game server."},"enabled":{"type":"boolean","description":"Indicates whether the game server is currently enabled."}},"additionalProperties":false,"description":"Represents a simplified view of a game server for storefront display purposes."},"StorefrontProductPricingDetailsDto":{"required":["price_final","price_original","upsell_discount_amount"],"type":"object","properties":{"active_sale":{"$ref":"#/components/schemas/StorefrontSaleDto"},"sale_value":{"type":["null","integer"],"description":"The amount of the sale discount in the lowest denominator (e.g. cents).","format":"int64"},"upsell_offer_id":{"$ref":"#/components/schemas/FlakeId"},"upsell_discount_amount":{"type":"integer","format":"int64"},"vat_rate":{"$ref":"#/components/schemas/VatRateDto"},"regional_pricing":{"$ref":"#/components/schemas/StorefrontProductPricingDetailsRegionalPricingDto"},"price_original":{"type":"integer","description":"The original price of the product before any discounts, in the lowest denominator (e.g. cents).","format":"int64"},"price_final":{"type":"integer","description":"The final price of the product after all discounts, in the lowest denominator (e.g. cents).","format":"int64"}},"additionalProperties":false,"description":"The pricing details for the product in the storefront."},"StorefrontSaleDto":{"required":["begins_at","discount_amount","discount_type","id","minimum_order_value","name"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"The name of the sale."},"discount_type":{"$ref":"#/components/schemas/SaleDiscountType"},"discount_amount":{"type":"integer","description":"The amount of the discount, either as a percentage in permille or as an absolute value in cents.","format":"int64"},"minimum_order_value":{"type":"integer","description":"The minimum order value required to apply the discount, in the lowest denominator (e.g. cents).","format":"int64"},"begins_at":{"type":"string","description":"The date and time when the sale begins.","format":"date-time"},"ends_at":{"type":["null","string"],"description":"The date and time when the sale ends, if applicable.","format":"date-time"}},"additionalProperties":false},"SaleDiscountType":{"enum":["percent","amount"],"type":"string"},"VatRateDto":{"required":["country_code","country_name","currency","eservice_rate","eu_member_state","percentage","vat_abbreviation","vat_local_name"],"type":"object","properties":{"country_code":{"type":"string","description":"The ISO country code."},"country_name":{"type":"string","description":"The full name of the country."},"currency":{"type":"string","description":"The local currency used in the country."},"vat_abbreviation":{"type":"string","description":"The abbreviation of the VAT term in the local language."},"vat_local_name":{"type":"string","description":"The full name of the VAT term in the local language."},"eu_member_state":{"type":"boolean","description":"Indicates whether the country is a member of the European Union."},"eservice_rate":{"type":"number","description":"The VAT rate applicable for electronic services, as a percentage.","format":"double"},"percentage":{"type":"number","description":"The VAT rate (synonym for EServiceRate).","format":"double","readOnly":true}},"additionalProperties":false,"description":"The VAT rate estimation for the passed in customer country / IP.\nInclude the VAT percentage + abbreviation in your product view to inform your customers about the tax."},"StorefrontProductPricingDetailsRegionalPricingDto":{"required":["base_price","currency","region_id","tax_inclusive"],"type":"object","properties":{"region_id":{"type":"string","description":"The identifier for the region."},"currency":{"type":"string","description":"The currency code used in the region."},"tax_inclusive":{"type":"boolean","description":"Indicates whether the base price includes tax."},"base_price":{"type":"integer","description":"The base price in the regional currency, in the lowest denominator (e.g. cents).","format":"int64"}},"additionalProperties":false,"description":"Regional pricing information for this product.\nOnly present if there is a regional pricing configured."},"CartLineCustomVariableDto":{"required":["description","id","identifier","name","options","type","value"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"name":{"type":"string","description":"The display name of the custom variable"},"identifier":{"type":"string","description":"The unique identifier string for the custom variable"},"description":{"type":"string","description":"The description of the custom variable"},"type":{"$ref":"#/components/schemas/CustomVariableType"},"value":{"type":"string","description":"The selected value of the custom variable"},"options":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomVariableOptionDto"},"description":"The collection of available options for this custom variable. Only present for dropdown type"},"selected_option":{"$ref":"#/components/schemas/StorefrontCustomVariableOptionDto"}},"additionalProperties":false},"CustomVariableType":{"enum":["dropdown","text","number"],"type":"string","description":"Defines the type of input method for a custom variable."},"StorefrontCustomVariableOptionDto":{"required":["is_default","name","price","sort_order","value"],"type":"object","properties":{"name":{"type":"string","description":"Display name shown to customers for this option."},"value":{"type":"string","description":"Internal value used for product command variable replacement, without brackets."},"price":{"type":"integer","description":"Additional price in the lowest denominator (e.g. cents) when this option is selected.","format":"int64"},"is_default":{"type":"boolean","description":"Whether this option is selected by default when the custom variable is presented.\nOnly one option per custom variable should be marked as default."},"sort_order":{"type":"integer","description":"Sort order for displaying options to customers.\nLower numbers appear first.","format":"int32"}},"additionalProperties":false},"CustomerDto":{"required":["created_at","id","metadata","store_id"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"store_id":{"$ref":"#/components/schemas/FlakeId"},"profile":{"$ref":"#/components/schemas/GenericProfileDto"},"steam_id":{"$ref":"#/components/schemas/SteamId"},"steam":{"$ref":"#/components/schemas/SteamProfileDto"},"minecraft_uuid":{"type":["null","string"],"description":"The customer's Minecraft UUID, if they have linked their Minecraft account.\nNot set for offline Minecraft stores. If the platform type is Minecraft - Geyser,\nand the profile is a bedrock account, this will be a UUID generated from the Xbox XUID."},"minecraft":{"$ref":"#/components/schemas/MinecraftProfileDto"},"xbox_xuid":{"type":["null","string"],"description":"The customer's Xbox XUID, if available."},"minecraft_platform":{"$ref":"#/components/schemas/CustomerMinecraftPlatform"},"name":{"type":["null","string"],"description":"The display name for the customer."},"created_at":{"type":"string","description":"The date and time when the customer was created in the system.","format":"date-time"},"updated_at":{"type":["null","string"],"description":"The date and time when the customer was last updated, if applicable.","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional custom data associated with the customer."}},"additionalProperties":false,"description":"Represents a customer in the PayNow system with their associated profiles and metadata."},"GenericProfileDto":{"required":["id","name","platform"],"type":"object","properties":{"id":{"type":"string","description":"The platform-specific identifier for the profile."},"platform":{"type":"string","description":"The name of the platform this profile belongs to."},"name":{"type":"string","description":"The display name of the user on this platform."},"avatar_url":{"type":["null","string"],"description":"The URL to the user's avatar image on this platform."}},"additionalProperties":false,"description":"Represents a generic platform profile for a customer."},"SteamId":{"type":"string","additionalProperties":false,"description":"A 64-bit Steam account identifier. Accepts string or numeric format.","format":"steam-id"},"SteamProfileDto":{"required":["avatar_url","id","name"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/SteamId"},"name":{"type":"string","description":"The display name of the user on Steam."},"avatar_url":{"type":"string","description":"The URL to the user's Steam avatar image."}},"additionalProperties":false,"description":"Represents a Steam profile for a customer."},"MinecraftProfileDto":{"required":["avatar_url","id","name"],"type":"object","properties":{"id":{"type":"string","description":"The UUID of the Minecraft player.\nIf the platform is Minecraft Offline, this will be the name itself.\nIf the platform is Minecraft Geyser, and this is a Bedrock account, this ID will be an Xbox XUID."},"name":{"type":"string","description":"The username of the Minecraft player."},"avatar_url":{"type":"string","description":"The URL to the player's Minecraft skin rendered as an avatar."}},"additionalProperties":false,"description":"Represents a Minecraft profile for a customer."},"CustomerMinecraftPlatform":{"enum":["unknown","java","bedrock"],"type":"string"},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/cart":{"get":{"tags":["cart"],"summary":"Get cart","description":"Retrieves the current customer's shopping cart.","operationId":"StorefrontCart_GetCart","parameters":[{"name":"currency","in":"query","description":"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.","schema":{"type":"string"}},{"name":"x-paynow-customer-ip","in":"header","description":"The IP address (IPv4 or IPv6) of the customer. Required if the request is not being made from the customer's browser.","schema":{"type":"string","format":"ipv4"}},{"name":"x-paynow-customer-countrycode","in":"header","description":"The customer's country code in ISO 3166-1 alpha-2 format. Optional, but recommended if you have this available.","schema":{"pattern":"^[A-Z]{2}$","type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartDto"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```

## Clear cart

> Clears all items from the customer's shopping cart.

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"cart"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/cart":{"delete":{"tags":["cart"],"summary":"Clear cart","description":"Clears all items from the customer's shopping cart.","operationId":"StorefrontCart_ClearCart","parameters":[{"name":"x-paynow-customer-ip","in":"header","description":"The IP address (IPv4 or IPv6) of the customer. Required if the request is not being made from the customer's browser.","schema":{"type":"string","format":"ipv4"}},{"name":"x-paynow-customer-countrycode","in":"header","description":"The customer's country code in ISO 3166-1 alpha-2 format. Optional, but recommended if you have this available.","schema":{"pattern":"^[A-Z]{2}$","type":"string"}}],"responses":{"204":{"description":"No Content"},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```

## Add product to cart

> Adds a product to the cart or updates the quantity of an existing product.\
> When increment parameter is "true" or "1", the specified quantity will be added to any existing quantity.\
> Otherwise, the quantity will be set to the specified value, replacing any existing quantity.

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"cart"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"CustomerProfilePlatform":{"enum":["invalid","steam","minecraft","paynow_name","paynow","minecraft_java_name","minecraft_bedrock_name","xbox_xuid","minecraft_uuid"],"type":"string"},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/cart/lines":{"put":{"tags":["cart"],"summary":"Add product to cart","description":"Adds a product to the cart or updates the quantity of an existing product.\nWhen increment parameter is \"true\" or \"1\", the specified quantity will be added to any existing quantity.\nOtherwise, the quantity will be set to the specified value, replacing any existing quantity.","operationId":"StorefrontCart_AddLine","parameters":[{"name":"product_id","in":"query","description":"The ID of the product that should be added to the cart.","required":true,"schema":{"$ref":"#/components/schemas/FlakeId"}},{"name":"quantity","in":"query","description":"The quantity to set or increment.","schema":{"type":"integer","format":"int32"}},{"name":"subscription","in":"query","description":"Set to either '1' or 'true' to store as a subscription line item.","schema":{"type":"string"}},{"name":"trial","in":"query","description":"Set to either '1' or 'true' to indicate if the line should be trialed.","schema":{"type":"string"}},{"name":"gameserver_id","in":"query","description":"A game server ID, required if single_game_server_only is enabled for the product.","schema":{"$ref":"#/components/schemas/FlakeId"}},{"name":"increment","in":"query","description":"Set to either '1' or 'true' to increment (add quantity instead of setting).","schema":{"type":"string"}},{"name":"custom_variables","in":"query","description":"Dictionary of product custom variables where each entry consists of a string key (identifier) \nand its corresponding selected value. Use the following URL parameter format: \n?custom_variables[IDENTIFIER]=VALUE","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}}},{"name":"gift_to_customer_id","in":"query","description":"The ID of the customer in which this line is a gift for.","schema":{"$ref":"#/components/schemas/FlakeId"}},{"name":"gift_to.platform","in":"query","description":"The platform type","schema":{"$ref":"#/components/schemas/CustomerProfilePlatform"}},{"name":"gift_to.id","in":"query","description":"The account ID on the platform","schema":{"type":"string"}},{"name":"x-paynow-customer-ip","in":"header","description":"The IP address (IPv4 or IPv6) of the customer. Required if the request is not being made from the customer's browser.","schema":{"type":"string","format":"ipv4"}},{"name":"x-paynow-customer-countrycode","in":"header","description":"The customer's country code in ISO 3166-1 alpha-2 format. Optional, but recommended if you have this available.","schema":{"pattern":"^[A-Z]{2}$","type":"string"}}],"responses":{"204":{"description":"No Content"},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```

## Create a cart checkout session

> Creates a checkout session from the contents of the cart.\
> After creating the checkout session, redirect the customer to the \`url\` returned.

```json
{"openapi":"3.1.1","info":{"title":"PayNow Storefront (Headless) API","version":"v1"},"tags":[{"name":"cart"}],"security":[{"Customer":[]}],"components":{"securitySchemes":{"Customer":{"type":"apiKey","description":"A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"CreateCartCheckoutSessionDto":{"type":"object","properties":{"coupon_id":{"$ref":"#/components/schemas/FlakeId"},"promo_codes":{"type":["null","array"],"items":{"type":"string"},"description":"Optional array of promo codes (coupons, gift cards, affiliates) to apply.\nAn invalid promo code will cause an error."},"affiliate_code":{"type":["null","string"],"description":"Optional affiliate code to track referrals.\nAn invalid affiliate code will NOT cause an error."},"return_url":{"type":["null","string"],"description":"Optional URL to redirect to after successful checkout"},"cancel_url":{"type":["null","string"],"description":"Optional URL to redirect to if checkout is canceled"},"auto_redirect":{"type":["null","boolean"],"description":"Whether to automatically redirect the customer (return_url must be set)"}},"additionalProperties":false,"description":"Request to create a new checkout session from a cart"},"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"CreateCheckoutSessionResponseDto":{"required":["id","token","url"],"type":"object","properties":{"id":{"$ref":"#/components/schemas/FlakeId"},"token":{"type":"string","description":"The token for the checkout session"},"url":{"type":"string","description":"The URL to redirect the customer to complete checkout"}},"additionalProperties":false,"description":"Response after creating a checkout session"},"PayNowError":{"required":["code","message","status"],"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status code.","format":"int32"},"code":{"type":"string","description":"The PayNow parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"trace_id":{"type":["null","string"],"description":"A distributed trace ID used for debugging."},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ValidationError"},"description":"An array of multiple errors. Only used by some API services."}},"additionalProperties":false,"description":"Represents a PayNow error"},"ValidationError":{"required":["code","message","path","validation"],"type":"object","properties":{"code":{"type":"string","description":"The parseable error code."},"message":{"type":"string","description":"The human-readable error message."},"path":{"type":"string","description":"The path leading to the validation error."},"validation":{"type":"string","description":"Type of the validation that failed."}},"additionalProperties":false,"description":"A validation error."}}},"paths":{"/v1/store/cart/checkout":{"post":{"tags":["cart"],"summary":"Create a cart checkout session","description":"Creates a checkout session from the contents of the cart.\nAfter creating the checkout session, redirect the customer to the `url` returned.","operationId":"StorefrontCart_CreateCartCheckout","parameters":[{"name":"x-paynow-customer-ip","in":"header","description":"The IP address (IPv4 or IPv6) of the customer. Required if the request is not being made from the customer's browser.","schema":{"type":"string","format":"ipv4"}},{"name":"x-paynow-customer-countrycode","in":"header","description":"The customer's country code in ISO 3166-1 alpha-2 format. Optional, but recommended if you have this available.","schema":{"pattern":"^[A-Z]{2}$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCartCheckoutSessionDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateCartCheckoutSessionDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateCartCheckoutSessionDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionResponseDto"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayNowError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paynow.gg/storefront-headless/storefront-api/cart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.