# Checkout

## Create a checkout session

> Creates a checkout session using a Customer token.\
> 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":"checkout"}],"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":{"CreateCheckoutSessionRequestDto":{"required":["lines"],"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateCheckoutSessionLineDto"},"description":"The line items to include in the checkout."},"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"},"CreateCheckoutSessionLineDto":{"required":["product_id","quantity"],"type":"object","properties":{"product_id":{"$ref":"#/components/schemas/FlakeId"},"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."}},"additionalProperties":false,"description":"Represents a line item in a checkout session request"},"FlakeId":{"type":"string","additionalProperties":false,"format":"flake-id"},"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"},"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/checkouts":{"post":{"tags":["checkout"],"summary":"Create a checkout session","description":"Creates a checkout session using a Customer token.\nAfter creating the checkout session, redirect the customer to the `url` returned.","operationId":"StorefrontCheckout_CreateCheckoutSession","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/CreateCheckoutSessionRequestDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequestDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CreateCheckoutSessionRequestDto"}}}},"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/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.