--- updatedAt: 2026-07-30T15:44:42.000Z agentTools: projectIndex: https://docs.partnerstack.com/llms.txt --- # List all rewards Returns a list of your rewards. The rewards are returned sorted by creation date by default, with the most recent rewards appearing first. > 📘 Pagination > > A cursor for use in pagination. `starting_after` is an item key that defines your place in the list. > > For instance, if you make a list request and receive 100 items, then the last item with `"key":"rwrd_f4Jmxb7LmvhERZ"`, can be used in your subsequent call as the parameter value to fetch the next page of results: `?starting_after=rwrd_f4Jmxb7LmvhERZ.` > > Click [here](https://docs.partnerstack.com/docs/partner-api#pagination) for more info about pagination. # OpenAPI definition ```json { "components": { "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "support@partnerstack.com", "name": "PartnerStack Support" }, "description": "PartnerStack Partner REST API.", "termsOfService": "https://docs.google.com/document/d/1o7pDmMsvetHTx2gwSSg2WBwbM2yZcvf-63-YIA_Qz2I/export?format=pdf", "title": "PartnerStack Partner API", "version": "2.0.0", "x-logo": { "altText": "PartnerStack Logo", "url": "https://assets.website-files.com/5bd09c4c2b661f4530a081c3/5bd86b2716e1ea314e5c2c05_rectangle%20-%20icon%20%2B%20text%20-%20purple.png" } }, "openapi": "3.0.2", "paths": { "/v2/rewards": { "get": { "description": "Returns a list of your rewards. The rewards are returned sorted by creation date by default, with the most recent rewards appearing first.", "parameters": [ { "description": "Company key in which the results are filtered by.", "example": "co_1234", "in": "query", "name": "company_key", "schema": { "type": "string" } }, { "description": "The payment status of the rewards", "example": "available", "in": "query", "name": "payment_status", "required": false, "schema": { "enum": [ "in_transit", "withdrawn", "paid_and_refunded", "available", "paid_externally", "expired", "failed", "merging" ], "type": "string" } }, { "description": "Applies a maximum epoch timestamp (ms) filter to the response `created_at`.", "example": 1538352000000, "in": "query", "name": "max_created", "schema": { "format": "int64", "type": "integer" } }, { "description": "Applies a minimum epoch timestamp (ms) filter to the response `created_at`.", "example": 1538062487765, "in": "query", "name": "min_created", "schema": { "format": "int64", "type": "integer" } }, { "description": "Reward key in which the results are filtered by. When provided, returns only the matching reward (or an empty list if not found).", "example": "rw_1234", "in": "query", "name": "reward_key", "schema": { "type": "string" } }, { "description": "The field in which the results are ordered by. A `-` prefix denotes that the results are in descending order.", "example": "-created_at", "in": "query", "name": "order_by", "required": false, "schema": { "enum": [ "-created_at", "created_at", "-amount", "amount", "-ready_at", "ready_at" ], "type": "string" } }, { "description": "Group key in which the results are filtered by", "example": "grup_123", "in": "query", "name": "group_key", "required": false, "schema": { "type": "string" } }, { "description": "PartnerStack internal customer key (`cus_*`) in which the results are filtered by", "example": "cus_123", "in": "query", "name": "customer_key", "required": false, "schema": { "type": "string" } }, { "description": "Customer external key in which the results are filtered by", "example": "ext_mock_customer_key_1234", "in": "query", "name": "customer_external_key", "required": false, "schema": { "type": "string" } }, { "description": "Invoice key in which the results are filtered by", "example": "invo_123", "in": "query", "name": "invoice_key", "required": false, "schema": { "type": "string" } }, { "description": "The status of the rewards", "example": "pending", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Flag if drip rewards should be included into the results", "example": "false", "in": "query", "name": "exclude_drip_rewards", "required": false, "schema": { "type": "string" } }, { "description": "Flag to hide rewards that have been archived", "example": "false", "in": "query", "name": "hide_archived_rewards", "required": false, "schema": { "type": "boolean" } }, { "description": "Flag if drip rewards returned have a line_id (invoice) attached or not", "example": "false", "in": "query", "name": "empty_line_id", "required": false, "schema": { "type": "boolean" } }, { "description": "Free keywords that will filter on the followingReward key, Customer name, Partner first name, Partner last name, Partner email, Partner key", "example": "rwrd_1234", "in": "query", "name": "keywords", "required": false, "schema": { "type": "string" } }, { "description": "Text that the description must contain", "example": "$5 for every sign up", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "Flag the returned results should have distinct descriptions or not", "example": "true", "in": "query", "name": "distinct_description", "required": false, "schema": { "type": "boolean" } }, { "description": "Flag the returned results should have distinct decline reasons or not", "example": "true", "in": "query", "name": "distinct_decline_reason", "required": false, "schema": { "type": "boolean" } }, { "description": "Text that the decline_reason must contain", "example": "Automated: On hold due to suspicious activity", "in": "query", "name": "decline_reason", "required": false, "schema": { "type": "string" } }, { "description": "Flag if the returned results should have only pending and approved rewards which do not have an associated payment line.", "example": "true", "in": "query", "name": "invoiceable", "required": false, "schema": { "type": "boolean" } }, { "description": "The currency of the rewards", "example": "USD", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Filter rewards by how they were created. Accepts a comma-separated list of values: `api_key`, `content_order`, `drip`, `import`, `manual`, `offer_trigger`, `mdf`.", "example": "offer_trigger,manual", "in": "query", "name": "creation_source", "required": false, "schema": { "type": "string" } }, { "description": "Drip key (`drip_*`) in which the results are filtered by. Returns only rewards generated from the given drip schedule.", "example": "drip_9ebOwdTywVFOFr", "in": "query", "name": "drip_key", "required": false, "schema": { "type": "string" } }, { "description": "A limit on the number of items to be returned. Limits can range between 1 and 250, and the default is 10.", "example": 10, "in": "query", "name": "limit", "schema": { "default": 10, "maximum": 250, "minimum": 1, "type": "integer" } }, { "description": "A cursor for use in pagination, `starting_after` takes in an item key and the subsequent call will return the following items in the list. This is mutually exclusive with `ending_before`.", "example": "key_8U5s1iH2Pd2a2p", "in": "query", "name": "starting_after", "schema": { "type": "string" } }, { "description": "A cursor for use in pagination, `ending_before` takes in an item key and the subsequent call will return the prior items in the list. This is mutually exclusive with `starting_after`.", "example": "key_sE1vd9uwep7XHg", "in": "query", "name": "ending_before", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "has_more": { "type": "boolean" }, "items": { "items": { "allOf": [ { "description": "Standard fields that are present on all database objects.", "properties": { "created_at": { "description": "Immutable Unix timestamp in milliseconds taken at time of creation", "example": 1574181282399, "format": "int64", "type": "integer" }, "key": { "description": "A unique identifier used to reference the object", "example": "co_a80cb515fe", "maxLength": 255, "type": "string" }, "updated_at": { "description": "Unix timestamp in milliseconds taken at time of last update", "example": 1574181282399, "format": "int64", "type": "integer" } }, "type": "object" }, { "allOf": [ { "description": "Reward is what you earn from companies on PartnerStack.", "properties": { "amount": { "description": "The amount of the reward in cents (USD).", "example": 1000, "maximum": 100000000, "nullable": true, "type": "integer" }, "created_by": { "description": "The user key or 'system' that created this reward.", "example": "user_9ebOwdTywVFOFr", "nullable": true, "type": "string" }, "created_by_name": { "description": "The full name of the user who created this reward, if applicable.", "example": "Jane Smith", "nullable": true, "type": "string" }, "creation_source": { "description": "The source that created this reward. Can be one of: `manual`, `offer_trigger`, `import`, `drip`, `api_key`, or `content_order`.", "example": "manual", "nullable": true, "type": "string" }, "currency": { "description": "The currency of the reward.", "example": "USD", "nullable": true, "type": "string" }, "decline_reason": { "description": "The reason the reward has been held or declined", "example": "Invalid reward", "nullable": true, "type": "string" }, "description": { "description": "The description that the company gives to the reward.", "example": "$30 earned for every transaction made by each customer", "nullable": true, "type": "string" }, "drip": { "description": "The drip associated with this reward, if the reward was generated from a drip schedule. Null when the reward is not a drip reward.", "nullable": true, "properties": { "created_at": { "description": "Epoch timestamp (ms) when the drip was created. This is the true creation date of the drip schedule, distinct from the reward's created_at which reflects when the drip commission becomes available.", "example": 1622733671000, "type": "integer" }, "key": { "description": "Unique key of this drip.", "example": "drip_9ebOwdTywVFOFr", "type": "string" } }, "type": "object" }, "reward_status": { "description": "The status of the reward. Can be one of: `hold`, `pending`, `approved`, `declined`, `paid`.", "example": "pending", "nullable": true, "type": "string" } }, "type": "object" }, { "description": "Reward is what you earn from companies on PartnerStack.", "properties": { "company": { "properties": { "id": { "description": "Unique id of this company.", "example": 1234567, "type": "integer" }, "key": { "description": "Unique key of this company.", "example": "comp_1234567", "type": "string" }, "name": { "description": "The name of this company.", "example": "Company", "type": "string" } }, "type": "object" }, "customer": { "nullable": true, "properties": { "created_at": { "description": "Immutable Unix timestamp in milliseconds taken at time of customer creation", "example": 1592944078600, "nullable": true, "type": "integer" }, "email": { "description": "The email of the customer.", "example": "cust@examle.com", "nullable": true, "type": "string" }, "key": { "description": "Unique key of this customer.", "example": "cus_1h1QBVUg03Ij69", "nullable": true, "type": "string" }, "name": { "description": "The name of the customer.", "example": "Adrian", "nullable": true, "type": "string" }, "shared_id": { "example": "twitter", "nullable": true, "type": "string" }, "sub_ids": { "example": [ "youtube" ], "items": { "type": "string" }, "nullable": true, "type": "array" }, "updated_at": { "description": "Immutable Unix timestamp in milliseconds taken at time of customer last update", "example": 1592944078600, "nullable": true, "type": "integer" } }, "type": "object" }, "partnership_key": { "description": "Unique key of this partnership.", "example": "part_1234567", "nullable": true, "type": "string" }, "payment_date": { "description": "The epoch timestamp (ms) for when the partner should be able to cash out the reward. Can be null when the reward is declined.", "example": 1592944078600, "nullable": true, "type": "integer" }, "payment_status": { "description": "This status indicates whether the partner can withdraw the reward. Can be one of: `pending`, `available`, `withdrawn`, or `paid_externally`. Can be null when the payment is declined.", "example": "pending", "nullable": true, "type": "string" }, "payout_id": { "description": "The unique Id of the payout this reward is associted with.", "example": 1234567, "nullable": true, "type": "integer" }, "source": { "nullable": true, "properties": { "key": { "description": "The key of the source that generated this reward.", "example": "tran_b0qwaE3cCldjci", "nullable": false, "type": "string" }, "type": { "description": "The source that generated this reward. Can be one of: `transaction`, `lead`, `deal`, `submission`, `action`, `bill`, `asset`, `order_item`, `request`, `bonus`.", "example": "transaction", "nullable": true, "type": "string" } }, "type": "object" }, "transaction": { "nullable": true, "properties": { "amount": { "description": "Transaction amount in cents for specified currency.", "example": 100, "nullable": true, "type": "integer" }, "amount_usd": { "description": "Transaction amount in cents converted to USD.", "example": 50, "nullable": true, "type": "integer" }, "archived": { "description": "The boolean flag which determines if the transaction is archived or not", "example": false, "nullable": false, "type": "boolean" }, "category_key": { "description": "Key of transaction category.", "example": "subscription", "nullable": true, "type": "string" }, "created_at": { "description": "Immutable Unix timestamp in milliseconds taken at time of creation", "example": 1592944078600, "nullable": true, "type": "integer" }, "currency": { "description": "Transaction currency type.", "example": "USD", "nullable": true, "type": "string" }, "product_key": { "description": "Key of transaction product.", "example": "monthly_plan", "nullable": true, "type": "string" }, "updated_at": { "description": "Unix timestamp in milliseconds taken at time of last update", "example": 1592944078600, "nullable": true, "type": "integer" } }, "type": "object" }, "withdrawn": { "description": "The boolean flag which determines if the reward has been withdrawn already in some payout", "example": false, "nullable": false, "type": "boolean" } }, "type": "object" } ] } ] }, "type": "array" }, "total": { "nullable": true, "type": "integer" } }, "type": "object" }, "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message", "data" ], "type": "object" } } }, "description": "Returns a list of your rewards. The rewards are returned sorted by creation date by default, with the most recent rewards appearing first." }, "400": { "content": { "application/json": { "example": { "message": "Bad Request, illegal input for operation", "status": 401 }, "schema": { "properties": { "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message" ], "type": "object" } } }, "description": "Bad Request Error" }, "401": { "content": { "application/json": { "example": { "message": "Unauthorized, you credentials were invalid", "status": 401 }, "schema": { "properties": { "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message" ], "type": "object" } } }, "description": "Unauthorized Error" }, "403": { "content": { "application/json": { "example": { "message": "You don't have permissions to do that", "status": 403 }, "schema": { "properties": { "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message" ], "type": "object" } } }, "description": "Forbidden Error" }, "404": { "content": { "application/json": { "example": { "message": "Not Found, could not find the requested resource", "status": 404 }, "schema": { "properties": { "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message" ], "type": "object" } } }, "description": "Not Found Error" }, "500": { "content": { "application/json": { "example": { "message": "Internal Server Error, something went wrong", "status": 500 }, "schema": { "properties": { "message": { "type": "string" }, "status": { "format": "int32", "type": "integer" } }, "required": [ "status", "message" ], "type": "object" } } }, "description": "Internal Server Error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List all rewards", "tags": [ "Rewards" ], "x-allowMcpOnPublic": false, "x-apiType": [ "partner" ], "x-isPublic": true, "x-scope": "read" } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "description": "Production environment", "url": "https://api.partnerstack.com/api" } ] } ```