Stripe Search API

openapi: 3.2.0
info:
  title: Stripe Accounts Account Search API
  description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
  contact:
    email: dev-platform@stripe.com
    name: Stripe Dev Platform Team
    url: https://stripe.com
  termsOfService: https://stripe.com/us/terms/
  version: '2023-10-16'
  x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Search
paths:
  /v1/customers/search:
    get:
      description: '<p>Search for customers you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.

        Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating

        conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up

        to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
      operationId: getCustomersSearch
      parameters:
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
        in: query
        name: page
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for customers](https://stripe.com/docs/search#query-fields-for-customers).
        in: query
        name: query
        required: true
        schema:
          maxLength: 5000
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetCustomersSearchRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/SearchResult'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Customers Search
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Search
  /v1/invoices/search:
    get:
      description: '<p>Search for invoices you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.

        Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating

        conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up

        to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
      operationId: getInvoicesSearch
      parameters:
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
        in: query
        name: page
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for invoices](https://stripe.com/docs/search#query-fields-for-invoices).
        in: query
        name: query
        required: true
        schema:
          maxLength: 5000
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetInvoicesSearchRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/SearchResult_2'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Invoices Search
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Search
  /v1/payment_intents/search:
    get:
      description: '<p>Search for PaymentIntents you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.

        Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating

        conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up

        to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
      operationId: getPaymentIntentsSearch
      parameters:
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
        in: query
        name: page
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for payment intents](https://stripe.com/docs/search#query-fields-for-payment-intents).
        in: query
        name: query
        required: true
        schema:
          maxLength: 5000
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPaymentIntentsSearchRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/SearchResult_3'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Payment Intents Search
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Search
  /v1/prices/search:
    get:
      description: '<p>Search for prices you’ve previously created using Stripe’s <a href="/docs/search#search-query-language">Search Query Language</a>.

        Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating

        conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up

        to an hour behind during outages. Search functionality is not available to merchants in India.</p>'
      operationId: getPricesSearch
      parameters:
      - description: Specifies which fields in the response should be expanded.
        explode: true
        in: query
        name: expand
        required: false
        schema:
          items:
            maxLength: 5000
            type: string
          type: array
        style: deepObject
      - description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.
        in: query
        name: page
        required: false
        schema:
          maxLength: 5000
          type: string
        style: form
      - description: The search query string. See [search query language](https://stripe.com/docs/search#search-query-language) and the list of supported [query fields for prices](https://stripe.com/docs/search#query-fields-for-prices).
        in: query
        name: query
        required: true
        schema:
          maxLength: 5000
          type: string
        style: form
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              additionalProperties: false
              $ref: '#/components/schemas/GetPricesSearchRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: ''
                x-expandableFields:
                - data
                $ref: '#/components/schemas/SearchResult_4'
          description: Successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
          description: Error response.
      summary: Stripe Get   Prices Search
      x-api-evangelist-processing:
        GenerateOperationSummariesFromPath: true
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        ChooseTags: true
      tags:
      - Search
components:
  schemas:
    customer:
      description: 'This object represents a customer of your business. Use it to create recurring charges and track payments that belong to the same customer.


        Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)'
      properties:
        address:
          anyOf:
          - $ref: '#/components/schemas/address'
          description: The customer's address.
        balance:
          description: The current balance, if any, that's stored on the customer. If negative, the customer has credit to apply to their next invoice. If positive, the customer has an amount owed that's added to their next invoice. The balance only considers amounts that Stripe hasn't successfully applied to any invoice. It doesn't reflect unpaid invoices. This balance is only taken into account after invoices finalize.
          type: integer
        cash_balance:
          anyOf:
          - $ref: '#/components/schemas/cash_balance'
          description: The current funds being held by Stripe on behalf of the customer. You can apply these funds towards payment intents when the source is "cash_balance". The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        currency:
          description: Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
          maxLength: 5000
          type:
          - string
          - 'null'
        default_source:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/bank_account'
          - $ref: '#/components/schemas/card'
          - $ref: '#/components/schemas/source'
          description: 'ID of the default payment source for the customer.


            If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.'
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/bank_account'
            - $ref: '#/components/schemas/card'
            - $ref: '#/components/schemas/source'
          x-stripeBypassValidation: true
        delinquent:
          description: 'Tracks the most recent state change on any invoice belonging to the customer. Paying an invoice or marking it uncollectible via the API will set this field to false. An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.


            If an invoice becomes uncollectible by [dunning](https://stripe.com/docs/billing/automatic-collection), `delinquent` doesn''t reset to `false`.


            If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead. Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.'
          type:
          - boolean
          - 'null'
        description:
          description: An arbitrary string attached to the object. Often useful for displaying to users.
          maxLength: 5000
          type:
          - string
          - 'null'
        discount:
          anyOf:
          - $ref: '#/components/schemas/discount'
          description: Describes the current discount active on the customer, if there is one.
        email:
          description: The customer's email address.
          maxLength: 5000
          type:
          - string
          - 'null'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        invoice_credit_balance:
          additionalProperties:
            type: integer
          description: The current multi-currency balances, if any, that's stored on the customer. If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency. If negative, the customer has an amount owed that's added to their next invoice denominated in that currency. These balances don't apply to unpaid invoices. They solely track amounts that Stripe hasn't successfully applied to any invoice. Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
          type: object
        invoice_prefix:
          description: The prefix for the customer used to generate unique invoice numbers.
          maxLength: 5000
          type:
          - string
          - 'null'
        invoice_settings:
          $ref: '#/components/schemas/invoice_setting_customer_setting'
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          type: object
        name:
          description: The customer's full name or business name.
          maxLength: 5000
          type:
          - string
          - 'null'
        next_invoice_sequence:
          description: The suffix of the customer's next invoice number (for example, 0001).
          type: integer
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - customer
          type: string
        phone:
          description: The customer's phone number.
          maxLength: 5000
          type:
          - string
          - 'null'
        preferred_locales:
          description: The customer's preferred locales (languages), ordered by preference.
          items:
            maxLength: 5000
            type: string
          type:
          - array
          - 'null'
        shipping:
          anyOf:
          - $ref: '#/components/schemas/shipping'
          description: Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
        sources:
          description: The customer's payment sources, if any.
          properties:
            data:
              description: Details about each object.
              items:
                anyOf:
                - $ref: '#/components/schemas/bank_account'
                - $ref: '#/components/schemas/card'
                - $ref: '#/components/schemas/source'
                title: Polymorphic
                x-stripeBypassValidation: true
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: ApmsSourcesSourceList
          type: object
          x-expandableFields:
          - data
        subscriptions:
          description: The customer's current subscriptions, if any.
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/subscription'
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: SubscriptionList
          type: object
          x-expandableFields:
          - data
        tax:
          $ref: '#/components/schemas/customer_tax'
        tax_exempt:
          description: 'Describes the customer''s tax exemption status, which is `none`, `exempt`, or `reverse`. When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.'
          enum:
          - exempt
          - none
          - reverse
          type:
          - string
          - 'null'
        tax_ids:
          description: The customer's tax IDs.
          properties:
            data:
              description: Details about each object.
              items:
                $ref: '#/components/schemas/tax_id'
              type: array
            has_more:
              description: True if this list has another page of items after this one that can be fetched.
              type: boolean
            object:
              description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
              enum:
              - list
              type: string
            url:
              description: The URL where this list can be accessed.
              maxLength: 5000
              type: string
          required:
          - data
          - has_more
          - object
          - url
          title: TaxIDsList
          type: object
          x-expandableFields:
          - data
        test_clock:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/test_helpers.test_clock'
          description: ID of the test clock that this customer belongs to.
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/test_helpers.test_clock'
      required:
      - created
      - id
      - livemode
      - object
      title: Customer
      type: object
      x-expandableFields:
      - address
      - cash_balance
      - default_source
      - discount
      - invoice_settings
      - shipping
      - sources
      - subscriptions
      - tax
      - tax_ids
      - test_clock
      x-resourceId: customer
    SearchResult:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/customer'
          type: array
        has_more:
          type: boolean
        next_page:
          maxLength: 5000
          type:
          - string
          - 'null'
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - search_result
          type: string
        total_count:
          description: The total number of objects that match the query, only accurate up to 10,000.
          type: integer
        url:
          maxLength: 5000
          type: string
    SearchResult_4:
      type: object
      required:
      - data
      - has_more
      - object
      - url
      properties:
        data:
          items:
            $ref: '#/components/schemas/price'
          type: array
        has_more:
          type: boolean
        next_page:
          maxLength: 5000
          type:
          - string
          - 'null'
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - search_result
          type: string
        total_count:
          description: The total number of objects that match the query, only accurate up to 10,000.
          type: integer
        url:
          maxLength: 5000
          type: string
    payment_method:
      description: 'PaymentMethod objects represent your customer''s payment instruments.

        You can use them with [PaymentIntents](https://stripe.com/docs/payments/payment-intents) to collect payments or save them to

        Customer objects to store instrument details for future payments.


        Related guides: [Payment Methods](https://stripe.com/docs/payments/payment-methods) and [More Payment Scenarios](https://stripe.com/docs/payments/more-payment-scenarios).'
      properties:
        acss_debit:
          $ref: '#/components/schemas/payment_method_acss_debit'
        affirm:
          $ref: '#/components/schemas/payment_method_affirm'
        afterpay_clearpay:
          $ref: '#/components/schemas/payment_method_afterpay_clearpay'
        alipay:
          $ref: '#/components/schemas/payment_flows_private_payment_methods_alipay'
        au_becs_debit:
          $ref: '#/components/schemas/payment_method_au_becs_debit'
        bacs_debit:
          $ref: '#/components/schemas/payment_method_bacs_debit'
        bancontact:
          $ref: '#/components/schemas/payment_method_bancontact'
        billing_details:
          $ref: '#/components/schemas/billing_details'
        blik:
          $ref: '#/components/schemas/payment_method_blik'
        boleto:
          $ref: '#/components/schemas/payment_method_boleto'
        card:
          $ref: '#/components/schemas/payment_method_card'
        card_present:
          $ref: '#/components/schemas/payment_method_card_present'
        cashapp:
          $ref: '#/components/schemas/payment_method_cashapp'
        created:
          description: Time at which the object was created. Measured in seconds since the Unix epoch.
          format: unix-time
          type: integer
        customer:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/customer'
          description: The ID of the Customer to which this PaymentMethod is saved. This will not be set when the PaymentMethod has not been saved to a Customer.
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/customer'
        customer_balance:
          $ref: '#/components/schemas/payment_method_customer_balance'
        eps:
          $ref: '#/components/schemas/payment_method_eps'
        fpx:
          $ref: '#/components/schemas/payment_method_fpx'
        giropay:
          $ref: '#/components/schemas/payment_method_giropay'
        grabpay:
          $ref: '#/components/schemas/payment_method_grabpay'
        id:
          description: Unique identifier for the object.
          maxLength: 5000
          type: string
        ideal:
          $ref: '#/components/schemas/payment_method_ideal'
        interac_present:
          $ref: '#/components/schemas/payment_method_interac_present'
        klarna:
          $ref: '#/components/schemas/payment_method_klarna'
        konbini:
          $ref: '#/components/schemas/payment_method_konbini'
        link:
          $ref: '#/components/schemas/payment_method_link'
        livemode:
          description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
          type: boolean
        metadata:
          additionalProperties:
            maxLength: 500
            type: string
          description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          type:
          - object
          - 'null'
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - payment_method
          type: string
        oxxo:
          $ref: '#/components/schemas/payment_method_oxxo'
        p24:
          $ref: '#/components/schemas/payment_method_p24'
        paynow:
          $ref: '#/components/schemas/payment_method_paynow'
        paypal:
          $ref: '#/components/schemas/payment_method_paypal'
        pix:
          $ref: '#/components/schemas/payment_method_pix'
        promptpay:
          $ref: '#/components/schemas/payment_method_promptpay'
        radar_options:
          $ref: '#/components/schemas/radar_radar_options'
        revolut_pay:
          $ref: '#/components/schemas/payment_method_revolut_pay'
        sepa_debit:
          $ref: '#/components/schemas/payment_method_sepa_debit'
        sofort:
          $ref: '#/components/schemas/payment_method_sofort'
        type:
          description: The type of the PaymentMethod. An additional hash is included on the PaymentMethod with a name matching this value. It contains additional information specific to the PaymentMethod type.
          enum:
          - acss_debit
          - affirm
          - afterpay_clearpay
          - alipay
          - au_becs_debit
          - bacs_debit
          - bancontact
          - blik
          - boleto
          - card
          - card_present
          - cashapp
          - customer_balance
          - eps
          - fpx
          - giropay
          - grabpay
          - ideal
          - interac_present
          - klarna
          - konbini
          - link
          - oxxo
          - p24
          - paynow
          - paypal
          - pix
          - promptpay
          - revolut_pay
          - sepa_debit
          - sofort
          - us_bank_account
          - wechat_pay
          - zip
          type: string
          x-stripeBypassValidation: true
        us_bank_account:
          $ref: '#/components/schemas/payment_method_us_bank_account'
        wechat_pay:
          $ref: '#/components/schemas/payment_method_wechat_pay'
        zip:
          $ref: '#/components/schemas/payment_method_zip'
      required:
      - billing_details
      - created
      - id
      - livemode
      - object
      - type
      title: PaymentMethod
      type: object
      x-expandableFields:
      - acss_debit
      - affirm
      - afterpay_clearpay
      - alipay
      - au_becs_debit
      - bacs_debit
      - bancontact
      - billing_details
      - blik
      - boleto
      - card
      - card_present
      - cashapp
      - customer
      - customer_balance
      - eps
      - fpx
      - giropay
      - grabpay
      - ideal
      - interac_present
      - klarna
      - konbini
      - link
      - oxxo
      - p24
      - paynow
      - paypal
      - pix
      - promptpay
      - radar_options
      - revolut_pay
      - sepa_debit
      - sofort
      - us_bank_account
      - wechat_pay
      - zip
      x-resourceId: payment_method
    subscription:
      description: 'Subscriptions allow you to charge a customer on a recurring basis.


        Related guide: [Creating subscriptions](https://stripe.com/docs/billing/subscriptions/creating)'
      properties:
        application:
          anyOf:
          - maxLength: 5000
            type: string
          - $ref: '#/components/schemas/application'
          - $ref: '#/components/schemas/deleted_application'
          description: ID of the Connect Application that created the subscription.
          x-expansionResources:
            oneOf:
            - $ref: '#/components/schemas/application'
            - $ref: '#/components/schemas/deleted_application'
        application_fee_percent:
          description: A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.
          type:
          - number
          - 'null'
        automatic_tax:
          $ref: '#/components/schemas/subscription_automatic_tax'
        billing_cycle_anchor:
          description: Determines the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices. The timestamp is in UTC format.
          format: unix-tim

# --- truncated at 32 KB (133 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-search-api-openapi.yml