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

# List sample requests

> Lists free sample requests that you fulfill yourself (stores without Shopify), newest first, across your organization's and child brands' campaigns.

Lists free sample requests that you fulfill yourself, newest first. These are requests from creators on campaigns whose store isn't on Shopify. See [Free samples for custom stores](https://growi.mintlify.site/essentials/custom-store-samples.md) for the full flow.

Requests on your child brands' campaigns are included.

## Query parameters

| Parameter | Type | Description | Required |
| - | - | - | - |
| `status` | String | Comma-separated: `pending`, `approved`, `shipped`, `delivered`, `rejected`, `cancelled` | No |
| `campaign_id` | Integer | Only requests on this campaign | No |
| `updated_since` | String | ISO-8601 timestamp. Only requests updated at or after this time, for incremental syncs | No |
| `page` | Integer | Page number (default `1`) | No |
| `per_page` | Integer | 1 to 100 (default `25`) | No |

## Request example

```bash theme={"dark"}
curl "https://api.growi.io/api/public/v1/sample_requests?status=approved" \
  -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

## Response example

```json theme={"dark"}
{
  "data": [
    {
      "id": 812345,
      "status": "approved",
      "campaign_id": 51812,
      "campaign_name": "Summer Creators",
      "campaign_affiliate_id": 4512345,
      "source": "creator_request",
      "creator": {
        "user_id": 45678,
        "name": "Jamie Rivera",
        "first_name": "Jamie",
        "last_name": "Rivera",
        "email": "jamie@example.com",
        "phone": "+15555550100"
      },
      "product": {
        "id": 501234,
        "title": "Pleated Air Filter 20x25x1 (4-Pack)",
        "sku": "AF-20251",
        "url": null,
        "image_url": "https://cdn.example.com/20x25x1.jpg",
        "shopify_id": null,
        "tik_tok_id": null,
        "amazon_product_id": null
      },
      "variant": {
        "id": 2801234,
        "title": "MERV 8",
        "display_name": "Pleated Air Filter 20x25x1 (4-Pack) - MERV 8",
        "sku": "AF-20251-M8",
        "external_id": null,
        "price": 109
      },
      "quantity": 1,
      "shipping_address": {
        "first_name": "Jamie",
        "last_name": "Rivera",
        "address_line_1": "100 Main St",
        "address_line_2": "Apt 4",
        "city": "Miami",
        "state": "FL",
        "postal_code": "33101",
        "country": "UNITED STATES",
        "phone": "+15555550100"
      },
      "order_id": null,
      "order_name": null,
      "tracking_url": null,
      "created_at": "2026-10-21T18:04:09Z",
      "updated_at": "2026-10-21T18:04:11Z"
    }
  ],
  "meta": { "row_count": 1, "page_count": 1, "current_page": 1, "per_page": 25 }
}
```

> [!NOTE]
>
> For creators who joined through the Growi marketplace, `email`, `phone`, `last_name` and `shipping_address` are `null` until the request is approved.

## Error responses

**401: missing or invalid API key**

```json theme={"dark"}
{ "error": "Not Authenticated" }
```

**422: invalid filter**

```json theme={"dark"}
{ "error": "updated_since must be an ISO-8601 timestamp" }
```


## OpenAPI

````yaml GET /sample_requests
openapi: 3.0.1
info:
  title: Growi API
  description: >-
    API documentation for Growi platform, showcasing the public tracking event
    endpoint
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.growi.io/api/public/v1
security:
  - bearerAuth: []
paths:
  /sample_requests:
    get:
      summary: List Sample Requests
      description: >-
        Lists free sample requests that you fulfill yourself (stores without
        Shopify), newest first, across your organization's and child brands'
        campaigns.
      parameters:
        - name: status
          in: query
          required: false
          description: >-
            Comma-separated statuses: pending, approved, shipped, delivered,
            rejected, cancelled
          schema:
            type: string
        - name: campaign_id
          in: query
          required: false
          schema:
            type: integer
        - name: updated_since
          in: query
          required: false
          description: ISO-8601 timestamp. Only requests updated at or after this time
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: 1 to 100
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Sample requests listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SampleRequest'
                  meta:
                    type: object
                    properties:
                      row_count:
                        type: integer
                      page_count:
                        type: integer
                      current_page:
                        type: integer
                      per_page:
                        type: integer
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid status or updated_since
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SampleRequest:
      type: object
      properties:
        id:
          type: integer
          description: Sample request id
        status:
          type: string
          enum:
            - pending
            - approved
            - shipped
            - delivered
            - completed
            - rejected
            - cancelled
        campaign_id:
          type: integer
        campaign_name:
          type: string
        campaign_affiliate_id:
          type: integer
          nullable: true
          description: The creator's campaign enrollment id
        source:
          type: string
          description: >-
            campaign_application (picked while applying), creator_request
            (requested after joining), or sample_program
        creator:
          type: object
          properties:
            user_id:
              type: integer
            name:
              type: string
            first_name:
              type: string
            last_name:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
            phone:
              type: string
              nullable: true
        product:
          type: object
          properties:
            id:
              type: integer
            title:
              type: string
              description: The product name the brand entered
            sku:
              type: string
              nullable: true
              description: The brand's product SKU
            url:
              type: string
              nullable: true
            image_url:
              type: string
              nullable: true
            shopify_id:
              type: string
              nullable: true
            tik_tok_id:
              type: string
              nullable: true
            amazon_product_id:
              type: string
              nullable: true
        variant:
          type: object
          nullable: true
          properties:
            id:
              type: integer
            title:
              type: string
              nullable: true
            display_name:
              type: string
              nullable: true
            sku:
              type: string
              nullable: true
              description: >-
                The brand's variant SKU. For a product without variants, the
                product SKU
            external_id:
              type: string
              nullable: true
              description: Null for brand sample products
            price:
              type: number
              nullable: true
        quantity:
          type: integer
          description: >-
            Units to ship: the quantity approved for the request, or the
            quantity the creator asked for
        shipping_address:
          type: object
          nullable: true
          description: >-
            Where to ship the sample. Null for a pending request from a
            marketplace creator.
          properties:
            first_name:
              type: string
              nullable: false
            last_name:
              type: string
              nullable: false
            address_line_1:
              type: string
              nullable: false
            address_line_2:
              type: string
              nullable: true
            city:
              type: string
              nullable: false
            state:
              type: string
              nullable: true
            postal_code:
              type: string
              nullable: false
            country:
              type: string
              nullable: false
            phone:
              type: string
              nullable: true
        order_id:
          type: string
          nullable: true
          description: Your order id, once reported
        order_name:
          type: string
          nullable: true
        tracking_url:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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