---
title: "List reward fulfillments"
method: GET
path: "/reward_fulfillments"
tags: ["Reward Fulfillments"]
---

# List reward fulfillments

`GET /reward_fulfillments`

## Request

- Base URL: `https://api.smile.io/v1`
- URL: `https://api.smile.io/v1/reward_fulfillments`
- Auth: HTTP bearer

Retrieves a list of reward fulfillments.

## Query parameters

- `customer_id` integer: Filter results to only reward fulfillments with the provided Smile customer ID.
- `fulfillment_status` 'pending' | 'issued' | 'cancelled' | 'failed': Filter results to only reward fulfillments whose fulfillment status matches the provided value.
- `usage_status` 'used' | 'unused' | 'untracked': Filter results to only reward fulfillments whose usage status matches the provided values.
- `updated_at_min` string, date-time: Filter results to only reward fulfillments updated after the provided date and time.
- `limit` integer: The maximum number of reward fulfillments to retrieve.
- `cursor` string: Cursor for the page of reward fulfillments to retrieve.

## Response `200`

- object
  - `reward_fulfillments` RewardFulfillment[]
    - `id` integer: Unique identifier for the reward fulfillment.
    - `name` string: The name of the reward fulfillment.
    - `code` string: A unique code for the customer to use or apply the reward fulfillment. This is commonly a discount code the customer applies at checkout on their next order, but it can be a unique code they use for other purposes like accessing an exclusive page on the merchant's website.
    - `customer_id` integer: The ID of the customer that the reward fulfillment belongs to.
    - `fulfillment_status` 'pending' | 'issued' | 'cancelled' | 'failed': The fulfillment status of the reward fulfillment, indicating whether the reward is available to the customer.
    - `image_url` string: An image for the reward fulfillment.
    - `action_text` string, nullable: A short call-to-action style text, appropriate for use in buttons or links, guiding the customer on how to use the reward fulfillment. This field may be blank
    - `action_url` string, nullable: A URL destination guiding the customer on how to use the reward, often paired with the `action_text` for use in buttons or links. This field may be blank.
    - `usage_instructions` string, nullable: A description of how the customer can use or apply the reward fulfillment.
    - `terms_and_conditions` string, nullable: A description of the reward fulfillment's limitations or restrictions. When the reward is a discount code, this commonly includes expiry date, minimum order amounts, or applicability to specific product collections.
    - `expires_at` string, date-time, nullable: The date and time when the reward fulfillment expires. When the reward is a discount code, this refers to the expiry date of the discount, and a `null` value indicates that the discount code does not expire.
    - `usage_status` 'used' | 'unused' | 'untracked': The usage status of the reward fulfillment, indicating whether the generated reward has been used by the customer.
    - `used_at` string, date-time, nullable: The date and time when the reward fulfillment was used by the customer. If the reward fulfillments does not support usage tracking, this field may be `null` even after the reward fulfillment has been used.
    - `created_at` string, date-time: The date and time when the reward fulfillment was created.
    - `updated_at` string, date-time: The date and time when the reward fulfillment was last updated.
  - `metadata` PaginationMetadata
    - `next_cursor` string, nullable: A cursor value that when present, can be used to retrieve the next page of results.
    - `previous_cursor` string, nullable: A cursor value that when present, can be used to retrieve the previous page of results.

---

[API](https://skmtc.dev/smile/apis/smile-io-rest-api.md) - [All operations](https://skmtc.dev/smile/apis/smile-io-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smile/apis/smile-io-rest-api/revisions/d395a9f2b730?raw)