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

# List Stores

> Learn how to list all stores registered in the Cabra API using the endpoint GET /stores.

## 🏬 List Stores

This endpoint allows you to **list all stores associated** with your account.

Stores are returned in `position` order (ascending).

It is ideal for:

* Displaying stores in administrative panels
* Integrating data with other systems
* Automating store queries

## 🔐 Authentication

This route **requires authentication** via **API Key**, sent in the request header:

```http theme={null}
Authorization: YOUR_API_KEY_HERE
```

## 📋 Example Request

```bash theme={null}
curl --location "https://api.cabrapi.com.br/v1/stores?page=1&limit=20" --header "Authorization: YOUR_API_KEY_HERE"
```

## 📊 Example Response (200)

```json theme={null}
{
  "code": "SUCCESS",
  "stores": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "teste",
      "position": 1,
      "description": "Loja de teste",
      "image": "https://example.com/image.png",
      "domain": "dominio.exemplo.com",
      "template": "PERSONALIZADO",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "createdAt": "2000-02-23T15:17:23.064Z",
      "updatedAt": "2000-02-23T15:17:50.527Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "nextCursor": null,
    "hasMore": false
  }
}
```

> The first call (without `cursor`) already returns `nextCursor` and `hasMore` in the pagination, allowing cursor pagination to start without extra calls.

## 📌 Parameters

### Query params

| Parameter | Type | Required | Description |
| - | - | - | - |
| `page` | number | No | Current page (default: `1`) |
| `limit` | number | No | Items per page (default: `20`, max: `100`) |
| `cursor` | string | No | Opaque cursor for cursor-based pagination. Use the `nextCursor` from the previous response. Cannot be used together with `page` |

If there are no stores on the queried page, `stores` is returned as an empty array.

### 🔄 Cursor pagination

For large lists (more than \~100 items), prefer **cursor** pagination instead of `page`:

1. Make the first call **without** `cursor`.
2. If `hasMore` is `true`, the response includes the `nextCursor` field.
3. Send that `nextCursor` in the `cursor` parameter of the next request to fetch the next page.

```bash theme={null}
curl --location "https://api.cabrapi.com.br/v1/stores?cursor=v1:YOUR_CURSOR_HERE&limit=20" --header "Authorization: YOUR_API_KEY_HERE"
```

In cursor mode, pagination is returned only with `nextCursor`, `hasMore` and `limit`:

```json theme={null}
{
  "code": "SUCCESS",
  "stores": [],
  "pagination": {
    "nextCursor": "v1:e2xFn...",
    "hasMore": true,
    "limit": 20
  }
}
```

* `cursor` and `page` **cannot** be used together (`400 INVALID_PAGINATION`).
* `nextCursor: null` with `hasMore: false` indicate the end of the list (the API responds `200` with an empty array).

## ⚠️ Possible errors

* `400 INVALID_PAGINATION_LIMIT` → `limit` outside the allowed range (`1` to `100`)
* `400 INVALID_PAGINATION_PAGE` → invalid `page`
* `400 INVALID_PAGINATION_CURSOR` → invalid or malformed `cursor`
* `400 INVALID_PAGINATION` → `page` and `cursor` used together
* `401 API_KEY_NOT_PROVIDED` → `Authorization` header not sent
* `401 INVALID_API_KEY` → invalid or not found API Key
* `401 UNAUTHENTICATED` → session/user not authenticated
* `403 USER_DISABLED` → user account disabled or deleted
* `403 NO_ACTIVE_SUBSCRIPTION` → account has no active plan
* `429 RATE_LIMIT_EXCEEDED` → plan per-minute request limit exceeded
* `500 INTERNAL_SERVER_ERROR` → internal error
* `503 SERVICE_UNAVAILABLE` → service temporarily unavailable

## 🔗 Useful Links

* [Authentication Documentation](https://docs.cabrapi.com.br/pages/en/api-reference/authorization.md)
* [Get Store by ID](https://docs.cabrapi.com.br/pages/en/api-reference/store/get-by-id.md)
* [Create Store](https://docs.cabrapi.com.br/pages/en/api-reference/store/post.md)
* [Update Store](https://docs.cabrapi.com.br/pages/en/api-reference/store/put.md)
* [Delete Store](https://docs.cabrapi.com.br/pages/en/api-reference/store/delete.md)

Update: 23/05/2024 as 13:00


## OpenAPI

````yaml GET /stores
openapi: 3.1.0
info:
  title: caBRAPI
  version: 1.0.0
servers:
  - url: https://api.cabrapi.com.br/v1
security: []
paths:
  /stores:
    get:
      tags:
        - Stores
      summary: List stores
      operationId: listStores
      parameters:
        - in: query
          name: page
          schema:
            default: 1
            minimum: 1
            type: integer
        - in: query
          name: limit
          schema:
            default: 20
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque cursor from previous page (do not combine with page).
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  code:
                    example: SUCCESS
                    type: string
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  stores:
                    items:
                      $ref: '#/components/schemas/Store'
                    type: array
                required:
                  - code
                  - stores
                  - pagination
                type: object
          description: Owner stores list ordered by position.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: >-
            INVALID_PAGINATION, INVALID_PAGINATION_LIMIT,
            INVALID_PAGINATION_PAGE, INVALID_PAGINATION_CURSOR
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: USER_DISABLED, NO_ACTIVE_SUBSCRIPTION
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Rate limit exceeded.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Service unavailable.
      security:
        - ApiKey: []
components:
  schemas:
    Pagination:
      properties:
        hasMore:
          type: boolean
        limit:
          type: integer
        nextCursor:
          nullable: true
          type: string
        page:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer
      type: object
    Store:
      properties:
        createdAt:
          format: date-time
          type: string
        description:
          nullable: true
          type: string
        domain:
          nullable: true
          type: string
        id:
          format: uuid
          type: string
        image:
          nullable: true
          type: string
        metadata:
          nullable: true
          type: object
        name:
          type: string
        position:
          type: integer
        template:
          enum:
            - PERSONALIZADO
            - N/A
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - id
        - name
        - position
        - template
        - createdAt
        - updatedAt
      type: object
    Error:
      properties:
        code:
          example: STORE_NOT_FOUND
          type: string
      required:
        - code
      type: object
  securitySchemes:
    ApiKey:
      in: header
      name: Authorization
      type: apiKey
      x-default: YOUR_API_KEY_HERE

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.