Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

Stripe Collectors

Overview

DataBlend collects the following Stripe object types: Balance Transactions, Charges, Checkouts, Checkout Sessions, Coupons, Credit Notes, Customers, Disputes, Events, Invoices, Invoice Items, Invoice Line Items, Invoice Payments, Payment Intents, Payment Intent Line Items, Payment Links, Payouts, Prices, Products, Promo Codes, Refunds, Reports, Search Payment Intents, Subscriptions, and Subscription Items.

The older "… By ID" object types (Customer By ID, Invoice By ID, Invoice Items By ID, Payout By ID) no longer appear in the list. Their job is now done by the optional IDs field on the matching list collector, for example Invoice IDs on the Invoices collector.

Configuration

Field

Required / Optional

Comments

Type

Required

Stripe

Name

Required

Descriptive free-text name for the collector.

Data Source

Required

Select a pre-configured data source from the drop-down or click Create New to create a new data source.

Schema Name

Required

Enter a name for the schema where the collected data will be stored. This can be a pre-configured schema or a new schema which will be created the first time the collector is run.

Credential

Required

Select a pre-configured Stripe credential from the drop-down.

API Version

Optional

v2 — HTTP (latest) calls Stripe's REST API directly and returns the raw JSON for the current Stripe API version. v1 — Stripe.NET SDK (legacy) returns the typed objects of the SDK version bundled with DataBlend. Column names and nesting can differ between the two, so re-check the schema after switching. This field replaces the old Use Latest API toggle. Organization API keys (sk_org_…) always use v2.

Object Type

Required

The Stripe object to collect. The fields below the drop-down change with the object type.

Account IDs

Required for organization API keys, otherwise ignored

For sk_org_… credentials, select one or more Stripe accounts to collect from. The collector runs once per account. Click Add Parameter to supply a comma-delimited list from a parameter instead.

[Object] IDs (e.g. Invoice IDs, Customer IDs, Charge IDs)

Optional

When set, the collector fetches exactly these records and ignores every other filter on the page. Click Add Parameter to supply a comma-delimited list from a parameter.

Expand

Optional

Comma-separated list of Stripe expand[] paths. See Expand field below.

Created On

Optional

A date. Combined with Create On Option, restricts the collection to records created on one side of this date. Click Add Parameter to supply the date from a parameter. See Filtering by date with Created On.

Create On Option

Required when Created On is set

Greater Than, Greater Than Or Equal, Less Than, or Less Than Or Equal.

Query (labelled Search query on Charges)

Optional (required on Search Payment Intents)

A Stripe search query. When set, the collector calls Stripe's Search API instead of the List API and returns only matching records. See The Query field.

Which optional filters appear depends on the object type:

Object Type

IDs

Created On

Query

Expand

Customers

Customer IDs

Yes

Yes

Yes

Invoices

Invoice IDs

Yes

Yes

Yes

Charges

Charge IDs

Yes

Yes (Search query)

Yes

Prices

Price IDs

Do not use (see note)

Yes

Yes

Products

Product IDs

Do not use (see note)

Yes

Yes

Search Payment Intents

—

—

Yes, required

—

All other object types

varies

varies

No

varies

Prices and Products: Stripe's Search API does not accept created for these two objects. Leave Created On blank on Prices and Products and filter with Query only, for example active:"true".

Filtering by date with Created On

Created On plus Create On Option is the simplest date filter. It applies to the record's created timestamp and sets one bound:

    • Created On = 2026-01-01, Create On Option = Greater Than Or Equal → everything created on or after 1 Jan 2026 (UTC).
    • Created On = 2026-02-01, Create On Option = Less Than → everything created before 1 Feb 2026 (UTC).

To bound both ends of a window (a "between" filter), use the Query field described next. If both Created On and Query are filled in, DataBlend appends the Created On condition to your query with and, so the two work together.

When Created On is parameterised (Add Parameter), the parameter must resolve to a date string DataBlend can parse, such as a Date or Relative Date parameter formatted yyyy-MM-dd. It must not be a Unix timestamp.

The Query field

What it does

The Query field passes a search expression straight to Stripe's Search API (/v1/<object>/search). Stripe evaluates the expression on its side and returns only the matching records, so a well-targeted query is much faster than collecting everything and filtering in DataBlend afterwards. DataBlend pages through all matches automatically.

The syntax is Stripe's own query language, documented at https://docs.stripe.com/search. The essentials:

Syntax

Meaning

Example

field:value

Exact match (case-insensitive)

status:"paid"

field>value, field>=value, field<value, field<=value

Numeric comparison. Works on numeric fields and on timestamps.

created>=1767225600

field~value

Substring match on string fields (3+ characters)

email~"acme"

-field:value

Negation

-currency:"usd"

field:null

Field is empty / key is absent

-metadata["region"]:null

metadata["key"]:"value"

Match a metadata key

metadata["erp_id"]:"C-1042"

AND / and

Both clauses must match (the default when clauses are separated by a space)

status:"open" and total>10000

OR / or

Either clause may match

currency:"usd" or currency:"cad"

Rules Stripe enforces:

    • String values must be in double quotes. Numbers and timestamps may be unquoted.
    • Timestamps are Unix epoch seconds in UTC (for example 1767225600 = 2026-01-01 00:00:00 UTC). Stripe rejects created>=2026-01-01.
    • Up to 10 clauses per query.
    • A query may use AND or OR, but not both, and parentheses are not supported.
    • Only the fields Stripe lists for that object can be searched (see the next section). Any other field returns Field "x" is an unsupported search field for resource "y".
    • Search results can lag a minute or so behind writes, and Stripe rate-limits search to 20 requests per second per account. For a complete export of an object, leave Query blank and let the collector use the List API.

Fields you can search, by Object Type

Object Type

Searchable fields

Date range possible?

Customers

created, email, name, phone, metadata["key"]

Yes, on created

Invoices

created, currency, customer, status, subscription, number, receipt_number, total, last_finalization_error_code, last_finalization_error_type, metadata["key"]

Yes, on created

Charges

created, amount, currency, customer, status, disputed, refunded, billing_details.address.postal_code, payment_method_details.card.last4 / .brand / .exp_month / .exp_year / .fingerprint, metadata["key"]

Yes, on created

Search Payment Intents

created, amount, currency, customer, status, metadata["key"]

Yes, on created

Prices

active, currency, type, product, lookup_key, metadata["key"]

No

Products

active, name, description, url, shippable, metadata["key"]

No

created is the only timestamp Stripe lets you search on for these objects. Other date columns you see in the collected data, such as period_start, period_end, due_date, finalized_at or paid_at, cannot be used in the Query field. See Filtering on other date columns for the pattern to use instead.

Collecting a date window

To collect records created between two dates, put both bounds in the Query field joined with and:

created>=1767225600 and created<=1769903999

That example is 1 Jan 2026 00:00:00 UTC through 31 Jan 2026 23:59:59 UTC. Combine it with other clauses as needed:

status:"paid" and created>=1767225600 and created<=1769903999

Leave Created On blank when the range is already in the query.

Using parameters in the Query field

The Query field accepts DataBlend parameters. Reference a parameter as ; DataBlend substitutes the parameter's value before the collector runs. Because Stripe needs Unix seconds, set the parameter's Format to U (Unix Timestamp).

Example: collect Invoices created in the previous calendar month, driven by two parameters

    • Open the collector and add two parameters on the Parameters tab:
      • Name period_start, Value Type Custom Relative Date (Start Of, Month, offset −1), Format U.
      • Name period_end, Value Type Custom Relative Date (End Of, Month, offset −1), Format U.
    • Set Object Type to Invoices and leave Created On and Create On Option blank.
    • In Query, enter:
    • Save and run. In the run dialog the resolved values are shown, for example 1767225600 and 1769903999, and the log shows the collector using the Search API.

    Any Date or Relative Date parameter works the same way as long as its Format is U. Fixed dates work too: a Date parameter with Format U renders as Unix seconds.

      created>= and created<=

        The same parameters can be supplied by a Workflow step, so a monthly workflow can drive the collector without editing it.

        Things to watch:

          • The parameter name inside must match exactly (case-sensitive). A missing parameter fails the run with Parameter 'period_start' not found.
          • If a date parameter has no Format, its raw value (an ISO date) is substituted and Stripe replies We were unable to parse your search query. Set Format to U.
          • Use U for parameters referenced in Query, and a date format such as yyyy-MM-dd for parameters referenced in Created On. The two fields expect different shapes.

        Filtering on other date columns (period_start, period_end, due_date, …)

        Stripe will not search on these fields, so they cannot go in the Query field. The efficient pattern is:

          • Narrow at Stripe with a created window in the Query field that is guaranteed to contain the records you want. For subscription invoices, period_start/period_end normally sit within a few days of created, so a window padded by a month on either side is usually plenty and still avoids a full export.
          • Filter precisely in DataBlend with a Query on the collected schema. The collector stores every column as text, so cast before comparing:
        1. SELECT * 
          4.  FROM stripe.invoices
          5.  WHERE CAST(period_start AS BIGINT) >=
        2. FROM stripe.invoices 
          5.  WHERE CAST(period_start AS BIGINT) >=
        3. WHERE CAST(period_start AS BIGINT) >= 
          AND CAST(period_end   AS BIGINT) <=

        Use the same period_start / period_end parameters (Format U) on the DataBlend Query, so one set of parameters drives both steps. To display the epoch columns as dates, convert them in the query, for example TO_TIMESTAMP(CAST(period_start AS BIGINT)).

        If padding the created window is not acceptable for your data, leave Query blank so the collector lists every record, then apply the DataBlend Query filter as above.

        Troubleshooting

        Message in the collector log

        Cause

        Fix

        Field 'period_start' is an unsupported search field for resource 'invoices'

        The field is not searchable at Stripe.

        Filter on created in the query and on the other column in a DataBlend Query.

        We were unable to parse your search query

        Unquoted string value, or a date that is not Unix seconds (often a parameter without Format U).

        Quote strings; set date parameters to Format U.

        Queries cannot have a mix of AND and OR

        Both operators in one query.

        Split into two collectors or restructure the clauses.

        Parameter 'x' not found

        The name inside has no matching parameter.

        Add the parameter or fix the spelling.

        Field 'created' is an unsupported search field for resource 'prices'

        Created On set on Prices or Products.

        Clear Created On on these object types.

        Records changed in the last minute are missing

        Stripe search indexing lag.

        Re-run, or use the List API (blank Query) for read-after-write flows.

        Expand field

        Some object types include an Expand field, which maps directly to Stripe's expand[] request parameter and returns full nested objects instead of just their IDs.

          • Comma-separated list of expandable field paths, no brackets or quotes.
          • When the collector lists or searches (the normal case), prefix each path with data. because Stripe returns a list: data.customer,data.charge.
          • When the collector fetches specific records through the IDs field, drop the prefix: customer,charge.
          • Use the paths exactly as Stripe documents them for the object; an invalid path fails the run.
          • Leave blank if nested objects are not needed. Expanding large objects increases run time.

        For additional details consult the Stripe API reference.

         
        To learn more about Stripe API requirements, please visit Stripe API reference – curl.