# Gifts

> The products you sent to hosts, where each gift stands, the store order behind it, and the feedback the host wrote after using it.

- Audience: API
- Page type: reference
- Updated: 2026-10-08
- Canonical URL: https://www.rendezvu.co/docs/api/gifts

A gift moves from `DRAFT` to `PENDING` when you send it, `ACCEPTED` when the host says yes, `SHIPPED` when it leaves your warehouse and `COMPLETE` when it is done. The host's feedback arrives once they have used the product.

Shipping addresses, phone numbers, emails and tracking numbers are never returned. A tracking number leads to a delivery address, so it stays in the console with the rest.

Needs the `gifts:read` scope and a plan that includes Gifting.

## List gifts

`GET /api/brand/v1/gifts`

Product gifts you sent to hosts, newest first: where each one stands, the store order behind it, and the feedback the host wrote. Shipping addresses, phone numbers and tracking numbers are never returned.

Scope: `gifts:read`. Plan feature: Gifting. Paginated.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `page` | integer, optional, default `1` | The page to return, starting at 1. At most 10,000. |
| `per_page` | integer, optional, default `25` | Items per page, between 1 and 100. |
| `status` | enum, optional | Only gifts in this state. Archived gifts are returned only when you ask for ARCHIVED. One of: `DRAFT`, `PENDING`, `ACCEPTED`, `SHIPPED`, `COMPLETE`, `ARCHIVED`. |

**Returns**

A page of gifts. `data` is an array of objects with these attributes, and the body carries `pagination`.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | string | The gift id. |
| `status` | enum | DRAFT, PENDING, ACCEPTED, SHIPPED, COMPLETE or ARCHIVED. |
| `product` | object | What you sent. |
| `product.name` | string | Product name. |
| `product.description` | string, nullable | Product description. |
| `product.url` | string, nullable | Product page. |
| `host` | object, nullable | Who you sent it to. |
| `host.id` | string | The host’s Rendezvu user id (UUID). |
| `host.username` | string, nullable | The host’s handle, as in rendezvu.co/username. |
| `host.first_name` | string, nullable | First name. |
| `host.last_name` | string, nullable | Last name. |
| `host.profile_photo` | string, nullable | URL of the host’s profile photo. |
| `opportunity` | object, nullable | The campaign the gift belongs to, if any. |
| `opportunity.id` | string | Opportunity id. |
| `opportunity.title` | string, nullable | Campaign title. |
| `shipment` | object | The store order Rendezvu placed for the gift, when there is one. |
| `shipment.store_order_state` | string, nullable | not_applicable, needs_variant, queued, draft_created, placed, fulfilled, failed or cancelled. |
| `shipment.store_order_name` | string, nullable | The order name in your store. |
| `shipment.store_order_placed_at` | timestamp, nullable | When the order was placed. |
| `feedback` | string, nullable | The host’s review of the product, written to you. |
| `feedback_submitted_at` | timestamp, nullable | When the host wrote it. |
| `created_at` | timestamp | When the gift was created. |
| `accepted_at` | timestamp, nullable | When the host accepted. |
| `shipped_at` | timestamp, nullable | When it shipped. |
| `completed_at` | timestamp, nullable | When it was marked complete. |
| `archived_at` | timestamp, nullable | When it was archived. |

**Example request**

```bash
curl 'https://api.rendezvu.co/api/brand/v1/gifts?status=SHIPPED&per_page=1' \
  -H "Authorization: Bearer $RENDEZVU_BRAND_API_KEY"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "status": "SHIPPED",
      "product": {
        "name": "Ridgeline 30L Pack",
        "description": "A 30 liter fastpack for long days.",
        "url": "https://northforkgear.com/products/ridgeline-30"
      },
      "host": {
        "id": "b2e4d6f8-1a3c-4e5f-8b7d-9c0e1f2a3b4c",
        "username": "sam.on.granite",
        "first_name": "Sam",
        "last_name": "Okafor",
        "profile_photo": null
      },
      "opportunity": {
        "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "title": "Fall trail series"
      },
      "shipment": {
        "store_order_state": "placed",
        "store_order_name": "#10477",
        "store_order_placed_at": "2026-09-20T13:00:00.000Z"
      },
      "feedback": null,
      "feedback_submitted_at": null,
      "created_at": "2026-09-19T08:45:00.000Z",
      "accepted_at": "2026-09-19T19:02:00.000Z",
      "shipped_at": "2026-09-21T15:30:00.000Z",
      "completed_at": null,
      "archived_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 1,
    "total_items": 6,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  },
  "_timing": {
    "duration_ms": 42
  }
}
```

## Related

- [Opportunities](https://www.rendezvu.co/docs/api/opportunities.md): Your campaigns with their briefs, compensation, deliverables and every host assignment, so you can track a program from your own systems.

---

Source: https://www.rendezvu.co/docs/api/gifts (Rendezvu docs, Markdown view). Every page: https://www.rendezvu.co/llms.txt