> For the complete documentation index, see [llms.txt](https://guides.paynow.gg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.paynow.gg/integrations-and-commands/storefront-api-notes.md).

# API Behaviour Notes

The [API reference](https://docs.paynow.gg) documents every endpoint and schema. This page is the handful of behaviours around them that support gets asked about, collected in one place.

## Products must exist before checkout

API checkouts sell **pre-defined products**: everything you offer through a checkout has to be created in the dashboard (or via the Management API) first, then referenced by `product_id` in the checkout's `lines`.

Defining a product inline at checkout time is not part of the standard platform. If your volume is large enough that per-checkout products are genuinely necessary, that is an enterprise conversation with PayNow rather than an API flag.

## Mixing one-time and subscription lines

A single checkout can contain both one-time products and subscription products. Older templates and integrations sometimes assume one type per checkout; that restriction no longer applies.

## Active delivery items only show enqueued deliveries

The active delivery-items endpoint lists items with a **command attempt enqueued** — a delivery routed to a game server. A customer's product that has no command attempt attached will not appear there, even though the customer owns it. If you are reconciling ownership rather than deliveries, read the customer's inventory instead.

## Building PayNow into an existing storefront

If you have integrated a checkout API before (Stripe Checkout is the closest comparison), the shape is familiar: create your products, create a checkout session with `lines`, redirect the customer to the returned `url`. The [Delivery Methods](/integrations-and-commands/delivery-methods.md) page covers what your store must have configured before any of it can deliver.

## Finding the affiliate behind an order

The `ON_ORDER_COMPLETED` webhook does not carry the affiliate code itself — it carries the **affiliate link ID**. The working pattern:

1. Receive the order-completed webhook.
2. Fetch the full order via the Management API; it includes the affiliate link ID when the order came through an affiliate.
3. Look the link up with [`GET /v1/stores/{storeId}/affiliate-links/{affiliateLinkId}`](https://docs.paynow.gg/management/management-api/affiliate-links) to get the code and its owner.

That resolves the code to whatever you need — crediting the affiliate, or granting an in-game reward to the buyer who used it.

## Which API is safe to expose

The split matters more than any other security advice here:

* The **Storefront (headless) API** is designed to be called from customer-facing code. Prices, products and checkout creation are validated server-side by PayNow — a customer editing your page cannot change what an order costs.
* The **Management API** is never safe client-side. Its key grants control of the store; it belongs on your backend only, and anything your frontend needs from it should go through your own server.

PayNow does not review or pentest your integration code. If you are building beyond the storefront API and are unsure, that is a job for a developer with security experience, before launch rather than after.