Reddit Funding Instruments API

openapi: 3.2.0
info:
  title: Reddit Advertising Funding Instruments API
  version: '3'
  x-logo:
    url: https://www.redditstatic.com/desktop2x/img/favicon/favicon-32x32.png
  description: '## 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 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, Developer Terms, and 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 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**. Get started with the API. API partners working on behalf of advertisers can request support by contacting us. See our supported partners. ## 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. All API applications must be authenticated with OAuth2 by creating a developer application and obtaining access and refresh tokens. !v3 ERD diagram


    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. - **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. Example


    ```

    User-Agent: android:com.example.myredditapp:v1.2.3 (by /u/kemitche)

    ```


    > **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.'
servers:
- url: https://ads-api.reddit.com/api/v3
  description: Reddit AdsAPI Production
tags:
- name: Funding Instruments
  description: Information about funding instruments.
paths:
  /ad_accounts/{ad_account_id}/funding_instruments:
    get:
      description: 'Retrieve funding instruments used by an ad account.

        Rate Limit


        See the rate limits for Billing


        Policy Slug: ads-funding-instruments


        Window: 60 seconds


        Quota: 30 requests'
      summary: List Funding Instruments
      operationId: list_account_funding_instruments
      parameters:
      - description: The ad account ID.
        in: path
        name: ad_account_id
        required: true
        schema:
          type: string
      - description: Filter by funding instrument IDs.
        in: query
        name: funding_instrument_ids
        style: form
        explode: false
        required: false
        example:
        - '246'
        - '12345'
        schema:
          type: array
          items:
            type: string
      - description: Filter by funding instrument types.
        in: query
        name: types
        style: form
        explode: false
        required: false
        example:
        - SELF_SERVE
        - CREDIT_LINE
        schema:
          type: array
          items:
            type: string
      - description: Start of the time window for filtering funding instruments ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
        in: query
        name: start_time
        required: false
        example: '2025-01-09T04:00:00Z'
        schema:
          type: string
          format: date-time
      - description: End of the time window for filtering funding instruments ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
        in: query
        name: end_time
        required: false
        example: '2025-02-09T04:00:00Z'
        schema:
          type:
          - string
          format: date-time
      - description: Search text.
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Filter by status.
        in: query
        name: mode
        required: false
        example: ACTIVE
        schema:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - UPCOMING
          - SELECTABLE
          - ALL
          x-enumDescriptions:
            ACTIVE: Funds in effect now. `start_time` is missing or in the past, `end_time` is missing or in the future, and the instrument was not deactivated by an admin.
            INACTIVE: Funds no longer available. `end_time` is in the past or the instrument was deactivated by an admin.
            UPCOMING: Funds not yet in effect. `start_time` is in the future and the instrument was not deactivated by an admin.
            SELECTABLE: Default. Same as `ACTIVE`, or `UPCOMING` with a `start_time` within the next 30 days. Not admin-deactivated.
            ALL: Every funding instrument on the ad account.
      - description: Deprecated. Use `mode=SELECTABLE` or `mode=ALL` instead.
        in: query
        name: is_selectable
        required: false
        schema:
          type: boolean
        deprecated: true
      - $ref: '#/components/parameters/components_parameters_page_token'
      - $ref: '#/components/parameters/components_parameters_page_size'
      responses:
        '200':
          description: A list of funding instruments.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                title: ListFundingInstrumentsResponseBody
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    title: FundingInstrumentsList
                    items:
                      $ref: '#/components/schemas/components_schema_funding_instrument'
                  pagination:
                    $ref: '#/components/schemas/components_schema_pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - RedditAPIKey:
        - adsread
      tags:
      - Funding Instruments
  /businesses/{business_id}/funding_instruments/query:
    post:
      description: 'Find funding instruments in a business.

        Rate Limit


        See the rate limits for Billing


        Policy Slug: ads-funding-instruments


        Window: 60 seconds


        Quota: 30 requests'
      summary: Query Funding Instruments by Business
      operationId: query_business_funding_instruments
      parameters:
      - description: The business ID.
        in: path
        name: business_id
        required: true
        schema:
          type: string
          format: uuid
          example: 1e200a0b-4e98-32cc-dd47-3006e4c85bb2
      - description: Filter funding instruments by a value that matches any field in the response, including `name`, `id`, or `type`.
        in: query
        example: My Funding Instrument
        name: search
        required: false
        explode: false
        style: form
        schema:
          type: string
      - $ref: '#/components/parameters/components_parameters_page_token'
      - $ref: '#/components/parameters/components_parameters_page_size'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: object
                  additionalProperties: false
                  title: QueryFundingInstrumentsRequestBody
                  properties:
                    partner_business_id:
                      type:
                      - string
                      - 'null'
                      description: Filter by the ID of the [partner business](https://business.reddithelp.com/s/article/partner-sharing) associated with the funding instrument.
                    funding_instrument_ids:
                      type: array
                      items:
                        type: string
                      example:
                      - '246'
                      - '12345'
                      description: Filter by funding instrument IDs.
                    mode:
                      type: string
                      description: The funding instrument inclusion mode. Defaults to `ACTIVE`.
                      enum:
                      - ACTIVE
                      - ALL
                      x-enumDescriptions:
                        ACTIVE: Include only active credit lines.
                        ALL: Include all credit lines.
      responses:
        '200':
          description: A list of funding instruments.
          content:
            application/json:
              schema:
                type: object
                title: QueryFundingInstrumentsResponse
                additionalProperties: false
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    title: FundingInstrumentsList
                    items:
                      $ref: '#/components/schemas/components_schema_funding_instrument'
                  pagination:
                    $ref: '#/components/schemas/components_schema_pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - RedditAPIKey:
        - adsread
      tags:
      - Funding Instruments
  /funding_instruments/{funding_instrument_id}/allocations:
    get:
      description: 'Retrieve funding instrument allocations.

        Rate Limit


        See the rate limits for Billing


        Policy Slug: ads-funding-instruments


        Window: 60 seconds


        Quota: 30 requests'
      summary: Get Child Funding Instruments
      operationId: get_child_funding_instruments
      parameters:
      - description: The funding instrument ID.
        in: path
        name: funding_instrument_id
        required: true
        schema:
          type: string
          format: int64
          example: '12345'
      - $ref: '#/components/parameters/components_parameters_page_size'
      - $ref: '#/components/parameters/components_parameters_page_token'
      responses:
        '200':
          description: A list of allocations.
          content:
            application/json:
              schema:
                type: object
                title: ListAllocationsByFundingInstrumentResponse
                additionalProperties: false
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    title: FundingInstrumentAllocationsList
                    items:
                      $ref: '#/components/schemas/components_schema_funding_instrument'
                  pagination:
                    $ref: '#/components/schemas/components_schema_pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
      - RedditAPIKey:
        - adsread
      tags:
      - Funding Instruments
components:
  schemas:
    components_errors_404:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - message
          additionalProperties: false
          properties:
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Member ID not found
            code:
              type: integer
              description: The error code.
              examples:
              - 404
    components_errors_429:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            code:
              type: integer
              description: The error code.
              examples:
              - 429
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Too Many Requests
    components_errors_400:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - message
          additionalProperties: false
          properties:
            code:
              type: integer
              description: The error code.
              examples:
              - 400
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Bad request.
            fields:
              title: FieldsList
              type: array
              items:
                type: object
                required:
                - field
                - message
                additionalProperties: false
                properties:
                  field:
                    title: FieldName
                    type: string
                    description: The field that caused the error.
                    examples:
                    - field_name
                  message:
                    type: string
                    description: A human friendly error message.
                    examples:
                    - Invalid value.
              description: The fields that caused the error.
    components_enums_billing_currency:
      type: string
      description: The currency used in this invoice ([ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)).
      enum:
      - USD
      - GBP
      - CAD
      - EUR
      - AUD
      - NZD
      - SGD
      - BRL
      examples:
      - USD
    components_schema_pagination:
      type: object
      additionalProperties: false
      properties:
        next_url:
          description: 'The full URL for the next page. If not available, the current page is the final page.

            > **Important:** The URL should be followed directly. Don''t assume pagination based on the query parameters in the provided URLs.

            '
          example: https://ads-api.reddit.com/api/v3?page.token=nextToken
          type:
          - string
          - 'null'
          readOnly: true
        previous_url:
          description: 'The full URL for the previous page. If not available, the current page is the first page.

            > **Important:** The URL should be followed directly. Don''t assume pagination based on the query parameters in the provided URLs.

            '
          example: https://ads-api.reddit.com/api/v3?page.token=previousToken
          type:
          - string
          - 'null'
          readOnly: true
    components_errors_403:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - message
          additionalProperties: false
          properties:
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Access not granted for listing profiles.
            code:
              type: integer
              description: The error code.
              examples:
              - 403
    components_errors_500:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - message
          additionalProperties: false
          properties:
            code:
              type: integer
              description: The error code.
              examples:
              - 500
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Internal Server Error
    components_errors_401:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - message
          additionalProperties: false
          properties:
            message:
              type: string
              description: A human friendly error message.
              examples:
              - Bad bearer token provided.
            code:
              type: integer
              description: The error code.
              examples:
              - 401
    components_schema_funding_instrument:
      title: Funding Instrument
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The funding instrument ID.
          examples:
          - '604212'
        name:
          type:
          - string
          - 'null'
          description: The funding instrument's name.
          examples:
          - Acme Winter Promo 2023-Q4 Auction
        currency:
          $ref: '#/components/schemas/components_enums_billing_currency'
        credit_limit:
          type: integer
          description: The maximum amount this funding instrument can spend before campaigns linked to it won't run.
          examples:
          - 1000000000
        billable_amount:
          type: integer
          description: The funding instrument's current outstanding debt (local microcurrency).
          examples:
          - 596086656
        start_time:
          type:
          - string
          - 'null'
          description: When set, campaigns using this funding instrument won't deliver until this time or later ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
          examples:
          - '2024-04-01T04:00:00Z'
          format: date-time
        end_time:
          type:
          - string
          - 'null'
          description: When set, campaigns using this funding instrument won't deliver after this time ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
          examples:
          - '2024-05-01T04:00:00Z'
          format: date-time
        is_servable:
          type: boolean
          description: Whether campaigns linked to this funding instrument are allowed to run.
        reasons_not_servable:
          type: array
          description: Why this funding instrument is not servable. When empty, it is servable.
          items:
            type: string
            enum:
            - DATES_OUT_OF_RANGE
            - CREDIT_LINE_EXHAUSTED
            - CREDIT_CARD_NOT_APPROVED
            - NOT_ACTIVE
            - TEST
          examples:
          - - CREDIT_LINE_EXHAUSTED
            - DATES_OUT_OF_RANGE
        invoice_group_status:
          type:
          - string
          - 'null'
          description: Status indicating the eligibility or issues with the invoice group.
          examples:
          - ELIGIBLE
          enum:
          - ELIGIBLE
          - NO_ACTIVE_CL_FOUND
          - MULTI_BILL_ENTITY_FOUND
          - MULTI_PO_FOUND
          - MULTI_PAY_TERMS_FOUND
          - MULTI_OPPORTUNITY_FOUND
          - null
        authorize_status:
          type:
          - string
          - 'null'
          description: The state of the credit card attachment. Applies only for `SELF_SERVE` funding instruments.
          x-enumDescriptions:
            PENDING: The credit card attachment is waiting for authorization.
            APPROVED: The credit card attachment is authorized for use.
            DECLINE_RETRYABLE: Authorization failed temporarily and may be retried.
            DECLINE_TERMINAL: Authorization failed permanently and should not be retried.
          enum:
          - PENDING
          - APPROVED
          - DECLINE_RETRYABLE
          - DECLINE_TERMINAL
          - null
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_400'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_404'
    Unauthorized:
      description: No bearer token or a bad bearer token was provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_401'
    TooManyRequests:
      description: Too many requests. See [Rate Limiting](/docs/v3/guides/quick-start/rate-limiting) for header details and best practices.
      headers:
        RateLimit-Policy:
          description: The rate limit policies that apply to this request (IETF "RateLimit header fields for HTTP" draft). Each comma-separated policy is keyed by a public policy name and lists its quota `q` and window in seconds `w`.
          schema:
            type: string
            examples:
            - '"custom-audience-ingestion";q=3000;w=900,"custom-audience-ingestion-burst";q=500;w=60'
        RateLimit:
          description: 'The current rate limit state for each applicable policy (IETF "RateLimit header fields for HTTP" draft): remaining quota `r` and seconds until the window resets `t`. On a 429 the exhausted policy reports `r=0`.'
          schema:
            type: string
            examples:
            - '"custom-audience-ingestion";r=0;t=42,"custom-audience-ingestion-burst";r=0;t=5'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_429'
    ServerError:
      description: Server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_500'
    Forbidden:
      description: Insufficient authentication scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/components_errors_403'
  parameters:
    components_parameters_page_token:
      description: The token for the page to retrieve.
      in: query
      name: page.token
      schema:
        type: string
    components_parameters_page_size:
      description: The number of items to be returned by page.
      in: query
      name: page.size
      allowEmptyValue: true
      schema:
        type: integer
        maximum: 1000
  securitySchemes:
    RedditAPIKey:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.reddit.com/api/v1/authorize
          refreshUrl: https://www.reddit.com/api/v1/access_token
          tokenUrl: https://www.reddit.com/api/v1/access_token
          scopes:
            adsconversions: Post conversion events through the API
            adsread: Read advertising data through my account.
            adsedit: Write advertising data through my account.
            adsdatadeletion: Delete advertising data through my account.
      description: Reddit OAuth2 Security Key