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

# Quick Start: Make Your First Mutasib API Call in Minutes

> Generate an API token, create a shop, add your first product, and record a sale — all through the Mutasib REST API.

This guide walks you through the essential steps to go from zero to a working Mutasib integration. By the end you will have an API token, a product in your shop's catalog, and your first recorded sale.

<Note>
  API tokens are not available on a free trial. An active paid plan is required to create and use them. Shops themselves are created and administered from the [Mutasib dashboard](https://mutasib.com/dashboard); the API operates on an existing shop.
</Note>

<Steps>
  <Step title="Generate an API token">
    Sign in to your [Mutasib dashboard](https://mutasib.com/dashboard) and create a new API token. Choose an expiration of 30, 60, or 90 days, then copy the token immediately, it is shown only once at creation time. Store it in a secure secret store such as an environment variable or a secrets manager. You can revoke the token anytime from the dashboard.

    Pass the token in the `Authorization` header on every request:

    ```text theme={null}
    Authorization: Bearer YOUR_API_TOKEN
    ```
  </Step>

  <Step title="Get your shop details">
    Look up your shop by ID to confirm the token works and grab any details you need.

    ```bash theme={null}
    curl https://api.mutasib.com/api/v1/shops/42 \
      -H "Authorization: Bearer YOUR_API_TOKEN"
    ```

    Replace `42` with your own shop ID (visible in the dashboard).
  </Step>

  <Step title="Add a product">
    Add your first product to the shop's catalog.

    ```bash theme={null}
    curl -X POST https://api.mutasib.com/api/v1/shops/42/products/ \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -d '{
        "name": "Organic Apples (1 kg)",
        "price": 12.50,
        "stock": 200
      }'
    ```

    ```json theme={null}
    {
      "id": 301,
      "shop_id": 42,
      "name": "Organic Apples (1 kg)",
      "price": "12.50",
      "stock": 200,
      "is_active": true,
      "created_at": "2024-11-01T10:05:00Z",
      "updated_at": "2024-11-01T10:05:00Z"
    }
    ```

    Note the `id` of the product — you need it in the next step.
  </Step>

  <Step title="Record a sale">
    Record a point-of-sale transaction by posting to the shop's sales endpoint. Pass an array of `items`, each with a `product_id` and `quantity`. Mutasib automatically decrements stock and issues a receipt token.

    ```bash theme={null}
    curl -X POST https://api.mutasib.com/api/v1/shops/42/sales/ \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -d '{
        "items": [
          { "product_id": 301, "quantity": 3 }
        ]
      }'
    ```

    ```json theme={null}
    {
      "id": 5001,
      "shop_id": 42,
      "total": "37.50",
      "receipt_token": "rcpt_a1b2c3d4e5f6",
      "items": [
        {
          "product_id": 301,
          "product_name": "Organic Apples (1 kg)",
          "quantity": 3,
          "unit_price": "12.50",
          "subtotal": "37.50"
        }
      ],
      "created_at": "2024-11-01T10:10:00Z"
    }
    ```

    The `receipt_token` uniquely identifies the transaction and can be used to fetch a shareable receipt via the [Public API](/api/public/overview).
  </Step>
</Steps>

<Tip>
  Store your API token in environment variables or a secrets manager. Never hard-code it in your source code or commit it to version control. If a token is compromised, revoke it from the dashboard and generate a new one.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Review the API token scope, allowlist, and error codes.
  </Card>

  <Card title="Shops API" icon="store" href="/api/shops/overview">
    Read and update your shop's details and settings.
  </Card>

  <Card title="Products API" icon="box" href="/api/products/overview">
    Create, list, update, and manage your product catalog.
  </Card>

  <Card title="Sales API" icon="receipt" href="/api/sales/overview">
    Record transactions, list sales history, and fetch daily totals.
  </Card>
</CardGroup>