> ## 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.

# Update sample request

> Reports progress on a sample request: approve or reject it, mark it shipped or delivered, and save your order id, order number and tracking link.

Reports what happened to a sample request after you fulfill it: mark it shipped or delivered and save your order details. Each status change sends the matching [webhook event](https://growi.mintlify.site/essentials/custom-store-samples.md#webhook-events).

> [!NOTE]
>
> Requires a full-access API key (read-only keys are rejected).

## Path parameters

| Parameter | Type | Description | Required |
| - | - | - | - |
| `id` | Integer | Sample request id | Yes |

## Body parameters

| Parameter | Type | Description | Required |
| - | - | - | - |
| `status` | String | `approved`, `rejected`, `shipped` or `delivered` | No |
| `order_id` | String | Your order id | No |
| `order_name` | String | Your order number | No |
| `tracking_url` | String | Tracking link for the package | No |

Allowed status changes:

| From | To |
| - | - |
| `pending` | `approved`, `rejected` |
| `approved` | `shipped`, `delivered` |
| `shipped` | `shipped`, `delivered` |

Send only `order_id`, `order_name` or `tracking_url` to update them without changing the status.

## Request example

```bash theme={"dark"}
curl -X PATCH "https://api.growi.io/api/public/v1/sample_requests/812345" \
  -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "shipped",
    "order_id": "FB-100231",
    "order_name": "#100231",
    "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }'
```

## Response

Returns the updated sample request in `data`. See [List sample requests](https://growi.mintlify.site/api-reference/endpoint/list-sample-requests.md) for the fields.

## Error responses

**403: read-only API key**

```json theme={"dark"}
{ "error": "This API key is read-only and cannot modify data." }
```

**404: not found for your organization**

```json theme={"dark"}
{ "error": "Sample request not found" }
```

**422: invalid status or transition**

```json theme={"dark"}
{ "error": "Cannot mark a pending sample request as shipped" }
```


## OpenAPI

````yaml PATCH /sample_requests/{id}
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/{id}:
    patch:
      summary: Update Sample Request
      description: >-
        Reports progress on a sample request: approve or reject it, mark it
        shipped or delivered, and save your order id, order number and tracking
        link.
      parameters:
        - name: id
          in: path
          required: true
          description: Sample request id
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - approved
                    - rejected
                    - shipped
                    - delivered
                  description: >-
                    approved and rejected need a pending request; shipped needs
                    an approved one; delivered needs an approved or shipped one
                order_id:
                  type: string
                  description: Your order id
                order_name:
                  type: string
                  description: Your order number
                tracking_url:
                  type: string
                  description: Tracking link for the creator
      responses:
        '200':
          description: Sample request updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SampleRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Read-only API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Sample request not found for your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid status or transition
          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.