Stripe Source

Stripe builds economic infrastructure for the internet, that enables businesses of every size to accept payments and manage their businesses online.

This is an Object Cloud Source which can export data from its third party tool and import it directly into your Segment warehouse.

This document was last updated on July 30, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

  1. From your workspace’s /sources page, click add source.
  2. Choose Stripe.
  3. Give the source a nickname and a schema name. The nickname will be used to designate the source in the Segment interface, and the schema name is the namespace you’ll be querying against in your warehouse. Both can be whatever you like, but we recommend sticking to something that reflects the source itself, like Stripe for nickname and stripe or stripe_prod for the schema name. NOTE: that you can add multiple instances if you have multiple Stripe accounts. That’s why we allow you to customize the source’s nickname and schema name!
  4. When you click connect, you’ll be dropped into Stripe’s OAuth flow. Once you sign in and grant permissions, you’ll be good to go!

Components

Sync

The Stripe source is built with a sync component, which means we’ll make requests to their API on your behalf on a 3 hour interval to pull the latest data into Segment. In the initial sync, we’ll grab all the Stripe objects (and their corresponding properties) according to the Collections Table below. The objects will be written into a separate schema, corresponding to the source instance’s schema name you designated upon creation (ie. stripe_prod.charges).

Our sync component uses an upsert API, so the data in your warehouse loaded via sync will reflect the latest state of the corresponding resource in Stripe. For example, if subscription_status goes from active to inactive between syncs, on its next sync that tickets status will be inactive.

The source syncs and warehouse syncs are independent processes. Source runs pull your data into the Segment Hub, and warehouse runs flush that data to your warehouse. Sources will sync with Segment every 3 hours. Depending on your Warehouses plan, we will push the Source data to your warehouse on the interval associated with your billing plan.

Collections

Collections are the groupings of resources we pull from your source. In your warehouse, each collection gets its own table.

CollectionTypeDescription
accountsobjectThis is an object representing your Stripe account. You can retrieve it to see properties on the account like its current e-mail address or if the account is enabled yet to make live charges. For more info, see Stripe’s API docs
application_fee_refundsobjectApplication Fee Refund objects allow you to refund an application fee that has previously been created but not yet refunded. Funds will be refunded to the Stripe account that the fee was originally collected from. For more info, see Stripe’s API docs
application_feesobjectWhen you collect a transaction fee on top of a charge made for your user (using Stripe Connect), an application fee object is created in your account. You can list, retrieve, and refund application fees. For more info, see Stripe’s API docs
balance_transactionsobjectBalance transactions lists the transaction balance history. For more info, see Stripe’s API docs
balance_transaction_fee_detailsobjectBalance transaction fee details include a breakdown of fees (in cents) paid for each transaction. For more info, see Stripe’s API docs
bank_accountsobjectBank accounts are used at Stripe in two ways: as a payment method on Customer objects and as a transfer destination on Account objects for managed accounts. The accepted and required parameters are different for each context. For more info, see Stripe’s API docs
bitcoin_receiversobjectA Bitcoin receiver wraps a Bitcoin address so that a customer can push a payment to you. This guide describes how to use receivers to create Bitcoin payments. For more info, see Stripe’s API docs
cardsobjectYou can store multiple cards on a customer in order to charge the customer later. You can also store multiple debit cards on a recipient or a managed account in order to transfer to those cards later. For more info, see Stripe’s API docs
chargesobjectTo charge a credit or a debit card, you create a charge object. You can retrieve and refund individual charges as well as list all charges. For more info, see Stripe’s API docs
couponsobjectA coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons only apply to invoices; they do not apply to one-off charges. For more info, see Stripe’s API docs
customersobjectCustomer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. For more info, see Stripe’s API docs
discountsobjectA discount represents the actual application of a coupon to a particular customer. It contains information about when the discount began and when it will end. For more info, see Stripe’s API docs
disputesobjectA dispute occurs when a customer questions your charge with their bank or credit card company. When a customer disputes your charge, you’re given the opportunity to respond to the dispute with evidence that shows the charge is legitimate. You can find more information about the dispute process in our disputes FAQ. For more info, see Stripe’s API docs
file_uploadsobjectThere are various times when you’ll want to upload files to Stripe (for example, when uploading dispute evidence). This can be done by creating a file upload object. When you upload a file, the API responds with a file token and other information about the file. The token can then be used to retrieve a file object. For more info, see Stripe’s API docs
invoice_itemsobjectSometimes you want to add a charge or credit to a customer but only actually charge the customer’s card at the end of a regular billing cycle. This is useful for combining several charges to minimize per-transaction fees or having Stripe tabulate your usage-based billing totals. For more info, see Stripe’s API docs
invoice_linesobjectWhen retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items For more info, see Stripe’s API docs
invoicesobjectInvoices are statements of what a customer owes for a particular billing period, including subscriptions, invoice items, and any automatic proration adjustments if necessary. For more info, see Stripe’s API docs
plansobjectA subscription plan contains the pricing information for different products and feature levels on your site. For more info, see Stripe’s API docs
refundsobjectRefund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded. For more info, see Stripe’s API docs
subscriptionsobjectSubscriptions allow you to charge a customer’s card on a recurring basis. A subscription ties a customer to a particular plan you’ve created. For more info, see Stripe’s API docs
transfer_reversalsobjectA previously created transfer can be reversed if it has not yet been paid out. Funds will be refunded to your available balance, and the fees you were originally charged on the transfer will be refunded. You may not reverse automatic Stripe transfers. For more info, see Stripe’s API docs
transfersobjectWhen Stripe sends you money or you initiate a transfer to a bank account, debit card, or connected Stripe account, a transfer object will be created. You can retrieve individual transfers as well as list all transfers. For more info, see Stripe’s API docs

Collection Properties

Below are tables outlining the properties included in the collections listed above.

accounts

Property NameDescription
emailThe primary user’s email address
statement_descriptorThe default text that appears on credit card statements when a charge is made directly on the account
display_nameThe display name for this account
timezoneThe timezone used in the Stripe Dashboard for this account
details_submittedWhether account details have been submitted
charges_enabledWhether the account can create live charges
transfers_enabledWhether transfers are enabled
default_currencyThe currency this account has chosen to use as the default
countryThe country of the account
business_nameThe publicly visible name of the business
business_urlThe publicly visible website of the business
support_phoneA publicly shareable support phone number for the business
business_logoThe publicly visible logo of the business
support_urlA publicly shareable website
support_emailA publicly shareable support email address for the business
debit_negative_balancesA Boolean indicating if Stripe should try to reclaim negative balances from an attached bank account

application_fee_refunds

Property NameDescription
amountAmount, in cents
currencyThree-letter ISO currency code, in lowercase
fee_idID of the application fee that was refunded

application_fees

Property NameDescription
account_idID of the Stripe account this fee was taken from
amountAmount earned, in pence
amount_refundedAmount in pence refunded
application_idID of the Connect application that earned the fee
balance_transaction_idBalance transaction that describes the impact of this collected application fee on your account balance
charge_idID of the charge that the application fee was taken from
currencyThree-letter ISO currency code, in lowercase
originating_transactionID of the corresponding charge on the platform account
refundedWhether the fee has been fully refunded

balance_transactions

Property NameDescription
amountGross amount of the transaction, in cents
currencyThree-letter ISO currency code, in lowercase
descriptionAn arbitrary string attached to the object
feeFees (in cents) paid for this transaction
netNet amount of the transaction, in cents
statusIf the transaction’s net funds are available in the Stripe balance yet
typeTransaction type
sourceThe Stripe object to which this transaction is related

balance_transaction_fee_details

Property NameDescription
balance_transaction_idUnique identifier for the object
amountGross amount of the transaction, in pence
currencyThree-letter ISO currency code, in lowercase
descriptionAn arbitrary string attached to the object
typeTransaction type

bank_accounts

Property NameDescription
bank_nameName of the bank associated with the routing number
countryTwo-letter ISO code representing the country the bank account is located in
currencyThree-letter ISO code for the currency paid out to the bank account
default_for_currencyCurrency default
statusStatus of account

cards

Property NameDescription
address_cityCity/District/Suburb/Town/Village
address_countryBilling address country, if provided when creating card
address_line1Address line 1 (Street address/PO Box/Company name)
address_line1_checkCheck for above
address_line2Address line 2 (Apartment/Suite/Unit/Building)
address_stateState/County/Province/Region
address_zipZIP or postal code
address_zip_checkCheck for above
brandCard brand
countryTwo-letter ISO code representing the country of the card
cvc_checkIf a CVC was provided, results of the check
exp_monthTwo-digit number representing the card’s expiration month
exp_yearFour-digit number representing the card’s expiration year
fundingCard funding type
nameCardholder name
last4The last four digits of the card
dynamic_last4The last four digits of the device account number
fingerprintUniquely identifies this particular card number.
tokenization_methodIf the card number is tokenized, this is the method that was used

charges

Property NameDescription
amountA positive integer in the smallest currency unit representing how much to charge
amount_refundedAmount in cents refunded
application_feeThe application fee (if any) for the charge
balance_transaction_idID of the balance transaction that describes the impact of this charge on your account balance
capturedIf the charge was created without capturing
currencyThree-letter ISO currency code, in lowercase
customer_idID of the customer this charge is for if one exists
descriptionAn arbitrary string attached to the object
destinationThe account (if any) the charge was made on behalf of, with an automatic transfer
failure_codeError code explaining reason for charge failure if available
failure_messageMessage to user further explaining reason for charge failure if available
invoice_idID of the invoice this charge is for if one exists
paidtrue if the charge succeeded, or was successfully authorized for later capture
receipt_emailThis is the email address that the receipt for this charge was sent to
receipt_numberThis is the transaction number that appears on email receipts sent for this charge
refundedWhether the charge has been fully refunded
statement_descriptorExtra information about a charge. This will appear on your customer’s credit card statement
statusThe status of the payment

coupons

Property NameDescription
percent_offPercent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon
amount_offAmount (in the currency specified) that will be taken off the subtotal of any invoices for this customer
currencyThe three-letter ISO code for the currency of the amount to take off
durationDescribes how long a customer who applies this coupon will get the discount
max_redemptionsMaximum number of times this coupon can be redeemed, in total, before it is no longer valid
times_redeemedNumber of times this coupon has been applied to a customer
validTaking account of the above properties, whether this coupon can still be applied to a customer
duration_in_monthsIf duration is repeating, the number of months the coupon applies

customers

Property NameDescription
account_balanceCurrent balance, if any, being stored on the customer’s account
currencyThree-letter ISO code for the currency the customer can be charged in for recurring billing purpose
delinquentWhen the customer’s latest invoice is billed by charging automatically, delinquent is true if the invoice’s latest charge is failed
descriptionAn arbitrary string attached to the object
emailThe customer’s email address

discounts

Property NameDescription
customer_idID of the customer
subscriptionThe subscription that this coupon is applied to, if it is applied to a particular subscription

disputes

Property NameDescription
charge_idID of the charge that was disputed
amountDisputed amount. Usually the amount of the charge
statusCurrent status of dispute
currencyThree-letter ISO currency code, in lowercase
reasonReason given by cardholder for dispute
is_charge_refundableIf true, it is still possible to refund the disputed payment

invoice_items

Property NameDescription
amountAmount (in the currency specified) of the invoice item
currencyThree-letter ISO currency code, in lowercase
customer_idThe ID of the customer who will be billed when this invoice item is billed
descriptionAn arbitrary string attached to the object
discountableIf true, discounts will apply to this invoice item. Always false for prorations
invoice_idThe ID of the invoice this invoice item belongs to
prorationWhether the invoice item was created automatically as a proration adjustment when the customer switched plans
quantityQuantity of units for the invoice item. If the invoice item is a proration, the quantity of the subscription that the proration was computed for
subscription_idThe subscription that this invoice item has been created for, if any

invoices

Property NameDescription
amount_dueFinal amount due at this time for this invoice
application_feeThe fee in cents that will be applied to the invoice and transferred to the application owner’s Stripe account when the invoice is paid
attempt_countNumber of payment attempts made for this invoice, from the perspective of the payment retry schedule
attemptedWhether an attempt has been made to pay the invoice
charge_idID of the latest charge generated for this invoice, if any
currencyThree-letter ISO currency code, in lowercase
customer_idID of the customer
descriptionAn arbitrary string attached to the object
ending_balanceEnding customer balance after the invoice is frozen
forgivenWhether the invoice has been forgiven. Forgiving an invoice instructs us to update the subscription status as if the invoice were successfully paid
paidWhether payment was successfully collected for this invoice
receipt_numberThis is the transaction number that appears on email receipts sent for this invoice
starting_balanceStarting customer balance before the invoice is frozen
statement_descriptorExtra information about an invoice for the customer’s credit card statement
subscription_idThe subscription that this invoice was prepared for, if any
subtotalTotal of all subscriptions, invoice items, and prorations on the invoice before any discount is applied
taxThe amount of tax included in the total, calculated from tax_percent and the subtotal. If no tax_percent is defined, this value will be null
tax_percentThis percentage of the subtotal has been added to the total amount of the invoice, including invoice line items and discounts
totalTotal after discount

plans

Property NameDescription
intervalOne of day, week, month or year. The frequency with which a subscription should be billed
nameUnique identifier
amountThe amount in cents to be charged on the interval specified
currencyThree-letter ISO currency code, in lowercase
interval_countThe number of intervals (specified in the interval property) between subscription billings
trial_period_daysDefault number of trial days when subscribing a customer to this plan using trial_from_plan=true

refunds

Property NameDescription
amountAmount, in cents
currencyThree-letter ISO currency code, in lowercase
balance_transaction_idBalance transaction that describes the impact on your account balance
charge_idID of the charge that was refunded
receipt_numberThis is the transaction number that appears on email receipts sent for this refund
reasonReason for the refund

subscriptions

Property NameDescription
application_fee_percentThis represents the percentage of the subscription invoice subtotal that will be transferred to the application owner’s Stripe account
cancel_at_period_endIf the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true
customer_idID of the customer who owns the subscription
quantityThe quantity of the plan to which the customer should be subscribed
statusPossible values are trialing, active, past_due, canceled, or unpaid
tax_percentIf provided, each invoice created by this subscription will apply the tax rate, increasing the amount billed to the customer

transfer_reversals

Property NameDescription
amountAmount, in cents
currencyThree-letter ISO currency code, in lowercase
balance_transaction_idBalance transaction that describes the impact on your account balance
transfer_idID of the transfer that was reversed

transfers

Property NameDescription
amountAmount in cents to be transferred
amount_reversedAmount in cents reversed (can be less than the amount attribute on the transfer if a partial reversal was issued)
application_feeapplication_fee
balance_transaction_idBalance transaction that describes the impact of this transfer on your account balance
currencyThree-letter ISO currency code, in lowercase
descriptionAn arbitrary string attached to the object
destination_idID of the Stripe account the transfer was sent to
destination_paymentIf the destination is a Stripe account, this will be the ID of the payment that the destination account received for the transfer
reversedWhether the transfer has been fully reversed. If the transfer is only partially reversed, this attribute will still be false
source_transactionID of the charge or payment that was used to fund the transfer. If null, the transfer was funded from the available balance

V2 Changelog

In September 2017, Segment will upgrade all Stripe sources to sync incrementally, using the List Events endpoint to sync changes to Stripe objects. There are a few benefits to this approach…

  • Faster sync times: for larger accounts, we’ve seen performance improve by 10x
  • Additional Object Properties: Events provide additional metadata about objects, like their creation time and deletion time
  • Reduced load on the Stripe API: Our new Stripe source helps cut down load on our partner’s API, and reduces unnecessary data transfer

How It Works

  1. The Stripe Source will run a full sync of all objects, using the List All endpoints for Charges, Customers, Refunds, etc.
  2. After the first sync completes, the source will automatically switch into incremental mode.
    1. When the source is scheduled to run, it will query for all events since the last sync completed. An event can be an object (e.g. a customer) being created, updated, or deleted
    2. The Segment source will materialize the event stream into the latest state of the object. So the charges table will always reflect the latest charge.updated event.

Changelog

CollectionChanges
accountsNo Change - accounts cannot be synced incrementally
application_fee_refundsDeprecated properties
  • balance_transaction_id
application_feesDeprecated properties
  • refund_ids
balance_transaction_fee_detailsNo Change
balance_transactionsDeprecated properties
  • sourced_transfers
bank_accountsDeprecated properties
  • currency
New properties
  • is_deleted
cardsNew properties
  • customer_id
  • is_deleted
chargesDeprecated properties
  • receipt_number
  • dispute_id
  • tokenization_method
couponsNo Change
customersDeprecated properties
  • source_ids
  • subscription_ids
  • discount_id
New properties
  • is_deleted
discountsNo Change
disputesNo Change
invoice_itemsNo Change
invoice_linesDeprecated properties
  • metadata_*
invoicesDeprecated properties
  • line_ids
  • attempt_count
  • next_payment_attempt
order_returnsDeprecated properties
  • refund_id
order_shipping_methodsNo Change
ordersDeprecated properties
  • statustransitions*
plansNo Change
productsNo Change
refundsDeprecated properties
  • refunds starting with py_
skusNo Change
subscriptionsNo Change
subscription_itemsNEWCOLLECTION
transfer_reversalsNo Change
transfersDeprecated Properties
  • reversal_ids

Adding Destinations

Currently, Warehouses are the only supported destination for object-cloud sources.


If you have any questions, or see anywhere we can improve our documentation, please let us know!