Reddit Advertising API

<details> <summary><strong>Important changes on September 30, 2025</strong></summary> Two critical changes are taking effect on September 30, 2025 that may impact your API access: <span>1. **Developer application migration to Business Manager**</span> All applications must be migrated to the Business Manager. Unmigrated applications will **lose access** to the Ads API. [Migrate your app](https://business.reddithelp.com/s/article/Create-a-Reddit-Application#migrate-an-application) to retain access to Ads API. <span>2. **v2 deprecation and support**</span> All public endpoints *except* the Conversions API (CAPI) have been sunsetted. If you are still using v2 endpoints, you **must migrate to v3** to avoid service disruption. After the deadline, v2 endpoints will return `410 GONE` errors. While support for CAPI v2 will continue, we encourage [migration to CAPI v3](https://ads-api.reddit.com/docs/v3/capi-migration) to take advantage of new features and long term support. Contact [adsapi-partner-support@reddit.com](mailto:adsapi-partner-support@reddit.com) for support or questions. </details> > **Note:** Find the older API doc site (v2) here: https://ads-api.reddit.com/docs/v2/ ## Ads API Terms By accessing or using the Ads API and/or associated Reddit Data, you are agreeing that you have read, and that you Agree to comply with and to be bound by, the [Ads API Terms](https://business.reddithelp.com/s/article/Reddit-Ads-API-Terms) and all applicable laws and regulations in their entirety without limitation or qualification. The Ads API Terms apply to and govern your access to and use of the Ads API and Reddit Data, constitute a legally binding agreement between you and Reddit, and include certain terms that are defined in the [Advertising Platform Terms](https://business.reddithelp.com/s/article/REDDIT-ADVERTISING-PLATFORM-TERMS), [Developer Terms](https://www.redditinc.com/policies/developer-terms), and [User Agreement](https://redditinc.com/policies/user-agreement). You may use the Ads API and Reddit Data only in accordance with the Ads API Terms. Use of the Conversions API is subject to the [Advertiser Measurement Program Terms](https://business.reddithelp.com/s/article/Reddit-Business-Tool-Terms) in addition to the same agreements as the Ads API. If you do not agree to the Ads API Terms, and Advertiser Measurement Program Terms as applicable, then you must not access or use the Ads API, Conversions API, or Reddit Data. > **Note:** The Reddit Ads API is open to all developers and **does not require allowlisting or approval from Reddit to access**. API partners working on behalf of advertisers can request support by contacting [adsapi-partner-support@reddit.com](mailto:adsapi-partner-support@reddit.com). [Managed advertisers](https://www.business.reddit.com/speak-with-a-reddit-ads-expert) can request partnership approval by contacting their Reddit Ads expert. Self-service developers interested in joining the Ads API ecosystem can apply to become a [partner](https://www.redditforbusiness.com/api-partnership). Learn more about Reddit's [advertising ecosystem partner program](https://www.business.reddit.com/solutions/advertising-agency/ecosystem-partner). ## Overview The Reddit Ads API lets advertisers tap into the Reddit Ads Platform to build and manage advertising campaigns and accounts programmatically. By integrating Reddit Ads API into your tooling, you can streamline workflows, reduce operational overhead, and accelerate the creation, optimization, and reporting of Reddit campaigns without needing to step into the Reddit Ads Manager directly.  Here are two popular ways to use the Reddit Ads API: - **Postman:** A visual client that makes it simpler to set up and start testing requests and responses. This is the fastest way to familiarize yourself with the API if you prefer a point-and-click approach. You can explore our [Postman collections](https://www.postman.com/reddit-ads-api "https://www.postman.com/reddit-ads-api"). - **Programmatic access:** Use your preferred programming language or command-line tools to create automations and integrations. This approach is ideal if you want to embed API calls into your workflows or build custom tools. ### User agents Rate-limiting issues often occur if you haven't set your user agent to a unique descriptor. Many default user agents (like `“Python/urllib”` or `“Java”`) are drastically limited to encourage unique and descriptive user-agent strings. We recommend following this format for your client's user agent string: ``` {{Target platform}}:{{Unique app ID}}:{{Version string}} (by /u/{{Your Reddit username}}) ``` > **Note:** Including your version number helps us block old buggy or broken versions of your app safely. Just remember to update this string when you update your version number. <details><summary>Example</summary> ``` User-Agent: android:com.example.myredditapp:v1.2.3 (by /u/kemitche) ``` </details> > **Important:** Never lie about your user agent! Don't pretend to be popular browsers or other bots. We'll ban anyone caught in the act. ### Pagination Paginated endpoints respond with a `pagination` object containing up to 2 fields: > **Important:** The URLs for these fields should be followed directly. Don't assume pagination based on the query parameters in the provided URLs. - **`next_url`:** The full URL to access the next page of the response. If not available, the current page is the final page. - **`previous_url`:** The full URL to access the previous page of the response. If not available, the current page is the first page. All endpoints that return a list, such as `List Campaigns` and `Get a Report`, will be paginated. ### Response types Response | Description --- | --- 200 | Successfully processed the request. 400 | Request was invalid. See the client error message for specifics. 401 | No bearer token or a bad bearer token was provided. Check your application authentication. 403 | Insufficient authentication scopes or the user doesn't have permission. Check the client error message for specifics. If it's a permission issue, ensure the user has the proper permissions assigned to take action. 404 | Specified resource was not found. Check that correct permissions have been given to the source and that the resource exists. 429 | Request has exceeded rate limits. For more information on rate limiting and best practices for handling errors, see our [rate limiting documentation](https://business.reddithelp.com/s/contactsupport). 500 | Server error while processing events. Try again later or [contact our support team](https://business.reddithelp.com/s/contactsupport) if the problem persists. ### Authentication All API applications must be authenticated with OAuth2 by [creating a developer application](#create-a-developer-application) and [obtaining access and refresh tokens](#authenticate-your-developer-application). ### Limitations > **Note:** Future changes may introduce new limitations. - **Rate limits:** Exceeding request limits may result in temporary throttling. - **Functionality restrictions:** Unless explicitly stated, alpha or beta products aren't supported in the Reddit Ads API. ### Rate Limiting The Reddit Ads API applies rate limits to prevent abuse, maintain stability, and ensure fair usage. Understanding these limits helps you build reliable integrations. > **Important:** The Conversions API (CAPI) endpoint has unique limits and currently doesn't support the standard rate limiting headers. Refer to [POST Conversion Events](/operations/Post%20Conversion%20Events) for more details. #### How it works Each route or endpoint is assigned to a specific endpoint group. Each group shares a pooled limit, meaning requests to endpoints within the same group count toward a shared limit. This limit is based on the group’s quota policies, each defining a request limit within a specific time window. Limits are applied to each [authorized](/#authenticate-your-developer-application) instance of your application, meaning each user who authorizes your application receives their own set of limits. #### Rate limiting headers Rate limit data is provided in HTTP headers for each API response. > **Important:** Monitor these headers to manage request rates and prevent throttling. #### `RateLimit-Policy` header Provides the application rate limit policies of the requested route. ``` RateLimit-Policy: "policy-name-1";q=quota-1;w=window-1,"policy-name-2";q=quota-2;w=window-2 ``` <details><summary>Example</summary> `custom-audience-ingestion` and `custom-audience-ingestion-burst` of 3000 requests/900 seconds and 500 requests/60 seconds ``` RateLimit-Policy: "custom-audience-ingestion";q=3000;w=900,"custom-audience-ingestion-burst";q=500;w=60 ``` </details> #### `RateLimit` header The remaining requests and the time until reset for each endpoint group. ``` RateLimit: "policy-name-1";r=remaining-1;t=time-until-reset-1,"policy-name-2";r=remaining-2;t=time-until-reset-2 ``` <details><summary>Example</summary> Remaining requests until reset time. 2134 requests remaining for the `custom-audience-ingestion` policy, which resets in 723 seconds, and 24 requests remaining for the `custom-audience-ingestion-burst` policy, which resets in 3 seconds. ``` RateLimit: "custom-audience-ingestion";r=2134;t=723,"custom-audience-ingestion-burst";r=24;t=3 ``` </details> <h4 id="rate-limit-endpoint-groups"> Rate Limit Endpoint Groups</h4><details><summary><span id="/ratelimits/Campaign Management Read"><strong>Campaign Management Read</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-campaign-management-read</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">400 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Get Ad Account" class="sl-text-primary hover:sl-underline">Get Ad Account</a> </li><li> <a href="/operations/List Ad Groups" class="sl-text-primary hover:sl-underline">List Ad Groups</a> </li><li> <a href="/operations/List Ads" class="sl-text-primary hover:sl-underline">List Ads</a> </li><li> <a href="/operations/List Campaigns" class="sl-text-primary hover:sl-underline">List Campaigns</a> </li><li> <a href="/operations/List Saved Audiences" class="sl-text-primary hover:sl-underline">List Saved Audiences</a> </li><li> <a href="/operations/Get Ad Group" class="sl-text-primary hover:sl-underline">Get Ad Group</a> </li><li> <a href="/operations/Get Ad" class="sl-text-primary hover:sl-underline">Get Ad</a> </li><li> <a href="/operations/List Ad Accounts By Business" class="sl-text-primary hover:sl-underline">List Ad Accounts By Business</a> </li><li> <a href="/operations/Get Campaign" class="sl-text-primary hover:sl-underline">Get Campaign</a> </li><li> <a href="/operations/Get Saved Audience" class="sl-text-primary hover:sl-underline">Get Saved Audience</a> </li><li> <a href="/operations/List Time Zones" class="sl-text-primary hover:sl-underline">List Time Zones</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Campaign Management Write"><strong>Campaign Management Write</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-campaign-management-write</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">200 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Update Ad Account" class="sl-text-primary hover:sl-underline">Update Ad Account</a> </li><li> <a href="/operations/Create Ad Group" class="sl-text-primary hover:sl-underline">Create Ad Group</a> </li><li> <a href="/operations/Create Ad" class="sl-text-primary hover:sl-underline">Create Ad</a> </li><li> <a href="/operations/Create Campaign" class="sl-text-primary hover:sl-underline">Create Campaign</a> </li><li> <a href="/operations/Create Saved Audience" class="sl-text-primary hover:sl-underline">Create Saved Audience</a> </li><li> <a href="/operations/Update Ad Group" class="sl-text-primary hover:sl-underline">Update Ad Group</a> </li><li> <a href="/operations/Update Ad" class="sl-text-primary hover:sl-underline">Update Ad</a> </li><li> <a href="/operations/Update Campaign" class="sl-text-primary hover:sl-underline">Update Campaign</a> </li><li> <a href="/operations/Update Saved Audience" class="sl-text-primary hover:sl-underline">Update Saved Audience</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Targeting Taxonomy"><strong>Targeting Taxonomy</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-targeting-taxonomy</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">500 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/List User Custom Audiences" class="sl-text-primary hover:sl-underline">List User Custom Audiences</a> </li><li> <a href="/operations/Get Custom Audience" class="sl-text-primary hover:sl-underline">Get Custom Audience</a> </li><li> <a href="/operations/List Carriers" class="sl-text-primary hover:sl-underline">List Carriers</a> </li><li> <a href="/operations/List Communities" class="sl-text-primary hover:sl-underline">List Communities</a> </li><li> <a href="/operations/Search Communities" class="sl-text-primary hover:sl-underline">Search Communities</a> </li><li> <a href="/operations/List Communities Suggestions" class="sl-text-primary hover:sl-underline">List Communities Suggestions</a> </li><li> <a href="/operations/List Devices" class="sl-text-primary hover:sl-underline">List Devices</a> </li><li> <a href="/operations/List Geolocations" class="sl-text-primary hover:sl-underline">List Geolocations</a> </li><li> <a href="/operations/Do Geolocation Validations" class="sl-text-primary hover:sl-underline">Do Geolocation Validations</a> </li><li> <a href="/operations/List Interests" class="sl-text-primary hover:sl-underline">List Interests</a> </li><li> <a href="/operations/Do Keyword Validations" class="sl-text-primary hover:sl-underline">Do Keyword Validations</a> </li><li> <a href="/operations/List 3rd Party Audiences" class="sl-text-primary hover:sl-underline">List 3rd Party Audiences</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Custom Audiences Ingestion"><strong>Custom Audiences Ingestion</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-custom-audience-ingestion</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">3000 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">900 sec</td> </tr><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-custom-audience-ingestion-burst</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">500 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Create Custom Audience" class="sl-text-primary hover:sl-underline">Create Custom Audience</a> </li><li> <a href="/operations/Delete Custom Audience" class="sl-text-primary hover:sl-underline">Delete Custom Audience</a> </li><li> <a href="/operations/Update Custom Audience Users" class="sl-text-primary hover:sl-underline">Update Custom Audience Users</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Billing"><strong>Billing</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-funding-instruments</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">30 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/List Funding Instruments" class="sl-text-primary hover:sl-underline">List Funding Instruments</a> </li><li> <a href="/operations/Query Funding Instruments by Business" class="sl-text-primary hover:sl-underline">Query Funding Instruments by Business</a> </li><li> <a href="/operations/Get Child Funding Instruments" class="sl-text-primary hover:sl-underline">Get Child Funding Instruments</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Business Manager"><strong>Business Manager</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-business-manager</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">100 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Get Ad Account History" class="sl-text-primary hover:sl-underline">Get Ad Account History</a> </li><li> <a href="/operations/List Profiles By Ad Account" class="sl-text-primary hover:sl-underline">List Profiles By Ad Account</a> </li><li> <a href="/operations/Get Business" class="sl-text-primary hover:sl-underline">Get Business</a> </li><li> <a href="/operations/Update Business" class="sl-text-primary hover:sl-underline">Update Business</a> </li><li> <a href="/operations/Query Ad Accounts" class="sl-text-primary hover:sl-underline">Query Ad Accounts</a> </li><li> <a href="/operations/List Profiles By Business" class="sl-text-primary hover:sl-underline">List Profiles By Business</a> </li><li> <a href="/operations/List Industries" class="sl-text-primary hover:sl-underline">List Industries</a> </li><li> <a href="/operations/Get Me" class="sl-text-primary hover:sl-underline">Get Me</a> </li><li> <a href="/operations/list_my_businesses" class="sl-text-primary hover:sl-underline">list_my_businesses</a> </li><li> <a href="/operations/Get Profile" class="sl-text-primary hover:sl-underline">Get Profile</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Leads"><strong>Leads</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-leads</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">20 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/List Lead Gen Forms" class="sl-text-primary hover:sl-underline">List Lead Gen Forms</a> </li><li> <a href="/operations/Create Lead Gen Form" class="sl-text-primary hover:sl-underline">Create Lead Gen Form</a> </li><li> <a href="/operations/Get Lead Gen Form" class="sl-text-primary hover:sl-underline">Get Lead Gen Form</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Conversion Signals"><strong>Conversion Signals</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-conversion-signals</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">30 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/List Pixels By Ad Account" class="sl-text-primary hover:sl-underline">List Pixels By Ad Account</a> </li><li> <a href="/operations/Get App Last Fired At" class="sl-text-primary hover:sl-underline">Get App Last Fired At</a> </li><li> <a href="/operations/List Pixels By Business" class="sl-text-primary hover:sl-underline">List Pixels By Business</a> </li><li> <a href="/operations/Get Last Fired At" class="sl-text-primary hover:sl-underline">Get Last Fired At</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Reporting"><strong>Reporting</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-reporting</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Get A Report" class="sl-text-primary hover:sl-underline">Get A Report</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Product Catalog"><strong>Product Catalog</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-product-catalog</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">7000 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">300 sec</td> </tr><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-product-catalog-burst</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">3000 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/List Product Catalogs" class="sl-text-primary hover:sl-underline">List Product Catalogs</a> </li><li> <a href="/operations/Create Product Catalog" class="sl-text-primary hover:sl-underline">Create Product Catalog</a> </li><li> <a href="/operations/List Catalog Import Issues" class="sl-text-primary hover:sl-underline">List Catalog Import Issues</a> </li><li> <a href="/operations/Get Catalog Import Report" class="sl-text-primary hover:sl-underline">Get Catalog Import Report</a> </li><li> <a href="/operations/Get Product Catalog" class="sl-text-primary hover:sl-underline">Get Product Catalog</a> </li><li> <a href="/operations/Delete Product Catalog" class="sl-text-primary hover:sl-underline">Delete Product Catalog</a> </li><li> <a href="/operations/Update Product Catalog" class="sl-text-primary hover:sl-underline">Update Product Catalog</a> </li><li> <a href="/operations/List Catalog Imports" class="sl-text-primary hover:sl-underline">List Catalog Imports</a> </li><li> <a href="/operations/List Product Feeds" class="sl-text-primary hover:sl-underline">List Product Feeds</a> </li><li> <a href="/operations/Create Product Feed" class="sl-text-primary hover:sl-underline">Create Product Feed</a> </li><li> <a href="/operations/List Product Sets" class="sl-text-primary hover:sl-underline">List Product Sets</a> </li><li> <a href="/operations/Create Product Set" class="sl-text-primary hover:sl-underline">Create Product Set</a> </li><li> <a href="/operations/List Products In Product Catalog" class="sl-text-primary hover:sl-underline">List Products In Product Catalog</a> </li><li> <a href="/operations/Get Product Feed" class="sl-text-primary hover:sl-underline">Get Product Feed</a> </li><li> <a href="/operations/Delete Product Feed" class="sl-text-primary hover:sl-underline">Delete Product Feed</a> </li><li> <a href="/operations/Update Product Feed" class="sl-text-primary hover:sl-underline">Update Product Feed</a> </li><li> <a href="/operations/Get Product Set" class="sl-text-primary hover:sl-underline">Get Product Set</a> </li><li> <a href="/operations/Delete Product Set" class="sl-text-primary hover:sl-underline">Delete Product Set</a> </li><li> <a href="/operations/Update Product Set" class="sl-text-primary hover:sl-underline">Update Product Set</a> </li><li> <a href="/operations/List Products In Product Set" class="sl-text-primary hover:sl-underline">List Products In Product Set</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Forecasting"><strong>Forecasting</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-forecasting</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">30 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Get Channel Planning Reach" class="sl-text-primary hover:sl-underline">Get Channel Planning Reach</a> </li><li> <a href="/operations/Generate Bid Suggestion" class="sl-text-primary hover:sl-underline">Generate Bid Suggestion</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Creative Management"><strong>Creative Management</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-creative-management</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">200 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Get Post" class="sl-text-primary hover:sl-underline">Get Post</a> </li><li> <a href="/operations/Update Post" class="sl-text-primary hover:sl-underline">Update Post</a> </li><li> <a href="/operations/List Posts" class="sl-text-primary hover:sl-underline">List Posts</a> </li><li> <a href="/operations/Create Post" class="sl-text-primary hover:sl-underline">Create Post</a> </li><li> <a href="/operations/List Structured Posts" class="sl-text-primary hover:sl-underline">List Structured Posts</a> </li><li> <a href="/operations/Create Structured Post Creation Job" class="sl-text-primary hover:sl-underline">Create Structured Post Creation Job</a> </li><li> <a href="/operations/Get Structured Post Creation Job" class="sl-text-primary hover:sl-underline">Get Structured Post Creation Job</a> </li><li> <a href="/operations/Get Structured Post" class="sl-text-primary hover:sl-underline">Get Structured Post</a> </li><li> <a href="/operations/Update Structured Post" class="sl-text-primary hover:sl-underline">Update Structured Post</a> </li></ul></details> </td> </tr></tbody></table></details><details><summary><span id="/ratelimits/Product Catalog Batch"><strong>Product Catalog Batch</strong></span></summary> <table class="sl-table sl-w-full sl-mb-6 sl-text-sm sl-border table-fixed"> <thead> <tr class="sl-bg-muted"> <th class="sl-p-2 sl-text-left sl-border" style="width: 20vw;">Slug</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Quota</th> <th class="sl-p-2 sl-text-left sl-border" style="width: 15vw;">Window</th> </tr> </thead> <tbody><tr> <td class="sl-p-2 sl-border" style="width: 20vw;"><span class="sl-font-mono sl-font-medium sl-mx-0.5 sl-px-1 sl-py-0.5 sl-bg-code sl-text-on-code sl-rounded sl-border" style="font-size: 0.8125em;">ads-product-catalog-batch</span></td> <td class="sl-p-2 sl-border" style="width: 15vw;">150 requests</td> <td class="sl-p-2 sl-border" style="width: 15vw;">60 sec</td> </tr><tr> <td class="sl-p-2 sl-border sl-text-muted" colspan="4"> <details><summary><strong>Endpoints</strong></summary> <ul><li> <a href="/operations/Batch Delete Products" class="sl-text-primary hover:sl-underline">Batch Delete Products</a> </li><li> <a href="/operations/Batch Create Products" class="sl-text-primary hover:sl-underline">Batch Create Products</a> </li></ul></details> </td> </tr></tbody></table></details> #### Best practices - Cache data when working with specialized values or reviewing large data sets frequently. - Stagger requests across multiple accounts to avoid sudden traffic spikes. - Backfill data only during non-peak business hours, when possible. - Include custom `User-Agent` headers with your request. - Design your apps to gracefully handle `429 Too Many Requests` responses by implementing fallbacks. <details><summary>Exponential backoff</summary> ``` max_attempts = 10 attempts = 0 while attempts < max_attempts: # Make a request to Ads API response = requests.get(request_url, headers = {"Authorization": "Bearer " + auth_token}) # If not rate limited, break out of while loop and continue with the rest of the code if response.status_code != 429: break # If rate limited, wait and try again time.sleep((2 ** attempts) + random.random()) attempts = attempts + 1 ``` </details> ## Quick Start Guide ### Create a developer application > **Important:** Only business admins can access this interface. Contact one of your business's administrators for help. Developer applications define the settings that determine how your app authenticates with the Ads API. These settings streamline workflows and enhance campaign management efficiency programmatically, enabling you to build custom tools to create and manage ad campaigns, generate reports, and manage custom audiences. <details><summary>Learn more</summary> These settings can only be managed by business admins with a [verified account](https://support.reddithelp.com/hc/en-us/articles/360043047552-Why-should-I-verify-my-Reddit-account-with-an-email-address). You can manage your developer applications in _Business Manager > Developer Application_.  In this interface, you can: - **Add an app:** Create or migrate an existing developer application to define the settings for how your app authenticates with the Ads API. - [**Create**](#create-an-application)**:** Make new developer application credentials for your app. - [**Migrate**](#migrate-an-application)**:** Move an existing developed app associated with your Reddit account to manage it in the Ads Manager. - **Edit an app:** Change any setting for your application, excluding its app ID and secret. - **Delete your app:** Remove this app from your business. > **Important:** Deleting an app will disconnect all third-party services using it from the Ads API. This action can't be undone. #### Create an application 1. In the developer application interface, select _Add Apps > Create an app_.  2. Set up your app. - **App name:** An appropriate and descriptive title. We recommend a name that reflects your business, product, or integration purpose. Avoid generic names like `Reddit Integration` or `Test`.  - **Description (optional):** Information about your app. - **About URL:** The URL that provides more information about your business or application. - **Redirect URL:** The URL to authorize access to your application. We recommend setting a path on your business domain, like `https://mybusiness.com/oauth/callback`. - **Primary contact:** The business admin responsible for this app, who may be contacted for operational updates related to the Ads API. This must be set to a business admin. Here's how to [set this permission](https://business.reddithelp.com/s/article/Add-users-to-a-Reddit-Ads-account#change-a-members-role). 3. When ready, select _Create App_. This will save your app and generate its secret and app ID.  #### Migrate an application > **Note:** Migration will limit your app's scope to the Ads API. Follow our [Devvit guide](https://developers.reddit.com/docs/) for other scopes. 1. In the developer application interface, select _Add Apps > Migrate an existing app_.  2. Select the app to migrate. 3. Choose a primary contact for your app. This must be set to a business admin. 4. When ready, select _Migrate App_. This will make your app only available to manage in the developer application interface and remove it from [Preferences > Apps](https://www.reddit.com/prefs/apps/).  #### Things to know - A member cannot be removed from your business if they're an active primary contact. - You agree to the [Advertising Platform Terms](https://business.reddithelp.com/s/article/REDDIT-ADVERTISING-PLATFORM-TERMS), [Developer Terms](https://www.redditinc.com/policies/developer-terms), and [User Agreement](https://redditinc.com/policies/user-agreement) when creating or migrating an app. - Migrating an application will limit your application's scope to only the Ads API. Follow [our authentication guide](https://developers.reddit.com/docs/authentication) to set up access to Devvit. - After creating your application, finish set up by [authenticating it](#authenticate-your-developer-application). </details> ### Authenticate your developer application You can set up your developer application to gain access to the Reddit API, letting you develop nifty applications and integrations that seamlessly interact with Reddit's ads platform. <details> <summary>Learn more</summary> Before you begin, you should have: - [A Reddit Ads account](https://business.reddithelp.com/s/article/Create-and-manage-your-Reddit-Ads-account#N1). - [A developer application](#create-a-developer-application). You'll need its app ID and secret. - Access to a terminal application. #### 1. Authorize your application Go to your business's [developer applications](https://ads.reddit.com/business/developer-applications) and find your application's app ID. Replace the values in the following link and navigate to it: ``` https://www.reddit.com/api/v1/authorize?client_id={{App ID}}&response_type=code&state={{Random String}}&redirect_uri={{Redirect URL}}&duration={{Duration}}&scope={{Scope}} ``` - `{{App ID}}`**:** The ID of your dev app - `{{Random String}}`**:** This can be set to any string with no spaces or special characters, like the name of your dev app. This is used to [detect cross-site request forgeries (CSRF)](https://owasp.org/www-community/attacks/csrf). You can also set a signature for additional security. - `{{Redirect URL}}`**:** The redirect URL you set for your dev app. > **Note:** Don't change `redirect_uri` to `redirect_url`. This parameter must be used so that the application can correctly route mobile and web application redirects. - `{{Duration}}`**:** The time limit that this access token will expire. You probably want to set this to `permanent`, but you can set it to `temporary` to make the access code valid for only one hour. > **Note:** If you set this to `temporary`, you won't be able to refresh this option. - `{{Scope}}`**:** A comma-separated list of the actions performable with the access token. Only the following scopes are accepted: `adsread`, `adsconversions`, `history`, `adsedit`, `read`. > **Tip:** If you'd like your token to access everything in the Reddit Ads API, you can set this to `adsread,adsconversions,history,adsedit,read`.  | **Scope** | **Description** | ---|--- | `adsconversions` | Post conversion events by enabling access to the [Conversions](https://ads-api.reddit.com/docs/v2/#tag/Conversions) endpoint | | `adsedit` | Edit ads data | | `adsread` | Read advertising data for your account  | | `history` | Access submission history | | `read` | Read posts and comments for your Reddit user account | <details> <summary><strong>Example:</strong> Get link based on credentials</summary> | **Field** | **Value** | |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **App ID** | ```DnvSjQYG9t13lWWOndNqOg``` | | **Redirect URL** | ```https://www.reddit.com/prefs/apps``` | | **Scope** | Post conversion events with the Conversions API (CAPI) | | **Link** | ```https://www.reddit.com/api/v1/authorize?client_id=DnvSjQYG9t13lWWOndNqOg&response_type=code&state=sgtm-capi&redirect_uri=https://www.reddit.com/prefs/apps&duration=permanent&scope=adsconversions``` | </details> Check that the username listed matches the account you want to authorize the app. If the username is correct, select _Allow_.  > **Important:** If an unexpected username is displayed, you're in an active Reddit session. To fix this, log out of your account, log into the correct account, then revisit the URL. You will be sent to the redirect URL that you provided earlier. The URL in your address bar will have 2 query parameters: the state and the code. Copy and record the code value and remove the `#_` characters at the end of the value, if any. > **Important:** This code should be used within the next ten minutes and only once per authorization.  <details> <summary><strong>Example:</strong> Find code value from redirect URL</summary> | Redirect URL | Code value | | --------------------------------------------------------------------------------------------------------- | -------------------------------- | | ```https://notarealbrand.myshopify.com/oauth/callback?state=my-state&code=Ve49meZ9oh3lZFY35CEizm3jTsfJeA#_``` | ```Ve49meZ9oh3lZFY35CEizm3jTsfJeA``` | </details> <p></p> #### 2. Get your access token from the Reddit API Open a terminal window and execute the following cURL command with your noted values: ```bash curl -X POST https://www.reddit.com/api/v1/access_token \      -H 'content-type: application/x-www-form-urlencoded' \      -A '{{Name}}' \      -u '{{App ID}}:{{Secret}}' \      -d 'grant_type=authorization_code&code={{Redirect Code}}&redirect_uri={{Redirect URL}}' ``` <details> <summary><strong>Example:</strong> Get access token</summary> <table> <tr> <th>Field</th> <th>Value</th> </tr> <tr> <td><strong>Name</strong></td> <td><code>SGTM-CAPI</code></td> </tr> <tr> <td><strong>App ID</strong></td> <td><code>DnvSjQYG9t13lWWOndNqOg</code></td> </tr> <tr> <td><strong>Secret</strong></td> <td><code>Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww</code></td> </tr> <tr> <td><strong>Redirect Code</strong></td> <td><code>QGRMgx3l54x0s8NT_WdcuSt_Adi9nA</code></td> </tr> <tr> <td><strong>Redirect URL</strong></td> <td><code>https://www.reddit.com/prefs/apps</code></td> </tr> <tr> <td><strong>Code</strong></td> <td> <pre><code> curl -X POST https://www.reddit.com/api/v1/access_token \ -H 'content-type: application/x-www-form-urlencoded' \ -A 'SGTM-CAPI' \ -u 'DnvSjQYG9t13lWWOndNqOg:Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww' \ -d 'grant_type=authorization_code&code=QGRMgx3l54x0s8NT_WdcuSt_Adi9nA&redirect_uri=https://www.reddit.com/prefs/apps' </pre></code> </td> </tr> </table> </details> If successful, you will receive a response that looks like this: ```json {     "access_token": {{Access token}},     "token_type": "bearer",     "expires_in": {{Expiration time in Unix epoch}},     "refresh_token": {{Refresh token}},     "scope": {{Scope string}} } ``` Record the value for `access_token` and `refresh_token`. You'll use `access_token` to access the Reddit Ads API for either one hour (3600) or one day (86400), whichever is listed for the value for `expires_in`. #### 3. (Optional) Refresh your access token You can use an active access token to maintain continuous access to the API without requiring re-authentication.  To refresh your token, open a terminal window and execute the following cURL command with your noted values: ```bash curl -X POST https://www.reddit.com/api/v1/access_token \      -A '{{Name}}' \      -u '{{App ID}}:{{Secret}}' \      -d 'grant_type=refresh_token&refresh_token={{Refresh token}}' ``` <details> <summary><strong>Example:</strong> Refresh token</summary> <table> <tr> <th>Field</th> <th>Value</th> </tr> <tr> <td><strong>Name</strong></td> <td><code>SGTM-CAPI</code></td> </tr> <tr> <td><strong>App ID</strong></td> <td><code>kmY1CRszT3obFwYeU3uuEw</code></td> </tr> <tr> <td><strong>Secret</strong></td> <td><code>rTBVO3UirF-fcwvlMNellSxqkd3wSQ</code></td> </tr> <tr> <td><strong>Refresh Token</strong></td> <td><code>90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw</code></td> </tr> <tr> <td><strong>Code</strong></td> <td> <pre><code> curl -X POST https://www.reddit.com/api/v1/access_token \ -A 'SGTM-CAPI' \ -u 'kmY1CRszT3obFwYeU3uuEw:rTBVO3UirF-fcwvlMNellSxqkd3wSQ' \ -d 'grant_type=refresh_token refresh_token=90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw' </pre></code> </td> </tr> </table> </details> If successful, you will receive a response that looks like this: ```json {     "access_token": {{Access token}},     "token_type": "bearer",     "expires_in": {{Expiration time in Unix epoch}},     "refresh_token": {{Refresh token}},     "scope": {{Scope string}} } ``` Record the value for `access_token` and `refresh_token`. You'll use `access_token` to access the Reddit Ads API for either one hour (3600) or one day (86400), whichever is listed for the value for `expires_in`. </details> ### Add adaptive time zone parameters The API defaults to returning data in Coordinated Universal Time (UTC). If you need data in a certain time zone, the `time_zone_id` parameter is effective only when the breakdowns include date details. If not, you can set the time offset with `start_at` and `end_at` to match your desired time zone. <details><summary>Learn more</summary> To return details about the time zone used by our API, you can call `GET List Time Zones`, which returns information like the time zone code, offset, and daylight saving time status: ``` json { "data": [ { "code": "PT", "dst_offset": 3600, "id": "America/Los_Angeles", "is_dst_active": false, "name": "Pacific Time", "offset": -28800 } ], "pagination": { "next_url": "https://ads-api.reddit.com/api/v3?page.token=nextToken", "previous_url": "https://ads-api.reddit.com/api/v3?page.token=previousToken" } } ``` This call can be integrated into middleware to periodically retrieve the offset (`dst_offset`) and accommodate daylight savings time (`is_dst_active`). > **Note:** Offset values are returned in seconds, so remember to adjust your timestamps accordingly. To make this easier, you can use third-party tools and libraries. For example, the `moment.js` library lets you handle time zone conversions: ``` js var jun = moment("2014-06-01T12:00:00Z"); var dec = moment("2014-12-01T12:00:00Z"); jun.tz('America/New_York').format('ha z'); // 8am EDT dec.tz('America/New_York').format('ha z'); // 7am EST ``` > **Important:** Keep in mind that third-party tools and libraries aren't officially endorsed or supported by Reddit. </details> ### Fetch ad accounts You can retrieve a list of your authorized ad accounts to determine which account you'd like to use for Reddit Ads API actions, like sending conversion events or fetching data from the Ads Manager. <details><summary>Learn more</summary> <br> #### Before you start - [**Set up a Reddit Ads account**](https://business.reddithelp.com/s/article/Create-and-manage-your-Reddit-Ads-account)**.** - **Find your ads account ID.** Let us know which business account to [fetch data from](https://ads-api.reddit.com/docs/v3/operations/List%20Ad%20Accounts%20By%20Business). You can find your ads account ID in [Accounts](https://ads.reddit.com/accounts). - **Find details about your Reddit developer application.** Retrieve details like the client ID and redirect URL for your app. You can find this information in your account's [application preferences](https://www.reddit.com/prefs/apps). - **Access a terminal application or Postman.** Ensure you have a way to create requests to the API. #### 1. Get your access token 1. Go to the authorization URL of your Reddit developer application. For `scope`, you must at least include `“adsread”`. > **Note:** For more details on setting up your authorization URL, see [Authorize your application](#create-a-developer-application). ``` bash https://www.reddit.com/api/v1/authorize?client_id={{Client ID}}&response_type=code&state={{Random String}}&redirect_uri={{Redirect URL}}&duration={{Duration}}&scope={{Scope}} ``` 2. Check that the username listed matches the member you want to authorize the app. The app will be able to access all the accounts this user has permission to manage, even as this user's permissions change over time. If the username is correct, select _Allow_.  > **Important:** If an unexpected username is displayed, you're in an active Reddit session. To fix this, log out of your account, log into the correct account, then revisit the URL. 3. You will be redirected to the redirect URL that you provided earlier. The URL in your address bar will have 2 query parameters: the state and the code. Copy and record the code value and remove the `_#\__` characters at the end of the value, if any.  <br> <details><summary>Example</summary> - **Example URL:** `https://mybusiness.com/oauth/callback?state=my-state&code=Ve49meZ9oh3lZFY35CEizm3jTsfJeA#_` - **Copy:** `Ve49meZ9oh3lZFY35CEizm3jTsfJeA` </details> <br> 4. Send an API request to retrieve your access token. For more details on sending this request, see [Create a developer application](#create-a-developer-application). ``` bash curl -X POST https://www.reddit.com/api/v1/access_token \ -H 'content-type: application/x-www-form-urlencoded' \ -A '{{Name}}' \ -u '{{Client ID}}:{{Secret}}' \ -d 'grant_type=authorization_code&code={{Redirect Code}}&redirect_uri={{Redirect URL}}' ``` #### 2. Find the business linked to your member Call [`GET List My Businesses`](https://ads-api.reddit.com/docs/v3/operations/List%20My%20Businesses) to return details about the businesses linked to your member. Save the `id` for the business account you need. <details> <summary>Response example</summary> ``` JSON { "data": [ { "id": "34e0ed2c-b15d-4945-bf3f-1428eaddbf11", "name": "Reddit inc", "industry": "OTHER", [...] } ], [...] } ``` </details> <br> #### 3. Fetch a list of ad accounts Get a list of the ad accounts in a business by calling [`GET List Ad Accounts by Businesses`](https://ads-api.reddit.com/docs/v3/operations/List%20Ad%20Accounts%20By%20Business). Only ad accounts that the member has permission on will be returned. Use `id` to perform API actions on specific ad accounts. <details><summary>Response example</summary> ``` json { "data": [ { "id": "a2_bzv32cgqp", "type": "MANAGED", "currency": "USD", "name": "anagtest", "business_id": "34e0ed2c-b15d-4945-bf3f-1428eaddbf11", [...] } ], [...] } ``` </details> </details> ### Set up a campaign You can programmatically set up campaigns using the Reddit Ads API. This lets you create ad groups to target your audience, organize the ads you display on Reddit, and measure your results in the Ads Manager. All ads created using the API are subject to our [Ads API Terms](https://business.reddithelp.com/s/article/Reddit-Ads-API-Terms) and [Ads Policy](https://business.reddithelp.com/s/article/Reddit-Advertising-Policy-Overview). > **Note:** Looking for an easier way to set up campaigns? Try creating a campaign in the Ads Manager using [Simple Create ](https://business.reddithelp.com/s/article/Simple-Create)or [Advanced Campaign Creation](https://business.reddithelp.com/s/article/Set-up-a-Reddit-Ads-Campaign). <details> <summary>Learn more</summary> <br> #### Before you start - [Set up a Reddit Ads account](https://business.reddithelp.com/s/article/Create-and-manage-your-Reddit-Ads-account) and [request access to the Ads API](https://www.redditforbusiness.com/api-partnership)  - **Create the content for your ads.** This includes text, [landing pages](https://business.reddithelp.com/s/article/URL-and-Landing-Page-Best-Practices), and [click or impression trackers](https://business.reddithelp.com/s/article/Set-up-third-party-measurement). [Learn about our ad specifications](https://business.reddithelp.com/s/article/Reddit-Ad-Unit-Specifications). - **Find your Pixel and profile ID.** You can find your Pixel ID in [Accounts](https://ads.reddit.com/accounts) and your profile ID by calling [`GET List Profiles By Ad Account`](https://ads-api.reddit.com/docs/v3/operations/List%20Profiles%20By%20Ad%20Account) or [`GET List Profiles by Business`](https://ads-api.reddit.com/docs/v3/operations/List%20Profiles%20By%20Business). - **Access a terminal application or Postman.** Ensure you have a way to create requests to the API. #### 1. Create a campaign Create a campaign by calling the [`POST Create Campaign`](https://ads-api.reddit.com/docs/v3/operations/Create%20Campaign) endpoint. The campaign ID will be listed in `id`. Save this value—you'll need this to create ad groups. ##### Reference > **Note:** For more details on setting these values, see [`Create Campaign`](https://ads-api.reddit.com/docs/v3/operations/Create%20Campaign). | Objective | Purpose | Cost | | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `IMPRESSIONS` | Awareness of your brand or product. Optimized for impressions. | Pay for cost-per-1,000 impressions (**CPM**) | | `CLICKS` | Traffic to your website. | Pay for cost-per-click | | `CONVERSIONS` | Conversions (valuable actions) on your website. | Pay for cost-per-click | | `VIDEO_VIEWABLE_IMPRESSIONS` | Views for your video. | Pay for cost-per-view (**CPV**) | | `APP_INSTALLS` | Installs for your mobile app. | Pay for clicks | | `CATALOG_SALES (beta)` | Sales of your retail products and services. Required for product and dynamic product ads. Optimized for clicks. | Pay for cost-per-click (**CPC**) | | `LEAD_GENERATION (beta)` | Increase potential customer interest by capturing valuable leads with forms on Reddit. | Pay for cost-per-click (**CPC**) | <details> <summary><strong>Example:</strong> App installs</summary> ```json {   "data": {     "name": "My App Installs Campaign",     "configured_status": "ACTIVE",     "objective": "APP_INSTALLS"   } } ``` </details> <details> <summary><strong>Example:</strong> Catalog sales</summary> ```json {   "data": {     "name": "My Catalog Campaign",     "configured_status": "ACTIVE",     "objective": "CATALOG_SALES"   } } ``` </details> <details> <summary><strong>Example:</strong> Conversions</summary> ```json {   "data": {     "name": "My Conversions Campaign",     "configured_status": "ACTIVE",     "objective": "CONVERSIONS"   } } ``` </details> <br> #### 2. Set up ad groups Granularly measure your campaign's performance and define audiences, targeting, and schedules for your ads using ad groups. You can create an ad group by calling the [`POST Create Ad Group`](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group) endpoint. The ad group ID will be listed in `id`. Save this value—you'll need this to create ads. <details> <summary><strong>Example:</strong> App installs</summary> `optimization_goal` is required for this campaign type. See all `optimization_goal` options in the [parameter examples](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group#request-body). > **Note:** Some required parameters may not be listed in the example. For full details, refer to the [endpoint documentation](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group). ```json {   "data": {     "campaign_id": "579922433862993631",     "name": "My App Installs Ad Group",     "app_id": "123456789",     "optimization_goal": "MOBILE_CONVERSION_INSTALL",     "bid_type": "CPC",     "bid_strategy": "MAXIMIZE_VOLUME",     "start_time": "2019-02-18T22:27:10Z",     "target": { "devices": [        {          "label_map": {            "Samsung": [              "Galaxy S9",              "Galaxy S10+"            ]          },          "max_version": "9",          "min_version": "8",          "os": "ANDROID",          "type": "DESKTOP"        }      ]     }   } } ``` </details> <details> <summary><strong>Example:</strong> Conversions</summary> `optimization_goal` is required for this campaign type and must match an existing event your Pixel is tracking. You can set this to `CLICKS` if your Pixel isn't set up. Custom events aren't supported. See all options in the [parameter examples](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group#request-body). > **Note:** Some required parameters may not be listed in the example. For full details, refer to the [endpoint documentation](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group). ```json { "data": {     "campaign_id": "579922433862993631",     "name": "My Conversions Ad Group",     "optimization_goal": "CLICKS",     "bid_type": "CPC",     "bid_strategy": "MAXIMIZE_VOLUME",     "start_time": "2019-02-18T22:27:10Z"   } } ``` </details> <details> <summary><strong>Example:</strong> Catalog sales</summary> Catalog ad groups require a `shopping_type` to specify whether ads are product or dynamic product ads. When using product filters, product\_set\_id can be provided to specify the product group. Learn how to [create product sets](https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Set). > **Note:** Some required parameters may not be listed in the example. For full details, refer to the [endpoint documentation](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group). ###### Dynamic product ads ```json {   "data": {     "campaign_id": "579922433862993631",     "name": "My DPA Ad Group",     "shopping_type": "DYNAMIC",     "shopping_targeting": {       "excluded_conversion_event_types": [        "VIEW_CONTENT"      ],      "targeting_type": "PROSPECTING",     },     "bid_type": "CPC",     "bid_strategy": "MAXIMIZE_VOLUME",     "start_time": "2019-02-18T22:27:10Z"    }   } ``` ###### Custom product ads ```json {   "data": {     "campaign_id": "579922433862993631",     "name": "My Product Ad Group",     "shopping_type": "STATIC",     "bid_type": "CPC",     "bid_strategy": "MAXIMIZE_VOLUME",     "start_time": "2019-02-18T22:27:10Z"    }   } ``` </details> <br> #### 4. Create a post > **Important:** Skip this step when creating catalog ads. Create the contents of your ad by calling `POST Create Post`. After creating your post, visit the `post_url` link to check your post looks right. If you need to make changes, create another post and copy the new post ID. The post ID will be listed in `id`. Save this value—you'll need this to create ads. ##### Reference | Type | Description | Additional required properties | | ---------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | | `CAROUSEL` | A post with up to 6 images. Each image can have a `caption`. | <ul><li>`content.caption`</li><li>`content.destination_url`</li></ul> | | `IMAGE` | A post with an image. | `content.destination_url` | | `TEXT` | A rich text post with inline links and media. Clicking or tapping it opens the post. | | | `VIDEO` | A post with a video. This can have a `destination_url`. | `thumbnail_url` | <details> <summary>Example</summary> > **Note:** For more details on setting these values, see [`Create Post`](https://ads-api.reddit.com/docs/v3/operations/Create%20Post). ```json {   "data": {     "content": [       {         "destination_url": "https://example.com",         "display_url": "https://example.com",         "media_url": "https://example.com/image.jpg"       }     ],     "headline": "Example post",     "thumbnail_url": "https://example.com/image.jpg",     "type": "IMAGE"   } } ``` </details> <br> #### 5. Build ads You can create ads using the Ads API to display on the Reddit platform. You can create an ad by calling the [`POST Create Ad`](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad) endpoint.  <details> <summary><strong>Example:</strong> Generic</summary> ```json {   "data": {     "ad_group_id": "142154364526",     "name": "My Ad",     "post_id": "t3_12345",     "click_url": "https://example.com",     "configured_status": "ACTIVE",     "preview_expiry": "2023-03-27T21:18:39.927000+00:00"   } } ``` </details> <details> <summary><strong>Example:</strong> Catalog sales</summary> The post for product ads is built with `shopping_creative`. Learn more about specific catalog parameters in [`POST Create Ad`](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad). ##### Dynamic product ad ```json {   "data": {     "ad_group_id": "142154364526",     "name": "My DPA",     "configured_status": "ACTIVE",     "profile_id": "t2_1234",     "shopping_creative": {       "allow_comments": false,       "call_to_action": "Shop Now",       "destination_url": "https://example.com/",       "headline": "Example ad",       "second_line_cta": "PRICE",       "dpa_carousel_mode": "AUTO"     }     "preview_expiry": "2023-03-27T21:18:39.927000+00:00"   } } ``` ##### Product ad ```json {   "data": {     "ad_group_id": "142154364526",     "name": "My Product Ad",     "configured_status": "ACTIVE",     "profile_id": "t2_1234",     "products": [       {         "product_id": "1234"       }     ],     "shopping_creative": {       "allow_comments": false,       "call_to_action": "Shop Now",       "destination_url": "https://example.com/",       "headline": "Example ad",       "second_line_cta": "PRICE"     }     "preview_expiry": "2023-03-27T21:18:39.927000+00:00"   } } ``` </details> <br> #### 6. Test your ad After building your ad, your ad will be reviewed. This process may take up to 48 business hours. Check your ad's status and rejection reason with [`GET Ad`](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad). We strongly recommend visiting the `preview_url` link to ensure your ad looks right. This preview will expire at the date and time listed in `preview_expiry`. > **Note:** You can set `preview_expiry` with [`PATCH Update Ad`](https://ads-api.reddit.com/docs/v3/operations/Update%20Ad). [Learn how to update this field](https://ads-api.reddit.com/docs/v3/#preview-an-ad). Once approved, monitor your ads at least once a week to optimize them: - [**Dashboard**](https://business.reddithelp.com/s/article/Reddit-Ads-reporting)**:** Measure impact and identify ways to improve your campaigns by viewing ad performance over time in the Ads Manager. - [`POST Get A Report`](https://ads-api.reddit.com/docs/v3/operations/Get%20A%20Report)**:** Generate a metrics report for up to three breakdowns based on the list of fields that you provide. Reports provide detailed insights and analytics on ad performance, audience engagement, and other relevant metrics. You can also use this endpoint to verify custom conversion events. </details> ### Preview an ad We strongly recommend previewing your ad to ensure it renders correctly in placements and as a post. <details> <summary>Learn more </summary> Ads built with the API can be tested in two ways: | | | | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Method | Description | Best for | | `preview_url` **(recommended)** | View your ad in an environment mirroring the ad’s real-life behavior. Only usable while `preview_expiry` is set and valid. | Validating tracking, analytics, ad performance, and reviewing placement. | | `post_url` | View your ad as a post. | Moderating comments or reviewing presentation. | You can retrieve both values with [GET Ad](https://ads-api.reddit.com/docs/v3/operations/Get%20Ad). > **Tip:** You can retrieve your ad’s ID with _More Tools > Copy ID_ [on the dashboard](https://ads.reddit.com/dashboard) or [GET List Ads](https://ads-api.reddit.com/docs/v3/operations/List%20Ads). #### Refresh preview expiration Use [PATCH Update Ad](https://ads-api.reddit.com/docs/v3/operations/Update%20Ad) to refresh your preview URL’s expiration date. This is required to generate `preview_url` initially. Provide a datetime within the next 30 days for `preview_expiry`. If this is the **first time** expiration has been set, open the Ads Manager and [generate its test URL](https://business.reddithelp.com/s/article/Generate-a-Test-Ad-URL-link). > **Note:** After refreshing, it may take up to 20 minutes for your ad to appear on your preview link. <details> <summary>Request body</summary> ```json "data": { "preview_expiry": "2025-03-27T21:18:39.927000+00:00" } ``` </details> <details> <summary>Example response</summary> ```json { "data": { "id": "2150528811614587268", ... "preview_expiry": "2025-11-14T15:32:29.080868+00:00", "preview_url": "https://www.reddit.com/?ad=kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D", ... } } ``` </details> <p></p> #### Preview on a specific post or community By default, `preview_url` shows your ad in the conversation placement on the Home feed. To test your ad on a specific post or community, append `?ad={{Your preview ID}}` to the URL. For example, if `preview_url` is: ``` https://www.reddit.com/?ad=kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D ``` You can use the same preview ID elsewhere: - **Preview ID:** `kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D` - **Preview on r/ramen:** `https://www.reddit.com/r/ramen/?ad=kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D` - **Preview on a post in r/ramen:** `https://www.reddit.com/r/ramen/comments/1nytqai/how_do_ramen_restaurants_make_their_ramen_so/?comments_ad=kR9wTqLzP5hA3cVnE7sGbUjM8fXyB6dK4aW2oP1iL0uYvJmQzR7tW5sF9eG1cHkO8rB3xNlD4pG6jVbCqI2gA9uYhTfE7lK5zM0wR8oPvB4cQ%3D` </details> ### Manage customer lists Custom Audiences allow you to reach a specific audience on Reddit based on data unique to your business, product, or service. It matches data using emails and mobile advertiser IDs. This helps you retarget future ads and continue the conversation with redditors who've engaged with your ads over the past 6 months. <details><summary>Learn more</summary> <br> #### Before you start - [Set up a Reddit Ads account](https://business.reddithelp.com/s/article/Create-and-manage-your-Reddit-Ads-account#N1) and [request access to the Ads API](https://www.redditforbusiness.com/api-partnership). - Find your ads account ID in [Accounts](https://ads.reddit.com/accounts). - Access a terminal application or Postman to send requests to the API. #### Create a custom audience Set up a custom audience using `POST Create Custom Audience`. After sending the request, you'll see the high and low estimates for the number of redditors in your audience. Your audience will be valid and usable if `size_range_upper >= 1000`. You can increase the audience size using direct upload or [`PATCH Update Custom Audience Users`](#update-users-in-your-custom-audience). The audience ID will be listed in `id`. Save this value—you'll need this to manage customers in your audience, use this audience in an ad group, or delete your audience. If you lose this value, you can call `GET List User Custom Audiences` to retrieve it again. <details><summary>Request body</summary> > **Note:** For more details on setting these values, see [`POST Create Custom Audience`](https://ads-api.reddit.com/docs/v3/operations/Create%20Custom%20Audience). ``` bash curl --request POST \ --url /api/v3/ad_account/{{Account ID}}/customer_lists \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "data": { "name": "{{Audience name}}", "type": "CUSTOMER_LIST" } }' ``` <br> </details> <details><summary>Example response</summary> ``` json { "data": { "id": "ca.129482487242828", "ad_account_id": "a2_abcdefg", "created_at": "2023-03-27T21:18:39Z", "modified_at": "2023-03-27T21:18:39Z", "name": "My Customer List 1", "size_range_lower": 140000, "size_range_upper": 160000, "status": "VALID", "type": "CUSTOMER_LIST" } } ``` </details> <br> #### Update users in your custom audience Manually add or remove users in a custom audience using `PATCH Update Custom Audience Users`. This requires sending each user's [SHA-256 hashed email, mobile advertising ID (MAID)](https://business.reddithelp.com/s/article/advanced-matching-for-developers), or both. You can manage up to 2,500 users per request. After sending the request, you'll receive an empty response (“`{}`”) if your request is valid. Audience size updates typically take up to 4 hours after the request is sent. You can check the size of your audience by calling `GET Get Custom Audience`. <details><summary>Request body</summary> > **Note:** For more details on setting these values, see [`PATCH Update Custom Audience Users`](https://ads-api.reddit.com/docs/v3/operations/Update%20Custom%20Audience%20Users). ``` json { "data": { "action_type": "{{ADD/REMOVE}}", "column_order": ["{{Column1}}", "{{Column2}}"], // e.g., ["EMAIL_SHA256", "MAID_SHA256"] "user_data": [ ["{{hashed email}}", "{{hashed MAID}}"] // based on column_order ] } } ``` </details> <br> </details> <details><summary>Troubleshooting</summary> Error | Solution -- | -- `400 - Type does not match support Audience Types` | Set `”type”` to `“CUSTOMER_LIST”` `401 - Unauthorized` | See [401 errors - Unauthorized](#401---unauthorized-1). `403 - Blocked` | Check that your user agent affects requests, then set your request's user agent header (`user-agent`) to a unique and descriptive string. `404 - Not found` | Check your ad account ID in the API request. `429 - Too many requests` | Set your request's user agent header (`user-agent`) to a unique and descriptive string or wait a few minutes before trying again. `500 - Internal server error` | An unspecified error has occurred. Try again later or [contact us](https://business.reddithelp.com/s/contactsupport) if this issue persists. `503 - Service unavailable` | The server is overloaded or down for maintenance. Try again later. #### 401 - Unauthorized Description | Solution -- | -- The client ID or secret key entered is invalid. | Verify and correct the client ID and secret key, then try again. User is trying to authorize with the wrong username.| Log out and log in to the correct account. User hasn't been authenticated, which can happen if you try to use a Reddit application without authentication. | [Create and authorize a Reddit Application](#create-a-developer-application). </details> ### Manage product catalogs Manage your products and categorize them into product sets for your [product ads](https://business.reddithelp.com/s/article/Product-Ads) and [dynamic product ads (DPAs)](https://business.reddithelp.com/s/article/dynamic-product-ads). <details> <summary>Learn more</summary> <br> #### Before you start - [Set up a Reddit Ads account](https://business.reddithelp.com/s/article/Create-and-manage-your-Reddit-Ads-account) and [request access to the Ads API](https://www.redditforbusiness.com/api-partnership). - Find your Pixel ID in [Accounts](https://ads.reddit.com/accounts). #### Set up a catalog Set up and manage product catalogs for your business. - [GET List Product Catalogs](https://ads-api.reddit.com/docs/v3/operations/List%20Product%20Catalogs) - [POST Create Product Catalog](https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Catalog) - [GET Product Catalog](https://ads-api.reddit.com/docs/v3/operations/Get%20Product%20Catalog) - [PATCH Update Product Catalog](https://ads-api.reddit.com/docs/v3/operations/Update%20Product%20Catalog) - [DELETE Product Catalog](https://ads-api.reddit.com/docs/v3/operations/Delete%20Product%20Catalog) #### Manage products There are several ways to manage products in your catalog: > **Tip:** Use [`GET List Products in Product Catalog`](https://ads-api.reddit.com/docs/v3/operations/List%20Products%20In%20Product%20Catalog) to view all the products in your catalog. <table> <thead> <tr> <th>Method</th> <th>Description</th> <th>Use case</th> </tr> </thead> <tbody> <tr> <td>Bulk import</td> <td> <p>Upload a file in the <a href="https://business.reddithelp.com/s/article/catalogs#2-add-items-to-your-catalog" target="_blank">Ads Manager</a> for a one-time update.</p> </td> <td> <p>Set up your initial catalog if you don't plan to update your catalog regularly. Not intended for ongoing updates.</p> </td> </tr> <tr> <td>Product feed</td> <td> <p>Sync products automatically using a hosted data feed. This feed overrides manual and bulk-import changes to ensure the catalog aligns with the latest feed data.</p> </td> <td> <p>Automate ongoing catalog updates.</p> </td> </tr> <tr> <td>Manual</td> <td> <p>Send an array with product details.</p> </td> <td> <p>Granular updates to your product metadata with REST API calls.</p> </td> </tr> </tbody> </table> ##### Product feed Create products for your catalog from a product feed hosted online. - [GET List Product Feeds](https://ads-api.reddit.com/docs/v3/operations/List%20Product%20Feeds) - [POST Create Product Feed](https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Feed) - [GET Product Feed](https://ads-api.reddit.com/docs/v3/operations/Get%20Product%20Feed) - [PATCH Update Product Feed](https://ads-api.reddit.com/docs/v3/operations/Update%20Product%20Feed) - [DELETE Product Feed](https://ads-api.reddit.com/docs/v3/operations/Delete%20Product%20Feed)  ##### Manual - [POST Batch Create Products](https://ads-api.reddit.com/docs/v3/operations/Batch%20Create%20Products) - [POST Batch Delete Products](https://ads-api.reddit.com/docs/v3/operations/Batch%20Delete%20Products) #### Organize products Categorize your products into product sets based on similar attributes. - [GET List Product Sets](https://ads-api.reddit.com/docs/v3/operations/List%20Product%20Sets) - [GET List Products in Product Set](https://ads-api.reddit.com/docs/v3/operations/List%20Products%20In%20Product%20Set) - [POST Create Product Set](https://ads-api.reddit.com/docs/v3/operations/Create%20Product%20Set) - [GET Product Set](https://ads-api.reddit.com/docs/v3/operations/Get%20Product%20Set) - [PATCH Update Product Set](https://ads-api.reddit.com/docs/v3/operations/Update%20Product%20Set) - [DELETE Product Set](https://ads-api.reddit.com/docs/v3/operations/Delete%20Product%20Set) ##### Filter rules Rules can be created using attribute and attribute operators.  ``` {"field":{"operator":"value"}} ``` These rules can be further combined using match operators. <details> <summary>Match operators</summary> Match operators specify the relationship between multiple conditions: ``` {"{{condition}}":[{{filter1}}, {{filter2}}]} ``` | Condition | Description | Example | |-----------|---------------------------|---------| | `and` | <p>All rules must be true</p> | <p>Title contains both `reddit` and `snoo`, and price is less than 1.00.</p><p>**Filter:** <code>{"and":[{"title":{"contains":"reddit"}},{"title":{"contains":"snoo"}},{"price":{"lt":"1.00"}}]}</code></p> | | `or` | <p>At least one rule is true</p> | <p>The product title contains `reddit` or `snoo`, or the product is in stock.</p><p>**Filter:** <code>{"or":[{"title":{"contains":"reddit"}},{"title":{"contains":"snoo"}},{"availability":{"eq":"IN_STOCK"}}]}</code></p> | </details> <details> <summary>Attributes</summary> Attributes are the fields that define your product. > **Note:** Learn more about our [catalog requirements](https://business.reddithelp.com/s/article/catalog-requirements). | Attributes | Description | |------------------|-------------| | `id` | <p>Unique identifier for the product</p> | | `title` | <p>Name of the product</p> | | `description` | <p>Detailed description of the product</p> | | `price` | <p>Cost of the product</p> | | `currency` | <p>Currency of the price.</p> | | `sale_price` | <p>Discounted price of the product</p> | | `availability` | <p>Availability status of the product. Must be one of the following:</p><ul><li>`IN_STOCK`</li><li>`OUT_OF_STOCK`</li><li>`PREORDER`</li><li>`BACKORDER`</li></ul> | | `brand` | <p>Brand of the product</p> | | `color` | <p>Color of the product</p> | | `gender` | <p>Gender the product is intended for. Must be one of the following:</p><ul><li>`MALE`</li><li>`FEMALE`</li><li>`UNISEX`</li></ul> | | `product_type` | <p>Type of product</p> | | `item_group_id` | <p>ID for grouping similar items</p> | | `condition` | <p>Condition of the product. Must be:</p><ul><li>`new`</li><li>`refurbished`</li><li>`used`</li></ul> | | `age_group` | <p>Age group the product is intended for. Must be:</p><ul><li>`newborn`</li><li>`infant`</li><li>`toddler`</li><li>`kids`</li><li>`adult`</li></ul> | | `size` | <p>Size of the product</p> | | `pattern` | <p>Pattern of the product</p> | | `material` | <p>Material the product is made from</p> | | `custom_label_0` | <p>Custom label 0</p> | | `custom_label_1` | <p>Custom label 1</p> | | `custom_label_2` | <p>Custom label 2</p> | | `custom_label_3` | <p>Custom label 3</p> | | `custom_label_4` | <p>Custom label 4</p> | </details> <details> <summary>Attribute operators</summary> Attribute operators define how to filter a specific attribute. > **Note:** All operators are case-sensitive unless otherwise noted. | Operator | Description | Examples | |------------------|------------------------------------------|----------| | `contains` | Substring contains text/number | <p>Title contains a substring of `red`.</p><p>**Rule:** <code>{"title":{"contains":"red"}}</code></p><ul><li>**True:** `red`, `reddit`</li><li>**False:** `Reddit`, `snoo`</li></ul> | | `not_contains` | No substring contains text/number | <p>Title doesn't contain a substring of `red`.</p><p>**Rule:** <code>{"title":{"not_contains":"red"}}</code></p><ul><li>**True:** `Reddit`, `snoo`</li><li>**False:** `red`, `reddit`</li></ul> | | `i_contains` | Substring contains (case-insensitive) | <p>Title contains a substring of `red` (case-insensitive).</p><p>**Rule:** <code>{"title":{"i_contains":"red"}}</code></p><ul><li>**True:** `Reddit`, `reddit`, `Red`</li><li>**False:** `snoo`</li></ul> | | `i_not_contains` | No substring contains (case-insensitive) | <p>Title doesn't contain a substring of `red` (case-insensitive).</p><p>**Rule:** <code>{"title":{"i_not_contains":"red"}}</code></p><ul><li>**True:** `snoo`</li><li>**False:** `Reddit`, `red`, `Red`</li></ul> | | `starts_with` | Starts with exact text/number | <p>Title starts with `snoo`.</p><p>**Rule:** <code>{"title":{"starts_with":"snoo"}}</code></p><ul><li>**True:** `snoo`, `snoo alien`</li><li>**False:** `Snoo`, `reddit snoo`</li></ul> | | `i_starts_with` | Starts with (case-insensitive) | <p>Title starts with `snoo` (case-insensitive).</p><p>**Rule:** <code>{"title":{"starts_with":"snoo"}}</code></p><ul><li>**True:** `snoo`, `Snoo`, `snoo alien`</li><li>**False:** `reddit snoo`</li></ul> | | `is_any` | Matches one of the values | <p>Title matches `snoo` or `reddit`.</p><p>**Rule:** <code>{"title":{"is_any":["snoo","reddit"]}}</code></p><ul><li>**True:** `snoo`, `reddit`</li><li>**False:** `snoo alien`, `Snoo`</li></ul> | | `is_not_any` | Does not match the values | <p>Title doesn't match `snoo` or `reddit`.</p><p>**Rule:** <code>{"title":{"is_not_any":["snoo","reddit"]}}</code></p><ul><li>**True:** `snoo alien`, `Snoo`</li><li>**False:** `snoo`, `reddit`</li></ul> | | `i_is_any` | Matches one value (case-insensitive) | <p>Title matches `snoo` or `reddit` (case-insensitive).</p><p>**Rule:** <code>{"title":{"i_is_any":["snoo","reddit"]}}</code></p><ul><li>**True:** `snoo`, `Snoo`, `reddit`</li><li>**False:** `snoo alien`</li></ul> | | `i_is_not_any` | Doesn't match values (case-insensitive) | <p>Title doesn't match `snoo` or `reddit` (case-insensitive).</p><p>**Rule:** <code>{"title":{"i_is_not_any":["snoo","reddit"]}}</code></p><ul><li>**True:** `snoo alien`</li><li>**False:** `Snoo`, `snoo`, `reddit`</li></ul> | | `eq` | Value is equal to | <p>Gender equals `UNISEX`.</p><p>**Rule:** <code>{"gender":{"eq":"UNISEX"}}</code></p><ul><li>**True:** `UNISEX`</li><li>**False:** `MALE`, `FEMALE`</li></ul> | | `neq` | Value is not equal to | <p>Product isn't in stock.</p><p>**Rule:** <code>{"availability":{"neq":"IN_STOCK"}}</code></p><ul><li>**True:** `OUT_OF_STOCK`, `PREORDER`</li><li>**False:** `IN_STOCK`</li></ul> | | `lt` | Value is less than | <p>Cost is less than 1.00.</p><p>**Rule:** <code>{"price":{"lt":"1.00"}}</code></p><ul><li>**True:** `-1`, `0`</li><li>**False:** `1`, `2`</li></ul> | | `lte` | Value is less than or equal to | <p>Cost is less than or equal to 1.00.</p><p>**Rule:** <code>{"price":{"lte":"1.00"}}</code></p><ul><li>**True:** `-1`, `0`, `1`</li><li>**False:** `2`</li></ul> | | `gt` | Value is greater than | <p>Cost is greater than 1.00.</p><p>**Rule:** <code>{"price":{"gt":"1.00"}}</code></p><ul><li>**True:** `2`</li><li>**False:** `-1`, `0`, `1`</li></ul> | | `gte` | Value is greater than or equal to | <p>Cost is greater than or equal to 1.00.</p><p>**Rule:** <code>{"price":{"gte":"1.00"}}</code></p><ul><li>**True:** `1`, `2`</li><li>**False:** `-1`, `0`</li></ul> | </details> <br> #### Create product ads Create product or dynamic product ads based on your catalog. > **Note:** Learn how to [set up a campaign](https://ads-api.reddit.com/docs/v3/#set-up-a-campaign). - [POST Create Campaign](https://ads-api.reddit.com/docs/v3/operations/Create%20Campaign) - [POST Create Ad Group](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad%20Group) - [POST Create Ad](https://ads-api.reddit.com/docs/v3/operations/Create%20Ad) #### Troubleshooting Retrieve import reports and diagnose catalog issues. Use these endpoints with [product diagnostics](https://business.reddithelp.com/s/article/troubleshoot-catalogs) and [DPA readiness](https://business.reddithelp.com/s/article/dpa-readiness) for troubleshooting. - [GET List Catalog Imports](https://ads-api.reddit.com/docs/v3/operations/List%20Catalog%20Imports) - [GET Catalog Import Report](https://ads-api.reddit.com/docs/v3/operations/Get%20Catalog%20Import%20Report) - [GET List Catalog Import Issues](https://ads-api.reddit.com/docs/v3/operations/List%20Catalog%20Import%20Issues) </details>