{ "openapi": "3.1.1", "info": { "title": "PayNow Storefront (Headless) API", "description": "The Storefront API lets you integrate your store into custom front-ends or games. It manages product catalogue displaying, VAT rate calculation, carts, checkout sessions, and more. This API can be safely called directly from customer browsers or client-side applications without requiring an API key.", "termsOfService": "https://paynow.gg/terms-of-use", "contact": { "name": "PayNow Services, Inc.", "url": "https://paynow.gg", "email": "support@paynow.gg" }, "version": "v1" }, "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" } } } } }, "security": [ { "Customer": [ ] } ] }, "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" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/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" }, "example": "Steam" }, { "name": "gift_to.id", "in": "query", "description": "The account ID on the platform", "schema": { "type": "string", "example": "76561198152492642" }, "example": "76561198152492642" }, { "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" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/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" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/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" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/auth": { "post": { "tags": [ "customer" ], "summary": "Authenticate customer", "description": "Creates a customer and returns a customer token from a platform account.", "operationId": "StorefrontAuth_AuthenticateStorefrontCustomer", "parameters": [ { "name": "x-paynow-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } }, { "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/AuthenticateStorefrontCustomerRequestDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/AuthenticateStorefrontCustomerRequestDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/AuthenticateStorefrontCustomerRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateStorefrontCustomerResponseDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } } } }, "/v1/store/customer": { "get": { "tags": [ "customer" ], "summary": "Get current customer", "description": "Retrieves the current customer from the passed Customer token.", "operationId": "StorefrontCustomer_GetStorefrontCustomer", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/giftcards/lookup/{code}": { "get": { "tags": [ "customer" ], "summary": "Lookup a gift card by the code", "operationId": "StorefrontCustomer_GetStorefrontGiftCard", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontGiftCardDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/delivery/items": { "get": { "tags": [ "delivery" ], "summary": "Get the customers delivery items", "description": "Retrieves the current customers delivery items.", "operationId": "StorefrontCustomerDelivery_GetStorefrontCustomerDeliveryItems", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of items to return in a single request.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "Returns items after the specified ID.\nUsed for forward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "before", "in": "query", "description": "Returns items before the specified ID.\nUsed for backward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "asc", "in": "query", "description": "Determines the sort order of returned items.\nWhen true, items are returned in ascending order.\nWhen false, items are returned in descending order.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontDeliveryItemDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/command-delivery": { "get": { "tags": [ "delivery" ], "summary": "Get the customers delivery items", "description": "**Deprecated:** \n\nRetrieves the current customers delivery items.", "operationId": "LegacyStorefrontCustomerCommandDelivery_GetStorefrontCustomerDeliveryItems", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of items to return in a single request.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "Returns items after the specified ID.\nUsed for forward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "before", "in": "query", "description": "Returns items before the specified ID.\nUsed for backward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "asc", "in": "query", "description": "Determines the sort order of returned items.\nWhen true, items are returned in ascending order.\nWhen false, items are returned in descending order.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontDeliveryItemDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "deprecated": true, "security": [ { "Customer": [ ] } ], "x-gitbook-ignore": true } }, "/v1/stores/{storeId}/product_versions/discord_actions": { "get": { "tags": [ "discord" ], "operationId": "ProductsDiscord_DoProductsHaveDiscordActions", "parameters": [ { "name": "storeId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "product_version_id", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FlakeId" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store/navlinks": { "get": { "tags": [ "navlinks" ], "summary": "Get navlinks", "description": "Retrieves the store's navlink structure used for navigation.", "operationId": "StorefrontNavLinks_GetStorefrontNavLinks", "parameters": [ { "name": "x-paynow-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontNavLinkDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store/customer/orders": { "get": { "tags": [ "orders" ], "summary": "Get orders", "description": "Retrieves all orders for the specified customer token.\n{% hint style=\"warning\" %}\nThis endpoint is only available for stores that use Steam based authentication.\n{% endhint %}", "operationId": "StorefrontOrders_GetOrders", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of items to return in a single request.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "Returns items after the specified ID.\nUsed for forward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "before", "in": "query", "description": "Returns items before the specified ID.\nUsed for backward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "asc", "in": "query", "description": "Determines the sort order of returned items.\nWhen true, items are returned in ascending order.\nWhen false, items are returned in descending order.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontOrderDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/orders/{orderId}": { "get": { "tags": [ "orders" ], "summary": "Get order by ID", "description": "Retrieves an order by its ID for the specified customer token.\n{% hint style=\"warning\" %}\nThis endpoint is only available for stores that use Steam based authentication.\n{% endhint %}", "operationId": "StorefrontOrders_GetOrderById", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontOrderDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/products": { "get": { "tags": [ "products" ], "summary": "Get products", "description": "Retrieves the available products. To make sure all VAT rates are properly displayed, pass in the IP headers as instructed.", "operationId": "StorefrontProducts_GetStorefrontProducts", "parameters": [ { "name": "tag", "in": "query", "description": "Tag slugs to filter by. Each tag slug is a separate query parameter.", "schema": { "type": "array", "items": { "type": "string" } } }, { "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-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } }, { "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": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontProductDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store/products/{idOrSlug}": { "get": { "tags": [ "products" ], "summary": "Get product by ID or slug", "description": "Retrieves a product by an ID or a slug. To make sure all VAT rates are properly displayed, pass in the IP headers as instructed.", "operationId": "StorefrontProducts_GetStorefrontProduct", "parameters": [ { "name": "idOrSlug", "in": "path", "required": true, "schema": { "type": "string" } }, { "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-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } }, { "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/StorefrontProductDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store": { "get": { "tags": [ "store" ], "summary": "Get current store", "description": "Retrieves a store by the passed in x-paynow-store-id or Customer token.", "operationId": "StorefrontStore_GetStorefrontStore", "parameters": [ { "name": "x-paynow-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } }, { "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/StorefrontStoreDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store/customer/subscriptions": { "get": { "tags": [ "subscriptions" ], "summary": "Get subscriptions", "description": "Retrieves all subscriptions for the specified customer token.\n{% hint style=\"warning\" %}\nThis endpoint is only available for stores that use Steam based authentication.\n{% endhint %}", "operationId": "StorefrontSubscriptions_GetSubscriptions", "parameters": [ { "name": "customer_id", "in": "query", "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "subscription_id", "in": "query", "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "billing_email", "in": "query", "schema": { "type": "string" } }, { "name": "payment_method_id", "in": "query", "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "checkout_id", "in": "query", "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "trial_id", "in": "query", "schema": { "$ref": "#/components/schemas/FlakeId" } }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionStatusDto" } } }, { "name": "limit", "in": "query", "description": "The maximum number of items to return in a single request.", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "Returns items after the specified ID.\nUsed for forward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "before", "in": "query", "description": "Returns items before the specified ID.\nUsed for backward pagination through results.", "schema": { "$ref": "#/components/schemas/FlakeId" }, "example": "null" }, { "name": "asc", "in": "query", "description": "Determines the sort order of returned items.\nWhen true, items are returned in ascending order.\nWhen false, items are returned in descending order.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontSubscriptionDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/customer/subscriptions/{subscriptionId}": { "get": { "tags": [ "subscriptions" ], "summary": "Get subscription by ID", "description": "Retrieves a subscription for the specified store by the supplied customer token.\n{% hint style=\"warning\" %}\nThis endpoint is only available for stores that use Steam based authentication.\n{% endhint %}", "operationId": "StorefrontSubscriptions_GetSubscriptionById", "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorefrontSubscriptionDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] }, "delete": { "tags": [ "subscriptions" ], "summary": "Cancel subscription by ID", "description": "Cancels a subscription for the specified store by the supplied customer token.\n{% hint style=\"warning\" %}\nThis endpoint is only available for stores that use Steam based authentication.\n{% endhint %}", "operationId": "StorefrontSubscriptions_CancelSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/tags": { "get": { "tags": [ "tags" ], "summary": "Get tags", "description": "Retrieves the store's tags.", "operationId": "StorefrontTags_GetStorefrontTags", "parameters": [ { "name": "x-paynow-store-id", "in": "header", "description": "PayNow Store Identifier (Store ID) available in Store Settings", "required": true, "schema": { "type": "string", "format": "flake-id" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontTagDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ], "APIKey": [ ] } ] } }, "/v1/store/tier-groups": { "get": { "tags": [ "tier-groups" ], "summary": "Get customer tier groups", "description": "Retrieves tier group state for a logged in customer. Returns an empty array if not logged in.", "operationId": "StorefrontTierGroups_GetCustomerTierGroups", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerTierGroupDto" } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { }, { "Customer": [ ] } ] } }, "/v1/store/tier-groups/{id}/change": { "post": { "tags": [ "tier-groups" ], "summary": "Update subscription tier group", "description": "Upgrades or downgrades an existing subscription tier group. The customer must have an active subscription within this tier group.", "operationId": "StorefrontTierGroups_UpdateSubscriptionTierGroup", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionResponseDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } }, "/v1/store/tier-groups/{id}/change/preview": { "post": { "tags": [ "tier-groups" ], "summary": "Preview update subscription tier group", "description": "Previews an upgrade or a downgrade an existing subscription tier group. The customer must have an active subscription within this tier group.", "operationId": "StorefrontTierGroups_UpdateSubscriptionTierGroupPreview", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/FlakeId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionTierRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionResponseDto" } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayNowError" } } } } }, "security": [ { "Customer": [ ] } ] } } }, "components": { "schemas": { "ActorDto": { "required": [ "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PayNowActorType" }, "id": { "$ref": "#/components/schemas/FlakeId" } }, "additionalProperties": false }, "AuthenticateStorefrontCustomerRequestDto": { "required": [ "id", "platform" ], "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/CustomerProfilePlatform" }, "id": { "type": "string", "description": "The account ID on the platform", "example": "76561198152492642" } }, "additionalProperties": false }, "AuthenticateStorefrontCustomerResponseDto": { "required": [ "customer_token" ], "type": "object", "properties": { "customer_token": { "type": "string", "description": "The token for the Customer" } }, "additionalProperties": false }, "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" }, "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 }, "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/StorefrontProductPricingDto" }, "custom_variables": { "type": "array", "items": { "$ref": "#/components/schemas/CartLineCustomVariableDto" }, "description": "Selected custom variables for this cart line." }, "gift_to_customer": { "$ref": "#/components/schemas/StorefrontCustomerDto" }, "gift_to_customer_id": { "$ref": "#/components/schemas/FlakeId" } }, "additionalProperties": false, "description": "Represents a line item in a cart" }, "CheckoutPaymentInfoDto": { "required": [ "declined", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status string from the payment provider." }, "declined": { "type": "boolean", "description": "Indicates whether the payment was declined." }, "decline_message": { "type": [ "null", "string" ], "description": "The customer readable decline reason, if the payment was declined." }, "checkout_url": { "type": [ "null", "string" ], "description": "Checkout URL to redirect to for on-session payments." } }, "additionalProperties": false, "description": "Payment outcome information returned after a subscription change triggers an immediate charge." }, "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" }, "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" }, "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" }, "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" }, "CustomVariableLineItemDto": { "required": [ "description", "id", "identifier", "name", "price", "value" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "identifier": { "type": "string", "description": "The identifier used to reference this custom variable (e.g., \"color\", \"size\")." }, "name": { "type": "string", "description": "The display name of the custom variable shown to users." }, "description": { "type": "string", "description": "A detailed description of what this custom variable represents." }, "price": { "type": "integer", "description": "The price associated with this custom variable in the smallest currency unit (e.g., cents).", "format": "int64" }, "value": { "type": "string", "description": "The selected value for this custom variable." } }, "additionalProperties": false }, "CustomVariableType": { "enum": [ "dropdown", "text", "number" ], "type": "string", "description": "Defines the type of input method for a custom variable.", "x-enumDescriptions": { "dropdown": "Dropdown selection with predefined options.\n Customers choose from a list of available options.\n Allows for additional pricing based on the selected entry.", "text": "Free-form text input.\n Customers can enter any text value (subject to validation).", "number": "Numeric input.\n Customers can enter numeric values (subject to validation)." } }, "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/CustomerGenericProfileDto" }, "steam_id": { "$ref": "#/components/schemas/SteamId" }, "steam": { "$ref": "#/components/schemas/CustomerSteamProfileDto" }, "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.", "example": "f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2" }, "minecraft": { "$ref": "#/components/schemas/CustomerMinecraftProfileDto" }, "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.", "example": "m0uka" }, "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." }, "CustomerGenericProfileDto": { "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.", "example": "steam" }, "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." }, "CustomerMinecraftPlatform": { "enum": [ "unknown", "java", "bedrock" ], "type": "string" }, "CustomerMinecraftProfileDto": { "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.", "example": "f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2" }, "name": { "type": "string", "description": "The username of the Minecraft player.", "example": "notch" }, "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." }, "CustomerPlatformAccountDto": { "required": [ "id", "platform" ], "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/CustomerProfilePlatform" }, "id": { "type": "string", "description": "The account ID on the platform", "example": "76561198152492642" } }, "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", "x-enumDescriptions": { "steam": "Steam profile platform - the ID param must be a Steam ID 64.", "minecraft": "Minecraft profile platform - the ID param must be a Minecraft nick.\n If your store platform is Geyser, this automatically sets the Minecraft platform based on the prefix configured in store settings.", "paynow_name": "PayNow name profile platform - the ID param must be a PayNow username.", "paynow": "PayNow name profile platform - the ID param must be a PayNow username.", "minecraft_java_name": "Minecraft Java Profile Platform - the ID param must be a Java minecraft nick.", "minecraft_bedrock_name": "Minecraft Bedrock Profile Platform - the ID param must be a Bedrock minecraft nick.", "xbox_xuid": "Minecraft Xbox XUID Profile Platform - the ID param must be an xbox xuid", "minecraft_uuid": "Minecraft profile platform - the ID param must be a Minecraft UUID." } }, "CustomerSteamProfileDto": { "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." }, "CustomerTierGroupDto": { "required": [ "active_product_id", "currency", "next_billing_amount", "next_billing_presentment_amount", "next_renewal_at", "presentment_currency", "tier_group_id" ], "type": "object", "properties": { "tier_group_id": { "$ref": "#/components/schemas/FlakeId" }, "active_product_id": { "$ref": "#/components/schemas/FlakeId" }, "pending_change_product_id": { "$ref": "#/components/schemas/FlakeId" }, "next_renewal_at": { "type": "string", "description": "The date and time of the next subscription renewal for this tier group.", "format": "date-time" }, "next_billing_amount": { "type": "integer", "description": "The next billing amount in the smallest currency unit (e.g., cents) in the settlement currency.", "format": "int64" }, "next_billing_presentment_amount": { "type": "integer", "description": "The next billing amount in the smallest currency unit (e.g., cents) in the customer-facing presentment currency.", "format": "int64" }, "currency": { "type": "string", "description": "The settlement currency code (e.g., \"usd\")." }, "presentment_currency": { "type": "string", "description": "The customer-facing presentment currency code (e.g., \"eur\")." } }, "additionalProperties": false }, "DeliveryItemProductDto": { "required": [ "id", "name", "slug", "version_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "name": { "type": "string", "description": "The name of the product", "example": "Premium Membership" }, "slug": { "type": "string", "description": "The URL-friendly slug of the product", "example": "premium-membership" }, "version_id": { "type": "string", "description": "The version identifier of the product", "example": "v2.1.0" } }, "additionalProperties": false, "description": "Represents the product information for a delivery item" }, "DeliveryItemStateDto": { "enum": [ "usable", "active", "used", "revoked", "renewed" ], "type": "string" }, "FlakeId": { "type": "string", "additionalProperties": false, "format": "flake-id", "example": "411486491630370816" }, "OrderStatus": { "enum": [ "created", "completed", "canceled", "refunded", "chargeback" ], "type": "string" }, "OrderType": { "enum": [ "one_time", "subscription_initial", "subscription_renewal", "subscription_proration", "mixed" ], "type": "string", "description": "Defines the type of items contained in an order", "x-enumDescriptions": { "one_time": "Order contains only one-time purchase items", "subscription_initial": "Order is the initial charge for a subscription", "subscription_renewal": "Order is a recurring renewal charge for a subscription", "subscription_proration": "Order is a proration charge for a subscription", "mixed": "Order contains both one-time purchase and subscription items" } }, "PayNowActorType": { "enum": [ "anonymous", "user", "api_key", "customer", "game_server", "internal", "admin", "platform", "global_customer" ], "type": "string" }, "PayNowError": { "required": [ "code", "message", "status" ], "type": "object", "properties": { "status": { "type": "integer", "description": "The HTTP status code.", "format": "int32", "example": 400 }, "code": { "type": "string", "description": "The PayNow parseable error code.", "example": "bad-request" }, "message": { "type": "string", "description": "The human-readable error message.", "example": "Bad Request Example" }, "trace_id": { "type": [ "null", "string" ], "description": "A distributed trace ID used for debugging.", "example": "234a5bcd543ef3fa53ce929d0e0e4736" }, "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" }, "PlatformCapability": { "enum": [ "invalid", "connected_users" ], "type": "string" }, "PlatformStoreTypeAssociationDetailsDto": { "required": [ "disable_billing_plans", "display_disclaimers", "full_external_management", "platform_id", "store_platform" ], "type": "object", "properties": { "platform_id": { "$ref": "#/components/schemas/FlakeId" }, "associated_platform": { "$ref": "#/components/schemas/PublicPlatformDto" }, "store_platform": { "type": "string", "description": "The store platform identifier string (e.g. \"rust\", \"minecraft\")." }, "paynow_platform_fee_percentage_override": { "type": [ "null", "integer" ], "description": "Overrides the default PayNow platform fee percentage for this association.\nExpressed in basis points (e.g. 250 = 2.50%).", "format": "int64" }, "connected_platform_fee_percentage": { "type": [ "null", "integer" ], "description": "The fee percentage charged by the connected platform.\nExpressed in basis points (e.g. 250 = 2.50%).", "format": "int64" }, "connected_platform_wallet_id": { "$ref": "#/components/schemas/FlakeId" }, "disable_billing_plans": { "type": "boolean", "description": "When true, billing plans are disabled for this platform/store type combination." }, "display_disclaimers": { "type": "boolean", "description": "When true, legal or compliance disclaimers should be displayed to the end user." }, "full_external_management": { "type": "boolean", "description": "Whether the management hides some PayNow UI" } }, "additionalProperties": false }, "PlatformType": { "enum": [ "invalid", "marketplace", "store_platform", "other" ], "type": "string" }, "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 }, "ProductRemoveAfterIntervalScale": { "enum": [ "invalid", "day", "week", "month" ], "type": "string" }, "ProductSubscriptionIntervalScale": { "enum": [ "invalid", "day", "week", "month", "year" ], "type": "string" }, "ProductTagDto": { "required": [ "id", "name", "slug" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "slug": { "type": "string", "description": "The unique slug for the tag.", "example": "packages" }, "name": { "type": "string", "description": "The display name of the tag.", "example": "Packages" } }, "additionalProperties": false }, "ProrationBehaviorDto": { "enum": [ "invalid", "immediate", "next_billing_period", "none" ], "type": "string", "description": "Describes how proration is handled when a subscription change is applied.", "x-enumDescriptions": { "immediate": "Subscription will be updated instantly, and a proration charge will be applied.", "next_billing_period": "Subscription will be updated at the end of the billing period, no proration will be applied.", "none": "No proration is applied, subscription is updated instantly." } }, "PublicPlatformDto": { "required": [ "accent_color", "business_name", "capabilities", "country_code", "created_at", "description", "id", "logo_url", "name", "slug", "type", "website_url" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "slug": { "type": "string" }, "type": { "$ref": "#/components/schemas/PlatformType" }, "country_code": { "type": "string" }, "business_name": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "website_url": { "type": "string" }, "logo_url": { "type": "string" }, "accent_color": { "type": "string" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformCapability" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "format": "date-time" }, "disabled_at": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false }, "SaleDiscountTypeDto": { "enum": [ "percent", "amount" ], "type": "string" }, "SalesTaxEstimateDto": { "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.", "example": "CZ" }, "country_name": { "type": "string", "description": "The full name of the country.", "example": "Czech Republic" }, "currency": { "type": "string", "description": "The local currency used in the country.", "example": "CZK" }, "vat_abbreviation": { "type": "string", "description": "The abbreviation of the tax term in the local language.", "readOnly": true, "example": "DPH" }, "vat_local_name": { "type": "string", "description": "The full name of the tax term in the local language.", "readOnly": true, "example": "Daň z přidané hodnoty" }, "tax_number_abbreviation": { "type": [ "null", "string" ], "description": "The abbreviation of the local tax identification number." }, "tax_number_local_name": { "type": [ "null", "string" ], "description": "The name of the local tax identification number." }, "eu_member_state": { "type": "boolean", "description": "Indicates whether the country is a member of the European Union.", "example": true }, "eservice_rate": { "type": "number", "description": "The tax rate applicable for electronic services, as a percentage.", "format": "double", "example": 21 }, "percentage": { "type": "number", "description": "The VAT rate (synonym for EServiceRate).", "format": "double", "readOnly": true, "example": 21 } }, "additionalProperties": false, "description": "The Sales Tax estimation for the passed in customer country / IP.\nInclude the tax percentage + abbreviation in your product view to inform your customers about the tax." }, "SalesTaxJurisdictionDto": { "required": [ "name", "taxes" ], "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tax jurisdiction.", "example": "EU OSS" }, "taxes": { "type": "array", "items": { "$ref": "#/components/schemas/SalesTaxJurisdictionTaxDto" }, "description": "List of taxes applied within this jurisdiction." }, "not_taxed_reason": { "type": [ "null", "string" ], "description": "Explanation for why taxes are not applied, if applicable.\nThis property is null when taxes are applied." } }, "additionalProperties": false, "description": "Object representing a sales tax jurisdiction and its associated taxes." }, "SalesTaxJurisdictionTaxDto": { "required": [ "tax_amount", "tax_name", "tax_rate", "taxable_amount" ], "type": "object", "properties": { "tax_name": { "type": "string", "description": "The name of the tax." }, "taxable_amount": { "type": "string", "description": "The amount subject to taxation, formatted as a string." }, "tax_amount": { "type": "string", "description": "The calculated tax amount, formatted as a string." }, "tax_rate": { "type": "string", "description": "The rate at which the tax is applied, formatted as a string." } }, "additionalProperties": false, "description": "Object representing a specific tax within a sales tax jurisdiction." }, "SteamId": { "type": "string", "additionalProperties": false, "description": "A 64-bit Steam account identifier. Accepts string or numeric format.", "format": "steam-id", "example": "76561197960287930" }, "StoreDto": { "required": [ "currency", "description", "game", "id", "live_mode", "name", "owner_id", "platform", "slug" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "owner_id": { "$ref": "#/components/schemas/FlakeId" }, "slug": { "type": "string", "description": "The URL-safe slug used to identify the store (e.g. \"my-rust-server\")." }, "name": { "type": "string", "description": "The display name of the store." }, "platform": { "type": "string", "description": "The platform this store is associated with (e.g. \"rust\", \"minecraft\")." }, "game": { "type": "string", "description": "Alias for 'platform'. Returns the platform identifier as a game name.", "readOnly": true }, "currency": { "type": "string", "description": "The ISO 4217 currency code used by this store for pricing (e.g. \"usd\", \"eur\")" }, "description": { "type": "string", "description": "A human-readable description of the store shown to customers and PayNow." }, "website_url": { "type": [ "null", "string" ], "description": "The store's public website URL." }, "contact_email": { "type": [ "null", "string" ], "description": "General contact email address for the store." }, "support_email": { "type": [ "null", "string" ], "description": "Dedicated support email address for customer inquiries." }, "support_url": { "type": [ "null", "string" ], "description": "URL to the store's support portal or help page." }, "integration_type": { "type": [ "null", "string" ], "description": "The integration type used by the store." }, "live_mode": { "type": "boolean", "description": "When set to true, the store is processing real transactions in live mode." }, "logo_url": { "type": [ "null", "string" ], "description": "URL of the store's full-size logo image." }, "logo_square_url": { "type": [ "null", "string" ], "description": "URL of the store's square/icon logo image." }, "minecraft_bedrock_username_prefix": { "type": [ "null", "string" ], "description": "Username prefix used to identify Minecraft Bedrock players (e.g. \".\")." }, "created_at": { "type": [ "null", "string" ], "description": "The UTC timestamp when the store was created.", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "The UTC timestamp when the store was last updated.", "format": "date-time" }, "onboarding_completed_at": { "type": [ "null", "string" ], "description": "The UTC timestamp when the store completed onboarding.", "format": "date-time" }, "platform_store_type_association": { "$ref": "#/components/schemas/PlatformStoreTypeAssociationDetailsDto" } }, "additionalProperties": false, "description": "Represents a PayNow store and its associated configuration." }, "StoreMemberDto": { "required": [ "id", "user", "user_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "user_id": { "$ref": "#/components/schemas/FlakeId" }, "user": { "$ref": "#/components/schemas/StoreMemberUserDto" }, "added_at": { "type": [ "null", "string" ], "description": "The UTC timestamp when the member was added to the store.", "format": "date-time" }, "added_by": { "$ref": "#/components/schemas/ActorDto" }, "role_id": { "$ref": "#/components/schemas/FlakeId" } }, "additionalProperties": false, "description": "Represents a member of a PayNow store." }, "StoreMemberUserDto": { "required": [ "id", "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PayNowActorType" }, "id": { "$ref": "#/components/schemas/FlakeId" }, "email": { "type": [ "null", "string" ], "description": "The email address associated with the user.\nOnly visible if you are the store owner." }, "first_name": { "type": [ "null", "string" ], "description": "The first name of the actor.\nHidden if the user has a set nickname, and you are not the store owner." }, "last_name": { "type": [ "null", "string" ], "description": "The last name of the actor.\nHidden if the user has a set nickname, and you are not the store owner." }, "nickname": { "type": [ "null", "string" ], "description": "The nickname of the user." } }, "additionalProperties": false, "description": "Represents identity and profile information for a store member." }, "StoreRequirementActionParty": { "enum": [ "invalid", "store", "paynow", "payment_processor", "payout_provider", "kyc_provider", "external" ], "type": "string", "description": "Determines the party that needs to perform or requests a verification", "x-enumDescriptions": { "store": "The associated store", "paynow": "We as a platform, RequestedByDetail is the admin actor ID in that case (or null if internal)", "payment_processor": "Payment processor, e.g. Stripe", "payout_provider": "Payout provider, e.g. Trolley, PayPal", "kyc_provider": "KYC provider, e.g. Stripe, Onefootprint", "external": "External party, not fitting in any other category, e.g. government, regulators" } }, "StoreRequirementCategory": { "enum": [ "invalid", "business", "kyc", "compliance", "risk", "technical", "financial", "legal", "other" ], "type": "string", "description": "Represents categories of requirements that must be fulfilled for store setup and compliance in the PayNow platform.", "x-enumDescriptions": { "invalid": "Invalid or unspecified category. Default value that should not be used in production.", "business": "Business information and operational requirements.\n Includes company details, business model, store policies, refund procedures,\n and operational guidelines for running a store on PayNow.", "kyc": "Know Your Customer (KYC) identity verification requirements.\n Includes government-issued ID verification, proof of address, and identity confirmation\n as per PayNow's KYC Policy and conducted via any third party KYC partners", "compliance": "Regulatory compliance requirements including AML checks and content policies.\n Covers sanctions screening, FATF checks, prohibited customer/product screening,\n and content compliance as defined in PayNow's policies.", "risk": "Risk management and fraud prevention requirements.\n Includes transaction monitoring, unusual activity detection, and ongoing\n risk assessment procedures to protect against fraudulent activities.", "technical": "Technical integration and setup requirements.\n Covers API configuration, webhook setup, platform integration, and any technical\n prerequisites for store operation.", "financial": "Financial setup and verification requirements.\n Includes payment processing configuration, banking information, Tipalti/Trolley payout setup,\n tax documentation (W-9, W-8, etc.), and payment method verification.", "legal": "Legal agreement and policy acceptance requirements.\n Covers acceptance of User Agreement, Terms of Service, Privacy Policy,\n and any other legal documents required by PayNow for store operation.", "other": "Other miscellaneous requirements that don't fit into the above categories.\n Used for special cases or additional requirements specific to certain store types\n or jurisdictions." } }, "StoreRequirementStatus": { "enum": [ "invalid", "pending", "under_review", "requires_revision", "approved", "expired", "waived", "rejected_final" ], "type": "string", "x-enumDescriptions": { "pending": "Requirement created, awaiting action", "under_review": "Submitted, under review, or awaiting external verification", "requires_revision": "Rejected, needs store to resubmit with corrections", "approved": "Requirement successfully fulfilled", "expired": "Requirement expired and needs renewal", "waived": "Requirement waived by PayNow (manual override)", "rejected_final": "Requirement fully rejected - usually terminal state for the entire store" } }, "StoreRestrictionFlagDto": { "enum": [ "none", "payments_disabled", "payouts_disabled" ], "type": "string" }, "StoreTrustDto": { "required": [ "created_at", "events", "pending_requirements", "restrictions", "status", "store_id" ], "type": "object", "properties": { "store_id": { "$ref": "#/components/schemas/FlakeId" }, "status": { "$ref": "#/components/schemas/StoreTrustStatusDto" }, "status_reason": { "type": [ "null", "string" ] }, "restrictions": { "$ref": "#/components/schemas/StoreRestrictionFlagDto" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "format": "date-time" }, "onboarding_steps": { "$ref": "#/components/schemas/StoreTrustOnboardingStepsDto" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/StoreTrustEventDto" } }, "pending_requirements": { "type": "array", "items": { "$ref": "#/components/schemas/TrustStoreRequirementDto" } } }, "additionalProperties": false }, "StoreTrustEventDto": { "required": [ "actor", "created_at", "id", "store_id", "type" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "type": { "$ref": "#/components/schemas/StoreTrustEventTypeDto" }, "description": { "type": [ "null", "string" ] }, "store_requirement_id": { "$ref": "#/components/schemas/FlakeId" }, "store_review_id": { "$ref": "#/components/schemas/FlakeId" }, "actor": { "$ref": "#/components/schemas/ActorDto" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "StoreTrustEventTypeDto": { "enum": [ "invalid", "onboarded", "escalated_to_review", "action_required", "restricted", "offboarded", "reactivated", "requirement_added", "requirement_submitted", "requirement_verified", "requirement_rejected", "requirement_deadline_missed", "requirement_waived", "requirement_requires_revision", "restriction_added", "restriction_lifted", "review_scheduled", "review_completed" ], "type": "string" }, "StoreTrustOnboardingStepsDto": { "required": [ "downloadable_files_added", "gameserver_linked", "kyc_completed", "payout_onboarding_completed", "products_created", "store_id", "store_owner_id", "webhooks_active" ], "type": "object", "properties": { "store_id": { "$ref": "#/components/schemas/FlakeId" }, "store_owner_id": { "$ref": "#/components/schemas/FlakeId" }, "payout_onboarding_completed": { "type": "boolean" }, "kyc_completed": { "type": "boolean" }, "products_created": { "type": "boolean" }, "gameserver_linked": { "type": "boolean" }, "webhooks_active": { "type": "boolean" }, "downloadable_files_added": { "type": "boolean" } }, "additionalProperties": false }, "StoreTrustStatusDto": { "enum": [ "invalid", "pending_review", "requires_action", "under_review", "active", "restricted", "offboarded" ], "type": "string" }, "StorefrontCustomVariableDto": { "required": [ "description", "identifier", "name", "options", "type" ], "type": "object", "properties": { "identifier": { "type": "string", "description": "Unique identifier string used to reference this custom variable programmatically.\nMust contain only letters, numbers, underscores, and hyphens." }, "name": { "type": "string", "description": "Display name for the custom variable shown to customers." }, "description": { "type": "string", "description": "Description explaining what this custom variable is for. Can be shown to customers." }, "type": { "$ref": "#/components/schemas/CustomVariableType" }, "value_regex": { "type": [ "null", "string" ], "description": "Optional regex pattern to validate text/number input values.\nOnly applies to text and number types.\nUses RE2 syntax - does not support negative lookarounds, backreferences, or other advanced regex features." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCustomVariableOptionDto" }, "description": "Available options for dropdown type custom variables.\nEmpty for text and number types." } }, "additionalProperties": false }, "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 }, "StorefrontCustomerDto": { "required": [ "id", "store_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "profile": { "$ref": "#/components/schemas/CustomerGenericProfileDto" }, "steam_id": { "$ref": "#/components/schemas/SteamId" }, "steam": { "$ref": "#/components/schemas/StorefrontCustomerSteamProfileDto" }, "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.", "example": "f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2" }, "minecraft": { "$ref": "#/components/schemas/StorefrontCustomerMinecraftProfileDto" }, "minecraft_platform": { "$ref": "#/components/schemas/CustomerMinecraftPlatform" }, "xbox_xuid": { "type": [ "null", "string" ], "description": "The customer's Xbox XUID, if available." }, "name": { "type": [ "null", "string" ], "description": "The display name for the customer.", "example": "m0uka" } }, "additionalProperties": false, "description": "A storefront representation of a customer in the PayNow system with their associated profiles and metadata." }, "StorefrontCustomerMinecraftProfileDto": { "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.", "example": "f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2" }, "name": { "type": "string", "description": "The username of the Minecraft player.", "example": "notch" }, "avatar_url": { "type": "string", "description": "The URL to the player's Minecraft skin rendered as an avatar." } }, "additionalProperties": false, "description": "A storefront representation of a customers Minecraft profile." }, "StorefrontCustomerSteamProfileDto": { "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": "A storefront representation of a customers Steam profile." }, "StorefrontDeliveryItemDto": { "required": [ "added_at", "customer_id", "expirable", "gift", "id", "product", "state", "store_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "customer_id": { "$ref": "#/components/schemas/FlakeId" }, "order_id": { "$ref": "#/components/schemas/FlakeId" }, "order_line_id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_id": { "$ref": "#/components/schemas/FlakeId" }, "execute_on_gameserver_id": { "$ref": "#/components/schemas/FlakeId" }, "quantity_index": { "type": [ "null", "integer" ], "description": "The index of the item when multiple quantities were assigned", "format": "int32" }, "product": { "$ref": "#/components/schemas/DeliveryItemProductDto" }, "state": { "$ref": "#/components/schemas/DeliveryItemStateDto" }, "expirable": { "type": "boolean", "description": "Indicates whether the delivery item can expire" }, "gift": { "type": "boolean", "description": "Indicates whether the item was given as a gift" }, "added_at": { "type": "string", "description": "The date and time when the item was added", "format": "date-time" }, "active_at": { "type": [ "null", "string" ], "description": "The date and time when the item became active", "format": "date-time" }, "expires_at": { "type": [ "null", "string" ], "description": "The date and time when the item expires naturally", "format": "date-time" }, "override_expires_at": { "type": [ "null", "string" ], "description": "The override expiry date for the delivery item", "format": "date-time" }, "removed_at": { "type": [ "null", "string" ], "description": "The date and time when the item was removed", "format": "date-time" }, "revoked_at": { "type": [ "null", "string" ], "description": "The date and time when the item was revoked", "format": "date-time" }, "revoke_reason": { "type": [ "null", "string" ], "description": "The reason for revoking the delivery item" } }, "additionalProperties": false, "description": "Represents a delivery item assigned to a customer" }, "StorefrontGameServerDto": { "required": [ "enabled", "id", "name" ], "type": "object", "properties": { "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." }, "StorefrontGiftCardDto": { "required": [ "balance", "code", "starting_balance" ], "type": "object", "properties": { "code": { "type": "string" }, "balance": { "type": "integer", "format": "int32" }, "starting_balance": { "type": "integer", "format": "int32" }, "expires_at": { "type": [ "null", "string" ], "format": "date-time" } }, "additionalProperties": false }, "StorefrontNavLinkDto": { "required": [ "children", "name", "node_id", "order", "tag_id", "tag_query", "tag_slug" ], "type": "object", "properties": { "node_id": { "type": "string", "description": "The unique identifier for this navigation node in the navigation tree." }, "parent_node_id": { "type": [ "null", "string" ], "description": "The identifier of the parent navigation node, if this is a child node." }, "tag_id": { "$ref": "#/components/schemas/FlakeId" }, "tag_slug": { "type": "string", "description": "The URL-friendly slug for the tag associated with this navigation link.", "example": "perks" }, "tag_query": { "type": "array", "items": { "type": "string" }, "description": "A list containing all parent tags and this node's tag, representing the complete path in the tag hierarchy.", "example": [ "perks", "vip" ] }, "name": { "type": "string", "description": "The display name of the associated tag shown to users in the UI.", "example": "Perks" }, "order": { "type": "integer", "description": "The display order of this navigation link relative to its siblings.", "format": "int32" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontNavLinkDto" }, "description": "The collection of child navigation links that appear beneath this link in the hierarchy." } }, "additionalProperties": false, "description": "Represents a navigation link in the storefront's hierarchical navigation structure." }, "StorefrontOrderDto": { "required": [ "currency", "customer", "customer_id", "discount_amount", "discount_amount_str", "giftcard_usage_amount", "giftcard_usage_amount_str", "id", "is_subscription", "lines", "presentment_currency", "presentment_discount_amount", "presentment_discount_amount_str", "presentment_giftcard_usage_amount", "presentment_giftcard_usage_amount_str", "presentment_subtotal_amount", "presentment_subtotal_amount_str", "presentment_tax_amount", "presentment_tax_amount_str", "presentment_total_amount", "presentment_total_amount_str", "pretty_id", "status", "store_id", "subtotal_amount", "subtotal_amount_str", "tax_amount", "tax_amount_str", "total_amount", "total_amount_str", "type" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "pretty_id": { "type": "string", "description": "Human-readable identifier for the order.", "readOnly": true }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "customer_id": { "$ref": "#/components/schemas/FlakeId" }, "customer": { "$ref": "#/components/schemas/StorefrontCustomerDto" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "type": { "$ref": "#/components/schemas/OrderType" }, "checkout_id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_id": { "$ref": "#/components/schemas/FlakeId" }, "is_subscription": { "type": "boolean", "description": "Indicates whether this order is a subscription order." }, "currency": { "type": "string", "description": "Currency code used for this order." }, "discount_amount": { "type": "integer", "description": "The total discount amount applied to this order in smallest currency unit", "format": "int32", "example": 500 }, "discount_amount_str": { "type": "string", "description": "The discount amount formatted as a string", "example": "$5.00" }, "subtotal_amount": { "type": "integer", "description": "The subtotal amount for this order in smallest currency unit", "format": "int32", "example": 9995 }, "subtotal_amount_str": { "type": "string", "description": "The subtotal amount formatted as a string", "example": "$99.95" }, "tax_amount": { "type": "integer", "description": "The tax amount for this order in smallest currency unit", "format": "int32", "example": 999 }, "tax_amount_str": { "type": "string", "description": "The tax amount formatted as a string", "example": "$9.99" }, "total_amount": { "type": "integer", "description": "The total amount for this order in smallest currency unit", "format": "int32", "example": 10494 }, "total_amount_str": { "type": "string", "description": "The total amount formatted as a string", "example": "$104.94" }, "giftcard_usage_amount": { "type": "integer", "description": "The amount of gift card value used for this order in smallest currency unit", "format": "int32", "example": 0 }, "giftcard_usage_amount_str": { "type": "string", "description": "The gift card usage amount formatted as a string", "example": "$0.00" }, "presentment_currency": { "type": "string", "description": "The presentment currency code used for this order (currency shown to customer)", "example": "eur" }, "presentment_subtotal_amount": { "type": "integer", "description": "The presentment subtotal amount in smallest currency unit", "format": "int32", "example": 9995 }, "presentment_subtotal_amount_str": { "type": "string", "description": "The presentment subtotal amount formatted as a string", "readOnly": true, "example": "€99.95" }, "presentment_discount_amount": { "type": "integer", "description": "The presentment discount amount in smallest currency unit", "format": "int32", "example": 500 }, "presentment_discount_amount_str": { "type": "string", "description": "The presentment discount amount formatted as a string", "readOnly": true, "example": "€5.00" }, "presentment_giftcard_usage_amount": { "type": "integer", "description": "The presentment gift card usage amount in the smallest currency unit", "format": "int32", "example": 0 }, "presentment_giftcard_usage_amount_str": { "type": "string", "description": "The presentment gift card usage amount formatted as a string", "readOnly": true, "example": "€0.00" }, "presentment_tax_amount": { "type": "integer", "description": "The presentment tax amount in smallest currency unit", "format": "int32", "example": 999 }, "presentment_tax_amount_str": { "type": "string", "description": "The presentment tax amount formatted as a string", "readOnly": true, "example": "€9.99" }, "presentment_total_amount": { "type": "integer", "description": "The presentment total amount in the smallest currency unit", "format": "int32", "example": 10494 }, "presentment_total_amount_str": { "type": "string", "description": "The presentment total amount formatted as a string", "readOnly": true, "example": "€104.94" }, "billing_cycle_sequence": { "type": [ "null", "integer" ], "description": "Sequence number of the billing cycle, if this order is associated with a subscription.", "format": "int32" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontOrderLineDto" }, "description": "Line items associated with this order." }, "created_at": { "type": [ "null", "string" ], "description": "Date and time when the order was created.", "format": "date-time" }, "completed_at": { "type": [ "null", "string" ], "description": "Date and time when the order was completed.", "format": "date-time" }, "canceled_at": { "type": [ "null", "string" ], "description": "Date and time when the order was canceled.", "format": "date-time" } }, "additionalProperties": false, "description": "Data transfer object representing a store order." }, "StorefrontOrderLineDto": { "required": [ "checkout_line_id", "discount_amount", "discount_amount_str", "gift", "giftcard_usage_amount", "giftcard_usage_amount_str", "id", "presentment_discount_amount", "presentment_discount_amount_str", "presentment_giftcard_usage_amount", "presentment_giftcard_usage_amount_str", "presentment_subtotal_amount", "presentment_subtotal_amount_str", "presentment_tax_amount", "presentment_tax_amount_str", "presentment_total_amount", "presentment_total_amount_str", "price", "price_str", "product_id", "product_image_url", "product_name", "product_version_id", "quantity", "subtotal_amount", "subtotal_amount_str", "tax_amount", "tax_amount_str", "tax_inclusive", "total_amount", "total_amount_str" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "checkout_line_id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_line_id": { "$ref": "#/components/schemas/FlakeId" }, "trial_id": { "$ref": "#/components/schemas/FlakeId" }, "product_id": { "$ref": "#/components/schemas/FlakeId" }, "product_version_id": { "$ref": "#/components/schemas/FlakeId" }, "product_name": { "type": "string", "description": "Name of the product associated with this order line." }, "product_image_url": { "type": "string", "description": "URL for the product image." }, "subscription_interval_value": { "type": [ "null", "integer" ], "description": "Numeric value of the subscription billing interval, if this line is a subscription.", "format": "int32" }, "subscription_interval_scale": { "type": [ "null", "string" ], "description": "Scale of the subscription billing interval (e.g., \"day\", \"month\", \"year\"), if applicable." }, "gift": { "type": "boolean", "description": "Indicates whether this order line is a gift to another customer." }, "gift_to_customer_id": { "$ref": "#/components/schemas/FlakeId" }, "gift_to_customer": { "$ref": "#/components/schemas/StorefrontCustomerDto" }, "price": { "type": "integer", "description": "The unit price of the product in the smallest currency unit (e.g., cents)", "format": "int32", "example": 1999 }, "price_str": { "type": "string", "description": "The unit price of the product formatted as a string", "example": "$19.99" }, "quantity": { "type": "integer", "description": "The quantity of the product in this order line", "format": "int32", "example": 1 }, "discount_amount": { "type": "integer", "description": "The discount amount (from sales, coupons, and affiliate links) applied to this order line", "format": "int32", "example": 0 }, "discount_amount_str": { "type": "string", "description": "The discount amount formatted as a string", "example": "$0.00" }, "giftcard_usage_amount": { "type": "integer", "description": "The amount of gift card used for this order line", "format": "int32", "example": 0 }, "giftcard_usage_amount_str": { "type": "string", "description": "The gift card usage amount formatted as a string", "example": "$0.00" }, "subtotal_amount": { "type": "integer", "description": "The subtotal amount for this order line", "format": "int32", "example": 1999 }, "subtotal_amount_str": { "type": "string", "description": "The subtotal amount formatted as a string", "example": "$19.99" }, "tax_amount": { "type": "integer", "description": "The tax amount for this order line", "format": "int32", "example": 200 }, "tax_amount_str": { "type": "string", "description": "The tax amount formatted as a string", "example": "$2.00" }, "total_amount": { "type": "integer", "description": "The total amount for this order line", "format": "int32", "example": 2199 }, "total_amount_str": { "type": "string", "description": "The total amount formatted as a string", "example": "$21.99" }, "presentment_subtotal_amount": { "type": "integer", "description": "The presentment subtotal amount for this order line", "format": "int32", "example": 1999 }, "presentment_subtotal_amount_str": { "type": "string", "description": "The presentment subtotal amount formatted as a string", "readOnly": true, "example": "€19.99" }, "presentment_discount_amount": { "type": "integer", "description": "The presentment discount amount for this order line", "format": "int32", "example": 0 }, "presentment_discount_amount_str": { "type": "string", "description": "The presentment discount amount formatted as a string", "readOnly": true, "example": "€0.00" }, "presentment_tax_amount": { "type": "integer", "description": "The presentment tax amount for this order line", "format": "int32", "example": 200 }, "presentment_tax_amount_str": { "type": "string", "description": "The presentment tax amount formatted as a string", "readOnly": true, "example": "€2.00" }, "presentment_giftcard_usage_amount": { "type": "integer", "description": "The presentment gift card usage amount for this order line", "format": "int32", "example": 0 }, "presentment_giftcard_usage_amount_str": { "type": "string", "description": "The presentment gift card usage amount formatted as a string", "readOnly": true, "example": "€0.00" }, "presentment_total_amount": { "type": "integer", "description": "The presentment total amount for this order line", "format": "int32", "example": 2199 }, "presentment_total_amount_str": { "type": "string", "description": "The presentment total amount formatted as a string", "readOnly": true, "example": "€21.99" }, "selected_gameserver_id": { "$ref": "#/components/schemas/FlakeId" }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether tax is included in the base price, or added on top", "example": false }, "pricing_region_id": { "type": [ "null", "string" ], "description": "The regional pricing region ID for this order line, null if no regional pricing set", "example": "eu" }, "custom_variables": { "type": [ "null", "object" ], "additionalProperties": { "$ref": "#/components/schemas/CustomVariableLineItemDto" }, "description": "Key-value pair of selected custom variables for this order." } }, "additionalProperties": false, "description": "Represents a line item within an order." }, "StorefrontProductDto": { "required": [ "allow_one_time_purchase", "allow_subscription", "currency", "custom_variables", "description", "gameservers", "hidden", "id", "is_affiliate_links_disabled", "is_coupons_disabled", "is_gift_cards_disabled", "is_gifting_disabled", "name", "price", "remove_after_enabled", "remove_after_time_scale", "remove_after_time_value", "single_game_server_only", "slug", "sort_order", "store_id", "subscription_interval_scale", "subscription_interval_value", "tags", "trial", "version_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "version_id": { "$ref": "#/components/schemas/FlakeId" }, "image_url": { "type": [ "null", "string" ], "description": "The URL to the product image.", "example": "https://cdn.paynow.gg/logo/full/logotype-color.svg" }, "slug": { "type": "string", "description": "The unique slug for the product.", "example": "premium-game-package" }, "name": { "type": "string", "description": "The display name of the product.", "example": "Premium Game Package" }, "description": { "type": "string", "description": "The detailed description of the product.", "example": "This premium package includes exclusive in-game items, bonus currency, and early access to new content." }, "enabled_at": { "type": [ "null", "string" ], "description": "The date and time when the product becomes enabled.", "format": "date-time" }, "enabled_until": { "type": [ "null", "string" ], "description": "The date and time until which the product remains enabled.", "format": "date-time" }, "label": { "type": [ "null", "string" ], "description": "The display label for the product.", "example": "Premium Items" }, "hidden": { "type": "boolean", "description": "Indicates if the product is hidden." }, "sort_order": { "type": "integer", "description": "The sort order for displaying the product.", "format": "int32" }, "price": { "type": "integer", "description": "The price of the product, in the lowest denominator (e.g. cents).", "format": "int64", "example": 1999 }, "currency": { "type": "string", "description": "The ISO three-letter lowercase currency code (e.g., usd, eur, gbp) the product is denominated in." }, "single_game_server_only": { "type": "boolean", "description": "Indicates whether the product is limited to a single game server." }, "allow_one_time_purchase": { "type": "boolean", "description": "Indicates whether one-time purchases are allowed.", "example": true }, "allow_subscription": { "type": "boolean", "description": "Indicates whether subscription purchases are allowed.", "example": true }, "is_gifting_disabled": { "type": "boolean", "description": "Indicates whether gifting is disabled for this product." }, "is_gift_cards_disabled": { "type": "boolean", "description": "Indicates whether gift cards are disabled entirely for the product." }, "is_coupons_disabled": { "type": "boolean", "description": "Indicates whether coupons are disabled entirely for the product." }, "is_affiliate_links_disabled": { "type": "boolean", "description": "Indicates whether affiliate links are disabled entirely for the product." }, "subscription_interval_value": { "type": "integer", "description": "The subscription interval value.", "format": "int32", "example": 1 }, "subscription_interval_scale": { "$ref": "#/components/schemas/ProductSubscriptionIntervalScale" }, "remove_after_enabled": { "type": "boolean", "description": "Indicates whether automatic removal is enabled.", "example": true }, "remove_after_time_value": { "type": "integer", "description": "The time value for automatic removal.", "format": "int32", "example": 1 }, "remove_after_time_scale": { "$ref": "#/components/schemas/ProductRemoveAfterIntervalScale" }, "pricing": { "$ref": "#/components/schemas/StorefrontProductPricingDto" }, "stock": { "$ref": "#/components/schemas/StorefrontProductStockDto" }, "trial": { "$ref": "#/components/schemas/StorefrontProductTrialDto" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ProductTagDto" }, "description": "The tags associated with the product." }, "gameservers": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontGameServerDto" }, "description": "The game servers associated with the product." }, "custom_variables": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontCustomVariableDto" }, "description": "Custom Variables associated with the product." }, "deliverable_actions": { "$ref": "#/components/schemas/ProductDeliverableActionsDto" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": { "type": "string" }, "description": "Additional metadata for the product." }, "created_at": { "type": [ "null", "string" ], "description": "The date and time when the product was created.", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "The date and time when the product was last updated.", "format": "date-time" }, "tier_group_id": { "$ref": "#/components/schemas/FlakeId" }, "active_tier_group": { "$ref": "#/components/schemas/CustomerTierGroupDto" } }, "additionalProperties": false }, "StorefrontProductPricingDto": { "required": [ "price_final", "price_original" ], "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", "example": 500 }, "vat_rate": { "$ref": "#/components/schemas/SalesTaxEstimateDto" }, "regional_pricing": { "$ref": "#/components/schemas/StorefrontProductRegionalPricingDto" }, "price_original": { "type": "integer", "description": "The original price of the product before any discounts, in the lowest denominator (e.g. cents).", "format": "int64", "example": 1999 }, "price_final": { "type": "integer", "description": "The final price of the product after all discounts, in the lowest denominator (e.g. cents).", "format": "int64", "example": 1499 } }, "additionalProperties": false, "description": "The pricing details for the product in the storefront." }, "StorefrontProductRegionalPricingDto": { "required": [ "base_price", "currency", "region_id", "tax_inclusive" ], "type": "object", "properties": { "region_id": { "type": "string", "description": "The identifier for the region.", "example": "eu" }, "currency": { "type": "string", "description": "The currency code used in the region.", "example": "eur" }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether the base price includes tax.", "example": true }, "base_price": { "type": "integer", "description": "The base price in the regional currency, in the lowest denominator (e.g. cents).", "format": "int64", "example": 1799 } }, "additionalProperties": false, "description": "Regional pricing information for this product.\nOnly present if there is a regional pricing configured." }, "StorefrontProductStockDto": { "required": [ "available_to_purchase", "customer_available" ], "type": "object", "properties": { "available_to_purchase": { "type": "boolean", "description": "Indicates whether the product is currently available for purchase (there is available stock).", "example": true }, "customer_available": { "type": "integer", "description": "The number of items available for the customer to purchase (customer stock limit remaining).", "format": "int32", "example": 5 } }, "additionalProperties": false, "description": "The stock status information for the product in the storefront." }, "StorefrontProductTrialDto": { "required": [ "eligible", "enabled", "period_scale", "period_value" ], "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates whether the trial period is enabled for this product." }, "eligible": { "type": "boolean", "description": "Indicates whether the customer is eligible for the trial period." }, "period_value": { "type": "integer", "description": "The duration value of the trial period.", "format": "int32" }, "period_scale": { "$ref": "#/components/schemas/ProductSubscriptionIntervalScale" } }, "additionalProperties": false }, "StorefrontSaleDto": { "required": [ "begins_at", "discount_amount", "discount_type", "id", "minimum_order_value", "name", "version_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "version_id": { "$ref": "#/components/schemas/FlakeId" }, "name": { "type": "string", "description": "The name of the sale.", "example": "Summer Sale" }, "discount_type": { "$ref": "#/components/schemas/SaleDiscountTypeDto" }, "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", "example": 2000 }, "minimum_order_value": { "type": "integer", "description": "The minimum order value required to apply the discount, in the lowest denominator (e.g. cents).", "format": "int64", "example": 0 }, "begins_at": { "type": "string", "description": "The date and time when the sale begins.", "format": "date-time", "example": "2025-06-01T00:00:00Z" }, "ends_at": { "type": [ "null", "string" ], "description": "The date and time when the sale ends, if applicable.", "format": "date-time", "example": "2025-06-30T23:59:59Z" } }, "additionalProperties": false }, "StorefrontStoreDto": { "required": [ "creator_currency", "currency", "game", "id", "live_mode", "name", "platform", "slug" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "slug": { "type": "string", "description": "The URL-friendly identifier for the store, used in store URLs.", "example": "m0ukas-awesome-store" }, "name": { "type": "string", "description": "The display name of the store shown to customers.", "example": "m0uka's awesome store" }, "platform": { "type": "string", "description": "The platform or the game of the store.", "example": "rust" }, "game": { "type": "string", "description": "The game of the store. Equivalent to the `platform` for backwards compatibility.", "readOnly": true }, "currency": { "type": "string", "description": "The three-letter ISO currency code used for pricing in this store.\nIf using the Adaptive Currency feature, this will be updated to reflect customer's local currency\n(based on passed in IP / country headers).", "example": "eur" }, "creator_currency": { "type": "string", "description": "The three-letter ISO currency code signifying the main currency of the store.", "example": "usd" }, "description": { "type": [ "null", "string" ], "description": "A detailed description of the store. Only present for some platform types." }, "website_url": { "type": [ "null", "string" ], "description": "The URL of the store's main website, if not using Hosted Webstores." }, "support_email": { "type": [ "null", "string" ], "description": "The email address customers can use to contact store support.", "example": "support@example.com" }, "support_url": { "type": [ "null", "string" ], "description": "The URL of the store's support page." }, "integration_type": { "type": [ "null", "string" ], "description": "The type of integration this store uses with external systems." }, "live_mode": { "type": "boolean", "description": "Indicates whether the store is in live mode (true) or test mode (false)." }, "logo_url": { "type": [ "null", "string" ], "description": "The URL to the store's main logo image." }, "logo_square_url": { "type": [ "null", "string" ], "description": "The URL to the store's square logo image." }, "created_at": { "type": [ "null", "string" ], "description": "The date and time when the store was created.", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "The date and time when the store was last updated.", "format": "date-time" } }, "additionalProperties": false, "description": "Represents a store entity within the storefront system." }, "StorefrontSubscriptionDto": { "required": [ "cancel_at_period_end", "coupon_ids", "created_at", "currency", "customer", "discount_amount", "discount_amount_str", "id", "initial_discount_amount", "initial_discount_amount_str", "initial_giftcard_usage_amount", "initial_giftcard_usage_amount_str", "initial_subtotal_amount", "initial_subtotal_amount_str", "initial_tax_amount", "initial_tax_amount_str", "initial_total_amount", "initial_total_amount_str", "interval_scale", "interval_value", "lines", "next_billing_amount", "next_billing_presentment_amount", "past_due", "pretty_id", "status", "store_id", "subtotal_amount", "subtotal_amount_str", "tax_amount", "tax_amount_str", "tax_jurisdictions", "total_amount", "total_amount_str" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "pretty_id": { "type": "string", "description": "Human-readable identifier for the subscription.", "readOnly": true }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "customer": { "$ref": "#/components/schemas/StorefrontCustomerDto" }, "pending_change": { "$ref": "#/components/schemas/SubscriptionChangeDto" }, "next_billing_amount": { "$ref": "#/components/schemas/SubscriptionBillingAmountDto" }, "next_billing_presentment_amount": { "$ref": "#/components/schemas/SubscriptionBillingAmountDto" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusDto" }, "coupon_ids": { "type": "array", "items": { "$ref": "#/components/schemas/FlakeId" }, "description": "Identifiers of coupons applied to this subscription." }, "checkout_id": { "$ref": "#/components/schemas/FlakeId" }, "tax_jurisdictions": { "type": "array", "items": { "$ref": "#/components/schemas/SalesTaxJurisdictionDto" }, "description": "List of tax jurisdictions applicable to this subscription." }, "interval_value": { "type": "integer", "description": "Numeric value of the billing interval.", "format": "int32" }, "interval_scale": { "$ref": "#/components/schemas/ProductSubscriptionIntervalScale" }, "currency": { "type": "string", "description": "Currency code used for billing this subscription." }, "discount_amount": { "type": "integer", "description": "Amount of discount applied in smallest currency units.", "format": "int64" }, "discount_amount_str": { "type": "string", "description": "Formatted string representation of the discount amount.", "readOnly": true }, "subtotal_amount": { "type": "integer", "description": "Subtotal amount in smallest currency units.", "format": "int64" }, "subtotal_amount_str": { "type": "string", "description": "Formatted string representation of the subtotal amount.", "readOnly": true }, "tax_amount": { "type": "integer", "description": "Tax amount in the smallest currency units.", "format": "int64" }, "tax_amount_str": { "type": "string", "description": "Formatted string representation of the tax amount.", "readOnly": true }, "total_amount": { "type": "integer", "description": "Total amount in the smallest currency units.", "format": "int64" }, "total_amount_str": { "type": "string", "description": "Formatted string representation of the total amount.", "readOnly": true }, "initial_discount_amount": { "type": "integer", "description": "Initial discount amount in the smallest currency units for the first billing cycle.", "format": "int64" }, "initial_discount_amount_str": { "type": "string", "description": "Formatted string representation of the initial discount amount.", "readOnly": true }, "initial_subtotal_amount": { "type": "integer", "description": "Initial subtotal amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_subtotal_amount_str": { "type": "string", "description": "Formatted string representation of the initial subtotal amount.", "readOnly": true }, "initial_giftcard_usage_amount": { "type": "integer", "description": "Initial gift card usage amount in smallest currency units.", "format": "int64" }, "initial_giftcard_usage_amount_str": { "type": "string", "description": "Formatted string representation of the initial gift card usage amount.", "readOnly": true }, "initial_tax_amount": { "type": "integer", "description": "Initial tax amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_tax_amount_str": { "type": "string", "description": "Formatted string representation of the initial tax amount.", "readOnly": true }, "initial_total_amount": { "type": "integer", "description": "Initial total amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_total_amount_str": { "type": "string", "description": "Formatted string representation of the initial total amount.", "readOnly": true }, "presentment_currency": { "type": [ "null", "string" ], "description": "Presentment currency code (currency shown to customer)." }, "presentment_subtotal_amount": { "type": [ "null", "integer" ], "description": "Presentment subtotal amount in smallest currency units.", "format": "int64" }, "presentment_subtotal_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment subtotal amount.", "readOnly": true }, "presentment_discount_amount": { "type": [ "null", "integer" ], "description": "Presentment discount amount in smallest currency units.", "format": "int64" }, "presentment_discount_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment discount amount.", "readOnly": true }, "presentment_tax_amount": { "type": [ "null", "integer" ], "description": "Presentment tax amount in smallest currency units.", "format": "int64" }, "presentment_tax_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment tax amount.", "readOnly": true }, "presentment_total_amount": { "type": [ "null", "integer" ], "description": "Presentment total amount in smallest currency units.", "format": "int64" }, "presentment_total_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment total amount.", "readOnly": true }, "initial_presentment_discount_amount": { "type": [ "null", "integer" ], "description": "Initial presentment discount amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_discount_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment discount amount.", "readOnly": true }, "initial_presentment_subtotal_amount": { "type": [ "null", "integer" ], "description": "Initial presentment subtotal amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_subtotal_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment subtotal amount.", "readOnly": true }, "initial_presentment_giftcard_usage_amount": { "type": [ "null", "integer" ], "description": "Initial presentment gift card usage amount in smallest currency units.", "format": "int64" }, "initial_presentment_giftcard_usage_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment gift card usage amount.", "readOnly": true }, "initial_presentment_tax_amount": { "type": [ "null", "integer" ], "description": "Initial presentment tax amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_tax_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment tax amount.", "readOnly": true }, "initial_presentment_total_amount": { "type": [ "null", "integer" ], "description": "Initial presentment total amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_total_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment total amount.", "readOnly": true }, "fx_rate": { "type": [ "null", "string" ], "description": "The foreign exchange rate applied (if presentment currency differs from settlement currency)." }, "current_period_start": { "type": [ "null", "string" ], "description": "Start date of the current billing period.", "format": "date-time" }, "current_period_end": { "type": [ "null", "string" ], "description": "End date of the current billing period.", "format": "date-time" }, "billing_cycle_sequence": { "type": [ "null", "integer" ], "description": "Sequence number of the current billing cycle.", "format": "int32" }, "next_attempt_at": { "type": [ "null", "string" ], "description": "Date and time when the next payment attempt will occur.", "format": "date-time" }, "attempt_count": { "type": [ "null", "integer" ], "description": "Number of payment attempts made for the current billing cycle.", "format": "int32" }, "created_at": { "type": "string", "description": "Date and time when the subscription was created.", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "Date and time when the subscription was last updated.", "format": "date-time" }, "active_at": { "type": [ "null", "string" ], "description": "Date and time when the subscription became active.", "format": "date-time" }, "canceled_at": { "type": [ "null", "string" ], "description": "Date and time when the subscription was canceled.", "format": "date-time" }, "cancel_reason": { "type": [ "null", "string" ], "description": "Reason provided for cancellation." }, "cancellation_requested_at": { "type": [ "null", "string" ], "description": "Date and time when a subscription cancellation (cancel_at_period_end) was requested.", "format": "date-time" }, "cancel_at_period_end": { "type": "boolean", "description": "Whether the subscription will be canceled at the end of the billing period.", "readOnly": true }, "past_due": { "type": "boolean", "description": "Whether the subscription is past due, and is in a dunning (retrying) state." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontSubscriptionLineDto" }, "description": "Line items associated with this subscription." } }, "additionalProperties": false, "description": "Data transfer object representing a store subscription." }, "StorefrontSubscriptionLineDto": { "required": [ "currency", "discount_amount", "discount_amount_str", "id", "initial_discount_amount", "initial_discount_amount_str", "initial_giftcard_usage_amount", "initial_giftcard_usage_amount_str", "initial_subtotal_amount", "initial_subtotal_amount_str", "initial_tax_amount", "initial_tax_amount_str", "initial_total_amount", "initial_total_amount_str", "price", "product_id", "product_name", "product_version_id", "store_id", "subscription_id", "subtotal_amount", "subtotal_amount_str", "tax_amount", "tax_amount_str", "tax_inclusive", "total_amount", "total_amount_str" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_id": { "$ref": "#/components/schemas/FlakeId" }, "checkout_line_id": { "$ref": "#/components/schemas/FlakeId" }, "initial_order_line_id": { "$ref": "#/components/schemas/FlakeId" }, "pricing_region_id": { "type": [ "null", "string" ], "description": "Identifier for the pricing region associated with this subscription line." }, "gift_to_customer_id": { "$ref": "#/components/schemas/FlakeId" }, "selected_gameserver_id": { "$ref": "#/components/schemas/FlakeId" }, "sale_id": { "$ref": "#/components/schemas/FlakeId" }, "sale_version_id": { "$ref": "#/components/schemas/FlakeId" }, "trial_id": { "$ref": "#/components/schemas/FlakeId" }, "product_id": { "$ref": "#/components/schemas/FlakeId" }, "product_version_id": { "$ref": "#/components/schemas/FlakeId" }, "product_name": { "type": "string", "description": "Name of the product associated with this subscription line." }, "product_image_url": { "type": [ "null", "string" ], "description": "URL for the product image." }, "tax_inclusive": { "type": "boolean", "description": "Indicates whether tax is included in the base price itself." }, "currency": { "type": "string", "description": "Currency code for this subscription line." }, "price": { "type": "integer", "description": "Base price of the subscription line in smallest currency units (e.g., cents).", "format": "int64" }, "discount_amount": { "type": "integer", "description": "Amount of discount applied in smallest currency units.", "format": "int64" }, "discount_amount_str": { "type": "string", "description": "Formatted string representation of the discount amount.", "readOnly": true }, "subtotal_amount": { "type": "integer", "description": "Subtotal amount in smallest currency units.", "format": "int64" }, "subtotal_amount_str": { "type": "string", "description": "Formatted string representation of the subtotal amount.", "readOnly": true }, "tax_amount": { "type": "integer", "description": "Tax amount in smallest currency units.", "format": "int64" }, "tax_amount_str": { "type": "string", "description": "Formatted string representation of the tax amount.", "readOnly": true }, "total_amount": { "type": "integer", "description": "Total amount in smallest currency units.", "format": "int64" }, "total_amount_str": { "type": "string", "description": "Formatted string representation of the total amount.", "readOnly": true }, "initial_discount_amount": { "type": "integer", "description": "Initial discount amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_discount_amount_str": { "type": "string", "description": "Formatted string representation of the initial discount amount.", "readOnly": true }, "initial_subtotal_amount": { "type": "integer", "description": "Initial subtotal amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_subtotal_amount_str": { "type": "string", "description": "Formatted string representation of the initial subtotal amount.", "readOnly": true }, "initial_giftcard_usage_amount": { "type": "integer", "description": "Initial gift card usage amount in smallest currency units.", "format": "int64" }, "initial_giftcard_usage_amount_str": { "type": "string", "description": "Formatted string representation of the initial gift card usage amount.", "readOnly": true }, "initial_tax_amount": { "type": "integer", "description": "Initial tax amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_tax_amount_str": { "type": "string", "description": "Formatted string representation of the initial tax amount.", "readOnly": true }, "initial_total_amount": { "type": "integer", "description": "Initial total amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_total_amount_str": { "type": "string", "description": "Formatted string representation of the initial total amount.", "readOnly": true }, "presentment_currency": { "type": [ "null", "string" ], "description": "Presentment currency code (currency shown to customer)." }, "presentment_subtotal_amount": { "type": [ "null", "integer" ], "description": "Presentment subtotal amount in smallest currency units.", "format": "int64" }, "presentment_subtotal_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment subtotal amount.", "readOnly": true }, "presentment_discount_amount": { "type": [ "null", "integer" ], "description": "Presentment discount amount in smallest currency units.", "format": "int64" }, "presentment_discount_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment discount amount.", "readOnly": true }, "presentment_tax_amount": { "type": [ "null", "integer" ], "description": "Presentment tax amount in smallest currency units.", "format": "int64" }, "presentment_tax_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment tax amount.", "readOnly": true }, "presentment_total_amount": { "type": [ "null", "integer" ], "description": "Presentment total amount in smallest currency units.", "format": "int64" }, "presentment_total_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the presentment total amount.", "readOnly": true }, "initial_presentment_discount_amount": { "type": [ "null", "integer" ], "description": "Initial presentment discount amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_discount_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment discount amount.", "readOnly": true }, "initial_presentment_subtotal_amount": { "type": [ "null", "integer" ], "description": "Initial presentment subtotal amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_subtotal_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment subtotal amount.", "readOnly": true }, "initial_presentment_giftcard_usage_amount": { "type": [ "null", "integer" ], "description": "Initial presentment gift card usage amount in smallest currency units.", "format": "int64" }, "initial_presentment_giftcard_usage_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment gift card usage amount.", "readOnly": true }, "initial_presentment_tax_amount": { "type": [ "null", "integer" ], "description": "Initial presentment tax amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_tax_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment tax amount.", "readOnly": true }, "initial_presentment_total_amount": { "type": [ "null", "integer" ], "description": "Initial presentment total amount in smallest currency units for the first billing cycle.", "format": "int64" }, "initial_presentment_total_amount_str": { "type": [ "null", "string" ], "description": "Formatted string representation of the initial presentment total amount.", "readOnly": true } }, "additionalProperties": false, "description": "Represents a line item within a subscription." }, "StorefrontTagDto": { "required": [ "created_at", "enabled", "id", "name", "slug", "store_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "slug": { "type": "string", "description": "The URL-friendly identifier for the tag, used in category URLs." }, "name": { "type": "string", "description": "The display name of the tag shown to customers." }, "description": { "type": [ "null", "string" ], "description": "A detailed description of the tag's purpose or the category it represents." }, "image_url": { "type": [ "null", "string" ], "description": "The URL to the tag image.", "example": "https://cdn.paynow.gg/logo/full/logotype-color.svg" }, "enabled": { "type": "boolean", "description": "Indicates whether the tag is active and should be included in navigation and filtering." }, "created_at": { "type": "string", "description": "The date and time when the tag was created.", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "The date and time when the tag was last updated, if applicable.", "format": "date-time" } }, "additionalProperties": false, "description": "Represents a tag entity used for categorizing and filtering products within a store." }, "SubscriptionBillingAmountDto": { "required": [ "currency", "discount", "subtotal", "tax", "total" ], "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code, in lowercase." }, "subtotal": { "type": "integer", "description": "Base amount before discounts or tax, in smallest currency units.", "format": "int64" }, "discount": { "type": "integer", "description": "Total discount applied, in smallest currency units.", "format": "int64" }, "tax": { "type": "integer", "description": "Tax amount, in smallest currency units.", "format": "int64" }, "total": { "type": "integer", "description": "Amount due after discounts and tax, in smallest currency units.", "format": "int64" } }, "additionalProperties": false, "description": "Represents a billing amount breakdown for a subscription." }, "SubscriptionChangeAmountDto": { "required": [ "currency", "discount", "subtotal", "tax", "total" ], "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code, in lowercase." }, "subtotal": { "type": "integer", "description": "Base amount before discounts or tax, in smallest currency units.", "format": "int64" }, "discount": { "type": "integer", "description": "Total discount applied, in smallest currency units.", "format": "int64" }, "tax": { "type": "integer", "description": "Tax amount, in smallest currency units.", "format": "int64" }, "total": { "type": "integer", "description": "Amount due after discounts and tax, in smallest currency units.", "format": "int64" } }, "additionalProperties": false, "description": "Pricing breakdown for a subscription change, in the smallest units of the given currency (e.g. cents)." }, "SubscriptionChangeDto": { "required": [ "created_at", "id", "lines", "next_billing_amount", "next_billing_presentment_amount", "off_session", "prorated_amount", "proration_behavior", "status", "subscription_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_id": { "$ref": "#/components/schemas/FlakeId" }, "prorated_order_id": { "$ref": "#/components/schemas/FlakeId" }, "status": { "$ref": "#/components/schemas/SubscriptionChangeStatusDto" }, "proration_behavior": { "$ref": "#/components/schemas/ProrationBehaviorDto" }, "off_session": { "type": "boolean", "description": "Whether this change was initiated without active customer interaction." }, "prorated_amount": { "$ref": "#/components/schemas/SubscriptionChangeProratedAmountDto" }, "created_at": { "type": "string", "format": "date-time" }, "applied_at": { "type": [ "null", "string" ], "format": "date-time" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionChangeLineDto" } }, "next_billing_amount": { "$ref": "#/components/schemas/SubscriptionChangeAmountDto" }, "next_billing_presentment_amount": { "$ref": "#/components/schemas/SubscriptionChangeAmountDto" } }, "additionalProperties": false, "description": "A pending or applied change to a subscription." }, "SubscriptionChangeLineAmountDto": { "required": [ "currency", "discount", "subtotal", "tax", "total" ], "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code in lowercase." }, "subtotal": { "type": "integer", "description": "Base amount before discounts or tax, in smallest currency units.", "format": "int64" }, "discount": { "type": "integer", "description": "Total discount applied, in smallest currency units.", "format": "int64" }, "tax": { "type": "integer", "description": "Tax amount, in smallest currency units.", "format": "int64" }, "total": { "type": "integer", "description": "Amount due after discounts and tax, in smallest currency units.", "format": "int64" } }, "additionalProperties": false, "description": "Pricing breakdown for a single subscription change line, in the smallest units of the given currency (e.g. cents)." }, "SubscriptionChangeLineDto": { "required": [ "amount", "id", "is_deleted", "presentment_amount", "price", "product", "prorated_amount", "prorated_presentment_amount", "remaining_minutes", "tax_inclusive", "total_minutes" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "subscription_line_id": { "$ref": "#/components/schemas/FlakeId" }, "is_deleted": { "type": "boolean", "description": "Whether this line is being removed by the change." }, "tax_inclusive": { "type": "boolean", "description": "Whether tax is included in the base price." }, "price": { "type": "integer", "description": "Base price in smallest settlement currency units.", "format": "int64" }, "product": { "$ref": "#/components/schemas/SubscriptionChangeLineProductDto" }, "amount": { "$ref": "#/components/schemas/SubscriptionChangeLineAmountDto" }, "presentment_amount": { "$ref": "#/components/schemas/SubscriptionChangeLineAmountDto" }, "prorated_amount": { "type": "integer", "description": "Prorated charge for this line in smallest settlement currency units.", "format": "int64" }, "prorated_presentment_amount": { "type": "integer", "description": "Prorated charge for this line in smallest presentment currency units.", "format": "int64" }, "remaining_minutes": { "type": "integer", "description": "Minutes remaining in the billing period at the time of change - used to calculate proration.", "format": "int64" }, "total_minutes": { "type": "integer", "description": "Total minutes in the billing period - used to calculate proration.", "format": "int64" } }, "additionalProperties": false, "description": "A single line item within a subscription change." }, "SubscriptionChangeLineProductDto": { "required": [ "custom_variables", "id", "name", "version_id" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "version_id": { "$ref": "#/components/schemas/FlakeId" }, "name": { "type": "string", "description": "Display name of the product." }, "image_url": { "type": [ "null", "string" ], "description": "URL of the product image, if set." }, "selected_gameserver_id": { "$ref": "#/components/schemas/FlakeId" }, "pricing_region_id": { "type": [ "null", "string" ], "description": "The pricing region used to determine the price, if applicable." }, "custom_variables": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CustomVariableLineItemDto" }, "description": "Custom variables set on this line item, keyed by variable identifier." } }, "additionalProperties": false, "description": "The product associated with a subscription change line." }, "SubscriptionChangeProratedAmountDto": { "required": [ "currency", "presentment_currency", "presentment_prorated_amount", "prorated_amount" ], "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 settlement currency code, in lowercase." }, "prorated_amount": { "type": "integer", "description": "Total prorated charge in smallest settlement currency units, including tax.", "format": "int64" }, "presentment_currency": { "type": "string", "description": "ISO 4217 presentment currency code, in lowercase." }, "presentment_prorated_amount": { "type": "integer", "description": "Total prorated charge in smallest presentment currency units, including tax.", "format": "int64" } }, "additionalProperties": false, "description": "The total prorated charge for a subscription change, expressed in both settlement and presentment currencies." }, "SubscriptionChangeStatusDto": { "enum": [ "invalid", "pending_payment", "pending_renewal", "applied", "canceled", "pending_verification" ], "type": "string", "description": "Represents the status of a subscription change.", "x-enumDescriptions": { "pending_payment": "The change is pending payment before it can be applied.", "pending_renewal": "The change will be applied at the next renewal.", "applied": "The change has been applied to the subscription.", "canceled": "The change was canceled and will not be applied.", "pending_verification": "The change requires a verification code sent to the customer's e-mail." } }, "SubscriptionStatusDto": { "enum": [ "invalid", "created", "active", "canceled" ], "type": "string", "description": "Represents the current state of a subscription.", "x-enumDescriptions": { "created": "The subscription has been created but is not yet active.", "active": "The subscription is currently active and will renew.", "canceled": "The subscription has been canceled and will no longer renew." } }, "TrustStoreRequirementDto": { "required": [ "category", "code", "created_at", "id", "metadata", "name", "requested_by", "restricts_capabilities", "status", "store_id", "submissions" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "template_id": { "type": [ "null", "string" ], "description": "Template ID if this requirement was created from a template. Null for ad-hoc requirements." }, "originating_flag_id": { "$ref": "#/components/schemas/FlakeId" }, "category": { "$ref": "#/components/schemas/StoreRequirementCategory" }, "code": { "type": "string", "description": "Unique code identifying the type of requirement. Copied from template or custom for ad-hoc requirements." }, "name": { "type": "string", "description": "Human-readable name of the requirement. Copied from template or custom for ad-hoc requirements." }, "description": { "type": [ "null", "string" ], "description": "Detailed description explaining what the store needs to provide. Copied from template or custom for ad-hoc requirements." }, "schema": { "type": "null", "description": "JSON schema defining the form fields, validation rules, and document requirements" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for this requirement (stored as JSON)" }, "status": { "$ref": "#/components/schemas/StoreRequirementStatus" }, "requested_by": { "$ref": "#/components/schemas/StoreRequirementActionParty" }, "requested_by_detail": { "type": [ "null", "string" ], "description": "Specifies the specific requester entity (e.g., \"stripe\", \"trolley\", or admin user ID)\nFree-form string for internal records" }, "created_at": { "type": "string", "description": "When this requirement was created", "format": "date-time" }, "updated_at": { "type": [ "null", "string" ], "description": "When this requirement was last updated", "format": "date-time" }, "deadline_at": { "type": [ "null", "string" ], "description": "When this requirement must be completed by (optional)", "format": "date-time" }, "submitted_at": { "type": [ "null", "string" ], "description": "When the store submitted their response to this requirement", "format": "date-time" }, "verified_at": { "type": [ "null", "string" ], "description": "When this requirement was verified and approved", "format": "date-time" }, "rejected_at": { "type": [ "null", "string" ], "description": "When this requirement was rejected for not meeting standards", "format": "date-time" }, "restricts_capabilities": { "type": "array", "items": { "type": "string" }, "description": "Store capabilities that are restricted until this requirement is satisfied" }, "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/TrustStoreRequirementSubmissionDto" }, "description": "Associated submissions for this requriement." } }, "additionalProperties": false }, "TrustStoreRequirementSubmissionDto": { "required": [ "id", "store_id", "store_requirement_field_id", "store_requirement_id", "submitted_at", "submitted_by" ], "type": "object", "properties": { "id": { "$ref": "#/components/schemas/FlakeId" }, "store_id": { "$ref": "#/components/schemas/FlakeId" }, "store_requirement_id": { "$ref": "#/components/schemas/FlakeId" }, "store_requirement_field_id": { "type": "string", "description": "The identifier of the specific field within the store requirement." }, "text_value": { "type": [ "null", "string" ], "description": "The text value submitted for this field, if applicable." }, "file_id": { "type": [ "null", "string" ], "description": "The identifier of the uploaded file, if a file was submitted." }, "file_name": { "type": [ "null", "string" ], "description": "The original name of the uploaded file." }, "file_content_type": { "type": [ "null", "string" ], "description": "The MIME content type of the uploaded file." }, "file_size_bytes": { "type": [ "null", "integer" ], "description": "The size of the uploaded file in bytes.", "format": "int64" }, "submitted_at": { "type": "string", "description": "The timestamp when this submission was made.", "format": "date-time" }, "submitted_by": { "$ref": "#/components/schemas/ActorDto" }, "submitted_by_ip_address": { "type": [ "null", "string" ], "description": "The IP address from which the submission was made." }, "submitted_by_user_agent": { "type": [ "null", "string" ], "description": "The user agent string of the client that made the submission." } }, "additionalProperties": false }, "UpdateSubscriptionResponseDto": { "required": [ "subscription_change" ], "type": "object", "properties": { "subscription_change": { "$ref": "#/components/schemas/SubscriptionChangeDto" }, "pending_payment": { "$ref": "#/components/schemas/CheckoutPaymentInfoDto" } }, "additionalProperties": false, "description": "Response returned after a subscription change is initiated." }, "UpdateSubscriptionTierRequestDto": { "required": [ "target_product_id" ], "type": "object", "properties": { "target_product_id": { "$ref": "#/components/schemas/FlakeId" }, "verification_code": { "type": [ "null", "string" ], "description": "A verification code sent to the customer's subscription billing e-mail.\nPass this if the `status` field on the `subscription_change` object equals `pending_verification`." } }, "additionalProperties": false }, "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." } }, "securitySchemes": { "APIKey": { "type": "apiKey", "description": "An API Key token generated in the Dashboard in the format 'APIKey TOKEN_HERE'.", "name": "Authorization", "in": "header", "x-gitbook-prefix": "APIKey", "x-gitbook-token-placeholder": "TOKEN_HERE" }, "Customer": { "type": "apiKey", "description": "A Customer token generated using an API Key in the format 'Customer TOKEN_HERE'.", "name": "Authorization", "in": "header", "x-gitbook-prefix": "Customer", "x-gitbook-token-placeholder": "TOKEN_HERE" } } }, "tags": [ { "name": "cart" }, { "name": "checkout" }, { "name": "customer" }, { "name": "delivery" }, { "name": "discord" }, { "name": "navlinks" }, { "name": "orders" }, { "name": "products" }, { "name": "store" }, { "name": "subscriptions" }, { "name": "tags" }, { "name": "tier-groups" } ] }