# Build your own integration

Choose how your customers discover, book and manage studio time. Podyx supplies the catalog, availability, prices, client records and payment state; your application decides how to bring those capabilities together.

## Start from what you know

There is no required order for the read capabilities. Start with a room, a service, a published Tour or an existing selection. Admission still requires a complete, valid selection and rechecks current studio policy.

| Your starting point | Capabilities to combine |
| --- | --- |
| A customer chooses a room | Catalog → physical availability windows → compatible service/setup/duration → eligible starts → quote |
| A customer chooses a service | Service offers → compatible setups → dates and eligible starts → quote |
| Your app already has a selection | Quote current selection → collect missing details → choose the applicable admission/payment capability |
| A customer has an existing booking | Current session → permitted reschedule, amendment, guest, add-on or cancellation capability |

These are examples of valid compositions, not a promise that operations work in arbitrary order. A quote does not reserve time, and a successful command does not establish every downstream outcome.

## Explore the capabilities

- [Access & permissions](/api/docs/guides/v2/access): backend credentials, visitor identity and studio authority.
- [Catalog & offers](/api/docs/guides/v2/catalog): discover buyable services, rooms, setups and add-ons.
- [Availability](/api/docs/guides/v2/availability): physical windows, eligible starts and local time.
- [Quotes & requirements](/api/docs/guides/v2/quotes): authoritative prices, missing inputs and required details.
- [Clients & identity](/api/docs/guides/v2/clients): studio association and explicit account activation.
- [Bookings & sessions](/api/docs/guides/v2/bookings): creation and the full post-booking lifecycle.
- [Payments & refunds](/api/docs/guides/v2/payments): native instructions, studio-collected money and refund obligations.
- [State & recovery](/api/docs/guides/v2/recovery): accepted commands, current resources and safe retries.

## Use the exact contract

The base URL is `https://app.podyx.com`. All v2 endpoints use the `/api/v2` prefix, so requests go to `https://app.podyx.com/api/v2/...`. Your backend supplies a studio API key. A configured test environment has its own base URL and synthetic resources; do not use production records for trial integrations.

Use the [complete reference](/api/docs) and [v2 OpenAPI](/api/openapi-v2.json) for exhaustive fields, permission requirements, responses and errors. The [v1 contract](/api/openapi.json) remains available for existing integrations. These guides focus on booking capabilities; the full reference also covers catalog administration, bundles and subscriptions.

Dollar-prefixed shell variables in examples stand for your securely configured values or IDs returned by Podyx. Angle-bracket values in JSON are placeholders, not valid IDs. Supply all studio-required details before admission. Amounts in examples illustrate a shape; use actual returned amounts and currency.

## Observe separate outcomes

Keep command acceptance, current booking state, payment settlement, staff approval, fulfillment and notification delivery distinct. Read the returned current resource after a write. Preserve request identities before sending, so an uncertain response can be recovered without another purchase or collection.

## Example

A room-first application can begin with physical windows before choosing a duration:

```sh
curl --get "https://app.podyx.com/api/v2/rooms/availability" \
  -H "Authorization: Bearer $PODYX_API_KEY" \
  --data-urlencode "room_id=$ROOM_ID" \
  --data-urlencode 'date=2026-11-02'
```

This read creates no hold. Add a duration and a compatible setup to ask for concrete eligible starts. A service-first application can instead begin with service offers and reach the same admission policy.