# Checkout

## Create a checkout session

> Creates a checkout session from a secure server using an API Key.\
> If you have a Customer token, see the Storefront API Create Checkout endpoint.

```json
{"openapi":"3.1.1","info":{"title":"PayNow Management API","version":"v1"},"tags":[{"name":"checkout"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"apiKey","description":"An API Key token generated in the Dashboard in the format 'APIKey TOKEN_HERE'.","name":"Authorization","in":"header"}},"schemas":{"CreateCheckoutSessionManagementDto":{"required":["customer_id","lines"],"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateCheckoutSessionLineManagementDto"},"description":"The line items to include in the checkout"},"subscription":{"type":["null","boolean"],"description":"Whether this checkout creates a subscription.\nDEPRECATED: Use 'subscription' field in 'lines' array objects instead.","deprecated":true},"coupon_id":{"$ref":"#/components/schemas/FlakeId"},"affiliate_code":{"type":["null","string"],"description":"Optional affiliate code to track referrals"},"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)"},"customer_id":{"$ref":"#/components/schemas/FlakeId"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Optional metadata to associate with the checkout session.\nDo not store any sensitive information here."}},"additionalProperties":false,"description":"Request to create a new checkout session from your back-end server using the management API.\n`customer_id` needs to be specified explicitly here instead of using a Customer token."},"CreateCheckoutSessionLineManagementDto":{"required":["quantity"],"type":"object","properties":{"subscription":{"type":["null","boolean"],"description":"Determines whether this line should create a subscription"},"trial":{"type":["null","boolean"],"description":"Indicates whether the product should be trialed"},"gift_to":{"$ref":"#/components/schemas/CustomerPlatformAccountDto"},"gift_to_customer_id":{"$ref":"#/components/schemas/FlakeId"},"quantity":{"type":"integer","description":"The quantity of this product to purchase","format":"int32"},"selected_gameserver_id":{"$ref":"#/components/schemas/FlakeId"},"custom_variables":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Key-value pair mapping custom variable identifiers to their selected values.\nRequired only when the product includes custom variables."},"product_id":{"$ref":"#/components/schemas/FlakeId"},"inline_product":{"$ref":"#/components/schemas/InlineProductCreateDto"},"payout_splits":{"type":["null","array"],"items":{"$ref":"#/components/schemas/CreateCheckoutSessionLineManagementPayoutSplitDto"},"description":"Optional payout splits for line items (requires approval)"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Optional metadata to associate with the checkout session line.\nDo not store any sensitive information here."}},"additionalProperties":false,"description":"Represents a line item in a checkout session request.\nOpposed to CreateCheckoutSessionLineDto, this is used while creating a checkout session using the Management API,\nand allows for creating inline products and payout splits (subject to special approval)"},"CustomerPlatformAccountDto":{"required":["id","platform"],"type":"object","properties":{"platform":{"$ref":"#/components/schemas/CustomerProfilePlatform"},"id":{"type":"string","description":"The account ID on the platform"}},"additionalProperties":false,"description":"Represents a customer platform association, used for gifting"},"CustomerProfilePlatform":{"enum":["invalid","steam","minecraft","paynow_name","paynow","minecraft_java_name","minecraft_bedrock_name","xbox_xuid","minecraft_uuid"],"type":"string"},"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"InlineProductCreateDto":{"type":"object","properties":{"slug":{"type":["null","string"],"description":"The unique URL-safe identifier (slug) for the product."},"name":{"type":["null","string"],"description":"The display name of the product."},"description":{"type":["null","string"],"description":"The detailed description of the product."},"label":{"type":["null","string"],"description":"The display label for the product."},"price":{"type":["null","integer"],"description":"The price of the product in the lowest denominator (e.g. cents).","format":"int64"},"single_game_server_only":{"type":["null","boolean"],"description":"Indicates whether the customer is prompted to select a game server before purchasing."},"allow_one_time_purchase":{"type":["null","boolean"],"description":"Indicates whether one-time purchases are allowed."},"allow_subscription":{"type":["null","boolean"],"description":"Indicates whether subscription purchases are allowed."},"subscription_interval_value":{"type":["null","integer"],"description":"The subscription interval value.","format":"int32"},"subscription_interval_scale":{"$ref":"#/components/schemas/ProductSubscriptionIntervalScale"},"trial":{"$ref":"#/components/schemas/UpsertProductTrialConfigurationDto"},"upselling":{"$ref":"#/components/schemas/UpsertProductUpsellConfigurationDto"},"remove_after_enabled":{"type":["null","boolean"],"description":"Indicates whether automatic removal is enabled."},"remove_after_time_value":{"type":["null","integer"],"description":"The time value for automatic removal.","format":"int32"},"remove_after_time_scale":{"$ref":"#/components/schemas/ProductRemoveAfterIntervalScale"},"store_stock_limit":{"$ref":"#/components/schemas/ProductStockLimitDto"},"customer_stock_limit":{"$ref":"#/components/schemas/ProductStockLimitDto"},"stock_limit_do_not_include_removed":{"type":["null","boolean"],"description":"Indicates whether removed items should be excluded from stock limits."},"tags":{"type":["null","array"],"items":{"$ref":"#/components/schemas/FlakeId"},"description":"The tag IDs associated with the product."},"gameservers":{"type":["null","array"],"items":{"$ref":"#/components/schemas/FlakeId"},"description":"The gameserver IDs associated with the product."},"commands":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ProductCommandDto"},"description":"The commands to be executed at different stages."},"deliverable_actions":{"$ref":"#/components/schemas/ProductDeliverableActionsDto"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata for the product."},"payout_splits":{"type":["null","array"],"items":{"$ref":"#/components/schemas/ProductPayoutSplitDto"},"description":"The payout splits for revenue distribution.\nRequires special approval."},"tax_code":{"$ref":"#/components/schemas/ProductTaxCode"},"allow_concurrent_active_items":{"type":["null","boolean"],"description":"Indicates whether concurrent active items are allowed."},"is_hidden":{"type":["null","boolean"],"description":"Indicates whether the product is hidden."},"is_gifting_disabled":{"type":["null","boolean"],"description":"Indicates whether gifting is disabled."},"enabled_at":{"type":["null","string"],"description":"The date and time when the product becomes enabled.\nSet to `null` to keep enabled.","format":"date-time"},"enabled_until":{"type":["null","string"],"description":"The date and time until which the product remains enabled.\nSet to `null` to keep enabled.","format":"date-time"},"required_product_ids":{"type":["null","array"],"items":{"$ref":"#/components/schemas/FlakeId"},"description":"The IDs of products required for purchasing this product."},"required_product_all":{"type":["null","boolean"],"description":"Indicates whether all required products are needed."},"custom_variable_ids":{"type":["null","array"],"items":{"$ref":"#/components/schemas/FlakeId"},"description":"The IDs of associated custom variables."},"is_gift_cards_disabled":{"type":["null","boolean"],"description":"Indicates if applying gift cards should be disabled on the product."},"is_coupons_disabled":{"type":["null","boolean"],"description":"Indicates if applying coupons should be disabled on the product."},"is_affiliate_links_disabled":{"type":["null","boolean"],"description":"Indicates if applying affiliate links should be disabled on the product."},"tier_group_id":{"$ref":"#/components/schemas/FlakeId"}},"additionalProperties":false,"description":"Optional inline product definition for dynamic products.\nRequires special approval, use `product_id` instead."},"ProductSubscriptionIntervalScale":{"enum":["invalid","day","week","month","year"],"type":"string"},"UpsertProductTrialConfigurationDto":{"type":"object","properties":{"enabled":{"type":["null","boolean"],"description":"Indicates if trials should be enabled for the product."},"period_value":{"type":["null","integer"],"description":"The trial period value.","format":"int32"},"period_scale":{"$ref":"#/components/schemas/ProductSubscriptionIntervalScale"},"revoke_immediately_when_canceled":{"type":["null","boolean"],"description":"Indicates if the trial should be revoked immediately when canceled or at the end of the trial."},"new_customers_only":{"type":["null","boolean"],"description":"Restricts trials to customers who have no orders within the lookback period.\nWhen enabled, customers with recent orders will be ineligible for trials."},"new_customer_order_lookback_value":{"type":["null","integer"],"description":"The lookback period value for determining if a customer is \"new\".\nOnly used when new_customers_only is enabled.","format":"int32"},"new_customer_order_lookback_scale":{"$ref":"#/components/schemas/ProductSubscriptionIntervalScale"},"allow_repeat_trials":{"type":["null","boolean"],"description":"Allows customers to trial again after a cooldown period following their previous trial.\nWhen disabled, customers can only trial once and never become eligible again."},"repeat_trial_cooldown_value":{"type":["null","integer"],"description":"The cooldown period value before a customer becomes eligible for another trial.\nOnly used when allow_repeat_trials is enabled.","format":"int32"},"repeat_trial_cooldown_scale":{"$ref":"#/components/schemas/ProductSubscriptionIntervalScale"}},"additionalProperties":false,"description":"Represents the configuration for trials of a product"},"UpsertProductUpsellConfigurationDto":{"type":"object","properties":{"enabled":{"type":["null","boolean"]},"recommendations":{"type":["null","array"],"items":{"$ref":"#/components/schemas/UpsertProductUpsellRecommendationDto"}}},"additionalProperties":false},"UpsertProductUpsellRecommendationDto":{"required":["discount_amount","discount_type","prefer_as_subscription","recommended_product_id","type"],"type":"object","properties":{"recommended_product_id":{"$ref":"#/components/schemas/FlakeId"},"type":{"$ref":"#/components/schemas/UpsellTypeDto"},"discount_type":{"$ref":"#/components/schemas/UpsellDiscountTypeDto"},"discount_amount":{"type":"integer","format":"int64"},"minimum_base_product_quantity":{"type":["null","integer"],"format":"int32"},"minimum_recommended_product_quantity":{"type":["null","integer"],"format":"int32"},"quantity_to_add":{"type":["null","integer"],"format":"int32"},"prefer_as_subscription":{"type":"boolean"}},"additionalProperties":false},"UpsellTypeDto":{"enum":["unknown","additional","alternative","increase_quantity"],"type":"string"},"UpsellDiscountTypeDto":{"enum":["unknown","none","fixed","percentage"],"type":"string"},"ProductRemoveAfterIntervalScale":{"enum":["invalid","day","week","month"],"type":"string"},"ProductStockLimitDto":{"required":["enabled","include_trials","time_scale"],"type":"object","properties":{"enabled":{"type":"boolean","description":"Indicates whether stock limit is enabled."},"quantity":{"type":["null","integer"],"description":"The quantity limit.","format":"int32"},"time_value":{"type":["null","integer"],"description":"The time value for stock limit period.","format":"int32"},"time_scale":{"$ref":"#/components/schemas/ProductStockTimeScale"},"include_trials":{"type":"boolean","description":"Indicates if trials should be included in the active stock limit calculation."}},"additionalProperties":false},"ProductStockTimeScale":{"enum":["invalid","day","week","month","year"],"type":"string"},"ProductCommandDto":{"required":["content","online_only","stage"],"type":"object","properties":{"stage":{"$ref":"#/components/schemas/ProductCommandStage"},"content":{"type":"string","description":"Content of the command."},"online_only":{"type":"boolean","description":"Value indicating whether the command should only execute when the player is online."},"override_execute_on_gameserver_ids":{"type":["null","array"],"items":{"$ref":"#/components/schemas/FlakeId"},"description":"Value indicating on which game servers should the command be executed.\nIf left empty or null, then the default behavior applies\n(executing on all game servers or on the selected game server is selection is enabled)"}},"additionalProperties":false},"ProductCommandStage":{"enum":["invalid","on_purchase","on_expire","on_refund","on_renew","on_chargeback","on_trial_start","on_trial_expire"],"type":"string","description":"Defines the stages at which product commands can be executed."},"ProductDeliverableActionsDto":{"required":["grant_giftcard"],"type":"object","properties":{"grant_giftcard":{"type":"boolean","description":"Value indicating whether to grant a giftcard with the product with the subtotal amount."}},"additionalProperties":false},"ProductPayoutSplitDto":{"required":["platform_fee","user_id"],"type":"object","properties":{"user_id":{"$ref":"#/components/schemas/FlakeId"},"percentage":{"type":["null","integer"],"description":"The percentage of the payment allocated to the user, in basis points (500 = 5%).\nThe last payout split must have this field set to `null` to receive the remaining portion.","format":"int64"},"platform_fee":{"type":"integer","description":"The platform fee percentage your platform receives, in basis points (500 = 5%).","format":"int64"}},"additionalProperties":false},"ProductTaxCode":{"enum":["unknown","digital_goods_subscription","digital_goods_permanent","saas","downloaded_software","digital_goods_subscription_gaming","digital_goods_permanent_gaming"],"type":"string","description":"Determines the category of the product for taxation purposes.\nContact support for help with setting the correct tax code."},"CreateCheckoutSessionLineManagementPayoutSplitDto":{"required":["payout_id"],"type":"object","properties":{"payout_id":{"type":"string","description":"The ID of the user's payout balance."},"percentage":{"type":["null","integer"],"description":"The percentage of the line amount this user receives (in basis points, e.g., 5000 = 50%)\nNOTE: The last payout split needs to have a null percentage set (so the remaining amount gets properly allocated)","format":"int64"},"platform_fee":{"type":["null","integer"],"description":"The platform fee percentage applied to this split (in basis points)\nOnly applicable to platforms.","format":"int64"}},"additionalProperties":false},"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/stores/{storeId}/checkouts":{"post":{"tags":["checkout"],"summary":"Create a checkout session","description":"Creates a checkout session from a secure server using an API Key.\nIf you have a Customer token, see the Storefront API Create Checkout endpoint.","operationId":"StoreCheckouts_CreateCheckoutSession","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionManagementDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionManagementDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionManagementDto"}}}},"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/management/management-api/checkout.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.