> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Make your first API call in under 2 minutes

<Info>
  This page is the **generic Dev API quickstart**.

  If your real goal is:

  * **theme editing with AI** -> start with [Build and Customize a Theme with AI](/themes/build-and-customize-with-ai)
  * **theme automation endpoints** -> read [Editing Themes](/themes/editing)

  This page is best when you want your first normal `/dev/v1/*` request.
</Info>

<Info>
  If you prefer an official SDK instead of raw `fetch` or `requests`, start with [SDKs & Libraries](/api-reference/sdks) — we have packages for Node.js/Bun (`@shoppexio/sdk`), Python (`shoppexio`), and PHP (`shoppexio/shoppex-php`).
</Info>

<Steps>
  <Step title="Get Your API Key">
    1. Log in to [dashboard.shoppex.io](https://dashboard.shoppex.io)
    2. Go to **Settings → API Keys**
    3. Click **Generate New Key**
    4. Copy the key (starts with `shx_`)

    <Warning>
      API keys are shown only once. Store it securely before closing the dialog.
    </Warning>
  </Step>

  <Step title="Make Your First Request">
    Let's fetch your shop information to verify everything works:

    <CodeGroup>
      ```bash cURL theme={"system"}
      curl https://api.shoppex.io/dev/v1/me \
        -H "Authorization: Bearer shx_your_api_key"
      ```

      ```typescript TypeScript theme={"system"}
      const response = await fetch('https://api.shoppex.io/dev/v1/me', {
        headers: {
          'Authorization': 'Bearer shx_your_api_key'
        }
      });

      const { data } = await response.json();
      console.log(data.name); // Your shop name
      ```

      ```python Python theme={"system"}
      import requests

      response = requests.get(
          'https://api.shoppex.io/dev/v1/me',
          headers={'Authorization': 'Bearer shx_your_api_key'}
      )

      data = response.json()['data']
      print(data['name'])  # Your shop name
      ```

      ```typescript JS SDK theme={"system"}
      import { ShoppexClient } from '@shoppexio/sdk';

      const client = new ShoppexClient({
        apiKey: process.env.SHOPPEX_API_KEY!,
      });

      const me = await client.me.get();
      console.log(me.data?.name);
      ```

      ```python Python SDK theme={"system"}
      from shoppexio import ShoppexClient

      client = ShoppexClient(api_key='shx_your_api_key')
      me = client.me.get()
      print(me.data.name)
      ```
    </CodeGroup>

    **Response:**

    ```json theme={"system"}
    {
      "data": {
        "id": 12345,
        "name": "My Awesome Shop",
        "currency": "USD",
        "created_at": 1704067200
      }
    }
    ```
  </Step>

  <Step title="Create a Payment">
    Now let's create a payment link:

    <CodeGroup>
      ```bash cURL theme={"system"}
      curl -X POST https://api.shoppex.io/dev/v1/payments \
        -H "Authorization: Bearer shx_your_api_key" \
        -H "Content-Type: application/json" \
        -H "Idempotency-Key: payment-create-order-123" \
        -d '{
          "title": "Order #123",
          "email": "customer@example.com",
          "value": 29.99,
          "currency": "USD"
        }'
      ```

      ```typescript TypeScript theme={"system"}
      const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer shx_your_api_key',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          title: 'Order #123',
          email: 'customer@example.com',
          value: 29.99,
          currency: 'USD'
        })
      });

      const { data } = await response.json();
      console.log(data.url); // Checkout URL
      ```

      ```python Python theme={"system"}
      import requests

      response = requests.post(
          'https://api.shoppex.io/dev/v1/payments',
          headers={
              'Authorization': 'Bearer shx_your_api_key',
              'Content-Type': 'application/json'
          },
          json={
              'title': 'Order #123',
              'email': 'customer@example.com',
              'value': 29.99,
              'currency': 'USD'
          }
      )

      data = response.json()['data']
      print(data['url'])  # Checkout URL
      ```

      ```typescript JS SDK theme={"system"}
      import { ShoppexClient } from '@shoppexio/sdk';

      const client = new ShoppexClient({
        apiKey: process.env.SHOPPEX_API_KEY!,
      });

      const payment = await client.payments.create({
        title: 'Order #123',
        email: 'customer@example.com',
        value: 29.99,
        currency: 'USD',
      });

      console.log(payment.data?.url);
      ```

      ```python Python SDK theme={"system"}
      from shoppexio import ShoppexClient

      client = ShoppexClient(api_key='shx_your_api_key')
      payment = client.payments.create({
          'title': 'Order #123',
          'email': 'customer@example.com',
          'value': 29.99,
          'currency': 'USD',
      })

      print(payment.data.url)
      ```
    </CodeGroup>

    **Response:**

    ```json theme={"system"}
    {
      "data": {
        "uniqid": "abc123def456...",
        "url": "https://checkout.shoppex.io/invoice/abc123def456...",
        "url_branded": "https://checkout.shoppex.io/invoice/abc123def456...?shop=12345",
        "total": 29.99,
        "currency": "USD",
        "status": "PENDING",
        "created_at": 1704067200
      }
    }
    ```

    Redirect your customer to the `url` to complete payment.

    <Info>
      `POST /payments` creates a generic developer payment — it does not trigger Shoppex product fulfillment. Use it when you want a payable invoice or hosted checkout URL. Use `POST /orders` instead when you need Shoppex product line items, delivery, and automatic fulfillment.
    </Info>

    If you force `gateway: "PANDABASE"`, the response can also include:

    * `checkout_url`: the direct Pandabase checkout session URL
    * `session_id`: the Pandabase session reference stored by Shoppex for automatic webhook reconciliation

    If you want hosted checkout to open directly on a concrete crypto coin or network, use a merchant crypto provider together with `crypto_gateway`.

    Simple example:

    ```json theme={"system"}
    {
      "gateway": "OXAPAY",
      "crypto_gateway": "TRON"
    }
    ```

    That returns a `url` like:

    ```text theme={"system"}
    https://checkout.shoppex.io/invoice/abc123def456...?selected_gateway=TRON&auto_start_gateway=1&auto_start_crypto=1
    ```
  </Step>

  <Step title="Handle the Result">
    After payment, Shoppex sends a webhook to your server:

    ```json theme={"system"}
    {
      "event": "order:paid",
      "data": {
        "uniqid": "inv_def456",
        "customer_email": "customer@example.com",
        "total": 29.99,
        "currency": "USD"
      }
    }
    ```

    <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
      Learn how to set up and verify webhooks
    </Card>

    <Card title="Dynamic Product Delivery" icon="bolt" href="/api-reference/webhooks/dynamic-delivery">
      Implement the fulfillment callback for `DYNAMIC` products
    </Card>
  </Step>
</Steps>

You just made your first API call and created a payment. From here, most developers either hook up webhooks for automated fulfillment or explore the full endpoint reference.

## Next Steps

<CardGroup cols={2}>
  <Card title="Theme Guide" icon="sparkles" href="/themes/build-and-customize-with-ai">
    Use this if your actual goal is AI-assisted theme editing, not generic API onboarding.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key security best practices
  </Card>

  <Card title="SDKs & Libraries" icon="box-open" href="/api-reference/sdks">
    Official JS, Python, and PHP SDKs for `/dev/v1/*`
  </Card>

  <Card title="Error Handling" icon="circle-exclamation" href="/api-reference/errors">
    Handle errors gracefully
  </Card>

  <Card title="Pagination" icon="list" href="/api-reference/pagination">
    Navigate large result sets
  </Card>

  <Card title="Full API Reference" icon="code" href="/api-reference/introduction">
    Explore all endpoints
  </Card>
</CardGroup>